@ai-matrx/canvas 0.0.0-bootstrap.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+/**
+ * @ai-matrx/canvas — core types.
+ *
+ * The canvas is ONE docked column on the right edge of an application. It holds
+ * panes; panes hold tabs; every tab is one CanvasItem. A CanvasItem is
+ * identified by `kind` + `key`, so opening the same thing twice always lands on
+ * the existing tab instead of creating a duplicate.
+ *
+ * Everything in CanvasState is plain JSON: it lives in the host's Redux store
+ * (or the package's own standalone store), it is persisted between sessions,
+ * and it can be inspected. No functions, no class instances, no React nodes.
+ */
+/** Any value that survives JSON.stringify → JSON.parse unchanged. */
+type CanvasJson = string | number | boolean | null | readonly CanvasJson[] | {
+    readonly [key: string]: CanvasJson | undefined;
+};
+declare const itemIdBrand: unique symbol;
+declare const paneIdBrand: unique symbol;
+declare const splitIdBrand: unique symbol;
+/** `${kind}::${key}` — the identity of one thing on the canvas. */
+type CanvasItemId = string & {
+    readonly [itemIdBrand]: true;
+};
+type CanvasPaneId = string & {
+    readonly [paneIdBrand]: true;
+};
+type CanvasSplitId = string & {
+    readonly [splitIdBrand]: true;
+};
+interface CanvasItem {
+    readonly id: CanvasItemId;
+    /** Registered kind id (see `registerCanvasKind`). */
+    readonly kind: string;
+    /** Stable key inside the kind — an artifact id, a conversation id, "default". */
+    readonly key: string;
+    /** Explicit tab title. `null` ⇒ the kind's `title(data)` or its label. */
+    readonly title: string | null;
+    readonly data: CanvasJson;
+    readonly openedAt: number;
+    readonly updatedAt: number;
+}
+interface CanvasPane {
+    readonly id: CanvasPaneId;
+    readonly itemIds: readonly CanvasItemId[];
+    readonly activeItemId: CanvasItemId | null;
+}
+/** "horizontal" = children side by side; "vertical" = children stacked. */
+type CanvasOrientation = "horizontal" | "vertical";
+type CanvasLayoutNode = {
+    readonly type: "pane";
+    readonly paneId: CanvasPaneId;
+} | {
+    readonly type: "split";
+    readonly id: CanvasSplitId;
+    readonly orientation: CanvasOrientation;
+    readonly children: readonly CanvasLayoutNode[];
+    /** Fractions, one per child, summing to 1. */
+    readonly sizes: readonly number[];
+};
+interface CanvasState {
+    readonly version: 1;
+    readonly isOpen: boolean;
+    readonly isFullscreen: boolean;
+    /** Column width in CSS pixels (desktop). */
+    readonly width: number;
+    readonly layout: CanvasLayoutNode;
+    readonly panes: {
+        readonly [paneId: string]: CanvasPane;
+    };
+    readonly items: {
+        readonly [itemId: string]: CanvasItem;
+    };
+    readonly focusedPaneId: CanvasPaneId;
+    /** Monotonic counter for minting pane/split ids — keeps the reducer pure. */
+    readonly seq: number;
+    /** True once a persisted snapshot was applied (or there was none). */
+    readonly hydrated: boolean;
+}
+/** Where a newly opened item goes. Existing items never move on open. */
+type CanvasOpenTarget = "focused" | "split-right" | "split-down" | {
+    readonly paneId: CanvasPaneId;
+};
+interface CanvasOpenInput {
+    readonly kind: string;
+    readonly key: string;
+    readonly title?: string | null | undefined;
+    readonly data?: CanvasJson | undefined;
+    readonly target?: CanvasOpenTarget | undefined;
+    /** Reveal the canvas when it is put away. Default true. */
+    readonly reveal?: boolean | undefined;
+    /** Make the item the pane's active tab. Default true. */
+    readonly activate?: boolean | undefined;
+}
+declare const CANVAS_MIN_WIDTH = 360;
+declare const CANVAS_DEFAULT_WIDTH = 640;
+declare const CANVAS_MIN_SPLIT_FRACTION = 0.12;
+
+declare function canvasItemId(kind: string, key: string): CanvasItemId;
+declare function parseCanvasItemId(id: CanvasItemId): {
+    kind: string;
+    key: string;
+};
+/**
+ * Returns the path of the first value that is NOT plain JSON, or null when the
+ * whole value is JSON. Functions, class instances, Dates, Maps, NaN and
+ * Infinity all fail — they would silently vanish or change on persist.
+ */
+declare function findNonJson(value: unknown, path?: string): string | null;
+declare function isCanvasJson(value: unknown): value is CanvasJson;
+
+/**
+ * Pure helpers over the canvas layout tree. Every function returns a new tree
+ * and never mutates its input.
+ */
+
+declare function listPaneIds(node: CanvasLayoutNode): CanvasPaneId[];
+/** Renormalizes to sum 1; falls back to even sizes for garbage input. */
+declare function normalizeSizes(sizes: readonly number[], count: number): number[];
+
+/**
+ * THE canvas reducer. Plain Redux-compatible reducer + action creators with no
+ * Redux Toolkit dependency, so it mounts in a host's RTK store
+ * (`canvasHost: canvasReducer`) or runs inside the package's own standalone
+ * store with identical behaviour.
+ *
+ * Identity law: an item is `kind::key`. Opening an item that is already on the
+ * canvas never duplicates it — it refreshes its data/title, activates its tab
+ * and focuses its pane, wherever that pane is.
+ */
+
+declare const P = "matrxCanvas/";
+type CanvasAction = {
+    type: `${typeof P}open`;
+    payload: CanvasOpenInput & {
+        now: number;
+    };
+} | {
+    type: `${typeof P}update`;
+    payload: {
+        itemId: CanvasItemId;
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+        now: number;
+    };
+} | {
+    type: `${typeof P}rekey`;
+    payload: {
+        itemId: CanvasItemId;
+        key: string;
+    };
+} | {
+    type: `${typeof P}closeItem`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}closeOthers`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}activate`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}focusPane`;
+    payload: {
+        paneId: CanvasPaneId;
+    };
+} | {
+    type: `${typeof P}moveItem`;
+    payload: {
+        itemId: CanvasItemId;
+        toPaneId: CanvasPaneId;
+        index?: number | undefined;
+    };
+} | {
+    type: `${typeof P}splitPane`;
+    payload: {
+        paneId: CanvasPaneId;
+        orientation: CanvasOrientation;
+        moveItemId?: CanvasItemId | undefined;
+    };
+} | {
+    type: `${typeof P}closePane`;
+    payload: {
+        paneId: CanvasPaneId;
+    };
+} | {
+    type: `${typeof P}resizeSplit`;
+    payload: {
+        splitId: CanvasSplitId;
+        sizes: readonly number[];
+    };
+} | {
+    type: `${typeof P}setOpen`;
+    payload: {
+        open: boolean;
+    };
+} | {
+    type: `${typeof P}toggle`;
+} | {
+    type: `${typeof P}setFullscreen`;
+    payload: {
+        fullscreen: boolean;
+    };
+} | {
+    type: `${typeof P}setWidth`;
+    payload: {
+        width: number;
+    };
+} | {
+    type: `${typeof P}hydrate`;
+    payload: {
+        snapshot: CanvasState | null;
+    };
+} | {
+    type: `${typeof P}reset`;
+};
+declare const canvasActions: {
+    readonly open: (input: CanvasOpenInput) => CanvasAction;
+    readonly update: (itemId: CanvasItemId, patch: {
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+    }) => CanvasAction;
+    /** Gives an item a new identity in place (e.g. a draft that was just saved and now has an id). */
+    readonly rekey: (itemId: CanvasItemId, key: string) => CanvasAction;
+    readonly closeItem: (itemId: CanvasItemId) => CanvasAction;
+    readonly closeOthers: (itemId: CanvasItemId) => CanvasAction;
+    readonly activate: (itemId: CanvasItemId) => CanvasAction;
+    readonly focusPane: (paneId: CanvasPaneId) => CanvasAction;
+    readonly moveItem: (itemId: CanvasItemId, toPaneId: CanvasPaneId, index?: number) => CanvasAction;
+    readonly splitPane: (paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId) => CanvasAction;
+    readonly closePane: (paneId: CanvasPaneId) => CanvasAction;
+    readonly resizeSplit: (splitId: CanvasSplitId, sizes: readonly number[]) => CanvasAction;
+    readonly setOpen: (open: boolean) => CanvasAction;
+    readonly toggle: () => CanvasAction;
+    readonly setFullscreen: (fullscreen: boolean) => CanvasAction;
+    readonly setWidth: (width: number) => CanvasAction;
+    readonly hydrate: (snapshot: CanvasState | null) => CanvasAction;
+    readonly reset: () => CanvasAction;
+};
+declare function isCanvasAction(action: unknown): action is CanvasAction;
+declare function createInitialCanvasState(): CanvasState;
+/**
+ * Validates a persisted snapshot. Anything malformed is dropped back to the
+ * initial state rather than half-applied — a corrupt layout must never crash
+ * the shell.
+ */
+declare function sanitizeCanvasSnapshot(raw: unknown): CanvasState | null;
+declare function canvasReducer(state: CanvasState | undefined, action: {
+    type: string;
+}): CanvasState;
+
+/**
+ * The store seam. The canvas never owns a second copy of its state: it reads
+ * and writes through a CanvasStoreBinding.
+ *
+ *  - A host WITH Redux mounts `canvasReducer` in its root reducer and binds it:
+ *      bindCanvasToReduxStore(store, (root) => root.canvasHost)
+ *  - A host WITHOUT Redux (a Vite tool, an Electron window) calls
+ *      createCanvasStore()
+ *    which runs the very same reducer in a tiny standalone store.
+ */
+
+interface CanvasStoreBinding {
+    getState(): CanvasState;
+    dispatch(action: CanvasAction): void;
+    subscribe(listener: () => void): () => void;
+}
+declare function createCanvasStore(initial?: CanvasState): CanvasStoreBinding;
+/** The minimum of a Redux store the canvas needs. */
+interface ReduxStoreLike<TRoot> {
+    getState(): TRoot;
+    dispatch(action: CanvasAction): unknown;
+    subscribe(listener: () => void): () => void;
+}
+declare function bindCanvasToReduxStore<TRoot>(store: ReduxStoreLike<TRoot>, select: (root: TRoot) => CanvasState): CanvasStoreBinding;
+
+/**
+ * Remembering the canvas between sessions — a table stake, never optional.
+ *
+ * The default port writes to localStorage under a versioned key. Items whose
+ * kind opts out (`restore: false`, e.g. a live session that cannot come back)
+ * are dropped from the snapshot, and panes they leave empty are dropped too.
+ */
+
+interface CanvasPersistencePort {
+    load(): CanvasState | null | Promise<CanvasState | null>;
+    save(snapshot: CanvasState): void | Promise<void>;
+}
+declare const CANVAS_STORAGE_KEY = "ai-matrx.canvas.v1";
+declare function createLocalStorageCanvasPersistence(key?: string, storage?: Pick<Storage, "getItem" | "setItem"> | null): CanvasPersistencePort;
+/** Builds the snapshot that is actually written: only restorable items. */
+declare function toPersistableSnapshot(state: CanvasState, isRestorable: (kind: string) => boolean): CanvasState;
+
+/**
+ * The canvas controller: the ONE imperative API every caller uses. It wraps a
+ * store binding, validates what callers hand it (so the reducer stays pure and
+ * trusting), and owns hydration + autosave.
+ *
+ * Nothing fails silently: a refused open (non-JSON data, unknown kind) is
+ * reported through the error sink and returns false.
+ */
+
+interface CanvasErrorReport {
+    readonly code: "non-json-data" | "unknown-kind" | "persistence-load" | "persistence-save";
+    readonly message: string;
+    readonly detail?: unknown;
+}
+type CanvasErrorSink = (report: CanvasErrorReport) => void;
+declare const consoleCanvasErrorSink: CanvasErrorSink;
+interface CanvasControllerOptions {
+    readonly store: CanvasStoreBinding;
+    readonly persistence?: CanvasPersistencePort | null | undefined;
+    /** Kinds that may not come back after a reload. Default: every kind restores. */
+    readonly isRestorable?: ((kind: string) => boolean) | undefined;
+    /** When given, opens of an unregistered kind are refused and reported. */
+    readonly isKnownKind?: ((kind: string) => boolean) | undefined;
+    readonly onError?: CanvasErrorSink | undefined;
+    readonly saveDelayMs?: number | undefined;
+    /**
+     * Whether a remembered "open" may be restored right now. A host returns
+     * false where an open canvas would take the whole screen (a phone).
+     */
+    readonly mayRestoreOpen?: (() => boolean) | undefined;
+}
+interface CanvasController {
+    readonly store: CanvasStoreBinding;
+    getState(): CanvasState;
+    open(input: CanvasOpenInput): CanvasItemId | null;
+    update(itemId: CanvasItemId, patch: {
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+    }): boolean;
+    /** Gives an item a new identity in place (a draft that was saved and now has a durable id). */
+    rekey(itemId: CanvasItemId, key: string): CanvasItemId | null;
+    close(itemId: CanvasItemId): void;
+    closeOthers(itemId: CanvasItemId): void;
+    activate(itemId: CanvasItemId): void;
+    focusPane(paneId: CanvasPaneId): void;
+    moveItem(itemId: CanvasItemId, toPaneId: CanvasPaneId, index?: number): void;
+    splitPane(paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId): void;
+    closePane(paneId: CanvasPaneId): void;
+    resizeSplit(splitId: CanvasSplitId, sizes: readonly number[]): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    setFullscreen(fullscreen: boolean): void;
+    setWidth(width: number): void;
+    /** Is this exact thing on the canvas right now? */
+    has(kind: string, key: string): boolean;
+    /**
+     * Is a canvas column on screen? A store can exist in a layout that shows no
+     * column (a kiosk, a meeting stage); opening there must be refused aloud.
+     */
+    isPresented(): boolean;
+    /** Called by a column on mount; returns the unmount callback. */
+    registerPresentation(): () => void;
+    subscribePresentation(listener: () => void): () => void;
+    /** Loads the persisted snapshot and starts autosave. Returns a disposer. */
+    start(): () => void;
+}
+declare function createCanvasController(options: CanvasControllerOptions): CanvasController;
+
+declare const selectCanvasIsOpen: (s: CanvasState) => boolean;
+declare const selectCanvasIsFullscreen: (s: CanvasState) => boolean;
+declare const selectCanvasWidth: (s: CanvasState) => number;
+declare const selectCanvasLayout: (s: CanvasState) => CanvasLayoutNode;
+declare const selectCanvasFocusedPaneId: (s: CanvasState) => CanvasPaneId;
+declare const selectCanvasIsHydrated: (s: CanvasState) => boolean;
+declare const selectCanvasItemCount: (s: CanvasState) => number;
+declare const selectCanvasPane: (s: CanvasState, paneId: CanvasPaneId) => CanvasPane | undefined;
+declare const selectCanvasItem: (s: CanvasState, itemId: CanvasItemId) => CanvasItem | undefined;
+declare function selectCanvasPaneCount(s: CanvasState): number;
+/** The item the person is looking at in the focused pane. */
+declare function selectCanvasActiveItem(s: CanvasState): CanvasItem | null;
+
+export { CANVAS_DEFAULT_WIDTH, CANVAS_MIN_SPLIT_FRACTION, CANVAS_MIN_WIDTH, CANVAS_STORAGE_KEY, type CanvasAction, type CanvasController, type CanvasControllerOptions, type CanvasErrorReport, type CanvasErrorSink, type CanvasItem, type CanvasItemId, type CanvasJson, type CanvasLayoutNode, type CanvasOpenInput, type CanvasOpenTarget, type CanvasOrientation, type CanvasPane, type CanvasPaneId, type CanvasPersistencePort, type CanvasSplitId, type CanvasState, type CanvasStoreBinding, type ReduxStoreLike, bindCanvasToReduxStore, canvasActions, canvasItemId, canvasReducer, consoleCanvasErrorSink, createCanvasController, createCanvasStore, createInitialCanvasState, createLocalStorageCanvasPersistence, findNonJson, isCanvasAction, isCanvasJson, listPaneIds, normalizeSizes, parseCanvasItemId, sanitizeCanvasSnapshot, selectCanvasActiveItem, selectCanvasFocusedPaneId, selectCanvasIsFullscreen, selectCanvasIsHydrated, selectCanvasIsOpen, selectCanvasItem, selectCanvasItemCount, selectCanvasLayout, selectCanvasPane, selectCanvasPaneCount, selectCanvasWidth, toPersistableSnapshot };