@volter/editor-sdk 0.5.57

package/src/widgets/primitives/Tooltip.tsx

@@ -0,0 +1,204 @@
+import {
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+
+interface TooltipProps {
+  text: string;
+  /** Explicitly `| undefined`: a hint resolved from the active keymap
+   *  (`keymap-presets.ts`) is absent when that keymap leaves the action
+   *  unbound, and the tooltip simply omits the `<kbd>` rather than lie. */
+  hotkey?: string | undefined;
+  children: ReactElement;
+  position?: TooltipPosition;
+  delay?: number;
+}
+
+interface TooltipCoordinates {
+  left: number;
+  top: number;
+  ready: boolean;
+}
+
+const VIEWPORT_GUTTER = 8;
+const TOOLTIP_GAP = 6;
+
+function opposite(position: TooltipPosition): TooltipPosition {
+  if (position === 'top') return 'bottom';
+  if (position === 'bottom') return 'top';
+  if (position === 'left') return 'right';
+  return 'left';
+}
+
+function placementFits(position: TooltipPosition, trigger: DOMRect, tooltip: DOMRect): boolean {
+  if (position === 'top') return trigger.top - tooltip.height - TOOLTIP_GAP >= VIEWPORT_GUTTER;
+  if (position === 'bottom')
+    return trigger.bottom + tooltip.height + TOOLTIP_GAP <= window.innerHeight - VIEWPORT_GUTTER;
+  if (position === 'left') return trigger.left - tooltip.width - TOOLTIP_GAP >= VIEWPORT_GUTTER;
+  return trigger.right + tooltip.width + TOOLTIP_GAP <= window.innerWidth - VIEWPORT_GUTTER;
+}
+
+function coordinatesFor(
+  position: TooltipPosition,
+  trigger: DOMRect,
+  tooltip: DOMRect,
+): TooltipCoordinates {
+  let left = trigger.left + (trigger.width - tooltip.width) / 2;
+  let top = trigger.top + (trigger.height - tooltip.height) / 2;
+  if (position === 'top') top = trigger.top - tooltip.height - TOOLTIP_GAP;
+  else if (position === 'bottom') top = trigger.bottom + TOOLTIP_GAP;
+  else if (position === 'left') left = trigger.left - tooltip.width - TOOLTIP_GAP;
+  else left = trigger.right + TOOLTIP_GAP;
+
+  return {
+    left: Math.max(
+      VIEWPORT_GUTTER,
+      Math.min(left, window.innerWidth - tooltip.width - VIEWPORT_GUTTER),
+    ),
+    top: Math.max(
+      VIEWPORT_GUTTER,
+      Math.min(top, window.innerHeight - tooltip.height - VIEWPORT_GUTTER),
+    ),
+    ready: true,
+  };
+}
+
+/**
+ * Canonical editor tooltip.
+ *
+ * The popup is portaled to the editor theme root and positioned against the
+ * viewport. That lets it escape dock/panel overflow clipping without leaking
+ * outside the theme boundary. Pointer and keyboard focus both expose the same
+ * accessible description.
+ */
+export function Tooltip({
+  text,
+  hotkey,
+  children,
+  position = 'bottom',
+  delay = 400,
+}: TooltipProps) {
+  const id = useId();
+  const wrapperRef = useRef<HTMLSpanElement>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+  const timer = useRef<ReturnType<typeof setTimeout>>(null);
+  const hovered = useRef(false);
+  const focused = useRef(false);
+  const [visible, setVisible] = useState(false);
+  const [portalRoot, setPortalRoot] = useState<Element | null>(null);
+  const [coordinates, setCoordinates] = useState<TooltipCoordinates>({
+    left: 0,
+    top: 0,
+    ready: false,
+  });
+
+  useLayoutEffect(() => {
+    setPortalRoot(wrapperRef.current?.closest('.vgai-editor-theme') ?? null);
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const hide = () => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    setVisible(false);
+  };
+
+  const hideIfInactive = () => {
+    if (!hovered.current && !focused.current) hide();
+  };
+
+  const show = (wait: number) => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      setCoordinates((current) => ({ ...current, ready: false }));
+      setVisible(true);
+    }, wait);
+  };
+
+  useLayoutEffect(() => {
+    if (!visible) return;
+    const update = () => {
+      const trigger = wrapperRef.current?.getBoundingClientRect();
+      const tooltip = tooltipRef.current?.getBoundingClientRect();
+      if (!trigger || !tooltip) return;
+      const resolved = placementFits(position, trigger, tooltip) ? position : opposite(position);
+      setCoordinates(coordinatesFor(resolved, trigger, tooltip));
+    };
+    update();
+    window.addEventListener('resize', update);
+    window.addEventListener('scroll', update, true);
+    return () => {
+      window.removeEventListener('resize', update);
+      window.removeEventListener('scroll', update, true);
+    };
+  }, [hotkey, position, text, visible]);
+
+  let child = children;
+  if (isValidElement<{ 'aria-describedby'?: string }>(children)) {
+    const describedBy = [children.props['aria-describedby'], visible ? id : null]
+      .filter(Boolean)
+      .join(' ');
+    child = cloneElement(children, describedBy ? { 'aria-describedby': describedBy } : {});
+  }
+
+  return (
+    <span
+      ref={wrapperRef}
+      className="vgai-tooltip-anchor"
+      onMouseEnter={() => {
+        hovered.current = true;
+        show(delay);
+      }}
+      onMouseLeave={() => {
+        hovered.current = false;
+        hideIfInactive();
+      }}
+      onFocusCapture={() => {
+        focused.current = true;
+        show(0);
+      }}
+      onBlurCapture={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          focused.current = false;
+          hideIfInactive();
+        }
+      }}
+    >
+      {child}
+      {visible &&
+        portalRoot &&
+        createPortal(
+          <div
+            ref={tooltipRef}
+            id={id}
+            role="tooltip"
+            className="vgai-tooltip"
+            style={{
+              left: coordinates.left,
+              top: coordinates.top,
+              visibility: coordinates.ready ? 'visible' : 'hidden',
+            }}
+          >
+            <span>{text}</span>
+            {hotkey && <kbd>{hotkey}</kbd>}
+          </div>,
+          portalRoot,
+        )}
+    </span>
+  );
+}

package/src/widgets/primitives/Vec3Input.tsx

@@ -0,0 +1,70 @@
+import { NumberInput } from './NumberInput';
+
+interface Vec3InputProps {
+  value: [number | null, number | null, number | null];
+  onChange: (value: [number, number, number]) => void;
+  /** Per-axis callback for multi-edit. When provided, takes priority over onChange. */
+  onAxisChange?: (axis: 0 | 1 | 2, value: number) => void;
+  step?: number;
+  disabled?: boolean;
+  /** When set, each axis field gets `data-testid="{prefix}-x|y|z"` for e2e. */
+  testIdPrefix?: string | undefined;
+}
+
+export function Vec3Input({
+  value,
+  onChange,
+  onAxisChange,
+  step = 0.1,
+  disabled = false,
+  testIdPrefix,
+}: Vec3InputProps) {
+  const tid = (axis: 'x' | 'y' | 'z') => (testIdPrefix ? `${testIdPrefix}-${axis}` : undefined);
+  const handleAxis = (axis: 0 | 1 | 2) => (v: number) => {
+    if (onAxisChange) {
+      onAxisChange(axis, v);
+    } else {
+      const tuple: [number, number, number] = [value[0] ?? 0, value[1] ?? 0, value[2] ?? 0];
+      tuple[axis] = v;
+      onChange(tuple);
+    }
+  };
+
+  // Axis tint literals are deliberate (not tokenized): they mirror the
+  // viewport gizmo's R/G/B axis colors, a cross-tool convention (Unity/
+  // Blender) distinct from the semantic danger/success/accent tones.
+  return (
+    <div style={{ display: 'flex', gap: 4 }}>
+      <NumberInput
+        label="X"
+        labelColor="#E06178"
+        value={value[0]}
+        onChange={handleAxis(0)}
+        step={step}
+        disabled={disabled}
+        style={{ flex: 1 }}
+        testId={tid('x')}
+      />
+      <NumberInput
+        label="Y"
+        labelColor="#C2ED66"
+        value={value[1]}
+        onChange={handleAxis(1)}
+        step={step}
+        disabled={disabled}
+        style={{ flex: 1 }}
+        testId={tid('y')}
+      />
+      <NumberInput
+        label="Z"
+        labelColor="#6BABF5"
+        value={value[2]}
+        onChange={handleAxis(2)}
+        step={step}
+        disabled={disabled}
+        style={{ flex: 1 }}
+        testId={tid('z')}
+      />
+    </div>
+  );
+}

package/src/widgets/primitives/banner-tones.ts

@@ -0,0 +1,32 @@
+import { themeVars } from '../theme';
+
+/**
+ * Shared semantic-tone triples for dismissible chrome banners
+ * (V-16): two sibling banners each hand-rolled an identical-shaped
+ * `{bg, border, fg}` triple as its own inline magic values — built from the
+ * same lightness formula, but two independent literals with no shared
+ * constant. Hoisted here so a future retouch of one can't silently drift
+ * from the other (the same class of bug V-4 already demonstrated happened
+ * to `PlayBar`'s button styles).
+ *
+ * These are tinted-panel triples, not `theme.ts`'s flat `danger`/`warn`
+ * scalars (`theme.ts` has no "dark tinted banner background" slot) — kept
+ * as their own small module rather than added to the shared token file.
+ */
+
+export interface BannerTone {
+  bg: string;
+  border: string;
+  fg: string;
+}
+
+export const TONE_ERROR: BannerTone = {
+  bg: themeVars.semantic.dangerFaint,
+  border: themeVars.semantic.danger,
+  fg: themeVars.semantic.danger,
+};
+export const TONE_WARNING: BannerTone = {
+  bg: themeVars.semantic.warningMuted,
+  border: themeVars.semantic.warning,
+  fg: themeVars.semantic.warning,
+};

package/src/widgets/primitives/clamp-to-viewport.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared clamp-to-viewport positioning (P6 glass-native chrome, U6.5 F5/F11).
+ *
+ * A popup/panel that anchors to a pointer position (a right-click context menu)
+ * or otherwise sets its own absolute/fixed `top`/`left` can open partly — or
+ * entirely — off the visible window when the anchor sits near an edge. This
+ * utility takes the *desired* rect (position + measured size) and returns a
+ * shifted `{ top, left }` that keeps the whole rect inside the window: it never
+ * resizes, only slides the popup so
+ *
+ *   top ≥ margin, bottom ≤ innerHeight − margin,
+ *   left ≥ margin, right ≤ innerWidth − margin.
+ *
+ * If the rect is larger than the viewport on an axis the leading edge wins
+ * (the popup pins to `margin` and lets the far edge overflow) so the anchor /
+ * first items stay reachable rather than the popup vanishing upward or left.
+ *
+ * Keep this the single home for the clamp — do not re-derive the arithmetic at
+ * each call site.
+ */
+export interface ClampDesiredRect {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ClampedPoint {
+  readonly top: number;
+  readonly left: number;
+}
+
+export function clampRectToViewport(desired: ClampDesiredRect, margin = 8): ClampedPoint {
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  // Math.max(margin, …) guards the case where the popup is wider/taller than the
+  // window: the upper bound collapses to `margin`, pinning the leading edge.
+  const maxLeft = Math.max(margin, viewportWidth - desired.width - margin);
+  const maxTop = Math.max(margin, viewportHeight - desired.height - margin);
+  return {
+    left: Math.min(Math.max(desired.left, margin), maxLeft),
+    top: Math.min(Math.max(desired.top, margin), maxTop),
+  };
+}

package/src/widgets/primitives/editor-icons.ts

@@ -0,0 +1,245 @@
+import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import {
+  faArrowPointer,
+  faArrowsRotate,
+  faArrowsToDot,
+  faArrowUpFromBracket,
+  faBookOpen,
+  faBorderAll,
+  faBorderTopLeft,
+  faCamera,
+  faChartSimple,
+  faCheck,
+  faCircleExclamation,
+  faCircleHalfStroke,
+  faCircleInfo,
+  faCode,
+  faCompress,
+  faCrosshairs,
+  faCube,
+  faCubesStacked,
+  faDiagramProject,
+  faExpand,
+  faEye,
+  faEyeSlash,
+  faFile,
+  faFileCode,
+  faFileExport,
+  faFolder,
+  faFolderOpen,
+  faFolderTree,
+  faForwardStep,
+  faGripLines,
+  faHammer,
+  faHand,
+  faImage,
+  faLightbulb,
+  faList,
+  faLock,
+  faLockOpen,
+  faMagnet,
+  faMagnifyingGlass,
+  faMagnifyingGlassMinus,
+  faMagnifyingGlassPlus,
+  faMaximize,
+  faMusic,
+  faPause,
+  faPlay,
+  faPlus,
+  faPuzzlePiece,
+  faRotate,
+  faRotateLeft,
+  faRotateRight,
+  faScissors,
+  faSliders,
+  faStop,
+  faTable,
+  faTableCells,
+  faTrash,
+  faTriangleExclamation,
+  faUpDownLeftRight,
+  faUpRightAndDownLeftFromCenter,
+  faUsers,
+  faXmark,
+} from '@fortawesome/free-solid-svg-icons';
+
+/**
+ * A definition under a name of OURS, carrying a Font Awesome drawing until an
+ * icon set supplies its own (see `editorIcons.modeling`). The name is the only
+ * thing that changes: `icon` — the width/height/path tuple every renderer
+ * actually paints — is the source definition's, so nothing moves on screen
+ * until a set keys the new name.
+ */
+function meshGlyph(iconName: string, source: IconDefinition): IconDefinition {
+  return { ...source, iconName: iconName as IconDefinition['iconName'] };
+}
+
+/**
+ * Semantic icon registry for editor chrome. Components may still import a
+ * genuinely domain-specific Font Awesome definition, but recurring actions,
+ * content kinds, status, and viewport tools use these stable meanings.
+ */
+export const editorIcons = {
+  action: {
+    add: faPlus,
+    close: faXmark,
+    delete: faTrash,
+    search: faMagnifyingGlass,
+    refresh: faArrowsRotate,
+    undo: faRotateLeft,
+    redo: faRotateRight,
+    build: faHammer,
+    export: faFileExport,
+    select: faArrowPointer,
+  },
+  transport: {
+    play: faPlay,
+    pause: faPause,
+    restart: faRotateRight,
+    stop: faStop,
+    step: faForwardStep,
+  },
+  content: {
+    project: faFolderOpen,
+    folder: faFolder,
+    file: faFile,
+    source: faFileCode,
+    scene: faBookOpen,
+    entity: faCube,
+    component: faPuzzlePiece,
+    camera: faCamera,
+    light: faLightbulb,
+    image: faImage,
+    audio: faMusic,
+    data: faTable,
+    code: faCode,
+    stateMachine: faDiagramProject,
+  },
+  status: {
+    success: faCheck,
+    info: faCircleInfo,
+    warning: faTriangleExclamation,
+    error: faCircleExclamation,
+    visible: faEye,
+    hidden: faEyeSlash,
+    locked: faLock,
+    unlocked: faLockOpen,
+  },
+  /** The 3D viewport's navigation cluster (`ViewportFurniture`). */
+  viewport: {
+    zoomIn: faMagnifyingGlassPlus,
+    zoomOut: faMagnifyingGlassMinus,
+    pan: faHand,
+    frame: faExpand,
+    /**
+     * IT OWNS ITS NAME, for the reason `modeling` below states in full:
+     * Blender's mark for this toggle is a grid IN PERSPECTIVE — a trapezoid,
+     * measured 32x26 device on `modeling-edit-none.png`'s navigation capsule —
+     * while three other sites ask for `border-all` and all three mean a FLAT
+     * grid (the canvas viewport's grid toggle, the 3D overlay's, and the CSS
+     * border editor's "all borders"). Redrawing the shared name would have
+     * put a receding floor on a CSS border button. Font Awesome's `border-all`
+     * stays as the drawing, so a set without this key paints what it painted.
+     */
+    projection: meshGlyph('viewport-projection', faBorderAll),
+  },
+  /**
+   * Mesh-modeling operators — the shelf glyphs a modeling document shows
+   * (Blender's toolbar column). One per operator the `mesh` capability ships;
+   * a contribution reaches them through `@volter/editor-sdk/widgets`.
+   *
+   * EACH OWNS ITS NAME. An icon set keys a glyph by `icon.iconName`
+   * (`EditorIcon` → `activeIconGlyph`), so while these pointed at
+   * `scissors`/`compress`/`grip-lines`/`table-cells` the operator mark and
+   * every OTHER site using that name were one drawing: redrawing Knife as a
+   * cut cube would have recut the editor's scissors everywhere. Blender draws
+   * an operator AS THE OPERATION ON A CUBE, which is meaningless as a generic
+   * mark, so the two must be separable — hence the `mesh-*` names below, which
+   * no other site asks for.
+   *
+   * Font Awesome's `IconPrefix`/`IconName` are closed string unions of ITS
+   * catalog, so a name of ours cannot typecheck as one: the prefix stays the
+   * source definition's (nothing looks a glyph up by prefix) and the name is
+   * asserted. The `icon` tuple stays the source's too, so a set that does not
+   * carry the `mesh-*` name still paints exactly what it painted before.
+   */
+  modeling: {
+    extrude: meshGlyph('mesh-extrude', faArrowUpFromBracket),
+    inset: meshGlyph('mesh-inset', faCompress),
+    bevel: meshGlyph('mesh-bevel', faBorderTopLeft),
+    loopCut: meshGlyph('mesh-loop-cut', faGripLines),
+    knife: meshGlyph('mesh-knife', faScissors),
+    smooth: meshGlyph('mesh-smooth', faCircleHalfStroke),
+    shrinkFatten: meshGlyph('mesh-shrink-fatten', faUpRightAndDownLeftFromCenter),
+    subdivide: meshGlyph('mesh-subdivide', faTableCells),
+  },
+  tool: {
+    extension: faPuzzlePiece,
+    /**
+     * THE TRANSFORM TOOLS OF THE SHELF (`ToolStrip`) — Blender's Edit Mode
+     * toolbar group 2, in Blender's own order: Move, Rotate, Scale,
+     * Transform.
+     *
+     * Move and Rotate keep the shared Font Awesome names because the Blender
+     * set's drawings for `up-down-left-right` and `rotate` say the same thing
+     * at every other site that asks for them. Scale and Transform do not:
+     * they asked for `maximize` (Font Awesome's window-expand cross) and
+     * `arrows-to-dot` (a crosshair), which are generic meanings other
+     * surfaces can reasonably want, and Blender's marks for the two tools —
+     * a small square growing into a larger outlined one, and a square inside
+     * a broken ring of arrows — are not those meanings. Same rule as
+     * `modeling` above: a glyph that IS an operation owns its own name.
+     */
+    /** Blender's group 1, Select Box — the tool that arms no gizmo. It shares
+     *  `arrow-pointer` with the action set's `select` above, because the two
+     *  mean the same thing and the Blender set already carries one drawing of
+     *  it in Blender's idiom (`blender-icons.source.mjs`, under `-- tools --`).
+     *  Blender's own mark is that pointer inside a dashed marquee; the marquee
+     *  is what this glyph does not carry, and that is the one difference
+     *  between the two shelves' first button. */
+    select: faArrowPointer,
+    move: faUpDownLeftRight,
+    rotate: faRotate,
+    scale: meshGlyph('tool-scale', faMaximize),
+    transform: meshGlyph('tool-transform', faArrowsToDot),
+    snap: faMagnet,
+    frame: faCrosshairs,
+    grid: faBorderAll,
+    profiler: faChartSimple,
+  },
+  /**
+   * A STATIC PANEL'S OWN GLYPH — what Blender puts in an area's EDITOR-TYPE
+   * WELL, and the only place this editor draws one (`workspace-regions.ts`'s
+   * `groupTabs`). `workspace-static-panels.ts` declares WHICH glyph per panel
+   * by name and takes {@link WorkspacePanelGlyphName} as a type-only import,
+   * so the inventory stays a dependency-free table and no panel can name a
+   * glyph this one does not resolve.
+   *
+   * TWO OF THESE ARE MEASURED AND FIVE ARE OURS, and the split is a fact
+   * about the reference frames rather than about effort. `outliner` and
+   * `properties` are Blender's own marks, read at native 2x off
+   * `outliner.png` and `modeling-edit-none.png`'s Properties area and drawn
+   * in `@vgai/blender`'s `blender-icons.source.mjs`, which carries the pixel
+   * edges. The other five have NO Blender reading at all: the reference set
+   * photographs the Layout, Modeling, Sculpting and Texture Paint workspaces
+   * — 3D View, Outliner, Properties, Timeline, Image Editor and the asset
+   * shelf — with every editor-type dropdown CLOSED, so it contains no File
+   * Browser, no Asset Browser, and no picture of the editors our Content,
+   * Library, Conversations, Project work and History panels correspond to.
+   * They reuse names the Blender set already draws, chosen here, so a well
+   * stays in that set's idiom instead of falling through to a Font Awesome
+   * silhouette beside two measured marks.
+   */
+  panel: {
+    outliner: meshGlyph('outliner', faFolderTree),
+    properties: meshGlyph('properties', faSliders),
+    'folder-open': faFolderOpen,
+    'cubes-stacked': faCubesStacked,
+    users: faUsers,
+    list: faList,
+    'rotate-left': faRotateLeft,
+  },
+} as const;
+
+/** The glyph names a static panel may declare (`workspace-static-panels.ts`). */
+export type WorkspacePanelGlyphName = keyof (typeof editorIcons)['panel'];

package/src/widgets/primitives/panel-header-styles.ts

@@ -0,0 +1,42 @@
+import type React from 'react';
+import { fontWeight, space, themeVars } from '../theme';
+
+/**
+ * Shared typography and metrics for panel titles and disclosure sections.
+ *
+ * The heights are the VARS, not `chromeSize`'s constants: a material may
+ * retune the chrome's density, and the constant is only the editor's own
+ * default. Read at module load it cannot learn the active material — the
+ * Blender material declares a 26px panel header and every Panel still drew
+ * the default 30, because `--vgai-panel-header-height` (which does carry the
+ * material's value) was not what this style read.
+ */
+export const panelHeaderLabelStyle: React.CSSProperties = {
+  minHeight: 'var(--vgai-panel-header-height)',
+  padding: `0 ${space[4]}px`,
+  color: themeVars.content.muted,
+  fontSize: 'var(--vgai-font-base)',
+  fontWeight: fontWeight.semibold,
+  textTransform: 'uppercase',
+  display: 'flex',
+  alignItems: 'center',
+  gap: space[2],
+  userSelect: 'none',
+};
+
+/** Disclosure rows are one density step below full panel headers. */
+export const sectionHeaderLabelStyle: React.CSSProperties = {
+  ...panelHeaderLabelStyle,
+  minHeight: 'var(--vgai-local-toolbar-height)',
+};
+
+/** Complete header rail treatment for a standalone panel. Glass treatments
+ *  emit a transparent structural surface; opaque/reduced-transparency themes
+ *  retain their occluding stack through the same variable. Headers never
+ *  own the content-frost filter. */
+export const panelHeaderStyle: React.CSSProperties = {
+  ...panelHeaderLabelStyle,
+  background: 'var(--vgai-surface-sticky)',
+  borderBottom: '1px solid var(--vgai-structural-divider)',
+  flexShrink: 0,
+};