@ai-matrx/canvas 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- **Toggle or focus a kind** — what a toolbar icon or a quick-tool launcher does. `toggleKind(controller, { kind, key?, data?, title?, whenVisible? })`: absent → open and reveal; behind another tab or canvas put away → bring it forward; in front → close it (default) or put the canvas away (`whenVisible: "hide"`). `data` seeds only a new item. `selectCanvasKindVisibility(state, kind, key?)` returns `"absent" | "background" | "visible"` (a primitive — safe in useSyncExternalStore / useSelector), and the React hook `useCanvasKindToggle(input)` gives `{ visibility, isOpen, isVisible, toggle }` for an icon button's active state. Key defaults to `CANVAS_DEFAULT_KEY` ("default").
+
+### Consumer action
+
+- Replace any host-side "open or focus this panel" helper with `toggleKind` / `useCanvasKindToggle` (desktop toolbar icons; web quick-tool launchers).
+
 ## 0.2.2
 
 - `CanvasToggle` takes `variant` (`"transparent"` default, or `"glass"`). The tap-target placement rules forbid one plain icon in a glass row; a host whose header buttons are glass passes `variant="glass"` so the toggle matches them.

package/README.md

@@ -38,6 +38,17 @@ defineCanvasKind<{ sessionKey: string }>({
 
 `body: "native"` makes the body a placeholder whose frame the host receives (below).
 
+## Toolbar icons: toggle or focus a kind
+
+```tsx
+const terminal = useCanvasKindToggle({ kind: "terminal" });
+<button aria-pressed={terminal.isVisible} onClick={terminal.toggle}>…</button>
+// outside React (Electron main, a menu handler):
+toggleKind(controller, { kind: "terminal" }); // absent → open · behind → focus · in front → close
+```
+
+`whenVisible: "hide"` puts the canvas away instead of closing the tab.
+
 ## 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.

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  CANVAS_DEFAULT_KEY: () => CANVAS_DEFAULT_KEY,
   CANVAS_DEFAULT_WIDTH: () => CANVAS_DEFAULT_WIDTH,
   CANVAS_DESKTOP_LAYOUT_RULES: () => CANVAS_DESKTOP_LAYOUT_RULES,
   CANVAS_MAIN_WINDOW: () => CANVAS_MAIN_WINDOW,
@@ -67,6 +68,7 @@ __export(src_exports, {
   selectCanvasIsOpen: () => selectCanvasIsOpen,
   selectCanvasItem: () => selectCanvasItem,
   selectCanvasItemCount: () => selectCanvasItemCount,
+  selectCanvasKindVisibility: () => selectCanvasKindVisibility,
   selectCanvasLayout: () => selectCanvasLayout,
   selectCanvasPane: () => selectCanvasPane,
   selectCanvasPaneCount: () => selectCanvasPaneCount,
@@ -76,7 +78,8 @@ __export(src_exports, {
   selectCanvasWindows: () => selectCanvasWindows,
   shareStructure: () => shareStructure,
   shouldStackSplit: () => shouldStackSplit,
-  toPersistableSnapshot: () => toPersistableSnapshot
+  toPersistableSnapshot: () => toPersistableSnapshot,
+  toggleKind: () => toggleKind
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -1394,4 +1397,42 @@ function selectCanvasWindows(s) {
 }
 var selectCanvasExtraWindow = (s, windowId) => s.windows?.[windowId];
 var selectCanvasWindowOfItem = canvasWindowOfItem;
+
+// src/core/toggleKind.ts
+var CANVAS_DEFAULT_KEY = "default";
+function selectCanvasKindVisibility(state, kind, key = CANVAS_DEFAULT_KEY) {
+  const itemId = canvasItemId(kind, key);
+  if (!state.items[itemId]) return "absent";
+  const windowId = canvasWindowOfItem(state, itemId);
+  if (!windowId) return "background";
+  const isOpen = canvasWindowFrame(state, windowId)?.isOpen ?? false;
+  const pane = Object.values(state.panes).find((p) => p.itemIds.includes(itemId));
+  return isOpen && pane?.activeItemId === itemId ? "visible" : "background";
+}
+function toggleKind(controller, input) {
+  const key = input.key ?? CANVAS_DEFAULT_KEY;
+  const itemId = canvasItemId(input.kind, key);
+  const before = selectCanvasKindVisibility(controller.getState(), input.kind, key);
+  if (before === "visible") {
+    if ((input.whenVisible ?? "close") === "close") {
+      controller.close(itemId);
+    } else {
+      controller.hide(canvasWindowOfItem(controller.getState(), itemId) ?? void 0);
+    }
+    return selectCanvasKindVisibility(controller.getState(), input.kind, key);
+  }
+  if (before === "background") {
+    controller.open({ kind: input.kind, key });
+    const windowId = canvasWindowOfItem(controller.getState(), itemId);
+    if (windowId) controller.show(windowId);
+    return selectCanvasKindVisibility(controller.getState(), input.kind, key);
+  }
+  const opened = controller.open({
+    kind: input.kind,
+    key,
+    ...input.data !== void 0 ? { data: input.data } : {},
+    ...input.title !== void 0 ? { title: input.title } : {}
+  });
+  return opened ? selectCanvasKindVisibility(controller.getState(), input.kind, key) : "absent";
+}
 //# sourceMappingURL=index.cjs.map