@hyperframes/studio 0.8.51 → 0.8.52

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

@@ -1,57 +1,249 @@
 // @vitest-environment happy-dom
 
-// happy-dom has no CSS engine, so this pins the structure that makes the gap
-// work (children are direct flex items of the gap-bearing button), not the
-// computed pixels. The measured gap is verified in a real browser.
+/**
+ * Button/IconButton: renders every variant and size, then compiles Studio's
+ * real stylesheet against the emitted classes so an unstyled class fails.
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import React, { act } from "react";
+import { compile } from "tailwindcss";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { Button, type ButtonSize, type ButtonVariant } from "./Button";
+import { IconButton } from "./IconButton";
+import { Tab, Tabs, TabsList } from "./Tabs";
+import { cleanupMounted, mountHost } from "./mountHost.testHelpers";
+import { isTypingTarget } from "../../utils/typingTarget";
+import { shouldIgnorePlaybackShortcutTarget } from "../../player/lib/playbackShortcuts";
 
-import { act } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
-import { Button } from "./Button";
+const VARIANTS: ButtonVariant[] = ["primary", "secondary", "danger", "ghost"];
+const SIZES: ButtonSize[] = ["sm", "md", "lg"];
 
-Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+afterEach(cleanupMounted);
 
-let root: Root | null = null;
+function classesOf(host: HTMLElement, selector = "button"): string[] {
+  const el = host.querySelector(selector);
+  if (!el) throw new Error(`nothing matched ${selector}`);
+  return [...el.classList];
+}
+
+// -- the compiled stylesheet, built once for the whole file --
 
-afterEach(() => {
-  if (root) act(() => root?.unmount());
-  root = null;
-  document.body.innerHTML = "";
+const STYLES_DIR = path.resolve(__dirname, "../../styles");
+const require = createRequire(import.meta.url);
+const TAILWIND_DIR = path.dirname(require.resolve("tailwindcss/package.json"));
+
+async function loadStylesheet(id: string, base: string) {
+  const file = id === "tailwindcss" ? path.join(TAILWIND_DIR, "index.css") : path.resolve(base, id);
+  return { path: file, base: path.dirname(file), content: readFileSync(file, "utf8") };
+}
+
+let compileStudioCss: (candidates: string[]) => string;
+
+beforeAll(async () => {
+  const compiled = await compile(readFileSync(path.join(STYLES_DIR, "studio.css"), "utf8"), {
+    base: STYLES_DIR,
+    loadStylesheet,
+  });
+  compileStudioCss = (candidates) => compiled.build(candidates);
 });
 
-function mount(element: React.ReactNode): HTMLButtonElement {
-  const host = document.createElement("div");
-  document.body.append(host);
-  root = createRoot(host);
-  act(() => root?.render(element));
-  const button = host.querySelector("button");
-  if (!button) throw new Error("button did not render");
-  return button;
+function unresolved(candidates: string[]): string[] {
+  const css = compileStudioCss(candidates);
+  return candidates.filter((candidate) => !css.includes(CSS.escape(candidate)));
 }
 
-describe("Button children layout", () => {
-  it("lays label and kbd out as sibling flex items of the gap-bearing button", () => {
-    const button = mount(
+describe("Button classes", () => {
+  it("emits only classes Studio's stylesheet defines", () => {
+    const emitted = new Set<string>();
+    for (const variant of VARIANTS) {
+      for (const size of SIZES) {
+        const host = mountHost(
+          <>
+            <Button variant={variant} size={size}>
+              Export
+            </Button>
+            <IconButton variant={variant} size={size} icon={null} aria-label="Zoom out" />
+          </>,
+        );
+        for (const el of host.querySelectorAll("button")) {
+          for (const cls of el.classList) emitted.add(cls);
+        }
+        cleanupMounted();
+      }
+    }
+
+    expect(emitted.size).toBeGreaterThan(20);
+    expect(unresolved([...emitted])).toEqual([]);
+  });
+
+  it("fails an undefined class, so the check above is not vacuous", () => {
+    // Names in a real namespace with no token behind them; the theme file now defines the
+    // `rounded-button` pair this used to name.
+    expect(unresolved(["bg-not-a-token", "text-step-999"])).toEqual([
+      "bg-not-a-token",
+      "text-step-999",
+    ]);
+  });
+
+  it("lets a caller's type size beat the size's own", () => {
+    // The Renders Export case: `size="md"` brings `text-step-12`, the caller
+    // wants 11px, and with plain concatenation both survived into the class
+    // list and the stylesheet's order decided the winner.
+    const classes = classesOf(mountHost(<Button size="md" className="text-step-11" />));
+
+    expect(classes).toContain("text-step-11");
+    expect(classes).not.toContain("text-step-12");
+  });
+
+  it("keeps every interactive look reachable without a pointer", () => {
+    // `data-preview-state` exists so a gallery can show the hover, active and
+    // focus looks. It is worth nothing if it drifts from the real state, so
+    // each pair is matched here in both directions.
+    const realPrefix = {
+      hover: ["enabled:hover:", "hover:"],
+      active: ["enabled:active:", "active:"],
+      focus: ["focus-visible:"],
+    };
+
+    for (const variant of VARIANTS) {
+      const classes = classesOf(mountHost(<Button variant={variant}>Export</Button>));
+      cleanupMounted();
+
+      for (const [state, prefixes] of Object.entries(realPrefix)) {
+        const previewPrefix = `data-[preview-state=${state}]:`;
+        const preview = classes
+          .filter((cls) => cls.startsWith(previewPrefix))
+          .map((cls) => cls.slice(previewPrefix.length));
+        const real = classes
+          .filter((cls) => prefixes.some((prefix) => cls.startsWith(prefix)))
+          .map((cls) => cls.slice(cls.lastIndexOf(":") + 1));
+
+        expect([...preview].sort(), `${variant} ${state}`).toEqual([...real].sort());
+        expect(preview.length, `${variant} ${state}`).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("uses a motion token that zeroes itself under reduced motion", () => {
+    // AE4. The zero-duration case lives in the `duration-press` 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 button's
+    // job is to name the token; the stylesheet's job is the media query.
+    expect(classesOf(mountHost(<Button>Export</Button>))).toContain("duration-press");
+
+    expect(compileStudioCss(["duration-press"])).toMatch(
+      /\.duration-press \{[\s\S]*?prefers-reduced-motion: reduce[\s\S]*?transition-duration: 0ms/,
+    );
+  });
+});
+
+describe("Button behaviour", () => {
+  it("does not fire a disabled click, and says it is disabled", () => {
+    let clicks = 0;
+    const host = mountHost(
+      <Button disabled onClick={() => (clicks += 1)}>
+        Export
+      </Button>,
+    );
+    const button = host.querySelector("button")!;
+
+    act(() => button.click());
+
+    expect(clicks).toBe(0);
+    expect(button.getAttribute("aria-disabled")).toBe("true");
+  });
+
+  it("still fires a click while a preview state is forced", () => {
+    let clicks = 0;
+    const host = mountHost(
+      <Button data-preview-state="hover" onClick={() => (clicks += 1)}>
+        Export
+      </Button>,
+    );
+    const button = host.querySelector("button")!;
+
+    act(() => button.click());
+
+    expect(clicks).toBe(1);
+    expect(button.getAttribute("data-preview-state")).toBe("hover");
+  });
+
+  it("is classified by the hotkey selectors the way a plain button is", () => {
+    // KTD13. Both selector lists gate on roles and element names. A primitive
+    // that landed on a different role would leak or swallow global hotkeys with
+    // nothing to notice it.
+    const host = mountHost(
+      <>
+        <button type="button" data-testid="plain">
+          Export
+        </button>
+        <Button data-testid="primitive">Export</Button>
+        <Tabs defaultValue="code">
+          <TabsList aria-label="Sidebar panels">
+            <Tab value="code">Code</Tab>
+          </TabsList>
+        </Tabs>
+      </>,
+    );
+    const plain = host.querySelector('[data-testid="plain"]')!;
+    const button = host.querySelector('[data-testid="primitive"]')!;
+    const tab = host.querySelector('[role="tab"]')!;
+
+    for (const el of [plain, button, tab]) {
+      expect(isTypingTarget(el)).toBe(false);
+      expect(shouldIgnorePlaybackShortcutTarget(el)).toBe(true);
+    }
+  });
+});
+
+describe("disabled states", () => {
+  it("disables a loading Button", () => {
+    const host = mountHost(<Button loading>Save</Button>);
+    const button = host.querySelector("button");
+
+    expect(button?.disabled).toBe(true);
+    expect(button?.getAttribute("aria-disabled")).toBe("true");
+  });
+
+  it("marks a disabled IconButton for assistive tech", () => {
+    const host = mountHost(<IconButton aria-label="Undo" icon={<svg />} disabled />);
+    const button = host.querySelector("button");
+
+    expect(button?.disabled).toBe(true);
+    expect(button?.getAttribute("aria-disabled")).toBe("true");
+  });
+});
+
+describe("children layout", () => {
+  it("keeps label and shortcut direct flex items of the gap-bearing button without an icon", () => {
+    const host = mountHost(
       <Button size="md">
         <span>Export</span>
         <kbd>⌘E</kbd>
       </Button>,
     );
+    const button = host.querySelector("button");
 
-    expect(button.classList.contains("inline-flex")).toBe(true);
-    expect(button.classList.contains("gap-1.5")).toBe(true);
-    expect(Array.from(button.children).map((child) => child.tagName)).toEqual(["SPAN", "KBD"]);
+    expect(button?.classList.contains("inline-flex")).toBe(true);
+    expect(button?.classList.contains("gap-1.5")).toBe(true);
+    expect(Array.from(button?.children ?? []).map((child) => child.tagName)).toEqual([
+      "SPAN",
+      "KBD",
+    ]);
   });
 
-  it("puts children next to the icon as direct flex items too", () => {
-    const button = mount(
+  it("makes label and shortcut direct flex items so the button gap applies between them", () => {
+    const host = mountHost(
       <Button icon={<svg />}>
         <span>Export</span>
         <kbd>⌘E</kbd>
       </Button>,
     );
+    const button = host.querySelector("button");
 
-    expect(Array.from(button.children).map((child) => child.tagName)).toEqual([
+    expect(Array.from(button?.children ?? []).map((child) => child.tagName)).toEqual([
       "SPAN",
       "SPAN",
       "KBD",

package/src/components/ui/Button.tsx

@@ -1,159 +1,122 @@
 /**
- * Button & IconButton — The most important primitive.
+ * Button — a native `<button>` wearing Studio's tokens.
  *
- * Absorbs: active state (scale 0.98), hit target (min 32px),
- * shadow anatomy (primary), focus ring, disabled state,
- * loading state, reduced motion, proper timing tokens.
+ * Everything visual comes from `theme.css`: the three control heights, the
+ * radius scale, the semantic colours, the motion durations. No value is decided
+ * here, so a button cannot drift from the rest of the system.
  *
- * Rules applied:
- * - physics-active-state: scale(0.98) on :active
- * - ux-fitts-target-size: min 32px hit target
- * - visual-button-shadow-anatomy: 6-layer shadow on primary
- * - duration-press-hover: 120ms press, 150ms hover
+ * Two conventions: classes merge through `cn`, so a caller's `className`
+ * always wins within its group; and every interactive look is written twice,
+ * once as the real state and once as `data-[preview-state=…]` (CSS-only, for
+ * screenshots). `Button.test.tsx` asserts the two stay in sync.
  */
 
 import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
+import { cn } from "./cn";
 
-// -- Button --
+export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
+export type ButtonSize = "sm" | "md" | "lg";
 
-type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
-type ButtonSize = "sm" | "md" | "lg";
+/** Forces one interactive look for a gallery shot. CSS-only; see the header. */
+export type PreviewState = "hover" | "active" | "focus";
 
-interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+export interface ButtonBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
   size?: ButtonSize;
+  "data-preview-state"?: PreviewState;
+}
+
+interface ButtonProps extends ButtonBaseProps {
   loading?: boolean;
   icon?: ReactNode;
 }
 
-const variantStyles: Record<ButtonVariant, string> = {
-  primary: [
-    "bg-white text-neutral-950 font-medium",
-    "shadow-btn-primary",
-    "enabled:hover:bg-neutral-200",
-    "enabled:active:scale-[0.97]",
-  ].join(" "),
-  secondary: [
-    "bg-transparent text-neutral-300 font-medium",
-    "border border-border",
-    "enabled:hover:bg-surface-hover enabled:hover:text-white enabled:hover:border-border-strong",
-    "enabled:active:scale-[0.98]",
-  ].join(" "),
-  danger: [
-    "bg-accent-red text-white font-medium",
-    "enabled:hover:bg-red-600",
-    "enabled:active:scale-[0.97]",
-  ].join(" "),
-  ghost: [
-    "bg-transparent text-neutral-400",
-    "enabled:hover:bg-surface-hover enabled:hover:text-white",
-    "enabled:active:scale-[0.98]",
-  ].join(" "),
+/**
+ * Shared by Button and IconButton. `disabled:` keeps pointer events alive so a
+ * wrapping Tooltip can still explain why the control is disabled.
+ */
+export const buttonBase = cn(
+  "inline-flex items-center justify-center select-none cursor-pointer whitespace-nowrap",
+  "transition-[background-color,border-color,color,filter,transform] ease-out-quint duration-press",
+  "disabled:opacity-40 disabled:cursor-not-allowed",
+  "outline-hidden",
+  "focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-accent",
+  "data-[preview-state=focus]:outline-solid data-[preview-state=focus]:outline-2 data-[preview-state=focus]:outline-offset-1 data-[preview-state=focus]:outline-accent",
+);
+
+/**
+ * One entry per variant. The `data-[preview-state=…]` half of each string
+ * repeats the `hover:` and `active:` half exactly; the test pairs them.
+ */
+export const buttonVariants: Record<ButtonVariant, string> = {
+  primary: cn(
+    "bg-accent text-bg-0 font-semibold",
+    "enabled:hover:brightness-110 data-[preview-state=hover]:brightness-110",
+    "enabled:active:scale-[0.98] data-[preview-state=active]:scale-[0.98]",
+  ),
+  secondary: cn(
+    "bg-transparent text-text-1 font-medium border border-border-strong",
+    "enabled:hover:bg-hover enabled:hover:text-text-0 data-[preview-state=hover]:bg-hover data-[preview-state=hover]:text-text-0",
+    "enabled:active:scale-[0.98] data-[preview-state=active]:scale-[0.98]",
+  ),
+  danger: cn(
+    "bg-danger text-text-0 font-medium",
+    "enabled:hover:brightness-110 data-[preview-state=hover]:brightness-110",
+    "enabled:active:scale-[0.98] data-[preview-state=active]:scale-[0.98]",
+  ),
+  ghost: cn(
+    "bg-transparent text-text-2 font-medium",
+    "enabled:hover:bg-hover enabled:hover:text-text-0 data-[preview-state=hover]:bg-hover data-[preview-state=hover]:text-text-0",
+    "enabled:active:scale-[0.98] data-[preview-state=active]:scale-[0.98]",
+  ),
 };
 
-const sizeStyles: Record<ButtonSize, string> = {
-  sm: "h-7 px-2.5 text-xs gap-1.5 rounded-button",
-  md: "h-8 px-3 text-sm gap-1.5 rounded-button",
-  lg: "h-9 px-4 text-base gap-2 rounded-button",
+/**
+ * The three control heights, 24 / 28 / 32 px, from `--spacing-ctl-*`.
+ * Exported so the Capture download `<a href>` can wear the same recipe as a Button.
+ */
+export const buttonSizes: Record<ButtonSize, string> = {
+  sm: "h-ctl-sm px-2 gap-1 rounded-sm text-step-11",
+  md: "h-ctl px-3 gap-1.5 rounded-md text-step-12",
+  lg: "h-ctl-lg px-4 gap-2 rounded-md text-step-13",
 };
 
-// Imported by the shell/renders PRs later in this stack.
-// fallow-ignore-next-line unused-export
+function Spinner() {
+  return (
+    <svg className="animate-spin size-3.5" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path
+        className="opacity-75"
+        fill="currentColor"
+        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+      />
+    </svg>
+  );
+}
+
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
   (
-    {
-      variant = "secondary",
-      size = "md",
-      loading,
-      icon,
-      children,
-      className = "",
-      disabled,
-      ...props
-    },
+    { variant = "secondary", size = "md", loading, icon, children, className, disabled, ...props },
     ref,
   ) => {
+    const isDisabled = disabled || loading;
+    let leading: ReactNode = null;
+    if (loading) leading = <Spinner />;
+    else if (icon) leading = <span className="shrink-0">{icon}</span>;
     return (
       <button
         ref={ref}
-        disabled={disabled || loading}
-        className={[
-          "inline-flex items-center justify-center",
-          "transition-all duration-press ease-standard",
-          // No pointer-events-none: disabled buttons must still receive hover
-          // so a wrapping Tooltip can explain WHY they're disabled (A5).
-          "disabled:opacity-40 disabled:cursor-not-allowed",
-          "select-none cursor-pointer",
-          "outline-hidden focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-studio-accent",
-          variantStyles[variant],
-          sizeStyles[size],
-          className,
-        ].join(" ")}
+        disabled={isDisabled}
+        // `aria-disabled` as well as `disabled`: assistive tech announces the
+        // state even where the native attribute is filtered out of the tree.
+        aria-disabled={isDisabled || undefined}
+        className={cn(buttonBase, buttonVariants[variant], buttonSizes[size], className)}
         {...props}
       >
-        {loading ? (
-          <svg className="animate-spin h-3.5 w-3.5" viewBox="0 0 24 24" fill="none">
-            <circle
-              className="opacity-25"
-              cx="12"
-              cy="12"
-              r="10"
-              stroke="currentColor"
-              strokeWidth="4"
-            />
-            <path
-              className="opacity-75"
-              fill="currentColor"
-              d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
-            />
-          </svg>
-        ) : icon ? (
-          <span className="shrink-0">{icon}</span>
-        ) : null}
+        {leading}
         {children}
       </button>
     );
   },
 );
 Button.displayName = "Button";
-
-// -- IconButton --
-// For icon-only buttons. Enforces min 32px hit target.
-
-interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  icon: ReactNode;
-  size?: ButtonSize;
-  variant?: ButtonVariant;
-  "aria-label": string; // REQUIRED for accessibility
-}
-
-const iconSizeStyles: Record<ButtonSize, string> = {
-  sm: "min-w-7 min-h-7 rounded-button", // 28px
-  md: "min-w-8 min-h-8 rounded-button", // 32px — minimum recommended
-  lg: "min-w-9 min-h-9 rounded-button", // 36px
-};
-
-// fallow-ignore-next-line unused-export
-export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
-  ({ icon, size = "md", variant = "ghost", className = "", ...props }, ref) => {
-    return (
-      <button
-        ref={ref}
-        className={[
-          "inline-flex items-center justify-center",
-          "transition-all duration-press ease-standard",
-          "disabled:opacity-40 disabled:cursor-not-allowed",
-          "select-none cursor-pointer",
-          "outline-hidden focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-studio-accent",
-          variantStyles[variant],
-          iconSizeStyles[size],
-          className,
-        ].join(" ")}
-        {...props}
-      >
-        {icon}
-      </button>
-    );
-  },
-);
-IconButton.displayName = "IconButton";

package/src/components/ui/IconButton.tsx

@@ -0,0 +1,38 @@
+/**
+ * IconButton — Button's square sibling; shares its base/variant classes so
+ * the two never drift. `aria-label` is required for screen readers.
+ */
+
+import { forwardRef } from "react";
+import type { ReactNode } from "react";
+import { buttonBase, buttonVariants, type ButtonBaseProps, type ButtonSize } from "./Button";
+import { cn } from "./cn";
+
+interface IconButtonProps extends ButtonBaseProps {
+  icon: ReactNode;
+  "aria-label": string;
+}
+
+/** Square boxes on the same 24 / 28 / 32 px control heights as Button. */
+const iconSizeStyles: Record<ButtonSize, string> = {
+  sm: "size-ctl-sm rounded-sm",
+  md: "size-ctl rounded-md",
+  lg: "size-ctl-lg rounded-md",
+};
+
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ icon, size = "md", variant = "ghost", className, disabled, ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        disabled={disabled}
+        aria-disabled={disabled || undefined}
+        className={cn(buttonBase, buttonVariants[variant], iconSizeStyles[size], className)}
+        {...props}
+      >
+        {icon}
+      </button>
+    );
+  },
+);
+IconButton.displayName = "IconButton";