@xemahq/ui-kernel 0.9.0 → 0.9.2

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/preview-device-frame.tsx

@@ -181,7 +181,7 @@ function ResponsiveViewport({
     const observer = new ResizeObserver(compute);
     observer.observe(el);
     return () => observer.disconnect();
-  }, [bezel.width, bezel.height]);
+  }, [aspectRatio, bezel.width, bezel.height]);
 
   return (
     <div

package/src/ui/primitives/tag-multi-select.tsx

@@ -138,9 +138,8 @@ export function TagMultiSelect({
                   className={cn('text-body-1 gap-1 pr-1', chipClass)}
                 >
                   <span className="truncate max-w-[160px]">{opt?.label ?? val}</span>
-                  <span
-                    role="button"
-                    tabIndex={-1}
+                  <button
+                    type="button"
                     onClick={(e) => remove(val, e)}
                     onKeyDown={(e) => {
                       if (e.key === 'Enter' || e.key === ' ') {
@@ -153,7 +152,7 @@ export function TagMultiSelect({
                     aria-label={`Remove ${opt?.label ?? val}`}
                   >
                     <X className="h-4 w-4" />
-                  </span>
+                  </button>
                 </Badge>
               );
             })}

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>
+  );
+}

package/src/vista/VistaPanel.tsx

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