@tai42/studio-sdk 0.2.0

package/src/components/select.tsx

@@ -0,0 +1,149 @@
+/**
+ * `Select` — a design-system wrapper over Radix Select (an accessible listbox with
+ * a `combobox` trigger). Options are passed declaratively — either a flat
+ * `options` run or labelled `groups`, never both — and the trigger auto-wires to
+ * an enclosing `Field`.
+ *
+ * Every surface is a class — `tai-select-trigger` for the control, and
+ * `tai-select-content` / `tai-select-item` for the popup, which is where the
+ * shared keyboard-highlight rule lives. The disclosure mark is the design
+ * system's `ChevronDownIcon`, decorative behind the trigger's own name.
+ */
+import * as RadixSelect from '@radix-ui/react-select';
+
+import { SELECT_TRIGGER_CLASS } from './control-styles';
+import { useFieldControl } from './field';
+import { CheckIcon, ChevronDownIcon } from './icons';
+
+export interface SelectOption {
+  readonly value: string;
+  readonly label: string;
+  readonly disabled?: boolean;
+}
+
+/** A labelled cluster of options (e.g. tools grouped by tag). */
+export interface SelectGroup {
+  readonly label: string;
+  readonly options: readonly SelectOption[];
+}
+
+/** Everything the two listbox shapes have in common. */
+interface SelectSharedProps {
+  readonly value?: string;
+  readonly defaultValue?: string;
+  readonly onValueChange?: (value: string) => void;
+  readonly placeholder?: string;
+  readonly disabled?: boolean;
+  readonly name?: string;
+  /**
+   * Accessible name for the trigger when it is not wired to an enclosing
+   * `Field`. A `Field` wins where both are given — it names the trigger 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;
+}
+
+/** The FLAT listbox: one ungrouped run of options. */
+export interface SelectProps extends SelectSharedProps {
+  readonly options: readonly SelectOption[];
+}
+
+/** The GROUPED listbox: labelled clusters, each carrying its own options. */
+export interface SelectGroupsProps extends SelectSharedProps {
+  readonly groups: readonly SelectGroup[];
+}
+
+/**
+ * What `Select` ACCEPTS: exactly one of the two shapes, never both. Only one
+ * list can be rendered, so accepting `options` alongside `groups` means
+ * discarding every entry of the other without a word.
+ *
+ * The exclusion lives HERE and not on the two interfaces because both are
+ * published plugin API and must stay extendable: `groups?: undefined` written
+ * onto `SelectProps` makes `interface MyPicker extends SelectProps { groups:
+ * readonly SelectGroup[] }` a TS2430, and a union cannot be `extends`-ed at all
+ * (TS2312).
+ */
+type SelectArgs =
+  | (SelectProps & { readonly groups?: undefined })
+  | (SelectGroupsProps & { readonly options?: undefined });
+
+function OptionItem({ option }: { option: SelectOption }) {
+  return (
+    <RadixSelect.Item className="tai-select-item" value={option.value} disabled={option.disabled}>
+      <RadixSelect.ItemText>{option.label}</RadixSelect.ItemText>
+      {/* The highlight follows the reader through the list, so it cannot also
+          stand for the chosen value. The check is what marks that, and Radix
+          renders it for the selected option only. It is decorative: Radix already
+          puts `aria-selected` on the item. */}
+      <RadixSelect.ItemIndicator className="tai-select-item-indicator">
+        <CheckIcon />
+      </RadixSelect.ItemIndicator>
+    </RadixSelect.Item>
+  );
+}
+
+export function Select(props: SelectArgs) {
+  const {
+    value,
+    defaultValue,
+    onValueChange,
+    placeholder = 'Select…',
+    disabled,
+    name,
+    'aria-label': ariaLabel,
+  } = props;
+  const field = useFieldControl();
+  // Untyped JavaScript is the only caller that reaches this. Rendering one list
+  // and dropping the other would lose every entry in the discarded one silently,
+  // and an empty listbox reads as "there is nothing to choose".
+  if ((props.options === undefined) === (props.groups === undefined)) {
+    throw new Error(
+      'Select renders exactly one of `options` or `groups`; it was given both, or neither.',
+    );
+  }
+  return (
+    <RadixSelect.Root
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange}
+      disabled={disabled}
+      name={name}
+    >
+      <RadixSelect.Trigger
+        id={field.id}
+        className={SELECT_TRIGGER_CLASS}
+        // A trigger claiming the field's id is named by that field's `<label
+        // for>`, and `aria-label` outranks a native label — emitting both would
+        // discard the visible text the field renders.
+        aria-label={field.id === undefined ? ariaLabel : undefined}
+        aria-describedby={field['aria-describedby']}
+        aria-invalid={field['aria-invalid']}
+      >
+        <RadixSelect.Value placeholder={placeholder} />
+        <RadixSelect.Icon aria-hidden="true">
+          <ChevronDownIcon />
+        </RadixSelect.Icon>
+      </RadixSelect.Trigger>
+      <RadixSelect.Portal>
+        <RadixSelect.Content className="tai-select-content" position="popper" sideOffset={4}>
+          <RadixSelect.Viewport className="tai-select-viewport">
+            {props.groups !== undefined
+              ? props.groups.map((group) => (
+                  <RadixSelect.Group key={group.label}>
+                    <RadixSelect.Label className="tai-select-group-label tai-label">
+                      {group.label}
+                    </RadixSelect.Label>
+                    {group.options.map((option) => (
+                      <OptionItem key={option.value} option={option} />
+                    ))}
+                  </RadixSelect.Group>
+                ))
+              : props.options.map((option) => <OptionItem key={option.value} option={option} />)}
+          </RadixSelect.Viewport>
+        </RadixSelect.Content>
+      </RadixSelect.Portal>
+    </RadixSelect.Root>
+  );
+}

package/src/components/table.tsx

@@ -0,0 +1,94 @@
+/**
+ * Semantic table primitives — thin wrappers over the native table elements.
+ * They keep the real `table`/`row`/`columnheader`/`cell` roles so assistive
+ * tech and tests read a proper table. Only the root carries a class: the header
+ * and cell rules in the stylesheet are descendants of `.tai-table`, so a cell
+ * cannot drift out of the system by forgetting one.
+ *
+ * A numeric column opts in with `numeric`, which stamps `data-numeric="true"` —
+ * the hook the stylesheet right-aligns on tabular figures so digits line up.
+ *
+ * Each wrapper FORWARDS a consumer `ref` to the native element it renders — the
+ * attribute spread carries it, the same way it carries every other native prop —
+ * 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';
+
+export interface TableProps extends HTMLAttributes<HTMLTableElement> {
+  readonly children?: ReactNode;
+  /** A consumer ref for the `<table>` itself. */
+  readonly ref?: Ref<HTMLTableElement>;
+}
+
+export function Table({ children, className, ...props }: TableProps) {
+  return (
+    <table {...props} className={className === undefined ? 'tai-table' : `tai-table ${className}`}>
+      {children}
+    </table>
+  );
+}
+
+/** `<thead>` and `<tbody>` take the same surface: the native one. */
+export interface TableSectionProps extends HTMLAttributes<HTMLTableSectionElement> {
+  readonly children?: ReactNode;
+  /** A consumer ref for the section element itself. */
+  readonly ref?: Ref<HTMLTableSectionElement>;
+}
+
+export function THead({ children, ...props }: TableSectionProps) {
+  return <thead {...props}>{children}</thead>;
+}
+
+export function TBody({ children, ...props }: TableSectionProps) {
+  return <tbody {...props}>{children}</tbody>;
+}
+
+export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+  readonly children?: ReactNode;
+  /** A consumer ref for the `<tr>` itself. */
+  readonly ref?: Ref<HTMLTableRowElement>;
+}
+
+export function TR({ children, ...props }: TableRowProps) {
+  return <tr {...props}>{children}</tr>;
+}
+
+/** Right-align a column of digits on tabular figures. */
+export interface NumericColumnProps {
+  readonly numeric?: boolean;
+}
+
+/**
+ * A header cell. `scope` defaults to `col` because that is what a `<th>` in the
+ * header row IS, and without it nothing associates the cell with the column
+ * below it: a screen reader announcing a data cell has no header to name it.
+ * A row header — the leading cell of a body row — passes `scope="row"`.
+ */
+export interface THProps extends ThHTMLAttributes<HTMLTableCellElement>, NumericColumnProps {
+  readonly children?: ReactNode;
+  /** A consumer ref for the `<th>` itself. */
+  readonly ref?: Ref<HTMLTableCellElement>;
+}
+
+export function TH({ children, numeric = false, scope = 'col', ...props }: THProps) {
+  return (
+    <th {...props} scope={scope} data-numeric={numeric ? 'true' : undefined}>
+      {children}
+    </th>
+  );
+}
+
+export interface TDProps extends TdHTMLAttributes<HTMLTableCellElement>, NumericColumnProps {
+  readonly children?: ReactNode;
+  /** A consumer ref for the `<td>` itself. */
+  readonly ref?: Ref<HTMLTableCellElement>;
+}
+
+export function TD({ children, numeric = false, ...props }: TDProps) {
+  return (
+    <td {...props} data-numeric={numeric ? 'true' : undefined}>
+      {children}
+    </td>
+  );
+}

package/src/components/tabs.tsx

@@ -0,0 +1,51 @@
+/**
+ * `Tabs` — a wrapper over Radix Tabs (roles `tablist` / `tab` / `tabpanel`,
+ * arrow-key roving focus). Panels are declared inline per item. The selected
+ * tab's accent rail and heavier label come from `.tai-tab[data-state='active']`
+ * in the stylesheet, keyed off the `data-state` Radix stamps on each trigger.
+ */
+import * as RadixTabs from '@radix-ui/react-tabs';
+import type { ReactNode } from 'react';
+
+export interface TabItem {
+  readonly value: string;
+  readonly label: string;
+  readonly content: ReactNode;
+  readonly disabled?: boolean;
+}
+
+export interface TabsProps {
+  readonly items: readonly TabItem[];
+  readonly value?: string;
+  readonly defaultValue?: string;
+  readonly onValueChange?: (value: string) => void;
+}
+
+export function Tabs({ items, value, defaultValue, onValueChange }: TabsProps) {
+  const firstValue = items[0]?.value;
+  return (
+    <RadixTabs.Root
+      value={value}
+      defaultValue={defaultValue ?? firstValue}
+      onValueChange={onValueChange}
+    >
+      <RadixTabs.List className="tai-tablist">
+        {items.map((item) => (
+          <RadixTabs.Trigger
+            key={item.value}
+            value={item.value}
+            disabled={item.disabled}
+            className="tai-tab"
+          >
+            {item.label}
+          </RadixTabs.Trigger>
+        ))}
+      </RadixTabs.List>
+      {items.map((item) => (
+        <RadixTabs.Content key={item.value} value={item.value} className="tai-tabpanel">
+          {item.content}
+        </RadixTabs.Content>
+      ))}
+    </RadixTabs.Root>
+  );
+}

package/src/components/tags.tsx

@@ -0,0 +1,137 @@
+/**
+ * Tag rendering + authoring, shared across features. `TagChips` displays a list of
+ * labels as escaped chips (server strings are arbitrary — React escapes every one,
+ * never an HTML sink). `TagsInput` is the controlled add/remove editor.
+ *
+ * A tag is a `tai-chip tai-chip-static`: it reads, it is not a control. The
+ * control beside it is the `tai-icon-btn` that removes it, which carries the
+ * accessible name ("Remove tag <tag>") because its `CloseIcon` is decorative.
+ *
+ * These live in the SDK because more than one feature (presets, agents, and the
+ * 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 { CloseIcon } from './icons';
+import { Button } from './primitives';
+import { TextInput } from './inputs';
+
+/** A tag and its remove control read as one unit, tighter than the row default. */
+const tagGroupStyle: CSSProperties = { gap: 'var(--tai-space-1)' };
+
+export interface TagChipsProps {
+  readonly tags: readonly string[];
+}
+
+/** Read-only chips for a list of tags. Renders nothing when there are none. */
+export function TagChips({ tags }: TagChipsProps): ReactNode {
+  if (tags.length === 0) return null;
+  return (
+    <span className="tai-row" style={tagGroupStyle}>
+      {tags.map((tag) => (
+        <span key={tag} className="tai-chip tai-chip-static">
+          {tag}
+        </span>
+      ))}
+    </span>
+  );
+}
+
+export interface TagsInputProps {
+  readonly value: readonly string[];
+  readonly onChange: (next: string[]) => void;
+  readonly disabled?: boolean;
+  /**
+   * The draft input's accessible name when no enclosing `Field` supplies one.
+   * Forwarded to the input as a native attribute — see the docblock below.
+   */
+  readonly 'aria-label'?: string;
+}
+
+/**
+ * Controlled tag editor. The caller owns the `value` list; `onChange` receives the
+ * next list on every add/remove. A blank or duplicate entry is ignored (never a
+ * silent duplicate chip). Enter or comma commits the draft chip.
+ *
+ * The draft input is a NATIVE-ATTRIBUTE PASS-THROUGH (the family `inputs.tsx`
+ * documents): inside a `Field` it renders the SDK's `TextInput`, which spreads
+ * `useFieldControl()` and so claims the Field's control id, taking the Field's
+ * visible label as its name; mounted OUTSIDE a `Field` it is named by a caller
+ * `aria-label`, which the editor forwards to that same input. Without one a bare
+ * editor is unnamed — the published component owns the naming route rather than
+ * assuming a `Field` is always present. When a `Field` DOES name it, a caller
+ * `aria-label` still has to CONTAIN that visible label (WCAG 2.5.3, Label in
+ * Name); `components/field-group.test.ts` enforces that at every call site.
+ */
+export function TagsInput({
+  value,
+  onChange,
+  disabled,
+  'aria-label': ariaLabel,
+}: TagsInputProps): ReactNode {
+  const [draft, setDraft] = useState('');
+
+  const add = (): void => {
+    const tag = draft.trim();
+    if (tag === '' || value.includes(tag)) {
+      setDraft('');
+      return;
+    }
+    onChange([...value, tag]);
+    setDraft('');
+  };
+
+  const remove = (tag: string): void => {
+    onChange(value.filter((existing) => existing !== tag));
+  };
+
+  return (
+    <div className="tai-stack tai-stack-2">
+      <div className="tai-row">
+        {/* The input takes the row; the button keeps its intrinsic width. */}
+        <div style={{ flex: 1 }}>
+          <TextInput
+            value={draft}
+            onChange={(event) => {
+              setDraft(event.target.value);
+            }}
+            onKeyDown={(event) => {
+              // Enter or comma commits the draft chip.
+              if (event.key === 'Enter' || event.key === ',') {
+                event.preventDefault();
+                add();
+              }
+            }}
+            placeholder="Add a tag…"
+            aria-label={ariaLabel}
+            disabled={disabled}
+          />
+        </div>
+        <Button type="button" onClick={add} disabled={disabled}>
+          Add tag
+        </Button>
+      </div>
+      {value.length > 0 ? (
+        <div className="tai-row">
+          {value.map((tag) => (
+            <span key={tag} className="tai-row" style={tagGroupStyle}>
+              <span className="tai-chip tai-chip-static">{tag}</span>
+              <button
+                type="button"
+                className="tai-icon-btn"
+                aria-label={`Remove tag ${tag}`}
+                onClick={() => {
+                  remove(tag);
+                }}
+                disabled={disabled}
+              >
+                <CloseIcon />
+              </button>
+            </span>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}