@xemahq/ui-kernel 0.9.0 → 0.9.1

package/src/ui/capture/submit-values.test.ts

@@ -0,0 +1,70 @@
+// Pure-logic proofs for the ONE values→wire projection and the declared
+// transform. Runs under the host-web vitest runner (this package carries no
+// vitest dep — see tsconfig exclude).
+import { describe, expect, it } from 'vitest';
+
+import { applyCaptureTransform, CaptureFieldTransform, CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+import { fieldSpecToZod } from './field-spec-to-zod';
+import { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
+
+const fields: CaptureFieldSpec[] = [
+  { key: 'apiKey', label: 'API key', type: CaptureFieldType.String, required: true, isSecret: true },
+  { key: 'baseUrl', label: 'Base URL', type: CaptureFieldType.Url, required: true },
+  { key: 'serviceAccount', label: 'Service account', type: CaptureFieldType.Json, required: false },
+];
+
+describe('applyCaptureTransform', () => {
+  it('applies only the DECLARED transform', () => {
+    expect(applyCaptureTransform(' a ', CaptureFieldTransform.Trim)).toBe('a');
+    expect(applyCaptureTransform('a', CaptureFieldTransform.Uppercase)).toBe('A');
+    expect(applyCaptureTransform('A', CaptureFieldTransform.Lowercase)).toBe('a');
+    expect(applyCaptureTransform(' a ', CaptureFieldTransform.None)).toBe(' a ');
+    // Absent = no normalization. There is no implicit blanket trim.
+    expect(applyCaptureTransform(' a ', undefined)).toBe(' a ');
+  });
+});
+
+describe('captureValuesToStringMap', () => {
+  it('projects ONLY declared keys, as strings', () => {
+    expect(
+      captureValuesToStringMap(fields, {
+        apiKey: 'sk-1',
+        baseUrl: 'https://acme.test',
+        rogue: 'should not travel',
+      }),
+    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: '' });
+  });
+});
+
+describe('captureValuesToSubmitPayload', () => {
+  it('parses a json field and leaves the rest untouched', () => {
+    expect(
+      captureValuesToSubmitPayload(fields, {
+        apiKey: 'sk-1',
+        baseUrl: 'https://acme.test',
+        serviceAccount: '{"a":1}',
+      }),
+    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: { a: 1 } });
+  });
+
+  it('does not drop an unparseable json value — validation is the gate', () => {
+    expect(captureValuesToSubmitPayload(fields, { serviceAccount: '{' }).serviceAccount).toBe('{');
+  });
+});
+
+describe('json field validation', () => {
+  const schema = fieldSpecToZod(fields);
+
+  it('rejects an unparseable json blob', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{' }).success).toBe(false);
+  });
+
+  it('accepts a parseable json blob and an omitted optional one', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{"a":1}' }).success).toBe(true);
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u' }).success).toBe(true);
+  });
+
+  it('requires a non-empty url/email field when required', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: '' }).success).toBe(false);
+  });
+});

package/src/ui/capture/submit-values.ts

@@ -0,0 +1,63 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Capture values → submit payload
+//
+// The ONE projection from the form's in-memory `CaptureValues` to what goes on
+// the wire. Two faces, because two wire contracts exist and neither should grow
+// its own inline projection:
+//
+//   • `captureValuesToStringMap` — every field as a STRING (the shape a
+//     credential submit takes: `fields: Record<string, string>`).
+//   • `captureValuesToSubmitPayload` — same, except a `json` field is PARSED
+//     into its structured value (the shape the connection credential write
+//     takes: `credentials: Record<string, unknown>`).
+//
+// Both are field-driven: only DECLARED keys are projected, so a stray key in
+// the values record can never reach the wire. Neither performs an undeclared
+// normalization — trimming/casing is `CaptureFieldTransform`, applied once at
+// the input boundary. A blanket trim here would silently override a field that
+// declared `transform: none`.
+// ═══════════════════════════════════════════════════════════════════════════
+import { CaptureFieldType, toFieldList, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues } from './field-spec';
+import { asString } from './value-format';
+
+type Schema = CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[];
+
+/** Project the declared fields to a flat `string` map (fields-only wire). */
+export function captureValuesToStringMap(
+  schema: Schema,
+  values: CaptureValues,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const field of toFieldList(schema)) {
+    payload[field.key] = asString(values[field.key]);
+  }
+  return payload;
+}
+
+/**
+ * Project the declared fields, parsing `json` fields into structured values.
+ *
+ * A `json` field that does not parse is left as its raw string — validation is
+ * `useSchemaValidation`'s job and it must run first; this projection does not
+ * silently drop a value it cannot parse.
+ */
+export function captureValuesToSubmitPayload(
+  schema: Schema,
+  values: CaptureValues,
+): CaptureValues {
+  const payload: CaptureValues = {};
+  for (const field of toFieldList(schema)) {
+    const raw = values[field.key];
+    if (field.type !== CaptureFieldType.Json) {
+      payload[field.key] = raw;
+      continue;
+    }
+    const text = asString(raw);
+    try {
+      payload[field.key] = JSON.parse(text);
+    } catch {
+      payload[field.key] = text;
+    }
+  }
+  return payload;
+}

package/src/ui/index.ts

@@ -54,6 +54,10 @@ export {
   PreviewDeviceFrame,
   type PreviewDevice,
 } from './primitives/preview-device-frame';
+export {
+  UrlPreviewChrome,
+  type UrlPreviewChromeProps,
+} from './primitives/url-preview-chrome';
 
 // ── chart primitives (Wave 9.2 — pure SVG, no external chart lib) ──
 export * from './charts';

package/src/ui/primitives/overflow-tabs.tsx

@@ -15,7 +15,14 @@
  * am I." Same for tabs marked `pinned: true` (indicator dot is sticky).
  */
 import { ChevronDown, X } from 'lucide-react';
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+} from 'react';
 
 import {
   DropdownMenu,
@@ -32,6 +39,14 @@ export interface OverflowTab {
   readonly indicator?: boolean;
   /** Optional numeric badge. */
   readonly count?: number;
+  /**
+   * A pinned tab is ALWAYS in the visible set (never collapsed into "More…")
+   * and never renders a close affordance, even when `onClose` is supplied.
+   * Used for a panel's permanent first tab (e.g. the Vista file browser).
+   */
+  readonly pinned?: boolean;
+  /** Optional leading glyph (a `lucide-react` icon component). */
+  readonly icon?: ComponentType<{ className?: string }>;
 }
 
 interface OverflowTabsProps {
@@ -105,7 +120,9 @@ export function OverflowTabs({
     let used = 0;
     for (let i = 0; i < tabs.length; i++) {
       const w = tabWidths[i] + (vis.length > 0 ? gap : 0);
-      if (used + w <= budget) {
+      // A pinned tab is never collapsed — it stays visible whatever the budget
+      // says, so a panel's permanent first tab can't hide behind "More…".
+      if (tabs[i].pinned === true || used + w <= budget) {
         vis.push(tabs[i]);
         used += w;
       } else {
@@ -155,7 +172,9 @@ export function OverflowTabs({
             tab={t}
             active={t.value === value}
             onClick={() => onChange(t.value)}
-            onClose={onClose ? () => onClose(t.value) : undefined}
+            onClose={
+              onClose && t.pinned !== true ? () => onClose(t.value) : undefined
+            }
           />
         ))}
       </div>
@@ -192,7 +211,7 @@ export function OverflowTabs({
                     className="ml-2 inline-block h-1.5 w-1.5 rounded-full bg-warning"
                   />
                 )}
-                {onClose && (
+                {onClose && t.pinned !== true && (
                   <button
                     type="button"
                     aria-label={`Close ${t.label}`}
@@ -241,6 +260,7 @@ function TabPill({
         onClick={onClick}
         className="inline-flex items-center gap-2 outline-none"
       >
+        {tab.icon && <tab.icon className="h-3.5 w-3.5 shrink-0" />}
         {tab.label}
         {tab.count !== undefined && (
           <span className="rounded bg-paper-elev px-1 font-mono text-[10px] tabular-nums leading-4 text-ink-4">

package/src/ui/primitives/url-preview-chrome.tsx

@@ -0,0 +1,102 @@
+/**
+ * Mock browser chrome for a URL preview.
+ *
+ * Renders the traffic-light dots + an address bar + a refresh affordance, then
+ * the caller-supplied live content (the real iframe) below.
+ *
+ * Owned by the UI kernel so the Vista `url` surface, the thin session
+ * workspace, and any biome preview reuse ONE chrome — there is no second
+ * implementation.
+ */
+import { RotateCw } from 'lucide-react';
+import type { ReactElement, ReactNode } from 'react';
+
+const TRAFFIC_LIGHTS = ['#e5645a', '#e8b13d', '#5bb35b'] as const;
+
+export interface UrlPreviewChromeProps {
+  /** Address shown in the mock address bar. */
+  readonly url: string;
+  /** Live preview content (the real iframe). */
+  readonly children: ReactNode;
+  /** Optional reload handler wired to the refresh glyph. */
+  readonly onReload?: () => void;
+}
+
+export function UrlPreviewChrome({
+  url,
+  children,
+  onReload,
+}: UrlPreviewChromeProps): ReactElement {
+  return (
+    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          padding: '8px 12px',
+          borderBottom: '1px solid hsl(var(--rule))',
+          background: 'hsl(var(--paper) / 0.5)',
+          flexShrink: 0,
+        }}
+      >
+        <span style={{ display: 'flex', gap: 5 }}>
+          {TRAFFIC_LIGHTS.map((color) => (
+            <span
+              key={color}
+              style={{
+                width: 9,
+                height: 9,
+                borderRadius: '50%',
+                background: color,
+              }}
+            />
+          ))}
+        </span>
+        <span
+          className="mono"
+          style={{
+            fontSize: 11,
+            color: 'hsl(var(--ink-4))',
+            marginLeft: 6,
+            padding: '3px 10px',
+            background: 'hsl(var(--paper-sunk))',
+            borderRadius: 6,
+            flex: 1,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {url}
+        </span>
+        {onReload ? (
+          <button
+            type="button"
+            onClick={onReload}
+            aria-label="Reload preview"
+            style={{
+              display: 'inline-flex',
+              color: 'hsl(var(--ink-4))',
+              padding: 2,
+              borderRadius: 5,
+            }}
+          >
+            <RotateCw size={13} />
+          </button>
+        ) : (
+          <RotateCw size={13} style={{ color: 'hsl(var(--ink-4))' }} />
+        )}
+      </div>
+      <div
+        style={{
+          flex: 1,
+          minHeight: 0,
+          background: 'hsl(var(--paper-elev))',
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/vista/GenericCatalogueSurface.tsx

@@ -0,0 +1,177 @@
+/**
+ * Generic schema-driven Vista surface — layer 2 of the three-layer
+ * zero-maintenance guarantee (own renderer > THIS > safe fallback card).
+ *
+ * Renders a biome-contributed surface kind that has NO dedicated frontend
+ * renderer yet: the catalogue `displayName` over a labelled key/value view of
+ * the payload, ORDERED and LABELLED from the kind's catalogue `payloadSchema`
+ * (an opaque JSON Schema the kernel passes through verbatim).
+ *
+ * The projection is a pure, total function of `(payloadSchema, payload)`:
+ *   • when the schema declares an object `properties` map, the declared keys
+ *     are shown FIRST, in declaration order, labelled by each property's
+ *     `title` (falling back to the key) and annotated with its `description`;
+ *   • any payload key the schema did not declare is appended after them, so a
+ *     payload is NEVER silently truncated by a stale schema;
+ *   • a schema with no usable `properties` map degrades to plain
+ *     `Object.entries(payload)` — the same view the ChatWidget generic renderer
+ *     has always given.
+ *
+ * A biome that ships its OWN renderer overrides this: the catalogue sync only
+ * registers here where no renderer exists.
+ */
+import { type ReactElement } from 'react';
+
+/** One resolved row: the label to show, and the payload key to read. */
+interface GenericSurfaceField {
+  readonly key: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null || value === undefined) return '—';
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' && value !== null && !Array.isArray(value)
+  );
+}
+
+/**
+ * Ordered, labelled fields for a payload, derived from the kind's JSON Schema.
+ * Schema-declared keys first (declaration order), then any undeclared payload
+ * key. Total: never throws, never drops a payload key.
+ */
+export function deriveGenericSurfaceFields(
+  payloadSchema: Record<string, unknown>,
+  payload: unknown,
+): readonly GenericSurfaceField[] {
+  const payloadKeys = isPlainObject(payload) ? Object.keys(payload) : [];
+  const properties = payloadSchema['properties'];
+  if (!isPlainObject(properties)) {
+    return payloadKeys.map((key) => ({ key, label: key }));
+  }
+  const declared: GenericSurfaceField[] = [];
+  for (const [key, raw] of Object.entries(properties)) {
+    const spec = isPlainObject(raw) ? raw : {};
+    const title = spec['title'];
+    const description = spec['description'];
+    declared.push({
+      key,
+      label: typeof title === 'string' && title.length > 0 ? title : key,
+      ...(typeof description === 'string' && description.length > 0
+        ? { description }
+        : {}),
+    });
+  }
+  const declaredKeys = new Set(declared.map((field) => field.key));
+  const extra = payloadKeys
+    .filter((key) => !declaredKeys.has(key))
+    .map((key) => ({ key, label: key }));
+  return [...declared, ...extra];
+}
+
+function readValue(payload: unknown, key: string): unknown {
+  return isPlainObject(payload) ? payload[key] : payload;
+}
+
+function renderGenericSurface({
+  displayName,
+  payloadSchema,
+  payload,
+}: Readonly<{
+  displayName: string;
+  payloadSchema: Record<string, unknown>;
+  payload: unknown;
+}>): ReactElement {
+  const fields = deriveGenericSurfaceFields(payloadSchema, payload);
+  const rows: readonly GenericSurfaceField[] =
+    fields.length > 0 ? fields : [{ key: 'value', label: 'value' }];
+  return (
+    <div
+      style={{
+        margin: 9,
+        border: '1px solid hsl(var(--rule))',
+        borderRadius: 9,
+        overflow: 'hidden',
+        background: 'hsl(var(--paper-elev))',
+      }}
+    >
+      <div
+        style={{
+          padding: '7px 11px',
+          borderBottom: '1px solid hsl(var(--rule))',
+          background: 'hsl(var(--muted))',
+          color: 'hsl(var(--ink-3))',
+          fontSize: 12,
+          fontWeight: 600,
+        }}
+      >
+        {displayName}
+      </div>
+      <div style={{ padding: '4px 0' }}>
+        {rows.map((field) => (
+          <div
+            key={field.key}
+            style={{
+              display: 'flex',
+              gap: 11,
+              padding: '4px 11px',
+              fontSize: 12.5,
+            }}
+          >
+            <span style={{ color: 'hsl(var(--ink-4))', minWidth: 128 }}>
+              {field.label}
+              {field.description !== undefined && (
+                <span
+                  style={{
+                    display: 'block',
+                    fontSize: 11,
+                    color: 'hsl(var(--ink-5, var(--ink-4)))',
+                  }}
+                >
+                  {field.description}
+                </span>
+              )}
+            </span>
+            <span
+              style={{ color: 'hsl(var(--ink-2))', wordBreak: 'break-word' }}
+            >
+              {stringify(
+                field.key === 'value' && !isPlainObject(payload)
+                  ? payload
+                  : readValue(payload, field.key),
+              )}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Build a renderer bound to a catalogue entry's `displayName` + `payloadSchema`
+ * for a biome surface kind with no dedicated frontend renderer.
+ */
+export function makeGenericSurfaceRenderer(
+  displayName: string,
+  payloadSchema: Record<string, unknown>,
+): (payload: unknown) => ReactElement {
+  // `renderGenericSurface` is a pure presentational function (no hooks); call
+  // it directly so the renderer is a plain element factory, not a nested
+  // component definition.
+  return (payload: unknown) =>
+    renderGenericSurface({ displayName, payloadSchema, payload });
+}

package/src/vista/SurfaceFallbackCard.tsx

@@ -0,0 +1,109 @@
+/**
+ * Safe fallback card for the Vista surface registry — layer 3 of the
+ * three-layer zero-maintenance guarantee (own renderer > generic schema-driven
+ * renderer > this).
+ *
+ * Rendered for an unknown kind, an unparseable payload, or a payload version
+ * newer than the host supports. It NEVER throws and NEVER blanks — it states
+ * what happened and discloses the raw payload, so a biome shipping a
+ * not-yet-known surface degrades VISIBLY instead of silently. The fallback is
+ * itself part of the contract, not an error path.
+ */
+import { AlertTriangle, ChevronDown, ChevronRight } from 'lucide-react';
+import { useState, type ReactElement } from 'react';
+
+import { ContributionFallbackReason } from '../lib/contribution-registry';
+
+const REASON_LABEL: Record<ContributionFallbackReason, string> = {
+  [ContributionFallbackReason.UnknownKind]:
+    "This view isn't available in your client.",
+  [ContributionFallbackReason.InvalidPayload]:
+    "This view couldn't be displayed (its data didn't match the expected shape).",
+  [ContributionFallbackReason.UnsupportedVersion]:
+    'This view needs a newer client — refresh to see it.',
+};
+
+export function SurfaceFallbackCard({
+  kind,
+  reason,
+  payload,
+  title,
+}: Readonly<{
+  kind: string;
+  reason: ContributionFallbackReason;
+  payload: unknown;
+  /** The tab title, when the envelope carried one. */
+  title?: string;
+}>): ReactElement {
+  const [open, setOpen] = useState(false);
+  let raw: string;
+  try {
+    raw = JSON.stringify(payload, null, 2);
+  } catch {
+    raw = String(payload);
+  }
+  return (
+    <div
+      style={{
+        margin: 9,
+        border: '1px solid hsl(var(--rule))',
+        borderRadius: 9,
+        background: 'hsl(var(--paper-elev))',
+        overflow: 'hidden',
+      }}
+    >
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 9,
+          width: '100%',
+          padding: '9px 11px',
+          textAlign: 'left',
+          cursor: 'pointer',
+        }}
+      >
+        <AlertTriangle
+          size={14}
+          style={{ color: 'hsl(var(--warning))', flexShrink: 0 }}
+        />
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <div
+            style={{ fontSize: 12.5, fontWeight: 600, color: 'hsl(var(--ink-2))' }}
+          >
+            {title ?? 'Unsupported view'}
+          </div>
+          <div style={{ fontSize: 11.5, color: 'hsl(var(--ink-4))', marginTop: 1 }}>
+            {REASON_LABEL[reason]}
+          </div>
+        </div>
+        <span
+          className="mono"
+          style={{ fontSize: 10.5, color: 'hsl(var(--ink-4))', flexShrink: 0 }}
+        >
+          {kind}
+        </span>
+        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
+      </button>
+      {open && (
+        <pre
+          className="mono"
+          style={{
+            margin: 0,
+            padding: '8px 11px',
+            borderTop: '1px solid hsl(var(--rule))',
+            fontSize: 11,
+            lineHeight: 1.55,
+            color: 'hsl(var(--ink-3))',
+            whiteSpace: 'pre-wrap',
+            overflowX: 'auto',
+          }}
+        >
+          {raw}
+        </pre>
+      )}
+    </div>
+  );
+}