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

package/dist/react.d.cts

@@ -0,0 +1,424 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, CSSProperties } from 'react';
+
+/**
+ * @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;
+}
+
+/**
+ * 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`;
+};
+
+/**
+ * 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+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;
+}
+
+/**
+ * THE canvas kind registry. A kind is one sort of thing the canvas can show —
+ * an artifact, a document, a chat, a notification feed. Any feature adds a
+ * kind with ONE call and never touches canvas code:
+ *
+ *   registerCanvasKind(defineCanvasKind<{ noteId: string }>({
+ *     id: "note",
+ *     label: "Note",
+ *     icon: NoteIcon,
+ *     load: () => import("./NoteCanvasView"),
+ *     title: (data) => data.noteId,
+ *   }));
+ *
+ * The registry lives on globalThis under a Symbol.for key so duplicated
+ * bundles (ESM + CJS, two chunks) share ONE registry.
+ */
+
+interface CanvasKindProps<TData extends CanvasJson = CanvasJson> {
+    readonly item: CanvasItem;
+    readonly data: TData;
+    readonly paneId: CanvasPaneId;
+    readonly isFocused: boolean;
+    readonly canvas: CanvasController;
+}
+interface CanvasMenuItem {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: ReactNode;
+    readonly onSelect: () => void;
+    readonly destructive?: boolean;
+}
+interface CanvasKind<TData extends CanvasJson = CanvasJson> {
+    readonly id: string;
+    /** Singular noun shown in menus and the empty-pane launcher. */
+    readonly label: string;
+    readonly icon: ComponentType<{
+        className?: string;
+    }>;
+    /** Eager component. Provide this OR `load`. */
+    readonly component?: ComponentType<CanvasKindProps<TData>>;
+    /** Lazy component — the kind's code loads only when a tab of it renders. */
+    readonly load?: () => Promise<{
+        default: ComponentType<CanvasKindProps<TData>>;
+    }>;
+    /** Tab title from the item's data. Falls back to the item's title, then `label`. */
+    readonly title?: (data: TData, item: CanvasItem) => string;
+    /** Comes back after a reload. Default true; false for live sessions that cannot resume. */
+    readonly restore?: boolean;
+    /** Stays mounted while its tab is in the background (live chat, a running tool). */
+    readonly keepAlive?: boolean;
+    /** When set, the kind is offered in an empty pane's launcher. */
+    readonly launcher?: {
+        readonly key: string;
+        readonly data: TData;
+        readonly title?: string;
+    };
+    /** The kind's own button, rendered left of the pane's "…" menu. */
+    readonly HeaderAction?: ComponentType<CanvasKindProps<TData>>;
+    /** Kind-specific entries for the pane's "…" menu. */
+    readonly menuItems?: (props: CanvasKindProps<TData>) => readonly CanvasMenuItem[];
+}
+/** Erased form stored in the registry. */
+type AnyCanvasKind = CanvasKind<CanvasJson>;
+/**
+ * Typed authoring helper. The data type is a promise the kind's opener keeps;
+ * the registry stores the erased form (the cast is the one registration seam).
+ */
+declare function defineCanvasKind<TData extends CanvasJson>(kind: CanvasKind<TData>): AnyCanvasKind;
+/** Registers (or replaces) a kind. Returns an unregister function. */
+declare function registerCanvasKind(kind: AnyCanvasKind): () => void;
+declare function registerCanvasKinds(kinds: readonly AnyCanvasKind[]): () => void;
+declare function getCanvasKind(id: string): AnyCanvasKind | undefined;
+declare function listCanvasKinds(): AnyCanvasKind[];
+
+/**
+ * Host capabilities that apply to EVERY kind — this is how saving, sharing and
+ * history are "handled globally": the host answers them once, here, and every
+ * item that qualifies gets the entries in its "…" menu.
+ */
+interface CanvasHostPorts {
+    /** Extra "…" menu entries for an item (share, save to cloud, version history…). */
+    readonly itemActions?: (item: CanvasItem, kind: AnyCanvasKind | undefined) => readonly CanvasMenuItem[];
+    /** Pops an item out into a floating window. Absent ⇒ no "Pop out" entry. */
+    readonly popOut?: (item: CanvasItem) => void;
+}
+interface CanvasProviderProps extends CanvasHostPorts {
+    readonly children: ReactNode;
+    /** A Redux-bound store (bindCanvasToReduxStore). Omit for a standalone store. */
+    readonly store?: CanvasStoreBinding;
+    /** `null` turns memory off. Default: localStorage. */
+    readonly persistence?: CanvasPersistencePort | null;
+    readonly onError?: CanvasErrorSink;
+    /** ⌘\ / Ctrl+\ toggles the canvas; Escape leaves full screen. Default true. */
+    readonly hotkeys?: boolean;
+}
+declare function CanvasProvider({ children, store, persistence, onError, hotkeys, itemActions, popOut, }: CanvasProviderProps): react.JSX.Element;
+/** The controller: open, close, toggle, split… */
+declare function useCanvas(): CanvasController;
+/** Same as useCanvas, but null outside a provider (for components that may render anywhere). */
+declare function useOptionalCanvas(): CanvasController | null;
+declare function useCanvasHostPorts(): CanvasHostPorts;
+/** True when a canvas column is on screen in this tree — the ONE availability answer. */
+declare function useCanvasIsPresented(): boolean;
+/** Subscribes to a slice of canvas state. The selector must return stable values. */
+declare function useCanvasState<T>(selector: (state: CanvasState) => T): T;
+/**
+ * Like useCanvasState, but safe outside a provider: returns `fallback` there.
+ * For components that may render in a tree with no canvas (a bare test, an
+ * embed). `fallback` must be referentially stable (a primitive or null).
+ */
+declare function useOptionalCanvasState<T>(selector: (state: CanvasState) => T, fallback: T): T;
+/** Re-renders when kinds register, so late-registered kinds appear. */
+declare function useCanvasKinds(): readonly AnyCanvasKind[];
+declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
+
+/** The column's rendered width in px: 0 when put away, null when full screen. */
+declare function useCanvasColumnWidth(): number | null;
+interface CanvasColumnProps {
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Called with the live width while the edge is dragged, then null — lets a host shell reflow in step. */
+    readonly onLiveWidth?: (width: number | null) => void;
+}
+declare function CanvasColumn({ className, style, onLiveWidth }: CanvasColumnProps): react.JSX.Element | null;
+/** THE one button that opens and puts away the canvas. */
+declare function CanvasToggle({ className }: {
+    className?: string;
+}): react.JSX.Element;
+/**
+ * For hosts without their own shell (a Vite app, an Electron window): the app
+ * on the left, the canvas column on the right, full screen handled.
+ */
+declare function CanvasFrame({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+
+declare function itemTitle(item: CanvasItem, kind: AnyCanvasKind | undefined): string;
+declare function CanvasPaneView({ paneId }: {
+    paneId: CanvasPaneId;
+}): react.JSX.Element | null;
+
+export { type AnyCanvasKind, CanvasColumn, type CanvasColumnProps, CanvasFrame, type CanvasHostPorts, type CanvasKind, type CanvasKindProps, type CanvasMenuItem, CanvasPaneView, CanvasProvider, type CanvasProviderProps, CanvasToggle, defineCanvasKind, getCanvasKind, itemTitle, listCanvasKinds, registerCanvasKind, registerCanvasKinds, useCanvas, useCanvasColumnWidth, useCanvasHostPorts, useCanvasIsPresented, useCanvasKind, useCanvasKinds, useCanvasState, useOptionalCanvas, useOptionalCanvasState };