@cosmicds/vue-toolkit 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicds/vue-toolkit",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "browser": "dist/index.umd.js",
   "dependencies": {
     "@capacitor/core": "^5.7.4",
@@ -17,21 +17,44 @@
     "vuetify": "^3.3.3"
   },
   "devDependencies": {
+    "@chromatic-com/storybook": "^1.3.3",
+    "@storybook/addon-essentials": "^8.0.9",
+    "@storybook/addon-interactions": "^8.0.9",
+    "@storybook/addon-links": "^8.0.9",
+    "@storybook/addon-webpack5-compiler-swc": "^1.0.2",
+    "@storybook/blocks": "^8.0.9",
+    "@storybook/test": "^8.0.9",
+    "@storybook/vue3": "^8.0.9",
+    "@storybook/vue3-webpack5": "^8.0.9",
     "@types/leaflet": "^1.9.11",
     "@typescript-eslint/eslint-plugin": "^6.19.0",
     "@typescript-eslint/parser": "^6.19.0",
     "@vue/cli-plugin-eslint": "^5.0.8",
     "@vue/cli-plugin-typescript": "^5.0.8",
     "@vue/cli-service": "^5.0.8",
+    "@vue/compiler-sfc": "^3.4.25",
     "@vue/eslint-config-typescript": "^12.0.0",
     "copy-webpack-plugin": "^12.0.2",
+    "css-loader": "^7.1.1",
     "eslint": "^8.31.0",
+    "eslint-plugin-storybook": "^0.8.0",
     "eslint-plugin-vue": "^9.8.0",
     "less": "^4.2.0",
     "less-loader": "^12.1.0",
+    "markdown-loader": "^8.0.0",
+    "pug": "^3.0.3",
+    "storybook": "^8.0.9",
+    "storybook-css-modules-preset": "^1.1.1",
+    "storybook-dark-mode": "^4.0.1",
+    "style-loader": "^4.0.0",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typedoc-plugin-vue": "^1.1.0",
     "typescript": "^4.9.4",
+    "vue-loader": "^17.4.2",
     "vue-template-compiler": "^2.7.14",
-    "webpack": "^5.75.0"
+    "webpack": "^5.75.0",
+    "webpack-dev-middleware": "^5.3.4"
   },
   "files": [
     "dist/*",
@@ -46,7 +69,10 @@
   "scripts": {
     "build": "vue-cli-service build --target lib --name index src/index.ts",
     "clean": "rimraf dist",
-    "lint": "vue-cli-service lint src --no-fix"
+    "docs": "typedoc --plugin typedoc-plugin-markdown",
+    "lint": "vue-cli-service lint src --no-fix",
+    "storybook": "storybook dev -p 6006 --debug",
+    "build-storybook": "storybook build -o docs"
   },
   "types": "./dist/src/index.d.ts"
 }

package/src/background.ts

@@ -1,5 +1,8 @@
+/** Class representing a background imageset for WorldWide Telescope */
 export class BackgroundImageset {
+  /** The outward-facing name to use for the imageset in a story */
   public imagesetName: string;
+  /** The name of the imageset object inside WorldWide Telescope */
   public displayName: string;
 
   constructor(displayName: string, imagesetName: string) {
@@ -8,6 +11,7 @@ export class BackgroundImageset {
   }
 }
 
+/** A default list of `BackgroundImagset` objects to use within data stories */
 export const skyBackgroundImagesets: BackgroundImageset[] = [
   new BackgroundImageset(
     "Optical (Terapixel DSS)",

package/src/composables.ts

@@ -1,6 +1,10 @@
 import { ref, onMounted, onUnmounted, Ref } from "vue";
 import screenfull from "screenfull";
 
+/**
+  * A composable that encapsulates fullscreen behavior.
+  * @returns A reactive variable indicating whether or not fullscreen mode is active
+  */ 
 export function useFullscreen(): Ref<boolean> {
   const fullscreenModeActive = ref(false);
   function update(_event: Event) {
@@ -22,11 +26,20 @@ export function useFullscreen(): Ref<boolean> {
   return fullscreenModeActive;
 }
 
+/** Interface describing the shape of a browser window */
 export interface WindowShape {
   width: number;
   height: number;
 }
+
+/** A default `WindowShape` to use */
 export const defaultWindowShape = { width: 1200, height: 900 };
+
+/**
+  * A composable that encapsulates a changing window shape.
+  *
+  * @returns A reactive variable describing the current window shape.
+  */
 export function useWindowShape() {
   const windowShape = ref<WindowShape>(defaultWindowShape);
   const resizeObserver = new ResizeObserver(_entries => update());
@@ -51,6 +64,6 @@ export function useWindowShape() {
     resizeObserver.unobserve(document.body);
   });
 
-  return { windowShape, resizeObserver };
+  return windowShape;
 }
 

package/src/geolocation.ts

@@ -2,6 +2,11 @@ import { ref, onMounted } from "vue";
 import { Capacitor, PermissionState as CapacitorPermissionState } from '@capacitor/core';
 import { Geolocation, PermissionStatus as CapacitorPermissionStatus, Position, PositionOptions } from "@capacitor/geolocation";
 
+/**
+  * Determine which of two capacitor permission states is 'better'.
+  * This implementation takes "prompt-with-rationale" to be better than "prompt".
+  * @returns The 'better' of the two input permission states
+  */
 function betterPermissionState(firstState: CapacitorPermissionState, secondState: CapacitorPermissionState): CapacitorPermissionState {
   const states: CapacitorPermissionState[] = ["granted", "prompt-with-rationale", "prompt", "denied"];
   for (const state of states) {
@@ -13,6 +18,13 @@ function betterPermissionState(firstState: CapacitorPermissionState, secondState
 }
 
 export type PositionCoords = Position['coords'];
+
+/**
+  * A composable that encapsulates the current state of the browser
+  * geolocation position and permission status.
+  * @param onStartup - Whether or not to query the user's geolocation on startup.
+  * @returns Reactive state describing the geolocation
+  */
 export function useGeolocation(onStartup=true) {
 
   const geolocation = ref<PositionCoords | null>(null);

package/src/index.ts

@@ -1,7 +1,7 @@
 import { BackgroundImageset, skyBackgroundImagesets } from "./background";
 import { useFullscreen, useWindowShape, WindowShape } from "./composables";
 import { PositionCoords, useGeolocation } from "./geolocation";
-import { KeyboardControlSettings } from "./keyboard";
+import { KeyPressInfo, KeyboardControlSettings } from "./keyboard";
 import { useWWTKeyboardControls } from "./wwt-utils";
 
 import IconButton from "./components/IconButton.vue";
@@ -15,6 +15,7 @@ import Gallery from "./components/Gallery.vue";
 
 export {
   BackgroundImageset,
+  KeyPressInfo,
   KeyboardControlSettings,
   Gallery,
   IconButton,

package/src/keyboard.ts

@@ -1,10 +1,21 @@
-class KeyPressInfo {
+/** Class representing a key press */
+export 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?: {
@@ -21,6 +32,11 @@ class KeyPressInfo {
     this.meta = modifiers?.meta ?? false;
   }
 
+  /**
+    * 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 {
     return (
       event.code === this.code &&
@@ -32,13 +48,26 @@ class KeyPressInfo {
   }
 }
 
+/** Type describing the possible WWT actions */
+type ActionType = KeyboardControlSettings["actionTypes"][number];
+
+/**
+  * Class describing keyboard control settings for WorldWide Telescope actions
+  */
 export 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({
@@ -69,8 +98,13 @@ export class KeyboardControlSettings {
     "moveRight",
   ] as const;
   
+  /** 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: KeyboardControlSettings["actionTypes"][number],
+    actionName: ActionType,
     action: () => void
   ): (event: KeyboardEvent) => void {
     return (event) => {

package/src/mapbox.ts

@@ -1,3 +1,4 @@
+/** Interface describing a MapBox content item */
 export interface MapBoxContextItem {
   id: string;
   // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -21,44 +22,65 @@ export interface MapBoxFeature {
   context: MapBoxContextItem[];
 }
 
+/** Interface describing a MapBox feature collection, which is a GeoJSON object */
 export interface MapBoxFeatureCollection {
+  /* The type of the collection */
   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";
 
-// For countries, use the ISO 3166-1 alpha-2 country codes:
-// https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+/** Interface describing options common to both forward and reverse MapBox geocoding */
 interface BaseMapBoxGeocodingOptions {
-  permanent?: boolean;
+  /** 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[];
 
-  // MapBox API access token
+  /** The access token for MapBox. Required */
   // eslint-disable-next-line @typescript-eslint/naming-convention
   access_token: string;
 }
 
+/** Interface describing options for forward geocoding */
 interface MapBoxForwardGeocodingOptions extends BaseMapBoxGeocodingOptions {
+  /** Whether to return autocomplete results. MapBox default is true */
   autocomplete?: boolean;
-  bbox?: number;
-  format?: "geojson" | "v5";
+  /** 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[];
 }
 
+/** Interface describing geocoding query parameters that are adjusted from the options exposed by our methods */
 interface MapBoxAdjustedGeocodingParams {
-  countries?: string;
+  /** We take in a string of country codes, but MapBox wants a comma-separated list */
+  country?: string;
+  /** We take in a list of types, but MapBox wants a comma-separated list */
   types?: string;
  }
 
+/** A type describing the query parameter type corresponding to one of our option types */
 type MapBoxQueryOptions<T extends BaseMapBoxGeocodingOptions> = {
   [K in keyof Omit<T, "countries" | "types">]: T[K];
 } & MapBoxAdjustedGeocodingParams;
@@ -67,6 +89,12 @@ const DEFAULT_RELEVANT_FEATURE_TYPES = ["postcode", "place", "region", "country"
 const NA_COUNTRIES = ["United States", "Canada", "Mexico"];
 const NA_ABBREVIATIONS = ["US-", "CA-", "MX-"];
 
+/** 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 function findBestFeature(collection: MapBoxFeatureCollection, relevantTypes?: MapBoxFeatureType[]): MapBoxFeature | null {
   const types = relevantTypes ?? DEFAULT_RELEVANT_FEATURE_TYPES;
   const relevantFeatures = collection.features.filter(feature => types.some(type => feature.place_type.includes(type)));
@@ -85,6 +113,12 @@ export function findBestFeature(collection: MapBoxFeatureCollection, relevantTyp
   return 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 function textForMapboxFeature(feature: MapBoxFeature, relevantTypes?: MapBoxFeatureType[]): string {
   const types = relevantTypes ?? DEFAULT_RELEVANT_FEATURE_TYPES;
   const pieces: string[] = [];
@@ -115,21 +149,38 @@ export function textForMapboxFeature(feature: MapBoxFeature, relevantTypes?: Map
   return pieces.join(", ");
 }
 
+/**
+  * 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 function textForMapboxResults(results: MapBoxFeatureCollection, relevantTypes?: MapBoxFeatureType[]): string {
   const feature = findBestFeature(results, relevantTypes);
   return feature !== null ? textForMapboxFeature(feature) : "";
 }
 
+/**
+  * Convert our MapBox options to options suitable for a query to the MapBox API
+  * @param options The toolkit MapBox options
+  * @returns The options converted into a suitable object to use for a MapBox API query
+  * @template T extends @link{BaseMapBoxGeocodingOptions}
+  */
 function convertOptionsToQueryParams<T extends BaseMapBoxGeocodingOptions>(options: T): MapBoxQueryOptions<T> {
   const { types, countries, ...params } = options;
   const queryParams = params as MapBoxQueryOptions<T>;
   queryParams.types = (types ?? ["place", "postcode"]).join(",");
   if (countries) {
-    queryParams.countries = countries.join(",");
+    queryParams.country = countries.join(",");
   }
   return queryParams;
 }
 
+/**
+  * Convert a set of MapBox geocoding options to URL search parameters
+  * @param options The MapBox geocoding options
+  * @returns A `URLSearchParams` object that can be used for a MapBox query
+  */
 function searchParams(options: MapBoxForwardGeocodingOptions | MapBoxReverseGeocodingOptions): URLSearchParams {
   const search = new URLSearchParams();
   const queryParams = convertOptionsToQueryParams(options);
@@ -137,6 +188,13 @@ function searchParams(options: MapBoxForwardGeocodingOptions | MapBoxReverseGeoc
   return search;
 }
 
+/**
+  * 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 async function textForLocation(longitudeDeg: number, latitudeDeg: number, options: MapBoxReverseGeocodingOptions): Promise<string> {
   const search = searchParams(options);
   const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${longitudeDeg},${latitudeDeg}.json?${search.toString()}`;
@@ -154,6 +212,14 @@ export async function textForLocation(longitudeDeg: number, latitudeDeg: number,
     });
 }
 
+/**
+  * 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 async function geocodingInfoForSearch(searchText: string, options: MapBoxForwardGeocodingOptions): Promise<MapBoxFeatureCollection> {
   const search = searchParams(options);
   const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${searchText}.json?${search.toString()}`;