@hyperframes/studio 0.8.50 → 0.8.52

package/src/components/ui/NumberField.tsx

@@ -0,0 +1,122 @@
+/**
+ * NumberField: the inspector's metric control. Commits only on blur, Enter, or a settled step (KTD11),
+ * never per keystroke. The unit is a sibling of the input; unparseable text shows a red boundary and commits nothing.
+ */
+
+import { NumberField as BaseNumberField } from "@base-ui/react/number-field";
+import { useEffect, useRef, useState } from "react";
+import { cn } from "./cn";
+import { fieldBase, fieldText } from "./Input";
+import type { PreviewState } from "./Button";
+
+export interface NumberFieldProps {
+  /** Accessible name. The inspector's row label is the usual one. */
+  label: string;
+  /** The committed value. */
+  value: number;
+  /** Called when a commit boundary produces a value different from `value`. */
+  onCommit: (next: number) => void;
+  /** Called once per committed change, for design-input telemetry. */
+  onTrack?: () => void;
+  /** Rendered beside the number: "px", "%", "deg". Never part of the text. */
+  unit?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+  className?: string;
+  "data-preview-state"?: PreviewState;
+}
+
+export function NumberField({
+  label,
+  value,
+  onCommit,
+  onTrack,
+  unit,
+  min,
+  max,
+  step,
+  disabled,
+  className,
+  "data-preview-state": previewState,
+}: NumberFieldProps) {
+  const [draft, setDraft] = useState<number | null>(value);
+  const [invalid, setInvalid] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // What was last handed to `onCommit`, which is not the same as `value`: a
+  // blur can fire both Base UI's commit and ours in one turn, before the parent
+  // has re-rendered with the new prop, and the second must be a no-op.
+  const committedRef = useRef(value);
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  useEffect(() => {
+    committedRef.current = value;
+    setDraft(value);
+    setInvalid(false);
+  }, [value]);
+
+  const commit = (next: number | null) => {
+    if (next === null || !Number.isFinite(next)) {
+      setInvalid(true);
+      return;
+    }
+    setInvalid(false);
+    if (next === committedRef.current) return;
+    committedRef.current = next;
+    onCommit(next);
+    onTrack?.();
+  };
+
+  /** Enter commits what is on screen, which Base UI has not parsed for us yet. */
+  const commitFromText = () => {
+    const text = inputRef.current?.value.trim() ?? "";
+    commit(text === "" ? null : Number(text));
+  };
+
+  return (
+    <BaseNumberField.Root
+      value={draft}
+      min={min}
+      max={max}
+      step={step}
+      disabled={disabled}
+      onValueChange={(next) => {
+        setDraft(next);
+        if (next !== null) setInvalid(false);
+      }}
+      onValueCommitted={(next) => commit(next)}
+    >
+      <BaseNumberField.Group
+        className={cn(fieldBase, className)}
+        aria-invalid={invalid || undefined}
+        data-preview-state={previewState}
+      >
+        <BaseNumberField.Input
+          ref={inputRef}
+          aria-label={label}
+          aria-invalid={invalid || undefined}
+          className={cn(fieldText, "tabular-nums")}
+          onKeyDown={(event) => {
+            if (event.key !== "Enter") return;
+            event.preventDefault();
+            commitFromText();
+          }}
+          onBlur={() => {
+            // Base UI's own blur handler returns without committing when the
+            // text does not parse. That is the only case left for us: a valid
+            // blur has already arrived through `onValueCommitted`.
+            const text = inputRef.current?.value.trim() ?? "";
+            if (text === "" || !Number.isFinite(Number(text))) setInvalid(true);
+          }}
+        />
+        {unit && (
+          <span className="shrink-0 select-none text-step-10 text-text-4" aria-hidden="true">
+            {unit}
+          </span>
+        )}
+      </BaseNumberField.Group>
+    </BaseNumberField.Root>
+  );
+}

package/src/components/ui/Popover.tsx

@@ -0,0 +1,74 @@
+/**
+ * Popover: `Menu`'s floating chrome (`popupSurface`) without item semantics, so arrow keys
+ * stay with whatever is focused inside (rename inputs, forms). Only the shadow differs.
+ */
+
+import { Popover as BasePopover } from "@base-ui/react/popover";
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+import { cn } from "./cn";
+import { popupSurface, type PopupPreviewState } from "./Menu";
+
+type PortalContainer = ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
+
+/** Matches Menu's gap from its trigger, and its viewport margin. */
+const SIDE_OFFSET = 6;
+const VIEWPORT_MARGIN = 8;
+
+interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof BasePopover.Root>, "children"> {
+  /** A single element. It becomes the trigger; no wrapper is added around it. */
+  trigger: ReactElement;
+  /** Arbitrary content. The popover owns none of its keys. */
+  children: ReactNode;
+  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. */
+  "aria-label"?: string;
+  /**
+   * What to focus on open. Defaults to Base UI's behaviour (the first tabbable
+   * element), which is what a rename field wants.
+   */
+  initialFocus?: ComponentPropsWithoutRef<typeof BasePopover.Popup>["initialFocus"];
+  className?: string;
+  "data-preview-state"?: PopupPreviewState;
+}
+
+export function Popover({
+  trigger,
+  children,
+  side = "bottom",
+  align = "center",
+  sideOffset = SIDE_OFFSET,
+  container,
+  className,
+  initialFocus,
+  "aria-label": ariaLabel,
+  "data-preview-state": previewState,
+  ...root
+}: PopoverProps) {
+  return (
+    <BasePopover.Root {...root}>
+      <BasePopover.Trigger render={trigger} />
+      <BasePopover.Portal container={container}>
+        <BasePopover.Positioner
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          collisionPadding={VIEWPORT_MARGIN}
+          className="z-200"
+        >
+          <BasePopover.Popup
+            aria-label={ariaLabel}
+            initialFocus={initialFocus}
+            data-preview-state={previewState}
+            className={cn(popupSurface, "p-3 text-step-11 text-text-1 shadow-popover", className)}
+          >
+            {children}
+          </BasePopover.Popup>
+        </BasePopover.Positioner>
+      </BasePopover.Portal>
+    </BasePopover.Root>
+  );
+}

package/src/components/ui/SearchInput.tsx

@@ -21,7 +21,7 @@ export function SearchInput({ className = "", ...props }: SearchInputProps) {
         height="12"
         viewBox="0 0 256 256"
         fill="none"
-        className="flex-shrink-0"
+        className="shrink-0"
         aria-hidden="true"
       >
         <circle
@@ -45,7 +45,7 @@ export function SearchInput({ className = "", ...props }: SearchInputProps) {
       </svg>
       <input
         type="text"
-        className="min-w-0 w-full bg-transparent text-[11px] text-panel-text-1 outline-none placeholder:text-panel-text-5"
+        className="min-w-0 w-full bg-transparent text-[11px] text-panel-text-1 outline-hidden placeholder:text-panel-text-5"
         {...props}
       />
     </div>

package/src/components/ui/Select.tsx

@@ -0,0 +1,100 @@
+/**
+ * Select: Base UI select in Input's box. The trigger keeps `role="combobox"`, which both hotkey selector
+ * lists match. Options are data, not children, so typeahead and the value display can read labels.
+ */
+
+import { Select as BaseSelect } from "@base-ui/react/select";
+import { cn } from "./cn";
+import { fieldBase } from "./Input";
+import type { PreviewState } from "./Button";
+
+export interface SelectOption {
+  label: string;
+  value: string;
+}
+
+export interface SelectProps {
+  /** Accessible name for the trigger. */
+  label: string;
+  value: string;
+  options: SelectOption[];
+  /** Called when a different option is chosen. */
+  onCommit: (next: string) => void;
+  /** Called once per committed change, for design-input telemetry. */
+  onTrack?: () => void;
+  disabled?: boolean;
+  className?: string;
+  "data-preview-state"?: PreviewState;
+}
+
+export function Select({
+  label,
+  value,
+  options,
+  onCommit,
+  onTrack,
+  disabled,
+  className,
+  "data-preview-state": previewState,
+}: SelectProps) {
+  return (
+    <BaseSelect.Root
+      value={value}
+      disabled={disabled}
+      items={options}
+      onValueChange={(next) => {
+        const chosen = String(next);
+        if (chosen === value) return;
+        onCommit(chosen);
+        onTrack?.();
+      }}
+    >
+      <BaseSelect.Trigger
+        aria-label={label}
+        className={cn(
+          fieldBase,
+          "w-full cursor-pointer justify-between text-left",
+          "data-[popup-open]:border-border-strong",
+          className,
+        )}
+        data-preview-state={previewState}
+      >
+        <BaseSelect.Value className="truncate" />
+        <BaseSelect.Icon className="shrink-0 text-text-4" aria-hidden="true">
+          <svg width="8" height="5" viewBox="0 0 8 5" fill="none">
+            <path
+              d="M1 1L4 4L7 1"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </BaseSelect.Icon>
+      </BaseSelect.Trigger>
+
+      <BaseSelect.Portal>
+        <BaseSelect.Positioner sideOffset={4} alignItemWithTrigger={false}>
+          <BaseSelect.Popup className="min-w-[var(--anchor-width)] rounded-md border border-border bg-surface py-1 shadow-menu outline-hidden">
+            <BaseSelect.List>
+              {options.map((option) => (
+                <BaseSelect.Item
+                  key={option.value}
+                  value={option.value}
+                  className={cn(
+                    "flex h-ctl-sm cursor-pointer select-none items-center gap-2 px-2.5",
+                    "text-step-11 text-text-2 outline-hidden",
+                    "data-[highlighted]:bg-hover data-[highlighted]:text-text-0",
+                    "data-[selected]:text-text-0",
+                  )}
+                >
+                  <BaseSelect.ItemText className="truncate">{option.label}</BaseSelect.ItemText>
+                </BaseSelect.Item>
+              ))}
+            </BaseSelect.List>
+          </BaseSelect.Popup>
+        </BaseSelect.Positioner>
+      </BaseSelect.Portal>
+    </BaseSelect.Root>
+  );
+}

package/src/components/ui/Slider.tsx

@@ -0,0 +1,153 @@
+/**
+ * Slider: `onPreview` fires while the thumb moves and writes nothing durable; `onCommit` (with `onTrack`, once)
+ * fires at a boundary. Right-click or Escape aborts a drag via `eventDetails.cancel()` and restores the start value.
+ */
+
+import { Slider as BaseSlider } from "@base-ui/react/slider";
+import { useEffect, useRef, useState } from "react";
+import { cn } from "./cn";
+import type { PreviewState } from "./Button";
+
+export interface SliderProps {
+  /** Accessible name for the thumb. The inspector's row label is the usual one. */
+  label: string;
+  /** The committed value. */
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  /** Every intermediate value while dragging or stepping. Not a commit. */
+  onPreview?: (next: number) => void;
+  /** Called at a commit boundary when the value really changed. */
+  onCommit: (next: number) => void;
+  /** Called once per commit boundary, for design-input telemetry. */
+  onTrack?: () => void;
+  disabled?: boolean;
+  className?: string;
+  "data-preview-state"?: PreviewState;
+}
+
+const first = (next: number | number[]): number => (Array.isArray(next) ? next[0] : next);
+
+export function Slider({
+  label,
+  value,
+  min,
+  max,
+  step,
+  onPreview,
+  onCommit,
+  onTrack,
+  disabled,
+  className,
+  "data-preview-state": previewState,
+}: SliderProps) {
+  const [draft, setDraft] = useState(value);
+  const draggingRef = useRef(false);
+  const abortedRef = useRef(false);
+  // The committed value the current gesture started from, so an abort has
+  // something to put back.
+  const dragStartRef = useRef(value);
+  // What was last handed to `onCommit`. A gesture's own commit lands before the
+  // parent re-renders, so deduping against the `value` prop would double-fire.
+  const committedRef = useRef(value);
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  // An external write wins, except mid-drag: the echo is a frame behind, and
+  // applying it would snap the thumb backwards under the pointer.
+  useEffect(() => {
+    if (draggingRef.current) return;
+    committedRef.current = value;
+    setDraft(value);
+  }, [value]);
+
+  const commit = (next: number) => {
+    if (next === committedRef.current) return;
+    committedRef.current = next;
+    onCommit(next);
+  };
+
+  const abort = () => {
+    if (!draggingRef.current) return;
+    abortedRef.current = true;
+    const start = dragStartRef.current;
+    setDraft(start);
+    onPreview?.(start);
+    commit(start);
+  };
+
+  return (
+    <BaseSlider.Root
+      value={draft}
+      min={min}
+      max={max}
+      step={step}
+      disabled={disabled}
+      onValueChange={(next, details) => {
+        if (abortedRef.current) {
+          // The pointer is still down after a right-click abort. Base UI would
+          // otherwise keep applying moves to a gesture the user cancelled.
+          details.cancel();
+          return;
+        }
+        const n = first(next);
+        setDraft(n);
+        onPreview?.(n);
+      }}
+      onValueCommitted={(next) => {
+        draggingRef.current = false;
+        if (abortedRef.current) {
+          abortedRef.current = false;
+          return;
+        }
+        commit(first(next));
+        onTrack?.();
+      }}
+      className={cn("flex min-w-0 items-center", className)}
+      data-preview-state={previewState}
+    >
+      <BaseSlider.Control
+        // A stable hook for the drag tests and for the screenshot script. Base
+        // UI's own marker on this part only exists before hydration.
+        data-slider-control="true"
+        // h-6 is the 24x24 WCAG 2.2 (2.5.8) target: the visible track stays
+        // 2px, only the pointer box grows.
+        className="flex h-6 w-full min-w-0 touch-none select-none items-center"
+        onPointerDown={() => {
+          draggingRef.current = true;
+          abortedRef.current = false;
+          dragStartRef.current = valueRef.current;
+        }}
+        onContextMenu={(event) => {
+          if (!draggingRef.current) return;
+          event.preventDefault();
+          abort();
+        }}
+        onKeyDown={(event) => {
+          if (event.key !== "Escape" || !draggingRef.current) return;
+          event.preventDefault();
+          abort();
+        }}
+      >
+        <BaseSlider.Track className="h-0.5 w-full rounded-full bg-hover">
+          <BaseSlider.Indicator className="rounded-full bg-text-5" />
+          <BaseSlider.Thumb
+            aria-label={label}
+            className={cn(
+              // The ring separates the thumb from the track behind it. A drop
+              // shadow would need a raw colour literal, which R5 does not allow
+              // outside the token file, and no shadow token fits a 10px dot.
+              "size-2.5 rounded-full bg-text-0 ring-2 ring-bg-1",
+              "cursor-grab active:cursor-grabbing data-[preview-state=active]:cursor-grabbing",
+              "hover:scale-110 data-[preview-state=hover]:scale-110",
+              "transition-transform ease-standard duration-hover",
+              "has-[:focus-visible]:outline-solid has-[:focus-visible]:outline-2 has-[:focus-visible]:outline-offset-2 has-[:focus-visible]:outline-accent",
+              "data-[preview-state=focus]:outline-solid data-[preview-state=focus]:outline-2 data-[preview-state=focus]:outline-offset-2 data-[preview-state=focus]:outline-accent",
+            )}
+          />
+        </BaseSlider.Track>
+      </BaseSlider.Control>
+    </BaseSlider.Root>
+  );
+}

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

@@ -0,0 +1,98 @@
+// @vitest-environment happy-dom
+
+/**
+ * Tabs: proves the shared strip reaches every tab by arrow key, something
+ * three of Studio's six hand-rolled strips don't.
+ */
+import React, { act } from "react";
+import { afterEach, expect, it } from "vitest";
+import { cleanupMounted, mountHost } from "./mountHost.testHelpers";
+import { Tab, TabPanel, Tabs, TabsList } from "./Tabs";
+
+const TABS = ["code", "comps", "assets", "catalog"];
+
+afterEach(cleanupMounted);
+
+function mount(): HTMLElement {
+  return mountHost(
+    <Tabs defaultValue="code">
+      <TabsList aria-label="Sidebar panels">
+        {TABS.map((id) => (
+          <Tab key={id} value={id}>
+            {id}
+          </Tab>
+        ))}
+      </TabsList>
+      {TABS.map((id) => (
+        <TabPanel key={id} value={id}>
+          {id} panel
+        </TabPanel>
+      ))}
+    </Tabs>,
+  );
+}
+
+function tab(host: HTMLElement, id: string): HTMLElement {
+  const el = host.querySelector<HTMLElement>(`[data-tab-id="${id}"]`);
+  if (!el) throw new Error(`no tab for ${id}`);
+  return el;
+}
+
+function selected(host: HTMLElement): string | null {
+  return (
+    host.querySelector('[role="tab"][aria-selected="true"]')?.getAttribute("data-tab-id") ?? null
+  );
+}
+
+/** Base UI moves the roving tabindex synchronously and the focus one task later. */
+async function arrow(key: string): Promise<void> {
+  const target = document.activeElement ?? document.body;
+  act(() => {
+    target.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, composed: true }));
+  });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+it("moves selection and focus with the arrow keys", async () => {
+  const host = mount();
+  act(() => tab(host, "code").focus());
+
+  await arrow("ArrowRight");
+
+  expect(selected(host)).toBe("comps");
+  expect(document.activeElement).toBe(tab(host, "comps"));
+});
+
+it("jumps to the first and last tab with Home and End", async () => {
+  const host = mount();
+  act(() => tab(host, "code").focus());
+
+  await arrow("End");
+  expect(selected(host)).toBe("catalog");
+  expect(document.activeElement).toBe(tab(host, "catalog"));
+
+  await arrow("Home");
+  expect(selected(host)).toBe("code");
+  expect(document.activeElement).toBe(tab(host, "code"));
+});
+
+it("labels the visible panel with its tab", () => {
+  const host = mount();
+  const panel = host.querySelector('[role="tabpanel"]:not([hidden])');
+
+  expect(panel?.textContent).toBe("code panel");
+  expect(panel?.getAttribute("aria-labelledby")).toBe(tab(host, "code").id);
+});
+
+it("carries data-tab-id, which the sidebar's focus restore looks up", () => {
+  // LeftSidebar finds a tab with `[data-tab-id="…"]` to restore focus after a
+  // programmatic switch. An attribute the primitive owns survives a reskin;
+  // the class it used to match on does not.
+  const host = mount();
+
+  expect(
+    [...host.querySelectorAll("[data-tab-id]")].map((el) => el.getAttribute("data-tab-id")),
+  ).toEqual(TABS);
+});

package/src/components/ui/Tabs.tsx

@@ -0,0 +1,71 @@
+/**
+ * Tabs — Base UI's tabs wearing Studio's tokens; replaces six hand-rolled
+ * strips with one implementation (roving tabindex, arrow/Home/End, `aria-controls`).
+ */
+
+import { Tabs as BaseTabs } from "@base-ui/react/tabs";
+import type { ComponentPropsWithoutRef, ElementType } from "react";
+import { cn } from "./cn";
+import type { PreviewState } from "./Button";
+
+/**
+ * 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;
+};
+
+/**
+ * Groups a tab list with its panels. Uncontrolled by default; pass `value` and
+ * `onValueChange` for a strip whose selection lives in a store.
+ */
+export function Tabs(props: ComponentPropsWithoutRef<typeof BaseTabs.Root>) {
+  return <BaseTabs.Root {...props} />;
+}
+
+/** The strip. Give it an `aria-label`: a tablist with no name is unlabelled. */
+export function TabsList({ className, ...props }: StyledProps<typeof BaseTabs.List>) {
+  return (
+    <BaseTabs.List
+      // Arrow keys move selection, matching today's sidebar strip.
+      activateOnFocus
+      className={cn("inline-flex items-center gap-0.5 rounded-lg bg-surface-alt p-1", className)}
+      {...props}
+    />
+  );
+}
+
+interface TabProps extends StyledProps<typeof BaseTabs.Tab> {
+  value: string;
+  "data-preview-state"?: PreviewState;
+}
+
+/**
+ * aria-selected drives the selected look (Base UI sets it) so assistive tech
+ * and sighted users match. data-preview-state is for gallery shots only.
+ */
+export function Tab({ value, className, ...props }: TabProps) {
+  return (
+    <BaseTabs.Tab
+      value={value}
+      data-tab-id={value}
+      className={cn(
+        "inline-flex h-ctl-sm cursor-pointer select-none items-center justify-center rounded-sm px-2.5",
+        "text-step-11 font-semibold whitespace-nowrap text-text-3",
+        "transition-[background-color,color] ease-out-quint duration-hover",
+        "hover:text-text-1 data-[preview-state=hover]:text-text-1",
+        "aria-selected:bg-hover aria-selected:text-text-0",
+        "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",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** The panel for one tab. Base UI wires `aria-labelledby` back to its tab. */
+export function TabPanel({ className, ...props }: StyledProps<typeof BaseTabs.Panel>) {
+  return <BaseTabs.Panel className={cn("outline-hidden", className)} {...props} />;
+}