@hyperframes/studio 0.8.50 → 0.8.52

package/src/components/ui/Toggle.tsx

@@ -0,0 +1,63 @@
+/**
+ * Toggle: a switch, not a checkbox (immediate effect). `role="switch"` needed an entry in
+ * `typingTarget.ts` so Space is not leaked to the global playback shortcut.
+ */
+
+import { Switch } from "@base-ui/react/switch";
+import { cn } from "./cn";
+import type { PreviewState } from "./Button";
+
+export interface ToggleProps {
+  /** Accessible name. */
+  label: string;
+  checked: boolean;
+  /** Called on every flip. */
+  onCommit: (next: boolean) => void;
+  /** Called once per flip, for design-input telemetry. */
+  onTrack?: () => void;
+  disabled?: boolean;
+  className?: string;
+  "data-preview-state"?: PreviewState;
+}
+
+export function Toggle({
+  label,
+  checked,
+  onCommit,
+  onTrack,
+  disabled,
+  className,
+  "data-preview-state": previewState,
+}: ToggleProps) {
+  return (
+    <Switch.Root
+      aria-label={label}
+      checked={checked}
+      disabled={disabled}
+      onCheckedChange={(next) => {
+        onCommit(next);
+        onTrack?.();
+      }}
+      data-preview-state={previewState}
+      className={cn(
+        "relative inline-flex h-4 w-7 shrink-0 cursor-pointer items-center rounded-full p-0.5",
+        "border border-border-input bg-input",
+        "transition-[background-color,border-color] ease-standard duration-press",
+        "hover:border-border-strong data-[preview-state=hover]:border-border-strong",
+        "data-[checked]:border-accent data-[checked]:bg-accent",
+        "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",
+        "disabled:cursor-not-allowed disabled:opacity-40",
+        className,
+      )}
+    >
+      <Switch.Thumb
+        className={cn(
+          "size-3 rounded-full bg-text-3",
+          "transition-[transform,background-color] ease-standard duration-press",
+          "data-[checked]:translate-x-3 data-[checked]:bg-bg-0",
+        )}
+      />
+    </Switch.Root>
+  );
+}

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

@@ -0,0 +1,110 @@
+// @vitest-environment happy-dom
+
+/**
+ * Tooltip a11y contract Base UI must not lose: focus opens it, Escape
+ * dismisses it (WCAG 1.4.13), aria-describedby ties trigger to bubble (4.1.2).
+ */
+import React, { act } from "react";
+import { afterEach, expect, it } from "vitest";
+import { cleanupMounted, mountHost } from "./mountHost.testHelpers";
+import { Tooltip } from "./Tooltip";
+
+afterEach(cleanupMounted);
+
+function mount(): HTMLElement {
+  const host = mountHost(
+    <Tooltip label="Selection tool (V)" delay={0}>
+      <button type="button" data-testid="trigger">
+        V
+      </button>
+    </Tooltip>,
+  );
+  const trigger = host.querySelector<HTMLElement>('[data-testid="trigger"]');
+  if (!trigger) throw new Error("trigger not rendered");
+  return trigger;
+}
+
+/** Base UI opens and closes across a task, not synchronously. */
+async function settle(): Promise<void> {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+/** Browsers send hover to the wrapper, never to a disabled control inside it. */
+function hover(trigger: HTMLElement): void {
+  const box = trigger.parentElement ?? trigger;
+  act(() => {
+    box.dispatchEvent(new PointerEvent("pointerenter", { bubbles: false, composed: true }));
+    box.dispatchEvent(new MouseEvent("mouseenter", { bubbles: false, composed: true }));
+    box.dispatchEvent(new MouseEvent("mousemove", { bubbles: true, composed: true }));
+  });
+}
+
+function bubble(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[role="tooltip"]');
+}
+
+it("opens on focus and describes its trigger", async () => {
+  const trigger = mount();
+
+  expect(bubble()).toBeNull();
+  act(() => trigger.focus());
+  await settle();
+
+  const tip = bubble();
+  expect(tip?.textContent).toBe("Selection tool (V)");
+  expect(trigger.getAttribute("aria-describedby")).toBe(tip?.id);
+});
+
+it("opens on pointer hover", async () => {
+  const trigger = mount();
+
+  hover(trigger);
+  await settle();
+
+  expect(bubble()?.textContent).toBe("Selection tool (V)");
+});
+
+it("closes on Escape and drops the description", async () => {
+  const trigger = mount();
+  act(() => trigger.focus());
+  await settle();
+  expect(bubble()).not.toBeNull();
+
+  act(() => {
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, composed: true }),
+    );
+  });
+  await settle();
+
+  expect(bubble()).toBeNull();
+  expect(trigger.getAttribute("aria-describedby")).toBeNull();
+});
+
+it("opens on hover over a disabled child", async () => {
+  const host = mountHost(
+    <Tooltip label="Rendering" delay={0}>
+      <button type="button" disabled data-testid="off">
+        Export
+      </button>
+    </Tooltip>,
+  );
+  const off = host.querySelector<HTMLElement>('[data-testid="off"]');
+  if (!off) throw new Error("trigger not rendered");
+
+  hover(off);
+  await settle();
+
+  expect(bubble()?.textContent).toBe("Rendering");
+});
+
+it("wraps its child in a box-less span so a disabled child still gets hover", () => {
+  const trigger = mount();
+
+  expect(trigger.tagName).toBe("BUTTON");
+  expect(trigger.parentElement?.tagName).toBe("SPAN");
+  expect(trigger.parentElement?.className).toBe("contents");
+  expect(trigger.parentElement?.parentElement?.parentElement).toBe(document.body);
+});

package/src/components/ui/Tooltip.tsx

@@ -1,127 +1,53 @@
-import {
-  useState,
-  useRef,
-  useCallback,
-  useEffect,
-  useLayoutEffect,
-  useId,
-  type ReactNode,
-} from "react";
-import { createPortal } from "react-dom";
-import { clampCentredLeft } from "../editor/floatingPanel";
+/**
+ * Tooltip: Base UI's tooltip in Studio tokens. The trigger is a box-less
+ * `display: contents` wrapper so a disabled control still gets hover.
+ */
+
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import { cloneElement, useId, useRef, useState, type ReactElement } from "react";
 
 interface TooltipProps {
   label: string;
-  children: ReactNode;
+  /** A single element, wrapped in a box-less span so a disabled one still gets hover. */
+  children: ReactElement<{ "aria-describedby"?: string }>;
+  /** Hover delay in ms. */
   delay?: number;
-  side?: "top" | "bottom";
+  side?: "top" | "bottom" | "left" | "right";
 }
 
-// Rough bubble height (padding + one text line) used to decide flipping
-// before the bubble has rendered; exact height isn't needed for the guard.
-const APPROX_BUBBLE_H = 28;
+/** Matches the old bubble's gap from its trigger, and its viewport margin. */
+const SIDE_OFFSET = 6;
 const VIEWPORT_MARGIN = 8;
 
 export function Tooltip({ label, children, delay = 400, side = "top" }: TooltipProps) {
-  const [visible, setVisible] = useState(false);
-  const [pos, setPos] = useState({ x: 0, y: 0 });
-  const [resolvedSide, setResolvedSide] = useState<"top" | "bottom">(side);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const triggerRef = useRef<HTMLSpanElement>(null);
-  const bubbleRef = useRef<HTMLDivElement>(null);
-  const [bubbleWidth, setBubbleWidth] = useState(0);
-  // WCAG 4.1.2: programmatically associate the bubble with its trigger.
+  const [open, setOpen] = useState(false);
+  const boxRef = useRef<HTMLSpanElement>(null);
   const tooltipId = useId();
 
-  const show = useCallback(() => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    timerRef.current = setTimeout(() => {
-      const el = triggerRef.current;
-      if (!el) return;
-      const child = el.firstElementChild as HTMLElement | null;
-      const rect = (child ?? el).getBoundingClientRect();
-      if (rect.width === 0 && rect.height === 0) return;
-      // Flip when the preferred side would clip the viewport edge.
-      let nextSide = side;
-      if (side === "top" && rect.top - APPROX_BUBBLE_H - 6 < VIEWPORT_MARGIN) {
-        nextSide = "bottom";
-      } else if (
-        side === "bottom" &&
-        rect.bottom + APPROX_BUBBLE_H + 6 > window.innerHeight - VIEWPORT_MARGIN
-      ) {
-        nextSide = "top";
-      }
-      setResolvedSide(nextSide);
-      setPos({
-        // Raw trigger centre; clamped to the viewport at render, once the
-        // bubble's own width is known (see clampedX).
-        x: rect.left + rect.width / 2,
-        y: nextSide === "top" ? rect.top - 6 : rect.bottom + 6,
-      });
-      setVisible(true);
-    }, delay);
-  }, [delay, side]);
-
-  const hide = useCallback(() => {
-    if (timerRef.current) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-    setVisible(false);
-  }, []);
-
-  // Measure before paint so a wide bubble near a viewport edge is clamped in
-  // the same commit it appears in (no visible jump).
-  useLayoutEffect(() => {
-    setBubbleWidth(visible ? (bubbleRef.current?.offsetWidth ?? 0) : 0);
-  }, [visible, label]);
-
-  // WCAG 1.4.13: tooltip content must be dismissible with Escape.
-  useEffect(() => {
-    if (!visible) return;
-    const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "Escape") hide();
-    };
-    document.addEventListener("keydown", onKeyDown);
-    return () => document.removeEventListener("keydown", onKeyDown);
-  }, [visible, hide]);
-
-  const clampedX = clampCentredLeft(pos.x, bubbleWidth, window.innerWidth, VIEWPORT_MARGIN);
-
   return (
-    <>
-      <span
-        ref={triggerRef}
-        onPointerEnter={show}
-        onPointerLeave={hide}
-        onFocus={show}
-        onBlur={hide}
-        aria-describedby={visible ? tooltipId : undefined}
-        className="contents"
-      >
-        {children}
-      </span>
-      {visible &&
-        createPortal(
-          <div
-            className="fixed z-[200] pointer-events-none"
-            style={{
-              left: clampedX,
-              top: pos.y,
-              transform: resolvedSide === "top" ? "translate(-50%, -100%)" : "translate(-50%, 0)",
-            }}
+    <BaseTooltip.Root open={open} onOpenChange={setOpen}>
+      <BaseTooltip.Trigger delay={delay} render={<span ref={boxRef} className="contents" />}>
+        {cloneElement(children, {
+          "aria-describedby": open ? tooltipId : children.props["aria-describedby"],
+        })}
+      </BaseTooltip.Trigger>
+      <BaseTooltip.Portal>
+        <BaseTooltip.Positioner
+          anchor={() => boxRef.current?.firstElementChild ?? null}
+          side={side}
+          sideOffset={SIDE_OFFSET}
+          collisionPadding={VIEWPORT_MARGIN}
+          className="z-200"
+        >
+          <BaseTooltip.Popup
+            id={tooltipId}
+            role="tooltip"
+            className="pointer-events-none rounded-md border border-border-input bg-surface px-2 py-1 text-step-10 font-medium text-text-1 whitespace-nowrap shadow-menu"
           >
-            <div
-              ref={bubbleRef}
-              role="tooltip"
-              id={tooltipId}
-              className="px-2 py-1 rounded-md bg-neutral-800 border border-neutral-700/50 text-[10px] font-medium text-neutral-200 whitespace-nowrap shadow-lg"
-            >
-              {label}
-            </div>
-          </div>,
-          document.body,
-        )}
-    </>
+            {label}
+          </BaseTooltip.Popup>
+        </BaseTooltip.Positioner>
+      </BaseTooltip.Portal>
+    </BaseTooltip.Root>
   );
 }

package/src/components/ui/cn.test.ts

@@ -0,0 +1,30 @@
+/**
+ * The two things `cn` must do that a bare `clsx` cannot: drop a losing class
+ * from the same group, and know the two class families `theme.css` invents.
+ */
+import { describe, expect, it } from "vitest";
+import { cn } from "./cn";
+
+describe("cn", () => {
+  it("keeps only the last class from a group", () => {
+    expect(cn("text-sm", "text-step-11")).toBe("text-step-11");
+    expect(cn("text-step-11", "text-sm")).toBe("text-sm");
+  });
+
+  it("takes clsx-style conditionals", () => {
+    const cond = true;
+    expect(cn("px-3", cond && "px-4")).toBe("px-4");
+    expect(cn("px-3", !cond && "px-4")).toBe("px-3");
+  });
+
+  it("merges the control heights against each other", () => {
+    expect(cn("h-ctl", "h-ctl-lg")).toBe("h-ctl-lg");
+    expect(cn("h-ctl-lg", "h-8")).toBe("h-8");
+    expect(cn("size-ctl", "size-ctl-sm")).toBe("size-ctl-sm");
+  });
+
+  it("keeps a type step and a text colour apart", () => {
+    // Both are `text-*`; only one is a font size.
+    expect(cn("text-step-11", "text-text-2")).toBe("text-step-11 text-text-2");
+  });
+});

package/src/components/ui/cn.ts

@@ -0,0 +1,25 @@
+/**
+ * Studio's tailwind-merge config: teaches it the two scales `theme.css`
+ * invents (`text-step-*`, `ctl`/`ctl-sm`/`ctl-lg`) so overrides replace, not stack.
+ */
+
+import { createCn } from "cn/config";
+
+/** `text-step-11`, `text-step-9`, … — the type scale from `theme.css`. */
+const isTypeStep = (value: string) => /^step-\d+$/.test(value);
+
+/** `ctl`, `ctl-sm`, `ctl-lg` — the control heights from `theme.css`. */
+const isControlSize = (value: string) => /^ctl(-sm|-lg)?$/.test(value);
+
+export const cn = createCn({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: [isTypeStep] }],
+      h: [{ h: [isControlSize] }],
+      w: [{ w: [isControlSize] }],
+      size: [{ size: [isControlSize] }],
+      "min-h": [{ "min-h": [isControlSize] }],
+      "min-w": [{ "min-w": [isControlSize] }],
+    },
+  },
+});

package/src/components/ui/index.ts

@@ -1,5 +1,32 @@
-// Minimal UI primitives for studio canvas components
-export { Button, IconButton } from "./Button";
+// Studio's shared UI primitives. Every control in the app is meant to come
+// from here, so a look or a keyboard behaviour is decided once.
+export { cn } from "./cn";
+export { Button, buttonBase, buttonSizes, buttonVariants } from "./Button";
+export type { ButtonSize, ButtonVariant, PreviewState } from "./Button";
+export { IconButton } from "./IconButton";
+export { Tab, TabPanel, Tabs, TabsList } from "./Tabs";
 export { HyperframesLoader, StatusFrame } from "./HyperframesLoader";
 export type { HyperframesLoaderProps } from "./HyperframesLoader";
 export { Tooltip } from "./Tooltip";
+export {
+  ContextMenu,
+  Menu,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuShortcut,
+  popupSurface,
+} from "./Menu";
+export type { MenuItemTone, PopupPreviewState } from "./Menu";
+export { Popover } from "./Popover";
+export { Input, fieldBase, fieldText } from "./Input";
+export type { InputProps } from "./Input";
+export { NumberField } from "./NumberField";
+export type { NumberFieldProps } from "./NumberField";
+export { Select } from "./Select";
+export type { SelectOption, SelectProps } from "./Select";
+export { Slider } from "./Slider";
+export type { SliderProps } from "./Slider";
+export { Toggle } from "./Toggle";
+export type { ToggleProps } from "./Toggle";

package/src/components/ui/mountHost.testHelpers.ts

@@ -0,0 +1,24 @@
+import { act, type ReactElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let mounted: { root: Root; host: HTMLElement } | null = null;
+
+/** Renders into a fresh host attached to the body; `cleanupMounted` tears it down. */
+export function mountHost(element: ReactElement): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  act(() => root.render(element));
+  return host;
+}
+
+export function cleanupMounted(): void {
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+}