@ai-matrx/canvas 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.0
+
+One canvas for the web app and the desktop app: the package now owns the pane chrome everywhere and carries what an Electron host needs (a store in the main process, native views, several windows).
+
+- **Chrome.** Panes are drawn with THE canvas chrome, ported from the design-system app shell: rounded cards on the column's frame background separated by gaps that are the split handles, a 36px header (title for a single tab, the tab strip for several), a per-kind leading slot, the kind's own button, "…", Expand, Close. Exported for hosts that frame their own panels: `CanvasPanel`, `CanvasPanelEmpty`, `CanvasHeaderButton`, `CanvasMenuTrigger`, `CanvasTab`, `BrowserTabs`, `BrowserBar` (same props as the design-system components they replace). The design-system copies are deleted (design-system 0.53.0).
+- **Layout rules.** `layoutRules` on `CanvasProvider` / `createCanvasController` (`CANVAS_WEB_LAYOUT_RULES` default, `CANVAS_DESKTOP_LAYOUT_RULES`): default width in px or as a fraction of the region, canvas min, centre min (the canvas shrinks first), the split-down share (desktop 70/30), the split-right share, and `paneMinWidth` under which side-by-side panes stack. `regionWidth` tells the provider the space the canvas shares (desktop: right of the sidebar). Pure helpers `fitCanvasWidth`, `clampDraggedCanvasWidth`, `shouldStackSplit` for a main process.
+- **Native-body kinds.** `body: "native"`: the pane renders a placeholder and reports its frame through `onNativeBodyFrame(itemId, rect | null, { visible, windowId })` in window CSS px with `devicePixelRatio`, in the same frame as any split, resize, expand or tab switch; null when hidden or gone; `visible: false` while package DOM floats over it (a DOM menu, a tab drag). `useCanvasNativeBodies().remeasure()` for host animations.
+- **Floating things are ports.** `showMenu(entries, anchor) → Promise<id | null>` draws the "…" menu (default: the package's DOM menu); `overlay.show(element) → remove` draws tooltips, drop indicators and tab drags (default: a DOM layer). Header tooltips now come from the package (no tap-target tooltip in the pane).
+- **Shortcuts as data.** `CANVAS_SHORTCUTS` (`{ id, accelerator, when, label, web }`), `runCanvasCommand(controller, id)`, `matchesCanvasAccelerator`, `canvasShortcutHint`. The provider binds the web-safe ones; ⌘W / Ctrl+Tab / Ctrl+Shift+Tab are desktop-only. New: Expand (⌘⇧Enter), Split right (⌘⌥\\), Split down (⌘⌥⇧\\), all only while focus is in the canvas.
+- **Remote store.** `createRemoteCanvasStore({ initialSnapshot, dispatch, subscribe, onError })` for a renderer bound to a main-process store: async dispatch, whole snapshots merged with `shareStructure` so unchanged slices keep their identity. A controller over it never hydrates or saves. `createKeyValueCanvasPersistence(kv)` is the main-process memory over any key-value store.
+- **Windows.** `CanvasWindowId`, `CANVAS_MAIN_WINDOW`, `state.windows` (the top-level frame fields stay the main window's). `CanvasProvider windowId`, `CanvasWindowScope`, `controller.forWindow(id)`, window-aware actions and selectors. Windows other than main are not restored: their tabs fold home.
+- **Pop-out.** Host ports `popOut(item) → Promise<{ windowId } | null>` and `dockBack(itemId, fromWindowId)`; `controller.popOut / dockBack / closeWindow`; reducer actions `popOut`, `dockBack`, `closeWindow(windowId, "dock" | "close")`. Without a port a pop-out is refused aloud (`pop-out-unavailable`) and no "Pop out" entry shows; a refusal reports `pop-out-refused`.
+- **Session-keyed restore.** `restore: "session"` with `sessionKey` (default `data.sessionKey`), `onAttach` (`open` · `restore` · `arrive`) and `onDetach` (`close` · `leave` · `unmount`). Hook failures report `session-hook`.
+- **Placeholder kinds.** `unavailable(data) → string | null` shows the honest one-line state in place of the body.
+- **Menu.** "Close tab" is always in "…"; "Dock back" replaces "Pop out" in a pop-out window.
+
+### Consumer action
+
+- `state.width` is `number | null` (null until the person drags; the layout rule decides). Read widths through `useCanvasColumnWidth()` / `fitCanvasWidth`, never `state.width` directly.
+- `CanvasState` has a required `windows` map; build states with `createInitialCanvasState()` / the reducer, never by hand.
+- `selectCanvasLayout` and `selectCanvasFocusedPaneId` return `null` for an unknown window; `selectCanvasItemCount` still counts every window (`selectCanvasWindowItemCount` counts one).
+- The `popOut` port now returns `Promise<{ windowId } | null>` and the package moves the item; a host that passed the old `(item) => void` must adopt the new contract.
+- Map the new tokens (or import `@ai-matrx/canvas/tokens.css`, which now follows a design-system theme): `--mxc-frame-bg`, `--mxc-title-fg`, `--mxc-disabled`, `--mxc-handle-hover`, `--mxc-tab-active-shadow`, `--mxc-input-bg`, `--mxc-ring`, `--mxc-tooltip-bg`, `--mxc-tooltip-fg`, `--mxc-float-shadow`, `--mxc-radius`, `--mxc-gap`. `--mxc-header-h` defaults to 2.25rem.
+- `CanvasKindProps` carries `windowId`; a kind that builds the props itself must pass it.
+- Hosts importing `CanvasPanel`, `CanvasPanelEmpty`, `BrowserTabs` or `BrowserBar` from `@ai-matrx/design-system` import them from `@ai-matrx/canvas/react` and add `@ai-matrx/canvas/styles.css`.
+
 ## 0.1.1
 
 - Build core and React declarations together so branded pane IDs, stores and controllers retain one type identity across entries.

package/README.md

@@ -1,10 +1,10 @@
 # @ai-matrx/canvas
 
-A docked right-hand canvas column with split panes, tabs, fullscreen, identity-based deduplication and persisted layout. Core state is framework-independent; React components ship through `./react`.
+A docked right-hand canvas column with split panes, tabs, expand, identity-based deduplication, persisted layout and ONE pane chrome. Core state is framework-independent (it runs in an Electron main process); React components ship through `./react`.
 
 ```tsx
 import "@ai-matrx/canvas/styles.css";
-import "@ai-matrx/canvas/tokens.css";
+import "@ai-matrx/canvas/tokens.css"; // follows a design-system theme; else built-in light/dark values
 import { CanvasProvider, CanvasFrame, CanvasToggle, registerCanvasKind, defineCanvasKind } from "@ai-matrx/canvas/react";
 
 registerCanvasKind(defineCanvasKind({ id: "note", label: "Note", icon: NoteIcon, load: () => import("./NoteView") }));
@@ -14,8 +14,118 @@ registerCanvasKind(defineCanvasKind({ id: "note", label: "Note", icon: NoteIcon,
 </CanvasProvider>
 ```
 
-`NoteIcon`, `NoteView` and `App` are your host components. A Redux host passes `store={bindCanvasToReduxStore(store, (s) => s.canvasHost)}` after mounting `canvasReducer`. Hosts own identity, navigation and token values; the package owns layout, pane/tab behavior and restoration.
+`NoteIcon`, `NoteView` and `App` are your host components. A Redux host passes `store={bindCanvasToReduxStore(store, (s) => s.canvasHost)}` after mounting `canvasReducer`. Hosts own identity, navigation, placement and token values; the package owns layout, pane/tab behavior, chrome and restoration. Item data must be plain JSON; failures are reported through `onError`.
 
-Entries: core (`.`), React (`./react`), structural CSS (`./styles.css`) and optional default theme values (`./tokens.css`). Item data must be plain JSON; failures are reported through `onError`.
+Entries: core (`.`), React (`./react`), structural CSS (`./styles.css`) and default theme values (`./tokens.css`).
+
+## A kind
+
+```tsx
+defineCanvasKind<{ sessionKey: string }>({
+  id: "terminal",
+  label: "Terminal",
+  icon: TerminalIcon,
+  load: () => import("./TerminalView"),
+  restore: "session",          // closing detaches; a restore or a move reattaches
+  onAttach: ({ sessionKey, reason }) => attach(sessionKey, reason),
+  onDetach: ({ sessionKey }) => detach(sessionKey), // never kill here
+  keepAlive: true,
+  HeaderLeading: NewTerminalButton, // "+ new terminal", a browser bar…
+  HeaderAction: ClearButton,
+  unavailable: () => (backendUp() ? null : "Terminal · next release"),
+});
+```
+
+`body: "native"` makes the body a placeholder whose frame the host receives (below).
+
+## Chrome for panels a host frames itself
+
+`CanvasPanel` (title or `header`, `leading`, `actions`, `renderMenu`, `onToggleExpand`, `onClose`), `CanvasPanelEmpty`, `CanvasHeaderButton`, `CanvasTab`, `BrowserTabs`, `BrowserBar` — the same components every canvas pane draws with. They render outside a provider too.
+
+## Layout rules
+
+```tsx
+<CanvasProvider layoutRules={CANVAS_DESKTOP_LAYOUT_RULES} regionWidth={windowWidth - railAndSidebar}>
+```
+
+| Rule | Web (default) | Desktop |
+|---|---|---|
+| `defaultWidth` | 640 | `{ fraction: 0.36 }` |
+| `minWidth` | 360 | 360 |
+| `centreMinWidth` (the canvas shrinks first) | 420 | 520 |
+| `stackSplit` (split down: first pane's share) | 0.5 | 0.7 |
+| `sideSplit` | 0.5 | 0.5 |
+| `paneMinWidth` (narrower side-by-side panes stack) | 0 (never) | 360 |
+
+Expand is one flag per window; it fills whatever the host placed the column in (`useCanvasColumnWidth()` returns `null`).
+
+## Electron
+
+One store in the main process; every window's renderer is a client.
+
+```ts
+// main
+import { createCanvasStore, createCanvasController, createKeyValueCanvasPersistence, isCanvasAction,
+  CANVAS_DESKTOP_LAYOUT_RULES, CANVAS_SHORTCUTS, runCanvasCommand } from "@ai-matrx/canvas";
+
+const store = createCanvasStore();
+const canvas = createCanvasController({
+  store,
+  persistence: createKeyValueCanvasPersistence({ get: (k) => kv.get(k), set: (k, v) => kv.set(k, v) }),
+  layoutRules: CANVAS_DESKTOP_LAYOUT_RULES,
+  isRestorable: (kind) => kind !== "browser", // main has no kind registry: name the kinds that never come back
+});
+canvas.start(); // hydrates, then autosaves
+
+ipcMain.handle("canvas:get", () => store.getState());
+ipcMain.handle("canvas:dispatch", (_e, action: unknown) => { if (isCanvasAction(action)) store.dispatch(action); });
+store.subscribe(() => { for (const w of BrowserWindow.getAllWindows()) w.webContents.send("canvas:snapshot", store.getState()); });
+
+// Shortcuts as data: bind them where keys inside native views still arrive.
+for (const s of CANVAS_SHORTCUTS) { /* menu accelerator or before-input-event → */ runCanvasCommand(canvas.forWindow(windowIdOf(win)), s.id); }
+// A BrowserWindow that closes: its tabs go home.
+win.on("closed", () => canvas.closeWindow(windowIdOf(win)));
+```
+
+```tsx
+// renderer (one per window)
+import { createRemoteCanvasStore } from "@ai-matrx/canvas";
+
+const store = createRemoteCanvasStore({
+  initialSnapshot: await ipcRenderer.invoke("canvas:get"),
+  dispatch: (action) => ipcRenderer.invoke("canvas:dispatch", action),
+  subscribe: (onSnapshot) => {
+    const on = (_e: unknown, s: CanvasState) => onSnapshot(s);
+    ipcRenderer.on("canvas:snapshot", on);
+    return () => ipcRenderer.off("canvas:snapshot", on);
+  },
+});
+
+<CanvasProvider
+  store={store}                    // remote: the main process hydrates and saves
+  windowId={myWindowId}            // "main" for the first window
+  layoutRules={CANVAS_DESKTOP_LAYOUT_RULES}
+  regionWidth={rightOfSidebar}
+  hotkeys={false}                  // main binds CANVAS_SHORTCUTS
+  onNativeBodyFrame={(itemId, rect, { visible }) => ipc.send("view:place", itemId, visible ? rect : null)}
+  showMenu={(entries, anchor) => ipc.invoke("menu:popup", entries, anchor)}   // Menu.popup → chosen id
+  overlay={{ show: (el) => { ipc.send("overlay:show", el); return () => ipc.send("overlay:hide", el); } }}
+  popOut={(item) => ipc.invoke("canvas:pop-out", item.id)}                    // → { windowId } of a new BrowserWindow
+>
+  <CanvasColumn />  {/* a pop-out window renders <CanvasColumn placement="fill" /> */}
+</CanvasProvider>
+```
+
+Rects are window CSS pixels with `devicePixelRatio`, reported in the frame the layout changed (layout effects + ResizeObserver). Call `useCanvasNativeBodies().remeasure()` per animation frame while the host animates its own layout. `visible: false` means package DOM floats over the view (a DOM menu or a tab drag): hide it so the DOM is seen and receives the drop.
+
+## Web pop-out
+
+```tsx
+popOut={async (item) => { const id = `pop-${item.id}`; openFloatingPanel(id); return { windowId: id }; }}
+// the floating panel:
+<CanvasWindowScope windowId={id}><CanvasColumn placement="fill" /></CanvasWindowScope>
+```
+
+When a pop-out window disappears from `state.windows` (docked back, last tab closed), close its panel.
 
 MIT.