@ai-matrx/canvas 0.3.0 → 0.5.0

package/dist/react.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, ReactElement } from 'react';
-import { F as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, I as CanvasSessionEvent, G as CanvasSessionAttachReason, H as CanvasSessionDetachReason, e as CanvasStoreBinding, E as CanvasPersistencePort, w as CanvasErrorSink, z as CanvasLayoutRules, T as ToggleKindInput, y as CanvasKindVisibility, f as CanvasState } from './toggleKind-A9v45oSb.cjs';
+import { N as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, L as CanvasPresentation, Q as CanvasSessionEvent, O as CanvasSessionAttachReason, P as CanvasSessionDetachReason, K as CanvasPreferredTarget, e as CanvasStoreBinding, J as CanvasPersistencePort, A as CanvasErrorSink, E as CanvasLayoutRules, X as ToggleKindInput, D as CanvasKindVisibility, f as CanvasState } from './toggleKind-BD78LnMB.cjs';
 
 /** One floating thing. Plain data, so a host can draw it in another process. */
 type CanvasFloating = {
@@ -66,9 +66,21 @@ interface CanvasKindProps<TData extends CanvasJson = CanvasJson> {
     readonly data: TData;
     readonly paneId: CanvasPaneId;
     readonly isFocused: boolean;
+    /**
+     * On screen right now: its tab is active and its canvas is open. A body
+     * stays mounted while hidden (a background tab, a put-away canvas) — pause
+     * costly work (polling, animation) while this is false.
+     */
+    readonly isVisible: boolean;
     /** The canvas, acting for the window this pane is in. */
     readonly canvas: CanvasController;
     readonly windowId: CanvasWindowId;
+    /**
+     * The space this body has, live: size, orientation, narrow, expanded, pane
+     * count. Lay content out for it (a graph in a tall narrow pane flows top to
+     * bottom). Nested components read the same value with `useCanvasPresentation()`.
+     */
+    readonly presentation: CanvasPresentation;
 }
 interface CanvasMenuItem {
     readonly id: string;
@@ -105,8 +117,26 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     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). */
+    /**
+     * @deprecated Since 0.5.0 every body stays mounted from the first time it
+     * is shown until its tab closes — through tab switches, splits, moves,
+     * expand and the canvas being put away. This field changes nothing.
+     */
     readonly keepAlive?: boolean;
+    /**
+     * Opt OUT of staying mounted: the body unmounts whenever it is not on
+     * screen (a hidden tab, a put-away canvas) and mounts fresh when shown.
+     * Only for genuinely heavy bodies whose state is cheap to rebuild.
+     */
+    readonly unmountWhenHidden?: boolean;
+    /**
+     * Where a NEW item of this kind opens while the canvas already shows
+     * something: "split-down" puts it in a pane below (the layout rules' split
+     * share — a feed under the work), "split-right" beside, "focused" (default)
+     * in the focused pane. A pane already showing this kind takes it instead of
+     * a new split. A caller's explicit `target` always wins.
+     */
+    readonly preferredTarget?: CanvasPreferredTarget;
     /**
      * "native": the body is drawn by the HOST outside the DOM (an Electron
      * WebContentsView). The pane renders a placeholder and reports its rect
@@ -133,6 +163,13 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     readonly HeaderLeading?: ComponentType<CanvasKindProps<TData>>;
     /** The kind's own button, rendered left of the pane's "…" menu. */
     readonly HeaderAction?: ComponentType<CanvasKindProps<TData>>;
+    /**
+     * A toolbar ROW between the pane header and the body, for the active item
+     * only (a browser's back / forward / reload / address / screenshot). Always
+     * DOM, never covered by a native view: a `body: "native"` frame is measured
+     * BELOW it.
+     */
+    readonly Toolbar?: ComponentType<CanvasKindProps<TData>>;
     /** Kind-specific entries for the pane's "…" menu. */
     readonly menuItems?: (props: CanvasKindProps<TData>) => readonly CanvasMenuItem[];
 }
@@ -178,6 +215,22 @@ interface CanvasHostPorts {
     readonly onNativeBodyFrame?: CanvasNativeBodyFrame | undefined;
 }
 type CanvasTabStripMode = "auto" | "always";
+/**
+ * One contextual launcher entry: a page offers something about ITSELF in the
+ * canvas's "New tab" launcher ("This chat's documents" on a chat page) for as
+ * long as it is mounted. Shown before the global kinds.
+ */
+interface CanvasLauncherEntry {
+    readonly kind: string;
+    readonly key: string;
+    readonly data?: CanvasJson | undefined;
+    /** The entry's label (and the new tab's title). Default: the kind's label. */
+    readonly title?: string | null | undefined;
+    /** Default: the kind's icon. */
+    readonly icon?: ComponentType<{
+        className?: string;
+    }> | undefined;
+}
 interface CanvasProviderProps extends CanvasHostPorts {
     readonly children: ReactNode;
     /** A Redux-bound store (bindCanvasToReduxStore), a remote one (createRemoteCanvasStore), or omit for a standalone store. */
@@ -243,6 +296,15 @@ declare function useCanvasKindToggle(input: ToggleKindInput): {
 /** Re-renders when kinds register, so late-registered kinds appear. */
 declare function useCanvasKinds(): readonly AnyCanvasKind[];
 declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
+/**
+ * Offers `entry` in the canvas's "New tab" launcher while the calling
+ * component is mounted — a route registers what is about IT (a chat's
+ * documents, a table's saved views). Contextual entries show before the
+ * global kinds. A no-op outside a CanvasProvider.
+ */
+declare function useCanvasLauncherEntry(entry: CanvasLauncherEntry): void;
+/** Contextual launcher entries, latest registration of each `kind::key` only, in registration order. */
+declare function useCanvasLauncherEntries(): readonly CanvasLauncherEntry[];
 
 /** The column's rendered width in px for this window: 0 when put away, null when expanded. */
 declare function useCanvasColumnWidth(): number | null;
@@ -267,6 +329,31 @@ declare function CanvasToggle({ className, variant, }: {
     className?: string;
     variant?: "glass" | "transparent";
 }): react.JSX.Element;
+/** One icon of a `CanvasKindIcons` cluster. A string is a kind on its "default" tab. */
+interface CanvasKindIcon {
+    readonly kind: string;
+    /** Default "default" — one instance of the kind (a toolbar tool). */
+    readonly key?: string | undefined;
+    /** Data for a NEW item; an open one keeps its own. */
+    readonly data?: CanvasJson | undefined;
+    readonly title?: string | null | undefined;
+    /** What a press does while the item is in front: close it (default) or put the canvas away. */
+    readonly whenVisible?: "close" | "hide" | undefined;
+    /** Accessible name and tooltip. Default: the kind's label. */
+    readonly label?: string | undefined;
+}
+/**
+ * A cluster of icon buttons for pinned kinds — the tool icons of a header
+ * (Terminal, Review, Browser…). Each toggles or focuses its kind and is drawn
+ * pressed while its item is in front, so web and desktop show the same
+ * cluster. A kind that is not registered draws nothing.
+ */
+declare function CanvasKindIcons({ kinds, variant, className, label, }: {
+    kinds: readonly (string | CanvasKindIcon)[];
+    variant?: "glass" | "transparent";
+    className?: string;
+    label?: 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, expand handled.
@@ -276,6 +363,16 @@ declare function CanvasFrame({ children, className }: {
     className?: string;
 }): react.JSX.Element;
 
+/**
+ * The live presentation of the canvas body this component renders in: size,
+ * orientation, narrow, expanded, pane count. `null` outside the canvas — so a
+ * component used both on a page and in a canvas adapts only in the canvas.
+ *
+ *   const p = useCanvasPresentation();
+ *   const direction = preferredFlowDirection(p); // "vertical" in a tall narrow pane
+ */
+declare function useCanvasPresentation(): CanvasPresentation | null;
+
 declare function itemTitle(item: CanvasItem, kind: AnyCanvasKind | undefined): string;
 declare function CanvasPaneView({ paneId }: {
     paneId: CanvasPaneId;
@@ -382,4 +479,4 @@ interface BrowserBarProps {
 /** 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, useCanvasKindToggle, useCanvasKinds, useCanvasNativeBodies, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };
+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 CanvasKindIcon, CanvasKindIcons, type CanvasKindProps, type CanvasLauncherEntry, 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, useCanvasKindToggle, useCanvasKinds, useCanvasLauncherEntries, useCanvasLauncherEntry, useCanvasNativeBodies, useCanvasPresentation, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, ReactElement } from 'react';
-import { F as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, I as CanvasSessionEvent, G as CanvasSessionAttachReason, H as CanvasSessionDetachReason, e as CanvasStoreBinding, E as CanvasPersistencePort, w as CanvasErrorSink, z as CanvasLayoutRules, T as ToggleKindInput, y as CanvasKindVisibility, f as CanvasState } from './toggleKind-A9v45oSb.js';
+import { N as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, L as CanvasPresentation, Q as CanvasSessionEvent, O as CanvasSessionAttachReason, P as CanvasSessionDetachReason, K as CanvasPreferredTarget, e as CanvasStoreBinding, J as CanvasPersistencePort, A as CanvasErrorSink, E as CanvasLayoutRules, X as ToggleKindInput, D as CanvasKindVisibility, f as CanvasState } from './toggleKind-BD78LnMB.js';
 
 /** One floating thing. Plain data, so a host can draw it in another process. */
 type CanvasFloating = {
@@ -66,9 +66,21 @@ interface CanvasKindProps<TData extends CanvasJson = CanvasJson> {
     readonly data: TData;
     readonly paneId: CanvasPaneId;
     readonly isFocused: boolean;
+    /**
+     * On screen right now: its tab is active and its canvas is open. A body
+     * stays mounted while hidden (a background tab, a put-away canvas) — pause
+     * costly work (polling, animation) while this is false.
+     */
+    readonly isVisible: boolean;
     /** The canvas, acting for the window this pane is in. */
     readonly canvas: CanvasController;
     readonly windowId: CanvasWindowId;
+    /**
+     * The space this body has, live: size, orientation, narrow, expanded, pane
+     * count. Lay content out for it (a graph in a tall narrow pane flows top to
+     * bottom). Nested components read the same value with `useCanvasPresentation()`.
+     */
+    readonly presentation: CanvasPresentation;
 }
 interface CanvasMenuItem {
     readonly id: string;
@@ -105,8 +117,26 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     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). */
+    /**
+     * @deprecated Since 0.5.0 every body stays mounted from the first time it
+     * is shown until its tab closes — through tab switches, splits, moves,
+     * expand and the canvas being put away. This field changes nothing.
+     */
     readonly keepAlive?: boolean;
+    /**
+     * Opt OUT of staying mounted: the body unmounts whenever it is not on
+     * screen (a hidden tab, a put-away canvas) and mounts fresh when shown.
+     * Only for genuinely heavy bodies whose state is cheap to rebuild.
+     */
+    readonly unmountWhenHidden?: boolean;
+    /**
+     * Where a NEW item of this kind opens while the canvas already shows
+     * something: "split-down" puts it in a pane below (the layout rules' split
+     * share — a feed under the work), "split-right" beside, "focused" (default)
+     * in the focused pane. A pane already showing this kind takes it instead of
+     * a new split. A caller's explicit `target` always wins.
+     */
+    readonly preferredTarget?: CanvasPreferredTarget;
     /**
      * "native": the body is drawn by the HOST outside the DOM (an Electron
      * WebContentsView). The pane renders a placeholder and reports its rect
@@ -133,6 +163,13 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     readonly HeaderLeading?: ComponentType<CanvasKindProps<TData>>;
     /** The kind's own button, rendered left of the pane's "…" menu. */
     readonly HeaderAction?: ComponentType<CanvasKindProps<TData>>;
+    /**
+     * A toolbar ROW between the pane header and the body, for the active item
+     * only (a browser's back / forward / reload / address / screenshot). Always
+     * DOM, never covered by a native view: a `body: "native"` frame is measured
+     * BELOW it.
+     */
+    readonly Toolbar?: ComponentType<CanvasKindProps<TData>>;
     /** Kind-specific entries for the pane's "…" menu. */
     readonly menuItems?: (props: CanvasKindProps<TData>) => readonly CanvasMenuItem[];
 }
@@ -178,6 +215,22 @@ interface CanvasHostPorts {
     readonly onNativeBodyFrame?: CanvasNativeBodyFrame | undefined;
 }
 type CanvasTabStripMode = "auto" | "always";
+/**
+ * One contextual launcher entry: a page offers something about ITSELF in the
+ * canvas's "New tab" launcher ("This chat's documents" on a chat page) for as
+ * long as it is mounted. Shown before the global kinds.
+ */
+interface CanvasLauncherEntry {
+    readonly kind: string;
+    readonly key: string;
+    readonly data?: CanvasJson | undefined;
+    /** The entry's label (and the new tab's title). Default: the kind's label. */
+    readonly title?: string | null | undefined;
+    /** Default: the kind's icon. */
+    readonly icon?: ComponentType<{
+        className?: string;
+    }> | undefined;
+}
 interface CanvasProviderProps extends CanvasHostPorts {
     readonly children: ReactNode;
     /** A Redux-bound store (bindCanvasToReduxStore), a remote one (createRemoteCanvasStore), or omit for a standalone store. */
@@ -243,6 +296,15 @@ declare function useCanvasKindToggle(input: ToggleKindInput): {
 /** Re-renders when kinds register, so late-registered kinds appear. */
 declare function useCanvasKinds(): readonly AnyCanvasKind[];
 declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
+/**
+ * Offers `entry` in the canvas's "New tab" launcher while the calling
+ * component is mounted — a route registers what is about IT (a chat's
+ * documents, a table's saved views). Contextual entries show before the
+ * global kinds. A no-op outside a CanvasProvider.
+ */
+declare function useCanvasLauncherEntry(entry: CanvasLauncherEntry): void;
+/** Contextual launcher entries, latest registration of each `kind::key` only, in registration order. */
+declare function useCanvasLauncherEntries(): readonly CanvasLauncherEntry[];
 
 /** The column's rendered width in px for this window: 0 when put away, null when expanded. */
 declare function useCanvasColumnWidth(): number | null;
@@ -267,6 +329,31 @@ declare function CanvasToggle({ className, variant, }: {
     className?: string;
     variant?: "glass" | "transparent";
 }): react.JSX.Element;
+/** One icon of a `CanvasKindIcons` cluster. A string is a kind on its "default" tab. */
+interface CanvasKindIcon {
+    readonly kind: string;
+    /** Default "default" — one instance of the kind (a toolbar tool). */
+    readonly key?: string | undefined;
+    /** Data for a NEW item; an open one keeps its own. */
+    readonly data?: CanvasJson | undefined;
+    readonly title?: string | null | undefined;
+    /** What a press does while the item is in front: close it (default) or put the canvas away. */
+    readonly whenVisible?: "close" | "hide" | undefined;
+    /** Accessible name and tooltip. Default: the kind's label. */
+    readonly label?: string | undefined;
+}
+/**
+ * A cluster of icon buttons for pinned kinds — the tool icons of a header
+ * (Terminal, Review, Browser…). Each toggles or focuses its kind and is drawn
+ * pressed while its item is in front, so web and desktop show the same
+ * cluster. A kind that is not registered draws nothing.
+ */
+declare function CanvasKindIcons({ kinds, variant, className, label, }: {
+    kinds: readonly (string | CanvasKindIcon)[];
+    variant?: "glass" | "transparent";
+    className?: string;
+    label?: 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, expand handled.
@@ -276,6 +363,16 @@ declare function CanvasFrame({ children, className }: {
     className?: string;
 }): react.JSX.Element;
 
+/**
+ * The live presentation of the canvas body this component renders in: size,
+ * orientation, narrow, expanded, pane count. `null` outside the canvas — so a
+ * component used both on a page and in a canvas adapts only in the canvas.
+ *
+ *   const p = useCanvasPresentation();
+ *   const direction = preferredFlowDirection(p); // "vertical" in a tall narrow pane
+ */
+declare function useCanvasPresentation(): CanvasPresentation | null;
+
 declare function itemTitle(item: CanvasItem, kind: AnyCanvasKind | undefined): string;
 declare function CanvasPaneView({ paneId }: {
     paneId: CanvasPaneId;
@@ -382,4 +479,4 @@ interface BrowserBarProps {
 /** 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, useCanvasKindToggle, useCanvasKinds, useCanvasNativeBodies, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };
+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 CanvasKindIcon, CanvasKindIcons, type CanvasKindProps, type CanvasLauncherEntry, 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, useCanvasKindToggle, useCanvasKinds, useCanvasLauncherEntries, useCanvasLauncherEntry, useCanvasNativeBodies, useCanvasPresentation, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };