@vgai/editor 0.2.0

package/src/components/data-csv.ts

@@ -0,0 +1,301 @@
+/**
+ * CSV round-trip for TABLE data assets (W6c, docs/DATA-TOOLS-DESIGN.md §7).
+ *
+ * React-free, sibling discipline to `inspectors/json-schema-fields.ts` — pure
+ * functions, unit-tested in Node, no DOM.
+ *
+ * ARCHITECTURE RULE: the editor never executes the project's Zod schema (the
+ * W2 pin — see `json-schema-fields.ts`'s header). Cell coercion here is by
+ * the EMITTED schema's `DataFieldDescriptor` KIND only (number/boolean/enum/
+ * string/color/group/json) — never a real `.parse()`. Real validation stays
+ * at the runtime parse-on-load (`defineData`) and the W5 build
+ * plugin/`vgai doctor` gate; this module's job is just "don't corrupt the
+ * file", not "be a validator".
+ *
+ * Import is WHOLE-TABLE REPLACE, deliberately: a CSV file IS the table (every
+ * row this import doesn't mention is gone). And it's ATOMIC — any coercion
+ * error anywhere in the sheet means NOTHING is written; the caller must not
+ * call `writeFile` when `errors.length > 0`.
+ */
+
+import type { DataFieldDescriptor } from './inspectors/json-schema-fields';
+import { defaultValueForDescriptor } from './inspectors/json-schema-fields';
+
+// ---------------------------------------------------------------------------
+// Export: table -> CSV text
+// ---------------------------------------------------------------------------
+
+/** RFC-4180 field escaping: quote when the cell contains a comma, quote, or
+ *  newline; double any embedded quote. */
+function escapeCsvField(value: string): string {
+  if (/[",\r\n]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/** One CSV cell for row-schema field `f`, from row value `v` (the row's
+ *  current value under key `f.name`, or `undefined` if absent). */
+function cellToCsv(f: DataFieldDescriptor, v: unknown): string {
+  if (v === undefined) return '';
+  // Nested/unrenderable kinds — or any non-primitive runtime value, in case
+  // data and schema disagree — round-trip as a JSON-encoded cell.
+  if (f.kind === 'group' || f.kind === 'json' || (v !== null && typeof v === 'object')) {
+    return escapeCsvField(JSON.stringify(v));
+  }
+  return escapeCsvField(String(v));
+}
+
+/**
+ * Serialize a table asset's data (minus `"$schema"`) to CSV text: header
+ * `key,<rowFields in schema order>`, one line per data key in FILE order,
+ * `\r\n` line endings (spreadsheet-friendly), trailing newline.
+ */
+export function tableToCsv(
+  data: Record<string, unknown>,
+  rowFields: DataFieldDescriptor[],
+): string {
+  const header = ['key', ...rowFields.map((f) => f.name)].map(escapeCsvField).join(',');
+  const lines = [header];
+  for (const [key, row] of Object.entries(data)) {
+    if (key === '$schema') continue;
+    const rowObj = row && typeof row === 'object' ? (row as Record<string, unknown>) : {};
+    const cells = [escapeCsvField(key), ...rowFields.map((f) => cellToCsv(f, rowObj[f.name]))];
+    lines.push(cells.join(','));
+  }
+  return `${lines.join('\r\n')}\r\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Import: CSV text -> string[][], then -> table
+// ---------------------------------------------------------------------------
+
+/**
+ * Advance one step while scanning INSIDE a quoted field. Returns the next
+ * scan position, the character (if any) to append to the current field, and
+ * whether this step closed the quote — pulled out of `parseCsv`'s main loop
+ * purely to keep that loop's branching flat (this is the one place with
+ * nested conditionals: a `""` escape vs. a closing `"`).
+ */
+function stepQuoted(
+  text: string,
+  i: number,
+): { next: number; char: string | null; closed: boolean } {
+  const ch = text[i]!;
+  if (ch !== '"') return { next: i + 1, char: ch, closed: false };
+  if (text[i + 1] === '"') return { next: i + 2, char: '"', closed: false }; // `""` escape
+  return { next: i + 1, char: null, closed: true }; // closing quote
+}
+
+/**
+ * Minimal RFC-4180 parser: quoted fields, `""` escapes, `\r\n`/`\n` line
+ * endings, no external deps. Returns rows of raw string cells (no
+ * type coercion — that's `csvToTable`'s job).
+ */
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = '';
+  let inQuotes = false;
+  let i = 0;
+  const n = text.length;
+
+  const endField = () => {
+    row.push(field);
+    field = '';
+  };
+  const endRow = () => {
+    endField();
+    rows.push(row);
+    row = [];
+  };
+
+  while (i < n) {
+    if (inQuotes) {
+      const step = stepQuoted(text, i);
+      if (step.char !== null) field += step.char;
+      if (step.closed) inQuotes = false;
+      i = step.next;
+      continue;
+    }
+    const ch = text[i]!;
+    if (ch === '"') {
+      inQuotes = true;
+      i += 1;
+      continue;
+    }
+    if (ch === ',') {
+      endField();
+      i += 1;
+      continue;
+    }
+    if (ch === '\r' || ch === '\n') {
+      // Treat \r\n and bare \r as one line ending.
+      if (ch === '\r' && text[i + 1] === '\n') i += 1;
+      endRow();
+      i += 1;
+      continue;
+    }
+    field += ch;
+    i += 1;
+  }
+  // Trailing field/row (no terminating newline, or the file has one and this
+  // is an empty tail — skip a wholly-empty trailing row from a final \r\n).
+  if (field !== '' || row.length > 0) {
+    endRow();
+  }
+  return rows;
+}
+
+/** Coerce one raw CSV cell string to field `f`'s runtime value. Returns
+ *  `{ error }` instead of throwing — the caller aggregates errors across the
+ *  whole sheet and refuses the import atomically if any exist. */
+function coerceCell(
+  raw: string,
+  f: DataFieldDescriptor,
+  rowNum: number,
+): { value: unknown } | { error: string } {
+  if (raw === '') {
+    // This is a PRESENT cell that's blank — `coerceRow` handles an entirely
+    // MISSING column itself and never reaches here with one (#5). A
+    // `kind: 'string'` field's blank cell IS the value `""`, never "absent",
+    // so it must not be swapped for the schema's default: an export→reimport
+    // of a legitimately-empty string field has to be a no-op diff, not a
+    // mutation. Every other kind has no meaningful "empty" runtime value, so
+    // those keep falling back to the field default.
+    return { value: f.kind === 'string' ? '' : defaultValueForDescriptor(f) };
+  }
+  switch (f.kind) {
+    case 'number': {
+      const n = Number(raw);
+      if (!Number.isFinite(n)) {
+        return { error: `row ${rowNum}, col ${f.name}: "${raw}" is not a number` };
+      }
+      return { value: n };
+    }
+    case 'boolean': {
+      const lower = raw.trim().toLowerCase();
+      if (lower === 'true' || lower === '1') return { value: true };
+      if (lower === 'false' || lower === '0') return { value: false };
+      return { error: `row ${rowNum}, col ${f.name}: "${raw}" is not a boolean (true/false/1/0)` };
+    }
+    case 'enum': {
+      const options = f.options ?? [];
+      if (!options.includes(raw)) {
+        return {
+          error: `row ${rowNum}, col ${f.name}: "${raw}" is not one of [${options.join(', ')}]`,
+        };
+      }
+      return { value: raw };
+    }
+    case 'string':
+    case 'color':
+      return { value: raw };
+    case 'group':
+    case 'json':
+      try {
+        return { value: JSON.parse(raw) };
+      } catch {
+        return { error: `row ${rowNum}, col ${f.name}: "${raw}" is not valid JSON` };
+      }
+    default:
+      return { value: raw };
+  }
+}
+
+export interface CsvImportResult {
+  /** Present (and non-empty `rows`) only when `errors` is empty. */
+  rows: Record<string, Record<string, unknown>>;
+  /** Any coercion/structural problem, one entry per issue. Non-empty means
+   *  the caller must NOT write — the import is atomic, all-or-nothing. */
+  errors: string[];
+}
+
+/**
+ * Coerce ONE data row (`line`, the raw CSV cells including the leading key)
+ * into its key + typed row object, pushing any problem onto `errors` (never
+ * throwing). Returns `null` when the row has no usable key (empty or the
+ * reserved `"$schema"`) — pulled out of `csvToTable`'s main loop so that loop
+ * only has to handle the duplicate-key check across rows.
+ */
+function coerceRow(
+  line: string[],
+  rowNum: number,
+  rowFields: DataFieldDescriptor[],
+  columns: string[],
+  errors: string[],
+): { key: string; value: Record<string, unknown> } | null {
+  const key = (line[0] ?? '').trim();
+  if (!key) {
+    errors.push(`row ${rowNum}: key cannot be empty.`);
+    return null;
+  }
+  if (key === '$schema') {
+    errors.push(`row ${rowNum}: "$schema" is reserved and cannot be a row key.`);
+    return null;
+  }
+
+  const rowValue: Record<string, unknown> = {};
+  for (const f of rowFields) {
+    // +1: `columns` excludes the leading "key" column that `line[0]` holds.
+    const colIdx = columns.indexOf(f.name);
+    if (colIdx < 0) {
+      // Column missing from the sheet ENTIRELY (distinct from a present but
+      // blank cell, #5) — there is no cell content to preserve, so every
+      // kind (string included) falls to the schema default here.
+      rowValue[f.name] = defaultValueForDescriptor(f);
+      continue;
+    }
+    const raw = line[colIdx + 1] ?? '';
+    const result = coerceCell(raw, f, rowNum);
+    if ('error' in result) {
+      errors.push(result.error);
+      continue;
+    }
+    rowValue[f.name] = result.value;
+  }
+  return { key, value: rowValue };
+}
+
+/**
+ * Parse CSV text into table rows for row-schema `rowFields`. Never throws;
+ * collects every problem into `errors` and returns `rows: {}` alongside them
+ * (callers must check `errors.length` before using `rows` — a non-empty
+ * `errors` means the sheet is not a valid whole-table replacement).
+ */
+export function csvToTable(text: string, rowFields: DataFieldDescriptor[]): CsvImportResult {
+  const errors: string[] = [];
+  const grid = parseCsv(text).filter((r) => !(r.length === 1 && r[0] === ''));
+  if (grid.length === 0) {
+    return { rows: {}, errors: ['CSV is empty — expected a header row starting with "key".'] };
+  }
+
+  const header = grid[0]!;
+  if (header[0] !== 'key') {
+    return { rows: {}, errors: [`First column must be "key" (found "${header[0] ?? ''}").`] };
+  }
+  const columns = header.slice(1);
+  const validNames = new Set(rowFields.map((f) => f.name));
+  for (const col of columns) {
+    if (!validNames.has(col)) {
+      errors.push(
+        `Unknown column "${col}" — valid columns are [${rowFields.map((f) => f.name).join(', ')}].`,
+      );
+    }
+  }
+
+  const rows: Record<string, Record<string, unknown>> = {};
+  for (let r = 1; r < grid.length; r++) {
+    const rowNum = r + 1; // 1-based, header is row 1 (spreadsheet-familiar numbering)
+    const coerced = coerceRow(grid[r]!, rowNum, rowFields, columns, errors);
+    if (!coerced) continue;
+    if (coerced.key in rows) {
+      errors.push(`row ${rowNum}: duplicate key "${coerced.key}".`);
+      continue;
+    }
+    rows[coerced.key] = coerced.value;
+  }
+
+  if (errors.length > 0) return { rows: {}, errors };
+  return { rows, errors: [] };
+}

package/src/components/entity-name-commit.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure decision for the inspector's entity-name field commit (T1.12b): given
+ * the in-progress draft and the last-committed name, returns the trimmed name
+ * to commit, or `null` if nothing should be committed (empty/whitespace-only
+ * draft, or unchanged). Kept import-free (no React/Three/editor-store deps)
+ * so it can be unit-tested without pulling in the HeaderSection module graph.
+ *
+ * Used by `EntityNameField` in
+ * `authoring/first-party-inspector/HeaderSection.tsx`, whose `commit()` handler
+ * (wired to `onBlur`/Enter only — never `onChange`) calls this before pushing
+ * to the store, so the store only sees one call per edit gesture instead of
+ * one per keystroke.
+ */
+export function resolveNameCommit(draft: string, name: string): string | null {
+  const trimmed = draft.trim();
+  if (trimmed && trimmed !== name) return trimmed;
+  return null;
+}

package/src/components/inspector-property-grouping.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure grouping logic behind the generic adapter-driven inspector's
+ * `PropertyDescriptor.group?` rendering (T3.4 slice 2, docs/ADAPTER-
+ * AUTHORING-DESIGN.md §1.E). Extracted out of `Inspector.tsx`'s (formerly
+ * `IngestPanels.tsx`'s `GenericInspector`) inspector shell component (a react
+ * component with no jsdom/testing-library in this repo — `vitest.config.ts`
+ * runs `environment: 'node'`) so
+ * this can be unit-tested directly as data-in/data-out, matching the
+ * repo's existing "test the pure logic headlessly" convention.
+ *
+ * Ungrouped fields keep their original relative order (byte-stable with the
+ * pre-`group` flat-list rendering); named groups are returned in FIRST-SEEN
+ * order, each carrying a slugified, testid-safe `groupId` (lowercase,
+ * non-alphanumeric runs collapsed to a single `-`, no leading/trailing `-`).
+ */
+
+import type { PropertyDescriptor } from '@engine/adapter';
+
+export interface PropertyGroup {
+  name: string;
+  /** Slugified group name — the suffix of the rendered section's
+   *  `data-testid="ingest-group-<groupId>"`. */
+  groupId: string;
+  properties: PropertyDescriptor[];
+}
+
+export interface GroupedProperties {
+  ungrouped: PropertyDescriptor[];
+  groups: PropertyGroup[];
+}
+
+/** Lowercase, non-alphanumeric runs -> single `-`, no leading/trailing `-`. */
+export function slugifyGroupName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function groupProperties(props: readonly PropertyDescriptor[]): GroupedProperties {
+  const ungrouped: PropertyDescriptor[] = [];
+  const order: string[] = [];
+  const byName = new Map<string, PropertyDescriptor[]>();
+
+  for (const p of props) {
+    if (p.group) {
+      if (!byName.has(p.group)) {
+        byName.set(p.group, []);
+        order.push(p.group);
+      }
+      byName.get(p.group)!.push(p);
+    } else {
+      ungrouped.push(p);
+    }
+  }
+
+  return {
+    ungrouped,
+    groups: order.map((name) => ({
+      name,
+      groupId: slugifyGroupName(name),
+      properties: byName.get(name)!,
+    })),
+  };
+}

package/src/components/inspector-widgets/AlignmentGrid.tsx

@@ -0,0 +1,188 @@
+/**
+ * AlignmentGrid — a 3×3 flex `justify-content`×`align-items` picker (spec 27
+ * §5 C1). Ported from `visual-edit/inspector.tsx`'s `AlignmentGrid`
+ * (:304-351). `AnchorPresets` below REUSES the existing `ui-editor/
+ * inspector.tsx` `ANCHOR_PRESETS` table's VALUES (now exported there for
+ * this reuse) as a data-only copy — not a live import — because
+ * `ui-editor/inspector.tsx` pulls in `UIEditStore`/`react-store`/
+ * `node-ops`/the inspector-section-registry (a whole editing-mode runtime
+ * graph this pure, adapter-free widget kit must not drag in, Rule zero's
+ * "talk ONLY to the AuthoringAdapter contract" spirit extended to "don't
+ * import a store-coupled module just for one constant"). Keep this table in
+ * sync with `ui-editor/inspector.tsx`'s `ANCHOR_PRESETS` if either changes —
+ * C2's wiring step is the natural point to collapse them into one shared,
+ * dependency-free `anchor-presets.ts` module both sides import.
+ */
+
+import { type ChangeHandlers, THEME } from './shared';
+
+const ANCHOR_PRESETS: Record<
+  string,
+  { anchor: AnchorRect['anchor']; offset: AnchorRect['offset'] }
+> = {
+  full: {
+    anchor: { left: 0, top: 0, right: 1, bottom: 1 },
+    offset: { left: 0, top: 0, right: 0, bottom: 0 },
+  },
+  top: {
+    anchor: { left: 0, top: 0, right: 1, bottom: 0 },
+    offset: { left: 0, top: 0, right: 0, bottom: 0 },
+  },
+  bottom: {
+    anchor: { left: 0, top: 1, right: 1, bottom: 1 },
+    offset: { left: 0, top: 0, right: 0, bottom: 0 },
+  },
+  left: {
+    anchor: { left: 0, top: 0, right: 0, bottom: 1 },
+    offset: { left: 0, top: 0, right: 0, bottom: 0 },
+  },
+  right: {
+    anchor: { left: 1, top: 0, right: 1, bottom: 1 },
+    offset: { left: 0, top: 0, right: 0, bottom: 0 },
+  },
+  center: {
+    anchor: { left: 0.5, top: 0.5, right: 0.5, bottom: 0.5 },
+    offset: { left: -60, top: -20, right: 60, bottom: 20 },
+  },
+  'top-left': {
+    anchor: { left: 0, top: 0, right: 0, bottom: 0 },
+    offset: { left: 0, top: 0, right: 120, bottom: 40 },
+  },
+  'top-right': {
+    anchor: { left: 1, top: 0, right: 1, bottom: 0 },
+    offset: { left: -120, top: 0, right: 0, bottom: 40 },
+  },
+};
+
+const JUSTIFY = ['flex-start', 'center', 'flex-end'] as const;
+const ALIGN = ['flex-start', 'center', 'flex-end'] as const;
+
+export interface AlignmentValue {
+  justify: (typeof JUSTIFY)[number];
+  align: (typeof ALIGN)[number];
+}
+
+/** One 3×3 dot — split out of `AlignmentGrid`'s double `.map` purely to keep
+ *  each function under biome's cognitive-complexity ceiling; same markup. */
+function AlignmentCell({
+  row,
+  col,
+  justify,
+  align,
+  isActive,
+  disabled,
+  onSelect,
+}: {
+  row: number;
+  col: number;
+  justify: AlignmentValue['justify'];
+  align: AlignmentValue['align'];
+  isActive: boolean;
+  disabled?: boolean | undefined;
+  onSelect: (justify: AlignmentValue['justify'], align: AlignmentValue['align']) => void;
+}): React.ReactElement {
+  return (
+    <div
+      data-testid={`alignment-grid-${row}-${col}`}
+      onClick={() => {
+        if (!disabled) onSelect(justify, align);
+      }}
+      style={{
+        width: 16,
+        height: 16,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        cursor: disabled ? 'not-allowed' : 'pointer',
+        borderRadius: 2,
+        background: isActive ? THEME.accent : 'transparent',
+      }}
+    >
+      <div
+        style={{
+          width: isActive ? 6 : 4,
+          height: isActive ? 6 : 4,
+          borderRadius: '50%',
+          background: isActive ? '#fff' : THEME.textMuted,
+        }}
+      />
+    </div>
+  );
+}
+
+export function AlignmentGrid({
+  value,
+  onChange,
+  disabled,
+}: ChangeHandlers<AlignmentValue>): React.ReactElement {
+  const jIdx = JUSTIFY.indexOf(value.justify);
+  const aIdx = ALIGN.indexOf(value.align);
+
+  return (
+    <div
+      data-testid="alignment-grid"
+      style={{
+        display: 'inline-grid',
+        gridTemplateColumns: 'repeat(3, 16px)',
+        gridTemplateRows: 'repeat(3, 16px)',
+        gap: 1,
+        background: THEME.inputBg,
+        borderRadius: 6,
+        padding: 4,
+        opacity: disabled ? 0.35 : 1,
+      }}
+    >
+      {ALIGN.map((a, row) =>
+        JUSTIFY.map((j, col) => (
+          <AlignmentCell
+            key={`${row}-${col}`}
+            row={row}
+            col={col}
+            justify={j}
+            align={a}
+            isActive={row === aIdx && col === jIdx}
+            disabled={disabled}
+            onSelect={(justify, align) => onChange({ justify, align })}
+          />
+        )),
+      )}
+    </div>
+  );
+}
+
+export interface AnchorRect {
+  anchor: { left: number; top: number; right: number; bottom: number };
+  offset: { left: number; top: number; right: number; bottom: number };
+}
+
+export interface AnchorPresetsProps {
+  onSelect: (name: string, preset: AnchorRect) => void;
+  disabled?: boolean | undefined;
+}
+
+export function AnchorPresets({ onSelect, disabled }: AnchorPresetsProps): React.ReactElement {
+  return (
+    <div data-testid="anchor-presets" style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+      {Object.entries(ANCHOR_PRESETS).map(([name, preset]) => (
+        <button
+          key={name}
+          type="button"
+          data-testid={`anchor-preset-${name}`}
+          disabled={disabled}
+          onClick={() => onSelect(name, preset)}
+          style={{
+            background: 'rgba(255,255,255,0.06)',
+            border: `1px solid ${THEME.border}`,
+            borderRadius: 3,
+            color: THEME.text,
+            fontSize: 10,
+            padding: '3px 6px',
+            cursor: disabled ? 'not-allowed' : 'pointer',
+          }}
+        >
+          {name}
+        </button>
+      ))}
+    </div>
+  );
+}