@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/tab-stop-parse.ts

@@ -0,0 +1,217 @@
+/**
+ * The low-level parsing behind `tabStopsIn`: balanced-bracket and value scanning,
+ * a tag's attribute value, the binding/import RESOLVER (name → its home file and
+ * definition, expanded across hops), and the two per-tag predicates —
+ * `tagDeclaresTab` (is this a tab stop?) and `taiClassesOf` (which `tai-*` classes
+ * does it wear?).
+ */
+
+/**
+ * The text from `start` to the character closing the bracket it opens, quotes
+ * respected so a brace inside a string neither opens nor closes anything.
+ */
+export function balancedFrom(source: string, start: number, open: string, close: string): string {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let index = start; index < source.length; index += 1) {
+    const character = source[index];
+    if (quote !== undefined) {
+      if (character === '\\') {
+        index += 1;
+        continue;
+      }
+      if (character === quote) quote = undefined;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') {
+      quote = character;
+      continue;
+    }
+    if (character === open) depth += 1;
+    else if (character === close) {
+      depth -= 1;
+      if (depth === 0) return source.slice(start, index + 1);
+    }
+  }
+  return source.slice(start);
+}
+
+/**
+ * The RHS of a `const`/`let` assignment beginning at `start`: text up to the
+ * top-level `;`, with brackets and quotes tracked so a `;` inside either does not
+ * end it.
+ */
+const QUOTE_CHARS = '"\'`';
+const OPEN_BRACKETS = '{([';
+const CLOSE_BRACKETS = '})]';
+
+export function readAssignmentValue(source: string, start: number): string {
+  let end = start;
+  let depth = 0;
+  let quote: string | undefined;
+  for (; end < source.length; end += 1) {
+    const character = source[end] ?? '';
+    if (quote !== undefined) {
+      if (character === '\\') end += 1;
+      else if (character === quote) quote = undefined;
+      continue;
+    }
+    if (QUOTE_CHARS.includes(character)) quote = character;
+    else if (OPEN_BRACKETS.includes(character)) depth += 1;
+    else if (CLOSE_BRACKETS.includes(character)) depth -= 1;
+    else if (character === ';' && depth === 0) break;
+  }
+  return source.slice(start, end);
+}
+
+/**
+ * The index of the `>` closing an opening tag whose attribute run starts at
+ * `from`, quotes and brace depth tracked so a `>` inside a `className` expression
+ * (`{x > 0 ? a : b}`) is not mistaken for it.
+ */
+export function scanToTagClose(source: string, from: number): number {
+  let end = from;
+  let depth = 0;
+  let quote: string | undefined;
+  for (; end < source.length; end += 1) {
+    const character = source[end];
+    if (quote !== undefined) {
+      if (character === '\\') end += 1;
+      else if (character === quote) quote = undefined;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') quote = character;
+    else if (character === '{') depth += 1;
+    else if (character === '}') depth -= 1;
+    else if (character === '>' && depth === 0) break;
+  }
+  return end;
+}
+
+/** One opening JSX tag: its element name and everything between that and the `>`. */
+export interface OpeningTag {
+  readonly name: string;
+  readonly attributes: string;
+}
+
+/**
+ * The value written for `attribute`, unquoted or unbraced; `undefined` when the
+ * tag does not write it at all, which is the difference between "no `tabIndex`"
+ * and "`tabIndex={-1}`".
+ */
+export function attributeValue(attributes: string, attribute: string): string | undefined {
+  const written = new RegExp(String.raw`(?<![\w-])${attribute}\s*=`).exec(attributes);
+  if (written === null) return undefined;
+  let index = written.index + written[0].length;
+  while (/\s/.test(attributes[index] ?? '')) index += 1;
+  const opener = attributes[index];
+  if (opener === '"' || opener === "'") {
+    const close = attributes.indexOf(opener, index + 1);
+    return attributes.slice(index + 1, close === -1 ? attributes.length : close);
+  }
+  if (opener === '{') return balancedFrom(attributes, index, '{', '}').slice(1, -1);
+  return '';
+}
+
+/** The elements that are in the tab order with no `tabIndex` of their own. */
+const NATIVELY_FOCUSABLE = new Set(['button', 'a', 'input', 'textarea', 'select', 'summary']);
+
+/** A `tabIndex` that takes the element OUT of the tab order. */
+const NEGATIVE_TAB_INDEX = /^\s*-/;
+
+/** A props object that puts its target in the tab order. */
+const SPREADS_TAB_INDEX = /tabIndex\s*:\s*(?!\s*-)/;
+
+/** Resolves a referenced name to the file it is bound in and its definition text. */
+export interface TabStopResolver {
+  /** Where a name is bound: the file itself, or the file it is imported from. */
+  homeOf(file: string, name: string): string | undefined;
+  /** The definition text of `name` bound in `home`, if any. */
+  definitionOf(home: string, name: string): string | undefined;
+  /**
+   * `text` with the definition of every name it references appended, to `depth`
+   * hops — a class reaches its element through as many as three (the tag names a
+   * helper, the helper names a table, the table holds the literal).
+   */
+  expand(text: string, file: string, depth: number, seen: Set<string>): string;
+}
+
+/** A resolver over pre-scanned per-file binding and import maps. */
+export function createTabStopResolver(
+  bindings: ReadonlyMap<string, Map<string, string>>,
+  imports: ReadonlyMap<string, Map<string, string>>,
+): TabStopResolver {
+  function homeOf(file: string, name: string): string | undefined {
+    if (bindings.get(file)?.has(name) === true) return file;
+    return imports.get(file)?.get(name);
+  }
+
+  function definitionOf(home: string, name: string): string | undefined {
+    return bindings.get(home)?.get(name);
+  }
+
+  function expand(text: string, file: string, depth: number, seen: Set<string>): string {
+    if (depth === 0) return text;
+    let out = text;
+    for (const match of text.matchAll(/(?<![\w.$])([A-Za-z_$][\w$]*)/g)) {
+      const name = match[1] ?? '';
+      const home = homeOf(file, name);
+      if (home === undefined) continue;
+      const key = `${home}#${name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const definition = definitionOf(home, name);
+      if (definition !== undefined) out += `\n${expand(definition, home, depth - 1, seen)}`;
+    }
+    return out;
+  }
+
+  return { homeOf, definitionOf, expand };
+}
+
+/** Whether a spread props object on the tag declares a non-negative `tabIndex`. */
+function spreadDeclaresTab(tag: OpeningTag, file: string, resolver: TabStopResolver): boolean {
+  for (const spread of tag.attributes.matchAll(/\{\s*\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+    const home = resolver.homeOf(file, spread[1] ?? '');
+    if (home === undefined) continue;
+    const definition = resolver.definitionOf(home, spread[1] ?? '');
+    if (
+      definition !== undefined &&
+      SPREADS_TAB_INDEX.test(resolver.expand(definition, home, 2, new Set()))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether the tag is a keyboard tab stop: a natively focusable element, an element
+ * with a non-negative `tabIndex`, or one spreading a props object that declares one.
+ */
+export function tagDeclaresTab(tag: OpeningTag, file: string, resolver: TabStopResolver): boolean {
+  const native =
+    NATIVELY_FOCUSABLE.has(tag.name) &&
+    (tag.name !== 'a' || /(?<![\w-])href\s*=/.test(tag.attributes));
+  if (native) return true;
+  const written = attributeValue(tag.attributes, 'tabIndex');
+  if (written !== undefined && !NEGATIVE_TAB_INDEX.test(written)) return true;
+  return spreadDeclaresTab(tag, file, resolver);
+}
+
+/** The `tai-*` classes the tag wears, expanded through its bindings to `depth` 3. */
+export function taiClassesOf(tag: OpeningTag, file: string, resolver: TabStopResolver): string[] {
+  const className = attributeValue(tag.attributes, 'className');
+  if (className === undefined) return [];
+  return [
+    ...new Set(
+      [
+        ...resolver
+          .expand(className, file, 3, new Set())
+          .matchAll(/(?<![\w-])(tai-[a-z][\w-]*)(?![\w])/g),
+      ]
+        .map((match) => `.${match[1] ?? ''}`)
+        .filter((name) => !name.endsWith('-')),
+    ),
+  ];
+}

package/src/components/table.tsx

@@ -13,7 +13,7 @@
  * so a caller that has to measure or scroll a cell is not forced back to a raw
  * `<td>` and out of the system.
  */
-import type { HTMLAttributes, Ref, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from 'react';
+import type { HTMLAttributes, ReactNode, Ref, TdHTMLAttributes, ThHTMLAttributes } from 'react';
 
 export interface TableProps extends HTMLAttributes<HTMLTableElement> {
   readonly children?: ReactNode;

package/src/components/tags.tsx

@@ -11,11 +11,11 @@
  * version-history panel's per-version tag editor) needs the same control; a single
  * canonical copy keeps the affordance identical everywhere.
  */
-import { useState, type CSSProperties, type ReactNode } from 'react';
+import { type CSSProperties, type ReactNode, useState } from 'react';
 
 import { CloseIcon } from './icons';
-import { Button } from './primitives';
 import { TextInput } from './inputs';
+import { Button } from './primitives';
 
 /** A tag and its remove control read as one unit, tighter than the row default. */
 const tagGroupStyle: CSSProperties = { gap: 'var(--tai-space-1)' };

package/src/components/templated-text-field.tsx

@@ -24,16 +24,19 @@
  * its kwargs, never converted or dropped. See `storageAbsent` /
  * `storagePresenceLoading`.
  */
-import { useState, type ReactNode } from 'react';
-
 import type { TemplatedText } from '@tai42/api-client';
+import { type ReactNode, useState } from 'react';
 
-import { Button, ErrorState, Skeleton } from './primitives';
 import { Field } from './field';
-import { RadioGroup } from './radio-group';
-import { Select } from './select';
-import { Textarea, TextInput } from './inputs';
-import { CloseIcon } from './icons';
+import {
+  initialMode,
+  type KwargRow,
+  type Mode,
+  objectToRows,
+  templatedValueFrom,
+} from './templated-text-kwargs';
+import { KwargsEditor, ReadOnlyKwargs } from './templated-text-kwargs-editor';
+import { TemplatedTextSource } from './templated-text-source';
 
 /** One stored template the id picker offers. */
 export interface TemplatedTextTemplateOption {
@@ -111,170 +114,6 @@ export function templatedTextSummary(value: TemplatedText | null): string {
   return value.content ?? '';
 }
 
-type Mode = 'inline' | 'stored';
-
-interface KwargRow {
-  readonly key: string;
-  readonly value: string;
-  /**
-   * The stored value this row was seeded from, kept so an UNTOUCHED row re-emits it
-   * BYTE-FOR-BYTE: the row form cannot tell a stored string `"7"` from the number `7`,
-   * so re-parsing an untouched row would silently coerce the stored type. `undefined`
-   * for a row the author added.
-   */
-  readonly original?: unknown;
-}
-
-/** The row's canonical string form, matched against `value` to detect an untouched row. */
-function stringifyRowValue(raw: unknown): string {
-  return typeof raw === 'string' ? raw : JSON.stringify(raw);
-}
-
-/** Parse a cell as JSON when it can be (numbers/bools/objects), else keep the string. */
-function parseCellValue(raw: string): unknown {
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) return '';
-  try {
-    return JSON.parse(trimmed);
-  } catch {
-    return raw;
-  }
-}
-
-/** Collapse the kwargs rows into an object, dropping rows with a blank key. */
-function rowsToObject(rows: readonly KwargRow[]): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const row of rows) {
-    const key = row.key.trim();
-    if (key.length === 0) continue;
-    // An untouched seeded row re-emits its stored value verbatim (no JSON-type coerce);
-    // an edited or added row is parsed from the cell text.
-    out[key] =
-      row.original !== undefined && stringifyRowValue(row.original) === row.value
-        ? row.original
-        : parseCellValue(row.value);
-  }
-  return out;
-}
-
-/** Seed rows from a stored kwargs object (stringifying non-string values). */
-function objectToRows(kwargs: Record<string, unknown> | undefined): KwargRow[] {
-  if (kwargs === undefined) return [];
-  return Object.entries(kwargs).map(([key, raw]) => ({
-    key,
-    value: stringifyRowValue(raw),
-    original: raw,
-  }));
-}
-
-/** The add/remove kwargs editor, revealed on demand and open when kwargs already exist. */
-function KwargsEditor({
-  label,
-  rows,
-  disabled,
-  onChange,
-}: {
-  readonly label: string;
-  readonly rows: readonly KwargRow[];
-  readonly disabled: boolean;
-  readonly onChange: (rows: KwargRow[]) => void;
-}): ReactNode {
-  const [open, setOpen] = useState(rows.length > 0);
-  const groupLabel = `${label} render parameters`;
-
-  if (!open) {
-    // Wrapped so the ghost button keeps its content width and stays left-aligned
-    // in the field's column, marking it as this field's own disclosure rather than
-    // a full-width control floating between two fields.
-    return (
-      <div>
-        <Button
-          type="button"
-          variant="ghost"
-          disabled={disabled}
-          onClick={() => {
-            setOpen(true);
-            onChange([...rows, { key: '', value: '' }]);
-          }}
-        >
-          Add render parameters
-        </Button>
-      </div>
-    );
-  }
-
-  return (
-    <div
-      role="group"
-      aria-label={groupLabel}
-      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}
-    >
-      <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
-        Render parameters
-      </span>
-      {rows.map((row, index) => (
-        <div
-          key={index}
-          style={{ display: 'flex', gap: 'var(--tai-space-2)', alignItems: 'center' }}
-        >
-          <TextInput
-            aria-label={`${groupLabel} key ${String(index + 1)}`}
-            placeholder="name"
-            value={row.key}
-            autoComplete="off"
-            disabled={disabled}
-            onChange={(event) => {
-              const next = [...rows];
-              next[index] = { ...row, key: event.target.value };
-              onChange(next);
-            }}
-          />
-          <TextInput
-            aria-label={`${groupLabel} value ${String(index + 1)}`}
-            placeholder="value"
-            value={row.value}
-            autoComplete="off"
-            disabled={disabled}
-            onChange={(event) => {
-              const next = [...rows];
-              next[index] = { ...row, value: event.target.value };
-              onChange(next);
-            }}
-          />
-          <Button
-            type="button"
-            variant="ghost"
-            aria-label={`Remove ${groupLabel} ${String(index + 1)}`}
-            disabled={disabled}
-            onClick={() => {
-              onChange(rows.filter((_, position) => position !== index));
-            }}
-          >
-            <CloseIcon aria-hidden="true" />
-          </Button>
-        </div>
-      ))}
-      <div>
-        <Button
-          type="button"
-          variant="ghost"
-          disabled={disabled}
-          onClick={() => {
-            onChange([...rows, { key: '', value: '' }]);
-          }}
-        >
-          Add parameter
-        </Button>
-      </div>
-    </div>
-  );
-}
-
-/** The initial mode: stored when the seed carries an `id`, inline otherwise. */
-function initialMode(value: TemplatedText | null): Mode {
-  return value?.id !== undefined ? 'stored' : 'inline';
-}
-
 export function TemplatedTextField({
   label,
   value,
@@ -304,22 +143,7 @@ export function TemplatedTextField({
     nextStored: string,
     nextKwargs: readonly KwargRow[],
   ): void => {
-    const kwargs = rowsToObject(nextKwargs);
-    const kw = Object.keys(kwargs).length > 0 ? { kwargs } : {};
-    if (nextMode === 'stored') {
-      const id = nextStored.trim();
-      if (id === '') {
-        onChange(required ? { id: '', ...kw } : null);
-        return;
-      }
-      onChange({ id, ...kw });
-      return;
-    }
-    if (nextInline.trim() === '') {
-      onChange(required ? { content: '', ...kw } : null);
-      return;
-    }
-    onChange({ content: nextInline, ...kw });
+    onChange(templatedValueFrom(nextMode, nextInline, nextStored, nextKwargs, required));
   };
 
   const changeMode = (next: Mode): void => {
@@ -342,125 +166,33 @@ export function TemplatedTextField({
     emit(mode, inlineDraft, storedDraft, next);
   };
 
-  const templateOptions = templates.map((template) => ({
-    value: template.id,
-    label: template.label ?? template.id,
-  }));
-  // A stored id the catalog does not offer cannot be picked from the list; it is
-  // shown as an unresolved note rather than silently blanked.
-  const unresolvedId =
-    mode === 'stored' &&
-    storedDraft.trim() !== '' &&
-    !templatesLoading &&
-    templatesError === undefined &&
-    !templates.some((template) => template.id === storedDraft.trim())
-      ? storedDraft.trim()
-      : undefined;
-
-  // The inline editor, shared by the present-storage inline mode and the
-  // absent-storage inline-only rendering: the caller's rich editor when supplied,
-  // else a plain textarea.
-  const inlineEditor =
-    renderInline !== undefined ? (
-      renderInline({ label, value: inlineDraft, onChange: changeInline, error, hideLabel: true })
-    ) : (
-      <Field label={label} hideLabel error={error}>
-        <Textarea
-          value={inlineDraft}
-          placeholder={placeholder}
-          disabled={disabled}
-          onChange={(event) => {
-            changeInline(event.target.value);
-          }}
-        />
-      </Field>
-    );
-
-  // A stored `id` already authored on the value: with storage absent it is shown
-  // read-only rather than resolved, browsed, converted, or dropped.
-  const authoredStoredId = value?.id;
-  const showsReadOnlyStored = storageAbsent && authoredStoredId !== undefined;
-
-  // The source region. While presence is unknown a placeholder stands in, so the
-  // toggle is never shown and then removed. With storage absent the stored source
-  // cannot work and is not offered: an inline or empty value edits inline; a value
-  // carrying an `id` is shown read-only with an unavailability note. With storage
-  // present the full inline/stored toggle and picker render.
-  let source: ReactNode;
-  if (storagePresenceLoading) {
-    source = <Skeleton height={36} />;
-  } else if (storageAbsent) {
-    source = showsReadOnlyStored ? (
-      <>
-        {/* A labeled read-only reference, NOT an editable field: no input box, a
-            "Stored template" caption, and the id in monospace — so it reads as a stored
-            reference the way the state-template screen shows one, never as literal text a
-            reader could mistake for the condition itself. A long id wraps rather than
-            overflowing its row. */}
-        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}>
-          <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
-            Stored template
-          </span>
-          <code style={{ fontFamily: 'var(--tai-font-mono)', wordBreak: 'break-all' }}>
-            {authoredStoredId}
-          </code>
-        </div>
-        <p
-          style={{
-            margin: 0,
-            fontSize: 'var(--tai-text-sm)',
-            color: 'var(--tai-color-text-muted)',
-          }}
-        >
-          Stored templates are unavailable — this deployment has no storage backend.
-        </p>
-      </>
-    ) : (
-      inlineEditor
-    );
-  } else {
-    source = (
-      <>
-        <RadioGroup
-          aria-label={`${label} source`}
-          variant="segmented"
-          value={mode}
-          disabled={disabled}
-          options={[
-            { value: 'inline', label: 'Inline text' },
-            { value: 'stored', label: 'Stored template' },
-          ]}
-          onValueChange={(next) => {
-            changeMode(next as Mode);
-          }}
-        />
-
-        {mode === 'inline' ? (
-          inlineEditor
-        ) : templatesError !== undefined ? (
-          <ErrorState message={templatesError} onRetry={onTemplatesRetry} />
-        ) : templatesLoading ? (
-          <Skeleton height={36} />
-        ) : (
-          <Field label={label} hideLabel error={error}>
-            <Select
-              placeholder={templates.length === 0 ? 'No templates available' : 'Select a template'}
-              value={storedDraft}
-              disabled={disabled || templates.length === 0}
-              options={templateOptions}
-              onValueChange={changeStored}
-            />
-          </Field>
-        )}
-
-        {unresolvedId !== undefined ? (
-          <p role="alert" style={{ margin: 0, color: 'var(--tai-color-err-text)' }}>
-            {resolveError ?? `The stored template "${unresolvedId}" is not available.`}
-          </p>
-        ) : null}
-      </>
-    );
-  }
+  // A stored `id` already authored on the value is shown read-only when storage is
+  // absent — never resolved, browsed, converted, or dropped.
+  const showsReadOnlyStored = storageAbsent && value?.id !== undefined;
+
+  const source = (
+    <TemplatedTextSource
+      label={label}
+      mode={mode}
+      inlineDraft={inlineDraft}
+      storedDraft={storedDraft}
+      error={error}
+      disabled={disabled}
+      placeholder={placeholder}
+      renderInline={renderInline}
+      templates={templates}
+      templatesLoading={templatesLoading}
+      templatesError={templatesError}
+      onTemplatesRetry={onTemplatesRetry}
+      resolveError={resolveError}
+      storageAbsent={storageAbsent}
+      storagePresenceLoading={storagePresenceLoading}
+      authoredStoredId={value?.id}
+      onModeChange={changeMode}
+      onInlineChange={changeInline}
+      onStoredChange={changeStored}
+    />
+  );
 
   // ONE coherent group per field: the label + description form the group header, and
   // the source region and the render-parameters disclosure sit under it — so the
@@ -470,36 +202,11 @@ export function TemplatedTextField({
   // visually-hidden `<label for>` (see `hideLabel`). The container-name redundancy
   // `Field` accepts by design (a redundant container is audible, an unnamed group is
   // silent).
-  //
-  // A read-only stored value shows its render parameters as read-only text — the values
-  // in normal weight, NOT the muted disabled inputs a reader could mistake for empty
-  // placeholders — matching the read-only treatment of the id above; every editable
-  // rendering keeps the full add/remove editor.
   return (
     <Field label={label} description={description} group>
       {source}
       {showsReadOnlyStored ? (
-        kwargsRows.length > 0 ? (
-          <div
-            role="group"
-            aria-label={`${label} render parameters`}
-            style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}
-          >
-            <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
-              Render parameters
-            </span>
-            {kwargsRows.map((row) => (
-              <div
-                key={row.key}
-                style={{ fontFamily: 'var(--tai-font-mono)', wordBreak: 'break-all' }}
-              >
-                <code>{row.key}</code>
-                <span style={{ color: 'var(--tai-color-text-muted)' }}>: </span>
-                <code>{row.value}</code>
-              </div>
-            ))}
-          </div>
-        ) : null
+        <ReadOnlyKwargs label={label} rows={kwargsRows} />
       ) : (
         <KwargsEditor label={label} rows={kwargsRows} disabled={disabled} onChange={changeKwargs} />
       )}