@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/ui/chrome/LoadingState.tsx

@@ -1,61 +0,0 @@
-import { Loader2 } from 'lucide-react';
-
-import { cn } from '../cn';
-import { Skeleton } from '../primitives/skeleton';
-
-export type LoadingStateVariant = 'spinner' | 'skeleton-list' | 'skeleton-card';
-
-interface LoadingStateProps {
-  /**
-   * `spinner` (default): centred spinner + optional label. `skeleton-list`:
-   * N skeleton rows. `skeleton-card`: a single card-shaped skeleton block.
-   */
-  variant?: LoadingStateVariant;
-  /** Accessible label / caption (spinner variant). */
-  label?: string;
-  /** Row count for `skeleton-list` (default 4). */
-  rows?: number;
-  className?: string;
-}
-
-/**
- * Canonical loading affordance shared across biomes. Replaces the per-biome
- * ad-hoc spinners and inline skeleton stacks.
- */
-export default function LoadingState({
-  variant = 'spinner',
-  label = 'Loading…',
-  rows = 4,
-  className,
-}: Readonly<LoadingStateProps>) {
-  if (variant === 'skeleton-list') {
-    return (
-      <div className={cn('space-y-3', className)} role="status" aria-label={label}>
-        {Array.from({ length: rows }).map((_, i) => (
-          <Skeleton key={i} className="h-12 w-full rounded-xl" />
-        ))}
-      </div>
-    );
-  }
-
-  if (variant === 'skeleton-card') {
-    return (
-      <div className={cn('space-y-3', className)} role="status" aria-label={label}>
-        <Skeleton className="h-40 w-full rounded-2xl" />
-        <Skeleton className="h-4 w-2/3 rounded" />
-        <Skeleton className="h-4 w-1/2 rounded" />
-      </div>
-    );
-  }
-
-  return (
-    <div
-      className={cn('flex flex-col items-center justify-center py-14 text-center', className)}
-      role="status"
-      aria-label={label}
-    >
-      <Loader2 className="h-6 w-6 animate-spin text-ink-3" />
-      {label && <p className="mt-3 text-body-2 text-ink-3">{label}</p>}
-    </div>
-  );
-}

package/src/ui/chrome/PageHeader.tsx

@@ -1,137 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── PageHeader — INVISIBLE topbar registration ──
-//
-// PageHeader does NOT render a visible header bar. It registers the page's
-// title, description, eyebrow, help-actions, status pill, count, and
-// primary action buttons into the shared page-meta store. The global
-// `AppTopbar` reads from that store and renders them in the topbar
-// (mac-style — the topbar IS the page chrome).
-//
-// Why invisible: stacking a second header row beneath the topbar wastes
-// vertical space and competes with the topbar for attention. Pages get
-// the canvas back; the topbar carries context.
-//
-// When you need a thin in-page row (filter dropdowns, search input,
-// selection-mode toolbar), use `<PageToolbar>` from this same file —
-// that's a real visible row but carries NO title (the topbar still owns
-// it), so there's no visual duplication.
-//
-// Host-agnostic: reaches the page-meta store through the kernel `HostBridge`
-// singleton (NOT a host import), so it bundles cleanly into any biome remote.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { useMemo, type ReactNode } from 'react';
-
-import { useHostBridge, type PageBackTarget } from '../../lib/biome-host';
-import { cn } from '../cn';
-
-interface PageHeaderProps {
-  readonly title: string;
-  /**
-   * Short secondary line. Renders in the topbar info popover (long-form
-   * `topbarDescription` wins for the popover if both are set) AND
-   * inline next to the title as `topbarMeta` when it's a string.
-   */
-  readonly description?: string;
-  /**
-   * Long-form text rendered ONLY in the topbar's info popover (the
-   * (i) button). Use when `description` is a counts line and you still
-   * want a richer popover blurb.
-   */
-  readonly topbarDescription?: string;
-  /** Mono caption rendered before the title in the topbar info popover. */
-  readonly eyebrow?: string;
-  /** Bullet list of "what you can do here" shown in the topbar info popover. */
-  readonly helpActions?: readonly string[];
-  /**
-   * Right-aligned topbar action cluster. Use small h-7 buttons / icon
-   * buttons. Anything that needs more space (multi-input filter rows,
-   * search inputs) belongs in a `<PageToolbar>` inside the page body
-   * — not here.
-   */
-  readonly actions?: ReactNode;
-  /**
-   * Leftmost back affordance. Renders as an icon-only button before
-   * the title in the topbar. Pages with a parent context (a detail
-   * page under a list, etc.) set this so the user can return to where
-   * they came from. See `app/page-meta.ts` for the full layout
-   * contract — back always lives on the left, never inside the page
-   * body.
-   */
-  readonly backTo?: PageBackTarget;
-}
-
-/**
- * Invisible primitive — registers page meta with the topbar. Renders
- * nothing visible. Mount once at the top of a page component.
- */
-export default function PageHeader({
-  title,
-  description,
-  topbarDescription,
-  eyebrow,
-  helpActions,
-  actions,
-  backTo,
-}: Readonly<PageHeaderProps>) {
-  // `topbarActions` is a ReactNode — wrap in useMemo so React doesn't see
-  // a new identity every render and re-notify the store needlessly. Same
-  // for the meta line.
-  const topbarActions = useMemo(() => actions, [actions]);
-  const topbarMeta = useMemo<ReactNode>(
-    () => (description ? <span>{description}</span> : null),
-    [description],
-  );
-
-  // Reach the host page-meta store through the shared bridge singleton — NOT
-  // a module-level import — so this component bundles cleanly into an MF
-  // remote and still drives the one host topbar store.
-  useHostBridge().pageMeta.usePageMeta({
-    title,
-    eyebrow,
-    description: topbarDescription ?? description,
-    actions: helpActions,
-    topbarActions,
-    topbarMeta,
-    backTo,
-  });
-  return null;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// ── PageToolbar — thin in-page row for filters / search / sub-tabs ──
-//
-// Use when the page needs a horizontal row of controls that don't fit
-// in the topbar (multi-select filter, search input, bulk-selection
-// toolbar). NEVER include the page title — that's the topbar's job.
-//
-// Default height is `h-9` to match the topbar visual rhythm without
-// looking like a duplicated header. Background is the same paper tone
-// as the page so it reads as a tool strip, not a banner.
-// ═══════════════════════════════════════════════════════════════════════════
-
-interface PageToolbarProps {
-  /** Left cluster — filters, search, etc. */
-  readonly children?: ReactNode;
-  /** Right cluster — usually `null`; the primary action lives in the topbar. */
-  readonly trailing?: ReactNode;
-  readonly className?: string;
-}
-
-export function PageToolbar({
-  children,
-  trailing,
-  className,
-}: Readonly<PageToolbarProps>) {
-  return (
-    <div
-      className={cn(
-        'flex shrink-0 items-center gap-2 border-b border-rule/50 bg-paper px-4 py-1.5 sm:px-6',
-        className,
-      )}
-    >
-      <div className="flex min-w-0 flex-1 flex-wrap items-center gap-2">{children}</div>
-      {trailing && <div className="flex shrink-0 items-center gap-1.5">{trailing}</div>}
-    </div>
-  );
-}

package/src/ui/chrome/RecordCardList.tsx

@@ -1,98 +0,0 @@
-import { cn } from '../cn';
-
-import type { ReactNode } from 'react';
-
-/**
- * One label/value row inside a record card — mirrors one table column.
- *
- * `key` exists because a card's rows are keyed by the COLUMN, and a column's
- * identity is its field key, not its user-facing label (two columns may carry
- * the same label). It defaults to `label` for the common case where the label
- * is already unique.
- */
-export interface RecordCardField {
-  readonly key?: string;
-  readonly label: string;
-  readonly value: ReactNode;
-  /**
-   * `data-*` attributes for the row element — e.g. the same hook the equivalent
-   * table cell carries, so a click-to-context resolver lands on the identical
-   * node at every viewport width. Deliberately `data-*` only: styling stays in
-   * this primitive, so a caller cannot re-open the drift it closed.
-   */
-  readonly rowAttributes?: Readonly<Record<`data-${string}`, string>>;
-}
-
-export interface RecordCardListProps<T> {
-  readonly items: readonly T[];
-  readonly getKey: (item: T) => string;
-  /** Card header rendered above the field list (title, status, row toggle). */
-  readonly renderHeader?: (item: T) => ReactNode;
-  readonly getFields: (item: T) => readonly RecordCardField[];
-  /** Row actions, rendered right-aligned below a divider. */
-  readonly renderActions?: (item: T) => ReactNode;
-  /** Free block appended after the actions (expanded detail). */
-  readonly renderDetail?: (item: T) => ReactNode;
-  /** Extra classes for the list element. */
-  readonly className?: string;
-}
-
-/**
- * Small-viewport (below `md`) layout for a record list: one stacked card per
- * record with the table's columns rendered as label/value rows, instead of a
- * horizontal-scroll-only table.
- *
- * This is the ONE definition of that card chrome — spacing, border, divider,
- * label/value alignment. Callers name their columns and their actions; they do
- * not restate the chrome. Deliberately NOT parameterised by card class: a
- * per-caller class hook is how the three copies this replaced drifted apart in
- * the first place.
- */
-export function RecordCardList<T>(props: Readonly<RecordCardListProps<T>>) {
-  const {
-    items,
-    getKey,
-    renderHeader,
-    getFields,
-    renderActions,
-    renderDetail,
-    className,
-  } = props;
-
-  return (
-    <ul className={cn('space-y-2', className)}>
-      {items.map((item) => {
-        const actions = renderActions?.(item);
-        const detail = renderDetail?.(item);
-        return (
-          <li
-            key={getKey(item)}
-            className="space-y-2 rounded-lg border border-rule bg-paper-elev p-3"
-          >
-            {renderHeader?.(item)}
-            <dl className="space-y-1.5">
-              {getFields(item).map((field) => (
-                <div
-                  key={field.key ?? field.label}
-                  {...field.rowAttributes}
-                  className="flex justify-between gap-3 text-sm"
-                >
-                  <dt className="shrink-0 text-ink-3">{field.label}</dt>
-                  <dd className="text-right text-ink-2">{field.value}</dd>
-                </div>
-              ))}
-            </dl>
-            {actions ? (
-              <div className="flex items-center justify-end gap-2 border-t border-rule/50 pt-2">
-                {actions}
-              </div>
-            ) : null}
-            {detail}
-          </li>
-        );
-      })}
-    </ul>
-  );
-}
-
-export default RecordCardList;

package/src/ui/chrome/StateCard.tsx

@@ -1,150 +0,0 @@
-/**
- * Unified state display card for empty, error-simple, and error-detailed states.
- * Replaces ErrorCard, ErrorDisplay, and EmptyState components.
- * Supports collapsible error details and structured field extraction.
- */
-import { ChevronDown, ChevronRight } from 'lucide-react';
-import React, { useState } from 'react';
-
-
-import { cn } from '../cn';
-
-interface FieldEntry {
-  label: string;
-  value: string | React.ReactNode;
-}
-
-interface StateCardProps {
-  /** State variant: 'empty' | 'error-simple' | 'error-detailed' */
-  variant: 'empty' | 'error-simple' | 'error-detailed';
-  /** Icon React element */
-  icon: React.ReactNode;
-  /** Primary title */
-  title: string;
-  /** Description or error message */
-  description?: string;
-  /** Optional action button */
-  action?: {
-    label: string;
-    onClick: () => void;
-  };
-  /** Optional error details (for error-detailed variant) */
-  errorDetails?: {
-    fields?: FieldEntry[];
-    stackTrace?: string;
-    requestId?: string;
-  };
-  /** Optional CSS class */
-  className?: string;
-}
-
-/**
- * Renders a state card (empty/error) with consistent appearance.
- * Supports collapsible error details for debugging.
- */
-export const StateCard: React.FC<StateCardProps> = ({
-  variant,
-  icon,
-  title,
-  description,
-  action,
-  errorDetails,
-  className = '',
-}) => {
-  const [detailsExpanded, setDetailsExpanded] = useState(false);
-
-  const isError = variant.startsWith('error');
-  const isDetailed = variant === 'error-detailed';
-
-  return (
-    <div className={cn(
-      'flex flex-col items-center justify-center py-14 px-6 rounded-xl border-2',
-      isError ? 'border-destructive/20 bg-destructive/[0.03]' : 'border-dashed border-border/50 bg-paper-elev/60',
-      className,
-    )}>
-      <div className={cn(
-        'h-14 w-14 rounded-2xl flex items-center justify-center mb-5',
-        isError ? 'bg-destructive/10' : 'bg-primary/10',
-      )}>
-        <span className={isError ? 'text-destructive' : 'text-primary'}>{icon}</span>
-      </div>
-
-      <h2 className="text-subtitle font-semibold text-ink mb-2 text-center">
-        {title}
-      </h2>
-
-      {description && (
-        <p className="text-body-1 text-ink-3 max-w-md text-center mb-4 leading-relaxed">
-          {description}
-        </p>
-      )}
-
-      {/* Error details section */}
-      {isDetailed && errorDetails && (
-        <div className="mt-4 w-full max-w-md">
-          <button
-            type="button"
-            onClick={() => setDetailsExpanded(!detailsExpanded)}
-            className="text-body-1 font-medium text-destructive hover:text-destructive flex items-center gap-1.5 mb-2"
-          >
-            {detailsExpanded ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
-            Error Details
-          </button>
-
-          {detailsExpanded && (
-            <div className="p-4 bg-card border border-destructive/20 rounded-xl space-y-3">
-              {/* Structured fields */}
-              {errorDetails.fields && errorDetails.fields.length > 0 && (
-                <div className="space-y-1.5">
-                  {errorDetails.fields.map((field, idx) => (
-                    <div key={idx} className="text-body-1">
-                      <span className="font-semibold text-destructive">{field.label}</span>
-                      <span className="text-ink/70">: {field.value}</span>
-                    </div>
-                  ))}
-                </div>
-              )}
-
-              {/* Stack trace */}
-              {errorDetails.stackTrace && (
-                <details className="text-body-1">
-                  <summary className="font-medium text-destructive cursor-pointer mb-1">
-                    Stack Trace
-                  </summary>
-                  <pre className="bg-destructive/5 p-3 rounded-lg overflow-auto max-h-32 text-destructive whitespace-pre-wrap break-words text-body-1 font-mono">
-                    {errorDetails.stackTrace}
-                  </pre>
-                </details>
-              )}
-
-              {/* Request ID */}
-              {errorDetails.requestId && (
-                <div className="text-body-1 pt-2 border-t border-destructive/15">
-                  <span className="font-medium text-ink-3">Request ID</span>
-                  <br />
-                  <code className="text-body-1 text-ink/70 font-mono break-all">{errorDetails.requestId}</code>
-                </div>
-              )}
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* Action button */}
-      {action && (
-        <button
-          type="button"
-          onClick={action.onClick}
-          className={cn(
-            'mt-6 px-5 py-2.5 rounded-lg font-medium transition-colors h-10',
-            isError
-              ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
-              : 'bg-primary text-primary-foreground hover:bg-primary/90',
-          )}
-        >
-          {action.label}
-        </button>
-      )}
-    </div>
-  );
-};

package/src/ui/chrome/confirm-delete-dialog.tsx

@@ -1,59 +0,0 @@
-import { Loader2 } from 'lucide-react';
-
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from '../primitives/alert-dialog';
-
-export interface ConfirmDeleteDialogProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  onConfirm: () => void;
-  title?: string;
-  description?: string;
-  isPending?: boolean;
-  /** Confirm-button label. Defaults to 'Delete' for the destructive case. */
-  confirmLabel?: string;
-}
-
-/**
- * Reusable delete confirmation dialog.
- * Used across CRUD surfaces to prevent accidental destructive actions.
- */
-export default function ConfirmDeleteDialog({
-  open,
-  onOpenChange,
-  onConfirm,
-  title = 'Delete item',
-  description = 'This action cannot be undone. Are you sure you want to continue?',
-  isPending,
-  confirmLabel = 'Delete',
-}: ConfirmDeleteDialogProps) {
-  return (
-    <AlertDialog open={open} onOpenChange={onOpenChange}>
-      <AlertDialogContent>
-        <AlertDialogHeader>
-          <AlertDialogTitle>{title}</AlertDialogTitle>
-          <AlertDialogDescription>{description}</AlertDialogDescription>
-        </AlertDialogHeader>
-        <AlertDialogFooter>
-          <AlertDialogCancel disabled={isPending}>Cancel</AlertDialogCancel>
-          <AlertDialogAction
-            onClick={onConfirm}
-            disabled={isPending}
-            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
-          >
-            {isPending && <Loader2 className="h-4 w-4 mr-1.5 animate-spin" />}
-            {confirmLabel}
-          </AlertDialogAction>
-        </AlertDialogFooter>
-      </AlertDialogContent>
-    </AlertDialog>
-  );
-}

package/src/ui/chrome/page-shell.spec.tsx

@@ -1,117 +0,0 @@
-/**
- * An EMBEDDED PageShell must not touch the topbar.
- *
- * ── THE DEFECT ────────────────────────────────────────────────────────────
- *
- * `embedded` means "the host page already owns the topbar — render only my
- * body". But `usePageMeta` was called UNCONDITIONALLY, above the `embedded`
- * check, and the page-meta store is a STACK: "nested pages can push their own
- * meta; on unmount the outer meta is restored".
- *
- * So an embedded shell pushed its own `title`, `description`, `eyebrow`,
- * `backTo` and `topbarActions` OVER its host's — the precise opposite of what
- * embedding means. The host's title and back button silently became the
- * child's for as long as the child was mounted, and the page-meta contract
- * ("never render a back button inside the page body… move it into
- * usePageMeta") made that the ONLY back affordance on screen, so it pointed at
- * the wrong parent.
- *
- * A hook cannot be called conditionally, so the fix is structural: `PageShell`
- * calls no hooks and only chooses between two components. These tests pin the
- * OBSERVABLE property — whether meta is registered — not the file layout, so
- * any future refactor that reintroduces the push fails them.
- *
- * Runs under the host-web vitest mirror (this package carries no vitest dep).
- */
-import { FileQuestion } from 'lucide-react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-
-
-const registered: unknown[] = [];
-
-// The kernel reaches the page-meta store through the HostBridge singleton,
-// never a host import — so the bridge is the seam to observe.
-vi.mock('../../lib/biome-host/host-bridge', async () => {
-  const actual = await vi.importActual<Record<string, unknown>>(
-    '../../lib/biome-host/host-bridge',
-  );
-  return {
-    ...actual,
-    useHostBridge: () => ({
-      pageMeta: {
-        usePageMeta: (meta: unknown) => {
-          registered.push(meta);
-        },
-      },
-    }),
-  };
-});
-
-const { default: PageShell } = await import('./page-shell');
-
-beforeEach(() => {
-  registered.length = 0;
-});
-
-const META = {
-  icon: FileQuestion,
-  title: 'Child Title',
-  description: 'Child description',
-  eyebrow: 'Child eyebrow',
-  backTo: { to: '/child-parent', label: 'Child parent' },
-} as const;
-
-describe('PageShell page-meta ownership', () => {
-  it('registers NOTHING when embedded — the host owns the topbar', () => {
-    // THE BUG, directly. Before the fix this registered the child's meta,
-    // replacing the host's title and back button on a stack-based store.
-    renderToStaticMarkup(
-      <PageShell {...META} embedded>
-        <p>body</p>
-      </PageShell>,
-    );
-    expect(registered).toEqual([]);
-  });
-
-  it('registers its meta when NOT embedded — a full page owns its topbar', () => {
-    // The other half: the fix must not silence the normal case.
-    renderToStaticMarkup(
-      <PageShell {...META}>
-        <p>body</p>
-      </PageShell>,
-    );
-    expect(registered).toHaveLength(1);
-    expect(registered[0]).toMatchObject({
-      title: 'Child Title',
-      description: 'Child description',
-      eyebrow: 'Child eyebrow',
-      backTo: { to: '/child-parent' },
-    });
-  });
-
-  it('still renders the embedded body — not registering is not "render nothing"', () => {
-    const html = renderToStaticMarkup(
-      <PageShell {...META} embedded>
-        <p>embedded-body-marker</p>
-      </PageShell>,
-    );
-    expect(html).toContain('embedded-body-marker');
-  });
-
-  it('renders the embedded sub-tab strip, which is the child’s own chrome', () => {
-    // Embedding suppresses the TOPBAR meta, not the child's in-body tabs.
-    const html = renderToStaticMarkup(
-      <PageShell
-        {...META}
-        embedded
-        tabs={[{ value: 'a', label: 'Alpha' }]}
-        activeTab="a"
-      >
-        <p>body</p>
-      </PageShell>,
-    );
-    expect(html).toContain('Alpha');
-    expect(registered).toEqual([]);
-  });
-});