@pauloricca/spagbol 0.0.0-stage → 0.1.0

package/src/react/SpagbolCanvasControls.tsx

@@ -0,0 +1,255 @@
+import { useReactFlow } from "@xyflow/react";
+import { isGroupBoundary } from "../core/index.js";
+import { useRef, useState, type ReactNode } from "react";
+import { SpagbolControlZoom } from "./SpagbolControlZoom.js";
+import { SpagbolCanvasMenu } from "./SpagbolCanvasMenu.js";
+import { useEditorSnapshot, useSpagbol } from "./context.js";
+
+export interface SpagbolCanvasAction {
+  id: string;
+  label: ReactNode;
+  ariaLabel?: string;
+  title?: string;
+  disabled?: boolean;
+  checked?: boolean;
+  onSelect(): void | Promise<void>;
+}
+export interface SpagbolCanvasMenuSeparator {
+  id: string;
+  separator: true;
+}
+export type SpagbolCanvasMenuItem =
+  | SpagbolCanvasAction
+  | SpagbolCanvasMenuSeparator;
+export interface SpagbolCanvasControlsOptions {
+  /** Host actions beside the menu; history buttons follow these by default. */
+  buttons?: readonly SpagbolCanvasAction[];
+  menuItems?: readonly SpagbolCanvasMenuItem[];
+  menuLabel?: string;
+  leading?: ReactNode;
+  zoomExtra?: ReactNode;
+  showZoom?: boolean;
+  showHistory?: boolean;
+  showLayoutLock?: boolean;
+  showBreadcrumbs?: boolean;
+  onActionError?(error: unknown, action: SpagbolCanvasAction): void;
+}
+const labelFor = (action: SpagbolCanvasAction) =>
+  action.ariaLabel ??
+  (typeof action.label === "string" ? action.label : action.id);
+
+/** Standard zoom stack and percentage/reset button, independent of app actions. */
+export function SpagbolCanvasControlsZoom({ extra }: { extra?: ReactNode }) {
+  const { zoom } = useSpagbol();
+  return (
+    <SpagbolControlZoom
+      className="spagbol-canvas-controls-zoom"
+      zoom={zoom}
+      extra={extra}
+      layout="corner"
+    />
+  );
+}
+
+/** Teia/visual-visual corner menu. Domain actions stay in the consumer. */
+export function SpagbolCanvasActions(options: SpagbolCanvasControlsOptions) {
+  const flow = useReactFlow();
+  const scale = (factor: number) => editor.scaleSelection(factor, new Map(flow.getNodes().filter(node => node.id.startsWith("node:")).map(node => [node.id.slice(5), { width: node.measured?.width ?? node.width ?? 180, height: node.measured?.height ?? node.height ?? 100 }])));
+  const { editor } = useSpagbol();
+  const snapshot = useEditorSnapshot(editor);
+  const [busy, setBusy] = useState<ReadonlySet<string>>(new Set());
+  const busyRef = useRef(new Set<string>());
+  const [error, setError] = useState<string | null>(null);
+  const buttons: SpagbolCanvasAction[] = [
+    ...(snapshot.path.length
+      ? [
+          {
+            id: "spagbol:exit",
+            label: "EXIT",
+            ariaLabel: "Exit nested graph",
+            onSelect: () => editor.exit(),
+          },
+        ]
+      : []),
+    ...(options.buttons ?? []),
+    ...(options.showHistory === false
+      ? []
+      : [
+          {
+            id: "spagbol:undo",
+            label: "UNDO",
+            ariaLabel: "Undo",
+            title: "Undo (Cmd/Ctrl+Z)",
+            disabled: !snapshot.canUndo || !editor.editing,
+            onSelect: () => editor.undo(),
+          },
+          {
+            id: "spagbol:redo",
+            label: "REDO",
+            ariaLabel: "Redo",
+            title: "Redo (Cmd/Ctrl+Shift+Z)",
+            disabled: !snapshot.canRedo || !editor.editing,
+            onSelect: () => editor.redo(),
+          },
+        ]),
+  ];
+  const members = editor.graph.nodes.filter(node => snapshot.selection.nodeIds.includes(node.id) && !isGroupBoundary(node));
+  const exposed = editor.graph.data?.exposedNodeIds;
+  const exposureChecked = members.length > 0 && Array.isArray(exposed) && members.every(node => exposed.includes(node.id));
+  const items: SpagbolCanvasMenuItem[] = [
+    { id: 'spagbol:group', label: 'GROUP TO SUBPATCH', ariaLabel: 'Group to subpatch', disabled: !editor.editing || !members.length, onSelect: () => { editor.groupSelection(); } },
+
+    { id: 'spagbol:scale-up', label: 'SCALE UP SELECTION', disabled: !editor.editing || !snapshot.selection.nodeIds.length, onSelect: () => scale(2) },
+    { id: 'spagbol:scale-down', label: 'SCALE DOWN SELECTION', disabled: !editor.editing || !snapshot.selection.nodeIds.length, onSelect: () => scale(0.5) },
+    ...(options.menuItems ?? []),
+    ...(options.showLayoutLock === false
+      ? []
+      : [
+          {
+            id: "spagbol:lock",
+            label: "LOCK UI",
+            ariaLabel: snapshot.mode === "edit" ? "Lock UI" : "Unlock UI",
+            checked: snapshot.mode !== "edit",
+            disabled: snapshot.mode === "readonly",
+            onSelect: () =>
+              editor.setMode(editor.editing ? "controls" : "edit"),
+          },
+        ]),
+  ];
+  const hasMenu = items.some((item) => !("separator" in item));
+  async function invoke(action: SpagbolCanvasAction, fromMenu: boolean) {
+    if (action.disabled || busyRef.current.has(action.id)) return;
+    busyRef.current.add(action.id);
+    setBusy(new Set(busyRef.current));
+    setError(null);
+    try {
+      await action.onSelect();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+      options.onActionError?.(cause, action);
+    } finally {
+      busyRef.current.delete(action.id);
+      setBusy(new Set(busyRef.current));
+    }
+  }
+  function actionButton(action: SpagbolCanvasAction, fromMenu = false) {
+    return (
+      <button
+        key={action.id}
+        type="button"
+        role={
+          fromMenu
+            ? action.checked === undefined
+              ? "menuitem"
+              : "menuitemcheckbox"
+            : undefined
+        }
+        aria-label={labelFor(action)}
+        title={action.title ?? labelFor(action)}
+        disabled={action.disabled || busy.has(action.id)}
+        aria-busy={busy.has(action.id) || undefined}
+        aria-checked={fromMenu ? action.checked : undefined}
+        aria-pressed={fromMenu ? undefined : action.checked}
+        onClick={() => {
+          void invoke(action, fromMenu);
+        }}
+      >
+        {action.checked !== undefined && fromMenu ? (
+          <span className="spagbol-canvas-menu-check" aria-hidden="true">
+            {action.checked ? "✓" : ""}
+          </span>
+        ) : null}
+        {action.label}
+      </button>
+    );
+  }
+  return (
+    <div
+      className="spagbol-canvas-actions nodrag nopan"
+      role="group"
+      aria-label="Canvas actions"
+      onPointerDown={(event) => event.stopPropagation()}
+      onDoubleClick={(event) => event.stopPropagation()}
+      onKeyDown={(event) => event.stopPropagation()}
+    >
+      {options.leading && (
+        <div className="spagbol-canvas-actions-leading">{options.leading}</div>
+      )}
+      {buttons.map((action) => actionButton(action))}
+      {hasMenu && (
+        <SpagbolCanvasMenu
+          label={
+            <>
+              {options.menuLabel ?? "MORE"} <span aria-hidden="true">ˆ</span>
+            </>
+          }
+        >
+          {items.map((item) =>
+            "separator" in item ? (
+              <div
+                key={item.id}
+                role="separator"
+                className="spagbol-canvas-menu-separator"
+              />
+            ) : (
+              actionButton(item, true)
+            ),
+          )}
+        </SpagbolCanvasMenu>
+      )}
+      {error && (
+        <div className="spagbol-canvas-actions-error" role="alert">
+          {error}
+          <button
+            type="button"
+            aria-label="Dismiss action error"
+            onClick={() => setError(null)}
+          >
+            ×
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function SpagbolCanvasControls(options: SpagbolCanvasControlsOptions) {
+  const { editor } = useSpagbol();
+  const snapshot = useEditorSnapshot(editor);
+  return (
+    <>
+      {options.showBreadcrumbs !== false && snapshot.path.length > 0 && (
+        <nav
+          className="spagbol-canvas-breadcrumbs nodrag nopan"
+          aria-label="Graph navigation"
+          onPointerDown={(event) => event.stopPropagation()}
+          onKeyDown={(event) => event.stopPropagation()}
+        >
+          <button type="button" onClick={() => editor.navigate([])}>
+            ROOT
+          </button>
+          {snapshot.path.map((id, index) => (
+            <button
+              key={`${index}:${id}`}
+              type="button"
+              aria-current={
+                index === snapshot.path.length - 1 ? "page" : undefined
+              }
+              onClick={() => editor.navigate(snapshot.path.slice(0, index + 1))}
+            >
+              {id}
+            </button>
+          ))}
+        </nav>
+      )}
+      <div
+        className={`spagbol-canvas-controls${options.showZoom === false ? " spagbol-canvas-controls-no-zoom" : ""}`}
+      >
+        {options.showZoom !== false && (
+          <SpagbolCanvasControlsZoom extra={options.zoomExtra} />
+        )}
+        <SpagbolCanvasActions {...options} />
+      </div>
+    </>
+  );
+}

package/src/react/SpagbolCanvasFlow.tsx

@@ -0,0 +1,38 @@
+import {
+  Background,
+  ReactFlow,
+  type Node,
+  type Edge,
+  type ReactFlowProps,
+} from "@xyflow/react";
+
+/** Controlled integration boundary for hosts with an existing graph controller.
+ * Node/edge payloads and all edit callbacks belong to the host. Use inside a
+ * ReactFlowProvider so specialised host nodes retain access to the flow store.
+ */
+export type SpagbolCanvasFlowProps<
+  N extends Node = Node,
+  E extends Edge = Edge,
+> = ReactFlowProps<N, E> & {
+  grid?: false | { color?: string; gap?: number; size?: number };
+};
+export function SpagbolCanvasFlow<
+  N extends Node = Node,
+  E extends Edge = Edge,
+>({ grid, children, className, ...props }: SpagbolCanvasFlowProps<N, E>) {
+  return (
+    <ReactFlow<N, E>
+      {...props}
+      className={`spagbol-canvas-flow ${className ?? ""}`}
+    >
+      {children}
+      {grid !== false && (
+        <Background
+          color={grid?.color ?? "var(--spagbol-grid, rgba(255,255,255,0.08))"}
+          gap={grid?.gap ?? 28}
+          size={grid?.size ?? 1}
+        />
+      )}
+    </ReactFlow>
+  );
+}

package/src/react/SpagbolCanvasLinkControls.tsx

@@ -0,0 +1,21 @@
+import type { CSSProperties } from 'react';
+import { standardLinkModes } from '../core/index.js';
+import { SpagbolControlNumberLink } from './SpagbolControlNumberLink.js';
+export interface SpagbolCanvasLinkControlsProps {
+  weight: number; mode: string; enabled: boolean; style?: CSSProperties;
+  modes?: readonly { id: string; label: string }[];
+  onWeightChange(value: number): void;
+  onModeChange(mode: string): void;
+  onEnabledChange(enabled: boolean): void;
+}
+export function SpagbolCanvasLinkControls({ weight, mode, enabled, style, modes = standardLinkModes, onWeightChange, onModeChange, onEnabledChange }: SpagbolCanvasLinkControlsProps) {
+  return <div className="spagbol-canvas-link-controls nodrag nopan" style={style} onPointerDown={event => event.stopPropagation()} onDoubleClick={event => event.stopPropagation()}>
+    <div className="spagbol-canvas-link-controls-value-row">
+      <SpagbolControlNumberLink value={weight} onChange={onWeightChange} />
+      <button className={`spagbol-canvas-link-controls-enabled nodrag nopan${enabled ? ' spagbol-canvas-link-controls-enabled-active' : ''}`} type="button" onClick={event => { event.stopPropagation(); onEnabledChange(!enabled); }} onPointerDown={event => event.stopPropagation()} onMouseDown={event => event.stopPropagation()} onDoubleClick={event => event.stopPropagation()} aria-label={enabled ? 'Disable link' : 'Enable link'} aria-pressed={enabled} title={enabled ? 'Disable link' : 'Enable link'} />
+    </div>
+    <select className="spagbol-canvas-link-controls-mode nodrag nopan" value={mode} onChange={event => { onModeChange(event.target.value); event.currentTarget.blur(); }} onPointerDown={event => event.stopPropagation()} onMouseDown={event => event.stopPropagation()} onDoubleClick={event => event.stopPropagation()} aria-label="Link mode" title="Link mode">
+      {modes.map(item => <option key={item.id} value={item.id}>{item.label}</option>)}
+    </select>
+  </div>;
+}

package/src/react/SpagbolCanvasMenu.tsx

@@ -0,0 +1,121 @@
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+
+export interface SpagbolCanvasMenuProps {
+  children: ReactNode;
+  label?: ReactNode;
+  ariaLabel?: string;
+  className?: string;
+  menuClassName?: string;
+  triggerClassName?: string;
+}
+/** Controller-independent menu mechanics; the host owns actions and styling. */
+export function SpagbolCanvasMenu({
+  children,
+  label = "MORE ˆ",
+  ariaLabel = "More actions",
+  className,
+  menuClassName,
+  triggerClassName,
+}: SpagbolCanvasMenuProps) {
+  const [open, setOpen] = useState(false);
+  const wrapper = useRef<HTMLDivElement>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  const menu = useRef<HTMLDivElement>(null);
+  const id = useId();
+  function close(restoreFocus = false) {
+    if (restoreFocus) trigger.current?.focus();
+    setOpen(false);
+  }
+  useEffect(() => {
+    if (!open) return;
+    const outside = (event: PointerEvent) => {
+      if (
+        event.target instanceof Node &&
+        !wrapper.current?.contains(event.target)
+      )
+        setOpen(false);
+    };
+    document.addEventListener("pointerdown", outside, true);
+    return () => document.removeEventListener("pointerdown", outside, true);
+  }, [open]);
+  return (
+    <div
+      ref={wrapper}
+      className={`spagbol-canvas-menu ${className ?? ""}`}
+      data-open={open}
+      onMouseEnter={() => setOpen(true)}
+      onMouseLeave={() => setOpen(false)}
+      onBlur={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget)) close();
+      }}
+      onKeyDown={(event) => {
+        event.stopPropagation();
+        if (event.key === "Escape") {
+          event.preventDefault();
+          close(true);
+        }
+        if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+          event.preventDefault();
+          setOpen(true);
+          const key = event.key;
+          requestAnimationFrame(() => {
+            const buttons = Array.from(
+              menu.current?.querySelectorAll<HTMLButtonElement>(
+                "button:not(:disabled)",
+              ) ?? [],
+            );
+            const current = buttons.indexOf(
+              document.activeElement as HTMLButtonElement,
+            );
+            const index =
+              key === "Home"
+                ? 0
+                : key === "End"
+                  ? buttons.length - 1
+                  : current < 0
+                    ? key === "ArrowDown"
+                      ? 0
+                      : buttons.length - 1
+                    : (current +
+                        (key === "ArrowDown" ? 1 : -1) +
+                        buttons.length) %
+                      buttons.length;
+            buttons[index]?.focus();
+          });
+        }
+      }}
+    >
+      <button
+        ref={trigger}
+        className={`spagbol-canvas-menu-trigger ${triggerClassName ?? ""}`}
+        type="button"
+        aria-haspopup="menu"
+        aria-controls={id}
+        aria-expanded={open}
+        aria-label={ariaLabel}
+        title={ariaLabel}
+        onFocus={() => setOpen(true)}
+        onClick={() => setOpen(true)}
+      >
+        {label}
+      </button>
+      <div
+        ref={menu}
+        id={id}
+        className={`spagbol-canvas-menu-items ${menuClassName ?? ""}`}
+        role="menu"
+        aria-label={ariaLabel}
+        hidden={!open}
+        onClick={(event) => {
+          const button =
+            event.target instanceof Element
+              ? event.target.closest("button")
+              : null;
+          if (button && !button.disabled) close(true);
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}