@tai42/studio-sdk 0.2.0

package/src/components/badge.tsx

@@ -0,0 +1,31 @@
+/**
+ * `Badge` — a small tinted label. `variant` is a free string (extension "kind"
+ * values map straight to it); known variants get a themed tint plus its
+ * matching text color from the design-system classes, and any other value falls
+ * back to the neutral tint.
+ */
+import type { ReactNode } from 'react';
+
+export interface BadgeProps {
+  readonly variant?: string;
+  readonly children: ReactNode;
+}
+
+const NEUTRAL_CLASS = 'tai-badge tai-badge-neutral';
+
+/** `primary` is the base badge: the accent tint needs no modifier class. */
+const VARIANT_CLASS: Record<string, string> = {
+  neutral: NEUTRAL_CLASS,
+  primary: 'tai-badge',
+  success: 'tai-badge tai-badge-ok',
+  warning: 'tai-badge tai-badge-warn',
+  danger: 'tai-badge tai-badge-err',
+};
+
+export function Badge({ variant = 'neutral', children }: BadgeProps) {
+  return (
+    <span data-variant={variant} className={VARIANT_CLASS[variant] ?? NEUTRAL_CLASS}>
+      {children}
+    </span>
+  );
+}

package/src/components/checkbox.tsx

@@ -0,0 +1,93 @@
+/**
+ * `Checkbox` — a design-system wrapper over Radix Checkbox (role `checkbox`). An
+ * optional inline `label` renders a linked `<label>` so clicking the text toggles
+ * the box (buttons are labelable). When the box carries no visible label (a
+ * selection column in a table), pass `aria-label` so it still has an accessible
+ * name. Inside a `Field` the box picks up the field id + a11y wiring instead.
+ *
+ * Appearance is the `tai-checkbox` class: Radix stamps `data-state` on the root,
+ * and the stylesheet paints the checked and indeterminate grounds from it, so the
+ * mark shows for a controlled AND an uncontrolled box alike. The two filled
+ * states share that ground, so the MARK is what tells them apart: `CheckIcon` for
+ * checked, `MinusIcon` for indeterminate, both decorative behind the control's
+ * own name.
+ */
+import * as RadixCheckbox from '@radix-ui/react-checkbox';
+import { useId } from 'react';
+
+import { useFieldControl } from './field';
+import { CheckIcon, MinusIcon } from './icons';
+
+export interface CheckboxProps {
+  /**
+   * `'indeterminate'` is the MIXED state a parent box wears while only some of
+   * the children it governs are checked. Radix reports it as
+   * `aria-checked="mixed"`; clicking it resolves to checked, which is why the
+   * change callback stays boolean.
+   */
+  readonly checked?: boolean | 'indeterminate';
+  readonly defaultChecked?: boolean;
+  readonly onCheckedChange?: (checked: boolean) => void;
+  readonly disabled?: boolean;
+  readonly label?: string;
+  /**
+   * Accessible name for a checkbox with no visible `label` (e.g. a table cell).
+   * An enclosing `Field` wins where both are given — it names the box from
+   * visible text, and `aria-label` would override that native label and leave
+   * the visible text out of the accessible name (WCAG 2.5.3).
+   */
+  readonly 'aria-label'?: string;
+  readonly name?: string;
+  readonly value?: string;
+}
+
+export function Checkbox({
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  disabled,
+  label,
+  'aria-label': ariaLabel,
+  name,
+  value,
+}: CheckboxProps) {
+  const field = useFieldControl();
+  const generatedId = useId();
+  const id = field.id ?? generatedId;
+
+  const box = (
+    <RadixCheckbox.Root
+      id={id}
+      className="tai-checkbox"
+      // The caller's name is the FALLBACK. A box named by an inline `label` or
+      // by an enclosing `Field` is named from visible text, and `aria-label`
+      // outranks a native `<label for>` — emitting both would discard that text.
+      aria-label={field.id === undefined && label === undefined ? ariaLabel : undefined}
+      aria-describedby={field['aria-describedby']}
+      aria-invalid={field['aria-invalid']}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={(next) => {
+        onCheckedChange?.(next === true);
+      }}
+      disabled={disabled}
+      name={name}
+      value={value}
+    >
+      {/* The indicator only ever holds the mark, so it is a bare flex box. The
+          checked and indeterminate grounds are the same accent fill, so a shared
+          mark would make the two states indistinguishable. */}
+      <RadixCheckbox.Indicator aria-hidden="true" style={{ display: 'flex' }}>
+        {checked === 'indeterminate' ? <MinusIcon /> : <CheckIcon />}
+      </RadixCheckbox.Indicator>
+    </RadixCheckbox.Root>
+  );
+
+  if (label === undefined) return box;
+  return (
+    <label htmlFor={id} className="tai-choice">
+      {box}
+      <span>{label}</span>
+    </label>
+  );
+}

package/src/components/code-block.tsx

@@ -0,0 +1,37 @@
+/**
+ * `CodeBlock` — escaped, monospaced preformatted text for tool results and string
+ * payloads, on the design system's terminal ground (`tai-code-block`). The content
+ * is a React text child inside `<pre><code>`, so it is escaped by React and
+ * rendered verbatim; this component is NEVER an HTML sink (no
+ * `dangerouslySetInnerHTML`).
+ *
+ * The `<pre>` 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 long line makes it a named keyboard target, a short one leaves it
+ * an ordinary block.
+ */
+import { useOverflowRegion } from './scroll-region';
+
+export interface CodeBlockProps {
+  readonly code: string;
+  /** Optional language label, shown as a caption; purely informational. */
+  readonly language?: string;
+}
+
+/** The region's name when no language caption supplies one. */
+const DEFAULT_LABEL = 'Code';
+
+export function CodeBlock({ code, language }: CodeBlockProps) {
+  // No consumer ref: the measurement's own callback ref is the only thing that
+  // needs the `<pre>`, and this component publishes no `ref` prop.
+  const region = useOverflowRegion(undefined, language ?? DEFAULT_LABEL);
+
+  return (
+    <div className="tai-stack tai-stack-2">
+      {language !== undefined ? <span className="tai-label">{language}</span> : null}
+      <pre className="tai-code-block" {...region}>
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+}

package/src/components/completion-input.tsx

@@ -0,0 +1,137 @@
+/**
+ * `CompletionInput` — a text field wired to MCP `completion/complete`. As the
+ * human types, it asks the provided `fetchCompletions` (a thin wrapper over the
+ * MCP completions capability) for argument suggestions and renders them as a
+ * selectable list; picking one fills the field. A fetch failure clears the
+ * suggestions and surfaces through `onError` — never a silent swallow.
+ *
+ * The field is a `tai-input` and its popup wears the Select popup's classes
+ * (`tai-select-content` / `tai-select-item`), so a suggestion list and a select
+ * list are the same object to a reader.
+ *
+ * Reusable by any feature; the intended consumer is a `SchemaForm` string field
+ * that has a completion provider for its tool/prompt/resource argument.
+ */
+import type { CSSProperties, ReactNode } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
+
+import { useFieldControl } from './field';
+
+export interface CompletionInputProps {
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  /** Fetch argument completions for the current input value. */
+  readonly fetchCompletions: (value: string) => Promise<readonly string[]>;
+  /** Surfaced (not swallowed) when a completion fetch fails. */
+  readonly onError?: (error: unknown) => void;
+  readonly placeholder?: string;
+}
+
+const wrapStyle: CSSProperties = { position: 'relative' };
+
+/**
+ * The popup sits directly under the field rather than against its top edge. It
+ * is a `<ul>`, so it also drops the marker a host without a CSS reset would draw.
+ */
+const listStyle: CSSProperties = {
+  marginTop: 'var(--tai-space-1)',
+  marginBottom: 0,
+  listStyle: 'none',
+};
+
+/**
+ * A completion-backed text input. Suggestions refresh on every edit (a
+ * per-request sequence guard drops a stale response) and render as an ARIA
+ * listbox; selecting an option fills the field and clears the list.
+ */
+export function CompletionInput({
+  value,
+  onChange,
+  fetchCompletions,
+  onError,
+  placeholder,
+}: CompletionInputProps): ReactNode {
+  const field = useFieldControl();
+  const listboxId = useId();
+  const [suggestions, setSuggestions] = useState<readonly string[]>([]);
+  // The list is only shown while the human is typing. Selecting an option (a
+  // programmatic value change) closes it until the next keystroke, so the field
+  // does not immediately re-suggest against the value it just accepted.
+  const [open, setOpen] = useState(false);
+  const seq = useRef(0);
+
+  useEffect(() => {
+    const requestId = ++seq.current;
+    let cancelled = false;
+    fetchCompletions(value)
+      .then((values) => {
+        // Drop a stale response so a slow earlier request cannot overwrite a
+        // newer one's suggestions.
+        if (!cancelled && requestId === seq.current) setSuggestions(values);
+      })
+      .catch((error: unknown) => {
+        if (cancelled || requestId !== seq.current) return;
+        setSuggestions([]);
+        onError?.(error);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [value, fetchCompletions, onError]);
+
+  const select = (suggestion: string) => {
+    setOpen(false);
+    setSuggestions([]);
+    onChange(suggestion);
+  };
+
+  const showList = open && suggestions.length > 0;
+
+  return (
+    <div style={wrapStyle}>
+      <input
+        {...field}
+        className="tai-input"
+        type="text"
+        role="combobox"
+        aria-expanded={showList}
+        aria-controls={listboxId}
+        aria-autocomplete="list"
+        value={value}
+        placeholder={placeholder}
+        onChange={(event) => {
+          setOpen(true);
+          onChange(event.target.value);
+        }}
+      />
+      {/* `tai-select-viewport` carries the inset that gives an option's focus ring
+          room. This popup is its own clip box — it has no Radix viewport to put
+          the class on — so it wears both, or preflight's `* { padding: 0 }` zeroes
+          the inset and clips every ring. */}
+      {showList && (
+        <ul
+          id={listboxId}
+          role="listbox"
+          className="tai-select-content tai-select-viewport"
+          style={listStyle}
+        >
+          {suggestions.map((suggestion) => (
+            <li key={suggestion} role="presentation">
+              <button
+                type="button"
+                role="option"
+                aria-selected={false}
+                className="tai-select-item"
+                onClick={() => {
+                  select(suggestion);
+                }}
+              >
+                {suggestion}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}