@aics/vole-app 3.4.4 → 3.5.0

package/type-declarations/aics-image-viewer/shared/utils/controlPointsToLut.d.ts

@@ -35,7 +35,7 @@ export declare function getDefaultLut(histogram: Histogram): Lut;
  * "autoij:0" // use Auto-IJ to calculate min and max.
  * ```
  */
-export declare function parseLutSetting(histogram: Histogram, lutSetting: [string, string] | undefined): Lut | undefined;
+export declare function parseLutSetting(histogram: Histogram, lutSetting: [string | number, string | number] | undefined): Lut | undefined;
 /**
  * Initializes the lookup table (LUT) that maps from volume intensity values to color + opacity and applies the LUT to the volume.
  *

package/type-declarations/aics-image-viewer/shared/utils/parseSnapshot.d.ts

@@ -0,0 +1,47 @@
+import type { MultisceneUrls } from "../../components/App/types";
+import type { ChannelState, ChannelStateSnapshot, ViewerStateSnapshot } from "../../state/types";
+import type { MetadataRecord } from "../types";
+import type { ViewerChannelSettings } from "./viewerChannelSettings";
+/**
+ * A message sent from an external application after this app was opened,
+ * containing data that was too large to pack into the URL.
+ */
+export type ViewerMessage = {
+    /** A (possibly very long) list of scene URLs. */
+    scenes?: (string | string[])[];
+    /** A (likely very large) list of metadata records for each scene. */
+    meta?: Record<string, MetadataRecord>;
+    /** The scene to open once this message arrives. */
+    sceneIndex?: number;
+};
+/** A snapshot of app state, containing (optional) global and per-channel settings. */
+export type StoreSnapshot = ViewerStateSnapshot & {
+    version: string;
+    channels: Record<string, ChannelStateSnapshot>;
+};
+/**
+ * A complete description of a viewer session, containing image URLs, global
+ * and per-channel settings, and optional image metadata.
+ */
+export type SessionSnapshot = StoreSnapshot & ViewerMessage & Required<Pick<ViewerMessage, "scenes">>;
+/** Verifies that the given object is (likely) a `StoreSnapshot`. */
+export declare const isStoreSnapshot: (settings: unknown) => settings is StoreSnapshot;
+/** Verifies that the given object is (likely) a `SessionSnapshot`. */
+export declare const isSessionSnapshot: (settings: unknown) => settings is SessionSnapshot;
+/** Converts an array of `ChannelState`s to a compact JSON representation that can be stringified into the clipboard. */
+export declare const channelStatesToSnapshot: (channelStates: ChannelState[], excludeKeys?: (keyof ChannelState)[]) => StoreSnapshot;
+/** Converts a compacted set of `ChannelState`s from the clipboard into a record of channel names and their states. */
+export declare const snapshotToChannelStates: (serialized: StoreSnapshot) => Record<string, Partial<ChannelState>>;
+export declare const snapshotToViewerChannelSettings: (serialized: StoreSnapshot) => ViewerChannelSettings | undefined;
+/**
+ * Parses a `ViewerMessage` into the relevant entries in `AppProps`.
+ *
+ * Optionally accepts the current value of the `imageUrl` prop, for the case where the message contains only metadata
+ * and the image URLs that correspond to the metadata were passed in by other means.
+ */
+export declare function viewerMessageToParams(message: ViewerMessage, propUrl?: string | MultisceneUrls): {
+    imageUrl?: string | MultisceneUrls;
+    metadata?: (MetadataRecord | undefined)[];
+};
+/** Formats the values of the `imageUrl` and `metadata` props to `App` as a `ViewerMessage`. */
+export declare function paramsToViewerMessage(imageUrl: string | MultisceneUrls, metadata?: (MetadataRecord | undefined)[]): ViewerMessage;

package/type-declarations/aics-image-viewer/shared/utils/{urlParsing.d.ts → parseUrl.d.ts}

@@ -1,7 +1,7 @@
 import type { FirebaseFirestore } from "@firebase/firestore-types";
 import type { AppProps } from "../../components/App/types";
 import type { ViewerStore } from "../../state/store";
-import { type ViewerState, ViewerStateParams } from "../../state/types";
+import type { ViewerState, ViewerStateStringified } from "../../state/types";
 import type { MetadataRecord } from "../types";
 /**
  * Channels, matching the pattern `c0`, `c1`, etc. corresponding to the index of the channel being configured.
@@ -60,19 +60,7 @@ declare class DeprecatedParams {
     /** Deprecated query parameter for channel colors. */
     colors?: string;
 }
-type AppParams = Partial<ViewerStateParams & DataParams & DeprecatedParams & ChannelParams>;
-/**
- * A message sent from an external application after this app was opened,
- * containing data that was too large to pack into the URL.
- */
-type ViewerMessage = {
-    /** A (possibly very long) list of scene URLs. */
-    scenes?: string[];
-    /** A (likely very large) list of metadata records for each scene. */
-    meta?: Record<string, MetadataRecord>;
-    /** The scene to open once this message arrives. */
-    sceneIndex?: number;
-};
+type AppParams = Partial<ViewerStateStringified & DataParams & DeprecatedParams & ChannelParams>;
 /**
  * Filters a set of URLSearchParams for only the keys that are valid parameters for the viewer.
  * Non-matching keys are discarded.
@@ -101,8 +89,6 @@ export declare function parseViewerUrlParams(search: string, firestore?: Firebas
     args: Partial<AppProps>;
     viewerSettings: Partial<ViewerState>;
 }>;
-/** Adds the data in a newly-arrived `ViewerMessage` to an existing stored `AppProps` instance. */
-export declare function addViewerParamsFromMessage<P extends Pick<AppProps, "imageUrl" | "metadata">>(args: P, message: ViewerMessage): P;
 /**
  * Serializes the ViewerState and ChannelState of a ViewerStateContext into a URLSearchParams object.
  * @param state ViewerStateContext to serialize.

package/type-declarations/aics-image-viewer/shared/utils/permissions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Try to determine whether attempting to access the clipboard will immediately fail.
+ *
+ * When this function returns `false`, accessing the clipboard *may* be successful, though some browsers require users
+ * to confirm every paste. When it returns `true`, access to the clipboard is definitely blocked.
+ */
+export declare const queryPasteDenied: () => Promise<boolean>;

package/type-declarations/aics-image-viewer/shared/utils/viewerChannelSettings.d.ts

@@ -21,7 +21,7 @@ export type IntensitySettings = {
      * - `autoij` in either the min or max fields will use the "auto" algorithm
      * from ImageJ to select the min and max.
      */
-    lut?: [string, string];
+    lut?: [string | number, string | number];
 };
 /** Settings for a single channel, as passed in via props by App users */
 export interface ViewerChannelSetting {

package/type-declarations/aics-image-viewer/state/deserialize.d.ts

@@ -1,7 +1,7 @@
 import type { Histogram } from "@aics/vole-core";
 import type { ColorArray } from "../shared/utils/colorRepresentations";
 import type { ViewerChannelSetting } from "../shared/utils/viewerChannelSettings";
-import { type ChannelState, type ViewerChannelStateParams, type ViewerState, type ViewerStateParams } from "./types";
+import type { CameraStateSnapshot, CameraStateStringified, ChannelState, ChannelStateSnapshot, ChannelStateStringified, ViewerState, ViewerStateSnapshot, ViewerStateStringified } from "./types";
 /**
  * LEGACY: Matches a COMMA-separated list of control points, where each control point is represented
  * by a triplet of `{x}:{opacity}:{hex color}`.
@@ -19,6 +19,22 @@ export declare const LEGACY_CONTROL_POINTS_REGEX: RegExp;
  *   with `1` to represent white (`ffffff`).
  */
 export declare const CONTROL_POINTS_REGEX: RegExp;
+export declare const enumParser: <E extends string>(enumValues: Record<string, E>) => ((value: string) => E | undefined);
+/**
+ * Converts a `CameraStateStringified` into a `CameraStateSnapshot` by parsing each key from its stringified
+ * representation to its type in `CameraStateSnapshot`.
+ */
+export declare const destringifyCameraStateSnapshot: (stringified: CameraStateStringified) => CameraStateSnapshot;
+/**
+ * Converts a `ViewerStateStringified` into a `ViewerStateSnapshot` by parsing each key from its stringified
+ * representation to its type in `ViewerStateSnapshot`.
+ */
+export declare const destringifyViewerStateSnapshot: (stringified: ViewerStateStringified) => ViewerStateSnapshot;
+/**
+ * Converts a `ChannelStateStringified` into a `ChannelStateSnapshot` by parsing each key from its stringified
+ * representation to its type in `ChannelStateSnapshot`.
+ */
+export declare const destringifyChannelStateSnapshot: (stringified: ChannelStateStringified) => ChannelStateSnapshot;
 /**
  * Parse a string list of comma-separated key:value pairs into
  * a key-value object.
@@ -30,50 +46,68 @@ export declare const CONTROL_POINTS_REGEX: RegExp;
  *  will be decoded using `decodeURIComponent`.
  */
 export declare function parseKeyValueList(data: string): Record<string, string>;
+export declare function parseHexColorAsColorArray(hexColor: unknown): ColorArray | undefined;
+/** Verifies that `value` is a `number`; if it is, clamps it between `min` and `max`. */
+export declare const validateNumber: (value: unknown, min?: number, max?: number) => number | undefined;
+/** Verifies that `value` is a `number`; if it is, truncates it to an integer and clamps it between `min` and `max`. */
+export declare const validateInt: (value: unknown, min?: number, max?: number) => number | undefined;
+type Untrusted<T> = {
+    [K in keyof T]?: unknown;
+};
+/** Parses a `ViewerStateSnapshot` to a `ViewerState`. */
+export declare function snapshotToViewerState(snapshot: Untrusted<ViewerStateSnapshot>): Partial<ViewerState>;
 /**
- * Parses a string to a float and clamps the result to the [min, max] range.
- * Returns `undefined` if the string is undefined or NaN.
- * @param value String to parse as a float. Will be parsed with `Number.parseFloat`.
- * @param min Minimum value, inclusive.
- * @param max Maximum value, inclusive.
- * @returns
- * - The parsed number, clamped to the [min, max] range.
- * - `undefined` if the string is undefined or NaN.
+ * Parses a `ChannelStateSnapshot` to a `ViewerChannelSetting`.
+ * @param channelId Either the index or the name of the channel, to be turned into a `match` value.
+ * @param jsonState The serialized `ViewerChannelSetting` to parse, as an object.
+ * @returns A `ViewerChannelSetting` object.
  */
-export declare function parseStringFloat(value: string | undefined, min: number, max: number): number | undefined;
+export declare function snapshotToViewerChannelSetting(channelId: number | string, jsonState: Untrusted<ChannelStateSnapshot>): ViewerChannelSetting;
 /**
- * Parses a string to an integer and clamps the result to the [min, max] range.
- * @param value String to parse as a float. Assumes base 10, parses with `Number.parseInt(value, 10)`.
- * @param min Minimum value, inclusive.
- * @param max Maximum value, inclusive.
- * @returns
- * - The parsed number, clamped to the [min, max] range.
- * - `undefined` if the string is undefined or NaN.
+ * Parses a `ChannelStateSnapshot` object into a partial `ChannelState`.
+ *
+ * This is used to convert from serialized formats (URL params, JSON) into
+ * internal channel state fields, leaving absent or invalid values undefined.
+ *
+ * This function optionally accepts the target channel's `Histogram`. This
+ * argument is required to parse the following params correctly:
+ *
+ * - `lut`, which contains instructions for how to set the channel's
+ *   intensities *relative to its intensity distribution*.
+ * - `rmp`, the legacy ramp parameter represented as histogram bin indices
+ * - `cps`, the legacy control points parameter where `x` values are
+ *   represented as histogram bin indices
+ *
+ * If `histogram` is left undefined, e.g. because the channel has not yet been
+ * loaded, these params are ignored.
  */
-export declare function parseStringInt(value: string | undefined, min: number, max: number): number | undefined;
+export declare function snapshotToChannelState(jsonState: Untrusted<ChannelStateSnapshot>, histogram?: Histogram): Partial<ChannelState>;
 /**
- * Parses a string to an enum value; if the string is not in the enum, returns the default value.
- * @param value String to parse.
- * @param enumValues Enum. Cannot be a `const enum`, as these are removed at compile time.
- * @param defaultValue Default value to return if the string is not in the enum.
- * @returns A value from the enum or the default value. Note that the return type includes `undefined`
- * if the `defaultValue` is `undefined`.
+ * Parses a stringified viewer state snapshot (`ViewerStateStringified`) to a
+ * `ViewerState`.
+ *
+ * This is equivalent to (and implemented by) calling
+ * `destringifyViewerStateSnapshot`, then `snapshotToViewerState`.
  */
-export declare function parseStringEnum<E extends string, T extends E | undefined>(value: string | undefined, enumValues: Record<string | number | symbol, E>, defaultValue?: T): T;
-export declare function parseHexColorAsColorArray(hexColor: string | undefined): ColorArray | undefined;
-export declare function deserializeViewerState(params: ViewerStateParams): Partial<ViewerState>;
+export declare const stringSnapshotToViewerState: (stringified: ViewerStateStringified) => Partial<ViewerState>;
 /**
- * Parses a ViewerChannelSetting from a JSON object.
+ * Parses a stringified channel state snapshot (`ChannelStateStringified`) to a
+ * `ViewerChannelSetting`.
+ *
+ * This is equivalent to (and implemented by) calling
+ * `destringifyChannelStateSnapshot`, then `snapshotToViewerChannelSetting`.
+ *
  * @param channelIndex Index of the channel, to be turned into a `match` value.
- * @param jsonState The serialized ViewerChannelSetting to parse, as an object.
- * @returns A ViewerChannelSetting object.
+ * @param jsonState The serialized `ViewerChannelSetting` to parse, as an object.
+ * @returns A `ViewerChannelSetting` object.
  */
-export declare function deserializeViewerChannelSetting(channelIndex: number, jsonState: ViewerChannelStateParams): ViewerChannelSetting;
+export declare const stringSnapshotToViewerChannelSetting: (channelIndex: number, jsonState: ChannelStateStringified) => ViewerChannelSetting;
 /**
- * Parses a `ViewerChannelStateParams` object into a partial `ChannelState`.
+ * Parses a stringified channel state snapshot (`ChannelStateStringified`)
+ * into a partial `ChannelState`.
  *
- * This is used to convert raw URL params into internal channel state fields,
- * leaving absent or invalid values undefined.
+ * This is equivalent to (and implemented by) calling
+ * `destringifyChannelStateSnapshot`, then `snapshotToChannelState`.
  *
  * This function optionally accepts the target channel's `Histogram`. This
  * argument is required to parse the following params correctly:
@@ -87,4 +121,5 @@ export declare function deserializeViewerChannelSetting(channelIndex: number, js
  * If `histogram` is left undefined, e.g. because the channel has not yet been
  * loaded, these params are ignored.
  */
-export declare function deserializeChannelState(jsonState: ViewerChannelStateParams, histogram?: Histogram): Partial<ChannelState>;
+export declare const stringSnapshotToChannelState: (jsonState: ChannelStateStringified, histogram?: Histogram) => Partial<ChannelState>;
+export {};

package/type-declarations/aics-image-viewer/state/reset.d.ts

@@ -1,7 +1,7 @@
 import type { StateCreator } from "zustand";
 import type { ViewerChannelSettings } from "../shared/utils/viewerChannelSettings";
-import type { ViewerState } from "../state/types";
 import type { ViewerStore } from "./store";
+import { type ViewerState } from "./types";
 export type ResetStateActions = {
     /**
      * Removes the channel from the list of channels to be reset (as given by

package/type-declarations/aics-image-viewer/state/serialize.d.ts

@@ -1,20 +1,54 @@
 import type { CameraState } from "@aics/vole-core";
-import { ViewMode } from "../shared/enums";
-import type { ChannelState, ViewerChannelStateParams, ViewerState, ViewerStateParams } from "./types";
+import type { CameraStateSnapshot, CameraStateStringified, ChannelState, ChannelStateSnapshot, ChannelStateStringified, ViewerState, ViewerStateSnapshot, ViewerStateStringified } from "./types";
+import { ViewMode } from "./types";
+/**
+ * Serializes an object with `string` keys to a compact `string` representation, where keys and values are separated
+ * by colons (`:`) and entries are separated by commas (`,`).
+ */
 export declare function objectToKeyValueList(obj: Record<string, string | undefined>): string;
-export declare function serializeCameraState(cameraState: Partial<CameraState>, removeDefaults: boolean, viewMode?: ViewMode): string | undefined;
 /**
- * Serializes a single viewer channel setting into a dictionary of URL parameters
- * (`ViewerChannelStateParams`).
+ * Converts a `CameraState` to a `CameraStateSnapshot`, suitable for serialization.
+ * @param cameraState The camera state to serialize.
+ * @param removeDefaults Whether to remove default values.
+ * @param viewMode The current view mode. Default `ViewMode.threeD`.
+ * @returns The resulting `CameraStateSnapshot`, or `undefined` if all values are default.
+ */
+export declare function cameraStateToSnapshot(cameraState: Partial<CameraState> | undefined, removeDefaults: boolean, viewMode?: ViewMode): CameraStateSnapshot | undefined;
+/**
+ * Converts a `ViewerState` to a `ViewerStateSnapshot`, suitable for serialization.
+ */
+export declare function viewerStateToSnapshot(state: Partial<ViewerState>, removeDefaults: boolean): ViewerStateSnapshot;
+export declare function channelStateToSnapshot(state: Partial<ChannelState>, removeDefaults: boolean): ChannelStateSnapshot;
+/**
+ * Converts all keys of a `CameraStateSnapshot` to compact `string` representations,
+ * for serialization to `string` formats.
+ */
+export declare const stringifyCameraStateSnapshot: (snapshot: CameraStateSnapshot) => CameraStateStringified;
+/**
+ * Converts all keys of a `ViewerStateSnapshot` to compact `string` representations,
+ * for serialization to `string` formats.
+ */
+export declare const stringifyViewerStateSnapshot: (snapshot: ViewerStateSnapshot) => ViewerStateStringified;
+/**
+ * Converts all keys of a `ChannelStateSnapshot` to compact `string` representations,
+ * for serialization to `string` formats.
+ */
+export declare const stringifyChannelStateSnapshot: (snapshot: ChannelStateSnapshot) => ChannelStateStringified;
+/**
+ * Converts a single viewer channel setting into a `ChannelStateStringified`.
+ *
+ * This is equivalent to (and implemented by) applying `channelStateToSnapshot`, then `stringifyChannelStateSnapshot`.
  * @param channelSetting The channel state object to serialize.
  * @param removeDefaults Whether to remove properties that match the output of `getDefaultChannelState`.
- * @returns A `ViewerChannelSettingParams` object with the serialized parameters. Undefined values are removed.
+ * @returns A `ChannelStateStringified` object with the serialized parameters. `undefined` values are removed.
  */
-export declare function serializeViewerChannelSetting(channelSetting: Partial<ChannelState>, removeDefaults: boolean): Partial<ViewerChannelStateParams>;
+export declare const channelStateToStringSnapshot: (channelSetting: Partial<ChannelState>, removeDefaults: boolean) => ChannelStateStringified;
 /**
- * Serializes a `ViewerState` object into a dictionary of URL parameters.
+ * Serializes a `ViewerState` object into a `ViewerStateStringified`.
+ *
+ * This is equivalent to (and implemented by) applying `viewerStateToSnapshot`, then `stringifyViewerStateSnapshot`.
  * @param state The `ViewerState` to serialize.
  * @param removeDefaults If true, remove properties that match the output of `getDefaultViewerState`.
- * @returns A `ViewerStateParams` object with the serialized parameters. Undefined values are removed.
+ * @returns A `ViewerStateStringified` object with the serialized parameters. `undefined` values are removed.
  */
-export declare function serializeViewerState(state: Partial<ViewerState>, removeDefaults: boolean): ViewerStateParams;
+export declare const viewerStateToStringSnapshot: (state: Partial<ViewerState>, removeDefaults: boolean) => ViewerStateStringified;