@ai-matrx/canvas 0.1.1 → 0.2.0

package/dist/react.d.cts

@@ -1,6 +1,48 @@
 import * as react from 'react';
-import { ComponentType, ReactNode, CSSProperties } from 'react';
-import { a as CanvasJson, e as CanvasItem, c as CanvasPaneId, l as CanvasController, u as CanvasStoreBinding, s as CanvasPersistencePort, o as CanvasErrorSink, d as CanvasState } from './controller-oY84BN2c.cjs';
+import { ComponentType, ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, ReactElement } from 'react';
+import { D as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, G as CanvasSessionEvent, E as CanvasSessionAttachReason, F as CanvasSessionDetachReason, e as CanvasStoreBinding, B as CanvasPersistencePort, v as CanvasErrorSink, x as CanvasLayoutRules, f as CanvasState } from './controller-Dv6J6XZm.cjs';
+
+/** One floating thing. Plain data, so a host can draw it in another process. */
+type CanvasFloating = {
+    readonly type: "tooltip";
+    readonly text: string;
+    readonly anchor: CanvasRect;
+    readonly side: "top" | "bottom";
+} | {
+    readonly type: "drop-indicator";
+    readonly rect: CanvasRect;
+    readonly paneId: CanvasPaneId;
+} | {
+    readonly type: "tab-drag";
+    readonly itemId: CanvasItemId;
+    readonly title: string;
+};
+interface CanvasOverlayPort {
+    /** Shows a floating element above everything (native views included); returns its remover. */
+    show(element: CanvasFloating): () => void;
+}
+/** A serializable "…" menu: the package keeps the handlers, a host draws the entries. */
+type CanvasMenuEntry = {
+    readonly type: "item";
+    readonly id: string;
+    readonly label: string;
+    readonly destructive?: boolean;
+} | {
+    readonly type: "separator";
+};
+/** Shows a menu at `anchor` (e.g. Electron `Menu.popup`); resolves the chosen entry id, or null. */
+type CanvasShowMenu = (entries: readonly CanvasMenuEntry[], anchor: CanvasRect) => Promise<string | null>;
+/** A native body's frame: window CSS pixels plus the device pixel ratio. */
+interface CanvasNativeRect extends CanvasRect {
+    readonly devicePixelRatio: number;
+}
+interface CanvasNativeBodyInfo {
+    /** False while package DOM floats over the canvas (a DOM menu, a tab drag): hide the native view. */
+    readonly visible: boolean;
+    readonly windowId: CanvasWindowId;
+}
+/** Reports where a native body sits; null when it is hidden or gone. Called in the frame the layout changed. */
+type CanvasNativeBodyFrame = (itemId: CanvasItemId, rect: CanvasNativeRect | null, info: CanvasNativeBodyInfo) => void;
 
 /**
  * THE canvas kind registry. A kind is one sort of thing the canvas can show —
@@ -24,7 +66,9 @@ interface CanvasKindProps<TData extends CanvasJson = CanvasJson> {
     readonly data: TData;
     readonly paneId: CanvasPaneId;
     readonly isFocused: boolean;
+    /** The canvas, acting for the window this pane is in. */
     readonly canvas: CanvasController;
+    readonly windowId: CanvasWindowId;
 }
 interface CanvasMenuItem {
     readonly id: string;
@@ -40,7 +84,7 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     readonly icon: ComponentType<{
         className?: string;
     }>;
-    /** Eager component. Provide this OR `load`. */
+    /** Eager component. Provide this OR `load` (optional for a native body or an `unavailable` placeholder). */
     readonly component?: ComponentType<CanvasKindProps<TData>>;
     /** Lazy component — the kind's code loads only when a tab of it renders. */
     readonly load?: () => Promise<{
@@ -48,16 +92,45 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     }>;
     /** 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;
+    /**
+     * Comes back after a reload. Default true; false for live things that cannot
+     * resume. "session": the tab is a view onto a process the HOST keeps (a
+     * terminal) — it comes back, closing it DETACHES (onDetach) instead of
+     * killing, and a restore or a move REATTACHES (onAttach).
+     */
+    readonly restore?: boolean | "session";
+    /** restore "session": the session's key. Default: `data.sessionKey` when it is a string. */
+    readonly sessionKey?: (data: TData, item: CanvasItem) => string | null;
+    /** restore "session": the tab now shows this session ("open" | "restore" | "arrive"). */
+    readonly onAttach?: (event: CanvasSessionEvent<CanvasSessionAttachReason>) => void;
+    /** restore "session": the tab no longer shows it ("close" | "leave" | "unmount"). Never kill the process here. */
+    readonly onDetach?: (event: CanvasSessionEvent<CanvasSessionDetachReason>) => void;
     /** Stays mounted while its tab is in the background (live chat, a running tool). */
     readonly keepAlive?: boolean;
+    /**
+     * "native": the body is drawn by the HOST outside the DOM (an Electron
+     * WebContentsView). The pane renders a placeholder and reports its rect
+     * through the provider's `onNativeBodyFrame`. Default "dom".
+     */
+    readonly body?: "dom" | "native";
+    /**
+     * An honest one-line state instead of the body while its backend is not
+     * there ("Files · next release", "No changes to show"). Return null to show
+     * the body. Read on every render.
+     */
+    readonly unavailable?: (data: TData, item: CanvasItem) => string | null;
     /** When set, the kind is offered in an empty pane's launcher. */
     readonly launcher?: {
         readonly key: string;
         readonly data: TData;
         readonly title?: string;
     };
+    /**
+     * Controls at the START of the pane header, after the title or tabs: a
+     * "+ new terminal", a browser's back / forward / reload / address bar. The
+     * slot grows to fill the header.
+     */
+    readonly HeaderLeading?: ComponentType<CanvasKindProps<TData>>;
     /** 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. */
@@ -70,6 +143,8 @@ type AnyCanvasKind = CanvasKind<CanvasJson>;
  * the registry stores the erased form (the cast is the one registration seam).
  */
 declare function defineCanvasKind<TData extends CanvasJson>(kind: CanvasKind<TData>): AnyCanvasKind;
+/** The session key of an item of a session kind (`kind.sessionKey`, else `data.sessionKey`). */
+declare function canvasSessionKey(kind: AnyCanvasKind, item: CanvasItem): string | null;
 /** Registers (or replaces) a kind. Returns an unregister function. */
 declare function registerCanvasKind(kind: AnyCanvasKind): () => void;
 declare function registerCanvasKinds(kinds: readonly AnyCanvasKind[]): () => void;
@@ -77,33 +152,75 @@ 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.
+ * What the host answers ONCE for every kind. Saving, sharing and history are
+ * "handled globally" here; the window ports let a desktop host draw floating
+ * things and native bodies its own way. Every port has a working default.
  */
 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;
+    readonly itemActions?: ((item: CanvasItem, kind: AnyCanvasKind | undefined) => readonly CanvasMenuItem[]) | undefined;
+    /**
+     * Opens a window that renders this canvas for the returned window id (web: a
+     * floating panel with <CanvasWindowScope>; desktop: a BrowserWindow with its
+     * own provider). The item then moves there. Absent ⇒ no "Pop out" entry, and
+     * `controller.popOut` is refused aloud.
+     */
+    readonly popOut?: ((item: CanvasItem) => Promise<{
+        readonly windowId: string;
+    } | null>) | undefined;
+    /** A tab docked back out of `fromWindowId`. Close that window once the state no longer lists it. */
+    readonly dockBack?: ((itemId: CanvasItemId, fromWindowId: CanvasWindowId) => void) | undefined;
+    /** Draws the "…" menu (Electron `Menu.popup`). Default: the package's DOM menu. */
+    readonly showMenu?: CanvasShowMenu | undefined;
+    /** Draws tooltips, drop indicators and tab drags above native views. Default: in the DOM. */
+    readonly overlay?: CanvasOverlayPort | undefined;
+    /** Where each native-body kind's view goes, reported in the frame the layout changed. */
+    readonly onNativeBodyFrame?: CanvasNativeBodyFrame | undefined;
 }
+type CanvasTabStripMode = "auto" | "always";
 interface CanvasProviderProps extends CanvasHostPorts {
     readonly children: ReactNode;
-    /** A Redux-bound store (bindCanvasToReduxStore). Omit for a standalone store. */
+    /** A Redux-bound store (bindCanvasToReduxStore), a remote one (createRemoteCanvasStore), or omit for a standalone store. */
     readonly store?: CanvasStoreBinding;
-    /** `null` turns memory off. Default: localStorage. */
+    /** `null` turns memory off. Default: localStorage. Ignored for a remote store (its owner saves). */
     readonly persistence?: CanvasPersistencePort | null;
     readonly onError?: CanvasErrorSink;
-    /** ⌘\ / Ctrl+\ toggles the canvas; Escape leaves full screen. Default true. */
+    /** Binds the shortcut table's web shortcuts (⌘\ toggles, Esc leaves expand…). Default true. */
     readonly hotkeys?: boolean;
+    /** The window this provider renders. Default: the main window. */
+    readonly windowId?: string;
+    /** Width and split numbers, read once. Default: CANVAS_WEB_LAYOUT_RULES. */
+    readonly layoutRules?: Partial<CanvasLayoutRules>;
+    /** Live width of the region the canvas shares with the content beside it (desktop: right of the sidebar). Default: the window. */
+    readonly regionWidth?: number | null;
+    /** "auto": a pane with one tab shows a title instead of a tab strip. Default "auto". */
+    readonly tabStrip?: CanvasTabStripMode;
 }
-declare function CanvasProvider({ children, store, persistence, onError, hotkeys, itemActions, popOut, }: CanvasProviderProps): react.JSX.Element;
-/** The controller: open, close, toggle, split… */
+declare function CanvasProvider({ children, store, persistence, onError, hotkeys, windowId: windowIdProp, layoutRules, regionWidth, tabStrip, ...hostPorts }: CanvasProviderProps): react.JSX.Element;
+/**
+ * Renders a subtree as ANOTHER window of the same canvas — the web host's
+ * pop-out panel: `<CanvasWindowScope windowId={id}><CanvasColumn placement="fill"/></CanvasWindowScope>`.
+ */
+declare function CanvasWindowScope({ windowId, children }: {
+    windowId: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The controller (acting for this window): 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;
+/** The window this subtree renders. */
+declare function useCanvasWindowId(): CanvasWindowId;
 declare function useCanvasHostPorts(): CanvasHostPorts;
-/** True when a canvas column is on screen in this tree — the ONE availability answer. */
+/**
+ * Native-body controls. `remeasure()` re-reports every native body's frame now —
+ * call it on each animation frame while the host animates its own layout (a
+ * sidebar collapsing moves the canvas without resizing it).
+ */
+declare function useCanvasNativeBodies(): {
+    readonly remeasure: () => void;
+};
+/** True when a canvas column is on screen for this window — 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;
@@ -117,22 +234,24 @@ declare function useOptionalCanvasState<T>(selector: (state: CanvasState) => T,
 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. */
+/** The column's rendered width in px for this window: 0 when put away, null when expanded. */
 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;
+    /** "docked": the right-edge column with a width handle. "fill": fills its container (a pop-out window). */
+    readonly placement?: "docked" | "fill";
 }
-declare function CanvasColumn({ className, style, onLiveWidth }: CanvasColumnProps): react.JSX.Element | null;
-/** THE one button that opens and puts away the canvas. */
+declare function CanvasColumn({ className, style, onLiveWidth, placement }: CanvasColumnProps): react.JSX.Element | null;
+/** THE one button that opens and puts away the canvas (this window's). */
 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.
+ * on the left, the canvas column on the right, expand handled.
  */
 declare function CanvasFrame({ children, className }: {
     children: ReactNode;
@@ -144,4 +263,105 @@ 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 };
+interface CanvasHeaderButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "title"> {
+    /** Accessible name and tooltip. */
+    readonly label: string;
+    /** Appended to the tooltip, e.g. "⌘\\". */
+    readonly shortcut?: string | null | undefined;
+    /** False draws the button dimmed and inert (a browser's Back with no history). Default true. */
+    readonly available?: boolean;
+    /** "sm" = a pane-header action (24px); "md" = a browser bar button (28px). */
+    readonly size?: "sm" | "md";
+    readonly pressed?: boolean;
+    readonly children: ReactNode;
+}
+/** The one icon button of the canvas chrome. */
+declare const CanvasHeaderButton: react.ForwardRefExoticComponent<CanvasHeaderButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface CanvasPanelProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    readonly panelId: string;
+    /** The header title (a single-tab pane, a panel with no tabs). */
+    readonly title: ReactNode;
+    /** Controls after the title or tabs: "+ new terminal", a browser's bar. Grows to fill the header. */
+    readonly leading?: ReactNode;
+    /** A custom start of the header instead of the title (a tab strip). `leading` still follows it. */
+    readonly header?: ReactNode;
+    /** Controls just before the "…" menu (a kind's own button). */
+    readonly actions?: ReactNode;
+    /** The "…" menu: the host renders its own menu around the trigger it receives. */
+    readonly renderMenu?: ((trigger: ReactElement) => ReactNode) | undefined;
+    readonly expanded?: boolean | undefined;
+    readonly onToggleExpand?: (() => void) | undefined;
+    readonly expandShortcut?: string | null | undefined;
+    /** Phones only: put the canvas away without closing anything. */
+    readonly onHide?: (() => void) | undefined;
+    readonly onClose?: (() => void) | undefined;
+    readonly closeLabel?: string | undefined;
+    readonly focused?: boolean | undefined;
+    /** Where the header's own body element goes (the pane body). */
+    readonly bodyProps?: HTMLAttributes<HTMLDivElement> | undefined;
+}
+/** The menu trigger every panel shares. */
+declare const CanvasMenuTrigger: react.ForwardRefExoticComponent<Omit<CanvasHeaderButtonProps, "children" | "label"> & {
+    label?: string;
+} & react.RefAttributes<HTMLButtonElement>>;
+/** The frame every canvas panel shares: header (title or tabs · leading · actions · … · expand · close) over a body. */
+declare const CanvasPanel: react.ForwardRefExoticComponent<CanvasPanelProps & react.RefAttributes<HTMLElement>>;
+/** The one-line honest state of a panel with nothing to show, or whose backend has not shipped. */
+declare function CanvasPanelEmpty({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+interface CanvasTabProps extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "onSelect"> {
+    readonly title: string;
+    readonly icon: ReactNode;
+    /** Small trailing state after the title, e.g. "exited". */
+    readonly note?: string | undefined;
+    readonly active: boolean;
+    readonly onSelect: () => void;
+    /** Absent ⇒ no close button. */
+    readonly onClose?: (() => void) | undefined;
+}
+/** One tab of a strip. */
+declare const CanvasTab: react.ForwardRefExoticComponent<CanvasTabProps & react.RefAttributes<HTMLDivElement>>;
+interface BrowserTab {
+    readonly id: string;
+    readonly title: string;
+    /** A favicon URL; a globe is drawn without one. */
+    readonly icon?: string | null | undefined;
+    /** A glyph instead of a favicon (a terminal tab draws its prompt icon). */
+    readonly glyph?: ReactNode;
+    /** Small trailing state after the title, e.g. "exited". */
+    readonly note?: string | undefined;
+}
+interface BrowserTabsProps {
+    readonly tabs: readonly BrowserTab[];
+    readonly activeId: string | null;
+    readonly onSelect: (id: string) => void;
+    readonly onClose: (id: string) => void;
+    /** Absent ⇒ no "+" button. */
+    readonly onNew?: (() => void) | undefined;
+    /** The "+" button's name (default "New tab"). */
+    readonly newLabel?: string;
+    /** The tab list's name (default "Tabs"). */
+    readonly label?: string;
+    readonly className?: string;
+}
+/** A tab strip for any panel with its own tabs: a browser's pages, a terminal's shells. */
+declare function BrowserTabs({ tabs, activeId, onSelect, onClose, onNew, newLabel, label, className }: BrowserTabsProps): react.JSX.Element;
+interface BrowserBarProps {
+    readonly url: string;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    readonly onBack: () => void;
+    readonly onForward: () => void;
+    readonly onReload: () => void;
+    /** Called with the typed address when the person presses Enter. */
+    readonly onNavigate: (address: string) => void;
+    /** Controls after the address (screenshot, open in your browser, more). */
+    readonly trailing?: ReactNode;
+    readonly className?: string;
+}
+/** A browser's back · forward · reload · address bar, for a kind's leading slot or its body. */
+declare function BrowserBar({ url, canGoBack, canGoForward, onBack, onForward, onReload, onNavigate, trailing, className }: BrowserBarProps): react.JSX.Element;
+
+export { type AnyCanvasKind, BrowserBar, type BrowserBarProps, type BrowserTab, BrowserTabs, type BrowserTabsProps, CanvasColumn, type CanvasColumnProps, type CanvasFloating, CanvasFrame, CanvasHeaderButton, type CanvasHeaderButtonProps, type CanvasHostPorts, type CanvasKind, type CanvasKindProps, type CanvasMenuEntry, type CanvasMenuItem, CanvasMenuTrigger, type CanvasNativeBodyFrame, type CanvasNativeBodyInfo, type CanvasNativeRect, type CanvasOverlayPort, CanvasPaneView, CanvasPanel, CanvasPanelEmpty, type CanvasPanelProps, CanvasProvider, type CanvasProviderProps, type CanvasShowMenu, CanvasTab, type CanvasTabProps, type CanvasTabStripMode, CanvasToggle, CanvasWindowScope, canvasSessionKey, defineCanvasKind, getCanvasKind, itemTitle, listCanvasKinds, registerCanvasKind, registerCanvasKinds, useCanvas, useCanvasColumnWidth, useCanvasHostPorts, useCanvasIsPresented, useCanvasKind, useCanvasKinds, useCanvasNativeBodies, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };