@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/vista/GenericCatalogueSurface.tsx

@@ -1,179 +0,0 @@
-/**
- * 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

@@ -1,109 +0,0 @@
-/**
- * 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>
-  );
-}

package/src/vista/VistaPanel.tsx

@@ -1,163 +0,0 @@
-/**
- * `VistaPanel` — the ONE tabbed render plane.
- *
- * It replaces the three hand-rolled tab strips the frontend carried (the thin
- * session workspace, the Design-System-Builder preview, and App Forge's
- * preview): tab chrome is {@link OverflowTabs} (auto-collapsing "More…" instead
- * of a horizontal-scroll strip, active + pinned always visible), tab STATE is
- * {@link useVistaTabs}, and the body is whatever the Vista surface registry
- * resolves the active {@link VistaTab} to.
- *
- * The panel is presentation only: it never fetches, never authorises, and never
- * decides what a kind means. Resolution follows the three-layer guarantee —
- * a registered renderer wins, else the generic schema-driven renderer the
- * catalogue sync installed, else {@link SurfaceFallbackCard} with a typed
- * reason. It never throws and never blanks.
- */
-import { type ReactElement, type ReactNode } from 'react';
-
-import { surfaceKindIcon } from './surface-icons';
-import { vistaSurfaceRegistry } from './surface-registry';
-import { SurfaceFallbackCard } from './SurfaceFallbackCard';
-import { cn } from '../ui/cn';
-import { OverflowTabs, type OverflowTab } from '../ui/primitives/overflow-tabs';
-
-import type { VistaTab } from './vista-model';
-
-export interface VistaPanelProps {
-  /** Every open tab, in display order (pinned first). */
-  readonly tabs: readonly VistaTab[];
-  /** The focused tab, or `null` when the panel holds no tabs. */
-  readonly activeTabId: string | null;
-  readonly onActivate: (tabId: string) => void;
-  /**
-   * Close handler. Omit for a panel whose tabs are all host-owned; pinned tabs
-   * never render a close affordance regardless.
-   */
-  readonly onClose?: (tabId: string) => void;
-  /** Optional action rendered at the right edge of the tab bar. */
-  readonly tabBarAction?: ReactNode;
-  /**
-   * Tab ids to mark with the strip's attention dot — "this tab changed while
-   * you were looking elsewhere". The panel does not decide what "changed"
-   * means; the owner does.
-   */
-  readonly indicatorTabIds?: readonly string[];
-  /** Rendered when there are no tabs at all. */
-  readonly emptyState?: ReactNode;
-  readonly className?: string;
-}
-
-export function VistaPanel({
-  tabs,
-  activeTabId,
-  onActivate,
-  onClose,
-  tabBarAction,
-  indicatorTabIds,
-  emptyState,
-  className,
-}: VistaPanelProps): ReactElement {
-  const active = tabs.find((t) => t.tabId === activeTabId) ?? null;
-  return (
-    <div
-      className={cn(
-        'flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden',
-        className,
-      )}
-    >
-      <VistaTabBar
-        tabs={tabs}
-        activeTabId={activeTabId}
-        onActivate={onActivate}
-        {...(onClose ? { onClose } : {})}
-        {...(tabBarAction === undefined ? {} : { tabBarAction })}
-        {...(indicatorTabIds === undefined ? {} : { indicatorTabIds })}
-      />
-      <div className="min-h-0 flex-1 overflow-hidden">
-        {active === null ? (
-          <>{emptyState ?? null}</>
-        ) : (
-          <VistaSurfaceBody tab={active} />
-        )}
-      </div>
-    </div>
-  );
-}
-
-export type VistaTabBarProps = Omit<
-  VistaPanelProps,
-  'emptyState' | 'className'
-> & { readonly className?: string };
-
-/**
- * The tab STRIP alone. Exported so a surface whose chrome interleaves other
- * controls between the tabs and the body (the Design-System-Builder's browser
- * chrome puts a URL + action row there) composes the SAME strip instead of
- * hand-rolling a second one. `VistaPanel` is just this plus
- * {@link VistaSurfaceBody}.
- */
-export function VistaTabBar({
-  tabs,
-  activeTabId,
-  onActivate,
-  onClose,
-  tabBarAction,
-  indicatorTabIds,
-  className,
-}: VistaTabBarProps): ReactElement {
-  const overflowTabs: OverflowTab[] = tabs.map((tab) => {
-    const entry: {
-      value: string;
-      label: string;
-      pinned?: boolean;
-      indicator?: boolean;
-      icon?: OverflowTab['icon'];
-    } = { value: tab.tabId, label: tab.title };
-    if (tab.pinned === true) {
-      entry.pinned = true;
-    }
-    if (indicatorTabIds?.includes(tab.tabId) === true) {
-      entry.indicator = true;
-    }
-    const icon = surfaceKindIcon(tab.kind);
-    if (icon !== undefined) {
-      entry.icon = icon;
-    }
-    return entry;
-  });
-  return (
-    <div className={cn('flex shrink-0 items-end gap-2 px-2', className)}>
-      <div className="min-w-0 flex-1">
-        <OverflowTabs
-          tabs={overflowTabs}
-          value={activeTabId ?? ''}
-          onChange={onActivate}
-          {...(onClose ? { onClose } : {})}
-        />
-      </div>
-      {tabBarAction}
-    </div>
-  );
-}
-
-/**
- * Resolve ONE tab through the registry and draw it. Split out so the resolution
- * decision (and therefore the fallback reason) is inspectable in isolation.
- */
-export function VistaSurfaceBody({
-  tab,
-}: Readonly<{ tab: VistaTab }>): ReactElement {
-  const resolution = vistaSurfaceRegistry.resolve(tab);
-  if (resolution.matched) {
-    return resolution.rendered;
-  }
-  return (
-    <SurfaceFallbackCard
-      kind={resolution.kind}
-      reason={resolution.reason}
-      payload={tab.payload}
-      title={tab.title}
-    />
-  );
-}

package/src/vista/form-payload.spec.ts

@@ -1,139 +0,0 @@
-/**
- * Guards `validateFormPayload` — the structural half of "the value never
- * reaches the agent".
- *
- * The payload has no network authority: it carries only a base64url opaque ref,
- * while the trusted service base URL comes from `VistaFormHost`.
- */
-import { describe, expect, it } from 'vitest';
-
-import { validateFormPayload } from './vista-payloads';
-import { CaptureFieldType } from '../ui/capture/field-spec';
-
-const BASE = {
-  ref: 'ref-1',
-  purpose: 'Connect Acme so I can read your tickets.',
-  fields: [
-    {
-      key: 'apiKey',
-      label: 'API key',
-      type: CaptureFieldType.String,
-      required: true,
-      isSecret: true,
-      transform: 'trim',
-    },
-    {
-      key: 'baseUrl',
-      label: 'Base URL',
-      type: CaptureFieldType.Url,
-      required: true,
-      isSecret: false,
-    },
-  ],
-};
-
-describe('validateFormPayload', () => {
-  it('accepts a well-formed field-mode payload and preserves declared secrecy', () => {
-    const payload = validateFormPayload(BASE);
-    expect(payload).not.toBeNull();
-    expect(payload?.fields).toHaveLength(2);
-    expect(payload?.fields[0]?.isSecret).toBe(true);
-    expect(payload?.fields[1]?.isSecret).toBe(false);
-    expect(payload?.fields[0]?.transform).toBe('trim');
-  });
-
-  it('rejects old or malicious payload-selected submit/status authorities', () => {
-    for (const target of [
-      'https://evil.example/steal',
-      'https://trusted.example@evil.example/steal',
-      '//evil.example/steal',
-      '/credential-elicitations/ref-1/submit',
-      'javascript:alert(1)',
-    ]) {
-      expect(validateFormPayload({ ...BASE, submitUrl: target })).toBeNull();
-      expect(validateFormPayload({ ...BASE, statusUrl: target })).toBeNull();
-    }
-  });
-
-  it('accepts an EMPTY field schema — the service is the authority, not the client', () => {
-    const payload = validateFormPayload({ ...BASE, fields: [] });
-    expect(payload).not.toBeNull();
-    expect(payload?.fields).toEqual([]);
-  });
-
-  it('rejects a malformed field spec rather than half-rendering it', () => {
-    expect(
-      validateFormPayload({
-        ...BASE,
-        fields: [{ key: 'a', label: 'A', type: 'nope' }],
-      }),
-    ).toBeNull();
-    expect(
-      validateFormPayload({ ...BASE, fields: [{ key: 'a', label: 'A' }] }),
-    ).toBeNull();
-    expect(
-      validateFormPayload({
-        ...BASE,
-        fields: [
-          {
-            key: 'a',
-            label: 'A',
-            type: CaptureFieldType.String,
-            isSecret: 'yes',
-          },
-        ],
-      }),
-    ).toBeNull();
-    expect(validateFormPayload({ ...BASE, fields: {} })).toBeNull();
-  });
-
-  it('accepts a launch payload with a root-relative trusted-service path', () => {
-    const payload = validateFormPayload({
-      ...BASE,
-      fields: [],
-      launch: {
-        path: '/oauth/authorize?x=1',
-        label: 'Continue to Acme',
-        hint: 'h',
-      },
-    });
-    expect(payload?.launch).toEqual({
-      path: '/oauth/authorize?x=1',
-      label: 'Continue to Acme',
-      hint: 'h',
-    });
-  });
-
-  it('rejects launch authority/scheme confusion and malformed paths', () => {
-    for (const path of [
-      'authorize',
-      '//evil.example/authorize',
-      'https://evil.example/authorize',
-      'javascript:alert(1)',
-      '\\\\evil.example\\authorize',
-    ]) {
-      expect(
-        validateFormPayload({ ...BASE, launch: { path, label: 'Go' } }),
-      ).toBeNull();
-    }
-    expect(
-      validateFormPayload({
-        ...BASE,
-        launch: { url: 'https://evil.example/a', label: 'Go' },
-      }),
-    ).toBeNull();
-    expect(
-      validateFormPayload({
-        ...BASE,
-        launch: { path: '/authorize', label: '' },
-      }),
-    ).toBeNull();
-  });
-
-  it('rejects missing refs and path-traversal/encoding input', () => {
-    for (const ref of ['', '.', '..', '../steal', 'a/b', '%2e%2e', 'réf']) {
-      expect(validateFormPayload({ ...BASE, ref })).toBeNull();
-    }
-    expect(validateFormPayload({ ...BASE, ref: undefined })).toBeNull();
-  });
-});