@volter/editor-sdk 0.5.57

package/src/widgets/primitives/Menu.tsx

@@ -0,0 +1,140 @@
+import {
+  type ButtonHTMLAttributes,
+  forwardRef,
+  type HTMLAttributes,
+  type RefObject,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+} from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export interface MenuProps extends HTMLAttributes<HTMLDivElement> {
+  autoFocusFirst?: boolean;
+  /** Optional trigger/anchor that counts as part of the menu's dismissal boundary.
+   * Portaled menus need this so pressing their trigger closes them once instead
+   * of the document-level outside handler closing on pointerdown and the
+   * trigger's click immediately reopening them. */
+  dismissBoundaryRef?: RefObject<HTMLElement | null>;
+  onDismiss?: (reason: MenuDismissReason) => void;
+}
+
+export type MenuDismissReason = 'escape' | 'outside';
+
+function enabledItems(menu: HTMLDivElement): HTMLElement[] {
+  return Array.from(
+    menu.querySelectorAll<HTMLElement>(
+      '[role="menuitem"]:not(:disabled), [role="menuitemradio"]:not(:disabled), [role="menuitemcheckbox"]:not(:disabled)',
+    ),
+  );
+}
+
+/** Focus a menu's first enabled item. Exported so a portaled owner (AnchoredMenu)
+ * can drive autofocus AFTER it unhides: browsers refuse `focus()` inside a
+ * `visibility:hidden` subtree and never restore it on unhide, so the passive
+ * mount-time effect below fires too early for a measure-then-show menu. */
+export function focusFirstMenuItem(menu: HTMLDivElement): void {
+  enabledItems(menu)[0]?.focus();
+}
+
+export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
+  {
+    className,
+    role = 'menu',
+    autoFocusFirst = false,
+    dismissBoundaryRef,
+    onDismiss,
+    onKeyDown,
+    ...props
+  },
+  ref,
+) {
+  const localRef = useRef<HTMLDivElement>(null);
+  useImperativeHandle(ref, () => localRef.current as HTMLDivElement);
+  useEffect(() => {
+    if (autoFocusFirst) enabledItems(localRef.current as HTMLDivElement)[0]?.focus();
+  }, [autoFocusFirst]);
+  useEffect(() => {
+    if (!onDismiss) return;
+    const dismissOutside = (event: PointerEvent) => {
+      const target = event.target as Node;
+      if (!localRef.current?.contains(target) && !dismissBoundaryRef?.current?.contains(target)) {
+        onDismiss('outside');
+      }
+    };
+    document.addEventListener('pointerdown', dismissOutside);
+    return () => document.removeEventListener('pointerdown', dismissOutside);
+  }, [dismissBoundaryRef, onDismiss]);
+
+  return (
+    <div
+      {...props}
+      ref={localRef}
+      role={role}
+      className={classes('vgai-menu', className)}
+      onKeyDown={(event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) return;
+        if (event.key === 'Escape') {
+          event.preventDefault();
+          onDismiss?.('escape');
+          return;
+        }
+        if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
+        event.preventDefault();
+        const items = enabledItems(event.currentTarget);
+        if (items.length === 0) return;
+        const current = items.indexOf(document.activeElement as HTMLElement);
+        if (event.key === 'Home') items[0]?.focus();
+        else if (event.key === 'End') items.at(-1)?.focus();
+        else if (event.key === 'ArrowDown')
+          items[(current + 1 + items.length) % items.length]?.focus();
+        else items[(current - 1 + items.length) % items.length]?.focus();
+      }}
+    />
+  );
+});
+
+export type MenuItemProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  onSelect?: (() => void) | undefined;
+};
+
+export const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(function MenuItem(
+  { className, type = 'button', role = 'menuitem', onClick, onSelect, ...props },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type={type}
+      role={role}
+      className={classes('vgai-menu-item', className)}
+      onClick={(event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) onSelect?.();
+      }}
+    />
+  );
+});
+
+export function MenuSeparator(props: HTMLAttributes<HTMLHRElement>) {
+  return <hr {...props} className={classes('vgai-menu-separator', props.className)} />;
+}
+
+export const MenuTrigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
+  function MenuTrigger({ className, type = 'button', ...props }, ref) {
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type={type}
+        aria-haspopup={props['aria-haspopup'] ?? 'menu'}
+        className={classes('vgai-menu-trigger', className)}
+      />
+    );
+  },
+);

package/src/widgets/primitives/NumberInput.tsx

@@ -0,0 +1,169 @@
+import { useEffect, useRef, useState } from 'react';
+import { useInteractiveEditScope } from '../interactive-edit-scope';
+import { TextInput } from './FormControls';
+
+interface NumberInputProps {
+  value: number | null; // null = mixed (multi-edit)
+  onChange: (value: number) => void;
+  /**
+   * Fires once per discrete edit gesture — a drag's pointerup (with the
+   * drag's FINAL value) or a typed edit's blur/Enter — instead of on every
+   * intermediate `onChange` call (which still fires on every pointermove
+   * during a drag, for callers that want live feedback as the value moves).
+   * Optional: existing callers that only wired `onChange` are unaffected. A
+   * caller whose `onChange` triggers something expensive per call (a file
+   * write, a network POST — see DataPanel's DATA-tab number cells, #3)
+   * should commit through THIS instead, so a 2-second scrub fires exactly
+   * one commit, not dozens.
+   */
+  onChangeEnd?: (value: number) => void;
+  step?: number;
+  /**
+   * Decimal places in the resting display. Defaults to 3 — the right read for
+   * a transform axis, and a nonsense one for a whole-number tuning field
+   * (`ROUNDS 3.000`). A caller that knows its field's granularity passes it;
+   * `TuningPanel` derives it from the schema's step.
+   */
+  precision?: number;
+  /** Read-only: no scrub, no typed edit. Optional — existing callers unchanged. */
+  disabled?: boolean;
+  label?: string;
+  labelColor?: string | undefined;
+  style?: React.CSSProperties;
+  /** Stable test hook (set on the wrapper; the edit <input> is its descendant). */
+  testId?: string | undefined;
+  /** Hover text for the whole field (a channel's read-only reason, say). */
+  title?: string | undefined;
+}
+
+export function NumberInput({
+  value,
+  onChange,
+  onChangeEnd,
+  step = 0.1,
+  precision = 3,
+  disabled = false,
+  label,
+  labelColor,
+  style,
+  testId,
+  title,
+}: NumberInputProps) {
+  const [editing, setEditing] = useState(false);
+  const [text, setText] = useState('');
+  const dragRef = useRef({ startX: 0, startVal: 0, dragging: false, gesture: false, lastVal: 0 });
+  const inputRef = useRef<HTMLInputElement>(null);
+  const editScope = useInteractiveEditScope();
+
+  useEffect(() => {
+    if (!editing) return;
+    const input = inputRef.current;
+    if (!input) return;
+    input.focus();
+    // THE WHOLE VALUE IS SELECTED WHEN THE EDITOR OPENS, so typing REPLACES
+    // it — every number field in every DCC tool. Focused without a
+    // selection, a typed number was spliced into the old text and committed
+    // as garbage: click the field showing -5, type -7, Enter → -47;
+    // double-click, type -9 → -459 (measured on the GPU instrument,
+    // 2026-09-03). That is the "everything's there, just not where I wanted
+    // it" and "it jumped" of runhuman passes 122 and 127 — the author typed
+    // one number and the field committed another.
+    input.select();
+  }, [editing]);
+
+  const isMixed = value === null;
+  const numValue = value ?? 0;
+  const display = isMixed
+    ? '—'
+    : Number.isFinite(numValue)
+      ? numValue.toFixed(precision)
+      : (0).toFixed(precision);
+
+  const handlePointerDown = (e: React.PointerEvent) => {
+    if (disabled) return;
+    dragRef.current = {
+      startX: e.clientX,
+      startVal: numValue,
+      dragging: false,
+      gesture: false,
+      lastVal: numValue,
+    };
+    const onMove = (me: PointerEvent) => {
+      const dx = me.clientX - dragRef.current.startX;
+      if (Math.abs(dx) > 3) dragRef.current.dragging = true;
+      if (dragRef.current.dragging) {
+        // Coalesce the whole scrub into a single undo step: open the gesture
+        // just before the first value change (so the snapshot is pre-drag).
+        if (!dragRef.current.gesture) {
+          dragRef.current.gesture = true;
+          editScope?.begin();
+        }
+        const newVal = dragRef.current.startVal + dx * step;
+        const rounded = Math.round(newVal / step) * step;
+        dragRef.current.lastVal = rounded;
+        onChange(rounded);
+      }
+    };
+    const onUp = () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      if (dragRef.current.gesture) editScope?.end();
+      if (dragRef.current.dragging) {
+        // One commit for the whole gesture (#3) — `onChange` above already
+        // fired per pointermove for callers that want live feedback; this is
+        // the single "the user is done" signal, with the drag's final value.
+        onChangeEnd?.(dragRef.current.lastVal);
+      } else {
+        setEditing(true);
+        setText(isMixed ? '' : display);
+      }
+    };
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+  };
+
+  const commitEdit = () => {
+    setEditing(false);
+    const n = Number.parseFloat(text);
+    if (Number.isFinite(n)) {
+      onChange(n);
+      onChangeEnd?.(n);
+    }
+  };
+
+  return (
+    <div className="vgai-number-input" data-testid={testId} title={title} style={style}>
+      {label && (
+        <span
+          className="vgai-number-input-label"
+          style={labelColor ? { color: labelColor } : undefined}
+        >
+          {label}
+        </span>
+      )}
+      {editing ? (
+        <TextInput
+          ref={inputRef}
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          onBlur={commitEdit}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') commitEdit();
+            if (e.key === 'Escape') setEditing(false);
+          }}
+          placeholder={isMixed ? '—' : undefined}
+          className="vgai-number-input-editor"
+        />
+      ) : (
+        <div
+          onPointerDown={handlePointerDown}
+          className="vgai-number-input-scrub"
+          data-mixed={isMixed || undefined}
+          data-disabled={disabled || undefined}
+        >
+          {display}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/widgets/primitives/Panel.tsx

@@ -0,0 +1,80 @@
+import type React from 'react';
+import { space } from '../theme';
+import { panelHeaderStyle } from './panel-header-styles';
+
+interface PanelOwnProps {
+  name: React.ReactNode;
+  actions?: React.ReactNode;
+  onHeaderClick?: () => void;
+  /** The dock host already names permanent panels in its tab strip. Hide the
+   * legacy embedded header there to avoid two consecutive titles for one
+   * surface while retaining Panel's content/layout behavior. */
+  hideHeader?: boolean;
+}
+
+type PanelProps = PanelOwnProps &
+  Omit<React.HTMLAttributes<HTMLDivElement>, keyof PanelOwnProps> & {
+    /** React 19 ref-as-prop, forwarded onto the panel's own scroll/root div. */
+    ref?: React.Ref<HTMLDivElement>;
+  };
+
+export function Panel({
+  name,
+  actions,
+  onHeaderClick,
+  hideHeader = false,
+  style,
+  children,
+  ...rest
+}: PanelProps) {
+  return (
+    <div
+      {...rest}
+      style={{
+        // No surface fill of its own (§2.31 transparent-interiors wave): the
+        // hosting dock group / floating card layer carries the themed panel
+        // surface. A Panel that floats free of any painted surface opts into
+        // one locally via `style` (see the design-system stories).
+        display: 'flex',
+        flexDirection: 'column',
+        pointerEvents: 'auto',
+        ...style,
+      }}
+    >
+      {!hideHeader && (
+        <div
+          role={onHeaderClick ? 'button' : undefined}
+          tabIndex={onHeaderClick ? 0 : undefined}
+          onClick={onHeaderClick}
+          onKeyDown={
+            onHeaderClick
+              ? (e) => {
+                  if (e.key === 'Enter') onHeaderClick();
+                }
+              : undefined
+          }
+          style={{
+            ...panelHeaderStyle,
+            cursor: onHeaderClick ? 'pointer' : undefined,
+            pointerEvents: 'auto',
+          }}
+        >
+          <span style={{ flexShrink: 0 }}>{name}</span>
+          {actions && (
+            <div
+              style={{
+                marginLeft: 'auto',
+                display: 'flex',
+                alignItems: 'center',
+                gap: space[3],
+              }}
+            >
+              {actions}
+            </div>
+          )}
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}

package/src/widgets/primitives/SectionHeader.tsx

@@ -0,0 +1,77 @@
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import { type ReactNode, useState } from 'react';
+import { DisclosureIcon, EditorIcon } from './EditorIcon';
+
+interface SectionHeaderProps {
+  label: string;
+  /** The section's glyph, beside the disclosure arrow. Every inspection
+   *  section carries one (`inspection/model.ts` makes `icon` required), so a
+   *  section reads the same in the stacked column as it does on the compact
+   *  card's icon strip. */
+  icon?: IconDefinition;
+  description?: ReactNode;
+  actions?: ReactNode;
+  /**
+   * `false` heads the section without a disclosure control and keeps it open.
+   * Collapsing is what a STACK is for — hiding one block to reach the next.
+   * Where a single section is showing because you pressed its tab, a triangle
+   * offers to hide the only thing in the box (owner, 2026-08-07: "in small
+   * mode there's no reason for a collapsible triangle on the section name").
+   */
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+  /* The disclosure's size is `--vgai-section-disclosure-size` where a surface
+   * sets one, and `--vgai-icon-xs` — `DisclosureIcon`'s own default rung —
+   * where none does, so a host that declares nothing renders exactly what it
+   * rendered before. The one declarer is the PROPERTIES presentation
+   * (`compact-inspector.css`), where Blender's band mark measures 5.5x9.5 CSS
+   * against the 4x6 this rung draws. */
+  children: ReactNode;
+}
+
+export function SectionHeader({
+  label,
+  icon,
+  description,
+  actions,
+  collapsible = true,
+  defaultOpen = true,
+  children,
+}: SectionHeaderProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const title = (
+    <span className="vgai-section-title">
+      <span>{label}</span>
+      {description ? <small>{description}</small> : null}
+    </span>
+  );
+
+  return (
+    <section className="vgai-section">
+      <div className="vgai-section-header">
+        {collapsible ? (
+          <button
+            type="button"
+            className="vgai-section-trigger"
+            aria-expanded={open}
+            onClick={() => setOpen(!open)}
+          >
+            <DisclosureIcon
+              direction={open ? 'down' : 'right'}
+              style={{ fontSize: 'var(--vgai-section-disclosure-size, var(--vgai-icon-xs))' }}
+            />
+            {icon && <EditorIcon icon={icon} tone="dim" className="vgai-section-glyph" />}
+            {title}
+          </button>
+        ) : (
+          <div className="vgai-section-trigger" data-vgai-static>
+            {icon && <EditorIcon icon={icon} tone="dim" className="vgai-section-glyph" />}
+            {title}
+          </div>
+        )}
+        {actions ? <div className="vgai-section-actions">{actions}</div> : null}
+      </div>
+      {(open || !collapsible) && <div className="vgai-section-body">{children}</div>}
+    </section>
+  );
+}

package/src/widgets/primitives/Text.tsx

@@ -0,0 +1,54 @@
+import { type ComponentType, type ElementType, forwardRef, type HTMLAttributes } from 'react';
+
+export type TextVariant = 'caption' | 'body' | 'label' | 'title' | 'heading' | 'display' | 'code';
+export type TextTone = 'primary' | 'muted' | 'dim' | 'accent' | 'danger' | 'warning' | 'success';
+
+export interface TextProps extends HTMLAttributes<HTMLElement> {
+  as?: ElementType;
+  variant?: TextVariant;
+  tone?: TextTone;
+  truncate?: boolean;
+  selectable?: boolean;
+}
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+/** Semantic editor typography. Product surfaces choose a role, never a px size. */
+export const Text = forwardRef<HTMLElement, TextProps>(function Text(
+  {
+    as: Component = 'span',
+    variant = 'body',
+    tone = 'primary',
+    truncate = false,
+    selectable = false,
+    className,
+    ...props
+  },
+  ref,
+) {
+  // `as` is polymorphic, so TS intersects props across EVERY member of
+  // `ElementType`. That intersection collapses to `never` the moment the JSX
+  // namespace grows — which it now does: the R3F design session pulls
+  // `@react-three/fiber`'s `IntrinsicElements` augmentation into the editor's
+  // program, and `ref`/`className` stopped being assignable here with no
+  // change to this file. Narrow the callee to the prop shape this component
+  // actually documents in `TextProps`.
+  const Element = Component as ComponentType<Record<string, unknown>>;
+  return (
+    <Element
+      {...props}
+      ref={ref}
+      data-variant={variant}
+      data-tone={tone}
+      data-truncate={truncate || undefined}
+      data-selectable={selectable || undefined}
+      className={classes('vgai-text', className)}
+    />
+  );
+});
+
+export function Keycap({ className, ...props }: HTMLAttributes<HTMLElement>) {
+  return <kbd {...props} className={classes('vgai-keycap', className)} />;
+}

package/src/widgets/primitives/ThemeRootPortal.tsx

@@ -0,0 +1,52 @@
+import { type ReactNode, useId, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * Portal children to the nearest `.vgai-editor-theme` root — the same target
+ * resolution `Tooltip` uses (`Tooltip.tsx`), extracted for `position: fixed`
+ * overlays that open from inside a panel (context menus).
+ *
+ * Why this exists (Glass-UI spike, W6 — work item 6): `backdrop-filter` (like
+ * `filter`/`transform`) makes an element the containing block for ALL
+ * positioned descendants, including `position: fixed`. An inline
+ * fixed-position menu inside a treated floating card would position relative
+ * to the card — at the wrong place — and be clipped by the card's `overflow:
+ * hidden`. The theme root carries no filter, so a menu portaled here keeps
+ * viewport-correct client coordinates under every workspace layout and
+ * theme treatment.
+ *
+ * THE PORTAL RECORDS WHERE IT CAME FROM, and that is what makes a portaled
+ * overlay reachable through the surface that opened it. The anchor span below
+ * already sits IN PLACE — it is how the theme root is found — so the two ends
+ * carry the same generated id: `data-vgai-portal` where the portal was
+ * written, `data-vgai-portal-content` on what it wrote. `editor-document-probe`
+ * walks that pair, so `editor.document.click` can drive a menu a DOCUMENT
+ * opened without being able to reach one the editor's own chrome opened. Its
+ * own header used to say the DOM records no ownership and that any heuristic
+ * wide enough would over-reach; this is the ownership, stated rather than
+ * guessed. A `display: contents` wrapper generates no box, so nothing about
+ * where a `position: fixed` child lands changes.
+ */
+export function ThemeRootPortal({ children }: { children: ReactNode }) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [portalRoot, setPortalRoot] = useState<Element | null>(null);
+  const id = useId();
+
+  useLayoutEffect(() => {
+    setPortalRoot(anchorRef.current?.closest('.vgai-editor-theme') ?? null);
+  }, []);
+
+  return (
+    <>
+      <span ref={anchorRef} data-vgai-portal={id} style={{ display: 'none' }} />
+      {portalRoot
+        ? createPortal(
+            <div data-vgai-portal-content={id} style={{ display: 'contents' }}>
+              {children}
+            </div>,
+            portalRoot,
+          )
+        : null}
+    </>
+  );
+}