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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @tissuumaps/core
 
+## 0.1.0-beta.3
+
+### Minor Changes
+
+- [#302](https://github.com/TissUUmaps/TissUUmaps/pull/302) [`a422564`](https://github.com/TissUUmaps/TissUUmaps/commit/a4225640dd4be545727210c11e5c12d3d81d650a) Thanks [@jwindhager](https://github.com/jwindhager)! - Data providers gain the optional `supports`, `readName` and `prepareDataSource` methods, and `SourceUtils` gains `getPathSegments`, `getStem`, `getExtension` and `makeProjectPath`.
+
+  Breaking: data provider UI schemas no longer contain the `source` control, which the app now renders itself.
+
+- [#300](https://github.com/TissUUmaps/TissUUmaps/pull/300) [`9fc85a9`](https://github.com/TissUUmaps/TissUUmaps/commit/9fc85a9148be339aa0e419620253f03aace7041a) Thanks [@jwindhager](https://github.com/jwindhager)! - The app store tracks the active panel (`activePanelId`) and the expanded objects of each panel (`expandedImageIds` etc.).
+
+  Breaking: `showImageSettings` etc. and the `imageSettingsRequest` etc. state are removed. Plugins call `setExpandedImageIds` etc. and `setActivePanelId` instead.
+
+### Patch Changes
+
+- [#307](https://github.com/TissUUmaps/TissUUmaps/pull/307) [`16e181e`](https://github.com/TissUUmaps/TissUUmaps/commit/16e181efd919f11a54b259c7e96231b724e628dd) Thanks [@jwindhager](https://github.com/jwindhager)! - Documentation links point to the new TissUUmaps website at https://tissuumaps.github.io/: the app's Docs link, and the packages' READMEs and homepages.
+
+## 0.1.0-beta.2
+
+### Minor Changes
+
+- [#296](https://github.com/TissUUmaps/TissUUmaps/pull/296) [`15a214a`](https://github.com/TissUUmaps/TissUUmaps/commit/15a214a7950a1e9aa605ca5445cc4273b826ca2d) Thanks [@jwindhager](https://github.com/jwindhager)! - `immer` is declared as an optional peer dependency ([#277](https://github.com/TissUUmaps/TissUUmaps/issues/277)), since the store types depend on it through `zustand/immer`.
+
 ## 0.1.0-beta.1
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,6 @@ stores and the data provider interfaces) silently degrade to `any` when
 
 ## Documentation
 
-- [API reference](https://tissuumaps.github.io/TissUUmaps/docs/docs/api/@tissuumaps/core/)
-- [Data model](https://tissuumaps.github.io/TissUUmaps/docs/docs/concepts/data-model/)
-- [Code architecture](https://tissuumaps.github.io/TissUUmaps/docs/docs/development/code-architecture/)
+- [API reference](https://tissuumaps.github.io/docs/api/@tissuumaps/core/)
+- [Data model](https://tissuumaps.github.io/docs/concepts/data-model/)
+- [Code architecture](https://tissuumaps.github.io/docs/development/code-architecture/)

package/dist/index.d.ts

@@ -98,33 +98,46 @@ export declare type AppStoreActions = {
      */
     setHighlightedItemGroup: (highlightedItemGroup: HighlightedItemGroup | null) => void;
     /**
-     * Shows the settings of an image: the Images panel is brought to the front
-     * and the settings are expanded
+     * Makes a panel the active panel, bringing its tab to the front
      *
-     * @param imageId - ID of the image whose settings to show
+     * An ID that does not identify a panel of the layout, e.g. that of the viewer
+     * or of a plugin that is not mounted, is reverted, leaving the layout
+     * unchanged.
+     *
+     * @param activePanelId - The ID of the panel, see
+     * {@link AppStoreState.activePanelId}
+     */
+    setActivePanelId: (activePanelId: string) => void;
+    /**
+     * Sets the images whose entries are expanded in the Images panel
+     *
+     * @param expandedImageIds - The IDs of the images, in any order
      */
-    showImageSettings: (imageId: string) => void;
+    setExpandedImageIds: (expandedImageIds: string[]) => void;
     /**
-     * Shows the settings of labels: the Labels panel is brought to the front
-     * and the settings are expanded
+     * Sets the labels whose entries are expanded in the Labels panel
      *
-     * @param labelsId - ID of the labels whose settings to show
+     * @param expandedLabelsIds - The IDs of the labels, in any order
      */
-    showLabelsSettings: (labelsId: string) => void;
+    setExpandedLabelsIds: (expandedLabelsIds: string[]) => void;
     /**
-     * Shows the settings of points: the Points panel is brought to the front
-     * and the settings are expanded
+     * Sets the points whose entries are expanded in the Points panel
      *
-     * @param pointsId - ID of the points whose settings to show
+     * @param expandedPointsIds - The IDs of the points, in any order
      */
-    showPointsSettings: (pointsId: string) => void;
+    setExpandedPointsIds: (expandedPointsIds: string[]) => void;
     /**
-     * Shows the settings of shapes: the Shapes panel is brought to the front
-     * and the settings are expanded
+     * Sets the shapes whose entries are expanded in the Shapes panel
      *
-     * @param shapesId - ID of the shapes whose settings to show
+     * @param expandedShapesIds - The IDs of the shapes, in any order
      */
-    showShapesSettings: (shapesId: string) => void;
+    setExpandedShapesIds: (expandedShapesIds: string[]) => void;
+    /**
+     * Sets the tables whose entries are expanded in the Tables panel
+     *
+     * @param expandedTableIds - The IDs of the tables, in any order
+     */
+    setExpandedTableIds: (expandedTableIds: string[]) => void;
     /**
      * Registers an image data provider
      *
@@ -214,45 +227,45 @@ export declare type AppStoreState = {
         container?: HTMLElement;
     }>;
     /**
-     * The latest request to show the settings of an image, or `null` if there has
-     * been none
+     * The ID of the active panel, i.e. the panel whose tab was selected last
      *
-     * 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.
+     * Either the ID of a built-in panel or that of a mounted plugin's panel, as
+     * listed in the plugin documentation. Kept in sync with the panel layout in
+     * both directions: selecting a tab sets it, and setting it brings that
+     * panel's tab to the front and activates its group. The viewer has no tab and
+     * is never the active panel, so focusing it leaves this unchanged.
      */
-    imageSettingsRequest: {
-        imageId: string;
-    } | null;
+    activePanelId: string;
     /**
-     * The latest request to show the settings of labels, or `null` if there has
-     * been none
+     * The IDs of the images whose entries are expanded in the Images panel
      *
-     * 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.
+     * Cleared whenever another project is loaded or the project is closed.
      */
-    labelsSettingsRequest: {
-        labelsId: string;
-    } | null;
+    expandedImageIds: string[];
     /**
-     * The latest request to show the settings of points, or `null` if there has
-     * been none
+     * The IDs of the labels whose entries are expanded in the Labels panel
      *
-     * 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.
+     * Cleared whenever another project is loaded or the project is closed.
      */
-    pointsSettingsRequest: {
-        pointsId: string;
-    } | null;
+    expandedLabelsIds: string[];
     /**
-     * The latest request to show the settings of shapes, or `null` if there has
-     * been none
+     * The IDs of the points whose entries are expanded in the Points panel
      *
-     * 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.
+     * Cleared whenever another project is loaded or the project is closed.
      */
-    shapesSettingsRequest: {
-        shapesId: string;
-    } | null;
+    expandedPointsIds: string[];
+    /**
+     * The IDs of the shapes whose entries are expanded in the Shapes panel
+     *
+     * Cleared whenever another project is loaded or the project is closed.
+     */
+    expandedShapesIds: string[];
+    /**
+     * The IDs of the tables whose entries are expanded in the Tables panel
+     *
+     * Cleared whenever another project is loaded or the project is closed.
+     */
+    expandedTableIds: string[];
 };
 
 /**
@@ -907,7 +920,12 @@ export declare interface DataProvider<TDataSource extends DataSource, TData exte
     readonly name: string;
     /** The JSON schema for the data source */
     readonly schema: JsonSchema;
-    /** The JSON Forms UI schema for the data source */
+    /**
+     * The JSON Forms UI schema for the data source
+     *
+     * It must not contain a control for the data source's `source`, which the
+     * application renders itself if the schema declares it, as a string.
+     */
     readonly uischema: UISchemaElement;
     /**
      * Returns the data source with all of this data provider's defaults applied
@@ -935,6 +953,60 @@ export declare interface DataProvider<TDataSource extends DataSource, TData exte
      * @returns The normalized data source
      */
     normalize(dataSource: TDataSource, workspace: FileSystemDirectoryHandle | null, projectSource: string | null): TNormalizedDataSource;
+    /**
+     * Returns whether this data provider can likely open a source
+     *
+     * Used to pick a data provider for a source the user entered or dropped,
+     * e.g. by its file extension or by cheaply reading its metadata. A data
+     * provider without this method is never picked automatically, but can
+     * still be chosen by the user. Callers treat a rejection as `false`.
+     *
+     * @param normalizedSource - The source, normalized with
+     * `SourceUtils.normalizeSource` like {@link DataProvider.normalize} does
+     * @param workspace - The directory handle of the open workspace, if any
+     * @param options - Optional abort signal
+     * @returns A promise that resolves to whether the source is supported
+     */
+    supports?(normalizedSource: string, workspace: FileSystemDirectoryHandle | null, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /**
+     * Reads the name a source stores in its metadata
+     *
+     * Used to name data objects added from a source the user entered or
+     * dropped. Only names stored in the source are returned, never names
+     * derived from the source itself, such as from its path. Without this
+     * method, or if it resolves to `undefined`, callers derive the name from the
+     * file name. Callers treat a rejection like `undefined`.
+     *
+     * @param normalizedSource - The source, normalized with
+     * `SourceUtils.normalizeSource` like {@link DataProvider.normalize} does
+     * @param workspace - The directory handle of the open workspace, if any
+     * @param options - Optional abort signal
+     * @returns A promise that resolves to the name, if any
+     */
+    readName?(normalizedSource: string, workspace: FileSystemDirectoryHandle | null, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    /**
+     * Prepares a data source before a data object backed by it is added, or
+     * before it is saved with a changed source or type
+     *
+     * Called once per added data object, with the data source the user entered,
+     * and once per saved edit that changes the data source's `source` or `type`.
+     * May create the data objects the data source depends on, and returns the
+     * data source to add or save.
+     *
+     * @param dataSource - The data source to prepare, not normalized
+     * @param workspace - The directory handle of the open workspace, if any
+     * @param projectSource - Where the project was loaded from, if anywhere (see
+     * {@link DataProvider.normalize})
+     * @param options - Optional abort signal
+     * @returns A promise that resolves to the data source to add or save
+     */
+    prepareDataSource?(dataSource: TDataSource, workspace: FileSystemDirectoryHandle | null, projectSource: string | null, options?: {
+        signal?: AbortSignal;
+    }): Promise<TDataSource>;
     /**
      * Opens a data source and returns the loaded data accessor
      *
@@ -3985,6 +4057,14 @@ export declare type SizeConfig = ConstantConfig<number, {
  * URL's path are dropped silently. Resolving within the workspace collapses the
  * segments and fails if the path leaves the workspace.
  *
+ * Helpers work on normalized sources: {@link SourceUtils.isWorkspacePath}
+ * classifies them, {@link SourceUtils.makeWorkspacePath} builds them,
+ * {@link SourceUtils.getPathSegments}, {@link SourceUtils.getParentSource},
+ * {@link SourceUtils.getStem} and {@link SourceUtils.getExtension} take them
+ * apart, and
+ * {@link SourceUtils.makeProjectPath} turns them back into project-relative
+ * paths.
+ *
  * A relative path whose first segment contains a colon (e.g.
  * `sample1:ch2.tif`) is taken for a URL; write it as `./sample1:ch2.tif`
  * instead.
@@ -3994,38 +4074,6 @@ export declare class SourceUtils {
     private static readonly _appPathPrefix;
     private static readonly _workspacePathPrefix;
     private static readonly _urlSchemePattern;
-    /**
-     * Returns whether a normalized source refers to a file or directory within
-     * the workspace
-     *
-     * @param normalizedSource - The normalized source (see
-     *   {@link SourceUtils.normalizeSource})
-     * @returns `true` for workspace-relative paths, `false` for URLs and
-     *   app-relative paths
-     */
-    static isWorkspacePath(normalizedSource: string): boolean;
-    /**
-     * Builds a workspace-relative path from the segments of a path within the
-     * workspace, as returned by `FileSystemDirectoryHandle.resolve`
-     *
-     * @param segments - The path segments, from the workspace root down to the
-     *   file or directory
-     * @returns The workspace-relative path (with `/` prefix)
-     */
-    static makeWorkspacePath(segments: string[]): string;
-    /**
-     * Returns the directory that contains a normalized source
-     *
-     * @param normalizedSource - The normalized source (see
-     *   {@link SourceUtils.normalizeSource})
-     * @returns The normalized parent source and the name of the source within
-     *   it, decoded for URLs; `null` if the source is the root of its URL's path
-     *   or lies directly in the workspace, as the workspace root is no source
-     */
-    static getParentSource(normalizedSource: string): {
-        parentSource: string;
-        name: string;
-    } | null;
     /**
      * Normalizes a source, applying the fallbacks for missing project sources
      * and workspaces
@@ -4098,6 +4146,24 @@ export declare class SourceUtils {
     static resolveSourceFile(normalizedSource: string, workspace: FileSystemDirectoryHandle | null, options?: {
         signal?: AbortSignal;
     }): Promise<string | FileSystemFileHandle>;
+    /**
+     * Resolves a normalized source to an absolute URL or a directory handle
+     *
+     * Like {@link SourceUtils.resolveSource}, for sources that have to refer to
+     * a directory.
+     *
+     * @param normalizedSource - See {@link SourceUtils.resolveSource}
+     * @param workspace - See {@link SourceUtils.resolveSource}
+     * @param options - See {@link SourceUtils.resolveSource}
+     * @returns A promise that resolves to the absolute URL, or to the directory
+     *   handle for sources within the workspace
+     * @throws See {@link SourceUtils.resolveSource}
+     * @throws DOMException if the source refers to a file within the workspace
+     *   (`TypeMismatchError`)
+     */
+    static resolveSourceDirectory(normalizedSource: string, workspace: FileSystemDirectoryHandle | null, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | FileSystemDirectoryHandle>;
     /**
      * Resolves a normalized source to an absolute URL or an opened file
      *
@@ -4128,23 +4194,102 @@ export declare class SourceUtils {
         file: File;
     }>;
     /**
-     * Resolves a normalized source to an absolute URL or a directory handle
+     * Returns whether a normalized source refers to a file or directory within
+     * the workspace
      *
-     * Like {@link SourceUtils.resolveSource}, for sources that have to refer to
-     * a directory.
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns `true` for workspace-relative paths, `false` for URLs and
+     *   app-relative paths
+     */
+    static isWorkspacePath(normalizedSource: string): boolean;
+    /**
+     * Builds a workspace-relative path from the segments of a path within the
+     * workspace, as returned by `FileSystemDirectoryHandle.resolve`
      *
-     * @param normalizedSource - See {@link SourceUtils.resolveSource}
-     * @param workspace - See {@link SourceUtils.resolveSource}
-     * @param options - See {@link SourceUtils.resolveSource}
-     * @returns A promise that resolves to the absolute URL, or to the directory
-     *   handle for sources within the workspace
-     * @throws See {@link SourceUtils.resolveSource}
-     * @throws DOMException if the source refers to a file within the workspace
-     *   (`TypeMismatchError`)
+     * @param segments - The path segments, from the workspace root down to the
+     *   file or directory
+     * @returns The workspace-relative path (with `/` prefix)
      */
-    static resolveSourceDirectory(normalizedSource: string, workspace: FileSystemDirectoryHandle | null, options?: {
-        signal?: AbortSignal;
-    }): Promise<string | FileSystemDirectoryHandle>;
+    static makeWorkspacePath(segments: string[]): string;
+    /**
+     * Turns a workspace-relative path into a path relative to the project file,
+     * if the project was loaded from the workspace
+     *
+     * The result normalizes back to the same workspace-relative path (see
+     * {@link SourceUtils.normalizeSource}), so data sources stay valid when the
+     * project and its data are moved together. A first segment that contains a
+     * colon gets a `./` prefix where it would otherwise be taken for a URL.
+     *
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource}); a workspace-relative path has to
+     *   name a file or directory within the workspace, not its root
+     * @param projectSource - Where the project was loaded from (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns The project-relative path (e.g. `points.csv` or
+     *   `../shared/x.csv`, or `.` for the project file's own directory) if both
+     *   the source and the project source are workspace-relative; the source
+     *   unchanged otherwise
+     */
+    static makeProjectPath(normalizedSource: string, projectSource: string | null): string;
+    /**
+     * Returns the path segments of a normalized source
+     *
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns The segments from the workspace root down to the file or
+     *   directory, or the decoded segments of a URL's path, without its query and
+     *   hash; empty for URLs without a path, such as `data:` URLs, and for the
+     *   root of an origin
+     * @throws TypeError if the source is neither a workspace-relative path nor
+     *   an absolute URL
+     * @throws Error if a workspace-relative path leads above the workspace root
+     */
+    static getPathSegments(normalizedSource: string): string[];
+    /**
+     * Returns the directory that contains a normalized source
+     *
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns The normalized parent source and the name of the source within
+     *   it, decoded for URLs; `null` if the source is the root of its URL's path,
+     *   is a URL without a path (such as a `data:` URL), or lies directly in the
+     *   workspace, as the workspace root is no source
+     * @throws See {@link SourceUtils.getPathSegments}
+     */
+    static getParentSource(normalizedSource: string): {
+        parentSource: string;
+        name: string;
+    } | null;
+    /**
+     * Returns the name of the file or directory a normalized source refers to,
+     * without its last extension
+     *
+     * Only the last extension is dropped, so `cells.ome.zarr` gives `cells.ome`.
+     * A leading dot does not start an extension, so `.hidden` stays as is.
+     *
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns The stem of the last path segment, decoded for URLs; an empty
+     *   string for URLs without a path, such as `data:` URLs or the root of an
+     *   origin
+     * @throws See {@link SourceUtils.getPathSegments}
+     */
+    static getStem(normalizedSource: string): string;
+    /**
+     * Returns the last extension of the file or directory a normalized source
+     * refers to, lower-cased for comparison
+     *
+     * Only the last extension is returned, so `cells.ome.zarr` gives `.zarr`.
+     * A leading dot does not start an extension, so `.hidden` has none.
+     *
+     * @param normalizedSource - The normalized source (see
+     *   {@link SourceUtils.normalizeSource})
+     * @returns The extension including its dot (e.g. `.csv`), or an empty
+     *   string if the last path segment has none
+     * @throws See {@link SourceUtils.getPathSegments}
+     */
+    static getExtension(normalizedSource: string): string;
     /**
      * Normalizes a project-relative path
      *
@@ -4201,6 +4346,25 @@ export declare class SourceUtils {
      * @throws TypeError if the path does not form a valid URL with the base URL
      */
     private static _normalizeAppPath;
+    /**
+     * Splits a workspace-relative path into its collapsed segments, the inverse
+     * of {@link SourceUtils.makeWorkspacePath}
+     *
+     * @param workspacePath - The workspace-relative path (with `/` prefix)
+     * @returns The segments from the workspace root down to the file or
+     *   directory, empty for the root itself
+     * @throws Error if the path leads above the workspace root
+     */
+    private static _getWorkspaceSegments;
+    /**
+     * Splits the path of a URL into its segments
+     *
+     * @param url - The URL
+     * @returns The non-empty, still encoded segments of the URL's path; empty
+     *   for URLs without a hierarchical path, such as `data:` and `blob:` URLs,
+     *   whose path does not start with `/`
+     */
+    private static _getURLSegments;
     /**
      * Splits a path into segments, dropping empty and `.` segments and
      * collapsing `..` segments against the segments preceding them
@@ -4212,6 +4376,22 @@ export declare class SourceUtils {
      * @throws Error if the path leads above the root
      */
     private static _collapseSegments;
+    /**
+     * Returns where the last extension of a file or directory name starts
+     *
+     * @param name - The name
+     * @returns The index of the extension's dot, or `-1` if the name has no
+     *   extension; a leading dot does not start one
+     */
+    private static _getExtensionIndex;
+    /**
+     * Decodes a percent-encoded URL path segment
+     *
+     * @param segment - The encoded segment
+     * @returns The decoded segment, or the segment as is if it holds a malformed
+     *   escape (e.g. a stray `%`), which the URL parser lets through
+     */
+    private static _decodeSegment;
 }
 
 /**

package/dist/index.js

@@ -2346,6 +2346,14 @@ var ProjectUtils = class {
 * URL's path are dropped silently. Resolving within the workspace collapses the
 * segments and fails if the path leaves the workspace.
 *
+* Helpers work on normalized sources: {@link SourceUtils.isWorkspacePath}
+* classifies them, {@link SourceUtils.makeWorkspacePath} builds them,
+* {@link SourceUtils.getPathSegments}, {@link SourceUtils.getParentSource},
+* {@link SourceUtils.getStem} and {@link SourceUtils.getExtension} take them
+* apart, and
+* {@link SourceUtils.makeProjectPath} turns them back into project-relative
+* paths.
+*
 * A relative path whose first segment contains a colon (e.g.
 * `sample1:ch2.tif`) is taken for a URL; write it as `./sample1:ch2.tif`
 * instead.
@@ -2356,58 +2364,6 @@ var SourceUtils = class SourceUtils {
 	static _workspacePathPrefix = SourceUtils._pathSep;
 	static _urlSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
 	/**
-	* Returns whether a normalized source refers to a file or directory within
-	* the workspace
-	*
-	* @param normalizedSource - The normalized source (see
-	*   {@link SourceUtils.normalizeSource})
-	* @returns `true` for workspace-relative paths, `false` for URLs and
-	*   app-relative paths
-	*/
-	static isWorkspacePath(normalizedSource) {
-		return normalizedSource.startsWith(SourceUtils._workspacePathPrefix) && !normalizedSource.startsWith(SourceUtils._appPathPrefix);
-	}
-	/**
-	* Builds a workspace-relative path from the segments of a path within the
-	* workspace, as returned by `FileSystemDirectoryHandle.resolve`
-	*
-	* @param segments - The path segments, from the workspace root down to the
-	*   file or directory
-	* @returns The workspace-relative path (with `/` prefix)
-	*/
-	static makeWorkspacePath(segments) {
-		return SourceUtils._workspacePathPrefix + segments.join(SourceUtils._pathSep);
-	}
-	/**
-	* Returns the directory that contains a normalized source
-	*
-	* @param normalizedSource - The normalized source (see
-	*   {@link SourceUtils.normalizeSource})
-	* @returns The normalized parent source and the name of the source within
-	*   it, decoded for URLs; `null` if the source is the root of its URL's path
-	*   or lies directly in the workspace, as the workspace root is no source
-	*/
-	static getParentSource(normalizedSource) {
-		if (SourceUtils.isWorkspacePath(normalizedSource)) {
-			const segments = normalizedSource.substring(SourceUtils._workspacePathPrefix.length).split(SourceUtils._pathSep);
-			const name = segments.pop();
-			if (name === void 0 || segments.length === 0) return null;
-			return {
-				parentSource: SourceUtils.makeWorkspacePath(segments),
-				name
-			};
-		}
-		const url = new URL(normalizedSource);
-		const segments = url.pathname.split(SourceUtils._pathSep).filter((segment) => segment !== "");
-		const name = segments.pop();
-		if (name === void 0) return null;
-		url.pathname = segments.join(SourceUtils._pathSep);
-		return {
-			parentSource: url.toString(),
-			name: decodeURIComponent(name)
-		};
-	}
-	/**
 	* Normalizes a source, applying the fallbacks for missing project sources
 	* and workspaces
 	*
@@ -2471,7 +2427,7 @@ var SourceUtils = class SourceUtils {
 		signal?.throwIfAborted();
 		if (!SourceUtils.isWorkspacePath(normalizedSource)) return normalizedSource;
 		if (workspace === null) throw new Error(`Cannot resolve workspace-relative path without workspace: ${normalizedSource}`);
-		const segments = SourceUtils._collapseSegments(normalizedSource.substring(SourceUtils._workspacePathPrefix.length));
+		const segments = SourceUtils._getWorkspaceSegments(normalizedSource);
 		const entryName = segments.pop();
 		if (entryName === void 0) throw new Error(`Not a workspace file or directory: ${normalizedSource}`);
 		let dir = workspace;
@@ -2511,6 +2467,26 @@ var SourceUtils = class SourceUtils {
 		return resolvedSource;
 	}
 	/**
+	* Resolves a normalized source to an absolute URL or a directory handle
+	*
+	* Like {@link SourceUtils.resolveSource}, for sources that have to refer to
+	* a directory.
+	*
+	* @param normalizedSource - See {@link SourceUtils.resolveSource}
+	* @param workspace - See {@link SourceUtils.resolveSource}
+	* @param options - See {@link SourceUtils.resolveSource}
+	* @returns A promise that resolves to the absolute URL, or to the directory
+	*   handle for sources within the workspace
+	* @throws See {@link SourceUtils.resolveSource}
+	* @throws DOMException if the source refers to a file within the workspace
+	*   (`TypeMismatchError`)
+	*/
+	static async resolveSourceDirectory(normalizedSource, workspace, options) {
+		const resolvedSource = await SourceUtils.resolveSource(normalizedSource, workspace, options);
+		if (typeof resolvedSource !== "string" && resolvedSource.kind !== "directory") throw new DOMException(`Not a workspace directory: ${normalizedSource}`, "TypeMismatchError");
+		return resolvedSource;
+	}
+	/**
 	* Resolves a normalized source to an absolute URL or an opened file
 	*
 	* Like {@link SourceUtils.resolveSourceFile}, for readers that take either
@@ -2539,24 +2515,141 @@ var SourceUtils = class SourceUtils {
 		return { file };
 	}
 	/**
-	* Resolves a normalized source to an absolute URL or a directory handle
+	* Returns whether a normalized source refers to a file or directory within
+	* the workspace
 	*
-	* Like {@link SourceUtils.resolveSource}, for sources that have to refer to
-	* a directory.
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns `true` for workspace-relative paths, `false` for URLs and
+	*   app-relative paths
+	*/
+	static isWorkspacePath(normalizedSource) {
+		return normalizedSource.startsWith(SourceUtils._workspacePathPrefix) && !normalizedSource.startsWith(SourceUtils._appPathPrefix);
+	}
+	/**
+	* Builds a workspace-relative path from the segments of a path within the
+	* workspace, as returned by `FileSystemDirectoryHandle.resolve`
 	*
-	* @param normalizedSource - See {@link SourceUtils.resolveSource}
-	* @param workspace - See {@link SourceUtils.resolveSource}
-	* @param options - See {@link SourceUtils.resolveSource}
-	* @returns A promise that resolves to the absolute URL, or to the directory
-	*   handle for sources within the workspace
-	* @throws See {@link SourceUtils.resolveSource}
-	* @throws DOMException if the source refers to a file within the workspace
-	*   (`TypeMismatchError`)
+	* @param segments - The path segments, from the workspace root down to the
+	*   file or directory
+	* @returns The workspace-relative path (with `/` prefix)
 	*/
-	static async resolveSourceDirectory(normalizedSource, workspace, options) {
-		const resolvedSource = await SourceUtils.resolveSource(normalizedSource, workspace, options);
-		if (typeof resolvedSource !== "string" && resolvedSource.kind !== "directory") throw new DOMException(`Not a workspace directory: ${normalizedSource}`, "TypeMismatchError");
-		return resolvedSource;
+	static makeWorkspacePath(segments) {
+		return SourceUtils._workspacePathPrefix + segments.join(SourceUtils._pathSep);
+	}
+	/**
+	* Turns a workspace-relative path into a path relative to the project file,
+	* if the project was loaded from the workspace
+	*
+	* The result normalizes back to the same workspace-relative path (see
+	* {@link SourceUtils.normalizeSource}), so data sources stay valid when the
+	* project and its data are moved together. A first segment that contains a
+	* colon gets a `./` prefix where it would otherwise be taken for a URL.
+	*
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource}); a workspace-relative path has to
+	*   name a file or directory within the workspace, not its root
+	* @param projectSource - Where the project was loaded from (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns The project-relative path (e.g. `points.csv` or
+	*   `../shared/x.csv`, or `.` for the project file's own directory) if both
+	*   the source and the project source are workspace-relative; the source
+	*   unchanged otherwise
+	*/
+	static makeProjectPath(normalizedSource, projectSource) {
+		if (projectSource === null || !SourceUtils.isWorkspacePath(projectSource) || !SourceUtils.isWorkspacePath(normalizedSource)) return normalizedSource;
+		const projectDirSegments = SourceUtils._getWorkspaceSegments(projectSource).slice(0, -1);
+		const segments = SourceUtils._getWorkspaceSegments(normalizedSource);
+		let commonLength = 0;
+		while (commonLength < projectDirSegments.length && commonLength < segments.length && projectDirSegments[commonLength] === segments[commonLength]) commonLength++;
+		const projectPath = [...Array(projectDirSegments.length - commonLength).fill(".."), ...segments.slice(commonLength)].join(SourceUtils._pathSep);
+		if (projectPath === "") return ".";
+		return SourceUtils._urlSchemePattern.test(projectPath) ? `.${SourceUtils._pathSep}${projectPath}` : projectPath;
+	}
+	/**
+	* Returns the path segments of a normalized source
+	*
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns The segments from the workspace root down to the file or
+	*   directory, or the decoded segments of a URL's path, without its query and
+	*   hash; empty for URLs without a path, such as `data:` URLs, and for the
+	*   root of an origin
+	* @throws TypeError if the source is neither a workspace-relative path nor
+	*   an absolute URL
+	* @throws Error if a workspace-relative path leads above the workspace root
+	*/
+	static getPathSegments(normalizedSource) {
+		if (SourceUtils.isWorkspacePath(normalizedSource)) return SourceUtils._getWorkspaceSegments(normalizedSource);
+		return SourceUtils._getURLSegments(new URL(normalizedSource)).map((segment) => SourceUtils._decodeSegment(segment));
+	}
+	/**
+	* Returns the directory that contains a normalized source
+	*
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns The normalized parent source and the name of the source within
+	*   it, decoded for URLs; `null` if the source is the root of its URL's path,
+	*   is a URL without a path (such as a `data:` URL), or lies directly in the
+	*   workspace, as the workspace root is no source
+	* @throws See {@link SourceUtils.getPathSegments}
+	*/
+	static getParentSource(normalizedSource) {
+		if (SourceUtils.isWorkspacePath(normalizedSource)) {
+			const segments = SourceUtils._getWorkspaceSegments(normalizedSource);
+			const name = segments.pop();
+			if (name === void 0 || segments.length === 0) return null;
+			return {
+				parentSource: SourceUtils.makeWorkspacePath(segments),
+				name
+			};
+		}
+		const url = new URL(normalizedSource);
+		const segments = SourceUtils._getURLSegments(url);
+		const name = segments.pop();
+		if (name === void 0) return null;
+		url.pathname = segments.join(SourceUtils._pathSep);
+		return {
+			parentSource: url.toString(),
+			name: SourceUtils._decodeSegment(name)
+		};
+	}
+	/**
+	* Returns the name of the file or directory a normalized source refers to,
+	* without its last extension
+	*
+	* Only the last extension is dropped, so `cells.ome.zarr` gives `cells.ome`.
+	* A leading dot does not start an extension, so `.hidden` stays as is.
+	*
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns The stem of the last path segment, decoded for URLs; an empty
+	*   string for URLs without a path, such as `data:` URLs or the root of an
+	*   origin
+	* @throws See {@link SourceUtils.getPathSegments}
+	*/
+	static getStem(normalizedSource) {
+		const name = SourceUtils.getPathSegments(normalizedSource).at(-1) ?? "";
+		const extensionIndex = SourceUtils._getExtensionIndex(name);
+		return extensionIndex !== -1 ? name.substring(0, extensionIndex) : name;
+	}
+	/**
+	* Returns the last extension of the file or directory a normalized source
+	* refers to, lower-cased for comparison
+	*
+	* Only the last extension is returned, so `cells.ome.zarr` gives `.zarr`.
+	* A leading dot does not start an extension, so `.hidden` has none.
+	*
+	* @param normalizedSource - The normalized source (see
+	*   {@link SourceUtils.normalizeSource})
+	* @returns The extension including its dot (e.g. `.csv`), or an empty
+	*   string if the last path segment has none
+	* @throws See {@link SourceUtils.getPathSegments}
+	*/
+	static getExtension(normalizedSource) {
+		const name = SourceUtils.getPathSegments(normalizedSource).at(-1) ?? "";
+		const extensionIndex = SourceUtils._getExtensionIndex(name);
+		return extensionIndex !== -1 ? name.substring(extensionIndex).toLowerCase() : "";
 	}
 	/**
 	* Normalizes a project-relative path
@@ -2585,7 +2678,7 @@ var SourceUtils = class SourceUtils {
 			} catch (error) {
 				throw new Error(`Invalid project-relative path: ${projectPath}`, { cause: error });
 			}
-			const projectDirSegments = SourceUtils._collapseSegments(projectSource.substring(SourceUtils._workspacePathPrefix.length)).slice(0, -1);
+			const projectDirSegments = SourceUtils._getWorkspaceSegments(projectSource).slice(0, -1);
 			const segments = SourceUtils._collapseSegments(projectPath, projectDirSegments);
 			return SourceUtils._normalizeWorkspacePath(SourceUtils.makeWorkspacePath(segments), workspace, options);
 		}
@@ -2612,13 +2705,12 @@ var SourceUtils = class SourceUtils {
 	*/
 	static _normalizeWorkspacePath(workspacePath, workspace, options) {
 		if (!workspacePath.startsWith(SourceUtils._workspacePathPrefix)) throw new Error(`Invalid workspace-relative path: ${workspacePath}`);
-		const path = workspacePath.substring(SourceUtils._workspacePathPrefix.length);
 		if (workspace !== null) {
-			const segments = SourceUtils._collapseSegments(path);
+			const segments = SourceUtils._getWorkspaceSegments(workspacePath);
 			if (segments.length === 0) throw new Error(`Not a workspace file or directory: ${workspacePath}`);
 			return SourceUtils.makeWorkspacePath(segments);
 		}
-		return SourceUtils._normalizeAppPath(SourceUtils._appPathPrefix + path, options);
+		return SourceUtils._normalizeAppPath(SourceUtils._appPathPrefix + workspacePath.substring(SourceUtils._workspacePathPrefix.length), options);
 	}
 	/**
 	* Normalizes an app-relative path to an absolute URL
@@ -2641,6 +2733,30 @@ var SourceUtils = class SourceUtils {
 		return new URL(path, baseUrl).toString();
 	}
 	/**
+	* Splits a workspace-relative path into its collapsed segments, the inverse
+	* of {@link SourceUtils.makeWorkspacePath}
+	*
+	* @param workspacePath - The workspace-relative path (with `/` prefix)
+	* @returns The segments from the workspace root down to the file or
+	*   directory, empty for the root itself
+	* @throws Error if the path leads above the workspace root
+	*/
+	static _getWorkspaceSegments(workspacePath) {
+		return SourceUtils._collapseSegments(workspacePath.substring(SourceUtils._workspacePathPrefix.length));
+	}
+	/**
+	* Splits the path of a URL into its segments
+	*
+	* @param url - The URL
+	* @returns The non-empty, still encoded segments of the URL's path; empty
+	*   for URLs without a hierarchical path, such as `data:` and `blob:` URLs,
+	*   whose path does not start with `/`
+	*/
+	static _getURLSegments(url) {
+		if (!url.pathname.startsWith(SourceUtils._pathSep)) return [];
+		return url.pathname.split(SourceUtils._pathSep).filter((segment) => segment !== "");
+	}
+	/**
 	* Splits a path into segments, dropping empty and `.` segments and
 	* collapsing `..` segments against the segments preceding them
 	*
@@ -2661,6 +2777,31 @@ var SourceUtils = class SourceUtils {
 		}
 		return segments;
 	}
+	/**
+	* Returns where the last extension of a file or directory name starts
+	*
+	* @param name - The name
+	* @returns The index of the extension's dot, or `-1` if the name has no
+	*   extension; a leading dot does not start one
+	*/
+	static _getExtensionIndex(name) {
+		const extensionIndex = name.lastIndexOf(".");
+		return extensionIndex > 0 ? extensionIndex : -1;
+	}
+	/**
+	* Decodes a percent-encoded URL path segment
+	*
+	* @param segment - The encoded segment
+	* @returns The decoded segment, or the segment as is if it holds a malformed
+	*   escape (e.g. a stray `%`), which the URL parser lets through
+	*/
+	static _decodeSegment(segment) {
+		try {
+			return decodeURIComponent(segment);
+		} catch {
+			return segment;
+		}
+	}
 };
 //#endregion
 //#region src/utils/TableUtils.ts

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tissuumaps/core",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Core model, types and utilities shared by the TissUUmaps packages",
-  "homepage": "https://tissuumaps.github.io/TissUUmaps/",
+  "homepage": "https://tissuumaps.github.io/",
   "bugs": "https://github.com/TissUUmaps/TissUUmaps/issues",
   "repository": {
     "type": "git",
@@ -32,11 +32,13 @@
     "@jsonforms/core": "^3.8.0",
     "@types/d3-color": "^3.1.3",
     "@types/d3-scale-chromatic": "^3.1.0",
+    "immer": "^11.1.8",
     "openseadragon": "^6.1.1",
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
     "@jsonforms/core": "^3.8.0",
+    "immer": "^11.1.8",
     "openseadragon": "^6.1.1",
     "zustand": "^5.0.15"
   },
@@ -44,6 +46,9 @@
     "@jsonforms/core": {
       "optional": true
     },
+    "immer": {
+      "optional": true
+    },
     "openseadragon": {
       "optional": true
     },