@xemahq/ui-kernel 0.1.12 → 0.2.0

package/src/lib/capabilities/types.ts

@@ -0,0 +1,69 @@
+import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
+
+/**
+ * One server-authoritative capability the caller holds, mirroring the
+ * FROZEN `GET /bff/me/capabilities` wire entry.
+ *
+ * These types are defined LOCALLY in the kernel — deliberately NOT imported
+ * from a backend DTO or an Orval client — so `@xemahq/ui-kernel` stays
+ * host-agnostic (no fetch lib, no generated client). The concrete host
+ * (`submodules/xema-host-web`) maps its client response onto this shape when
+ * it implements {@link CapabilityPort}.
+ */
+export interface CapabilityEntry {
+  /**
+   * The capability reference (e.g. `capability:session.launch`). Matched
+   * verbatim by {@link useCapability}; the kernel does not parse it.
+   */
+  readonly ref: string;
+  /**
+   * The execution environments in which the caller holds this capability.
+   * A gate that names an `environment` is allowed only if it appears here.
+   */
+  readonly environments: ExecutionEnvironmentKind[];
+  /**
+   * When `true`, holding the capability still requires a human approval step
+   * before the side-effect runs — so a UI affordance should route through the
+   * approval flow rather than acting directly.
+   */
+  readonly approvalRequired: boolean;
+}
+
+/**
+ * The caller's effective capability set for one active org, mirroring the
+ * FROZEN `MeCapabilitiesResponse` wire shape.
+ */
+export interface MeCapabilitiesSnapshot {
+  /** The subject (user) the snapshot was resolved for. */
+  readonly subjectId: string;
+  /** The org the snapshot is scoped to. */
+  readonly orgId: string;
+  /** Every capability the subject effectively holds in this org. */
+  readonly capabilities: CapabilityEntry[];
+}
+
+/**
+ * Host-implemented port that fetches the caller's effective capability set.
+ *
+ * The kernel never calls an API directly — the HOST implements this against
+ * its Orval client (`GET /bff/me/capabilities`) and maps the response onto
+ * {@link MeCapabilitiesSnapshot}. The implementation is hung off
+ * {@link HostBridge.capabilities}; {@link CapabilityProvider} reads it from
+ * the bridge and uses the bridge's `QueryClient` for caching/refetch.
+ */
+export interface CapabilityPort {
+  /**
+   * Return the caller's effective capability set for the active org.
+   *
+   * @param options.orgId The org to resolve for. When omitted the host
+   *   resolves against its currently-selected org.
+   * @param options.environment Optional environment hint the host MAY pass to
+   *   the backend to narrow the set. Callers gate by environment client-side
+   *   via {@link useCapability}, so a host MAY ignore this and return the full
+   *   set; it exists so a host can request a pre-filtered snapshot.
+   */
+  list(options?: {
+    orgId?: string;
+    environment?: ExecutionEnvironmentKind;
+  }): Promise<MeCapabilitiesSnapshot>;
+}

package/src/lib/capabilities/use-capability.ts

@@ -0,0 +1,72 @@
+import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
+
+import { useCapabilityContext, type CapabilityContextValue } from './capability-provider';
+import type { MeCapabilitiesSnapshot } from './types';
+
+export interface UseCapabilityOptions {
+  /**
+   * Gate against a specific execution environment. When set, the capability
+   * counts only if the snapshot lists it for this environment.
+   */
+  readonly environment?: ExecutionEnvironmentKind;
+}
+
+export interface CapabilityDecision {
+  /**
+   * `true` only when the caller holds the capability, holds it in the named
+   * environment (if one was given), AND it does NOT require approval. A gate
+   * that should let the user act directly checks this.
+   */
+  readonly allowed: boolean;
+  /**
+   * `true` when the caller holds the capability (in the named environment, if
+   * given) but it requires a human approval step first — render the
+   * approval-routed affordance instead of acting directly.
+   */
+  readonly approvalRequired: boolean;
+  /** The snapshot is still being fetched; treat as "unknown", not "denied". */
+  readonly isLoading: boolean;
+  /** The fetch failed; surfaced so callers never conflate failure with denial. */
+  readonly error: unknown;
+}
+
+/**
+ * Server-authoritative capability gate.
+ *
+ * Resolves `ref` against the cached {@link CapabilityProvider} snapshot:
+ * - `allowed`  = entry exists AND (no environment asked OR listed for it) AND NOT approvalRequired.
+ * - `approvalRequired` = entry exists AND (no environment asked OR listed for it) AND approvalRequired.
+ *
+ * While the snapshot is loading, `allowed` is `false` and `isLoading` is
+ * `true` — callers gate on `isLoading` to distinguish "unknown" from "denied".
+ * On error, `allowed` is `false` and `error` is set; the hook never silently
+ * degrades a failed fetch into a confident denial.
+ */
+export function useCapability(ref: string, opts?: UseCapabilityOptions): CapabilityDecision {
+  const { snapshot, isLoading, error } = useCapabilityContext();
+
+  const entry = snapshot?.capabilities.find((c) => c.ref === ref);
+  const inEnvironment =
+    !!entry && (!opts?.environment || entry.environments.includes(opts.environment));
+
+  return {
+    allowed: inEnvironment && !entry.approvalRequired,
+    approvalRequired: inEnvironment && entry.approvalRequired,
+    isLoading,
+    error,
+  };
+}
+
+/**
+ * Accessor for the raw capability snapshot plus its loading/error state.
+ * Use when a component needs to enumerate capabilities rather than gate on a
+ * single `ref`.
+ */
+export function useCapabilities(): {
+  snapshot: MeCapabilitiesSnapshot | undefined;
+  isLoading: boolean;
+  error: unknown;
+} {
+  const ctx: CapabilityContextValue = useCapabilityContext();
+  return { snapshot: ctx.snapshot, isLoading: ctx.isLoading, error: ctx.error };
+}

package/src/ui/chrome/AsyncBoundary.tsx

@@ -0,0 +1,66 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import ErrorCard, { type ErrorMessageFormatter } from './ErrorCard';
+import EmptyState from './EmptyState';
+import LoadingState, { type LoadingStateVariant } from './LoadingState';
+
+interface AsyncBoundaryEmpty {
+  icon: LucideIcon;
+  title: string;
+  description?: ReactNode;
+}
+
+interface AsyncBoundaryProps {
+  /** Async in flight — renders the loading affordance. */
+  isLoading: boolean;
+  /** Resolved error, if any — renders an `ErrorCard`. */
+  error?: Error | string | unknown | null;
+  /**
+   * When true, the resolved data is empty — renders an `EmptyState`. Only
+   * checked when `empty` config is supplied; otherwise children render.
+   */
+  isEmpty?: boolean;
+  /** Empty-state config; omit to never render an empty state. */
+  empty?: AsyncBoundaryEmpty;
+  /** Retry handler threaded to `ErrorCard`. */
+  onRetry?: () => void;
+  /** Loading affordance variant. */
+  loadingVariant?: LoadingStateVariant;
+  /** Host error decoder threaded to `ErrorCard`. */
+  formatError?: ErrorMessageFormatter;
+  children: ReactNode;
+}
+
+/**
+ * Declarative loading / error / empty wrapper. Collapses the
+ * `if (isLoading) … if (error) … if (empty) … else children` ladder that
+ * every biome list/detail surface re-implements into one component built on
+ * the shared `LoadingState` / `ErrorCard` / `EmptyState` primitives.
+ *
+ * Precedence: loading → error → empty → children.
+ */
+export default function AsyncBoundary({
+  isLoading,
+  error,
+  isEmpty,
+  empty,
+  onRetry,
+  loadingVariant,
+  formatError,
+  children,
+}: Readonly<AsyncBoundaryProps>) {
+  if (isLoading) {
+    return <LoadingState variant={loadingVariant} />;
+  }
+
+  if (error) {
+    return <ErrorCard error={error} onRetry={onRetry} formatError={formatError} />;
+  }
+
+  if (isEmpty && empty) {
+    return <EmptyState icon={empty.icon} title={empty.title} description={empty.description} />;
+  }
+
+  return <>{children}</>;
+}

package/src/ui/chrome/EmptyState.tsx

@@ -0,0 +1,184 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ComponentType, ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Button } from '../primitives/button';
+import { Card, CardContent } from '../primitives/card';
+
+export type EmptyStateVariant = 'not-configured' | 'no-results' | 'disabled-context';
+
+/**
+ * Visual density.
+ *  - `comfortable` (default): hero empty state for full-page surfaces —
+ *    big 64px icon, generous padding, hero copy. Use when the page has
+ *    nothing else to render.
+ *  - `dense`: inline empty state for surfaces nested inside other
+ *    content (tabs, sub-panels). Smaller icon, tighter padding, no
+ *    dashed card frame — reads as a calm placeholder, not a banner.
+ *  - `inline`: single-line text-only message, no icon, no card. Use
+ *    inside list sub-sections where even the dense frame is too much.
+ */
+export type EmptyStateSize = 'comfortable' | 'dense' | 'inline';
+
+/**
+ * Polymorphic link element. The host shell renders Next.js `<Link>`;
+ * pass it via `linkComponent` to get client-side routing. Defaults to a
+ * plain anchor so the primitive stays host-framework-agnostic.
+ */
+export type EmptyStateLinkComponent = ComponentType<{
+  href: string;
+  children: ReactNode;
+}>;
+
+const DefaultLink: EmptyStateLinkComponent = ({ href, children }) => (
+  <a href={href}>{children}</a>
+);
+
+interface EmptyStateAction {
+  label: string;
+  onClick: () => void;
+  icon?: LucideIcon;
+}
+
+interface EmptyStateSecondaryAction {
+  label: string;
+  href: string;
+}
+
+interface EmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  description?: ReactNode;
+  /** Optional illustration or extra content above the title */
+  illustration?: ReactNode;
+  /** Visual variant — drives default iconBg/iconColor unless overridden. */
+  variant?: EmptyStateVariant;
+  size?: EmptyStateSize;
+  /** Icon tint — overrides variant defaults */
+  iconBg?: string;
+  iconColor?: string;
+  action?: EmptyStateAction;
+  secondaryAction?: EmptyStateSecondaryAction;
+  /** Host link component for `secondaryAction.href` (defaults to `<a>`). */
+  linkComponent?: EmptyStateLinkComponent;
+  className?: string;
+}
+
+const VARIANT_DEFAULTS: Record<EmptyStateVariant, { iconBg: string; iconColor: string }> = {
+  'not-configured': { iconBg: 'bg-info/10', iconColor: 'text-info' },
+  'no-results': { iconBg: 'bg-warning/10', iconColor: 'text-warning' },
+  'disabled-context': { iconBg: 'bg-muted', iconColor: 'text-ink-3' },
+};
+
+export default function EmptyState({
+  icon: Icon,
+  title,
+  description,
+  illustration,
+  variant = 'not-configured',
+  size = 'comfortable',
+  iconBg,
+  iconColor,
+  action,
+  secondaryAction,
+  linkComponent,
+  className,
+}: Readonly<EmptyStateProps>) {
+  const Link = linkComponent ?? DefaultLink;
+  const defaults = VARIANT_DEFAULTS[variant];
+  const resolvedIconBg = iconBg ?? defaults.iconBg;
+  const resolvedIconColor = iconColor ?? defaults.iconColor;
+
+  if (size === 'inline') {
+    return (
+      <div className={cn('flex items-center justify-center px-3 py-6 text-center text-body-2 text-ink-4', className)}>
+        <div className="max-w-sm space-y-1">
+          <p className="text-ink-3">{title}</p>
+          {description && <p className="text-ink-4">{description}</p>}
+          {(action || secondaryAction) && (
+            <div className="mt-3 flex items-center justify-center gap-2">
+              {action && (
+                <Button size="sm" variant="outline" onClick={action.onClick} className="h-7 gap-1.5 text-body-2">
+                  {action.icon && <action.icon className="h-3.5 w-3.5" />}
+                  {action.label}
+                </Button>
+              )}
+              {secondaryAction && (
+                <Button asChild size="sm" variant="ghost" className="h-7 px-2 text-body-2">
+                  <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+                </Button>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (size === 'dense') {
+    return (
+      <div
+        className={cn(
+          'flex flex-col items-center justify-center px-4 py-8 text-center',
+          className,
+        )}
+      >
+        {illustration ?? (
+          <div className={cn('h-9 w-9 rounded-xl flex items-center justify-center mb-3', resolvedIconBg)}>
+            <Icon className={cn('h-4 w-4', resolvedIconColor)} />
+          </div>
+        )}
+        <p className="text-body-1 font-semibold text-ink">{title}</p>
+        {description && (
+          <p className="mt-1 max-w-md text-body-2 leading-snug text-ink-3">{description}</p>
+        )}
+        {(action || secondaryAction) && (
+          <div className="mt-3 flex items-center gap-2">
+            {action && (
+              <Button size="sm" variant="outline" onClick={action.onClick} className="h-7 gap-1.5 text-body-2">
+                {action.icon && <action.icon className="h-3.5 w-3.5" />}
+                {action.label}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button asChild size="sm" variant="ghost" className="h-7 px-2 text-body-2">
+                <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <Card className={cn('border-2 border-dashed border-border/50 rounded-xl', className)}>
+      <CardContent className="flex flex-col items-center justify-center py-16 text-center">
+        {illustration ?? (
+          <div className={`h-16 w-16 rounded-2xl flex items-center justify-center mb-5 ${resolvedIconBg}`}>
+            <Icon className={`h-7 w-7 ${resolvedIconColor}`} />
+          </div>
+        )}
+        <p className="text-subtitle font-semibold text-ink">{title}</p>
+        {description && (
+          <p className="text-body-1 mt-2 max-w-sm text-ink-3 leading-relaxed">{description}</p>
+        )}
+        {(action || secondaryAction) && (
+          <div className="mt-6 flex items-center gap-3">
+            {action && (
+              <Button size="sm" variant="outline" onClick={action.onClick} className="gap-2 h-10 px-5">
+                {action.icon && <action.icon className="h-4 w-4" />}
+                {action.label}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button asChild size="sm" variant="ghost" className="h-10 px-3">
+                <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+              </Button>
+            )}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/ui/chrome/ErrorCard.tsx

@@ -0,0 +1,68 @@
+import { AlertCircle, RefreshCw } from 'lucide-react';
+
+import { Button } from '../primitives/button';
+import { Card, CardContent } from '../primitives/card';
+
+/**
+ * Host-agnostic error formatter. The host shell owns rich error decoding
+ * (Orval envelopes, workflow error codes, …); pass its formatter via
+ * `formatError` to preserve that behaviour. The default extracts a plain
+ * message and is safe in any consumer.
+ */
+export type ErrorMessageFormatter = (error: unknown, fallback: string) => string;
+
+const defaultFormatError: ErrorMessageFormatter = (error, fallback) => {
+  if (typeof error === 'string') {
+    return error || fallback;
+  }
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return fallback;
+};
+
+interface ErrorCardProps {
+  error: Error | string | unknown;
+  title?: string;
+  onRetry?: () => void;
+  /**
+   * Optional host error-decoder. Defaults to a plain message extractor.
+   * The host shell should pass `getUserFacingErrorMessage` to keep its
+   * envelope-aware messaging.
+   */
+  formatError?: ErrorMessageFormatter;
+  fallbackMessage?: string;
+}
+
+export default function ErrorCard({
+  error,
+  title = 'Something went wrong',
+  onRetry,
+  formatError = defaultFormatError,
+  fallbackMessage = 'Unable to load this content right now.',
+}: ErrorCardProps) {
+  const message = formatError(error, fallbackMessage);
+
+  return (
+    <Card className="border-destructive/25 bg-destructive/[0.03] rounded-xl">
+      <CardContent className="flex flex-col items-center py-14 text-center">
+        <div className="h-14 w-14 rounded-2xl bg-destructive/10 flex items-center justify-center mb-4">
+          <AlertCircle className="h-6 w-6 text-destructive" />
+        </div>
+        <p className="text-subtitle font-semibold text-ink">{title}</p>
+        <p className="text-body-1 text-ink-3 mt-2 max-w-md leading-relaxed">{message}</p>
+        {onRetry && (
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={onRetry}
+            className="mt-5 gap-2 h-10 border-destructive/20 text-destructive hover:bg-destructive/5"
+          >
+            <RefreshCw className="h-4 w-4" />
+            Retry
+          </Button>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/ui/chrome/LoadingState.tsx

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,137 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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>
+  );
+}