@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/json-diff.tsx

@@ -21,6 +21,7 @@
  */
 import { type ReactNode } from 'react';
 
+import { isRecord } from '../guards';
 import { Badge } from './badge';
 import { JsonTree } from './json-tree';
 import { Table, TBody, TD, TH, THead, TR } from './table';
@@ -36,10 +37,6 @@ export interface JsonDiffRow {
   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;

package/src/components/json-tree-context.ts

@@ -0,0 +1,26 @@
+/**
+ * The shared tree state a `JsonTree` publishes to its nodes: per-node open state,
+ * the reader's toggle, the single copy path, and the page size.
+ */
+import { createContext, useContext } from 'react';
+
+export interface JsonTreeContextValue {
+  /** Whether the node at `path`/`depth` is open right now. */
+  readonly isOpen: (path: string, depth: number) => boolean;
+  /** Records the reader's explicit toggle of one node. */
+  readonly setOpen: (path: string, open: boolean) => void;
+  /** Copies a value's JSON, returning whether the write succeeded. */
+  readonly copy: (value: unknown) => Promise<boolean>;
+  readonly pageSize: number;
+}
+
+export const JsonTreeContext = createContext<JsonTreeContextValue | null>(null);
+
+/** The shared tree state; a subcomponent outside a `JsonTree` is a wiring error. */
+export function useJsonTreeContext(): JsonTreeContextValue {
+  const context = useContext(JsonTreeContext);
+  if (context === null) {
+    throw new Error('JsonTree subcomponents must be rendered inside a JsonTree.');
+  }
+  return context;
+}

package/src/components/json-tree-model.ts

@@ -0,0 +1,139 @@
+/**
+ * The bounded-traversal model behind `JsonTree`: container inspection, the paged
+ * child slice, path identity, and the open-state computation for the depth
+ * default, expand-all and collapse-all baselines. Pure — no React, no DOM.
+ */
+import { isRecord } from '../guards';
+
+/** The deepest level opened by the guarded default; deeper nodes start collapsed. */
+export const AUTO_EXPAND_DEPTH = 1;
+
+/**
+ * The deepest level EXPAND-ALL reaches. Past it a node opens only on an explicit
+ * click, so the one action that opens the whole tree still cannot force an
+ * unbounded-depth payload into the DOM in a single stroke.
+ */
+export const MAX_AUTO_DEPTH = 6;
+
+/** Children rendered per page; the rest wait behind a "show more" control. */
+export const PAGE_SIZE = 100;
+
+/**
+ * The most rendered nodes EXPAND-ALL may auto-open in one stroke. The depth cap and
+ * the per-page limit each bound ONE dimension, but a payload that is wide AND deep
+ * multiplies them — auto-opening every node up to the cap would lay out on the order
+ * of PAGE_SIZE^depth nodes and freeze the tab. Expand-all instead opens containers
+ * breadth-first only until this budget is spent; a node past it stays collapsed and
+ * opens on an explicit click, so a huge payload opens a bounded, usable subset.
+ */
+export const AUTO_EXPAND_NODE_BUDGET = 1500;
+
+/** Whether a value is a disclosure (object or array) rather than a leaf. */
+export function isContainer(value: unknown): boolean {
+  return Array.isArray(value) || isRecord(value);
+}
+
+/** A container's child count, without materializing its entries. */
+export function containerCount(value: unknown): number {
+  if (Array.isArray(value)) return value.length;
+  if (isRecord(value)) return Object.keys(value).length;
+  throw new Error('containerCount expects an array or a record.');
+}
+
+/**
+ * The first `end` entries of a container, arrays keyed by index and objects by
+ * key. Only the visible window is materialized, so a million-element array's
+ * children never all exist at once.
+ */
+export function sliceEntries(value: unknown, end: number): [string, unknown][] {
+  if (Array.isArray(value)) {
+    return value.slice(0, end).map((item, index) => [String(index), item]);
+  }
+  // Slice the keys before reading values, so only the visible window is materialized.
+  if (isRecord(value))
+    return Object.keys(value)
+      .slice(0, end)
+      .map((key) => [key, value[key]]);
+  throw new Error('sliceEntries expects an array or a record.');
+}
+
+/** One container's summary text: its kind and its child count. */
+export function containerSummary(value: unknown, count: number): string {
+  return Array.isArray(value) ? `Array(${String(count)})` : `Object(${String(count)})`;
+}
+
+/**
+ * A child's identity for the open-state map. Each segment is percent-encoded, so a
+ * key that itself contains the separator cannot collide with a different path.
+ */
+export function childPath(parent: string, name: string): string {
+  const segment = encodeURIComponent(name);
+  return parent === '' ? segment : `${parent}/${segment}`;
+}
+
+/** The default open state a call site's `defaultExpanded` selects. */
+export type Baseline = 'depth' | 'expanded' | 'collapsed';
+
+export function initialBaseline(defaultExpanded: boolean | undefined): Baseline {
+  if (defaultExpanded === true) return 'expanded';
+  if (defaultExpanded === false) return 'collapsed';
+  return 'depth';
+}
+
+/**
+ * The set of paths EXPAND-ALL auto-opens: a breadth-first sweep that opens each
+ * container in turn — spending its visible child count against a shared node budget
+ * and enqueuing that page's own container children — skipping any node whose page
+ * would overspend {@link AUTO_EXPAND_NODE_BUDGET} or that sits past {@link MAX_AUTO_DEPTH}.
+ * Only a bounded window of a huge payload is materialized, so this stays cheap even
+ * when the data is enormous; the paths it omits stay collapsed and open on a click.
+ */
+export function expandedOpenPaths(root: unknown): ReadonlySet<string> {
+  const open = new Set<string>();
+  if (!isContainer(root)) return open;
+
+  let budget = AUTO_EXPAND_NODE_BUDGET;
+  const queue: { readonly value: unknown; readonly path: string; readonly depth: number }[] = [
+    { value: root, path: '', depth: 0 },
+  ];
+
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (node === undefined) break;
+    if (node.depth >= MAX_AUTO_DEPTH) continue;
+
+    const shown = Math.min(PAGE_SIZE, containerCount(node.value));
+    // Skip when the budget can't seat a whole page (a later, smaller node may still fit).
+    if (shown > budget) continue;
+    budget -= shown;
+    open.add(node.path);
+
+    for (const [name, childValue] of sliceEntries(node.value, shown)) {
+      if (isContainer(childValue)) {
+        queue.push({ value: childValue, path: childPath(node.path, name), depth: node.depth + 1 });
+      }
+    }
+  }
+
+  return open;
+}
+
+/**
+ * Whether a node is open, from the baseline and the reader's own toggles. An
+ * explicit toggle always wins; otherwise the baseline decides — the depth-guarded
+ * default opens through {@link AUTO_EXPAND_DEPTH}, expand-all opens the budgeted
+ * breadth-first set, collapse-all opens nothing.
+ */
+export function computeOpen(
+  baseline: Baseline,
+  overrides: ReadonlyMap<string, boolean>,
+  expandedPaths: ReadonlySet<string> | null,
+  path: string,
+  depth: number,
+): boolean {
+  const override = overrides.get(path);
+  if (override !== undefined) return override;
+  if (baseline === 'expanded') return expandedPaths?.has(path) ?? false;
+  if (baseline === 'collapsed') return false;
+  return depth <= AUTO_EXPAND_DEPTH;
+}

package/src/components/json-tree-nodes.tsx

@@ -0,0 +1,224 @@
+/**
+ * The rendered nodes of a `JsonTree`: the copy control, one disclosure/leaf node,
+ * and a node's paged children. State is read from the tree context; layout uses
+ * the code-block rhythm.
+ */
+import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactElement } from 'react';
+import { useEffect, useRef, useState } from 'react';
+
+import { COPIED_LABEL, COPIED_RESET_MS } from '../hooks/useClipboardCopy';
+import { CheckIcon, CopyIcon } from './icons';
+import { useJsonTreeContext } from './json-tree-context';
+import {
+  childPath,
+  containerCount,
+  containerSummary,
+  isContainer,
+  sliceEntries,
+} from './json-tree-model';
+import { primitiveClass, primitiveText } from './json-value-format';
+
+/** A copy control's resting face; whichever is exposed is also its accessible name. */
+export const COPY_LABEL = 'Copy';
+
+/**
+ * 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 = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 'var(--tai-space-2)',
+  cursor: 'pointer',
+};
+
+/** The copy control sits at the far end of a disclosure's row. */
+const nodeCopyStyle: CSSProperties = { marginLeft: 'auto' };
+
+/**
+ * The per-node copy button's geometry: borrows `tai-icon-btn` for the focus ring,
+ * muted ink and hover, then shrinks to the code rhythm so the row stays dense.
+ */
+const nodeCopyButtonStyle: CSSProperties = {
+  width: 'auto',
+  height: 'auto',
+  padding: 'var(--tai-space-1)',
+};
+
+const showMoreStyle: CSSProperties = { marginTop: 'var(--tai-space-1)' };
+
+interface CopyButtonProps {
+  readonly value: unknown;
+  /**
+   * The button's resting accessible name. When it flips to its confirmed state the
+   * name flips with it, so a control reading "Copied" is never still named "Copy"
+   * (WCAG 2.5.3). A `text` button spells the name in its own words; an `icon` button
+   * takes it from here.
+   */
+  readonly label: string;
+  readonly variant: 'text' | 'icon';
+}
+
+/**
+ * A copy control that writes its value to the clipboard and shows a transient
+ * confirmed state. The write itself lives on the tree context, so a refusal is
+ * reported ONCE — as the tree's shared alert — rather than inline at each of the
+ * many buttons a large payload carries.
+ */
+export function CopyButton({ value, label, variant }: CopyButtonProps): ReactElement {
+  const { copy } = useJsonTreeContext();
+  const [copied, setCopied] = useState(false);
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // The write is async, so a copy can be in flight when the button unmounts (a dialog
+  // holding the tree closes on the same click); checked before the resolution sets state.
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      if (resetTimer.current !== null) clearTimeout(resetTimer.current);
+    };
+  }, []);
+
+  const handleClick = (event: ReactMouseEvent<HTMLButtonElement>): void => {
+    // Inside a `<summary>` a click both toggles the disclosure natively and reaches
+    // the summary's own toggle handler; neither should fire for a copy.
+    event.preventDefault();
+    event.stopPropagation();
+    void copy(value).then((ok) => {
+      if (!ok || !mounted.current) return;
+      setCopied(true);
+      if (resetTimer.current !== null) clearTimeout(resetTimer.current);
+      resetTimer.current = setTimeout(() => {
+        if (mounted.current) setCopied(false);
+      }, COPIED_RESET_MS);
+    });
+  };
+
+  if (variant === 'text') {
+    return (
+      <button type="button" className="tai-btn tai-btn-ghost" onClick={handleClick}>
+        {copied ? <CheckIcon /> : <CopyIcon />}
+        {copied ? COPIED_LABEL : label}
+      </button>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      className="tai-icon-btn"
+      style={{ ...nodeCopyStyle, ...nodeCopyButtonStyle }}
+      aria-label={copied ? COPIED_LABEL : label}
+      onClick={handleClick}
+    >
+      {copied ? <CheckIcon /> : <CopyIcon />}
+    </button>
+  );
+}
+
+interface NodeProps {
+  readonly name?: string;
+  readonly value: unknown;
+  readonly depth: number;
+  readonly path: string;
+}
+
+/**
+ * The visible slice of a container's children, plus a "show more" control while
+ * any remain. Rendered ONLY when the node is open, so a collapsed container costs
+ * nothing and the page count follows how far the reader has opened it.
+ */
+function NodeChildren({
+  value,
+  count,
+  depth,
+  path,
+}: {
+  readonly value: unknown;
+  readonly count: number;
+  readonly depth: number;
+  readonly path: string;
+}): ReactElement {
+  const { pageSize } = useJsonTreeContext();
+  const [visible, setVisible] = useState(pageSize);
+  const shownCount = Math.min(visible, count);
+  const shown = sliceEntries(value, shownCount);
+  const remaining = count - shownCount;
+
+  return (
+    <div style={childrenStyle}>
+      {shown.map(([childName, childValue]) => (
+        <JsonNode
+          key={childName}
+          name={childName}
+          value={childValue}
+          depth={depth + 1}
+          path={childPath(path, childName)}
+        />
+      ))}
+      {remaining > 0 ? (
+        <button
+          type="button"
+          className="tai-btn tai-btn-ghost"
+          style={showMoreStyle}
+          onClick={() => {
+            setVisible((current) => current + pageSize);
+          }}
+        >
+          Show {String(Math.min(remaining, pageSize))} more
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function JsonNode({ name, value, depth, path }: NodeProps): ReactElement {
+  const { isOpen, setOpen } = useJsonTreeContext();
+
+  if (isContainer(value)) {
+    const count = containerCount(value);
+    const open = isOpen(path, depth);
+    const summary = containerSummary(value, count);
+    const handleToggle = (event: ReactMouseEvent<HTMLElement>): void => {
+      // The disclosure is state-driven: cancel the browser's own toggle so the two
+      // never diverge, then record the reader's intent.
+      event.preventDefault();
+      setOpen(path, !open);
+    };
+
+    return (
+      <details open={open}>
+        <summary style={summaryStyle} onClick={handleToggle}>
+          {name !== undefined ? <span className="tai-syntax-key">{name}: </span> : null}
+          <span className="tai-muted">{summary}</span>
+          {/* The root's copy-node control would duplicate the toolbar's copy-whole. */}
+          {depth > 0 ? (
+            <CopyButton
+              value={value}
+              variant="icon"
+              label={name !== undefined ? `Copy ${name}` : COPY_LABEL}
+            />
+          ) : null}
+        </summary>
+        {open ? <NodeChildren value={value} count={count} depth={depth} path={path} /> : null}
+      </details>
+    );
+  }
+
+  return (
+    <div>
+      {name !== undefined ? <span className="tai-syntax-key">{name}: </span> : null}
+      <span className={primitiveClass(value)}>{primitiveText(value)}</span>
+    </div>
+  );
+}