@volter/editor-sdk 0.5.57

package/src/widgets/patterns/Surfaces.tsx

@@ -0,0 +1,122 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export type EditorTone = 'info' | 'warning' | 'error' | 'success';
+export type EditorSurfaceVariant = 'shell' | 'panel' | 'chrome' | 'raised' | 'inset' | 'overlay';
+
+export interface EditorSurfaceProps extends HTMLAttributes<HTMLDivElement> {
+  variant?: EditorSurfaceVariant;
+  border?: boolean;
+  scroll?: boolean;
+}
+
+export function EditorSurface({
+  variant = 'panel',
+  border = false,
+  scroll = false,
+  className,
+  ...props
+}: EditorSurfaceProps) {
+  return (
+    <div
+      {...props}
+      data-variant={variant}
+      data-border={border || undefined}
+      data-scroll={scroll || undefined}
+      className={classes('vgai-surface', className)}
+    />
+  );
+}
+
+export interface EditorBannerProps extends HTMLAttributes<HTMLDivElement> {
+  tone?: EditorTone;
+  icon?: ReactNode;
+  actions?: ReactNode;
+}
+
+export function EditorBanner({
+  tone = 'info',
+  icon,
+  actions,
+  className,
+  children,
+  ...props
+}: EditorBannerProps) {
+  return (
+    <div
+      {...props}
+      role={tone === 'error' ? 'alert' : 'status'}
+      data-tone={tone}
+      className={classes('vgai-banner', className)}
+    >
+      {icon && <span className="vgai-banner-icon">{icon}</span>}
+      <div className="vgai-banner-content">{children}</div>
+      {actions && <div className="vgai-banner-actions">{actions}</div>}
+    </div>
+  );
+}
+
+export const EditorPopover = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function EditorPopover({ className, ...props }, ref) {
+    return <div ref={ref} {...props} className={classes('vgai-popover', className)} />;
+  },
+);
+
+export interface EditorBadgeProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Labels are the safe default. Use count only for compact numeric counters. */
+  shape?: 'label' | 'count';
+}
+
+export function EditorBadge({ shape = 'label', className, ...props }: EditorBadgeProps) {
+  return <span {...props} data-shape={shape} className={classes('vgai-badge', className)} />;
+}
+
+export interface DropIndicatorProps extends HTMLAttributes<HTMLDivElement> {
+  position?: 'before' | 'inside' | 'after';
+}
+
+export function DropIndicator({ position = 'inside', className, ...props }: DropIndicatorProps) {
+  return (
+    <div
+      {...props}
+      aria-hidden="true"
+      data-position={position}
+      className={classes('vgai-drop-indicator', className)}
+    />
+  );
+}
+
+export interface ResizeHandleProps extends HTMLAttributes<HTMLDivElement> {
+  orientation: 'horizontal' | 'vertical';
+  label: string;
+  valueNow?: number;
+  valueMin?: number;
+  valueMax?: number;
+}
+
+export function ResizeHandle({
+  orientation,
+  label,
+  valueNow,
+  valueMin = 0,
+  valueMax = 100,
+  className,
+  ...props
+}: ResizeHandleProps) {
+  return (
+    <div
+      {...props}
+      role="separator"
+      aria-label={label}
+      aria-orientation={orientation}
+      aria-valuenow={valueNow}
+      aria-valuemin={valueNow === undefined ? undefined : valueMin}
+      aria-valuemax={valueNow === undefined ? undefined : valueMax}
+      data-orientation={orientation}
+      className={classes('vgai-resize-handle', className)}
+    />
+  );
+}

package/src/widgets/patterns/Tabs.tsx

@@ -0,0 +1,80 @@
+import { type ButtonHTMLAttributes, forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export const EditorTabList = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function EditorTabList({ className, onKeyDown, ...props }, ref) {
+    return (
+      <div
+        {...props}
+        ref={ref}
+        role="tablist"
+        className={classes('vgai-tabs', className)}
+        onKeyDown={(event) => {
+          onKeyDown?.(event);
+          if (event.defaultPrevented) return;
+          if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;
+          const tabs = Array.from(
+            event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="tab"]:not(:disabled)'),
+          );
+          if (tabs.length === 0) return;
+          event.preventDefault();
+          const current = tabs.indexOf(document.activeElement as HTMLButtonElement);
+          const next =
+            event.key === 'Home'
+              ? tabs[0]
+              : event.key === 'End'
+                ? tabs.at(-1)
+                : event.key === 'ArrowRight'
+                  ? tabs[(current + 1 + tabs.length) % tabs.length]
+                  : tabs[(current - 1 + tabs.length) % tabs.length];
+          next?.focus();
+        }}
+      />
+    );
+  },
+);
+
+export interface EditorTabProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  selected?: boolean;
+  dirty?: boolean;
+  badge?: ReactNode;
+}
+
+export const EditorTab = forwardRef<HTMLButtonElement, EditorTabProps>(function EditorTab(
+  {
+    selected = false,
+    dirty = false,
+    badge,
+    className,
+    type = 'button',
+    tabIndex,
+    children,
+    ...props
+  },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type={type}
+      role="tab"
+      tabIndex={tabIndex ?? (selected ? 0 : -1)}
+      aria-selected={selected}
+      data-selected={selected || undefined}
+      className={classes('vgai-tab', className)}
+    >
+      {dirty && (
+        <>
+          <span className="vgai-tab-dirty" title="Unsaved" aria-hidden="true" />
+          <span className="vgai-sr-only">Unsaved</span>
+        </>
+      )}
+      <span className="vgai-tab-label">{children}</span>
+      {badge !== undefined && <span className="vgai-tab-badge">{badge}</span>}
+    </button>
+  );
+});

package/src/widgets/patterns/Toolbar.tsx

@@ -0,0 +1,72 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export interface EditorToolbarProps extends HTMLAttributes<HTMLDivElement> {
+  label: string;
+  compact?: boolean;
+  /** Independent controls may be active together; single-selection toolbars emphasize one choice. */
+  selectionMode?: 'independent' | 'single';
+}
+
+export const EditorToolbar = forwardRef<HTMLDivElement, EditorToolbarProps>(function EditorToolbar(
+  { label, compact = false, selectionMode = 'independent', className, ...props },
+  ref,
+) {
+  return (
+    <div
+      {...props}
+      ref={ref}
+      role="toolbar"
+      aria-label={label}
+      data-compact={compact || undefined}
+      data-selection-mode={selectionMode}
+      className={classes('vgai-toolbar', className)}
+    />
+  );
+});
+
+export function ToolbarGroup({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} role="group" className={classes('vgai-toolbar-group', className)} />;
+}
+
+export function ToolbarDivider(props: HTMLAttributes<HTMLSpanElement>) {
+  return (
+    <span
+      {...props}
+      aria-hidden="true"
+      className={classes('vgai-toolbar-divider', props.className)}
+    />
+  );
+}
+
+/** Viewport-local tool cluster. Placement remains the viewport's
+ * responsibility. `vgai-glass-island` opts the cluster into the refraction
+ * engine's opt-in island surface set (P6 — glass-native chrome): under a
+ * glass theme on a capable GPU it carries its own url() displacement
+ * chain; everywhere else the class is inert and the var-driven
+ * `.vgai-floating-toolbar` paint decides (including inside floating cards,
+ * where the engine refuses islands — one filter per card). */
+export function FloatingToolbar({ className, onPointerDownCapture, ...props }: EditorToolbarProps) {
+  return (
+    <EditorToolbar
+      {...props}
+      compact
+      className={classes('vgai-floating-toolbar vgai-glass-island', className)}
+      onPointerDownCapture={(event) => {
+        onPointerDownCapture?.(event);
+        // Viewport floating toolbars live inside the element owned by
+        // OrbitControls. Without this capture boundary, OrbitControls sees a
+        // button pointerdown, captures the pointer to the viewport container,
+        // and the button never receives the matching pointerup/click.
+        event.stopPropagation();
+      }}
+    />
+  );
+}
+
+export function SplitButtonGroup({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} role="group" className={classes('vgai-split-button', className)} />;
+}

package/src/widgets/patterns/Tree.tsx

@@ -0,0 +1,72 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export interface EditorTreeProps extends HTMLAttributes<HTMLDivElement> {
+  label: string;
+}
+
+export const EditorTree = forwardRef<HTMLDivElement, EditorTreeProps>(function EditorTree(
+  { label, className, ...props },
+  ref,
+) {
+  return (
+    <div
+      {...props}
+      ref={ref}
+      role="tree"
+      aria-label={label}
+      className={classes('vgai-tree', className)}
+    />
+  );
+});
+
+export interface EditorTreeRowProps extends HTMLAttributes<HTMLDivElement> {
+  level?: number;
+  selected?: boolean;
+  expanded?: boolean | undefined;
+  muted?: boolean;
+  dragging?: boolean;
+  leading?: ReactNode;
+  actions?: ReactNode;
+}
+
+export const EditorTreeRow = forwardRef<HTMLDivElement, EditorTreeRowProps>(function EditorTreeRow(
+  {
+    level = 1,
+    selected = false,
+    expanded,
+    muted = false,
+    dragging = false,
+    leading,
+    actions,
+    className,
+    children,
+    style,
+    ...props
+  },
+  ref,
+) {
+  return (
+    <div
+      {...props}
+      ref={ref}
+      role="treeitem"
+      tabIndex={props.tabIndex ?? -1}
+      aria-level={level}
+      aria-selected={selected}
+      {...(expanded === undefined ? {} : { 'aria-expanded': expanded })}
+      data-selected={selected || undefined}
+      data-muted={muted || undefined}
+      data-dragging={dragging || undefined}
+      className={classes('vgai-tree-row', className)}
+      style={{ paddingLeft: 6 + Math.max(0, level - 1) * 14, ...style }}
+    >
+      {leading && <span className="vgai-tree-row-leading">{leading}</span>}
+      <span className="vgai-tree-row-label">{children}</span>
+      {actions && <span className="vgai-tree-row-actions">{actions}</span>}
+    </div>
+  );
+});

package/src/widgets/primitives/AnchoredMenu.tsx

@@ -0,0 +1,260 @@
+import {
+  type ButtonHTMLAttributes,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import { clampRectToViewport } from './clamp-to-viewport';
+import { focusFirstMenuItem, Menu, type MenuDismissReason, MenuItem, type MenuProps } from './Menu';
+import { ThemeRootPortal } from './ThemeRootPortal';
+
+export interface AnchoredMenuProps extends Omit<MenuProps, 'children' | 'onDismiss' | 'style'> {
+  anchorRef: RefObject<HTMLElement | null>;
+  children: ReactNode;
+  /** Horizontal edge shared with the trigger. Game-toolbar menus are trailing-aligned. */
+  align?: 'start' | 'end';
+  /** Which side of the trigger the menu opens toward. A trigger at the bottom
+   * of the viewport (a composer control) opens 'top' — upward — so the menu
+   * stays on screen. `right` and `left` open BESIDE it with their top edge on
+   * the trigger's, which is what a SUBMENU does: its trigger is one row of the
+   * menu above it, so opening downward would cover the rows below. `align` is
+   * not read for those two — a side placement's cross-axis is the trigger's
+   * own top. */
+  side?: 'bottom' | 'top' | 'right' | 'left';
+  gap?: number;
+  /** Slide the placed rect back inside the window when the trigger sits near
+   * an edge (`clampRectToViewport`). Opt-in: a trigger that cannot reach an
+   * edge keeps the exact shared-edge alignment, which is why this is not the
+   * default. */
+  clamp?: boolean;
+  onDismiss: () => void;
+  style?: CSSProperties;
+}
+
+/**
+ * A menu positioned against a trigger while portaled to the owning theme root.
+ *
+ * Glass surfaces create containing/stacking contexts through backdrop-filter.
+ * A dropdown left inside one cannot out-stack a neighbouring glass card no
+ * matter how large its local z-index is. This primitive measures the existing
+ * trigger/menu geometry, expresses the same placement in viewport coordinates,
+ * and portals the menu to the filter-free theme root. It deliberately does not
+ * clamp: callers that can reach a viewport edge own that policy separately via
+ * `clampRectToViewport`.
+ */
+export function AnchoredMenu({
+  anchorRef,
+  align = 'end',
+  side = 'bottom',
+  autoFocusFirst = true,
+  gap = 4,
+  clamp = false,
+  onDismiss,
+  style,
+  children,
+  ...props
+}: AnchoredMenuProps) {
+  const [menuElement, setMenuElement] = useState<HTMLDivElement | null>(null);
+  const [position, setPosition] = useState<{ left: number; top: number } | null>(null);
+  const positionRef = useRef<{ left: number; top: number } | null>(null);
+  const restoreFocusOnUnmount = useRef(true);
+  const didAutoFocus = useRef(false);
+
+  const updatePosition = useCallback(() => {
+    const anchor = anchorRef.current;
+    if (!anchor || !menuElement) return;
+    const anchorRect = anchor.getBoundingClientRect();
+    const menuRect = menuElement.getBoundingClientRect();
+    const beside = side === 'right' || side === 'left';
+    const placed = beside
+      ? {
+          left: side === 'right' ? anchorRect.right + gap : anchorRect.left - gap - menuRect.width,
+          top: anchorRect.top,
+        }
+      : {
+          left: align === 'end' ? anchorRect.right - menuRect.width : anchorRect.left,
+          top: side === 'top' ? anchorRect.top - gap - menuRect.height : anchorRect.bottom + gap,
+        };
+    const next = clamp
+      ? clampRectToViewport({ ...placed, width: menuRect.width, height: menuRect.height })
+      : placed;
+    const current = positionRef.current;
+    if (current?.left === next.left && current.top === next.top) return;
+    positionRef.current = next;
+    setPosition(next);
+  }, [align, anchorRef, clamp, gap, menuElement, side]);
+
+  useLayoutEffect(() => {
+    const anchor = anchorRef.current;
+    if (!anchor || !menuElement) return;
+    updatePosition();
+
+    // Portaling changes the menu from anchor-relative CSS geometry to fixed
+    // viewport coordinates. Preserve the old continuous attachment contract.
+    // ResizeObserver covers size changes but intentionally does not report a
+    // position-only reflow, and transforms/layout can move an anchor without
+    // emitting window resize or scroll. While this transient menu is open,
+    // one animation-frame geometry read is the only complete signal. The
+    // ref equality guard above keeps settled frames free of React updates.
+    let frame = 0;
+    const trackPosition = () => {
+      updatePosition();
+      frame = requestAnimationFrame(trackPosition);
+    };
+    frame = requestAnimationFrame(trackPosition);
+    window.addEventListener('resize', updatePosition);
+    document.addEventListener('scroll', updatePosition, true);
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(updatePosition);
+    resizeObserver?.observe(anchor);
+    resizeObserver?.observe(menuElement);
+    return () => {
+      const restoreFocus =
+        restoreFocusOnUnmount.current && menuElement.contains(document.activeElement);
+      window.removeEventListener('resize', updatePosition);
+      document.removeEventListener('scroll', updatePosition, true);
+      cancelAnimationFrame(frame);
+      resizeObserver?.disconnect();
+      // A selected item unmounts its menu through the caller rather than the
+      // Menu dismissal callback. Restore after that commit, while leaving an
+      // outside-pointer target in control of focus.
+      if (restoreFocus) queueMicrotask(() => anchorRef.current?.focus());
+    };
+  }, [anchorRef, menuElement, updatePosition]);
+
+  // Drive autofocus HERE, not through Menu's mount-time effect. The menu is
+  // `visibility:hidden` until the measure pass sets `position`; a `focus()`
+  // into a hidden subtree is refused by the browser and not restored on
+  // unhide, so Menu's passive focus fires uselessly on the first commit. Focus
+  // once, right after we unhide, guarding against the rAF reposition loop
+  // stealing focus back to the first item mid-navigation.
+  useLayoutEffect(() => {
+    if (!autoFocusFirst || didAutoFocus.current) return;
+    if (!menuElement || !position) return;
+    didAutoFocus.current = true;
+    focusFirstMenuItem(menuElement);
+  }, [autoFocusFirst, menuElement, position]);
+
+  const handleDismiss = (reason: MenuDismissReason) => {
+    restoreFocusOnUnmount.current = reason !== 'outside';
+    onDismiss();
+    if (reason === 'escape') anchorRef.current?.focus();
+  };
+
+  return (
+    <ThemeRootPortal>
+      <Menu
+        {...props}
+        ref={setMenuElement}
+        dismissBoundaryRef={anchorRef}
+        onDismiss={handleDismiss}
+        style={{
+          ...style,
+          position: 'fixed',
+          left: position?.left ?? 0,
+          top: position?.top ?? 0,
+          visibility: position ? style?.visibility : 'hidden',
+        }}
+      >
+        {children}
+      </Menu>
+    </ThemeRootPortal>
+  );
+}
+
+/**
+ * A MENU ROW THAT OPENS A MENU OF ITS OWN — the nested half of `Menu`, and the
+ * shape every DCC menu bar has (Blender draws `Mesh ▸`, `Light ▸`, `Apply ▸`,
+ * `Clear ▸` and `Set Origin ▸` this way; so does every desktop application
+ * menu). It lives HERE rather than beside `MenuItem` because it opens an
+ * {@link AnchoredMenu}, and `AnchoredMenu` is what imports `Menu` — the other
+ * direction would be a cycle.
+ *
+ * IT OWNS ITS OWN OPEN STATE, which is what makes it a primitive rather than a
+ * pattern every caller re-coordinates. Opening is a hover or a click, both of
+ * which a person reaches for. CLOSING is the part that is easy to get wrong:
+ * the child menu is PORTALED (menus escape glass stacking contexts), so moving
+ * the pointer from this row into the menu it just opened fires `pointerleave`
+ * on the row. `relatedTarget` is the element being ENTERED, so a leave into
+ * this submenu's own subtree is not a leave at all — and a sibling row's hover
+ * closes this one by being somewhere else. The subtree is found by a `data`
+ * attribute rather than by a ref, because `AnchoredMenu` portals its menu and
+ * forwards no handle to it.
+ *
+ * Choosing a row in the child unmounts the whole tree through the caller's own
+ * close, which is why there is no `onSelect` here: this row has no action.
+ */
+export function MenuSubmenu({
+  label,
+  children,
+  gap = 0,
+  ...props
+}: Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onSelect'> & {
+  label: ReactNode;
+  children: ReactNode;
+  /** Passed through to the child menu's placement. */
+  gap?: number;
+}) {
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const id = useId();
+  const staysOpen = (node: EventTarget | null): boolean =>
+    node instanceof Element &&
+    (triggerRef.current?.contains(node) === true ||
+      node.closest(`[data-vgai-submenu="${id}"]`) !== null);
+  const leave = (event: { relatedTarget: EventTarget | null }): void => {
+    if (!staysOpen(event.relatedTarget)) setOpen(false);
+  };
+  return (
+    <>
+      <MenuItem
+        {...props}
+        ref={triggerRef}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onPointerEnter={() => setOpen(true)}
+        onPointerLeave={leave}
+        onClick={(event) => {
+          // A click on this row OPENS and never selects or closes: the row has
+          // no action of its own, so letting the click through would close the
+          // whole menu having done nothing, and toggling would close a submenu
+          // a person had just pointed at. Blender's submenus behave the same —
+          // they close by leaving them or by Escape.
+          event.preventDefault();
+          setOpen(true);
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'ArrowRight' || event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            setOpen(true);
+          }
+          if (event.key === 'ArrowLeft') setOpen(false);
+        }}
+      >
+        <span style={{ flex: 1 }}>{label}</span>
+        <span aria-hidden="true" style={{ paddingInlineStart: 'var(--vgai-space-4)' }}>
+          ▸
+        </span>
+      </MenuItem>
+      {open && (
+        <AnchoredMenu
+          anchorRef={triggerRef}
+          data-vgai-submenu={id}
+          side="right"
+          gap={gap}
+          clamp
+          autoFocusFirst={false}
+          onDismiss={() => setOpen(false)}
+          onPointerLeave={leave}
+        >
+          {children}
+        </AnchoredMenu>
+      )}
+    </>
+  );
+}

package/src/widgets/primitives/Button.tsx

@@ -0,0 +1,62 @@
+import { type ButtonHTMLAttributes, forwardRef, type ReactNode } from 'react';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'success';
+export type ButtonSize = 'compact' | 'default' | 'comfortable';
+export type ButtonShape = 'default' | 'segment';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  /** Segment reserves a stable capsule footprint for mode/tool selections. */
+  shape?: ButtonShape;
+}
+
+export type IconButtonProps = Omit<ButtonProps, 'aria-label'> & {
+  'aria-label': string;
+  /** Optional visible caption rendered below the icon for labelled toolbars. */
+  visibleLabel?: ReactNode;
+};
+
+/** Canonical editor button. Visual variants and dimensions live in theme.css. */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  {
+    variant = 'secondary',
+    size = 'default',
+    shape = 'default',
+    className,
+    type = 'button',
+    ...props
+  },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type={type}
+      className={className ? `vgai-btn ${className}` : 'vgai-btn'}
+      data-variant={variant}
+      data-size={size}
+      data-shape={shape}
+    />
+  );
+});
+
+/** Icon-only button. The accessible name is required by its public type. */
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
+  { variant = 'ghost', visibleLabel, children, ...props },
+  ref,
+) {
+  return (
+    <Button
+      {...props}
+      ref={ref}
+      variant={variant}
+      data-icon="true"
+      data-label-placement={visibleLabel === undefined ? undefined : 'below'}
+    >
+      {children}
+      {visibleLabel !== undefined && <span className="vgai-icon-button-label">{visibleLabel}</span>}
+    </Button>
+  );
+});