@cosmicds/vue-toolkit 0.2.0 → 0.4.0

package/dist/src/index.d.ts

@@ -1,12 +1,15 @@
-import { KeyboardControlSettings } from "./keyboard";
-import MiniDSBase from "./components/MiniDSBase";
+import { BackgroundImageset, skyBackgroundImagesets } from "./background";
+import { useFullscreen, useWindowShape, WindowShape } from "./composables";
+import { PositionCoords, useGeolocation } from "./geolocation";
+import { KeyPressInfo, KeyboardControlSettings } from "./keyboard";
+import { useWWTKeyboardControls } from "./wwt-utils";
 import IconButton from "./components/IconButton.vue";
 import LocationSelector from "./components/LocationSelector.vue";
-import DefaultMiniCredits from "./components/DefaultMiniCredits.vue";
-import FundingAcknowledgment from "./components/FundingAcknowledgment.vue";
+import FundingAcknowledgement from "./components/FundingAcknowledgement.vue";
 import CreditLogos from "./components/CreditLogos.vue";
-import wwtHUD from "./components/wwtHUD.vue";
-import { BackgroundImageset, skyBackgroundImagesets } from "./background";
+import GeolocationButton from "./components/GeolocationButton.vue";
+import WwtHud from "./components/WwtHud.vue";
 import Gallery from "./components/Gallery.vue";
-import { API_BASE_URL, MINIDS_BASE_URL, R2D, D2R } from "./utils";
-export { BackgroundImageset, KeyboardControlSettings, MiniDSBase, Gallery, IconButton, LocationSelector, skyBackgroundImagesets, DefaultMiniCredits, FundingAcknowledgment, CreditLogos, wwtHUD, API_BASE_URL, MINIDS_BASE_URL, R2D, D2R };
+export { BackgroundImageset, KeyPressInfo, KeyboardControlSettings, Gallery, IconButton, LocationSelector, skyBackgroundImagesets, useFullscreen, useWindowShape, WindowShape, FundingAcknowledgement, CreditLogos, GeolocationButton, WwtHud, PositionCoords, useGeolocation, useWWTKeyboardControls, };
+export * from "./types";
+export * from "./utils";

package/dist/src/keyboard.d.ts

@@ -1,24 +1,52 @@
-declare class KeyPressInfo {
+/** Class representing a key press */
+export declare class KeyPressInfo {
+    /** The code of the key that was pressed */
     code: string;
+    /** Whether the control modifier was pressed */
     ctrl: boolean;
+    /** Whether the alt modifier was pressed */
     alt: boolean;
+    /** Whether the shift modifier was pressed */
     shift: boolean;
+    /** Whether the meta modifier was pressed */
     meta: boolean;
+    /**
+      * Create an instance of key press information
+      * @param code The key code describing the keypress
+      * @param modifiers An object of boolean values describing which modifier keys were pressed down
+      */
     constructor(code: string, modifiers?: {
         ctrl?: boolean;
         alt?: boolean;
         shift?: boolean;
         meta?: boolean;
     });
+    /**
+      * Determine whether a keyboard event matches this key press information
+      * @param event - The keyboard event to test
+      * @returns Whether or not the given event matches
+      */
     matches(event: KeyboardEvent): boolean;
 }
+/** Type describing the possible WWT actions */
+type ActionType = KeyboardControlSettings["actionTypes"][number];
+/**
+  * Class describing keyboard control settings for WorldWide Telescope actions
+  */
 export declare class KeyboardControlSettings {
+    /** A list of key presses that should result in zooming in */
     zoomIn: KeyPressInfo[];
+    /** A list of key presses that should result in zooming out */
     zoomOut: KeyPressInfo[];
+    /** A list of key presses that should result in moving the view up */
     moveUp: KeyPressInfo[];
+    /** A list of key presses that should result in moving the view down */
     moveDown: KeyPressInfo[];
+    /** A list of key presses that should result in moving the view left */
     moveLeft: KeyPressInfo[];
+    /** A list of key presses that should result in moving the view right */
     moveRight: KeyPressInfo[];
+    /** A value describing how much to move on a movement press. Larger means more movement. */
     moveAmount: number;
     constructor({ zoomIn, zoomOut, moveUp, moveLeft, moveDown, moveRight, moveAmount }: {
         zoomIn?: KeyPressInfo[] | undefined;
@@ -30,6 +58,11 @@ export declare class KeyboardControlSettings {
         moveAmount?: number | undefined;
     });
     readonly actionTypes: readonly ["zoomIn", "zoomOut", "moveUp", "moveDown", "moveLeft", "moveRight"];
-    makeListener(actionName: KeyboardControlSettings["actionTypes"][number], action: () => void): (e: KeyboardEvent) => void;
+    /** Make a listener for a given WWT action
+      * @param actionName - The WWT action to make a listener for
+      * @param action - Function to execute when the given WWT action occurs
+      * @returns The key event listener for the desired behavior
+      */
+    makeListener(actionName: ActionType, action: () => void): (event: KeyboardEvent) => void;
 }
 export {};

package/dist/src/mapbox.d.ts

@@ -0,0 +1,98 @@
+/** Interface describing a MapBox content item */
+export interface MapBoxContextItem {
+    id: string;
+    mapbox_id: string;
+    text: string;
+    wikidata: string;
+    short_code?: string;
+}
+export interface MapBoxFeature {
+    place_type: string[];
+    place_name: string;
+    text?: string;
+    properties: {
+        short_code: string;
+    };
+    center: [number, number];
+    context: MapBoxContextItem[];
+}
+/** Interface describing a MapBox feature collection, which is a GeoJSON object */
+export interface MapBoxFeatureCollection {
+    type: "FeatureCollection";
+    /** The list of features in the collection */
+    features: MapBoxFeature[];
+}
+/** Union type describing the feature types available in MapBox */
+export type MapBoxFeatureType = "country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address";
+/** Union type describing the worldviews available in MapBox */
+export type MapBoxWorldviewType = "ar" | "cn" | "in" | "jp" | "ma" | "ru" | "tr" | "us";
+/** Interface describing options common to both forward and reverse MapBox geocoding */
+interface BaseMapBoxGeocodingOptions {
+    /** The language to use for the results, as an IEFT language tag */
+    language?: string;
+    /** The number of results to return. Default is 5 */
+    limit?: number;
+    /** Countries to include in the results. If a list is given, any result outside of these countries is omitted
+      * Specify countries using ISO 3166-1 alpha-2 country codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      */
+    countries?: string[];
+    /** The result types to include */
+    types?: MapBoxFeatureType[];
+    /** The access token for MapBox. Required */
+    access_token: string;
+}
+/** Interface describing options for forward geocoding */
+interface MapBoxForwardGeocodingOptions extends BaseMapBoxGeocodingOptions {
+    /** Whether to return autocomplete results. MapBox default is true */
+    autocomplete?: boolean;
+    /** A bounding box for results. Should be a string of the form "minLon,minLat,maxLon,maxLat" */
+    bbox?: string;
+    /** Whether MapBox should try approximate, as well as exact, matching. MapBox default is true */
+    fuzzyMatch?: boolean;
+    /** If specified, results are biased to favor results closer to this location. Should be a string of the form "longitude, latitude" */
+    proximity?: string;
+}
+/** Interface describing options for reverse geocoding */
+interface MapBoxReverseGeocodingOptions extends BaseMapBoxGeocodingOptions {
+    /** The worldview to use for search results. MapBox default is "us" */
+    worldview?: MapBoxWorldviewType[];
+}
+/** Find the best feature from a collection of MapBox features.
+  * We look for feature place types in the order: 'place', 'postcode', 'region', 'country'
+  * @param collection The collection of items to search
+  * @param relevantTypes The set of feature place types to consider. If not specified, we use the four types mentioned above
+  * @returns The "best" feature, as described above
+  */
+export declare function findBestFeature(collection: MapBoxFeatureCollection, relevantTypes?: MapBoxFeatureType[]): MapBoxFeature | null;
+/**
+  * Create text describing a MapBox feature, based on the MapBox items inside of the feature's context
+  * @param feature The MapBox feature
+  * @param relevantTypes The item types inside the feature's context that we want to consider when creating the string. If not specified, we use 'place', 'postcode', 'region', and 'country'
+  * @returns A string describing the feature
+  */
+export declare function textForMapboxFeature(feature: MapBoxFeature, relevantTypes?: MapBoxFeatureType[]): string;
+/**
+  * Return text describing the "best" feature in a MapBox collection.
+  * See @link{findBestFeature} for a description of how a feature is chosen
+  * @param results The feature collection to use
+  * @param relevantTypes The item types inside the best feature's context that we want to consider when creating the string. If not specified, we use 'place', 'postcode', 'region', and 'country'
+  */
+export declare function textForMapboxResults(results: MapBoxFeatureCollection, relevantTypes?: MapBoxFeatureType[]): string;
+/**
+  * Obtain text describing a given longitude and latitude based on a MapBox reverse geocoding query
+  * @param longitudeDeg The longitude of the location, in degrees
+  * @param latitudeDeg The latitude of the location, in degrees
+  * @param options Options for the MapBox reverse geocoding
+  * @returns A promise that resolves to the string describing the given coordinates
+  */
+export declare function textForLocation(longitudeDeg: number, latitudeDeg: number, options: MapBoxReverseGeocodingOptions): Promise<string>;
+/**
+  * Obtain a collection of MapBox items obtained from performing a forward geocoding query for a particular search string.
+  * Note that the number of items returned is set by the `limit` field in your options.
+  * If `limit` is not specified, the MapBox default is 5
+  * @param searchText The search string
+  * @param options Options for the MapBox forward geocoding
+  * @returns A promise that resolves to the found collection of MapBox items
+  */
+export declare function geocodingInfoForSearch(searchText: string, options: MapBoxForwardGeocodingOptions): Promise<MapBoxFeatureCollection>;
+export {};

package/dist/src/stories/CreditLogos.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { CreditLogos } from "..";
+declare const meta: Meta<typeof CreditLogos>;
+export default meta;
+type Story = StoryObj<typeof CreditLogos>;
+export declare const Primary: Story;

package/dist/src/stories/FundingAcknowledgement.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { FundingAcknowledgement } from "..";
+declare const meta: Meta<typeof FundingAcknowledgement>;
+export default meta;
+type Story = StoryObj<typeof FundingAcknowledgement>;
+export declare const Primary: Story;

package/dist/src/stories/Gallery.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { Gallery } from "..";
+declare const meta: Meta<typeof Gallery>;
+export default meta;
+type Story = StoryObj<typeof Gallery>;
+export declare const Primary: Story;

package/dist/src/stories/IconButton.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { IconButton } from "..";
+declare const meta: Meta<typeof IconButton>;
+export default meta;
+type Story = StoryObj<typeof IconButton>;
+export declare const Primary: Story;

package/dist/src/stories/LocationSelector.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { LocationSelector } from "..";
+declare const meta: Meta<typeof LocationSelector>;
+export default meta;
+type Story = StoryObj<typeof LocationSelector>;
+export declare const Primary: Story;

package/dist/src/stories/WwtHud.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/vue3";
+import { WwtHud } from "..";
+declare const meta: Meta<typeof WwtHud>;
+export default meta;
+type Story = StoryObj<typeof WwtHud>;
+export declare const Primary: Story;

package/dist/src/types.d.ts

@@ -0,0 +1,241 @@
+import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome";
+import { CircleMarkerOptions, TileLayerOptions } from "leaflet";
+import { engineStore } from "@wwtelescope/engine-pinia";
+/** The type of the WWT engine Pinia store */
+export type WWTEngineStore = ReturnType<typeof engineStore>;
+/** Interface describing props for the funding acknowledgement component */
+export interface FundingAcknowledgementProps {
+    /** The color of the acknowledgement text */
+    color?: string;
+    /** The background color of the acknowledgement */
+    backgroundColor?: string;
+}
+/** Interface describing a logo */
+export interface CreditLogo {
+    /** The URL for the logo image */
+    src: string;
+    /** The URL to open when the logo is clicked */
+    href: string;
+    /** Alt text to use for the logo. If none is given, the logo will have no alt text */
+    alt?: string;
+}
+/** A union type enumerating the default credit logos */
+export type DefaultCreditLogo = "cosmicds" | "wwt" | "sciact" | "nasa";
+/** Interface describing props for the credit logos component */
+export interface CreditLogosProps {
+    /** What size to use for the logos. Should be a valid CSS size. */
+    logoSize?: string;
+    /** Any extra logos that we want to use */
+    extraLogos?: CreditLogo[];
+    /** Which default logos to use. If not specified, use them all */
+    defaultLogos: DefaultCreditLogo[];
+}
+/** Interface describing props for the gallery component */
+export interface GalleryProps {
+    /** The URL of a WTML file describing the desired gallery contents. Required */
+    wtmlUrl: string;
+    /** The number of columns of the gallery.
+      * Accepts a number or a valid CSS value to be used in `repeat` for `grid-template-columns`
+      * Defaults to 'auto-fit'
+      */
+    columns?: number | string;
+    /** The width of the gallery. Should be a valid CSS value for `width`. Defaults to 300px */
+    width?: string;
+    /** Maximum height of the gallery. Should be a valid CSS value for `max-height`. Defaults to 500px */
+    maxHeight?: string;
+    /** The title of the gallery. Default is 'Gallery' */
+    title?: string;
+    /** The accent color to use for selected images in the gallery. Should be a valid CSS color. Default is 'dodgerblue' */
+    selectedColor?: string;
+    /** Whether a user can select only one image at a time. Default true */
+    singleSelect?: boolean;
+    /** Whether only the last selected image is highlighted. Default false */
+    highlightLastOnly?: boolean;
+    /** The index of the preview image in the WTML file. Defaults to 0. */
+    previewIndex?: number;
+    /** The text to show when the gallery is closed. Default is 'Image Gallery' */
+    closedText?: string;
+}
+/** A union type consisting of the density options for the geolocation button */
+export type GeolocationButtonDensity = null | "default" | "comfortable" | "compact";
+/** Interface describing props for the geolocation button */
+export interface GeolocationButtonProps {
+    /** The color of the geolocation button. Defaults to "white" */
+    color?: string;
+    /** The size of the button */
+    size?: string;
+    /** The density of the button. This adjusts the vertical height of the button. Defaults to "comfortable" */
+    density?: GeolocationButtonDensity;
+    /** The elevation of the button. Defaults to "2" */
+    elevation?: string;
+    /** Whether to hide the button. Defaults to false */
+    hideButton?: boolean;
+    /** Whether to show the button's text label. Defaults to false */
+    showTextLabel?: boolean;
+    /** Whether to show the button's geolocation coordinates. Defaults to false */
+    showCoords?: boolean;
+    /** Whether to show text indicating when location fetching is in progress. Defaults to false */
+    showTextProgress?: boolean;
+    /** Whether to show circle indicator when fetching is in progress. Defaults to true */
+    showProgressCircle?: boolean;
+    /** Whether to include text on the button. Defaults to false */
+    useTextButton?: boolean;
+    /** The size of the in-progress circle. Defaults to 12 */
+    progressCircleSize?: number;
+    /** The button's label. Defaults to "My Location" */
+    label?: string;
+    /** The ID to use to create the button ID */
+    id?: string;
+    /** The icon to use when the geolocation has been obtained */
+    trueIcon?: string;
+    /** The icon to use when there is no value for the geolocation */
+    falseIcon?: string;
+    /** Whether to show the location and permission status. Useful for debugging, defaults to false */
+    showPermissions?: boolean;
+}
+/**
+  * A type describing the props of a FontAwesome icon
+  * We need to do this because FontAwesome doesn't export the prop types
+  */
+export type FontAwesomeIconProps = InstanceType<typeof FontAwesomeIcon>["$props"];
+/** A type describing the size options for a FontAwesome icon */
+export type SizeType = Extract<FontAwesomeIconProps, 'size'>;
+/** An interface describing props for the icon button */
+export interface IconButtonProps {
+    /** Whether or not the icon button is active. Only makes sense in cases where one wants the button to have an on/off state */
+    modelValue?: boolean;
+    /** The name of the FontAwesome icon to use. It's assumed that only one of this and `mdIcon` will be used */
+    faIcon?: string;
+    /** The name of the MID icon to use. It's assumed that only one of this and `faIcon` will be used */
+    mdIcon?: string;
+    /** The primary color of the button. Sets the icon and border colors. Default is white */
+    color?: string;
+    /** The color of the button when focused. Default is white */
+    focusColor?: string;
+    /** The color of the button when active. Default is white */
+    activeColor?: string;
+    /** The background color of the button. Default is #040404 */
+    backgroundColor?: string;
+    /** Whether the button has a border. Default is true */
+    border?: boolean;
+    /** The time duration, in ms, to recognize a press event as a long press. Default is 500 */
+    longPressTimeMs?: number;
+    /** The tooltip text for the button. If not specified, tooltip will not be shown */
+    tooltipText?: string;
+    /** The location of the tooltip. Default is start */
+    tooltipLocation?: string;
+    /** Whether to show the tooltip when the button is clicked. Default is false */
+    tooltipOnClick?: boolean;
+    /** Whether to show the tooltip when the button is focused. Default is false */
+    tooltipOnFocus?: boolean;
+    /** Whether to show the tooltip when the button is hovered. Default is true */
+    tooltipOnHover?: boolean;
+    /** The distance away from the button that the tooltip appears. Default is 0 */
+    tooltipOffset?: string | number;
+    /** Whether to show the tooltip when appropriate. Default is true */
+    showTooltip?: boolean;
+    /** The size of the FontAwesome icon */
+    faSize?: SizeType;
+    /** The size of the MDI icon. Should be a valid CSS size */
+    mdSize?: string;
+}
+/** An interface describing a latitude/longitude location */
+export interface LocationDeg {
+    /** The longitude of the location, in degrees */
+    longitudeDeg: number;
+    /** The latitude of the location, in degrees */
+    latitudeDeg: number;
+}
+/** An interface describing options for the Leaflet map in the location selector */
+export interface LeafletMapOptions extends TileLayerOptions {
+    /** The template URL to use for the base map layer */
+    templateUrl: string;
+    /** The initial location to center the map on */
+    initialLocation?: LocationDeg;
+    /** The initial zoom level of the map */
+    initialZoom?: number;
+}
+/** An interface describing a GeoJSON item, to be used as a prop for the location selector */
+export interface GeoJSONProp {
+    /** The URL of a remote GeoJSON resource. This and `geojson` and not intended to be used together */
+    url?: string;
+    /** A GeoJSON object to add to the location selector */
+    geojson?: GeoJSON.FeatureCollection | GeoJSON.Feature | GeoJSON.GeometryCollection;
+    /** The style options for any circle markers related to this item. Required */
+    style: CircleMarkerOptions;
+}
+/** Interface describing a place on the location selector */
+export interface PlaceDeg extends LocationDeg {
+    /** The color to use for the circle showing the place */
+    color?: string;
+    /** The fill color to use for the circle showing the place */
+    fillColor?: string;
+    /** The fill opacity to use for the circle showing the place */
+    fillOpacity?: number;
+    /** The radius to use for the circle showing the place */
+    radius?: number;
+    /** The name of the place */
+    name?: string;
+}
+/** Interface describing props for the location selector */
+export interface LocationSelectorProps {
+    /** The color to use for the activator button */
+    activatorColor?: string;
+    /** Whether to attempt to detect the user's location when the component is mounted. Default is true */
+    detectLocation?: boolean;
+    /** The currently selected location. Default is the coordinates for Harvard College Observatory */
+    modelValue?: LocationDeg;
+    /** Map options for the Leaflet map. If not specified, sensible defaults are used */
+    mapOptions?: LeafletMapOptions;
+    /** The initial place to be selected on the map */
+    initialPlace?: PlaceDeg;
+    /** The list of places to show on the map */
+    places?: PlaceDeg[];
+    /** Options for place circles */
+    placeCircleOptions?: CircleMarkerOptions;
+    /** Whether places can be selected on the map. Default is true */
+    placeSelectable?: boolean;
+    /** Whether a location can be selected on the map. Default is true */
+    selectable?: boolean;
+    /** Options for the circle showing the selected place */
+    selectedCircleOptions?: CircleMarkerOptions;
+    /** Which event to use to select a location. Default is "click" */
+    selectionEvent?: "click" | "dblclick";
+    /** Whether to use world radii for circle sizes (as opposed to screen radii). Default is true */
+    worldRadii?: boolean;
+    /** GeoJSON items to display on the map. The list is empty by default */
+    geoJsonFiles?: GeoJSONProp[];
+    /** Layers to show on the map. The list is empty by default */
+    layers?: L.Layer[];
+}
+/** Interface describing the location of the WWT HUD */
+export interface HUDLocation {
+    /** Distance from the top. Should be a valid CSS value */
+    top?: string | number;
+    /** Distance from the left. Should be a valid CSS value */
+    left?: string | number;
+    /** Distance from the bottom. Should be a valid CSS value */
+    bottom?: string | number;
+    /** Distance from the right. Should be a valid CSS value */
+    right?: string | number;
+}
+/** Interface describing props for the WWT HUD */
+export interface WwtHUDProps {
+    /** Location of the HUD in the browser window. Default is `{ top: "50%", left: "50%" }` */
+    location?: HUDLocation;
+    /** Define an offset for the HUD. Default is `{ x: 0.5, y: 0.5 }` */
+    offsetCenter?: {
+        x: number;
+        y: number;
+    };
+    /** Other variables to include in the HUD display. Default is `{}` */
+    otherVariables?: Object;
+    /** The font size of the HUD text. Should be a valid CSS value for `font-size` */
+    fontSize?: string;
+    /** Background color for the HUD. Should be a valid CSS color. Default is `rgba(0, 0, 0, 0.5)` */
+    backgroundColor?: string | null;
+    /** Text shadow for the HUD text. Should be a valid CSS value for `text-shadow`. Default is `"0 0 5px black"` */
+    textShadow?: string | null;
+    /** The WWT engine store to use for the HUD. Required */
+    store: ReturnType<typeof engineStore>;
+}

package/dist/src/utils.d.ts

@@ -1,4 +1,30 @@
+/** Degrees -> radians conversion factor */
 export declare const D2R: number;
+/** Radians -> degrees conversion factor */
 export declare const R2D: number;
+/** The base URL for the CosmicDS API server */
 export declare const API_BASE_URL = "https://api.cosmicds.cfa.harvard.edu";
-export declare const MINIDS_BASE_URL: string;
+/**
+  * Determine whether the user's device supports touch events.
+  *
+  * @returns Whether touch events are supported
+  */
+export declare function supportsTouchscreen(): boolean;
+/**
+  * Determine whether a given user agent string describes a mobile device.
+  * This is done via a regex match against common user agent string pieces.
+  *
+  * @returns Whether the user agent string describes a mobile device
+  */
+export declare function isMobile(userAgent: string): boolean;
+/** Blur the current active element, if there is one */
+export declare function blurActiveElement(): void;
+/**
+  * Filter an array in place (as opposed to .filter, which creates a new array).
+  * Modified from https://stackoverflow.com/a/37319954
+  *
+  * @param array - The array to filter
+  * @param condition - The filtering condition. Elements for which this returns true are retained
+  * @template T
+  */
+export declare function filterInPlace<T>(array: T[], condition: (t: T) => boolean): void;

package/dist/src/wwt-utils.d.ts

@@ -0,0 +1,11 @@
+import { engineStore } from "@wwtelescope/engine-pinia";
+import { KeyboardControlSettings } from "./keyboard";
+type WWTEngineStore = ReturnType<typeof engineStore>;
+/**
+  * A composable that sets up WWT keyboard controls.
+  * @param store The WWT engine's Pinia store
+  * @param element The element on which to attach the keyboard listeners. Uses the browser window if none is given
+  * @returns The `KeyboardControlSettings` instance that was used to create the listeners
+  */
+export declare function useWWTKeyboardControls(store: WWTEngineStore, element?: Window | HTMLElement): KeyboardControlSettings;
+export {};