@xemahq/ui-kernel 0.8.0 → 0.9.1

package/src/vista/surfaces/FilesSurface.tsx

@@ -0,0 +1,268 @@
+/**
+ * `SurfaceKind.Files` — the grouped file browser, and the pinned first tab of
+ * every file-backed Vista panel.
+ *
+ * Moved out of the thin session workspace (`WorkspaceFileBrowser` +
+ * `workspace-model`'s grouping/extension helpers) so the Design-System-Builder
+ * file tab, the session workspace, and any agent-opened `files` surface draw the
+ * SAME browser. Grouped by folder with a caption header; each row is a
+ * colour-coded extension tile + filename + change badges. Clicking a row opens
+ * the file as its own tab through {@link useVistaOpen}.
+ */
+import { ChevronRight, Folder } from 'lucide-react';
+
+
+import { fileSurface } from '../vista-model';
+import { useVistaOpen } from '../vista-open-context';
+
+import type { VistaFileEntry, VistaFilesPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+/** Extension → colour-coded tile metadata. */
+interface FileExtMeta {
+  readonly color: string;
+  readonly tag: string;
+}
+
+const EXT_META: Readonly<Record<string, FileExtMeta>> = {
+  ts: { color: 'hsl(var(--info))', tag: 'TS' },
+  tsx: { color: 'hsl(var(--info))', tag: 'TSX' },
+  js: { color: 'hsl(var(--warning))', tag: 'JS' },
+  jsx: { color: 'hsl(var(--warning))', tag: 'JSX' },
+  json: { color: 'hsl(var(--ink-3))', tag: 'JSON' },
+  md: { color: 'hsl(var(--p-people))', tag: 'MD' },
+  css: { color: 'hsl(var(--p-sales))', tag: 'CSS' },
+  html: { color: 'hsl(var(--p-sales))', tag: 'HTML' },
+  yaml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+  yml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+};
+
+/** Resolve the colour-coded tile metadata for a filename. */
+export function fileExtMeta(name: string): FileExtMeta {
+  if (/\.test\.[tj]sx?$/.test(name) || /\.spec\.[tj]sx?$/.test(name)) {
+    return { color: 'hsl(var(--success))', tag: 'TEST' };
+  }
+  const ext = name.split('.').pop() ?? '';
+  return (
+    EXT_META[ext] ?? {
+      color: 'hsl(var(--ink-4))',
+      tag: (ext || 'FILE').toUpperCase().slice(0, 4),
+    }
+  );
+}
+
+/** A group of files under one folder caption. */
+export interface VistaFileGroup {
+  /** Folder path (`''` = root). */
+  readonly dir: string;
+  readonly files: readonly VistaFileEntry[];
+}
+
+/** Order folder captions: root first, then alphabetical. */
+function compareDirs(a: string, b: string): number {
+  if (a === '') return -1;
+  if (b === '') return 1;
+  return a.localeCompare(b);
+}
+
+/** Group a flat file list by folder, root group first, paths sorted. */
+export function groupFilesByFolder(
+  files: readonly VistaFileEntry[],
+): VistaFileGroup[] {
+  const groups = new Map<string, VistaFileEntry[]>();
+  for (const file of files) {
+    const slash = file.path.lastIndexOf('/');
+    const dir = slash < 0 ? '' : file.path.slice(0, slash);
+    const bucket = groups.get(dir);
+    if (bucket) bucket.push(file);
+    else groups.set(dir, [file]);
+  }
+  return [...groups.keys()].sort(compareDirs).map((dir) => ({
+    dir,
+    files: [...(groups.get(dir) ?? [])].sort((a, b) =>
+      a.path.localeCompare(b.path),
+    ),
+  }));
+}
+
+export function FilesSurface({
+  files,
+}: Readonly<VistaFilesPayload>): ReactElement {
+  const open = useVistaOpen();
+  const groups = groupFilesByFolder(files);
+  if (groups.length === 0) {
+    return (
+      <div
+        style={{
+          height: '100%',
+          display: 'grid',
+          placeItems: 'center',
+          fontSize: 12.5,
+          color: 'hsl(var(--ink-4))',
+        }}
+      >
+        No files in the workspace yet.
+      </div>
+    );
+  }
+  return (
+    <div style={{ height: '100%', overflowY: 'auto', padding: '14px 12px' }}>
+      {groups.map((group) => (
+        <section key={group.dir || 'root'} style={{ marginBottom: 16 }}>
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 6,
+              padding: '0 8px 8px',
+            }}
+          >
+            <Folder size={12} style={{ color: 'hsl(var(--ink-4))' }} />
+            <span
+              className="cap"
+              style={{ fontSize: 9.5, letterSpacing: '0.07em' }}
+            >
+              {group.dir ? group.dir.replaceAll('/', ' / ') : 'Root'}
+            </span>
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+            {group.files.map((file) => (
+              <FileRow
+                key={file.path}
+                file={file}
+                onOpen={
+                  open === null
+                    ? null
+                    : () => {
+                        open(fileSurface(file.path));
+                      }
+                }
+              />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+function FileRow({
+  file,
+  onOpen,
+}: Readonly<{
+  file: VistaFileEntry;
+  onOpen: (() => void) | null;
+}>): ReactElement {
+  const name = file.path.split('/').pop() ?? file.path;
+  const meta = fileExtMeta(name);
+  const changed = file.add !== undefined || file.del !== undefined;
+  const body = (
+    <>
+      <span
+        style={{
+          width: 28,
+          height: 28,
+          borderRadius: 8,
+          flexShrink: 0,
+          display: 'grid',
+          placeItems: 'center',
+          background: `color-mix(in oklch, ${meta.color} 13%, transparent)`,
+          border: `1px solid color-mix(in oklch, ${meta.color} 26%, transparent)`,
+        }}
+      >
+        <span
+          className="mono"
+          style={{
+            fontSize: 8,
+            fontWeight: 700,
+            color: meta.color,
+            letterSpacing: '0.02em',
+          }}
+        >
+          {meta.tag}
+        </span>
+      </span>
+      <span style={{ flex: 1, minWidth: 0 }}>
+        <span
+          style={{
+            display: 'block',
+            fontSize: 13,
+            fontWeight: 500,
+            color: 'hsl(var(--ink))',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {name}
+        </span>
+        {changed && (
+          <span
+            className="mono"
+            style={{ fontSize: 10, color: 'hsl(var(--ink-4))' }}
+          >
+            changed
+          </span>
+        )}
+      </span>
+      {changed && (
+        <span style={{ display: 'inline-flex', gap: 6, flexShrink: 0 }}>
+          {file.add !== undefined && file.add > 0 && (
+            <span
+              className="mono"
+              style={{ fontSize: 10.5, color: 'hsl(var(--success))' }}
+            >
+              +{file.add}
+            </span>
+          )}
+          {file.del !== undefined && file.del > 0 && (
+            <span
+              className="mono"
+              style={{
+                fontSize: 10.5,
+                color: 'hsl(var(--destructive, var(--danger)))',
+              }}
+            >
+              −{file.del}
+            </span>
+          )}
+        </span>
+      )}
+      {onOpen !== null && (
+        <ChevronRight
+          size={13}
+          style={{ color: 'hsl(var(--ink-4))', flexShrink: 0, opacity: 0.6 }}
+        />
+      )}
+    </>
+  );
+
+  const rowStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 11,
+    width: '100%',
+    padding: '8px 9px',
+    borderRadius: 9,
+    textAlign: 'left',
+  } as const;
+
+  if (onOpen === null) {
+    return <div style={rowStyle}>{body}</div>;
+  }
+  return (
+    <button
+      type="button"
+      onClick={onOpen}
+      style={{ ...rowStyle, transition: 'background 140ms ease' }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.background = 'hsl(var(--paper-elev))';
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.background = 'transparent';
+      }}
+    >
+      {body}
+    </button>
+  );
+}

package/src/vista/surfaces/FormSurface.tsx

@@ -0,0 +1,264 @@
+/**
+ * `SurfaceKind.Form` — the secure-elicitation surface (Canopy §8.4).
+ *
+ * The agent asks for a credential it must never see. This surface renders the
+ * connector's ONBOARDING form (or, for `oauth2` / `app_install`, the consent
+ * link), captures the values in local state, and POSTs them BROWSER → OWNING
+ * SERVICE with the SUBJECT's own JWT. The agent learns only
+ * `{ submitted, ref }`.
+ *
+ * ── What makes the value unreachable from the agent ─────────────────────────
+ *   • the only outbound channel is `host.onOutcome(VistaFormOutcome)`, whose
+ *     type has three scalar members and no place a value could be assigned;
+ *   • the values live in this component's `useState`; the single reader is
+ *     `submitElicitationFields`, which takes them as a parameter and returns an
+ *     outcome — the values are not reachable from any return or any throw;
+ *   • the POST target is an ABSOLUTE service URL (`validateFormPayload` rejects
+ *     a relative one), so the request cannot be aimed at the host's own BFF or
+ *     the chat transport;
+ *   • secret fields are DECLARED (`spec.isSecret`) and render write-only; the
+ *     surface holds no cache and no read path repopulates them.
+ *
+ * Nothing here is provider-aware. Whether the flow is a field form or an OAuth
+ * handoff is decided by the payload the owning service produced.
+ */
+import { AlertTriangle, CheckCircle2, ExternalLink, Loader2, ShieldCheck } from 'lucide-react';
+import { useCallback, useEffect, useState, type ReactElement, type ReactNode } from 'react';
+
+import { readElicitationStatus, submitElicitationFields, VistaFormSubmitError } from './elicitation-transport';
+import { SchemaForm } from '../../ui/capture/schema-form';
+import { captureValuesToStringMap } from '../../ui/capture/submit-values';
+import { useSchemaValidation } from '../../ui/capture/use-schema-validation';
+import { cn } from '../../ui/cn';
+import { Button } from '../../ui/primitives/button';
+import { useVistaFormHost, type VistaFormOutcome } from '../vista-form-host';
+
+import type { CaptureValues } from '../../ui/capture/field-spec';
+import type { VistaFormPayload } from '../vista-payloads';
+
+/** Explicit lifecycle. No implicit "maybe submitted" state. */
+enum FormPhase {
+  Editing = 'editing',
+  Working = 'working',
+  Settled = 'settled',
+}
+
+export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
+  const host = useVistaFormHost();
+  const [values, setValues] = useState<CaptureValues>({});
+  const [phase, setPhase] = useState<FormPhase>(FormPhase.Editing);
+  const [serviceError, setServiceError] = useState<string | null>(null);
+  const [showFieldErrors, setShowFieldErrors] = useState(false);
+  const [outcome, setOutcome] = useState<VistaFormOutcome | null>(null);
+  const { errors, isValid } = useSchemaValidation(payload.fields, values);
+
+  const settle = useCallback(
+    (next: VistaFormOutcome): void => {
+      // The values are dropped the moment the elicitation settles: nothing in
+      // this component may outlive the submission holding secret material.
+      setValues({});
+      setOutcome(next);
+      setPhase(FormPhase.Settled);
+      host?.onOutcome(next);
+    },
+    [host],
+  );
+
+  const failed = useCallback((error: unknown): void => {
+    setServiceError(
+      error instanceof VistaFormSubmitError || error instanceof Error
+        ? error.message
+        : 'The submission could not be completed.',
+    );
+    setPhase(FormPhase.Editing);
+  }, []);
+
+  const handleSubmit = useCallback((): void => {
+    if (host === null) return;
+    setShowFieldErrors(true);
+    if (!isValid) return;
+    setServiceError(null);
+    setPhase(FormPhase.Working);
+    // The values object is a PARAMETER here and nowhere else. It is never
+    // returned, logged, or handed to a callback.
+    void host
+      .getAccessToken()
+      .then((accessToken) =>
+        submitElicitationFields({
+          submitUrl: payload.submitUrl,
+          ref: payload.ref,
+          accessToken,
+          fields: captureValuesToStringMap(payload.fields, values),
+        }),
+      )
+      .then(settle, failed);
+  }, [host, isValid, payload.fields, payload.ref, payload.submitUrl, settle, failed, values]);
+
+  const handleCheckStatus = useCallback((): void => {
+    if (host === null) return;
+    setServiceError(null);
+    setPhase(FormPhase.Working);
+    void host
+      .getAccessToken()
+      .then((accessToken) =>
+        readElicitationStatus({ statusUrl: payload.statusUrl, ref: payload.ref, accessToken }),
+      )
+      .then((next) => {
+        if (next === null) {
+          setServiceError('Not completed yet — finish the steps in the other window, then check again.');
+          setPhase(FormPhase.Editing);
+          return;
+        }
+        settle(next);
+      }, failed);
+  }, [host, payload.ref, payload.statusUrl, settle, failed]);
+
+  // The consent/install window is a separate browsing context, so the only
+  // signal this tab gets is the user returning to it. Re-checking on focus is
+  // an event, not a timer — there is no polling loop and no timeout.
+  const isLaunch = payload.launch !== undefined;
+  useEffect(() => {
+    if (!isLaunch || phase === FormPhase.Settled || host === null) return;
+    const onFocus = (): void => handleCheckStatus();
+    globalThis.addEventListener?.('focus', onFocus);
+    return () => globalThis.removeEventListener?.('focus', onFocus);
+    // `handleCheckStatus` is stable per (host, payload) and re-subscribing on a
+    // phase change is intended: a settled surface stops listening.
+  }, [isLaunch, phase, host, handleCheckStatus]);
+
+  if (host === null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <Notice tone="error" title="This form cannot be submitted here">
+          No form host is mounted for this panel, so there is no way to sign the
+          request as you. Open the request from a surface that provides one.
+        </Notice>
+      </Shell>
+    );
+  }
+
+  if (phase === FormPhase.Settled && outcome !== null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <div className="flex items-start gap-2 rounded-md border border-rule bg-paper-elev p-3">
+          <CheckCircle2 className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+          <div className="space-y-0.5">
+            <p className="text-body-1 font-medium text-ink">Submitted.</p>
+            <p className="text-caption text-ink-3">
+              The value went straight to the service and was never shown to the
+              agent{outcome.connectionId === null ? '.' : `. Connection ${outcome.connectionId} is ready.`}
+            </p>
+          </div>
+        </div>
+      </Shell>
+    );
+  }
+
+  const working = phase === FormPhase.Working;
+
+  return (
+    <Shell heading={payload.heading} purpose={payload.purpose}>
+      {payload.launch !== undefined ? (
+        <>
+          {payload.launch.hint !== undefined && (
+            <p className="text-body-1 text-ink-3">{payload.launch.hint}</p>
+          )}
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              onClick={() => {
+                globalThis.open(payload.launch?.url, '_blank', 'noopener,noreferrer');
+              }}
+              className="gap-1.5"
+              disabled={working}
+            >
+              <ExternalLink className="h-4 w-4" />
+              {payload.launch.label}
+            </Button>
+            <Button variant="outline" onClick={handleCheckStatus} disabled={working}>
+              {working && <Loader2 className="mr-1 h-4 w-4 animate-spin" />}
+              I&apos;ve finished — check
+            </Button>
+          </div>
+        </>
+      ) : (
+        <>
+          {payload.fields.length === 0 && (
+            <Notice tone="warn" title="No form fields were declared">
+              This connector declares no onboarding form. Submitting will ask the
+              service, which is the authority on whether that is allowed.
+            </Notice>
+          )}
+          <SchemaForm
+            fields={payload.fields}
+            values={values}
+            onChange={setValues}
+            disabled={working}
+            {...(showFieldErrors ? { errors } : {})}
+          />
+          <div className="flex items-center gap-2">
+            <Button onClick={handleSubmit} disabled={working}>
+              {working && <Loader2 className="mr-1 h-4 w-4 animate-spin" />}
+              {payload.submitLabel ?? 'Submit securely'}
+            </Button>
+          </div>
+        </>
+      )}
+
+      {serviceError !== null && (
+        <Notice tone="error" title="The service rejected this">
+          {serviceError}
+        </Notice>
+      )}
+    </Shell>
+  );
+}
+
+function Shell({
+  heading,
+  purpose,
+  children,
+}: Readonly<{ heading?: string; purpose: string; children: ReactNode }>): ReactElement {
+  return (
+    <div className="h-full overflow-auto">
+      <div className="mx-auto max-w-2xl space-y-4 p-6">
+        <div className="space-y-1">
+          <h2 className="text-subtitle font-semibold text-ink">{heading ?? 'Secure request'}</h2>
+          {purpose.length > 0 && <p className="text-body-1 text-ink-2">{purpose}</p>}
+          <p className="flex items-center gap-1.5 text-caption text-ink-3">
+            <ShieldCheck className="h-3.5 w-3.5" />
+            Sent straight to the service with your own sign-in. The agent never sees what you type.
+          </p>
+        </div>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+function Notice({
+  tone,
+  title,
+  children,
+}: Readonly<{ tone: 'error' | 'warn'; title: string; children: ReactNode }>): ReactElement {
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'flex items-start gap-2 rounded-md border p-3',
+        tone === 'error' ? 'border-destructive/40 bg-destructive/10' : 'border-rule bg-paper-elev',
+      )}
+    >
+      <AlertTriangle
+        className={cn('mt-0.5 h-4 w-4 shrink-0', tone === 'error' ? 'text-destructive' : 'text-ink-3')}
+      />
+      <div className="space-y-0.5">
+        <p className={cn('text-body-1 font-medium', tone === 'error' ? 'text-destructive' : 'text-ink')}>
+          {title}
+        </p>
+        <p className={cn('text-body-1', tone === 'error' ? 'text-destructive/90' : 'text-ink-3')}>
+          {children}
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/vista/surfaces/HtmlSurface.tsx

@@ -0,0 +1,43 @@
+/**
+ * `SurfaceKind.Html` — the "render anything, safely" surface.
+ *
+ * It draws through the promoted {@link CustomUiFrame}: an opaque-origin,
+ * `allow-scripts`-only sandbox iframe with a `<meta>` CSP of
+ * `default-src 'none'; script-src <pinned>; style-src 'unsafe-inline';
+ * base-uri 'none'; form-action 'none'`.
+ *
+ * Two forms, one frame:
+ *   • `{ document }` — untrusted, agent-authored HTML. `script-src 'none'`, and
+ *     the frame is mounted with {@link NO_CUSTOM_UI_INTENTS}: it can render, and
+ *     it can do NOTHING else. This is what an agent's `html` tab uses.
+ *   • `{ compiledOutput, integrity }` — a server-compiled, SRI-pinned chunk.
+ *     `script-src '<sha384-…>'` executes exactly those bytes and nothing else.
+ *
+ * A surface that wants intents (App Forge's runtime views) mounts
+ * `CustomUiFrame` directly with its own closed set; the generic `html` TAB
+ * deliberately grants none — an agent-authored document must not be able to
+ * drive the host.
+ */
+
+import { NO_CUSTOM_UI_INTENTS } from '../html/custom-ui-intents';
+import { CustomUiFrame } from '../html/CustomUiFrame';
+
+import type { VistaHtmlPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+export function HtmlSurface(payload: VistaHtmlPayload): ReactElement {
+  const content =
+    'document' in payload
+      ? { document: payload.document }
+      : { compiledOutput: payload.compiledOutput, integrity: payload.integrity };
+  const styleCss = 'document' in payload ? undefined : payload.styleCss;
+  return (
+    <CustomUiFrame
+      content={content}
+      intents={NO_CUSTOM_UI_INTENTS}
+      title="Rendered view"
+      className="h-full p-2"
+      {...(styleCss === undefined ? {} : { styleCss })}
+    />
+  );
+}

package/src/vista/surfaces/TableSurface.tsx

@@ -0,0 +1,99 @@
+/**
+ * `SurfaceKind.Table` — generic columns + rows, the universal "show me
+ * structured records" surface.
+ *
+ * Presentation only: no sorting model, no paging, no cell semantics. A cell
+ * value that is not a primitive is JSON-serialised rather than dropped, so a
+ * nested value is visible instead of silently blank.
+ */
+import type { VistaTablePayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+
+function cellText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+export function TableSurface({
+  columns,
+  rows,
+}: Readonly<VistaTablePayload>): ReactElement {
+  return (
+    <div style={{ height: '100%', overflow: 'auto' }}>
+      <table
+        style={{
+          width: '100%',
+          borderCollapse: 'collapse',
+          fontSize: 12.5,
+        }}
+      >
+        <thead>
+          <tr>
+            {columns.map((column) => (
+              <th
+                key={column}
+                style={{
+                  position: 'sticky',
+                  top: 0,
+                  textAlign: 'left',
+                  padding: '8px 12px',
+                  background: 'hsl(var(--paper-elev))',
+                  borderBottom: '1px solid hsl(var(--rule))',
+                  color: 'hsl(var(--ink-3))',
+                  fontWeight: 600,
+                  whiteSpace: 'nowrap',
+                }}
+              >
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, rowIndex) => (
+            <tr
+              // Rows carry no identity in the generic contract; position is the
+              // only stable key available.
+               
+              key={rowIndex}
+            >
+              {columns.map((column, columnIndex) => (
+                <td
+                  key={column}
+                  style={{
+                    padding: '7px 12px',
+                    borderBottom: '1px solid hsl(var(--rule) / 0.6)',
+                    color: 'hsl(var(--ink-2))',
+                    verticalAlign: 'top',
+                  }}
+                >
+                  {cellText(row[columnIndex])}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      {rows.length === 0 && (
+        <div
+          style={{
+            padding: 24,
+            textAlign: 'center',
+            fontSize: 12.5,
+            color: 'hsl(var(--ink-4))',
+          }}
+        >
+          No rows.
+        </div>
+      )}
+    </div>
+  );
+}