From 1ceadec8abb30fe27e9d7f9560cd8623184bc019 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 27 Sep 2023 22:48:36 +0000 Subject: [PATCH 01/29] build(deps): bump get-func-name from 2.0.0 to 2.0.2 Bumps [get-func-name](https://github.com/chaijs/get-func-name) from 2.0.0 to 2.0.2. - [Release notes](https://github.com/chaijs/get-func-name/releases) - [Commits](https://github.com/chaijs/get-func-name/commits/v2.0.2) --- updated-dependencies: - dependency-name: get-func-name dependency-type: indirect ... Signed-off-by: dependabot[bot] --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index 252aeb5d..2745c35a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5139,9 +5139,9 @@ __metadata: linkType: hard "get-func-name@npm:^2.0.0": - version: 2.0.0 - resolution: "get-func-name@npm:2.0.0" - checksum: 8d82e69f3e7fab9e27c547945dfe5cc0c57fc0adf08ce135dddb01081d75684a03e7a0487466f478872b341d52ac763ae49e660d01ab83741f74932085f693c3 + version: 2.0.2 + resolution: "get-func-name@npm:2.0.2" + checksum: 3f62f4c23647de9d46e6f76d2b3eafe58933a9b3830c60669e4180d6c601ce1b4aa310ba8366143f55e52b139f992087a9f0647274e8745621fa2af7e0acf13b languageName: node linkType: hard From 1791a53e99857a0a1d50db6abf5b66d24cb89cb6 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 6 Oct 2023 12:10:58 -0400 Subject: [PATCH 02/29] Fix lint complaints --- .eslintrc.js | 8 +------- research-app/src/App.vue | 1 - 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 4dea0abf..3bda9bbf 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -10,13 +10,7 @@ module.exports = { 'plugin:@typescript-eslint/recommended' ], rules: { - "no-unused-vars": [ - "warn", { - "args": "all", - "argsIgnorePattern": "^_", - "varsIgnorePattern": "^_" - } - ], + "no-unused-vars": "off", // this rule is superseded by typescript-eslint's version "@typescript-eslint/no-unused-vars": [ "warn", { "args": "all", diff --git a/research-app/src/App.vue b/research-app/src/App.vue index 71c79525..059884d1 100644 --- a/research-app/src/App.vue +++ b/research-app/src/App.vue @@ -398,7 +398,6 @@ import { extractSpreadSheetLayerSettings, extractImageSetLayerSettings, isCircleAnnotationSetting, - isEngineSetting, isImageSetLayerSetting, isPolyAnnotationSetting, isPolyLineAnnotationSetting, From de1218a3cc99bf73ef83b6f99613b678a113be55 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 6 Oct 2023 12:21:40 -0400 Subject: [PATCH 03/29] engine-types: tidy up doc warnings, provide a little bit more of an index --- docs/engine/engine-types-index.md | 8 +++++++- engine-types/src/index.ts | 7 ++++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/engine/engine-types-index.md b/docs/engine/engine-types-index.md index 9961a591..c9f695c7 100644 --- a/docs/engine/engine-types-index.md +++ b/docs/engine/engine-types-index.md @@ -1 +1,7 @@ -Basic types relating to the engine. +Basic data types relating to the WorldWide Telescope engine. The types here are +the ones that were historically easy to define independently of the actual +engine implementation, so that you could reference them without pulling in the +large body of engine code. + +Check out the [module page](./modules.html) for an index of the types defined in +this package. diff --git a/engine-types/src/index.ts b/engine-types/src/index.ts index 9bb04cf1..7f868914 100644 --- a/engine-types/src/index.ts +++ b/engine-types/src/index.ts @@ -653,7 +653,7 @@ export function isBaseSpreadSheetLayerSetting(obj: [string, any]): obj is BaseSp /** Settings specifically for instances of the VoTableLayer type. * - * These are nearly, but not exactly, identical to [[BaseSpreadSheetLayerSetting]]. + * These are nearly, but not exactly, identical to {@link BaseSpreadSheetLayerSetting}. * */ export type BaseVoTableLayerSetting = ["altColumn", number] | @@ -762,9 +762,10 @@ export function isBaseVoTableLayerSetting(obj: [string, any]): obj is BaseVoTabl } } -// TypeScript magic to allow fallible reverse mapping of string-valued enums. +/** This type provides some TypeScript magic to allow fallible reverse mapping + * of string-valued enums. */ // https://stackoverflow.com/q/57922745/3760486 -type StringEnum = { [key: string]: string }; +export type StringEnum = { [key: string]: string }; function keysOf>(o: K): (keyof K)[]; function keysOf(o: any) { return Object.keys(o); } // eslint-disable-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/no-explicit-any From b2bc86e0f514ff78296a9464e7629471d1a05f35 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 6 Oct 2023 12:37:46 -0400 Subject: [PATCH 04/29] embed-common: tidy up doc warnings, provide a little bit more of an index In order to make TypeDoc happy, it looks like I have to manually deal with types from other packages that appear in the API. In this case, that's BaseEngineSetting. --- docs/engine/embed-common-index.md | 9 +++++++++ embed-common/src/index.ts | 7 +++++++ embed-common/tsconfig.json | 3 ++- 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/engine/embed-common-index.md b/docs/engine/embed-common-index.md index e5346d81..38b5fa3f 100644 --- a/docs/engine/embed-common-index.md +++ b/docs/engine/embed-common-index.md @@ -1 +1,10 @@ Utilities relating to the embedding functionality. + +Check out the [module page](./modules.html) for an index of the types defined in +this package. + +The core type is [EmbedSettings](./classes/EmbedSettings.html), which expresses +a set of settings that can be used to configure the WWT embed app. The [embed +creator](https://embed.worldwidetelescope.org/) uses this type to serialize +settings, and the [embed app](https://www.npmjs.com/package/@wwtelescope/embed) +uses it to deserialize them and set up the engine. diff --git a/embed-common/src/index.ts b/embed-common/src/index.ts index 6569eb30..6327ce53 100644 --- a/embed-common/src/index.ts +++ b/embed-common/src/index.ts @@ -108,6 +108,13 @@ export class EmbedSettings { return s; } + /** Return a set of + * [`BaseEngineSetting`](../../engine-types/types/BaseEngineSetting.html) + * values implied by this configuration. (The `BaseEngineSetting` type is + * defined in the `@wwtelescope/engine-types` module.) + * + * @returns A list of setting values. + */ asSettings(): BaseEngineSetting[] { const s: BaseEngineSetting[] = []; s.push(["showCrosshairs", this.showCrosshairs]); diff --git a/embed-common/tsconfig.json b/embed-common/tsconfig.json index 0cc4bb64..1a6d4ec0 100644 --- a/embed-common/tsconfig.json +++ b/embed-common/tsconfig.json @@ -29,6 +29,7 @@ "excludePrivate": true, "validation": { "invalidLink": true - } + }, + "intentionallyNotExported": ["BaseEngineSetting"] } } \ No newline at end of file From fb81c141f5d7e0a69b258586bc8756ba645fb3ec Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 6 Oct 2023 12:59:59 -0400 Subject: [PATCH 05/29] engine: tidy up doc warnings, provide a little bit more of an index --- docs/engine/engine-index.md | 14 ++- engine/src/index.d.ts | 240 ++++++++++++++++++------------------ engine/tsconfig.json | 31 ++++- 3 files changed, 160 insertions(+), 125 deletions(-) diff --git a/docs/engine/engine-index.md b/docs/engine/engine-index.md index 8ee50f46..e51cb0fe 100644 --- a/docs/engine/engine-index.md +++ b/docs/engine/engine-index.md @@ -1,5 +1,7 @@ -This package is the core WWT WebGL engine, transpiled from C# and decorated with -TypeScript annotations. +This package contains the core WWT WebGL engine. It is written in plain +JavaScript and decorated with TypeScript annotations, which are then used to +generate this documentation. The annotations cover very large fractions of its +functionality, but not everything. To work with the WWT engine in your own code, we recommended starting with a higher-level module like [@wwtelescope/engine-helpers](../engine-helpers/) or @@ -8,4 +10,10 @@ However, regardless of which broad framework you use, if you interact with the engine in detail you will likely end up using and referring to the definitions in this module. -[Vue]: https://vuejs.org/ \ No newline at end of file +[Vue]: https://vuejs.org/ + +Your primary interfaces to control the engine are the +[WWTControl](./classes/WWTControl-1.html) and the +[ScriptInterface](./classes/ScriptInterface.html) types, both of which exist as +global singletons. To initialize these objects, use +[WWTControlBuilder](./classes/WWTControlBuilder.html). diff --git a/engine/src/index.d.ts b/engine/src/index.d.ts index a2002482..f48c8abe 100644 --- a/engine/src/index.d.ts +++ b/engine/src/index.d.ts @@ -156,7 +156,7 @@ export interface EngineSettingsInterface extends EngineSettingsInterfaceRO { set_solarSystemMinorOrbits(v: boolean): boolean; } -/** Interface for querying [[ImageSetLayer]] settings. +/** Interface for querying {@link ImageSetLayer} settings. * * The `RO` is short for "read-only". * */ @@ -165,7 +165,7 @@ export interface ImageSetLayerSettingsInterfaceRO extends LayerSettingsInterface get_overrideDefaultLayer(): boolean; } -/** Interface for controlling [[ImageSetLayer]] settings. */ +/** Interface for controlling {@link ImageSetLayer} settings. */ export interface ImageSetLayerSettingsInterface extends LayerSettingsInterface, ImageSetLayerSettingsInterfaceRO { set_colorMapperName(v: string): string; set_overrideDefaultLayer(v: boolean): boolean; @@ -230,7 +230,7 @@ export interface PolyLineAnnotationSettingsInterface extends AnnotationSettingsI set_lineWidth(v: number): number; } -/** Interface for querying [[SpreadSheetLayer]] settings. +/** Interface for querying {@link SpreadSheetLayer} settings. * * The `RO` is short for "read-only". * */ @@ -284,7 +284,7 @@ export interface SpreadSheetLayerSettingsInterfaceRO extends LayerSettingsInterf get_zAxisReverse(): boolean; } -/** Interface for controlling [[SpreadSheetLayer]] settings. */ +/** Interface for controlling {@link SpreadSheetLayer} settings. */ export interface SpreadSheetLayerSettingsInterface extends LayerSettingsInterface, SpreadSheetLayerSettingsInterfaceRO { set_altColumn(v: number): number; set_altType(v: AltTypes): AltTypes; @@ -335,7 +335,7 @@ export interface SpreadSheetLayerSettingsInterface extends LayerSettingsInterfac set_zAxisReverse(v: boolean): boolean; } -/** Interface for querying [[VoTableLayer]] settings. +/** Interface for querying {@link VoTableLayer} settings. * * The `RO` is short for "read-only". * */ @@ -381,7 +381,7 @@ export interface VoTableLayerSettingsInterfaceRO extends LayerSettingsInterfaceR get_zAxisReverse(): boolean; } -/** Interface for controlling [[VoTableLayer]] settings. */ +/** Interface for controlling {@link VoTableLayer} settings. */ export interface VoTableLayerSettingsInterface extends LayerSettingsInterface, VoTableLayerSettingsInterfaceRO { set_altColumn(v: number): number; set_altType(v: AltTypes): AltTypes; @@ -500,10 +500,10 @@ export class Circle extends Annotation implements CircleAnnotationSettingsInterf get_fill(): boolean; set_fill(v: boolean): boolean; get_fillColor(): string; - /** The color is parsed using [[Color.fromName]]. */ + /** The color is parsed using {@link Color.fromName}. */ set_fillColor(v: string): string; get_lineColor(): string; - /** The color is parsed using [[Color.load]]. */ + /** The color is parsed using {@link Color.load}. */ set_lineColor(v: string): string; /** This parameter currently DOES NOTHING because the WebGL renderer doesn't yet support parametrizable line widths. */ get_lineWidth(): number; @@ -599,7 +599,7 @@ export namespace Color { /** Create a color from a hex string `AARRGGBB`. */ export function fromSimpleHex(hex: string): Color; - /** This function is the same as [[Color.fromName]]. */ + /** This function is the same as {@link Color.fromName}. */ export function load(name: string): Color; } @@ -774,7 +774,7 @@ export class FolderUp implements Thumbnail { /** An simple Version 4 GUID. * * Note that in WWT, GUID contents are not validated in any way upon creation. - * The stringification of a [[Guid]] may therefore not follow the UUID4 standard + * The stringification of a {@link Guid} may therefore not follow the UUID4 standard * form. */ export class Guid { @@ -998,7 +998,7 @@ export interface ImagesetLoadedCallback { /** Data returned when querying for dynamic catalog data within the current * view. * - * See [[RenderContext.getCatalogHipsDataInView]]. + * See {@link RenderContext.getCatalogHipsDataInView}. * */ export interface InViewReturnMessage { /** The table data, as tab-separated values with Windows (\r\n) newlines. */ @@ -1064,23 +1064,23 @@ export namespace LayerManager { /** Get the hierarchy of layers registered with the engine. * - * This function returns a dictionary of [[LayerMap]] instances that define + * This function returns a dictionary of {@link LayerMap} instances that define * the engine’s rendering hierarchy. This top-level dictionary contains only * the root reference frames used by the engine — typically, it has only two * entries, named `"Sun"` and `"Sky"`. Below the `"Sun"` map (in its - * [[LayerMap.childMaps]] field) are found maps for the planets, and below + * {@link LayerMap.childMaps} field) are found maps for the planets, and below * those are maps for their moons. * - * See also [[get_allMaps]], which returns the same collection of layer maps + * See also {@link get_allMaps}, which returns the same collection of layer maps * but in a flattened hierarchy. */ export function get_layerMaps(): { [name: string]: LayerMap } /** Get the flattened hierarchy of layers registered with the engine. * - * This function returns a dictionary of [[LayerMap]] instances that define + * This function returns a dictionary of {@link LayerMap} instances that define * the engine’s rendering hierarchy. The dictionary contains an entry for - * every [[LayerMap]] registered with the engine. This is unlike the + * every {@link LayerMap} registered with the engine. This is unlike the * `get_layerMaps()` interface, which only returns the “root” layer maps. * Because there is a layer map for every solar system planet and every known * moon thereof, this dictionary is quite large. @@ -1092,7 +1092,7 @@ export namespace LayerManager { /** Get the collection of all layers registered with the engine. * * The layer "list" is really an unordered dictionary of all registered - * layers, keyed by each layer's stringified GUID. Given a [[Layer]] object, + * layers, keyed by each layer's stringified GUID. Given a {@link Layer} object, * you can get its key with `layer.id.toString()`. This list includes layers * that have been registered for all engine rendering modes, while only one * rendering mode is currently active at a time. So there are inevitably @@ -1107,16 +1107,16 @@ export namespace LayerManager { export function createSpreadsheetLayer(frame: string, name: string, data: string): SpreadSheetLayer; export function deleteLayerByID(id: Guid, removeFromParent: boolean, updateTree: boolean): void; - /** Add a new [[VoTableLayer]] to the manager with a default plot type. + /** Add a new {@link VoTableLayer} to the manager with a default plot type. * - * This is the same as [[addVoTableLayerWithPlotType]] with the plot type + * This is the same as {@link addVoTableLayerWithPlotType} with the plot type * defaulted to `PlotTypes.Circle`. * */ export function addVoTableLayer(table: VoTable, title: string): VoTableLayer; - /** Add a new [[VoTableLayer]] to the manager. + /** Add a new {@link VoTableLayer} to the manager. * - * @param table The [[VoTable]] that will underlie the new layer. + * @param table The {@link VoTable} that will underlie the new layer. * @param title The name that will be given to the new layer. * @param plotType The point plotting type that the new layer will use. * @returns The newly-created layer. @@ -1129,15 +1129,15 @@ export namespace LayerManager { } /** An alias for the type implicitly defined by the static - * [[LayerManager]] namespace. */ + * {@link LayerManager} namespace. */ export type LayerManagerObject = typeof LayerManager; /** A collection of layers in a hierarchical tree. * - * Each map includes a collection of zero or more [[Layer]]s rooted in its - * reference frame (the [[layers]] list) as well as a collection of zero or more - * child [[LayerMap]]s, which have reference frames that are defined relative to - * this layer's reference frame (the [[childMaps]] dictionary). + * Each map includes a collection of zero or more {@link Layer}s rooted in its + * reference frame (the {@link layers} list) as well as a collection of zero or more + * child {@link LayerMap}s, which have reference frames that are defined relative to + * this layer's reference frame (the {@link childMaps} dictionary). **/ export class LayerMap { childMaps: { [childName: string]: LayerMap }; @@ -1227,10 +1227,10 @@ export class Poly extends Annotation implements PolyAnnotationSettingsInterface get_fill(): boolean; set_fill(v: boolean): boolean; get_fillColor(): string; - /** The color is parsed using [[Color.fromName]]. */ + /** The color is parsed using {@link Color.fromName}. */ set_fillColor(v: string): string; get_lineColor(): string; - /** The color is parsed using [[Color.load]]. */ + /** The color is parsed using {@link Color.load}. */ set_lineColor(v: string): string; /** This parameter currently DOES NOTHING because the WebGL renderer doesn't yet support parametrizable line widths. */ get_lineWidth(): number; @@ -1253,7 +1253,7 @@ export type PolyAnnotationSetting = /** An annotation composed of a sequence of lines. */ export class PolyLine extends Annotation implements PolyLineAnnotationSettingsInterface { get_lineColor(): string; - /** The color is parsed using [[Color.load]]. */ + /** The color is parsed using {@link Color.load}. */ set_lineColor(v: string): string; /** This parameter currently DOES NOTHING because the WebGL renderer doesn't yet support parametrizable line widths. */ get_lineWidth(): number; @@ -1283,20 +1283,20 @@ export interface ReadyEventCallback { * * ### The Camera * - * - [[viewCamera]] - * - [[targetCamera]] + * - {@link viewCamera} + * - {@link targetCamera} * * ### Core Datasets * - * - [[get_backgroundImageset]], [[set_backgroundImageset]] - * - [[get_foregroundImageset]], [[set_foregroundImageset]] - * - [[get_catalogHipsImagesets]] - * - [[addCatalogHips]], [[removeCatalogHips]] - * - [[getCatalogHipsDataInView]] + * - {@link get_backgroundImageset}, {@link set_backgroundImageset} + * - {@link get_foregroundImageset}, {@link set_foregroundImageset} + * - {@link get_catalogHipsImagesets} + * - {@link addCatalogHips}, {@link removeCatalogHips} + * - {@link getCatalogHipsDataInView} * * ### The Viewport * - * - [[width]], [[height]] + * - {@link width}, {@link height} */ export class RenderContext { height: number; @@ -1319,7 +1319,7 @@ export class RenderContext { /** Get a list of all active "catalog HiPS" imagesets. * - * These are the items that have been added with the [[addCatalogHips]] API. + * These are the items that have been added with the {@link addCatalogHips} API. * * @returns The list of active catalog HiPS imagesets * */ @@ -1347,9 +1347,9 @@ export class RenderContext { /** Add a new "catalog HiPS" imageset to the view. * - * Each catalog HiPS imageset is associated with a [[SpreadSheetLayer]] that + * Each catalog HiPS imageset is associated with a {@link SpreadSheetLayer} that * is updated with dynamically-loaded data as the WWT camera moves around. - * This API adds this layer to the [[LayerManager]] and invokes the *onLoad* + * This API adds this layer to the {@link LayerManager} and invokes the *onLoad* * callback when the imageset's initial loading has completed. * * The caller must ensure that the *imageset* argument actually does @@ -1362,7 +1362,7 @@ export class RenderContext { /** Fetch the subset of catalog HiPS data contained within the current view. * - * The imageset should have been loaded with the [[addCatalogHips]] call. The + * The imageset should have been loaded with the {@link addCatalogHips} call. The * *limit* parameter should almost always be true, since if false the * data-fetch operation can potentially attempt to download and return * gigabytes of data. @@ -1375,7 +1375,7 @@ export class RenderContext { /** Remove a "catalog HiPS" imageset from the view. * - * The argument must be an imageset previously passed to [[addCatalogHips]]. + * The argument must be an imageset previously passed to {@link addCatalogHips}. * * @param imageset The imageset to remove. * */ @@ -1438,8 +1438,8 @@ export class ScriptInterface { /** Deregister a "ready" callback. */ remove_ready(callback: ReadyEventCallback): void; - /** Register a callback to be called when [[WWTControl.loadTour]] or - * [[WWTControl.playTour]] have finished loading a tour. + /** Register a callback to be called when {@link WWTControl.loadTour} or + * {@link WWTControl.playTour} have finished loading a tour. */ add_tourReady(callback: ScriptInterfaceCallback): void; @@ -1452,14 +1452,14 @@ export class ScriptInterface { * an XML document in the [WTML collection][wtml] format. Any `ImageSet` * entries in the collection, or `Place` entries containing image sets, will * be added to the WWT instance’s list of available imagery. Subsequent calls - * to functions like [[WWTControl.setForegroundImageByName]] will be able to + * to functions like {@link WWTControl.setForegroundImageByName} will be able to * locate the new imagesets and display them to the user. * * If the URL is not accessible due to CORS restrictions, the request will * automatically be routed through the WWT’s CORS proxying service. * * After the collection is successfully loaded, a `collectionLoaded` event - * will be issued, which you can listen for using the [[add_collectionLoaded]] + * will be issued, which you can listen for using the {@link add_collectionLoaded} * method. * * [wtml]: https://docs.worldwidetelescope.org/data-guide/1/data-file-formats/collections/ @@ -1479,7 +1479,7 @@ export class ScriptInterface { /** Initiate the loading of a image set or single-file FITS layer. * * If the specified URL already exists in the image set collection, i.e. it - * has previously been created with [[loadImageCollection]], then this image set + * has previously been created with {@link loadImageCollection}, then this image set * is added to the view. * * If the specified URL is pointing to a FITS file, it will be downloaded and parsed. @@ -1510,19 +1510,19 @@ export class ScriptInterface { /** Create a circle annotation. * - * It is *not* automatically added to the renderer. Use [[addAnnotation]] to do that. + * It is *not* automatically added to the renderer. Use {@link addAnnotation} to do that. */ createCircle(fill: boolean): Circle; /** Create a polygonal annotation. * - * It is *not* automatically added to the renderer. Use [[addAnnotation]] to do that. + * It is *not* automatically added to the renderer. Use {@link addAnnotation} to do that. */ createPolygon(fill: boolean): Poly; /** Create a multi-line annotation. * - * It is *not* automatically added to the renderer. Use [[addAnnotation]] to do that. + * It is *not* automatically added to the renderer. Use {@link addAnnotation} to do that. */ createPolyLine(unused: boolean): PolyLine; @@ -1536,7 +1536,7 @@ export class ScriptInterface { clearAnnotations(): void; } -/** A generic [[ScriptInterface]] callback. */ +/** A generic {@link ScriptInterface} callback. */ export interface ScriptInterfaceCallback { (si: ScriptInterface): void; } @@ -1689,7 +1689,7 @@ export class Settings implements EngineSettingsInterface { export namespace SpaceTimeController { /** Have the WWT clock immediately lock onto to the system clock. * - * This function not only has the effect of calling [[set_syncToClock]] with a + * This function not only has the effect of calling {@link set_syncToClock} with a * true argument, it also sets the offset between the two clocks to be zero. */ export function syncTime(): void; @@ -1724,7 +1724,7 @@ export namespace SpaceTimeController { * @returns The input argument. * * If set to false, the WWT clock will stop advancing, ignoring the value of - * [[get_timeRate]]. If set to true, the WWT clock will resume advancing from + * {@link get_timeRate}. If set to true, the WWT clock will resume advancing from * where it left off, possibly inducing an offset between the WWT clock and * the system clock. */ @@ -1747,7 +1747,7 @@ export namespace SpaceTimeController { * that time in WWT proceeds 10 times faster than system time. The rate may be * negative. * - * Do not set the rate to zero. Instead, call [[set_syncToClock]] with a false + * Do not set the rate to zero. Instead, call {@link set_syncToClock} with a false * argument. */ export function set_timeRate(rate: number): number; @@ -1771,7 +1771,7 @@ export namespace SpaceTimeController { * @param jdate The Julian date, usually a number around 2.4 million. * @returns A Javascript datetime. * - * See [[get_jNow]] for commentary on this conversion, which is not rigorously + * See {@link get_jNow} for commentary on this conversion, which is not rigorously * correct and can only be trusted to granularities of less than around a * minute. */ @@ -1782,7 +1782,7 @@ export namespace SpaceTimeController { * @param date The datetime. * @returns A Julian date. * - * See [[get_jNow]] for commentary on this conversion, which is not rigorously + * See {@link get_jNow} for commentary on this conversion, which is not rigorously * correct and can only be trusted to granularities of less than around a * minute. */ @@ -1790,7 +1790,7 @@ export namespace SpaceTimeController { } /** An alias for the type implicitly defined by the static - * [[SpaceTimeController]] namespace. */ + * {@link SpaceTimeController} namespace. */ export type SpaceTimeControllerObject = typeof SpaceTimeController; @@ -1906,7 +1906,7 @@ export class SpreadSheetLayer extends Layer implements SpreadSheetLayerSettingsI */ getTableDataInView(): string; - /** Guess header semantics using a [[VoTable]] with similarly named columns as + /** Guess header semantics using a {@link VoTable} with similarly named columns as * a reference. This can exploit the typed "UCD" annotations associated with * such tables. * @@ -2037,15 +2037,15 @@ export class TourEditTab { } export interface TourEndedCallback { - /** Called when a [[TourPlayer]] has finished playing its tour. */ + /** Called when a {@link TourPlayer} has finished playing its tour. */ (player: TourPlayer): void; } /** An object that manages the playback of a tour. * - * Each [[TourPlayer]] may be associated with an underlying [[TourDocument]], - * which defines the tour in question. It may be accessed using the [[get_tour]] + * Each {@link TourPlayer} may be associated with an underlying {@link TourDocument}, + * which defines the tour in question. It may be accessed using the {@link get_tour} * method. */ export class TourPlayer implements UiController { @@ -2055,10 +2055,10 @@ export class TourPlayer implements UiController { /** Set the tour associated with this tour player. */ set_tour(tour: TourDocument | null): TourDocument | null; - /** Get whether this player will leave slide [[Settings]] applied when it stops. */ + /** Get whether this player will leave slide {@link Settings} applied when it stops. */ get_leaveSettingsWhenStopped(): boolean; - /** Set whether this player will leave slide [[Settings]] applied when it stops. */ + /** Set whether this player will leave slide {@link Settings} applied when it stops. */ set_leaveSettingsWhenStopped(v: boolean): boolean; /** Force the currently playing tour to advance to the next slide. */ @@ -2115,7 +2115,7 @@ export namespace TourPlayer { } -/** A stop in a [[TourDocument]]. */ +/** A stop in a {@link TourDocument}. */ export class TourStop implements SettingsInterface { get_description(): string; set_description(desc: string): string; @@ -2267,9 +2267,9 @@ export namespace VoTable { } -/** A [[VoTable]] rendered as a layer. +/** A {@link VoTable} rendered as a layer. * - * This class is highly similar to [[SpreadSheetLayer]], and the latter class is + * This class is highly similar to {@link SpreadSheetLayer}, and the latter class is * generally more featureful. It should be preferred when possible. */ export class VoTableLayer extends Layer implements VoTableLayerSettingsInterface { @@ -2354,7 +2354,7 @@ export class VoTableLayer extends Layer implements VoTableLayerSettingsInterface } export namespace VoTableLayer { - /** Create a new [[VoTableLayer]] for the specified [[VoTable]]. */ + /** Create a new {@link VoTableLayer} for the specified {@link VoTable}. */ export function create(table: VoTable, plotType: PlotTypes): VoTableLayer; } @@ -2438,48 +2438,48 @@ export class WcsImage { /** The primary WWT engine state object. * * The main state of the WWT rendering engine is stored in a global - * [[WWTControl]] singleton object. As such, this class has APIs relating to - * nearly every single feature offered by WWT. The [[ScriptInterface]] object + * {@link WWTControl} singleton object. As such, this class has APIs relating to + * nearly every single feature offered by WWT. The {@link ScriptInterface} object * adds a few additional features, but it primarily delegates its work to this * class. * * ### Rendering * - * - [[renderContext]], the core renderer state - * - [[renderType]], the current renderer mode - * - [[renderOneFrame]], a method to render a single frame + * - {@link renderContext}, the core renderer state + * - {@link renderType}, the current renderer mode + * - {@link renderOneFrame}, a method to render a single frame * * ### UI Plumbing * - * - [[uiController]], special UI state + * - {@link uiController}, special UI state * * ### Basic Camera Controls * - * - [[gotoRADecZoom]] - * - [[gotoTarget]] - * - [[zoom]] + * - {@link gotoRADecZoom} + * - {@link gotoTarget} + * - {@link zoom} * * ### Core Datasets * - * - [[getImagesetByName]] - * - [[getDefaultImageset]] - * - [[setBackgroundImageByName]] - * - [[setForegroundImageByName]] - * - [[addCatalogHipsByName]], [[addCatalogHipsByNameWithCallback]] - * - [[removeCatalogHipsByName]] + * - {@link getImagesetByName} + * - {@link getDefaultImageset} + * - {@link setBackgroundImageByName} + * - {@link setForegroundImageByName} + * - {@link addCatalogHipsByName}, {@link addCatalogHipsByNameWithCallback} + * - {@link removeCatalogHipsByName} * * ### Tours * - * - [[loadTour]] - * - [[playTour]] - * - [[playCurrentTour]] - * - [[pauseCurrentTour]] - * - [[stopCurrentTour]] + * - {@link loadTour} + * - {@link playTour} + * - {@link playCurrentTour} + * - {@link pauseCurrentTour} + * - {@link stopCurrentTour} * * ### Other Settings * - * - [[set_zoomMax]], [[set_zoomMin]] - * - [[setSolarSystemMaxZoom]], [[setSolarSystemMinZoom]] + * - {@link set_zoomMax}, {@link set_zoomMin} + * - {@link setSolarSystemMaxZoom}, {@link setSolarSystemMinZoom} * * */ export class WWTControl { @@ -2497,7 +2497,7 @@ export class WWTControl { /** The image sets that have been loaded into the engine */ static getImageSets(): Imageset[]; - /** Special UI state that may be active such as a [[TourPlayer]]. */ + /** Special UI state that may be active such as a {@link TourPlayer}. */ uiController: UiController | null; /** State of the WWT rendering engine. */ @@ -2506,7 +2506,7 @@ export class WWTControl { /** The current mode that the renderer is in. * * This value tracks the type of the background imageset. It is updated at the - * beginning of [[renderOneFrame]], not immediately upon alteration of the + * beginning of {@link renderOneFrame}, not immediately upon alteration of the * background image set. */ renderType: ImageSetType; @@ -2519,7 +2519,7 @@ export class WWTControl { * The current reference frame defines the physical coordinates of the view * and the list of layers that are included in the current rendering process. * The return value of this function can be indexed into - * [[LayerManager.get_allMaps]] to find the root [[LayerMap]] that is used to + * {@link LayerManager.get_allMaps} to find the root {@link LayerMap} that is used to * determine what gets rendered in the current view. * * In standard 2D sky mode, the return value will be `"Sky"`. @@ -2564,7 +2564,7 @@ export class WWTControl { */ timeToRADecZoom(ra_hours: number, dec_deg: number, zoom: number, roll_deg?: number): number; - /** Start navigating the view to the specified [[Place]]. + /** Start navigating the view to the specified {@link Place}. * * @param place The destination of the view * @param noZoom If true, the zoom, angle, and rotation of the target camera @@ -2611,7 +2611,7 @@ export class WWTControl { * This function searches the control’s database of imagery and returns a * "default" imageset for the given settings. First preference is given to an * imageset with matching `type` and `bandpass` that has a - * [[Imageset.get_defaultSet]] of true (corresponding to the `StockSet` XML + * {@link Imageset.get_defaultSet} of true (corresponding to the `StockSet` XML * attribute). If no such set exists, the first set with matching `type` and * `bandpass` is returned, regardless of its `defaultSet` setting. If there is * still no such result, the first imageset with the same `type`, ignoring @@ -2629,9 +2629,9 @@ export class WWTControl { * This function may change the viewer mode (e.g. sky, panorama, 3D solar * system, etc.). To avoid display artifacts when switching to a planetary * mode, set the foreground imageset to the same value using - * [[setForegroundImageByName]]. + * {@link setForegroundImageByName}. * - * The imageset lookup is done using [[getImagesetByName]]. If the imageset is + * The imageset lookup is done using {@link getImagesetByName}. If the imageset is * not found, this function silently does nothing. * * @param imagesetName: The imageset name. @@ -2640,7 +2640,7 @@ export class WWTControl { /** Set the foreground imageset using a name-based lookup. * - * The imageset lookup is done using [[getImagesetByName]]. If the imageset is + * The imageset lookup is done using {@link getImagesetByName}. If the imageset is * not found, this function silently does nothing. * * Note that this function does not alter the camera in any way. You will need @@ -2653,32 +2653,32 @@ export class WWTControl { /** Add a "catalog HiPS" dataset to the current view. * - * The [[SpreadSheetLayer]] of data associated with this special imageset will - * be added to the [[LayerManager]]. The caller must know *a priori* that the + * The {@link SpreadSheetLayer} of data associated with this special imageset will + * be added to the {@link LayerManager}. The caller must know *a priori* that the * named imageset indeed corresponds to a catalog HiPS dataset. * - * See also [[addCatalogHipsByName]], [[addCatalogHipsByNameWithCallback]]. + * See also {@link addCatalogHipsByName}, {@link addCatalogHipsByNameWithCallback}. * */ addCatalogHips(imageset: Imageset): void; /** Add a "catalog HiPS" dataset to the current view, by name. * * The catalog HiPS is loaded from the engine’s listing of recognized - * imagesets using the [[getImagesetByName]] mechanism. The - * [[SpreadSheetLayer]] of data associated with this special imageset will be - * added to the [[LayerManager]]. The caller must know *a priori* that the + * imagesets using the {@link getImagesetByName} mechanism. The + * {@link SpreadSheetLayer} of data associated with this special imageset will be + * added to the {@link LayerManager}. The caller must know *a priori* that the * named imageset indeed corresponds to a catalog HiPS dataset. * - * See also [[addCatalogHips]], [[addCatalogHipsByNameWithCallback]]. + * See also {@link addCatalogHips}, {@link addCatalogHipsByNameWithCallback}. * */ addCatalogHipsByName(name: string): void; /** Add a "catalog HiPS" dataset to the current view, by name, with a * callback. * - * Same as [[addCatalogHipsByName]], with the addition that the *onLoad* + * Same as {@link addCatalogHipsByName}, with the addition that the *onLoad* * callback will be called once the initial data loading of the catalog HiPS - * data has completed. See also [[addCatalogHips]]. + * data has completed. See also {@link addCatalogHips}. * */ addCatalogHipsByNameWithCallback(name: string, onLoad: Action): void; @@ -2694,9 +2694,9 @@ export class WWTControl { /** Start loading the tour stored at the specified URL. * * When loading is complete, a `tourReady` event will be issued, which you can - * listen for using the [[add_tourReady]] method. You can then get access to a - * [[TourPlayer]] by casting the [[uiController]] property of this - * [[WWTControl]]: + * listen for using the {@link ScriptInterface.add_tourReady} method. You can + * then get access to a {@link TourPlayer} by casting the {@link uiController} + * property of this {@link WWTControl}: * * ``` * if (ctl.uiController !== null && ctl.uiController instanceof TourPlayer) { @@ -2710,9 +2710,9 @@ export class WWTControl { /** Load the tour stored at the specified URL and start playing it. * * When loading is complete, a `tourReady` event will be issued, which you can - * listen for using the [[add_tourReady]] method. + * listen for using the {@link ScriptInterface.add_tourReady} method. * - * See also [[loadTour]], which provides more flexibility to the caller. + * See also {@link loadTour}, which provides more flexibility to the caller. */ playTour(url: string): void; @@ -2795,10 +2795,10 @@ export class WWTControl { } export namespace Wtml { - /** Load a WTML collection and register its imagesets with the [[WWTControl]]. + /** Load a WTML collection and register its imagesets with the {@link WWTControl}. * * This function launches an asychronous operation to retrieve the collection - * data from the specified URL. As such, the returned [[Folder]] object will + * data from the specified URL. As such, the returned {@link Folder} object will * start out blank and unpopulated. Its contents will be filled in from the * parsed data at some point in the future, at which point the `complete` * callback will be called. @@ -2807,7 +2807,7 @@ export namespace Wtml { * @param complete A callback to be called after the folder (and all child * folders, if loadChildFolders is set to true) is successfully loaded. * @param loadChildFolders Optional, When true, this method will recursively - * download and unpack all [[Folder]]s contained in the original WTML file. + * download and unpack all {@link Folder}s contained in the original WTML file. * Defaults to false. * @returns A folder object that will be populated asynchronously. */ @@ -2818,7 +2818,7 @@ export namespace WWTControl { /** Initialize the WWT engine and launch its rendering loop. * * While this function is maintained for backwards compatibility, modern users - * should use the [[WWTControlBuilder]] class to initialize and instantiate + * should use the {@link WWTControlBuilder} class to initialize and instantiate * the engine. * * The engine is not immediately usable since it must perform initialization @@ -2826,7 +2826,7 @@ export namespace WWTControl { * * @param divId The `id` of the DOM element into which the WWT WebGL surface * will be inserted. - * @return A handle to a [[ScriptInterface]] associated with this engine + * @return A handle to a {@link ScriptInterface} associated with this engine * instance. */ export function initControl(divId: string): ScriptInterface; @@ -2834,10 +2834,10 @@ export namespace WWTControl { /** Initialize the WWT engine with defaults. * * While this function is maintained for backwards compatibility, modern users - * should use the [[WWTControlBuilder]] class to initialize and instantiate + * should use the {@link WWTControlBuilder} class to initialize and instantiate * the engine. * - * The same as [[initControl6]], with `startLat` and `startLng` defaulting to + * The same as {@link initControl6}, with `startLat` and `startLng` defaulting to * 0, `startZoom` defaulting to 360, and `startMode` defaulting to `"Sky"`. */ export function initControl2(divId: string, startRenderLoop: boolean): ScriptInterface; @@ -2845,7 +2845,7 @@ export namespace WWTControl { /** Initialize the WWT engine. * * While this function is maintained for backwards compatibility, modern users - * should use the [[WWTControlBuilder]] class to initialize and instantiate + * should use the {@link WWTControlBuilder} class to initialize and instantiate * the engine. * * The engine is not immediately usable since it must perform initialization @@ -2864,7 +2864,7 @@ export namespace WWTControl { * @param startZoom The starting zoom level for the view. * @param startMode The starting mode for the view: one of `"earth"` or * `"Sky"` or `"black"`. - * @return A handle to a [[ScriptInterface]] associated with this engine + * @return A handle to a {@link ScriptInterface} associated with this engine * instance. */ export function initControl6( diff --git a/engine/tsconfig.json b/engine/tsconfig.json index a5016be5..c2fab4a1 100644 --- a/engine/tsconfig.json +++ b/engine/tsconfig.json @@ -33,6 +33,33 @@ "excludePrivate": true, "validation": { "invalidLink": true - } + }, + "intentionallyNotExported": [ + "AltTypes", + "AltUnits", + "BandPass", + "BaseEngineSetting", + "BaseLayerSetting", + "BaseImageSetLayerSetting", + "BaseSpreadSheetLayerSetting", + "BaseVoTableLayerSetting", + "Classification", + "ConstellationFilterInterface", + "CoordinatesType", + "FadeType", + "FolderGroup", + "FolderRefreshType", + "FolderType", + "ImageSetType", + "MarkerScales", + "PlotTypes", + "PointScaleTypes", + "ProjectionType", + "RAUnits", + "ScaleTypes", + "SettingsInterface", + "SolarSystemObjects", + "Thumbnail" + ] } -} \ No newline at end of file +} From ff984466b60238870a48e84d59d81edabf6ffa22 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 6 Oct 2023 13:22:51 -0400 Subject: [PATCH 06/29] engine-helpers: tidy up doc warnings, provide a little bit more of an index --- docs/engine/engine-helpers-index.md | 15 ++++++- engine-helpers/src/circleannotation.ts | 2 +- engine-helpers/src/imagesetlayer.ts | 2 +- engine-helpers/src/index.ts | 41 +++++++++++-------- engine-helpers/src/polyannotation.ts | 2 +- engine-helpers/src/polylineannotation.ts | 2 +- engine-helpers/src/spreadsheetlayer.ts | 2 +- engine-helpers/src/votablelayer.ts | 2 +- engine-helpers/tsconfig.json | 52 +++++++++++++++++++++++- 9 files changed, 95 insertions(+), 25 deletions(-) diff --git a/docs/engine/engine-helpers-index.md b/docs/engine/engine-helpers-index.md index 05b4d6b4..3eb37cd4 100644 --- a/docs/engine/engine-helpers-index.md +++ b/docs/engine/engine-helpers-index.md @@ -1 +1,14 @@ -More idiomatic wrappers for the engine. +More idiomatic wrappers for the [engine](../engine/). + +This package provides infrastructure for controlling the WWT engine with your +own JavaScript/TypeScript coe. It’s higher-level than the pure +[@wwtelescope/engine](../engine/) implementation, but not as sophisticated as +the [@wwtelescope/engine-pinia](../engine-pinia/) package, which depends on +[Vue] and [Pinia]. + +[Vue]: https://vuejs.org/ +[Pinia]: https://pinia.vuejs.org/ + +Your primary gateway into this package is the +[WWTInstance](./classes/WWTInstance.html) type, which provides an +object-oriented interface for controlling the WWT engine. diff --git a/engine-helpers/src/circleannotation.ts b/engine-helpers/src/circleannotation.ts index 36bebe54..cb9be4aa 100644 --- a/engine-helpers/src/circleannotation.ts +++ b/engine-helpers/src/circleannotation.ts @@ -30,7 +30,7 @@ const justCircleAnnotationSettingNames = [ /** A list of the names of the available settings for `CircleAnnotation` * instances and their equivalents (things implementing - * [[CircleAnnotationSettingsInterface]]). + * {@link CircleAnnotationSettingsInterface}). * * This is a superset of the names available for generic annotations. */ diff --git a/engine-helpers/src/imagesetlayer.ts b/engine-helpers/src/imagesetlayer.ts index b7e25a76..412d17d6 100644 --- a/engine-helpers/src/imagesetlayer.ts +++ b/engine-helpers/src/imagesetlayer.ts @@ -30,7 +30,7 @@ const justImageSetLayerSettingNames = [ /** A list of the names of the available settings for `ImageSetLayer` * instances and their equivalents (things implementing - * [[ImageSetLayerSettingsInterface]]). + * {@link ImageSetLayerSettingsInterface}). * * This is a superset of the names available for generic layers. */ diff --git a/engine-helpers/src/index.ts b/engine-helpers/src/index.ts index bef0868e..022a96bc 100644 --- a/engine-helpers/src/index.ts +++ b/engine-helpers/src/index.ts @@ -120,7 +120,7 @@ export const enum InitControlViewType { Earth = "earth", } -/** Options for the [[WWTInstance]] constructor. */ +/** Options for the {@link WWTInstance} constructor. */ export interface InitControlSettings { /** The identifier of the DOM element to which to attach the control. If * unspecified, defaults to `"wwt"`. */ @@ -154,7 +154,7 @@ export interface InitControlSettings { startMode?: InitControlViewType; } -/** Options for [[WWTInstance.gotoTarget]]. */ +/** Options for {@link WWTInstance.gotoTarget}. */ export interface GotoTargetOptions { /** The destination of the view. */ place: Place; @@ -175,7 +175,7 @@ export interface GotoTargetOptions { /** Deprecated, use AddImageSetLayerOptions instead. - * Options for [[WWTInstance.addImageSetLayer]]. */ + * Options for {@link WWTInstance.addImageSetLayer}. */ export interface LoadFitsLayerOptions { /** The URL of the FITS file. */ url: string; @@ -188,20 +188,20 @@ export interface LoadFitsLayerOptions { gotoTarget: boolean; } -/** Options for [[WWTInstance.addImageSetLayer]]. */ +/** Options for {@link WWTInstance.addImageSetLayer}. */ export interface AddImageSetLayerOptions { /** The URL of the FITS file *or* the URL of the desired image set. * * This should match an image set URL previously loaded with - * [[WWTInstance.loadImageCollection]]. */ + * {@link WWTInstance.loadImageCollection}. */ url: string; /** Indicates what type of layer you are adding. * - * If "fits", the [[url]] will be taken to point to a single FITS File that + * If "fits", the {@link url} will be taken to point to a single FITS File that * should be added. If "preloaded", it will be taken to match the URL * associated with an imageset that has already been added to WWT's internal - * catalogs via [[WWTInstance.loadImageCollection]]. If "autodetect", WWT will + * catalogs via {@link WWTInstance.loadImageCollection}. If "autodetect", WWT will * guess: if the URL ends with a FITS-like extension, "fits" mode will be * activated; otherwise it will use "preloaded" mode. */ mode: "autodetect" | "fits" | "preloaded"; @@ -214,7 +214,7 @@ export interface AddImageSetLayerOptions { goto: boolean; } -/** Options for [[WWTInstance.setImageSetLayerOrder]]. */ +/** Options for {@link WWTInstance.setImageSetLayerOrder}. */ export interface SetLayerOrderOptions { /** The ID of the layer. */ id: string; @@ -224,7 +224,7 @@ export interface SetLayerOrderOptions { } -/** Options for [[WWTInstance.stretchFitsLayer]]. */ +/** Options for {@link WWTInstance.stretchFitsLayer}. */ export interface StretchFitsLayerOptions { /** The ID of the FITS layer. */ id: string; @@ -239,7 +239,7 @@ export interface StretchFitsLayerOptions { vmax: number; } -/** Options for [[WWTInstance.setFitsLayerColormap]]. */ +/** Options for {@link WWTInstance.setFitsLayerColormap}. */ export interface SetFitsLayerColormapOptions { /** The ID of the FITS layer. */ id: string; @@ -293,7 +293,7 @@ export interface GetCatalogHipsDataInViewOptions { limit: boolean; } -/** Options for [[setupForImageset]]. */ +/** Options for {@link WWTInstance.setupForImageset}. */ export interface SetupForImagesetOptions { /** The imageset to foreground. */ foreground: Imageset; @@ -303,7 +303,7 @@ export interface SetupForImagesetOptions { background?: Imageset; } -/** Options for [CaptureFrame] */ +/** Options for {@link WWTInstance.captureFrame}. */ export interface CaptureFrameOptions { /** The desired image width, in pixels. */ width: number; @@ -353,9 +353,16 @@ class SavedPromise { } export class WWTInstance { + /** The [`WWTControl`](../../engine/classes/WWTControl-1.html) associated with this instance. */ readonly ctl: WWTControl; + + /** The [`LayerManager`](../../engine/modules/LayerManager.html) associated with this instance. */ readonly lm: LayerManagerObject; + + /** The [`ScriptInterface`](../../engine/classes/ScriptInterface.html) associated with this instance. */ readonly si: ScriptInterface; + + /** The [`SpaceTimeController`](../../engine/modules/SpaceTimeController.html) associated with this instance. */ readonly stc: SpaceTimeControllerObject; /** Create a WWT control, attaching it to a DOM element. @@ -571,7 +578,7 @@ export class WWTInstance { * an XML document in the [WTML collection][wtml] format. Any `ImageSet` * entries in the collection, or `Place` entries containing image sets, will * be added to the WWT instance’s list of available imagery. Subsequent calls - * to functions like [[setForegroundImageByName]] will be able to locate the + * to functions like {@link setForegroundImageByName} will be able to locate the * new imagesets and display them to the user. * * Each unique URL is only requested once. Once a given URL has been @@ -651,7 +658,7 @@ export class WWTInstance { * The FITS file must be downloaded and processed, so this API is * asynchronous, and is not appropriate for files that might be large. * - * The image set must have previously been created with [[loadImageCollection]] + * The image set must have previously been created with {@link loadImageCollection} */ async addImageSetLayer(options: AddImageSetLayerOptions): Promise { return new Promise((resolve, _reject) => { @@ -729,7 +736,7 @@ export class WWTInstance { * imgset.get_hipsProperties().get_catalogSpreadSheetLayer() * ``` * - * You can use methods like [[applyTableLayerSettings]] to modify the settings + * You can use methods like {@link applyTableLayerSettings} to modify the settings * of this layer by extracting its ID string with `layer.id.toString()`. * * The contents of this catalog will update dynamically as the user navigates @@ -751,7 +758,7 @@ export class WWTInstance { /** Fetch the subset of catalog HiPS data contained within the current view. * - * The imageset should have been loaded with the [[addCatalogHipsByName]] + * The imageset should have been loaded with the {@link addCatalogHipsByName} * call. The *limit* option should almost always be true, since if it is false * the data-fetch operation can potentially attempt to download and return * gigabytes of data. @@ -900,7 +907,7 @@ export class WWTInstance { /** Load a tour from a URL. * - * Once the tour has loaded, you can use [[getActiveTourPlayer]] to get the + * Once the tour has loaded, you can use {@link getActiveTourPlayer} to get the * tour player controller and the underlying tour document. * * @param url The URL of the tour to load and play. diff --git a/engine-helpers/src/polyannotation.ts b/engine-helpers/src/polyannotation.ts index 6aabf880..6e3726af 100644 --- a/engine-helpers/src/polyannotation.ts +++ b/engine-helpers/src/polyannotation.ts @@ -28,7 +28,7 @@ const justPolyAnnotationSettingNames = [ /** A list of the names of the available settings for `PolyAnnotation` * instances and their equivalents (things implementing - * [[PolyAnnotationSettingsInterface]]). + * {@link PolyAnnotationSettingsInterface}). * * This is a superset of the names available for generic annotations. */ diff --git a/engine-helpers/src/polylineannotation.ts b/engine-helpers/src/polylineannotation.ts index 082abb80..dc8bddea 100644 --- a/engine-helpers/src/polylineannotation.ts +++ b/engine-helpers/src/polylineannotation.ts @@ -26,7 +26,7 @@ const justPolyLineAnnotationSettingNames = [ /** A list of the names of the available settings for `PolyLineAnnotation` * instances and their equivalents (things implementing - * [[PolyLineAnnotationSettingsInterface]]). + * {@link PolyLineAnnotationSettingsInterface}). * * This is a superset of the names available for generic annotations. */ diff --git a/engine-helpers/src/spreadsheetlayer.ts b/engine-helpers/src/spreadsheetlayer.ts index eafd3d4d..b68ae44e 100644 --- a/engine-helpers/src/spreadsheetlayer.ts +++ b/engine-helpers/src/spreadsheetlayer.ts @@ -80,7 +80,7 @@ const justSpreadSheetLayerSettingNames = [ /** A list of the names of the available settings for `SpreadSheetLayer` * instances and their equivalents (things implementing - * [[SpreadSheetLayerSettingsInterface]]). + * {@link SpreadSheetLayerSettingsInterface}). * * This is a superset of the names available for generic layers. */ diff --git a/engine-helpers/src/votablelayer.ts b/engine-helpers/src/votablelayer.ts index edd68964..0569b41d 100644 --- a/engine-helpers/src/votablelayer.ts +++ b/engine-helpers/src/votablelayer.ts @@ -71,7 +71,7 @@ const justVoTableLayerSettingNames = [ /** A list of the names of the available settings for `VoTableLayer` * instances and their equivalents (things implementing - * [[VoTableLayerSettingsInterface]]). + * {@link VoTableLayerSettingsInterface}). * * This is a superset of the names available for generic layers. */ diff --git a/engine-helpers/tsconfig.json b/engine-helpers/tsconfig.json index af696b20..1cbcf7d2 100644 --- a/engine-helpers/tsconfig.json +++ b/engine-helpers/tsconfig.json @@ -35,6 +35,56 @@ "excludePrivate": true, "validation": { "invalidLink": true - } + }, + "intentionallyNotExported": [ + "AltTypes", + "AltUnits", + "AnnotationSetting", + "AnnotationSettingsInterface", + "AnnotationSettingsInterfaceRO", + "CircleAnnotationSetting", + "CircleAnnotationSettingsInterface", + "CircleAnnotationSettingsInterfaceRO", + "Color", + "ConstellationFilter", + "CoordinatesType", + "EngineSetting", + "EngineSettingsInterface", + "FadeType", + "Folder", + "Imageset", + "ImageSetLayer", + "ImageSetLayerSetting", + "ImageSetLayerSettingsInterface", + "ImageSetLayerSettingsInterfaceRO", + "InViewReturnMessage", + "LayerManager", + "LayerSetting", + "LayerSettingsInterface", + "LayerSettingsInterfaceRO", + "MarkerScales", + "Place", + "PolyAnnotationSetting", + "PolyAnnotationSettingsInterface", + "PolyAnnotationSettingsInterfaceRO", + "PolyLineAnnotationSetting", + "PolyLineAnnotationSettingsInterface", + "PolyLineAnnotationSettingsInterfaceRO", + "PlotTypes", + "PointScaleTypes", + "RAUnits", + "ScaleTypes", + "ScriptInterface", + "SettingsInterface", + "SpaceTimeController", + "SpreadSheetLayerSetting", + "SpreadSheetLayerSettingsInterface", + "SpreadSheetLayerSettingsInterfaceRO", + "TourPlayer", + "VoTableLayerSetting", + "VoTableLayerSettingsInterface", + "VoTableLayerSettingsInterfaceRO", + "WWTControl", + ] } } \ No newline at end of file From bd850ca6a9a538df17d3dcfab419a4e698d0ab5e Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Sat, 7 Oct 2023 17:01:06 -0400 Subject: [PATCH 07/29] Take the plunge and update to latest typedoc --- astro/package.json | 2 +- embed-common/package.json | 2 +- embed-common/tsconfig.json | 3 +- embed-creator/package.json | 2 +- embed/package.json | 2 +- engine-helpers/package.json | 2 +- engine-helpers/tsconfig.json | 52 +----------------- engine-pinia/package.json | 2 +- engine-types/package.json | 2 +- engine/package.json | 2 +- engine/tsconfig.json | 31 +---------- research-app-messages/package.json | 2 +- research-app/package.json | 2 +- yarn.lock | 86 ++++++++++++++++++------------ 14 files changed, 66 insertions(+), 126 deletions(-) diff --git a/astro/package.json b/astro/package.json index 2a5ef398..e17e67db 100644 --- a/astro/package.json +++ b/astro/package.json @@ -10,7 +10,7 @@ "@typescript-eslint/parser": "^5.38.1", "eslint": "^8.24.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4" }, "homepage": "https://worldwidetelescope.org/home/", diff --git a/embed-common/package.json b/embed-common/package.json index 358127ff..2f6e683c 100644 --- a/embed-common/package.json +++ b/embed-common/package.json @@ -13,7 +13,7 @@ "@typescript-eslint/parser": "^5.38.1", "eslint": "^8.24.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4" }, "homepage": "https://worldwidetelescope.org/home/", diff --git a/embed-common/tsconfig.json b/embed-common/tsconfig.json index 1a6d4ec0..0cc4bb64 100644 --- a/embed-common/tsconfig.json +++ b/embed-common/tsconfig.json @@ -29,7 +29,6 @@ "excludePrivate": true, "validation": { "invalidLink": true - }, - "intentionallyNotExported": ["BaseEngineSetting"] + } } } \ No newline at end of file diff --git a/embed-creator/package.json b/embed-creator/package.json index a2a28f77..8f78ae9a 100644 --- a/embed-creator/package.json +++ b/embed-creator/package.json @@ -32,7 +32,7 @@ "rimraf": "^3", "sass": "^1.26.3", "sass-loader": "^13.0.2", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4", "vue-template-compiler": "~2.6.11", "webpack": "^5.76.0" diff --git a/embed/package.json b/embed/package.json index 11d7c4cb..89fc143d 100644 --- a/embed/package.json +++ b/embed/package.json @@ -32,7 +32,7 @@ "rimraf": "^3", "sass": "^1.26.3", "sass-loader": "^13.0.2", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4", "vue-template-compiler": "~2.6.11", "webpack": "^5.76.0" diff --git a/engine-helpers/package.json b/engine-helpers/package.json index 375e440d..55ba2a63 100644 --- a/engine-helpers/package.json +++ b/engine-helpers/package.json @@ -15,7 +15,7 @@ "@typescript-eslint/parser": "^5.38.1", "eslint": "^8.24.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4" }, "homepage": "https://worldwidetelescope.org/home/", diff --git a/engine-helpers/tsconfig.json b/engine-helpers/tsconfig.json index 1cbcf7d2..af696b20 100644 --- a/engine-helpers/tsconfig.json +++ b/engine-helpers/tsconfig.json @@ -35,56 +35,6 @@ "excludePrivate": true, "validation": { "invalidLink": true - }, - "intentionallyNotExported": [ - "AltTypes", - "AltUnits", - "AnnotationSetting", - "AnnotationSettingsInterface", - "AnnotationSettingsInterfaceRO", - "CircleAnnotationSetting", - "CircleAnnotationSettingsInterface", - "CircleAnnotationSettingsInterfaceRO", - "Color", - "ConstellationFilter", - "CoordinatesType", - "EngineSetting", - "EngineSettingsInterface", - "FadeType", - "Folder", - "Imageset", - "ImageSetLayer", - "ImageSetLayerSetting", - "ImageSetLayerSettingsInterface", - "ImageSetLayerSettingsInterfaceRO", - "InViewReturnMessage", - "LayerManager", - "LayerSetting", - "LayerSettingsInterface", - "LayerSettingsInterfaceRO", - "MarkerScales", - "Place", - "PolyAnnotationSetting", - "PolyAnnotationSettingsInterface", - "PolyAnnotationSettingsInterfaceRO", - "PolyLineAnnotationSetting", - "PolyLineAnnotationSettingsInterface", - "PolyLineAnnotationSettingsInterfaceRO", - "PlotTypes", - "PointScaleTypes", - "RAUnits", - "ScaleTypes", - "ScriptInterface", - "SettingsInterface", - "SpaceTimeController", - "SpreadSheetLayerSetting", - "SpreadSheetLayerSettingsInterface", - "SpreadSheetLayerSettingsInterfaceRO", - "TourPlayer", - "VoTableLayerSetting", - "VoTableLayerSettingsInterface", - "VoTableLayerSettingsInterfaceRO", - "WWTControl", - ] + } } } \ No newline at end of file diff --git a/engine-pinia/package.json b/engine-pinia/package.json index bb0159f4..26f2f333 100644 --- a/engine-pinia/package.json +++ b/engine-pinia/package.json @@ -24,7 +24,7 @@ "eslint": "^8.24.0", "eslint-plugin-vue": "^9.5.1", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4", "vue-template-compiler": "~2.6.11" }, diff --git a/engine-types/package.json b/engine-types/package.json index 076ac7a9..60a33b89 100644 --- a/engine-types/package.json +++ b/engine-types/package.json @@ -10,7 +10,7 @@ "@typescript-eslint/parser": "^5.38.1", "eslint": "^8.24.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4" }, "homepage": "https://worldwidetelescope.org/home/", diff --git a/engine/package.json b/engine/package.json index 6f539462..36cb8039 100644 --- a/engine/package.json +++ b/engine/package.json @@ -18,7 +18,7 @@ "eslint": "^8.24.0", "mocha-headless-chrome": "^4.0.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4", "webpack": "^5.76.0", "webpack-cli": "^5.1.4" diff --git a/engine/tsconfig.json b/engine/tsconfig.json index c2fab4a1..a5016be5 100644 --- a/engine/tsconfig.json +++ b/engine/tsconfig.json @@ -33,33 +33,6 @@ "excludePrivate": true, "validation": { "invalidLink": true - }, - "intentionallyNotExported": [ - "AltTypes", - "AltUnits", - "BandPass", - "BaseEngineSetting", - "BaseLayerSetting", - "BaseImageSetLayerSetting", - "BaseSpreadSheetLayerSetting", - "BaseVoTableLayerSetting", - "Classification", - "ConstellationFilterInterface", - "CoordinatesType", - "FadeType", - "FolderGroup", - "FolderRefreshType", - "FolderType", - "ImageSetType", - "MarkerScales", - "PlotTypes", - "PointScaleTypes", - "ProjectionType", - "RAUnits", - "ScaleTypes", - "SettingsInterface", - "SolarSystemObjects", - "Thumbnail" - ] + } } -} +} \ No newline at end of file diff --git a/research-app-messages/package.json b/research-app-messages/package.json index 535cf3a6..87d45f42 100644 --- a/research-app-messages/package.json +++ b/research-app-messages/package.json @@ -10,7 +10,7 @@ "@typescript-eslint/parser": "^5.38.1", "eslint": "^8.24.0", "rimraf": "^3", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4" }, "homepage": "https://worldwidetelescope.org/home/", diff --git a/research-app/package.json b/research-app/package.json index 7017f93e..562bf9ab 100644 --- a/research-app/package.json +++ b/research-app/package.json @@ -39,7 +39,7 @@ "rimraf": "^3", "sass": "^1.26.3", "sass-loader": "^13.0.2", - "typedoc": "0.23.20", + "typedoc": "0.25.1", "typescript": "~4.8.4", "vue-template-compiler": "~2.6.11", "webpack": "^5.76.0" diff --git a/yarn.lock b/yarn.lock index 2745c35a..053a2770 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1649,7 +1649,7 @@ __metadata: "@typescript-eslint/parser": ^5.38.1 eslint: ^8.24.0 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 languageName: unknown linkType: soft @@ -1663,7 +1663,7 @@ __metadata: "@wwtelescope/engine-types": "workspace:0.0.0-dev.0" eslint: ^8.24.0 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 languageName: unknown linkType: soft @@ -1694,7 +1694,7 @@ __metadata: rimraf: ^3 sass: ^1.26.3 sass-loader: ^13.0.2 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 vue: ^3 vue-clipboard3: ^2.0.0 @@ -1728,7 +1728,7 @@ __metadata: sass: ^1.26.3 sass-loader: ^13.0.2 screenfull: ^5 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 v-tooltip: ^2.1 vue: ^3 @@ -1749,7 +1749,7 @@ __metadata: "@wwtelescope/engine-types": "workspace:0.0.0-dev.0" eslint: ^8.24.0 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 languageName: unknown linkType: soft @@ -1772,7 +1772,7 @@ __metadata: eslint-plugin-vue: ^9.5.1 pinia: ^2.0.22 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 vue: ^3 vue-template-compiler: ~2.6.11 @@ -1787,7 +1787,7 @@ __metadata: "@typescript-eslint/parser": ^5.38.1 eslint: ^8.24.0 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 languageName: unknown linkType: soft @@ -1804,7 +1804,7 @@ __metadata: mocha-headless-chrome: ^4.0.0 pako: ^1.0.11 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 uuid: ^8.3.2 webpack: ^5.76.0 @@ -1820,7 +1820,7 @@ __metadata: "@typescript-eslint/parser": ^5.38.1 eslint: ^8.24.0 rimraf: ^3 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 languageName: unknown linkType: soft @@ -1855,7 +1855,7 @@ __metadata: sass: ^1.26.3 sass-loader: ^13.0.2 screenfull: ^5 - typedoc: 0.23.20 + typedoc: 0.25.1 typescript: ~4.8.4 vue: ^3 vue-color-kit: ^1.0.5 @@ -2118,6 +2118,13 @@ __metadata: languageName: node linkType: hard +"ansi-sequence-parser@npm:^1.1.0": + version: 1.1.1 + resolution: "ansi-sequence-parser@npm:1.1.1" + checksum: ead5b15c596e8e85ca02951a844366c6776769dcc9fd1bd3a0db11bb21364554822c6a439877fb599e7e1ffa0b5f039f1e5501423950457f3dcb2f480c30b188 + languageName: node + linkType: hard + "ansi-styles@npm:^3.2.0, ansi-styles@npm:^3.2.1": version: 3.2.1 resolution: "ansi-styles@npm:3.2.1" @@ -6557,7 +6564,7 @@ __metadata: languageName: node linkType: hard -"jsonc-parser@npm:^3.0.0": +"jsonc-parser@npm:^3.2.0": version: 3.2.0 resolution: "jsonc-parser@npm:3.2.0" checksum: 946dd9a5f326b745aa326d48a7257e3f4a4b62c5e98ec8e49fa2bdd8d96cef7e6febf1399f5c7016114fd1f68a1c62c6138826d5d90bc650448e3cf0951c53c7 @@ -7157,7 +7164,7 @@ __metadata: languageName: node linkType: hard -"marked@npm:^4.0.19": +"marked@npm:^4.3.0": version: 4.3.0 resolution: "marked@npm:4.3.0" bin: @@ -7332,7 +7339,7 @@ __metadata: languageName: node linkType: hard -"minimatch@npm:^5.0.1, minimatch@npm:^5.1.0": +"minimatch@npm:^5.0.1": version: 5.1.6 resolution: "minimatch@npm:5.1.6" dependencies: @@ -7341,7 +7348,7 @@ __metadata: languageName: node linkType: hard -"minimatch@npm:^9.0.1": +"minimatch@npm:^9.0.1, minimatch@npm:^9.0.3": version: 9.0.3 resolution: "minimatch@npm:9.0.3" dependencies: @@ -9975,14 +9982,15 @@ __metadata: languageName: node linkType: hard -"shiki@npm:^0.11.1": - version: 0.11.1 - resolution: "shiki@npm:0.11.1" +"shiki@npm:^0.14.1": + version: 0.14.4 + resolution: "shiki@npm:0.14.4" dependencies: - jsonc-parser: ^3.0.0 - vscode-oniguruma: ^1.6.1 - vscode-textmate: ^6.0.0 - checksum: 2a4ebc3b466816263fc244ae4f67a4ff96aa74d863b9c5e7e4affc50f37fd6d1a781405de0dbf763b777bc33e49a0d441de7ff3fededb8b01e3b8dbb37e2927d + ansi-sequence-parser: ^1.1.0 + jsonc-parser: ^3.2.0 + vscode-oniguruma: ^1.7.0 + vscode-textmate: ^8.0.0 + checksum: 1173f6fa9531690a8cd4bf1d8e28c9eb9295af38a4c150cba6546e95f6e32bc96c7dd98826e39e688f1ca9d36b683a9a02ef77d51ce6495900b3a46ada64f828 languageName: node linkType: hard @@ -10959,19 +10967,28 @@ __metadata: languageName: node linkType: hard -"typedoc@npm:0.23.20": - version: 0.23.20 - resolution: "typedoc@npm:0.23.20" +"typedoc-plugin-vue@npm:^1.1.0": + version: 1.1.0 + resolution: "typedoc-plugin-vue@npm:1.1.0" + peerDependencies: + typedoc: 0.25.x + checksum: b689dab5716a38c76e9c0848932cb0118e2af3c482b0b0ea80c67680a006c6ee35a024db819b0dc972af52e572a04b0d008862c6874bca7d7547872cc2e6caac + languageName: node + linkType: hard + +"typedoc@npm:0.25.1": + version: 0.25.1 + resolution: "typedoc@npm:0.25.1" dependencies: lunr: ^2.3.9 - marked: ^4.0.19 - minimatch: ^5.1.0 - shiki: ^0.11.1 + marked: ^4.3.0 + minimatch: ^9.0.3 + shiki: ^0.14.1 peerDependencies: - typescript: 4.6.x || 4.7.x || 4.8.x + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x bin: typedoc: bin/typedoc - checksum: 8dbe046794a827b87e186523df86573673520ea5c706e1dfc2a820360bda5e998c23fd2ced91299ef060339f6ebba1086776e4e7423769da9b135a13edee10ec + checksum: 6c1c28cbf51b6ab1741429f58f540c5c12d6119ce30054866b879ef2a3a2120a6adbaf59919f7411d3bb51b9113fc926522c40934a3d8ef601785abdf0134eed languageName: node linkType: hard @@ -11201,17 +11218,17 @@ __metadata: languageName: node linkType: hard -"vscode-oniguruma@npm:^1.6.1": +"vscode-oniguruma@npm:^1.7.0": version: 1.7.0 resolution: "vscode-oniguruma@npm:1.7.0" checksum: 53519d91d90593e6fb080260892e87d447e9b200c4964d766772b5053f5699066539d92100f77f1302c91e8fc5d9c772fbe40fe4c90f3d411a96d5a9b1e63f42 languageName: node linkType: hard -"vscode-textmate@npm:^6.0.0": - version: 6.0.0 - resolution: "vscode-textmate@npm:6.0.0" - checksum: ff6f17a406c2906586afc14ef01cb122e33acd35312e815abb5c924347a777c6783ce3fe7db8b83f1760ebf843c669843b9390f905b69c433b3395af28e4b483 +"vscode-textmate@npm:^8.0.0": + version: 8.0.0 + resolution: "vscode-textmate@npm:8.0.0" + checksum: 127780dfea89559d70b8326df6ec344cfd701312dd7f3f591a718693812b7852c30b6715e3cfc8b3200a4e2515b4c96f0843c0eacc0a3020969b5de262c2a4bb languageName: node linkType: hard @@ -11872,6 +11889,7 @@ __metadata: "@wwtelescope/research-app-messages": "workspace:*" concurrently: ^5.2.0 rimraf: ^3 + typedoc-plugin-vue: ^1.1.0 languageName: unknown linkType: soft From c0248cceebe7c9f8a2983ca0866e362f57c101c1 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Sat, 7 Oct 2023 17:36:39 -0400 Subject: [PATCH 08/29] docs/engine/engine-helpers-index.md: polish a bit --- docs/engine/engine-helpers-index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/engine/engine-helpers-index.md b/docs/engine/engine-helpers-index.md index 3eb37cd4..1149d4d1 100644 --- a/docs/engine/engine-helpers-index.md +++ b/docs/engine/engine-helpers-index.md @@ -1,14 +1,14 @@ -More idiomatic wrappers for the [engine](../engine/). +More idiomatic wrappers for the [WWT engine](../engine/). This package provides infrastructure for controlling the WWT engine with your -own JavaScript/TypeScript coe. It’s higher-level than the pure +own JavaScript/TypeScript code. It’s higher-level than the pure [@wwtelescope/engine](../engine/) implementation, but not as sophisticated as -the [@wwtelescope/engine-pinia](../engine-pinia/) package, which depends on -[Vue] and [Pinia]. +the [@wwtelescope/engine-pinia](../engine-pinia/) package, which helps you +include WWT in modern, component-based web applications via the [Vue] and +[Pinia] frameworks. [Vue]: https://vuejs.org/ [Pinia]: https://pinia.vuejs.org/ -Your primary gateway into this package is the -[WWTInstance](./classes/WWTInstance.html) type, which provides an -object-oriented interface for controlling the WWT engine. +Your primary gateway into this package is the {@link WWTInstance} type, which +provides an object-oriented interface for controlling the WWT engine. From 688ea55c3b5ba473a8aab98c63dbf515e1cadb9d Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Sat, 7 Oct 2023 21:11:48 -0400 Subject: [PATCH 09/29] engine-pinia: lots of docs work Including a whole new support module provided by a typedoc developer --- docs/engine/engine-pinia-index.md | 90 +++++-- engine-pinia/src/Component.vue | 11 +- engine-pinia/src/global-state.d.ts | 1 + engine-pinia/src/index.ts | 36 ++- engine-pinia/src/shims-vue.d.ts | 28 +++ engine-pinia/src/store.ts | 225 ++++++++--------- engine-pinia/src/wwtaware.ts | 383 +++++++++++++++++------------ engine-pinia/tsconfig.json | 3 + package.json | 3 +- 9 files changed, 459 insertions(+), 321 deletions(-) diff --git a/docs/engine/engine-pinia-index.md b/docs/engine/engine-pinia-index.md index 561e221b..bcabb419 100644 --- a/docs/engine/engine-pinia-index.md +++ b/docs/engine/engine-pinia-index.md @@ -8,21 +8,72 @@ This package turns the [WorldWide Telescope][wwt] rendering engine, [Pinia]: https://pinia.vuejs.org/ [TypeScript]: https://www.typescriptlang.org/ -The important top-level interfaces are: +Vue and Pinia are systems that provide a slick, modern framework for creating +[component-based] Web applications. This kind of approach requires more +infrastructure than hand-coding HTML and JavaScript, but it allows you to build +large, sophisticated apps in a tractable way — while also making it easy to take +advantage of pre-built, third-party app components. To learn more about these +frameworks, we suggest checking out [the Vue +guide](https://vuejs.org/guide/introduction.html) and then [the Pinia +guide](https://pinia.vuejs.org/core-concepts/). There are many, many other +tutorials for these popular packages around the web as well. -- The [WWTAwareComponent] component defining Vue/Pinia hooks for interfacing with the - engine +[component-based]: https://vuejs.org/guide/essentials/component-basics.html -[createPlugin]: ./globals.html#createplugin -[WWTAwareComponent]: ./classes/wwtawarecomponent.html +This package provides the following building blocks: +- A system that lets you control the WWT engine using the [Pinia] + state-management framework. This integration provides a standardized way for + different pieces of code (say, different components of a web app) to observe + the state of the WWT engine (say, the current coordinates of its view center) + as well as control it (say, trigger a slew to a new location). +- A reusable [Vue] component, {@link WWTComponent}, that contains a WWT view and + links it up to the Pinia system. If you include a {@link WWTComponent} in your + Vue-based web application, you can control it from anywhere else in your + codebase by using Pinia actions like {@link WWTAwareComponent.gotoRADecZoom}. +- Finally, this package also provides a helper called {@link WWTAwareComponent}. + If you are using Vue’s [“options API”][opt-api], you can use it as a base + class for your own Vue components (say, a readout of the current view + coordinates) to gain easy access to the WWT state. Specifically, this base + class provides a full suite of getters and methods that are automagically + wired up to the engine’s Pinia state. In Vue’s [“composition API”][opt-api], + the recommended style is use the Pinia store directly. -# Quick Start +[Vue component]: https://vuejs.org/guide/essentials/component-basics.html +[opt-api]: https://vuejs.org/guide/introduction.html#api-styles -A minimal Vue [single-file-component][sfc] building on this library might look like -this: +The key benefit provided by this whole framework is that it makes it easy to +integrate WWT into a modern, component-based web application. *Any* component +that needs to observe or control the WWT view — not just the one directly +wrapping it — can do so, thanks to Pinia. -[sfc]: https://vuejs.org/v2/guide/single-file-components.html + +# API Overview + +If you‘re constructing a Vue app based on this system, you’ll need to use two +key interfaces: + +- {@link WWTComponent} to include an actual WWT view in your app somewhere +- {@link wwtPinia} to set up the WWT Pinia linkage. + +See the next section for a minimal example of how to do this. You may also find +it convenient to use {@link WWTAwareComponent} as a base class for some of your +components to get pre-wired methods for interacting with the WWT engine Pinia +state. + +Once you have wired things up, you presumably want to know what WWT is doing and +to command it! See [The WWT Pinia +Interface](classes/WWTAwareComponent.html#md:the-wwt-pinia-interface) for an +overview of all the possible ways that your application code can interact with +the WWT engine. + + +# Quick Start for Vue Initiates + +If you’re familiar with Vue, you might want to see what a minimal +[single-file-component][sfc] building on this library would look like: + +[sfc]: https://vuejs.org/guide/scaling-up/sfc.html ```vue