@tai42/studio-sdk 0.2.0

package/src/components/json-diff.tsx

@@ -0,0 +1,192 @@
+/**
+ * `JsonDiff` — a GENERIC, kind-agnostic structural diff of two JSON values,
+ * hand-rolled (no diff library). It recursively walks OBJECT keys and emits one row
+ * per leaf difference: a key present only on one side is `added`/`removed`, a key
+ * whose value differs is `changed`.
+ *
+ * ARRAYS ARE LEAVES: an unequal array (by deep compare) emits exactly ONE `changed`
+ * row at the array's path carrying both whole array values — there are no per-index
+ * rows and no LCS alignment. A container object whose descendants differ emits rows
+ * only for the differing leaves, never for the container itself.
+ *
+ * Rendered as a table: the dotted `path` (e.g. `fixed_kwargs.city`) as code, the
+ * kind as a Badge (removed → danger, added → success, changed → neutral), and the
+ * before/after values as a `JsonTree` for objects/arrays or escaped text for
+ * scalars. Every value renders as React TEXT, so payload markup is escaped and this
+ * is never an HTML sink.
+ *
+ * Each row also carries its `tai-diff-*` tint, but the tint only REINFORCES the
+ * kind — the Badge spells the kind out in words, so a row is never identified by
+ * color alone.
+ */
+import { type ReactNode } from 'react';
+
+import { Badge } from './badge';
+import { JsonTree } from './json-tree';
+import { Table, TBody, TD, TH, THead, TR } from './table';
+
+/** One leaf difference between the two JSON values. */
+export interface JsonDiffRow {
+  /** The dotted path to the differing key, e.g. `fixed_kwargs.city` (`''` = root). */
+  readonly path: string;
+  readonly kind: 'added' | 'removed' | 'changed';
+  /** The value on the LEFT side — set for `removed` and `changed` rows. */
+  readonly before?: unknown;
+  /** The value on the RIGHT side — set for `added` and `changed` rows. */
+  readonly after?: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Structural deep-equality over JSON values (arrays compared position-wise). */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+      if (!deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+function childPath(path: string, key: string): string {
+  return path === '' ? key : `${path}.${key}`;
+}
+
+/**
+ * Recursively collect the leaf differences. Only when BOTH sides are plain objects
+ * does the walk descend by key; anything else (arrays, scalars, a type mismatch) is
+ * compared as a single leaf.
+ */
+function collect(path: string, before: unknown, after: unknown, rows: JsonDiffRow[]): void {
+  if (isRecord(before) && isRecord(after)) {
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort((a, b) =>
+      a.localeCompare(b),
+    );
+    for (const key of keys) {
+      const next = childPath(path, key);
+      const inBefore = key in before;
+      const inAfter = key in after;
+      if (inBefore && !inAfter) {
+        rows.push({ path: next, kind: 'removed', before: before[key] });
+      } else if (!inBefore && inAfter) {
+        rows.push({ path: next, kind: 'added', after: after[key] });
+      } else {
+        collect(next, before[key], after[key], rows);
+      }
+    }
+    return;
+  }
+  if (!deepEqual(before, after)) {
+    rows.push({ path, kind: 'changed', before, after });
+  }
+}
+
+/** The pure structural diff — every leaf difference between `before` and `after`. */
+export function diffJson(before: unknown, after: unknown): JsonDiffRow[] {
+  const rows: JsonDiffRow[] = [];
+  collect('', before, after, rows);
+  return rows;
+}
+
+const KIND_VARIANT = {
+  added: 'success',
+  removed: 'danger',
+  changed: 'neutral',
+} as const;
+
+/** The row tint for each kind — a reinforcement of the Badge, never the sole cue. */
+const KIND_ROW_CLASS = {
+  added: 'tai-diff-added',
+  removed: 'tai-diff-removed',
+  changed: 'tai-diff-changed',
+} as const;
+
+/**
+ * Render one side's value: a `JsonTree` for objects/arrays, escaped text for
+ * scalars. The tree is a scroll region once it overflows, so it is named from
+ * the row's path and its side — a table of rows all announcing "JSON" tells a
+ * reader which pane they are in for none of them.
+ */
+function DiffValue({
+  value,
+  label,
+}: {
+  readonly value: unknown;
+  readonly label: string;
+}): ReactNode {
+  if (Array.isArray(value) || isRecord(value)) {
+    return <JsonTree data={value} defaultExpanded={false} label={label} />;
+  }
+  return <code className="tai-code">{JSON.stringify(value)}</code>;
+}
+
+/** The row's path as it reads on screen; the root diff has no path of its own. */
+function pathLabel(path: string): string {
+  return path === '' ? '(root)' : path;
+}
+
+const emptyCell = <span className="tai-muted">—</span>;
+
+export interface JsonDiffProps {
+  readonly before: unknown;
+  readonly after: unknown;
+}
+
+export function JsonDiff({ before, after }: JsonDiffProps): ReactNode {
+  const rows = diffJson(before, after);
+
+  if (rows.length === 0) {
+    return <p className="tai-muted">No differences between the two values.</p>;
+  }
+
+  return (
+    <Table>
+      <THead>
+        <TR>
+          <TH>Path</TH>
+          <TH>Change</TH>
+          <TH>Before</TH>
+          <TH>After</TH>
+        </TR>
+      </THead>
+      <TBody>
+        {rows.map((row, index) => (
+          <TR
+            key={`${row.kind}-${row.path}-${String(index)}`}
+            className={KIND_ROW_CLASS[row.kind]}
+            data-testid={`diff-row-${row.path}`}
+          >
+            <TD className="tai-table-id" style={{ wordBreak: 'break-all' }}>
+              {pathLabel(row.path)}
+            </TD>
+            <TD>
+              <Badge variant={KIND_VARIANT[row.kind]}>{row.kind}</Badge>
+            </TD>
+            <TD>
+              {row.kind === 'added' ? (
+                emptyCell
+              ) : (
+                <DiffValue value={row.before} label={`${pathLabel(row.path)} before`} />
+              )}
+            </TD>
+            <TD>
+              {row.kind === 'removed' ? (
+                emptyCell
+              ) : (
+                <DiffValue value={row.after} label={`${pathLabel(row.path)} after`} />
+              )}
+            </TD>
+          </TR>
+        ))}
+      </TBody>
+    </Table>
+  );
+}

package/src/components/json-tree.tsx

@@ -0,0 +1,129 @@
+/**
+ * `JsonTree` — a collapsible viewer for arbitrary JSON on the design system's
+ * terminal ground (`tai-code-block`, which also supplies the mono face, the code
+ * size and the line rhythm every row inherits). Objects and arrays are native
+ * `<details>`/`<summary>` disclosures (keyboard-accessible, no custom ARIA
+ * needed); primitives render inline, tinted by the `tai-syntax-*` class for their
+ * type so a value's kind is readable at a glance. All values render as React TEXT
+ * children, so a payload containing markup (e.g. `<script>`) is escaped by React
+ * and never interpreted — this component is never an HTML sink.
+ *
+ * The pane IS the scrolling box, so it carries the region attributes itself
+ * rather than sitting inside a `ScrollRegion` wrapper that would add a second
+ * scroller: a deeply indented value makes it a named keyboard target, a shallow
+ * one leaves it an ordinary block.
+ */
+import type { CSSProperties, ReactElement } from 'react';
+
+import { useOverflowRegion } from './scroll-region';
+
+export interface JsonTreeProps {
+  readonly data: unknown;
+  readonly defaultExpanded?: boolean;
+  /** The region's accessible name, applied only while the pane actually scrolls. */
+  readonly label?: string;
+}
+
+/** The region's name when the caller supplies none. */
+const DEFAULT_LABEL = 'JSON';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function primitiveText(value: unknown): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'undefined':
+      return 'undefined';
+    case 'string':
+      return `"${value}"`;
+    case 'number':
+    case 'bigint':
+    case 'boolean':
+      return String(value);
+    case 'symbol':
+      return value.toString();
+    case 'function':
+      return '[Function]';
+    default:
+      return '[object]';
+  }
+}
+
+/**
+ * One nesting level's indent: the child block insets and draws its own guide
+ * rail. The depth is expressed by the DOM nesting, so each level repeats this
+ * single step rather than computing an absolute offset.
+ */
+const childrenStyle: CSSProperties = {
+  paddingLeft: 'var(--tai-space-4)',
+  marginLeft: 'var(--tai-space-1)',
+  borderLeft: '1px solid var(--tai-color-decor)',
+};
+
+/** A `<summary>` is a click target; browsers do not style it as one by default. */
+const summaryStyle: CSSProperties = { cursor: 'pointer' };
+
+interface NodeProps {
+  readonly name?: string;
+  readonly value: unknown;
+  readonly defaultExpanded: boolean;
+}
+
+/** The syntax class for a primitive's type; anything outside JSON reads as muted. */
+function primitiveClass(value: unknown): string {
+  if (typeof value === 'string') return 'tai-syntax-string';
+  if (typeof value === 'number' || typeof value === 'bigint') return 'tai-syntax-number';
+  if (typeof value === 'boolean') return 'tai-syntax-bool';
+  if (value === null || value === undefined) return 'tai-syntax-null';
+  return 'tai-muted';
+}
+
+function JsonNode({ name, value, defaultExpanded }: NodeProps): ReactElement {
+  if (Array.isArray(value) || isRecord(value)) {
+    const entries: [string, unknown][] = Array.isArray(value)
+      ? value.map((item, index) => [String(index), item])
+      : Object.entries(value);
+    const summary = Array.isArray(value)
+      ? `Array(${String(value.length)})`
+      : `Object(${String(entries.length)})`;
+    return (
+      <details open={defaultExpanded}>
+        <summary style={summaryStyle}>
+          {name !== undefined ? <span className="tai-syntax-key">{name}: </span> : null}
+          <span className="tai-muted">{summary}</span>
+        </summary>
+        <div style={childrenStyle}>
+          {entries.map(([childName, childValue]) => (
+            <JsonNode
+              key={childName}
+              name={childName}
+              value={childValue}
+              defaultExpanded={defaultExpanded}
+            />
+          ))}
+        </div>
+      </details>
+    );
+  }
+
+  return (
+    <div>
+      {name !== undefined ? <span className="tai-syntax-key">{name}: </span> : null}
+      <span className={primitiveClass(value)}>{primitiveText(value)}</span>
+    </div>
+  );
+}
+
+export function JsonTree({ data, defaultExpanded = true, label }: JsonTreeProps) {
+  // No consumer ref: the measurement's own callback ref is the only thing that
+  // needs the pane, and this component publishes no `ref` prop.
+  const region = useOverflowRegion(undefined, label ?? DEFAULT_LABEL);
+
+  return (
+    <div className="tai-code-block" {...region}>
+      <JsonNode value={data} defaultExpanded={defaultExpanded} />
+    </div>
+  );
+}

package/src/components/modal-focus.ts

@@ -0,0 +1,150 @@
+/**
+ * Focus return for a modal that renders no Radix `Trigger`.
+ *
+ * Radix composes its own close handler AFTER the consumer's — `composeEventHandlers`
+ * runs the consumer's `onCloseAutoFocus` first and skips Radix's only when that
+ * handler called `preventDefault`. Radix's handler is
+ * `event.preventDefault(); triggerRef.current?.focus()`: it returns focus to the
+ * Trigger and cancels the focus scope's restore in the same breath. A modal
+ * driven purely by `open`/`onOpenChange` — every confirm mounted for the
+ * duration of one action — has no Trigger for that ref to point at, so if that
+ * handler is allowed to run the cancel lands, the focus does not, and the reader
+ * is left on `<body>` with their place in the page gone (WCAG 2.4.3).
+ *
+ * So with no Trigger this stands in for one and never yields the decision back:
+ * it prevents default unconditionally — Radix's restore is a guaranteed no-op
+ * here, and a `<body>` if allowed to run — and then lands the focus itself, on
+ * the first of these that will take it:
+ *
+ *   1. the element focus left on the way in, when it can still hold focus;
+ *   2. the nearest of that element's ancestors still in the document, borrowing
+ *      it a `tabindex="-1"` if it has none.
+ *
+ * The second case is the common one, not the exotic one: the action a confirm
+ * confirms is usually what removes, disables or hides the control that opened
+ * it. The list or table the vanished row sat in is still on screen and is where
+ * the reader was, so that is where they are put back.
+ *
+ * Those ancestors are recorded on the way IN because they cannot be recovered on
+ * the way out: detaching a node clears its own `parentElement`, so walking up
+ * from a removed row's button dead-ends inside the removed subtree instead of
+ * reaching the list that is still there. While the opener is still attached its
+ * live chain is used instead, so an opener that moved is followed rather than
+ * remembered wrongly.
+ *
+ * A borrowed `tabindex` is handed back on the element's `blur`, so the DOM keeps
+ * the attribute only while that element actually holds focus — and an element
+ * that is itself removed first takes the listener with it. Removing it any
+ * earlier would strip the attribute out from under the focus it exists to hold.
+ *
+ * When a Trigger IS rendered both handlers stand down and prevent nothing, so
+ * Radix's own restore runs untouched — there is never a second mechanism
+ * competing with the primitive.
+ */
+import { useRef } from 'react';
+
+export interface ModalFocusReturnHandlers {
+  /** Runs before Radix moves focus into the panel, while the opener still holds it. */
+  readonly onOpenAutoFocus: (event: Event) => void;
+  /** Runs as the panel unmounts, before the focus scope would restore. */
+  readonly onCloseAutoFocus: (event: Event) => void;
+}
+
+/**
+ * `element`'s ancestors, nearest first, stopping short of `<body>` — landing on
+ * `<body>` is the failure this module exists to prevent, and it is already where
+ * focus falls when nothing else will take it.
+ */
+function ancestorChain(element: HTMLElement): HTMLElement[] {
+  const chain: HTMLElement[] = [];
+  const { body } = element.ownerDocument;
+  for (
+    let node = element.parentElement;
+    node !== null && node !== body;
+    node = node.parentElement
+  ) {
+    chain.push(node);
+  }
+  return chain;
+}
+
+/**
+ * Focuses a container that was never meant to be focusable, lending it a
+ * `tabindex="-1"` if it has none and taking that back when it loses focus.
+ *
+ * @returns whether the focus actually landed.
+ */
+function focusAsFallback(element: HTMLElement): boolean {
+  const borrowed = !element.hasAttribute('tabindex');
+  if (borrowed) element.setAttribute('tabindex', '-1');
+  element.focus();
+  if (element.ownerDocument.activeElement !== element) {
+    if (borrowed) element.removeAttribute('tabindex');
+    return false;
+  }
+  if (borrowed) {
+    element.addEventListener(
+      'blur',
+      () => {
+        element.removeAttribute('tabindex');
+      },
+      { once: true },
+    );
+  }
+  return true;
+}
+
+/**
+ * The `onOpenAutoFocus` / `onCloseAutoFocus` pair to spread onto a Radix
+ * `Dialog.Content`.
+ *
+ * @param hasTrigger - whether a Radix `Trigger` is rendered. When it is, both
+ *   handlers stand down and Radix's own focus return applies.
+ */
+export function useModalFocusReturn(hasTrigger: boolean): ModalFocusReturnHandlers {
+  const openerRef = useRef<HTMLElement | null>(null);
+  const openedUnderRef = useRef<HTMLElement[]>([]);
+
+  return {
+    onOpenAutoFocus: (): void => {
+      // Recording is only ever read by the close handler, which stands down with
+      // a Trigger present. Standing down here too keeps the pair symmetric and
+      // stops the hook holding the opener and its whole ancestor chain alive for
+      // a modal that will never consult them.
+      if (hasTrigger) return;
+      // The focus scope dispatches this BEFORE it focuses the panel, so the
+      // active element is still whatever the reader activated to open the modal,
+      // and its ancestors are still attached to record.
+      const active = document.activeElement;
+      const opener = active instanceof HTMLElement ? active : null;
+      openerRef.current = opener;
+      openedUnderRef.current = opener === null ? [] : ancestorChain(opener);
+    },
+    onCloseAutoFocus: (event: Event): void => {
+      if (hasTrigger) return;
+      const opener = openerRef.current;
+      const openedUnder = openedUnderRef.current;
+      openerRef.current = null;
+      openedUnderRef.current = [];
+
+      // Radix's handler runs next unless this one prevents default. Its
+      // `triggerRef` is null by definition here, and it cancels the scope's
+      // restore before finding that out, so letting it run is a guaranteed
+      // `<body>`. Take the decision away from it in every case, including the
+      // one where there is nothing to return focus to.
+      event.preventDefault();
+      if (opener === null) return;
+
+      opener.focus();
+      if (opener.ownerDocument.activeElement === opener) return;
+
+      // The opener would not take focus — it was removed, disabled or hidden by
+      // the action this modal confirmed. Fall back to the nearest ancestor that
+      // is still in the document, so the reader keeps their place in the page.
+      const chain = opener.isConnected ? ancestorChain(opener) : openedUnder;
+      for (const ancestor of chain) {
+        if (ancestor.isConnected && focusAsFallback(ancestor)) return;
+      }
+    },
+  };
+}

package/src/components/page-header.tsx

@@ -0,0 +1,107 @@
+/**
+ * `PageHeader`, `Page`, `Stack` — the screen scaffolding every feature was
+ * hand-rolling as a flex column plus an ad-hoc heading block.
+ *
+ * `PageHeader` owns a DOM contract `page-header.test.tsx` asserts: exactly one
+ * `<h1>` whose accessible name is the title VERBATIM. The nav-section eyebrow a
+ * screen shows above its title is therefore a SIBLING of the `<h1>`, never a
+ * child — nesting it would fold it into the computed name and break every
+ * heading assertion. The `<h1>` is also permanently focusable
+ * (`tabIndex={-1}`), which is what makes it addressable as a focus target
+ * through {@link PageHeaderProps.titleRef} or `id`.
+ */
+import type { CSSProperties, ReactElement, ReactNode, Ref } from 'react';
+
+/** The wrapper props both layout primitives share, ref included. */
+interface LayoutElementProps {
+  readonly className?: string;
+  readonly style?: CSSProperties;
+  /** A consumer ref for the wrapper element itself. */
+  readonly ref?: Ref<HTMLDivElement>;
+}
+
+export interface PageHeaderProps {
+  /** The screen's title. It is the `<h1>`'s accessible name, VERBATIM. */
+  readonly title: string;
+  /** The screen's existing nav-section label, rendered ABOVE the h1 — never inside it. */
+  readonly eyebrow?: string;
+  readonly description?: string;
+  readonly actions?: ReactNode;
+  /**
+   * A consumer ref for the `<h1>`. Published so a caller that wants to move
+   * focus to the new screen's title — after a route change, say — has the
+   * element without querying for it; the heading is focusable for that reason.
+   */
+  readonly titleRef?: Ref<HTMLHeadingElement>;
+  /**
+   * An id for the `<h1>`, not for the `<header>` root. The heading is the element
+   * a caller has a reason to address — an `aria-labelledby` pointing at it names
+   * the region from the screen's own title — and it is the other way to reach it
+   * as a focus target.
+   */
+  readonly id?: string;
+}
+
+export function PageHeader({
+  title,
+  eyebrow,
+  description,
+  actions,
+  titleRef,
+  id,
+}: PageHeaderProps): ReactElement {
+  return (
+    <header className="tai-page-header">
+      <div>
+        {eyebrow === undefined ? null : <div className="tai-label">{eyebrow}</div>}
+        <h1 className="tai-page-title" tabIndex={-1} ref={titleRef} id={id}>
+          {title}
+        </h1>
+        {description === undefined ? null : <p className="tai-page-description">{description}</p>}
+      </div>
+      {actions === undefined ? null : <div className="tai-page-actions">{actions}</div>}
+    </header>
+  );
+}
+
+export interface PageLayoutProps extends LayoutElementProps {
+  readonly children: ReactNode;
+}
+
+/** The screen wrapper: the max-width, the gutters, and the vertical rhythm. */
+export function Page({ children, className, style, ref }: PageLayoutProps): ReactElement {
+  return (
+    <div
+      className={className === undefined ? 'tai-page' : `tai-page ${className}`}
+      style={style}
+      ref={ref}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface StackProps extends LayoutElementProps {
+  readonly children: ReactNode;
+  /** The gap step; 4 is the default and needs no modifier class. */
+  readonly gap?: 2 | 3 | 4 | 6;
+}
+
+/** The modifier class per non-default gap step; gap 4 is `.tai-stack`'s own gap. */
+const STACK_GAP_CLASS: Record<2 | 3 | 6, string> = {
+  2: 'tai-stack-2',
+  3: 'tai-stack-3',
+  6: 'tai-stack-6',
+};
+
+/** A vertical flex column on the spacing scale. */
+export function Stack({ children, gap = 4, className, style, ref }: StackProps): ReactElement {
+  const classes = ['tai-stack'];
+  if (gap !== 4) classes.push(STACK_GAP_CLASS[gap]);
+  if (className !== undefined) classes.push(className);
+  return (
+    <div className={classes.join(' ')} style={style} ref={ref}>
+      {children}
+    </div>
+  );
+}