@tai42/studio-sdk 0.2.0

package/src/components/field.tsx

@@ -0,0 +1,169 @@
+/**
+ * `Field` — the label + description + error wrapper every form control sits in.
+ * It owns one generated id and publishes it (plus the description/error ids and
+ * the invalid flag) through a context; a nested control reads them via
+ * `useFieldControl` and spreads them, so the label's `htmlFor`, the control's
+ * `aria-describedby`, and its `aria-invalid` stay wired without the caller
+ * threading ids by hand.
+ */
+import { createContext, useContext, useId } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
+
+import { XCircleIcon } from './icons';
+
+interface FieldContextValue {
+  readonly controlId: string | undefined;
+  readonly describedBy: string | undefined;
+  readonly invalid: boolean;
+}
+
+const FieldContext = createContext<FieldContextValue | null>(null);
+
+/** The a11y wiring a form control spreads onto its element. */
+export interface FieldControlProps {
+  readonly id: string | undefined;
+  readonly 'aria-describedby': string | undefined;
+  readonly 'aria-invalid': true | undefined;
+}
+
+/**
+ * Read the enclosing Field's wiring.
+ *
+ * `id` and `aria-describedby` are `undefined` both when there is no Field AND
+ * inside a group `Field`: a group has no single element to carry them, and the
+ * group container itself already carries the name and the description. Only
+ * `aria-invalid` still crosses that boundary, because `role="group"` does not
+ * support it (ARIA 1.2), so the control is the sole place an errored group can
+ * expose its invalid state.
+ */
+export function useFieldControl(): FieldControlProps {
+  const ctx = useContext(FieldContext);
+  if (ctx === null) {
+    return { id: undefined, 'aria-describedby': undefined, 'aria-invalid': undefined };
+  }
+  return {
+    id: ctx.controlId,
+    'aria-describedby': ctx.describedBy,
+    'aria-invalid': ctx.invalid ? true : undefined,
+  };
+}
+
+export interface FieldProps {
+  readonly label: string;
+  readonly description?: string;
+  readonly error?: string;
+  readonly children: ReactNode;
+  readonly style?: CSSProperties;
+  /** APPENDED to `tai-field` rather than replacing it, so the field keeps its paint. */
+  readonly className?: string;
+  /**
+   * Set when the wrapped control is a GROUP rather than one labelable element —
+   * a `RadioGroup`, a set of checkboxes, any `role="radiogroup"`/`role="group"`
+   * panel.
+   *
+   * `<label for>` can only name a labelable element: pointed at a group it
+   * either dangles at an id no element carries or names an element the browser
+   * refuses to label, and it is inert either way. So a group Field wraps
+   * `children` in the group CONTAINER itself — a `<div role="group">` carrying
+   * `aria-labelledby` at the label and `aria-describedby` at the description and
+   * error — and the label becomes a `<span>`, because a `<label>` associated
+   * with nothing is a semantics lie.
+   *
+   * IT ALSO CHANGES WHAT A CHILD READS FROM {@link useFieldControl}. The
+   * container is what carries the name and the description, so the group Field
+   * publishes NEITHER `id` NOR `aria-describedby` — both are `undefined`, and a
+   * control that spread them would take the group's own name and description for
+   * itself. `aria-invalid` still crosses: `role="group"` does not support it
+   * (ARIA 1.2), so the control is the only place an errored group can expose its
+   * invalid state.
+   *
+   * Naming therefore happens BY CONSTRUCTION rather than by the call site
+   * remembering to read a hook. The cost is one extra container announcement
+   * where the child has a group role of its own; that is accepted deliberately,
+   * because the two failure directions are asymmetric — a redundant container is
+   * audible, an unnamed group is silent.
+   *
+   * A group child left UNMARKED is a build failure, not a runtime surprise:
+   * `components/field-group.test.ts` ("Field group contract" → "marks every
+   * Field whose child does not claim its control id") scans every Field call
+   * site in the repository, and a child outside its list of control-id-claiming
+   * components — `RadioGroup` among them — reddens until the site passes
+   * `group`.
+   */
+  readonly group?: boolean;
+}
+
+export function Field({
+  label,
+  description,
+  error,
+  children,
+  style,
+  className,
+  group = false,
+}: FieldProps) {
+  const controlId = useId();
+  const labelId = `${controlId}-label`;
+  const descriptionId = `${controlId}-desc`;
+  const errorId = `${controlId}-err`;
+
+  const describedByIds: string[] = [];
+  if (description !== undefined) describedByIds.push(descriptionId);
+  if (error !== undefined) describedByIds.push(errorId);
+  const describedBy = describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+
+  // A group withholds the ID and the DESCRIPTION — there is no single element to
+  // carry them, and a control that spread them inside a group would take the
+  // group's own name and description for itself — but it still publishes
+  // `invalid`. `aria-invalid` is not supported on `role="group"` (ARIA 1.2), so
+  // if the group Field withheld it too, a group Field carrying an `error` would
+  // expose its invalid state NOWHERE in the accessibility tree.
+  const value: FieldContextValue = group
+    ? { controlId: undefined, describedBy: undefined, invalid: error !== undefined }
+    : { controlId, describedBy, invalid: error !== undefined };
+
+  return (
+    <FieldContext.Provider value={value}>
+      <div
+        className={className === undefined ? 'tai-field' : `tai-field ${className}`}
+        style={style}
+      >
+        {group ? (
+          <span id={labelId} className="tai-field-label">
+            {label}
+          </span>
+        ) : (
+          <label id={labelId} htmlFor={controlId} className="tai-field-label">
+            {label}
+          </label>
+        )}
+        {group ? (
+          <div
+            role="group"
+            aria-labelledby={labelId}
+            aria-describedby={describedBy}
+            className="tai-field-group"
+          >
+            {children}
+          </div>
+        ) : (
+          children
+        )}
+        {description !== undefined ? (
+          <p id={descriptionId} className="tai-field-hint" style={{ margin: 0 }}>
+            {description}
+          </p>
+        ) : null}
+        {/* The icon carries the invalid state alongside the color, never the color
+            alone — and it is the ERROR mark: a rejected value is a definite
+            negative, not the warning the triangle states. */}
+        {error !== undefined ? (
+          <p id={errorId} role="alert" className="tai-field-error" style={{ margin: 0 }}>
+            <XCircleIcon />
+            {error}
+          </p>
+        ) : null}
+      </div>
+    </FieldContext.Provider>
+  );
+}

package/src/components/fleet-report.tsx

@@ -0,0 +1,136 @@
+/**
+ * `FleetReport` — the shared, loud rendering of a config mutation's fleet broadcast.
+ * Every mutation surface (connector, backup, mcp-config, env, extensions, single-MCP
+ * reload, fleet reload) computes a `FleetReportSummary` from its response through the
+ * api-client's shared handler and hands it here, so a FAILED propagation is never
+ * invisible.
+ *
+ * The `action` prop tunes the copy to the caller's framing: `'save'` (the default,
+ * used by every config-mutation surface) reports a saved change that did not fully
+ * propagate and points the operator at the System page to reload; `'reload'` (the
+ * System page's own fleet-reload action) drops the "Change saved" framing — nothing
+ * was saved, a reload was dispatched — and the self-referential System-page pointer.
+ *
+ * A `converged` summary (every origin applied, or a lone-worker local-only change)
+ * renders NOTHING — the calling surface shows its own success. A `degraded` summary
+ * (the bus was reached but a sibling did not confirm) or an `unreachable` summary (the
+ * bus itself failed) renders a loud `role="alert"` panel naming the honest per-origin
+ * outcomes: `failed` / `missing` / `departed` / `timed_out`, or the bus error. It
+ * never fakes success on a stranded origin. Every server-supplied string (an origin
+ * name, an error/detail message) renders as escaped React text, never an HTML sink.
+ *
+ * Every state — the headline and each origin's outcome — is a `tai-status` line: an
+ * icon MARK plus a word LABEL, with the tone color only reinforcing them, so the
+ * report is readable without color perception.
+ */
+import type { ReactNode } from 'react';
+import type { FleetReportSummary, FleetFailureOutcome } from '@tai42/api-client';
+
+import { AlertTriangleIcon, PendingIcon, XCircleIcon, type IconComponent } from './icons';
+
+/** Human labels for the per-origin non-applied outcomes. */
+const OUTCOME_LABEL: Record<FleetFailureOutcome, string> = {
+  failed: 'apply failed',
+  missing: 'alive but did not acknowledge in time',
+  departed: 'left mid-broadcast',
+  timed_out: 'acknowledged but did not finish applying',
+};
+
+interface StatusTone {
+  /** The `tai-status-*` modifier carrying the tone. */
+  readonly tone: string;
+  /** The mark that states the outcome without relying on that tone. */
+  readonly Icon: IconComponent;
+}
+
+/**
+ * How each outcome reads as a status. `failed` is a definite negative — the apply
+ * raised. `departed` is a warning — the worker is gone, so nothing will converge it.
+ * `missing` and `timed_out` are both UNRESOLVED (never acknowledged / acknowledged
+ * but never finished), so they read as pending rather than as an outright failure.
+ */
+const OUTCOME_STATUS: Record<FleetFailureOutcome, StatusTone> = {
+  failed: { tone: 'tai-status-err', Icon: XCircleIcon },
+  missing: { tone: 'tai-status-pending', Icon: PendingIcon },
+  departed: { tone: 'tai-status-warn', Icon: AlertTriangleIcon },
+  timed_out: { tone: 'tai-status-pending', Icon: PendingIcon },
+};
+
+/**
+ * Render a fleet broadcast's failure state. Returns `null` for a converged/absent
+ * report (nothing to warn about) so callers can always mount it unconditionally
+ * beside their own success line.
+ */
+export interface FleetReportProps {
+  readonly summary: FleetReportSummary | null;
+  /** Whose framing the copy takes: a saved config change, or a dispatched reload. */
+  readonly action?: 'save' | 'reload';
+}
+
+export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
+  if (summary === null || summary.status === 'converged') return null;
+
+  if (summary.status === 'unreachable') {
+    return (
+      <div role="alert" className="tai-error-state tai-stack tai-stack-2">
+        <strong className="tai-status tai-status-err">
+          <XCircleIcon />
+          {action === 'reload'
+            ? 'The worker fleet was not reached'
+            : 'Change saved, but the worker fleet was not reached'}
+        </strong>
+        <p>
+          {action === 'reload'
+            ? 'The worker bus was unreachable, so other workers may still be running the old config. Re-run the reload once the bus is back.'
+            : 'The worker bus was unreachable, so other workers may still be running the old config. Re-run the reload from the System page once the bus is back.'}
+        </p>
+        {/* The bus error is a message, not a listing: it wraps rather than scrolls. */}
+        {summary.error !== null ? (
+          <p className="tai-code-block tai-code-block-wrap">{summary.error}</p>
+        ) : null}
+      </div>
+    );
+  }
+
+  // degraded — the bus was reached but named origins did not converge. That is a
+  // warning, not a failure, so it takes the warning surface: a warn-toned
+  // headline inside an error-toned panel would state two different severities.
+  //
+  // A count and its noun agree. `worker(s)` is machine output at the one moment
+  // an operator is being told something went wrong, and a single unconverged
+  // worker is the commonest degraded fleet there is.
+  const count = summary.failures.length;
+  const workers = `${String(count)} worker${count === 1 ? '' : 's'}`;
+  return (
+    <div role="alert" className="tai-warn-state tai-stack tai-stack-2">
+      <strong className="tai-status tai-status-warn">
+        <AlertTriangleIcon />
+        {action === 'reload'
+          ? `${workers} did not converge`
+          : `Change saved, but ${workers} did not converge`}
+      </strong>
+      <p>
+        {`${count === 1 ? 'This worker' : 'These workers'} may still be running the old config — ` +
+          (action === 'reload' ? 're-run the reload' : 'reload the fleet from the System page') +
+          ` to converge ${count === 1 ? 'it' : 'them'}.`}
+      </p>
+      <ul className="tai-stack tai-stack-2">
+        {summary.failures.map((failure) => {
+          const { tone, Icon } = OUTCOME_STATUS[failure.outcome];
+          return (
+            <li key={failure.origin} className="tai-row">
+              <span className="tai-mono">{failure.origin}</span>
+              <span className={`tai-status ${tone}`}>
+                <Icon />
+                {OUTCOME_LABEL[failure.outcome]}
+              </span>
+              {failure.message !== null ? (
+                <span className="tai-muted">{failure.message}</span>
+              ) : null}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

package/src/components/fonts.css

@@ -0,0 +1,22 @@
+/*
+ * The two webfonts the design system is drawn in, self-hosted so no request ever
+ * leaves the deployment (`font-src 'self'`): Inter Variable for the interface and
+ * Geist Mono Variable for the machine voice — identifiers, timestamps, code, and
+ * the uppercase label style.
+ *
+ * This is a separate stylesheet so a HOST app loads the faces exactly once. A
+ * plugin never imports it; it inherits the families through `--tai-font-sans` and
+ * `--tai-font-mono`.
+ *
+ * BUNDLER-RESOLVED ENTRY POINT. The two lines below are BARE PACKAGE specifiers,
+ * not URLs: only a bundler (or anything else applying Node resolution to CSS)
+ * turns them into the `@font-face` blocks and the hashed `.woff2` assets. Linked
+ * straight into a page — `<link href=".../@tai42/studio-sdk/dist/components/
+ * fonts.css">` — a browser resolves them against the stylesheet's own URL, both
+ * requests 404, and the page silently falls back to the platform font with
+ * nothing failing anywhere. So `@tai42/studio-sdk/fonts.css` is for a build that
+ * resolves package specifiers; `tokens.css` and `components.css`, which carry no
+ * `@import` at all, are the two subpaths a page may link directly.
+ */
+@import '@fontsource-variable/inter';
+@import '@fontsource-variable/geist-mono';