@hyperframes/studio 0.8.50 → 0.8.52

package/src/components/dock/Dock.tsx

@@ -0,0 +1,281 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+  DockviewReact,
+  type DockviewApi,
+  type DockviewReadyEvent,
+  type IDockviewPanelProps,
+} from "dockview-react";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { installDockAccessibility } from "./dockAccessibility";
+import { addRegisteredPanel, applySideMinimums, buildEditLayout } from "./dockLayout";
+import { DOCK_PANEL_COMPONENT } from "./dockLayoutSchema";
+import { useDockLayoutStore, type DockController, type DockSnapshot } from "./dockLayoutStore";
+import {
+  PANEL_DEFINITIONS,
+  PANEL_IDS,
+  isPanelId,
+  panelsInZone,
+  type PanelDefinition,
+  type PanelId,
+} from "./panelRegistry";
+import "./dock.css";
+
+const PERSIST_DEBOUNCE_MS = 250;
+
+type Slots = Partial<Record<PanelId, HTMLElement>>;
+
+interface SlotsContextValue {
+  slots: Slots;
+  registerSlot: (id: PanelId, element: HTMLElement | null) => void;
+}
+
+const SlotsContext = createContext<SlotsContextValue | null>(null);
+
+function useSlots(): SlotsContextValue {
+  const value = useContext(SlotsContext);
+  if (!value) throw new Error("Dock.Panel must be rendered inside Dock.Root");
+  return value;
+}
+
+/** The element dockview mounts for a panel; Dock.Panel portals the real content into it. */
+function PanelSlot({ api }: IDockviewPanelProps) {
+  const { registerSlot } = useSlots();
+  const id = api.id;
+  const ref = useCallback(
+    (element: HTMLDivElement | null) => {
+      if (isPanelId(id)) registerSlot(id, element);
+    },
+    [id, registerSlot],
+  );
+  return <div ref={ref} className="h-full w-full min-h-0 min-w-0 overflow-hidden" />;
+}
+
+const COMPONENTS = { [DOCK_PANEL_COMPONENT]: PanelSlot };
+
+function snapshot(api: DockviewApi): DockSnapshot {
+  const openPanels = new Set<PanelId>();
+  const visiblePanels = new Set<PanelId>();
+  for (const panel of api.panels) {
+    if (!isPanelId(panel.id)) continue;
+    openPanels.add(panel.id);
+    if (panel.api.isVisible && panel.group.api.isVisible) visiblePanels.add(panel.id);
+  }
+  const active = api.activePanel?.id;
+  return { openPanels, visiblePanels, activePanel: isPanelId(active) ? active : null };
+}
+
+function createController(api: DockviewApi): DockController {
+  const open = (id: PanelId) => {
+    if (api.getPanel(id)) return;
+    const { zone, reopen } = PANEL_DEFINITIONS[id];
+    // Side columns are tab groups; preview and timeline are separate groups in the centre.
+    const sibling =
+      zone === "center"
+        ? undefined
+        : panelsInZone(zone).find((other) => other !== id && api.getPanel(other));
+    if (sibling) {
+      addRegisteredPanel(api, id, { referencePanel: sibling, direction: "within" });
+      return;
+    }
+    const hasAnchor = api.getPanel(reopen.near) !== undefined;
+    const position = { referencePanel: reopen.near, direction: reopen.direction };
+    addRegisteredPanel(api, id, hasAnchor ? position : undefined);
+  };
+  return {
+    open,
+    activate: (id) => {
+      open(id);
+      api.getPanel(id)?.api.setActive();
+    },
+    close: (id) => {
+      const panel = api.getPanel(id);
+      if (panel) api.removePanel(panel);
+    },
+    setTitle: (id, title) => api.getPanel(id)?.api.setTitle(title),
+    setGroupVisible: (id, visible) => api.getPanel(id)?.group.api.setVisible(visible),
+    reset: () => buildEditLayout(api, window.innerWidth),
+  };
+}
+
+function restoreOrBuild(api: DockviewApi, projectId: string | null) {
+  const stored = readStudioUiPreferences(undefined, projectId).dockLayout;
+  if (stored) {
+    try {
+      api.fromJSON(stored);
+      return;
+    } catch {
+      /* a layout the schema accepted but dockview cannot load: start over */
+    }
+  }
+  buildEditLayout(api, window.innerWidth);
+}
+
+function Root({ projectId, children }: { projectId: string | null; children: ReactNode }) {
+  const [slots, setSlots] = useState<Slots>({});
+  const registerSlot = useCallback((id: PanelId, element: HTMLElement | null) => {
+    setSlots((prev) => {
+      if (prev[id] === (element ?? undefined)) return prev;
+      const next = { ...prev };
+      if (element) next[id] = element;
+      else delete next[id];
+      return next;
+    });
+  }, []);
+
+  const disposeRef = useRef<() => void>(() => {});
+  useEffect(() => () => disposeRef.current(), []);
+
+  const onReady = useCallback(
+    ({ api }: DockviewReadyEvent) => {
+      disposeRef.current();
+      restoreOrBuild(api, projectId);
+      applySideMinimums(api);
+      const root = api.groups[0]?.element.closest<HTMLElement>(".hf-dock");
+      const disposeAccessibility = root ? installDockAccessibility(api, root) : () => {};
+      // The dock spans the window (buildEditLayout sizes against it too); its own box lags a resize.
+      const resizeObserver = new ResizeObserver(() => applySideMinimums(api, window.innerWidth));
+      if (root) resizeObserver.observe(root);
+      const store = useDockLayoutStore.getState();
+      store.attach(createController(api));
+      store.sync(snapshot(api));
+      const pending = store.takePendingActivation();
+      if (pending) api.getPanel(pending)?.api.setActive();
+
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const persist = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+          writeStudioUiPreferences({ dockLayout: api.toJSON() }, undefined, projectId);
+        }, PERSIST_DEBOUNCE_MS);
+      };
+      // dockview does not fire onDidLayoutChange for add/remove/activate,
+      // so every event class is wired to the same sync+persist pair.
+      const onDockChange = () => {
+        useDockLayoutStore.getState().sync(snapshot(api));
+        persist();
+      };
+      const subscriptions = [
+        api.onDidAddPanel(() => {
+          applySideMinimums(api);
+          onDockChange();
+        }),
+        api.onDidMovePanel(() => {
+          applySideMinimums(api);
+          onDockChange();
+        }),
+        api.onDidRemovePanel(onDockChange),
+        api.onDidActivePanelChange(onDockChange),
+        api.onDidLayoutChange(onDockChange),
+      ];
+      disposeRef.current = () => {
+        clearTimeout(timer);
+        for (const subscription of subscriptions) subscription.dispose();
+        disposeAccessibility();
+        resizeObserver.disconnect();
+        useDockLayoutStore.getState().detach();
+      };
+    },
+    [projectId],
+  );
+
+  return (
+    <SlotsContext.Provider value={{ slots, registerSlot }}>
+      <DockviewReact
+        key={projectId ?? ""}
+        className="hf-dock flex-1 min-h-0"
+        components={COMPONENTS}
+        defaultRenderer="always"
+        disableFloatingGroups
+        onReady={onReady}
+      />
+      {children}
+    </SlotsContext.Provider>
+  );
+}
+
+function Panel({ id, title, children }: { id: PanelId; title?: string; children: ReactNode }) {
+  const element = useSlots().slots[id];
+  const visible = useDockLayoutStore((state) => state.visiblePanels.has(id));
+  const controller = useDockLayoutStore((state) => state.controller);
+  const label = title ?? PANEL_DEFINITIONS[id].title;
+  useEffect(() => {
+    controller?.setTitle(id, label);
+  }, [controller, id, label]);
+  const definition: PanelDefinition = PANEL_DEFINITIONS[id];
+  const shown = visible || definition.keepMounted;
+  return element && shown ? createPortal(children, element) : null;
+}
+
+function WindowMenu() {
+  const openPanels = useDockLayoutStore((state) => state.openPanels);
+  const togglePanel = useDockLayoutStore((state) => state.togglePanel);
+  const resetLayout = useDockLayoutStore((state) => state.resetLayout);
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const close = (event: PointerEvent) => {
+      if (!rootRef.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener("pointerdown", close);
+    return () => document.removeEventListener("pointerdown", close);
+  }, [open]);
+
+  return (
+    <div ref={rootRef} className="relative">
+      <button
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen((value) => !value)}
+        className="h-7 px-2.5 rounded-md text-[11px] font-medium text-neutral-400 hover:text-neutral-200 hover:bg-neutral-800 transition-colors"
+      >
+        Window
+      </button>
+      {open && (
+        <div
+          role="menu"
+          className="absolute right-0 top-8 z-50 w-44 rounded-md border border-neutral-800 bg-neutral-900 py-1 shadow-lg"
+        >
+          {PANEL_IDS.map((id) => (
+            <button
+              key={id}
+              type="button"
+              role="menuitemcheckbox"
+              aria-checked={openPanels.has(id)}
+              onClick={() => togglePanel(id)}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-neutral-300 hover:bg-neutral-800"
+            >
+              <span className="w-3 text-panel-accent">{openPanels.has(id) ? "✓" : ""}</span>
+              {PANEL_DEFINITIONS[id].title}
+            </button>
+          ))}
+          <div className="my-1 border-t border-neutral-800" />
+          <button
+            type="button"
+            role="menuitem"
+            onClick={() => {
+              resetLayout();
+              setOpen(false);
+            }}
+            className="w-full px-3 py-1.5 text-left text-[11px] text-neutral-300 hover:bg-neutral-800"
+          >
+            Reset layout
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export const Dock = { Root, Panel, WindowMenu };

package/src/components/dock/dock.css

@@ -0,0 +1,28 @@
+@import "dockview-react/dist/styles/dockview.css";
+
+.hf-dock {
+  --dv-group-view-background-color: var(--color-panel-bg);
+  --dv-tabs-and-actions-container-background-color: var(--color-panel-surface);
+  --dv-activegroup-visiblepanel-tab-background-color: var(--color-panel-bg);
+  --dv-activegroup-hiddenpanel-tab-background-color: var(--color-panel-surface);
+  --dv-inactivegroup-visiblepanel-tab-background-color: var(--color-panel-bg);
+  --dv-inactivegroup-hiddenpanel-tab-background-color: var(--color-panel-surface);
+  --dv-activegroup-visiblepanel-tab-color: var(--color-panel-text-1);
+  --dv-activegroup-hiddenpanel-tab-color: var(--color-panel-text-3);
+  --dv-inactivegroup-visiblepanel-tab-color: var(--color-panel-text-2);
+  --dv-inactivegroup-hiddenpanel-tab-color: var(--color-panel-text-4);
+  --dv-tab-divider-color: var(--color-panel-border);
+  --dv-separator-border: var(--color-panel-border);
+  --dv-paneview-header-border-color: var(--color-panel-border);
+  --dv-sash-color: var(--color-panel-hover);
+  --dv-active-sash-color: var(--color-panel-accent);
+  --dv-drag-over-background-color: color-mix(in srgb, var(--color-panel-accent) 12%, transparent);
+  --dv-drag-over-border-color: var(--color-panel-accent);
+  --dv-tab-font-size: 11px;
+  --dv-tabs-and-actions-container-font-size: 11px;
+}
+
+.hf-dock .dv-sash:focus-visible {
+  background-color: var(--dv-active-sash-color);
+  outline: none;
+}

package/src/components/dock/dockAccessibility.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment happy-dom
+
+import type { DockviewApi } from "dockview-react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mountBareDockview } from "./dockTestHarness";
+import { installDockAccessibility } from "./dockAccessibility";
+import { applySideMinimums, buildEditLayout } from "./dockLayout";
+
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = ResizeObserverStub;
+
+let host: HTMLElement;
+let api: DockviewApi;
+let dispose: () => void;
+
+beforeEach(() => {
+  ({ host, api } = mountBareDockview());
+  api.layout(1200, 700);
+  buildEditLayout(api, 1200);
+  applySideMinimums(api, 1200);
+  dispose = installDockAccessibility(api, host);
+});
+
+afterEach(() => {
+  dispose();
+  api.dispose();
+  document.body.innerHTML = "";
+});
+
+const sashes = () => [...host.querySelectorAll<HTMLElement>(".dv-sash")];
+const columnSash = (index: number) =>
+  sashes().filter((sash) => sash.getAttribute("aria-orientation") === "vertical")[
+    index
+  ] as HTMLElement;
+const widthOf = (panel: string) => api.getPanel(panel)?.group.width;
+const press = (target: Element, key: string, init: KeyboardEventInit = {}) =>
+  target.dispatchEvent(
+    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, ...init }),
+  );
+
+describe("dock sashes", () => {
+  it("are focusable separators with an orientation and a label", () => {
+    expect(sashes()).toHaveLength(3);
+    for (const sash of sashes()) {
+      expect(sash.getAttribute("role")).toBe("separator");
+      expect(sash.tabIndex).toBe(0);
+      const label = sash.getAttribute("aria-label");
+      const orientation = sash.getAttribute("aria-orientation");
+      expect(label).toBe(orientation === "vertical" ? "Resize columns" : "Resize rows");
+    }
+    expect(
+      sashes()
+        .map((sash) => sash.getAttribute("aria-orientation"))
+        .sort(),
+    ).toEqual(["horizontal", "vertical", "vertical"]);
+  });
+
+  it("are decorated again after a layout restore rebuilds them", () => {
+    api.fromJSON(api.toJSON());
+    expect(sashes()).toHaveLength(3);
+    for (const sash of sashes()) expect(sash.getAttribute("role")).toBe("separator");
+  });
+
+  it("resize the neighbouring groups by 16px per arrow press, 64px with Shift", () => {
+    const left = widthOf("compositions") as number;
+    const preview = widthOf("preview") as number;
+    const sash = columnSash(0);
+    press(sash, "ArrowRight");
+    expect(widthOf("compositions")).toBe(left + 16);
+    expect(widthOf("preview")).toBe(preview - 16);
+    press(sash, "ArrowRight", { shiftKey: true });
+    expect(widthOf("compositions")).toBe(left + 80);
+    press(sash, "ArrowLeft");
+    expect(widthOf("compositions")).toBe(left + 64);
+  });
+
+  it("stop at the panels' minimum sizes", () => {
+    const sash = columnSash(0);
+    for (let i = 0; i < 20; i++) press(sash, "ArrowLeft", { shiftKey: true });
+    expect(widthOf("compositions")).toBe(200);
+    for (let i = 0; i < 40; i++) press(sash, "ArrowRight", { shiftKey: true });
+    expect(widthOf("preview")).toBe(360);
+  });
+
+  it("ignore the arrow keys of the other axis and keys pressed anywhere else", () => {
+    const left = widthOf("compositions");
+    press(columnSash(0), "ArrowDown");
+    press(host, "ArrowRight");
+    press(document.body, "ArrowRight");
+    expect(widthOf("compositions")).toBe(left);
+  });
+
+  it("resize rows with the vertical arrows", () => {
+    const timeline = api.getPanel("timeline")?.group.height as number;
+    const rows = sashes().find((sash) => sash.getAttribute("aria-orientation") === "horizontal");
+    press(rows as HTMLElement, "ArrowUp");
+    expect(api.getPanel("timeline")?.group.height).toBe(timeline + 16);
+  });
+});
+
+describe("dock tab strips", () => {
+  const tabsOf = (panel: string) => [
+    ...(api.getPanel(panel)?.group.element.querySelectorAll<HTMLElement>('[role="tab"]') ?? []),
+  ];
+
+  it("keep dockview's tablist, tab and selected roles with one tab stop", () => {
+    const tabs = tabsOf("compositions");
+    expect(tabs).toHaveLength(4);
+    expect(tabs[0]?.closest('[role="tablist"]')).not.toBeNull();
+    expect(tabs.map((tab) => tab.getAttribute("aria-selected"))).toEqual([
+      "true",
+      "false",
+      "false",
+      "false",
+    ]);
+    expect(tabs.map((tab) => tab.tabIndex)).toEqual([0, -1, -1, -1]);
+  });
+
+  it("leave browser shortcuts alone when Alt, Ctrl or Meta is held", () => {
+    const sash = columnSash(0);
+    const left = widthOf("compositions");
+    const tab = tabsOf("compositions")[0] as HTMLElement;
+    const active = () => api.getPanel("compositions")?.group.activePanel?.id;
+    for (const init of [{ altKey: true }, { ctrlKey: true }, { metaKey: true }]) {
+      const onSash = new KeyboardEvent("keydown", {
+        key: "ArrowRight",
+        cancelable: true,
+        bubbles: true,
+        ...init,
+      });
+      sash.dispatchEvent(onSash);
+      press(tab, "ArrowRight", init);
+      expect(onSash.defaultPrevented).toBe(false);
+      expect(active()).toBe("compositions");
+    }
+    expect(widthOf("compositions")).toBe(left);
+  });
+
+  it("move focus and activate the neighbouring tab, wrapping at both ends", () => {
+    const tabs = tabsOf("compositions");
+    const active = () => api.getPanel("compositions")?.group.activePanel?.id;
+    (tabs[0] as HTMLElement).focus();
+    press(tabs[0] as HTMLElement, "ArrowRight");
+    expect(active()).toBe("assets");
+    expect(document.activeElement).toBe(tabs[1]);
+    press(tabs[1] as HTMLElement, "ArrowLeft");
+    press(tabs[0] as HTMLElement, "ArrowLeft");
+    expect(active()).toBe("catalog");
+    expect(document.activeElement).toBe(tabs[3]);
+    press(tabs[3] as HTMLElement, "ArrowRight");
+    expect(active()).toBe("compositions");
+  });
+
+  it("jump to the first and last tab with Home and End", () => {
+    const tabs = tabsOf("design");
+    press(tabs[0] as HTMLElement, "End");
+    expect(api.getPanel("design")?.group.activePanel?.id).toBe("variables");
+    expect(document.activeElement).toBe(tabs[3]);
+    press(tabs[3] as HTMLElement, "Home");
+    expect(api.getPanel("design")?.group.activePanel?.id).toBe("design");
+  });
+});

package/src/components/dock/dockAccessibility.ts

@@ -0,0 +1,98 @@
+import type { DockviewApi } from "dockview-react";
+
+const SASH_STEP = 16;
+const SASH_STEP_SHIFT = 64;
+
+type Axis = "horizontal" | "vertical";
+
+/** A horizontal split lays views left to right, so its sashes are vertical bars. */
+function splitAxis(sash: HTMLElement): Axis {
+  return sash.closest(".dv-split-view-container")?.classList.contains("dv-horizontal")
+    ? "horizontal"
+    : "vertical";
+}
+
+/** Dockview draws sashes as bare divs; make each one a focusable separator. */
+function decorateSashes(root: HTMLElement) {
+  for (const sash of root.querySelectorAll<HTMLElement>(".dv-sash")) {
+    const axis = splitAxis(sash);
+    sash.tabIndex = 0;
+    sash.setAttribute("role", "separator");
+    sash.setAttribute("aria-orientation", axis === "horizontal" ? "vertical" : "horizontal");
+    sash.setAttribute("aria-label", axis === "horizontal" ? "Resize columns" : "Resize rows");
+  }
+}
+
+/** Replays a pointer drag on the sash so dockview's own clamping to minimum sizes applies. */
+function nudgeSash(sash: HTMLElement, axis: Axis, delta: number) {
+  const at = (value: number) =>
+    axis === "horizontal" ? { clientX: value, clientY: 0 } : { clientX: 0, clientY: value };
+  const doc = sash.ownerDocument;
+  const fire = (target: EventTarget, type: string, value: number) =>
+    target.dispatchEvent(new MouseEvent(type, { ...at(value), bubbles: true, cancelable: true }));
+  fire(sash, "pointerdown", 0);
+  fire(doc, "pointermove", delta);
+  fire(doc, "pointerup", delta);
+}
+
+/** Browser and OS shortcuts (Alt+Left is Back) keep their meaning. */
+function hasShortcutModifier(event: KeyboardEvent) {
+  return event.altKey || event.ctrlKey || event.metaKey;
+}
+
+function onSashKeyDown(event: KeyboardEvent, sash: HTMLElement) {
+  if (hasShortcutModifier(event)) return;
+  const axis = splitAxis(sash);
+  const [less, more] =
+    axis === "horizontal" ? ["ArrowLeft", "ArrowRight"] : ["ArrowUp", "ArrowDown"];
+  if (event.key !== less && event.key !== more) return;
+  event.preventDefault();
+  const step = event.shiftKey ? SASH_STEP_SHIFT : SASH_STEP;
+  nudgeSash(sash, axis, event.key === more ? step : -step);
+}
+
+/** Wraps around and activates the tab it lands on, unlike dockview's focus-only arrows. */
+function onTabKeyDown(event: KeyboardEvent, tab: HTMLElement, api: DockviewApi) {
+  if (hasShortcutModifier(event)) return;
+  const tabs = [
+    ...(tab.closest('[role="tablist"]')?.querySelectorAll<HTMLElement>('[role="tab"]') ?? []),
+  ];
+  const index = tabs.indexOf(tab);
+  const last = tabs.length - 1;
+  const targets: Record<string, number> = {
+    ArrowRight: index === last ? 0 : index + 1,
+    ArrowLeft: index === 0 ? last : index - 1,
+    Home: 0,
+    End: last,
+  };
+  const target = tabs[targets[event.key] ?? -1];
+  if (!target) return;
+  event.preventDefault();
+  event.stopPropagation();
+  const panelId = target.dataset.tabPanelId;
+  if (panelId) api.getPanel(panelId)?.api.setActive();
+  target.focus();
+}
+
+/** Keyboard and ARIA support dockview 8.3 lacks for sashes and tab arrows. Returns a disposer. */
+export function installDockAccessibility(api: DockviewApi, root: HTMLElement): () => void {
+  const decorate = () => decorateSashes(root);
+  decorate();
+  const subscriptions = [
+    api.onDidLayoutChange(decorate),
+    api.onDidLayoutFromJSON(decorate),
+    api.onDidAddPanel(decorate),
+    api.onDidRemovePanel(decorate),
+  ];
+  // Capture phase so the tab handler runs before dockview's own focus-only arrows.
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (!(event.target instanceof HTMLElement)) return;
+    if (event.target.classList.contains("dv-sash")) onSashKeyDown(event, event.target);
+    else if (event.target.getAttribute("role") === "tab") onTabKeyDown(event, event.target, api);
+  };
+  root.addEventListener("keydown", onKeyDown, true);
+  return () => {
+    root.removeEventListener("keydown", onKeyDown, true);
+    for (const subscription of subscriptions) subscription.dispose();
+  };
+}