@ai-matrx/canvas 0.3.0 → 0.5.0

package/dist/{toggleKind-A9v45oSb.d.ts → toggleKind-BD78LnMB.d.ts}

@@ -37,6 +37,20 @@ type CanvasWindowId = string & {
     readonly [windowIdBrand]: true;
 };
 declare const CANVAS_MAIN_WINDOW: CanvasWindowId;
+/**
+ * Where a tab was before it navigated in place (`controller.navigate`). Plain
+ * JSON, so history persists with the layout; Back reopens the last entry.
+ */
+interface CanvasHistoryEntry {
+    readonly kind: string;
+    readonly key: string;
+    readonly title: string | null;
+    readonly data: CanvasJson;
+}
+/** The built-in "New tab" item: the launcher, shown as a tab. Never registered as a kind. */
+declare const CANVAS_LAUNCHER_KIND = "canvas.launcher";
+/** How many steps Back can go in one tab. Older entries fall off. */
+declare const CANVAS_HISTORY_LIMIT = 50;
 interface CanvasItem {
     readonly id: CanvasItemId;
     /** Registered kind id (see `registerCanvasKind`). */
@@ -48,6 +62,14 @@ interface CanvasItem {
     readonly data: CanvasJson;
     readonly openedAt: number;
     readonly updatedAt: number;
+    /** Earlier contents of this tab, oldest first (navigate in place). Absent = no Back. */
+    readonly history?: readonly CanvasHistoryEntry[] | undefined;
+    /**
+     * The mounted body's identity. Minted when the item is created and kept by
+     * `rekey`, so a draft that receives its durable id keeps its live body.
+     * Absent on items saved before 0.5.0 (the item id stands in).
+     */
+    readonly instance?: string | undefined;
 }
 interface CanvasPane {
     readonly id: CanvasPaneId;
@@ -122,6 +144,15 @@ interface CanvasState extends CanvasWindowFrame {
 type CanvasOpenTarget = "focused" | "split-right" | "split-down" | {
     readonly paneId: CanvasPaneId;
 };
+/** Where a NEW item of a kind prefers to open while the canvas already shows something. */
+type CanvasPreferredTarget = "focused" | "split-right" | "split-down";
+/** What a tab navigates to in place. */
+interface CanvasNavigateInput {
+    readonly kind: string;
+    readonly key: string;
+    readonly title?: string | null | undefined;
+    readonly data?: CanvasJson | undefined;
+}
 interface CanvasOpenInput {
     readonly kind: string;
     /** Which window a NEW item opens in. Default: the controller's window (main). An existing item stays where it is. */
@@ -184,6 +215,19 @@ type CanvasAction = {
         itemId: CanvasItemId;
         key: string;
     };
+} | {
+    type: `${typeof P}navigate`;
+    payload: {
+        itemId: CanvasItemId;
+        to: CanvasNavigateInput;
+        now: number;
+    };
+} | {
+    type: `${typeof P}back`;
+    payload: {
+        itemId: CanvasItemId;
+        now: number;
+    };
 } | {
     type: `${typeof P}closeItem`;
     payload: {
@@ -288,6 +332,10 @@ declare const canvasActions: {
     }) => 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;
+    /** Replaces a tab's content with another item in place, remembering what it showed (Back returns). */
+    readonly navigate: (itemId: CanvasItemId, to: CanvasNavigateInput) => CanvasAction;
+    /** Returns a tab to what it showed before its last navigate. */
+    readonly back: (itemId: CanvasItemId) => CanvasAction;
     readonly closeItem: (itemId: CanvasItemId) => CanvasAction;
     readonly closeOthers: (itemId: CanvasItemId) => CanvasAction;
     readonly activate: (itemId: CanvasItemId) => CanvasAction;
@@ -521,6 +569,11 @@ interface CanvasControllerOptions {
     readonly windowPorts?: (() => CanvasWindowPorts) | undefined;
     /** Session hooks for a kind, or undefined when the kind is not session-backed. */
     readonly sessions?: ((kind: string) => CanvasSessionHooks | undefined) | undefined;
+    /**
+     * Where a NEW item of a kind opens while the canvas already shows something
+     * (a kind's `preferredTarget`). An explicit `target` always wins.
+     */
+    readonly preferredTarget?: ((kind: string) => CanvasPreferredTarget | undefined) | undefined;
 }
 interface CanvasController {
     readonly store: CanvasStoreBinding;
@@ -537,6 +590,17 @@ interface CanvasController {
     }): 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;
+    /**
+     * Replaces a tab's content with another item IN PLACE and records history,
+     * so the pane header offers Back. Identity still holds: when the target is
+     * already open, it is focused where it is (a launcher tab then closes; any
+     * other tab keeps what it shows). Returns the item now shown, or null.
+     */
+    navigate(itemId: CanvasItemId, to: CanvasNavigateInput): CanvasItemId | null;
+    /** Returns a tab to what it showed before (see navigate). Null when it has no history. */
+    back(itemId: CanvasItemId): CanvasItemId | null;
+    /** Opens the launcher as a new tab in a pane (default: this window's focused pane), or focuses the one already there. */
+    newTab(paneId?: CanvasPaneId): CanvasItemId;
     close(itemId: CanvasItemId): void;
     closeOthers(itemId: CanvasItemId): void;
     activate(itemId: CanvasItemId): void;
@@ -573,6 +637,46 @@ interface CanvasController {
 }
 declare function createCanvasController(options: CanvasControllerOptions): CanvasController;
 
+/**
+ * Presentation — what a body knows about the space the canvas gives it.
+ *
+ * A body rendered in the canvas is told so, and told its live shape: a tall
+ * narrow pane is not a wide page. Content that lays itself out in a direction
+ * (a graph, a timeline, a row of cards) reads `orientation` and flows down a
+ * portrait pane instead of across it. Pure data and pure functions, so a
+ * desktop main process can compute the same answer for a native view.
+ */
+type CanvasPresentationOrientation = "portrait" | "landscape" | "square";
+interface CanvasPresentation {
+    /** Always "canvas" — a body rendered anywhere else gets no presentation at all. */
+    readonly host: "canvas";
+    /** The body's size in CSS pixels, live. */
+    readonly width: number;
+    readonly height: number;
+    readonly orientation: CanvasPresentationOrientation;
+    /** Narrower than `CANVAS_NARROW_WIDTH`: one column of content at most. */
+    readonly isNarrow: boolean;
+    /** The canvas is expanded to fill the space its host gives it. */
+    readonly isFullscreen: boolean;
+    /** How many panes the window's canvas shows right now. */
+    readonly paneCount: number;
+}
+/** Under this width (px) a body is narrow. */
+declare const CANVAS_NARROW_WIDTH = 480;
+declare function canvasOrientation(width: number, height: number): CanvasPresentationOrientation;
+declare function canvasPresentation(input: {
+    readonly width: number;
+    readonly height: number;
+    readonly isFullscreen: boolean;
+    readonly paneCount: number;
+}): CanvasPresentation;
+/**
+ * Which way content with a layout direction should flow: "vertical" (top to
+ * bottom) in a portrait or narrow body, "horizontal" (left to right) otherwise
+ * and outside the canvas.
+ */
+declare function preferredFlowDirection(presentation: CanvasPresentation | null | undefined): "vertical" | "horizontal";
+
 /**
  * "Toggle or focus this kind" — what a toolbar icon does (the desktop's
  * Terminal/Review/Browser icons, the web's quick-tool launchers):
@@ -602,4 +706,4 @@ interface ToggleKindInput {
 /** Returns what the item is after the click. */
 declare function toggleKind(controller: CanvasController, input: ToggleKindInput): CanvasKindVisibility;
 
-export { createLocalStorageCanvasPersistence as $, type CanvasOpenInput as A, type CanvasOpenTarget as B, type CanvasItemId as C, type CanvasOrientation as D, type CanvasPersistencePort as E, type CanvasRect as F, type CanvasSessionAttachReason as G, type CanvasSessionDetachReason as H, type CanvasSessionEvent as I, type CanvasSessionHooks as J, type CanvasSplitId as K, type CanvasWindowCloseMode as L, type CanvasWindowFrame as M, type CanvasWindowPorts as N, bindCanvasToReduxStore as O, canvasActions as P, canvasReducer as Q, type ReduxStoreLike as R, canvasWindowFrame as S, type ToggleKindInput as T, canvasWindowOfPane as U, clampDraggedCanvasWidth as V, consoleCanvasErrorSink as W, createCanvasController as X, createCanvasStore as Y, createInitialCanvasState as Z, createKeyValueCanvasPersistence as _, type CanvasWindowId as a, defaultCanvasWidth as a0, fitCanvasWidth as a1, foldCanvasWindows as a2, isCanvasAction as a3, listCanvasWindowIds as a4, resolveCanvasLayoutRules as a5, sanitizeCanvasSnapshot as a6, selectCanvasKindVisibility as a7, shouldStackSplit as a8, toPersistableSnapshot as a9, toggleKind as aa, type CanvasJson as b, type CanvasLayoutNode as c, type CanvasPaneId as d, type CanvasStoreBinding as e, type CanvasState as f, type CanvasAction as g, type CanvasController as h, type CanvasItem as i, type CanvasExtraWindow as j, type CanvasPane as k, canvasWindowOfItem as l, CANVAS_DEFAULT_KEY as m, CANVAS_DEFAULT_WIDTH as n, CANVAS_DESKTOP_LAYOUT_RULES as o, CANVAS_MAIN_WINDOW as p, CANVAS_MIN_SPLIT_FRACTION as q, CANVAS_MIN_WIDTH as r, CANVAS_STORAGE_KEY as s, CANVAS_WEB_LAYOUT_RULES as t, type CanvasControllerOptions as u, type CanvasErrorReport as v, type CanvasErrorSink as w, type CanvasKeyValueStore as x, type CanvasKindVisibility as y, type CanvasLayoutRules as z };
+export { canvasPresentation as $, type CanvasErrorSink as A, type CanvasKeyValueStore as B, type CanvasItemId as C, type CanvasKindVisibility as D, type CanvasLayoutRules as E, type CanvasNavigateInput as F, type CanvasOpenInput as G, type CanvasOpenTarget as H, type CanvasOrientation as I, type CanvasPersistencePort as J, type CanvasPreferredTarget as K, type CanvasPresentation as L, type CanvasPresentationOrientation as M, type CanvasRect as N, type CanvasSessionAttachReason as O, type CanvasSessionDetachReason as P, type CanvasSessionEvent as Q, type CanvasSessionHooks as R, type CanvasSplitId as S, type CanvasWindowCloseMode as T, type CanvasWindowFrame as U, type CanvasWindowPorts as V, type ReduxStoreLike as W, type ToggleKindInput as X, bindCanvasToReduxStore as Y, canvasActions as Z, canvasOrientation as _, type CanvasWindowId as a, canvasReducer as a0, canvasWindowFrame as a1, canvasWindowOfPane as a2, clampDraggedCanvasWidth as a3, consoleCanvasErrorSink as a4, createCanvasController as a5, createCanvasStore as a6, createInitialCanvasState as a7, createKeyValueCanvasPersistence as a8, createLocalStorageCanvasPersistence as a9, defaultCanvasWidth as aa, fitCanvasWidth as ab, foldCanvasWindows as ac, isCanvasAction as ad, listCanvasWindowIds as ae, preferredFlowDirection as af, resolveCanvasLayoutRules as ag, sanitizeCanvasSnapshot as ah, selectCanvasKindVisibility as ai, shouldStackSplit as aj, toPersistableSnapshot as ak, toggleKind as al, type CanvasJson as b, type CanvasLayoutNode as c, type CanvasPaneId as d, type CanvasStoreBinding as e, type CanvasState as f, type CanvasAction as g, type CanvasController as h, type CanvasItem as i, type CanvasExtraWindow as j, type CanvasHistoryEntry as k, type CanvasPane as l, canvasWindowOfItem as m, CANVAS_DEFAULT_KEY as n, CANVAS_DEFAULT_WIDTH as o, CANVAS_DESKTOP_LAYOUT_RULES as p, CANVAS_HISTORY_LIMIT as q, CANVAS_LAUNCHER_KIND as r, CANVAS_MAIN_WINDOW as s, CANVAS_MIN_SPLIT_FRACTION as t, CANVAS_MIN_WIDTH as u, CANVAS_NARROW_WIDTH as v, CANVAS_STORAGE_KEY as w, CANVAS_WEB_LAYOUT_RULES as x, type CanvasControllerOptions as y, type CanvasErrorReport as z };

package/dist/tokens.css

@@ -32,6 +32,9 @@
   --mxc-radius: 10px;
   --mxc-gap: 6px;
   --mxc-header-h: 2.25rem;
+  /* THE canvas motion (the shell sidebar's slide). A host reflowing beside the column uses the same pair. */
+  --mxc-motion-duration: 600ms;
+  --mxc-motion-ease: cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 @media (prefers-color-scheme: dark) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/canvas",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The AI Matrx canvas: a docked right-hand column with split panes, tabs, full screen, a kind registry, Redux-compatible state and persistence.",
   "type": "module",
   "main": "./dist/index.cjs",