@ai-matrx/canvas 0.2.2 → 0.4.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 { 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';
+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';
 
 /** One floating thing. Plain data, so a host can draw it in another process. */
 type CanvasFloating = {
@@ -133,6 +133,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[];
 }
@@ -230,6 +237,16 @@ declare function useCanvasState<T>(selector: (state: CanvasState) => T): T;
  * embed). `fallback` must be referentially stable (a primitive or null).
  */
 declare function useOptionalCanvasState<T>(selector: (state: CanvasState) => T, fallback: T): T;
+/**
+ * A toolbar icon's view of one kind: "absent" | "background" | "visible"
+ * (a primitive, so it never loops), plus the click that toggles or focuses it.
+ */
+declare function useCanvasKindToggle(input: ToggleKindInput): {
+    readonly visibility: CanvasKindVisibility;
+    readonly isOpen: boolean;
+    readonly isVisible: boolean;
+    readonly toggle: () => CanvasKindVisibility;
+};
 /** Re-renders when kinds register, so late-registered kinds appear. */
 declare function useCanvasKinds(): readonly AnyCanvasKind[];
 declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
@@ -372,4 +389,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, 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 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 };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 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.js';
+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';
 
 /** One floating thing. Plain data, so a host can draw it in another process. */
 type CanvasFloating = {
@@ -133,6 +133,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[];
 }
@@ -230,6 +237,16 @@ declare function useCanvasState<T>(selector: (state: CanvasState) => T): T;
  * embed). `fallback` must be referentially stable (a primitive or null).
  */
 declare function useOptionalCanvasState<T>(selector: (state: CanvasState) => T, fallback: T): T;
+/**
+ * A toolbar icon's view of one kind: "absent" | "background" | "visible"
+ * (a primitive, so it never loops), plus the click that toggles or focuses it.
+ */
+declare function useCanvasKindToggle(input: ToggleKindInput): {
+    readonly visibility: CanvasKindVisibility;
+    readonly isOpen: boolean;
+    readonly isVisible: boolean;
+    readonly toggle: () => CanvasKindVisibility;
+};
 /** Re-renders when kinds register, so late-registered kinds appear. */
 declare function useCanvasKinds(): readonly AnyCanvasKind[];
 declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
@@ -372,4 +389,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, 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 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 };

package/dist/react.js

@@ -1220,6 +1220,44 @@ function selectCanvasWindowItemCount(s, windowId) {
 }
 var NO_WINDOWS = Object.freeze({});
 
+// 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";
+}
+
 // src/react/layer.tsx
 import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import { createPortal } from "react-dom";
@@ -1519,6 +1557,17 @@ function useOptionalCanvasState(selector, fallback) {
   const read = () => store ? selector(store.getState()) : fallback;
   return useSyncExternalStore2(store ? store.subscribe : NO_SUBSCRIPTION, read, read);
 }
+function useCanvasKindToggle(input) {
+  const controller = useCanvasContext().controller;
+  const key = input.key ?? CANVAS_DEFAULT_KEY;
+  const visibility = useCanvasState((s) => selectCanvasKindVisibility(s, input.kind, key));
+  return {
+    visibility,
+    isOpen: visibility !== "absent",
+    isVisible: visibility === "visible",
+    toggle: () => toggleKind(controller, input)
+  };
+}
 function useCanvasKinds() {
   useSyncExternalStore2(subscribeCanvasKinds, getCanvasKindsVersion, getCanvasKindsVersion);
   return listCanvasKinds();
@@ -1959,6 +2008,7 @@ function CanvasPaneView({ paneId }) {
   const kindProps = active && kind ? { item: active, data: active.data, paneId, isFocused: focused, canvas, windowId } : null;
   const Leading = kind?.HeaderLeading;
   const Action = kind?.HeaderAction;
+  const Toolbar = kind?.Toolbar;
   const single = tabStrip === "auto" && pane.itemIds.length === 1 && active;
   const hideDrop = () => {
     drop.current?.();
@@ -1985,7 +2035,7 @@ function CanvasPaneView({ paneId }) {
     canvas.moveItem(itemId, paneId);
   };
   const closeLabel = role === "pop-out" && paneCount === 1 ? "Close window" : paneCount > 1 ? "Close pane" : "Close canvas";
-  return /* @__PURE__ */ jsx5(
+  return /* @__PURE__ */ jsxs4(
     CanvasPanel,
     {
       ref: sectionRef,
@@ -2010,15 +2060,30 @@ function CanvasPaneView({ paneId }) {
       onDragOver,
       onDragLeave,
       onDrop,
-      children: pane.itemIds.length === 0 ? /* @__PURE__ */ jsx5(Launcher, { paneId }) : pane.itemIds.map((itemId) => {
-        const item = items[itemId];
-        if (!item) return null;
-        const isActive = itemId === pane.activeItemId;
-        return /* @__PURE__ */ jsx5(ItemBody, { item, paneId, windowId, isActive, isFocused: focused && isActive, hasNativePort: !!ports.onNativeBodyFrame }, itemId);
-      })
+      children: [
+        Toolbar && kindProps ? /* @__PURE__ */ jsx5("div", { className: "mxc-item-toolbar", "data-kind": active?.kind, children: /* @__PURE__ */ jsx5(ToolbarBoundary, { kindId: kind?.id ?? "", children: /* @__PURE__ */ jsx5(Toolbar, { ...kindProps }) }) }) : null,
+        pane.itemIds.length === 0 ? /* @__PURE__ */ jsx5(Launcher, { paneId }) : pane.itemIds.map((itemId) => {
+          const item = items[itemId];
+          if (!item) return null;
+          const isActive = itemId === pane.activeItemId;
+          return /* @__PURE__ */ jsx5(ItemBody, { item, paneId, windowId, isActive, isFocused: focused && isActive, hasNativePort: !!ports.onNativeBodyFrame }, itemId);
+        })
+      ]
     }
   );
 }
+var ToolbarBoundary = class extends Component {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error) {
+    console.error(`[@ai-matrx/canvas] "${this.props.kindId}" Toolbar threw`, error);
+  }
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+};
 function SingleTitle({ item, kind }) {
   const title = itemTitle(item, kind);
   const drag = useTabDrag(item.id, title);
@@ -2534,6 +2599,7 @@ export {
   useCanvasHostPorts,
   useCanvasIsPresented,
   useCanvasKind,
+  useCanvasKindToggle,
   useCanvasKinds,
   useCanvasNativeBodies,
   useCanvasState,