@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

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} />;
+}

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/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>
+  );
+}