@hyperframes/studio 0.8.50 → 0.8.52

package/src/components/ui/Menu.test.tsx

@@ -0,0 +1,374 @@
+// @vitest-environment happy-dom
+/** Menu, ContextMenu and Popover: key/aria behaviour, dismissal, and that emitted classes resolve. */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import React, { act, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { compile } from "tailwindcss";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { loadStylesheet, STYLES_DIR } from "../../styles/styleSources";
+import { ContextMenu, Menu, MenuItem, MenuRadioGroup, MenuRadioItem, MenuSeparator } from "./Menu";
+import { Popover } from "./Popover";
+import { isTypingTarget } from "../../utils/typingTarget";
+import { shouldIgnorePlaybackShortcutTarget } from "../../player/lib/playbackShortcuts";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let mounted: { root: Root; host: HTMLElement } | null = null;
+
+function render(element: React.ReactElement): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  act(() => root.render(element));
+  return host;
+}
+
+afterEach(() => {
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+/** Base UI moves focus into the popup one task after open, not synchronously. */
+async function settle(): Promise<void> {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+function press(target: Element): void {
+  // `composed` is what a real browser sets: without it the event never crosses
+  // a shadow boundary and Base UI's document listener never sees it.
+  const init = { bubbles: true, cancelable: true, composed: true };
+  act(() => {
+    target.dispatchEvent(new PointerEvent("pointerdown", init));
+    target.dispatchEvent(new MouseEvent("mousedown", init));
+  });
+}
+
+/**
+ * A mouse click, spelled out: bare `.click()` reads as keyboard activation to Base UI,
+ * which pre-highlights the first item and shifts every arrow-key assertion by one.
+ */
+function clickWithMouse(target: Element): void {
+  const init = { bubbles: true, cancelable: true, composed: true, detail: 1 };
+  act(() => {
+    target.dispatchEvent(new PointerEvent("pointerdown", { ...init, pointerType: "mouse" }));
+    target.dispatchEvent(new MouseEvent("mousedown", init));
+    target.dispatchEvent(new PointerEvent("pointerup", { ...init, pointerType: "mouse" }));
+    target.dispatchEvent(new MouseEvent("mouseup", init));
+    target.dispatchEvent(new MouseEvent("click", init));
+  });
+}
+
+function key(k: string, target: Element | null = document.activeElement): void {
+  const init = { key: k, bubbles: true, cancelable: true, composed: true };
+  act(() => {
+    (target ?? document.body).dispatchEvent(new KeyboardEvent("keydown", init));
+    (target ?? document.body).dispatchEvent(new KeyboardEvent("keyup", init));
+  });
+}
+
+function one<T extends Element>(selector: string, what: string): T {
+  const el = document.querySelector<T>(selector);
+  if (!el) throw new Error(`${what} not rendered`);
+  return el;
+}
+
+const trigger = () => one<HTMLElement>('[data-testid="trigger"]', "trigger");
+const popup = () => document.querySelector<HTMLElement>('[role="menu"]');
+const items = () => [...document.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+
+/** A Studio element menu: actions, a hairline, a destructive item; `disabled` marks the passed label. */
+function ActionMenu({
+  activated,
+  disable,
+}: {
+  activated: string[];
+  disable?: string;
+}): React.JSX.Element {
+  return (
+    <Menu trigger={<button data-testid="trigger">Actions</button>} aria-label="Element actions">
+      <MenuItem shortcut="⌘]" onClick={() => activated.push("front")}>
+        Bring to front
+      </MenuItem>
+      <MenuItem disabled={disable === "group"} onClick={() => activated.push("group")}>
+        Group
+      </MenuItem>
+      <MenuSeparator />
+      <MenuItem tone="danger" shortcut="⌫" onClick={() => activated.push("delete")}>
+        Delete
+      </MenuItem>
+    </Menu>
+  );
+}
+
+async function openActionMenu(activated: string[] = [], disable?: string): Promise<void> {
+  render(<ActionMenu activated={activated} disable={disable} />);
+  clickWithMouse(trigger());
+  await settle();
+  expect(popup()).not.toBeNull();
+}
+
+describe("Menu behaviour", () => {
+  // AE5.
+  it("activates the second item with ArrowDown twice then Enter, and closes", async () => {
+    const activated: string[] = [];
+    await openActionMenu(activated);
+
+    key("ArrowDown");
+    key("ArrowDown");
+    key("Enter");
+    await settle();
+
+    expect(activated).toEqual(["group"]);
+    expect(popup()).toBeNull();
+  });
+
+  it("does not activate a disabled item, and the arrow keys reach past it", async () => {
+    const activated: string[] = [];
+    await openActionMenu(activated, "group");
+
+    const [, disabled, last] = items();
+    expect(disabled.getAttribute("data-disabled")).not.toBeNull();
+    expect(disabled.getAttribute("aria-disabled")).toBe("true");
+
+    // Base UI keeps a disabled item in the roving sequence (the ARIA menu
+    // pattern: a disabled command stays discoverable). So the guarantee is not
+    // that the highlight skips it, it is that nothing runs when it is aimed at
+    // directly, by key or by pointer.
+    key("ArrowDown");
+    key("ArrowDown");
+    expect(disabled.getAttribute("data-highlighted")).not.toBeNull();
+    key("Enter", disabled);
+    act(() => disabled.click());
+    await settle();
+
+    expect(activated).toEqual([]);
+    expect(popup()).not.toBeNull();
+
+    // And the item after it is still reachable, so a disabled row is not a wall.
+    key("ArrowDown");
+    key("Enter");
+    await settle();
+
+    expect(activated).toEqual(["delete"]);
+    expect(last.isConnected).toBe(false);
+  });
+
+  it("renders a shortcut hint that assistive tech does not read as a label", async () => {
+    await openActionMenu();
+
+    const hint = one<HTMLElement>('[role="menuitem"] span[aria-hidden="true"]', "shortcut hint");
+
+    expect(hint.textContent).toBe("⌘]");
+    expect(items()[0].textContent).toContain("Bring to front");
+  });
+
+  it("closes on an outside press that a parent stops in the bubble phase", async () => {
+    // U3's finding, on the shipped component: the canvas overlay swallows
+    // bubble-phase pointer events, and Base UI's dismissal listens in capture.
+    const swallow = (event: React.SyntheticEvent) => event.stopPropagation();
+    render(
+      <div onPointerDown={swallow} onMouseDown={swallow}>
+        <div data-testid="overlay" aria-label="Composition canvas">
+          overlay
+        </div>
+        <Menu trigger={<button data-testid="trigger">Actions</button>} aria-label="Actions">
+          <MenuItem>Bring to front</MenuItem>
+        </Menu>
+      </div>,
+    );
+    act(() => trigger().click());
+    await settle();
+    expect(popup()).not.toBeNull();
+
+    // Witness: a bubble-phase document listener is the thing the overlay
+    // starves. If it starts firing, the press stopped being swallowed and this
+    // test would pass for a reason that says nothing about capture-phase
+    // dismissal.
+    let sawBubblePress = false;
+    const witness = () => {
+      sawBubblePress = true;
+    };
+    document.addEventListener("pointerdown", witness);
+    press(one('[data-testid="overlay"]', "overlay"));
+    document.removeEventListener("pointerdown", witness);
+
+    expect(sawBubblePress).toBe(false);
+    expect(popup()).toBeNull();
+  });
+});
+
+describe("MenuRadioGroup", () => {
+  it("selects one item and unselects the rest, and reports aria-checked", async () => {
+    function SpeedMenu(): React.JSX.Element {
+      const [rate, setRate] = useState(1);
+      return (
+        <Menu trigger={<button data-testid="trigger">{rate}x</button>} aria-label="Playback speed">
+          <MenuRadioGroup value={rate} onValueChange={(next) => setRate(next as number)}>
+            {[0.5, 1, 2].map((speed) => (
+              <MenuRadioItem key={speed} value={speed}>
+                {speed}x
+              </MenuRadioItem>
+            ))}
+          </MenuRadioGroup>
+        </Menu>
+      );
+    }
+    render(<SpeedMenu />);
+    act(() => trigger().click());
+    await settle();
+
+    const radios = () => [...document.querySelectorAll<HTMLElement>('[role="menuitemradio"]')];
+    const checked = () => radios().filter((el) => el.getAttribute("aria-checked") === "true");
+
+    expect(radios()).toHaveLength(3);
+    expect(checked().map((el) => el.textContent)).toEqual(["1x"]);
+
+    act(() => radios()[2].click());
+    await settle();
+
+    expect(checked().map((el) => el.textContent)).toEqual(["2x"]);
+    expect(trigger().textContent).toBe("2x");
+  });
+});
+
+describe("ContextMenu", () => {
+  it("opens on a right click over its area and closes when an item runs", async () => {
+    const activated: string[] = [];
+    render(
+      <ContextMenu
+        aria-label="Clip actions"
+        trigger={
+          <div data-testid="trigger">
+            <span>clip</span>
+          </div>
+        }
+      >
+        <MenuItem onClick={() => activated.push("split")}>Split</MenuItem>
+      </ContextMenu>,
+    );
+
+    // The trigger renders the caller's element and keeps its children.
+    expect(trigger().textContent).toBe("clip");
+    expect(popup()).toBeNull();
+
+    act(() => {
+      trigger().dispatchEvent(
+        new MouseEvent("contextmenu", { bubbles: true, cancelable: true, composed: true }),
+      );
+    });
+    await settle();
+    expect(popup()).not.toBeNull();
+
+    act(() => items()[0].click());
+    await settle();
+
+    expect(activated).toEqual(["split"]);
+    expect(popup()).toBeNull();
+  });
+});
+
+describe("Popover", () => {
+  it("leaves the keys of a text field inside it alone", async () => {
+    // The Menu owns ArrowDown and typeahead; a Popover must not, or the rename
+    // field in AssetContextMenu would lose its own caret keys.
+    render(
+      <Popover trigger={<button data-testid="trigger">Rename</button>} aria-label="Rename asset">
+        <input data-testid="rename" defaultValue="scene1" />
+      </Popover>,
+    );
+    act(() => trigger().click());
+    await settle();
+
+    const input = one<HTMLInputElement>('[data-testid="rename"]', "rename field");
+    act(() => input.focus());
+    expect(document.activeElement).toBe(input);
+
+    key("ArrowDown");
+    key("ArrowUp");
+    key("s");
+    await settle();
+
+    expect(document.activeElement).toBe(input);
+    expect(document.querySelector('[role="menu"]')).toBeNull();
+  });
+});
+
+describe("hotkey classification", () => {
+  it("classifies menu rows and popover contents the way the menus they replace were", async () => {
+    // `typingTarget` and `playbackShortcuts` match exact role strings; Base UI renders
+    // a `<div>` with those roles, so the roles alone must carry the classification.
+    render(
+      <>
+        <Menu trigger={<button data-testid="trigger">Actions</button>} aria-label="Actions">
+          <MenuItem>Split</MenuItem>
+          <MenuRadioGroup value={1}>
+            <MenuRadioItem value={1}>1x</MenuRadioItem>
+          </MenuRadioGroup>
+        </Menu>
+      </>,
+    );
+    act(() => trigger().click());
+    await settle();
+
+    const row = one('[role="menuitem"]', "menu item");
+    const radio = one('[role="menuitemradio"]', "radio item");
+
+    for (const el of [row, radio]) {
+      expect(isTypingTarget(el)).toBe(false);
+      expect(shouldIgnorePlaybackShortcutTarget(el)).toBe(true);
+    }
+  });
+
+  it("treats a field inside a Popover as somewhere the user is typing", async () => {
+    render(
+      <Popover trigger={<button data-testid="trigger">Rename</button>} aria-label="Rename asset">
+        <input data-testid="rename" defaultValue="scene1" />
+      </Popover>,
+    );
+    act(() => trigger().click());
+    await settle();
+
+    const input = one('[data-testid="rename"]', "rename field");
+
+    expect(isTypingTarget(input)).toBe(true);
+    expect(shouldIgnorePlaybackShortcutTarget(input)).toBe(true);
+  });
+});
+
+/**
+ * Class resolution is covered by `styles/tokenGate.test.ts`; this checks what the compiled rule
+ * does (AE4).
+ */
+describe("open motion", () => {
+  let compileStudioCss: (candidates: string[]) => string;
+
+  beforeAll(async () => {
+    const compiled = await compile(readFileSync(path.join(STYLES_DIR, "studio.css"), "utf8"), {
+      base: STYLES_DIR,
+      // Tailwind's signature wants a promise; the shared resolver is sync.
+      loadStylesheet: async (id, base) => loadStylesheet(id, base),
+    });
+    compileStudioCss = (candidates) => compiled.build(candidates);
+  });
+
+  // AE4.
+  it("names a motion token that zeroes itself under reduced motion", async () => {
+    // The zero-duration case lives in the `duration-open` utility itself
+    // (theme.css), not in a `motion-reduce:` class beside it, so a caller
+    // cannot use the token and forget the reduced-motion half. The menu's job
+    // is to name the token; the stylesheet's job is the media query.
+    await openActionMenu();
+
+    expect([...popup()!.classList]).toContain("duration-open");
+    expect(compileStudioCss(["duration-open"])).toMatch(
+      /\.duration-open \{[\s\S]*?prefers-reduced-motion: reduce[\s\S]*?transition-duration: 0ms/,
+    );
+  });
+});

package/src/components/ui/Menu.tsx

@@ -0,0 +1,213 @@
+/**
+ * Menu and ContextMenu on Base UI. Dismissal is plain Base UI (capture-phase listeners survive the overlay's
+ * `stopPropagation`); `trigger` is rendered, not wrapped; `container` exists for shadow roots.
+ */
+
+import { ContextMenu as BaseContextMenu } from "@base-ui/react/context-menu";
+import { Menu as BaseMenu } from "@base-ui/react/menu";
+import type { ComponentPropsWithoutRef, ElementType, ReactElement, ReactNode } from "react";
+import { cn } from "./cn";
+
+/**
+ * Base UI lets `className` be a function of the part's state. Studio's parts
+ * merge a string with `cn`, so the string form is the one they accept.
+ */
+type StyledProps<T extends ElementType> = Omit<ComponentPropsWithoutRef<T>, "className"> & {
+  className?: string;
+};
+
+/** Forces the settled open look for a gallery shot; CSS-only, open state stays controlled. */
+export type PopupPreviewState = "open";
+
+/** Where the portal puts the popup. `null` keeps it inline, next to its trigger. */
+type PortalContainer = ComponentPropsWithoutRef<typeof BaseMenu.Portal>["container"];
+
+/** Matches Tooltip's gap from its trigger, and its viewport margin. */
+const SIDE_OFFSET = 6;
+const VIEWPORT_MARGIN = 8;
+
+/**
+ * Chrome shared by every floating panel (`Popover` too); callers add their own shadow token.
+ * `data-starting-style`/`data-ending-style` are Base UI's transition attributes.
+ */
+export const popupSurface = cn(
+  "rounded-lg border border-border-input bg-surface",
+  "origin-[var(--transform-origin)] outline-hidden",
+  "transition-[opacity,transform] ease-out-quint duration-open",
+  "data-[starting-style]:opacity-0 data-[starting-style]:scale-95",
+  "data-[ending-style]:opacity-0 data-[ending-style]:scale-95",
+  "data-[preview-state=open]:opacity-100 data-[preview-state=open]:scale-100",
+);
+
+/** The popup's own layer: menus sit above panel chrome and below a modal. */
+const POPUP_LAYER = "z-200";
+
+const menuPopup = cn(popupSurface, "min-w-36 p-1 shadow-menu");
+
+/** One row. `data-highlighted` is set by keyboard and pointer alike, so the seen row is the Enter row. */
+const itemBase = cn(
+  "flex cursor-default select-none items-center justify-between gap-6 rounded-sm px-2 py-1.5",
+  "text-step-11 whitespace-nowrap text-text-1",
+  "outline-hidden transition-colors ease-out-quint duration-hover",
+  "data-[highlighted]:bg-hover data-[highlighted]:text-text-0",
+  "data-[preview-state=hover]:bg-hover data-[preview-state=hover]:text-text-0",
+  "data-[disabled]:pointer-events-none data-[disabled]:opacity-40",
+);
+
+const itemDanger = cn("text-danger data-[highlighted]:bg-danger/15 data-[highlighted]:text-danger");
+
+export type MenuItemTone = "default" | "danger";
+
+interface PositionedProps {
+  side?: "top" | "bottom" | "left" | "right";
+  align?: "start" | "center" | "end";
+  sideOffset?: number;
+  /** Portal target. Pass the shadow root when the trigger lives in one. */
+  container?: PortalContainer;
+  /** Names the popup for assistive tech. A menu with no name is unlabelled. */
+  "aria-label"?: string;
+  className?: string;
+  "data-preview-state"?: PopupPreviewState;
+}
+
+interface MenuProps
+  extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof BaseMenu.Root>, "children"> {
+  /** A single element. It becomes the trigger; no wrapper is added around it. */
+  trigger: ReactElement;
+  /** The items: `MenuItem`, `MenuRadioGroup`, `MenuSeparator`. */
+  children: ReactNode;
+}
+
+/**
+ * A menu opened by its trigger. Uncontrolled by default; pass `open` and
+ * `onOpenChange` for a menu whose state lives in a store.
+ */
+export function Menu({
+  trigger,
+  children,
+  side = "bottom",
+  align = "start",
+  sideOffset = SIDE_OFFSET,
+  container,
+  className,
+  "aria-label": ariaLabel,
+  "data-preview-state": previewState,
+  ...root
+}: MenuProps) {
+  return (
+    <BaseMenu.Root {...root}>
+      <BaseMenu.Trigger render={trigger} />
+      <BaseMenu.Portal container={container}>
+        <BaseMenu.Positioner
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          collisionPadding={VIEWPORT_MARGIN}
+          className={POPUP_LAYER}
+        >
+          <BaseMenu.Popup
+            aria-label={ariaLabel}
+            data-preview-state={previewState}
+            className={cn(menuPopup, className)}
+          >
+            {children}
+          </BaseMenu.Popup>
+        </BaseMenu.Positioner>
+      </BaseMenu.Portal>
+    </BaseMenu.Root>
+  );
+}
+
+interface ContextMenuProps
+  extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof BaseContextMenu.Root>, "children"> {
+  /**
+   * The right-clickable area, as the caller's own element. Its children are
+   * kept: the trigger renders that element rather than wrapping it.
+   */
+  trigger: ReactElement;
+  children: ReactNode;
+}
+
+/** Opened by right click or long press at the pointer, so `side` and `align` are not offered. */
+export function ContextMenu({
+  trigger,
+  children,
+  container,
+  className,
+  "aria-label": ariaLabel,
+  "data-preview-state": previewState,
+  ...root
+}: Omit<ContextMenuProps, "side" | "align" | "sideOffset">) {
+  return (
+    <BaseContextMenu.Root {...root}>
+      <BaseContextMenu.Trigger render={trigger} />
+      <BaseContextMenu.Portal container={container}>
+        <BaseContextMenu.Positioner collisionPadding={VIEWPORT_MARGIN} className={POPUP_LAYER}>
+          <BaseContextMenu.Popup
+            aria-label={ariaLabel}
+            data-preview-state={previewState}
+            className={cn(menuPopup, className)}
+          >
+            {children}
+          </BaseContextMenu.Popup>
+        </BaseContextMenu.Positioner>
+      </BaseContextMenu.Portal>
+    </BaseContextMenu.Root>
+  );
+}
+
+/** Keyboard shortcut hint, mono and tabular; exported for hints that are not a plain string. */
+export function MenuShortcut({ className, ...props }: StyledProps<"span">) {
+  return (
+    <span
+      className={cn("shrink-0 font-mono text-step-10 tabular-nums text-text-4", className)}
+      aria-hidden="true"
+      {...props}
+    />
+  );
+}
+
+interface MenuItemProps extends StyledProps<typeof BaseMenu.Item> {
+  /** Rendered as a dim mono hint on the trailing edge. Decorative. */
+  shortcut?: string;
+  /** `danger` for a destructive action (Delete, Remove). */
+  tone?: MenuItemTone;
+  "data-preview-state"?: "hover";
+}
+
+/** One action. `disabled` items are skipped by the arrow keys, not just dimmed. */
+export function MenuItem({ shortcut, tone, className, children, ...props }: MenuItemProps) {
+  return (
+    <BaseMenu.Item className={cn(itemBase, tone === "danger" && itemDanger, className)} {...props}>
+      <span className="truncate">{children}</span>
+      {shortcut ? <MenuShortcut>{shortcut}</MenuShortcut> : null}
+    </BaseMenu.Item>
+  );
+}
+
+/** Single-choice group; selection is `aria-checked` on each item, which the dot indicator draws from. */
+export function MenuRadioGroup(props: ComponentPropsWithoutRef<typeof BaseMenu.RadioGroup>) {
+  return <BaseMenu.RadioGroup {...props} />;
+}
+
+interface MenuRadioItemProps extends StyledProps<typeof BaseMenu.RadioItem> {
+  "data-preview-state"?: "hover";
+}
+
+/** One choice in a `MenuRadioGroup`. The dot renders only while it is checked. */
+export function MenuRadioItem({ className, children, ...props }: MenuRadioItemProps) {
+  return (
+    <BaseMenu.RadioItem className={cn(itemBase, className)} {...props}>
+      <span className="truncate">{children}</span>
+      {/* Fixed box so a checked and an unchecked row keep the same width. */}
+      <span className="flex size-3 shrink-0 items-center justify-center">
+        <BaseMenu.RadioItemIndicator className="size-1.5 rounded-full bg-accent" />
+      </span>
+    </BaseMenu.RadioItem>
+  );
+}
+
+/** A hairline between two groups of items. */
+export function MenuSeparator({ className, ...props }: StyledProps<typeof BaseMenu.Separator>) {
+  return <BaseMenu.Separator className={cn("my-1 h-px bg-hairline", className)} {...props} />;
+}