@tissuumaps/core 0.1.0-beta.0 → 0.1.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tissuumaps/core
 
+## 0.1.0-beta.1
+
+### Minor Changes
+
+- [#259](https://github.com/TissUUmaps/TissUUmaps/pull/259) [`62b79c2`](https://github.com/TissUUmaps/TissUUmaps/commit/62b79c2218ea5419972553b43cc217084d9a9d23) Thanks [@cavenel](https://github.com/cavenel)! - Plugins can show the settings of an image, labels, points or shapes: `appStore.getState().showImageSettings(imageId)` brings the Images panel to the front and expands the image's settings, and `showLabelsSettings`, `showPointsSettings` and `showShapesSettings` do the same for the other panels. Adds these actions and the `imageSettingsRequest`, `labelsSettingsRequest`, `pointsSettingsRequest` and `shapesSettingsRequest` app store state.
+
+- [#253](https://github.com/TissUUmaps/TissUUmaps/pull/253) [`8acd194`](https://github.com/TissUUmaps/TissUUmaps/commit/8acd1946245c89c961af2857e13ae373bc256d62) Thanks [@jwindhager](https://github.com/jwindhager)! - `TableData.loadUniqueValueCounts` and `TableData.loadValueRange` are now optional: table data only implements them if it can determine the counts or the range more cheaply than by loading the column (e.g. from file metadata). Callers use the new `TableUtils.loadUniqueValueCounts` and `TableUtils.loadValueRange`, which fall back to the loaded column values (see `TableUtils.computeValueRange`). CSV tables no longer implement either method, and Parquet and hierarchical (AnnData) tables no longer implement `loadUniqueValueCounts`. Unless the table data determines them itself, the app now computes unique value counts and value ranges from the column values it has already loaded, instead of loading the column again.
+
+- [#253](https://github.com/TissUUmaps/TissUUmaps/pull/253) [`8acd194`](https://github.com/TissUUmaps/TissUUmaps/commit/8acd1946245c89c961af2857e13ae373bc256d62) Thanks [@jwindhager](https://github.com/jwindhager)! - Group-by palettes (colors and markers without a map) now assign their values by group position, in the order the groups first appear in the table column, instead of by hashing the group names; random colors are still hashed. Projects that group by a palette show different colors or markers than before. `ConfigUtils.createGroupValueGetter` takes the ordered groups alongside the palette, and the new `TableUtils.loadGroupCounts` lists them.
+
+- [#252](https://github.com/TissUUmaps/TissUUmaps/pull/252) [`cb49f75`](https://github.com/TissUUmaps/TissUUmaps/commit/cb49f75bb87c17d06198562d53e4ab17cd89aaf5) Thanks [@jwindhager](https://github.com/jwindhager)! - Plugins are no longer mounted when registered: a menu in the tab bar lists the registered plugins and mounts the one picked, and closing a plugin's panel only unmounts it. The menu can also load third-party plugins, ES modules whose default export is the plugin, from a local file or a URL, absolute or relative to the page. Third-party plugins should both default-export the plugin and register it through `window.tissuumaps`, so that the same file can be loaded through the menu or included in the page. Adds `PluginRegistry.mountPlugin`/`unmountPlugin`.
+
 ## 0.1.0-beta.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -97,6 +97,34 @@ export declare type AppStoreActions = {
      * none
      */
     setHighlightedItemGroup: (highlightedItemGroup: HighlightedItemGroup | null) => void;
+    /**
+     * Shows the settings of an image: the Images panel is brought to the front
+     * and the settings are expanded
+     *
+     * @param imageId - ID of the image whose settings to show
+     */
+    showImageSettings: (imageId: string) => void;
+    /**
+     * Shows the settings of labels: the Labels panel is brought to the front
+     * and the settings are expanded
+     *
+     * @param labelsId - ID of the labels whose settings to show
+     */
+    showLabelsSettings: (labelsId: string) => void;
+    /**
+     * Shows the settings of points: the Points panel is brought to the front
+     * and the settings are expanded
+     *
+     * @param pointsId - ID of the points whose settings to show
+     */
+    showPointsSettings: (pointsId: string) => void;
+    /**
+     * Shows the settings of shapes: the Shapes panel is brought to the front
+     * and the settings are expanded
+     *
+     * @param shapesId - ID of the shapes whose settings to show
+     */
+    showShapesSettings: (shapesId: string) => void;
     /**
      * Registers an image data provider
      *
@@ -172,8 +200,9 @@ export declare type AppStoreState = {
     /** The registered table data providers, by data source type */
     tableDataProviders: Map<string, TableDataProvider<TableDataSource, TableData>>;
     /**
-     * The registered plugins, by plugin ID, each as its human-readable name
-     * together with the element its user interface is mounted into, if it has one
+     * The registered plugins, by plugin ID, each as its human-readable name,
+     * whether it has a user interface that can be mounted, and the element its
+     * user interface is mounted into while it is mounted
      *
      * Written by the plugin registry, which owns the plugin lifecycle and keeps
      * the plugin objects themselves to itself, so that nothing a plugin owns ends
@@ -181,8 +210,49 @@ export declare type AppStoreState = {
      */
     plugins: Map<string, {
         name: string;
+        mountable: boolean;
         container?: HTMLElement;
     }>;
+    /**
+     * The latest request to show the settings of an image, or `null` if there has
+     * been none
+     *
+     * Set by {@link AppStoreActions.showImageSettings} to a new object on every call, so
+     * that a repeated request for the same image is a change too.
+     */
+    imageSettingsRequest: {
+        imageId: string;
+    } | null;
+    /**
+     * The latest request to show the settings of labels, or `null` if there has
+     * been none
+     *
+     * Set by {@link AppStoreActions.showLabelsSettings} to a new object on every call, so
+     * that a repeated request for the same labels is a change too.
+     */
+    labelsSettingsRequest: {
+        labelsId: string;
+    } | null;
+    /**
+     * The latest request to show the settings of points, or `null` if there has
+     * been none
+     *
+     * Set by {@link AppStoreActions.showPointsSettings} to a new object on every call, so
+     * that a repeated request for the same points is a change too.
+     */
+    pointsSettingsRequest: {
+        pointsId: string;
+    } | null;
+    /**
+     * The latest request to show the settings of shapes, or `null` if there has
+     * been none
+     *
+     * Set by {@link AppStoreActions.showShapesSettings} to a new object on every call, so
+     * that a repeated request for the same shapes is a change too.
+     */
+    shapesSettingsRequest: {
+        shapesId: string;
+    } | null;
 };
 
 /**
@@ -384,7 +454,8 @@ export declare type ColorConfig = ConstantConfig<Color> | FromConfig<{
     palette: string;
 }> | GroupByConfig<false, {
     /**
-     * ID of the color palette for mapping hashed group names to colors
+     * ID of the color palette whose colors are assigned to the groups in the
+     * order they first appear in the table column
      *
      * Only used when no project-global colormap is specified
      */
@@ -561,18 +632,22 @@ export declare class ConfigUtils {
      *
      * With a map, a group takes its value in the map, else the map's default,
      * else `defaultValue`; a map that does not exist gives every group
-     * `defaultValue`. Without a map, a group takes the palette value its name
-     * hashes to, or `defaultValue` if there is no palette.
+     * `defaultValue`. Without a map, the groups take the palette values in
+     * order, cycling through the palette if there are more groups than values;
+     * a group that is not listed, or every group if there is no palette, takes
+     * `defaultValue`.
      *
      * @param config - The group-by configuration
      * @param map - The map the configuration refers to (see
      * {@link findGroupByMap}), or `undefined` if it refers to none or the map
      * does not exist
      * @param defaultValue - The value of a group that nothing assigns one to
-     * @param palette - The values to pick from by hash if there is no map
+     * @param palette - The values to assign to the groups if there is no map
+     * @param groups - All groups of the column the configuration groups by, in
+     * the order they take the palette values (see `TableUtils.loadGroupCounts`)
      * @returns The value of a group, by group name (the cell value as a string)
      */
-    static createGroupValueGetter<TValue>(config: GroupByConfig<false>, map: GroupValueMap<TValue> | undefined, defaultValue: TValue, palette?: readonly TValue[]): (group: string) => TValue;
+    static createGroupValueGetter<TValue>(config: GroupByConfig<false>, map: GroupValueMap<TValue> | undefined, defaultValue: TValue, palette?: readonly TValue[], groups?: Iterable<string>): (group: string) => TValue;
     /**
      * Returns the table column a configuration groups by
      *
@@ -2243,9 +2318,12 @@ export declare type Path = Vertex[];
  * A plugin that can be registered with the application
  *
  * A plugin's lifecycle is `setup`, `mount`, `unmount`, `teardown`: registering
- * the plugin calls {@link setup} and then {@link mount}, and unregistering it
- * calls the callback returned by `mount` and then the callback returned by
- * `setup`. All four steps are optional.
+ * the plugin calls {@link setup}; mounting it, which happens when the user opens
+ * it, calls {@link mount}; unmounting it, which happens when the user closes its
+ * panel, calls the callback returned by `mount`; and unregistering it unmounts
+ * it if it is mounted and then calls the callback returned by `setup`. A plugin
+ * can be mounted and unmounted any number of times while it is registered. All
+ * four steps are optional.
  */
 declare type Plugin_2 = {
     /** The unique ID of the plugin */
@@ -2255,7 +2333,7 @@ declare type Plugin_2 = {
     /**
      * Sets up the plugin and registers any necessary event listeners or other resources
      *
-     * Called first when the plugin is registered. A plugin whose `setup` throws is
+     * Called once when the plugin is registered. A plugin whose `setup` throws is
      * not registered, and the teardown callback is not called: releasing whatever
      * `setup` had already acquired before it throws is `setup`'s own
      * responsibility.
@@ -2273,48 +2351,68 @@ declare type Plugin_2 = {
     /**
      * Mounts the plugin's user interface, if any
      *
-     * A plugin with a `mount` is shown as a panel titled with the plugin's
-     * {@link name}, for exactly as long as the plugin is registered. Closing the
-     * panel unregisters the plugin; a plugin without a `mount` can only be
-     * unregistered through the registry.
+     * A plugin with a `mount` can be opened by the user, which mounts it and shows
+     * it as a panel titled with the plugin's {@link name}. Closing the panel
+     * unmounts the plugin again, but keeps it registered, so that it can be opened
+     * again later.
      *
-     * Called once {@link setup} has returned successfully, with an empty element
-     * owned by the application. The element is not part of the document yet: the
+     * Called each time the plugin is mounted, with a fresh, empty element owned by
+     * the application. The element is not part of the document yet: the
      * application attaches it to the panel once that is shown, and keeps the user
      * interface mounted while the panel is hidden behind other tabs or moved.
-     * A plugin whose `mount` throws is not registered, and the teardown callback
-     * returned by `setup` is called.
+     * A plugin whose `mount` throws is not mounted, but stays registered.
      *
-     * The container is discarded together with the plugin, so the returned
+     * The container is discarded when the plugin is unmounted, so the returned
      * callback only has to release what is not plain DOM, such as store
      * subscriptions, listeners on `window`, or a React root.
      *
      * @param container - The element to mount the user interface into
      * @param stores - The stores provided by the application for the plugin to interact with
      * @returns An unmount callback that unmounts the user interface again, if
-     * any. It is called first when the plugin is unregistered, before the
-     * teardown callback returned by {@link setup}.
+     * any. It is called when the plugin is unmounted, which also happens first
+     * when a mounted plugin is unregistered, before the teardown callback
+     * returned by {@link setup}.
      */
     mount?: (container: HTMLElement, stores: PluginStores) => (() => void) | void;
 };
 export { Plugin_2 as Plugin }
 
 /**
- * The registry through which the application registers and unregisters plugins
+ * The registry through which the application registers, mounts, unmounts and
+ * unregisters plugins
  */
 export declare type PluginRegistry = {
     /**
-     * Registers a plugin, calling its `setup` and then its `mount`, if it has them
+     * Registers a plugin, calling its `setup`, if it has one
      *
-     * Registering a plugin whose ID is already in use unregisters the previously
-     * registered plugin first.
+     * The plugin is not mounted: that is up to the user, or to
+     * {@link mountPlugin}. Registering a plugin whose ID is already in use
+     * unregisters the previously registered plugin first.
      *
      * @param plugin - The plugin to register
      */
     registerPlugin: (plugin: Plugin_2) => void;
     /**
-     * Unregisters a registered plugin, calling the unmount callback returned by
-     * its `mount` and then the teardown callback returned by its `setup`
+     * Mounts a registered plugin, calling its `mount` and showing its panel
+     *
+     * Does nothing if the plugin is not registered, has no `mount`, or is already
+     * mounted.
+     *
+     * @param pluginId - The ID of the plugin to mount
+     */
+    mountPlugin: (pluginId: string) => void;
+    /**
+     * Unmounts a mounted plugin, removing its panel and calling the unmount
+     * callback returned by its `mount`
+     *
+     * The plugin stays registered. Does nothing if the plugin is not mounted.
+     *
+     * @param pluginId - The ID of the plugin to unmount
+     */
+    unmountPlugin: (pluginId: string) => void;
+    /**
+     * Unregisters a registered plugin, unmounting it if it is mounted and then
+     * calling the teardown callback returned by its `setup`
      *
      * @param pluginId - The ID of the plugin to unregister
      */
@@ -4199,24 +4297,32 @@ export declare interface TableData extends ItemsData {
     /**
      * Loads the number of rows per unique value of a column
      *
+     * Only implemented by table data that can count the values more cheaply
+     * than by loading the column (e.g. from file metadata); otherwise, callers
+     * count the values loaded by {@link loadValues}.
+     *
      * @typeParam T - Element type of the column
      * @param column - The column name
      * @param options - Optional abort signal and progress callback
      * @returns The row count of every unique column value, keyed by value, in the
      * order the values first appear
      */
-    loadUniqueValueCounts<T>(column: string, options?: {
+    loadUniqueValueCounts?<T>(column: string, options?: {
         signal?: AbortSignal;
         onProgress?: ProgressCallback;
     }): Promise<Map<T, number>>;
     /**
      * Loads a column's minimum and maximum values
      *
+     * Only implemented by table data that can determine the range more cheaply
+     * than by loading the column (e.g. from file metadata); otherwise, callers
+     * compute the range of the values loaded by {@link loadValues}.
+     *
      * @param column - The column name
      * @param options - Optional abort signal and progress callback
      * @returns The numeric [min, max] value range of the column, or `undefined` if not numeric
      */
-    loadValueRange(column: string, options?: {
+    loadValueRange?(column: string, options?: {
         signal?: AbortSignal;
         onProgress?: ProgressCallback;
     }): Promise<[number, number] | undefined>;
@@ -4274,7 +4380,8 @@ export declare const tableDefaults: {};
  * {@link fillFromTableGroups} fill a typed array with one packed value per
  * item from a table column, one by parsing the cell values and one by mapping
  * their distinct values as groups. IDs that the table does not contain fall
- * back to a default value, with a warning.
+ * back to a default value, with a warning. {@link loadGroupCounts} lists the
+ * groups of a column, for all rows rather than per item.
  */
 export declare class TableUtils {
     /**
@@ -4332,6 +4439,67 @@ export declare class TableUtils {
     static fillFromTableGroups<TValue>(packedValues: TypedArray, tableData: TableData, ids: IDArray, column: string, defaultValue: TValue, mapGroupToValue: (group: string) => TValue, packValue: (value: TValue) => number, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /**
+     * Loads the range of a table column's numeric values
+     *
+     * Uses the table's own value range if it provides one, and otherwise
+     * computes the range of the loaded column values (see
+     * {@link computeValueRange}).
+     *
+     * @param tableData - The table to load the value range of
+     * @param column - Name of the table column
+     * @param options - Optional abort signal and progress callback
+     * @returns The column's minimum and maximum value, or `undefined` if the
+     * column is not numeric
+     */
+    static loadValueRange(tableData: TableData, column: string, options?: {
+        signal?: AbortSignal;
+        onProgress?: ProgressCallback;
+    }): Promise<[number, number] | undefined>;
+    /**
+     * Computes the range of loaded table column values
+     *
+     * @param values - The column values
+     * @param options - Optional abort signal
+     * @returns The minimum and maximum value, or `undefined` if the values are
+     * not numeric or hold no two distinct finite values
+     */
+    static computeValueRange(values: TypedArrayOrArray<unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<[number, number] | undefined>;
+    /**
+     * Loads how many rows of a table each group of a column holds
+     *
+     * Groups are the cell values as strings, as {@link fillFromTableGroups} and
+     * group-to-value maps key them, so values with the same string (e.g. `null`
+     * and `"null"`) form one group.
+     *
+     * @param tableData - The table to load the groups of
+     * @param column - Name of the table column to group by
+     * @param options - Optional abort signal
+     * @returns The row count of every group, in the order the groups first
+     * appear in the column
+     */
+    static loadGroupCounts(tableData: TableData, column: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Map<string, number>>;
+    /**
+     * Loads the number of rows per unique value of a table column
+     *
+     * Uses the table's own counts if it provides them, and otherwise counts the
+     * loaded column values (see `MathUtils.computeUniqueValueCounts`).
+     *
+     * @typeParam T - Element type of the column
+     * @param tableData - The table to load the unique value counts of
+     * @param column - Name of the table column
+     * @param options - Optional abort signal and progress callback
+     * @returns The row count of every unique column value, keyed by value, in the
+     * order the values first appear
+     */
+    static loadUniqueValueCounts<T>(tableData: TableData, column: string, options?: {
+        signal?: AbortSignal;
+        onProgress?: ProgressCallback;
+    }): Promise<Map<T, number>>;
     /**
      * Calls `callback` for every ID with the index of the table row holding that ID
      *

package/dist/index.js

@@ -1697,26 +1697,32 @@ var ConfigUtils = class ConfigUtils {
 	*
 	* With a map, a group takes its value in the map, else the map's default,
 	* else `defaultValue`; a map that does not exist gives every group
-	* `defaultValue`. Without a map, a group takes the palette value its name
-	* hashes to, or `defaultValue` if there is no palette.
+	* `defaultValue`. Without a map, the groups take the palette values in
+	* order, cycling through the palette if there are more groups than values;
+	* a group that is not listed, or every group if there is no palette, takes
+	* `defaultValue`.
 	*
 	* @param config - The group-by configuration
 	* @param map - The map the configuration refers to (see
 	* {@link findGroupByMap}), or `undefined` if it refers to none or the map
 	* does not exist
 	* @param defaultValue - The value of a group that nothing assigns one to
-	* @param palette - The values to pick from by hash if there is no map
+	* @param palette - The values to assign to the groups if there is no map
+	* @param groups - All groups of the column the configuration groups by, in
+	* the order they take the palette values (see `TableUtils.loadGroupCounts`)
 	* @returns The value of a group, by group name (the cell value as a string)
 	*/
-	static createGroupValueGetter(config, map, defaultValue, palette) {
+	static createGroupValueGetter(config, map, defaultValue, palette, groups) {
 		if (config.groupBy.map !== void 0) {
 			if (map === void 0) return () => defaultValue;
 			const values = new Map(Object.entries(map.values));
 			const mapDefault = map.default ?? defaultValue;
 			return (group) => values.get(group) ?? mapDefault;
 		}
-		if (palette === void 0 || palette.length === 0) return () => defaultValue;
-		return (group) => palette[HashUtils.hash(group) % palette.length];
+		if (palette === void 0 || palette.length === 0 || groups === void 0) return () => defaultValue;
+		const paletteValues = /* @__PURE__ */ new Map();
+		for (const group of groups) if (!paletteValues.has(group)) paletteValues.set(group, palette[paletteValues.size % palette.length]);
+		return (group) => paletteValues.get(group) ?? defaultValue;
 	}
 	/**
 	* Returns the table column a configuration groups by
@@ -2683,7 +2689,8 @@ var SourceUtils = class SourceUtils {
 * {@link fillFromTableGroups} fill a typed array with one packed value per
 * item from a table column, one by parsing the cell values and one by mapping
 * their distinct values as groups. IDs that the table does not contain fall
-* back to a default value, with a warning.
+* back to a default value, with a warning. {@link loadGroupCounts} lists the
+* groups of a column, for all rows rather than per item.
 */
 var TableUtils = class TableUtils {
 	/**
@@ -2777,6 +2784,81 @@ var TableUtils = class TableUtils {
 		if (numMissingIds > 0) console.warn(`${numMissingIds} IDs missing in column ${column}, using default value`);
 	}
 	/**
+	* Loads the range of a table column's numeric values
+	*
+	* Uses the table's own value range if it provides one, and otherwise
+	* computes the range of the loaded column values (see
+	* {@link computeValueRange}).
+	*
+	* @param tableData - The table to load the value range of
+	* @param column - Name of the table column
+	* @param options - Optional abort signal and progress callback
+	* @returns The column's minimum and maximum value, or `undefined` if the
+	* column is not numeric
+	*/
+	static async loadValueRange(tableData, column, options) {
+		if (tableData.loadValueRange !== void 0) return await tableData.loadValueRange(column, options);
+		const values = await tableData.loadValues(column, options);
+		return await TableUtils.computeValueRange(values, options);
+	}
+	/**
+	* Computes the range of loaded table column values
+	*
+	* @param values - The column values
+	* @param options - Optional abort signal
+	* @returns The minimum and maximum value, or `undefined` if the values are
+	* not numeric or hold no two distinct finite values
+	*/
+	static async computeValueRange(values, options) {
+		const { signal } = options ?? {};
+		signal?.throwIfAborted();
+		if (!ArrayBuffer.isView(values)) return;
+		const [vmin, vmax] = await MathUtils.computeRange(values, { signal });
+		return vmin < vmax ? [vmin, vmax] : void 0;
+	}
+	/**
+	* Loads how many rows of a table each group of a column holds
+	*
+	* Groups are the cell values as strings, as {@link fillFromTableGroups} and
+	* group-to-value maps key them, so values with the same string (e.g. `null`
+	* and `"null"`) form one group.
+	*
+	* @param tableData - The table to load the groups of
+	* @param column - Name of the table column to group by
+	* @param options - Optional abort signal
+	* @returns The row count of every group, in the order the groups first
+	* appear in the column
+	*/
+	static async loadGroupCounts(tableData, column, options) {
+		const { signal } = options ?? {};
+		signal?.throwIfAborted();
+		const uniqueValueCounts = await TableUtils.loadUniqueValueCounts(tableData, column, { signal });
+		const groupCounts = /* @__PURE__ */ new Map();
+		for (const [value, count] of uniqueValueCounts) {
+			const group = String(value);
+			groupCounts.set(group, (groupCounts.get(group) ?? 0) + count);
+		}
+		return groupCounts;
+	}
+	/**
+	* Loads the number of rows per unique value of a table column
+	*
+	* Uses the table's own counts if it provides them, and otherwise counts the
+	* loaded column values (see `MathUtils.computeUniqueValueCounts`).
+	*
+	* @typeParam T - Element type of the column
+	* @param tableData - The table to load the unique value counts of
+	* @param column - Name of the table column
+	* @param options - Optional abort signal and progress callback
+	* @returns The row count of every unique column value, keyed by value, in the
+	* order the values first appear
+	*/
+	static async loadUniqueValueCounts(tableData, column, options) {
+		if (tableData.loadUniqueValueCounts !== void 0) return await tableData.loadUniqueValueCounts(column, options);
+		const values = await tableData.loadValues(column, options);
+		return await MathUtils.computeUniqueValueCounts(values, options);
+	}
+	/**
 	* Calls `callback` for every ID with the index of the table row holding that ID
 	*
 	* If `ids` is the table's own ID array, the ID at position `i` is held by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tissuumaps/core",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Core model, types and utilities shared by the TissUUmaps packages",
   "homepage": "https://tissuumaps.github.io/TissUUmaps/",
   "bugs": "https://github.com/TissUUmaps/TissUUmaps/issues",