@xemahq/ui-kernel 0.4.1 → 0.5.0

package/src/lib/biome-host/use-page-state.ts

@@ -0,0 +1,231 @@
+/**
+ * usePageState — page-level UI state synced to the URL query string.
+ *
+ * State survives refresh, back/forward, and is shareable via URL. Rebuilt on
+ * the {@link HostBridge} navigation port (`useSearchParams` to read,
+ * `useLocation` for the current path, `push`/`replace` to write) so biome code
+ * never imports a router primitive (`next/navigation`, `react-router-dom`)
+ * directly — the host owns history semantics.
+ *
+ * Usage:
+ *   const [activeTab, setActiveTab] = usePageState<string>('tab', 'runs');
+ *   const [selectedId, setSelectedId] = usePageState<string | null>('run', null);
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useHostBridge } from './host-bridge';
+
+/** Default debounce for the URL mirror of a free-text input, in ms. */
+const INPUT_URL_MIRROR_DEBOUNCE_MS = 300;
+
+function buildPath(pathname: string, params: URLSearchParams): string {
+  const queryString = params.toString();
+  return queryString ? `${pathname}?${queryString}` : pathname;
+}
+
+function serializeValue<T>(value: T): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean')
+    return String(value);
+  return JSON.stringify(value);
+}
+
+function tryParseJson(rawValue: string): unknown {
+  try {
+    return JSON.parse(rawValue);
+  } catch {
+    return undefined;
+  }
+}
+
+function deserializePrimitive<T>(
+  rawValue: string,
+  defaultValue: T,
+): T | undefined {
+  if (typeof defaultValue === 'string') return rawValue as T;
+
+  if (typeof defaultValue === 'number') {
+    const numericValue = Number(rawValue);
+    return (Number.isNaN(numericValue) ? defaultValue : numericValue) as T;
+  }
+
+  if (typeof defaultValue === 'boolean') {
+    if (rawValue === 'true') return true as T;
+    if (rawValue === 'false') return false as T;
+    return defaultValue;
+  }
+
+  return undefined;
+}
+
+function deserializeValue<T>(rawValue: string | null, defaultValue: T): T {
+  if (rawValue === null) return defaultValue;
+
+  const primitive = deserializePrimitive(rawValue, defaultValue);
+  if (primitive !== undefined) return primitive;
+
+  // Default is null/undefined or a complex type (array/object). The value was
+  // written via JSON.stringify in serializeValue, so attempt to parse it back.
+  // If parsing yields a structured value (array/object/null), return it;
+  // otherwise fall back to the raw string (covers `T = string | null`).
+  const parsedValue = tryParseJson(rawValue);
+  if (parsedValue !== undefined && typeof parsedValue === 'object') {
+    return parsedValue as T;
+  }
+
+  if (defaultValue === null || defaultValue === undefined) return rawValue as T;
+
+  if (parsedValue !== undefined) return parsedValue as T;
+
+  if (Array.isArray(defaultValue)) {
+    return rawValue ? ([rawValue] as unknown as T) : defaultValue;
+  }
+
+  return defaultValue;
+}
+
+export function usePageState<T>(
+  stateKey: string,
+  defaultValue: T,
+): [T, (value: T) => void] {
+  const { navigation } = useHostBridge();
+  const searchParams = navigation.useSearchParams();
+  const { pathname } = navigation.useLocation();
+
+  const rawValue = searchParams.get(stateKey);
+  const value = deserializeValue(rawValue, defaultValue);
+
+  const setValue = useCallback(
+    (newValue: T) => {
+      const next = new URLSearchParams(searchParams);
+      if (
+        newValue === null ||
+        newValue === undefined ||
+        serializeValue(newValue) === serializeValue(defaultValue)
+      ) {
+        next.delete(stateKey);
+      } else {
+        next.set(stateKey, serializeValue(newValue));
+      }
+      navigation.push(buildPath(pathname, next));
+    },
+    [defaultValue, stateKey, searchParams, pathname, navigation],
+  );
+
+  return [value, setValue];
+}
+
+/**
+ * usePageInputState — like {@link usePageState}, but tuned for FREE-TEXT
+ * `<Input>` values that are mirrored to the URL on every keystroke.
+ *
+ * The returned value lives in LOCAL React state, so typing is instant. The URL
+ * is mirrored — debounced — via the host's `replace` (an in-place history entry
+ * update), so the value stays shareable / refresh-survivable WITHOUT pushing a
+ * new history entry per keystroke.
+ *
+ * The local value re-syncs whenever the underlying search param changes from
+ * the outside (a real navigation, a "Clear" button writing the param, or
+ * back/forward), so external resets still flow through.
+ *
+ * Use this ONLY for free-text inputs. Tabs, selects, and row selection are real
+ * navigations — keep them on {@link usePageState}.
+ *
+ * Usage:
+ *   const [filter, setFilter] = usePageInputState('runFilter', '');
+ *   <Input value={filter} onChange={(e) => setFilter(e.target.value)} />
+ */
+export function usePageInputState(
+  stateKey: string,
+  defaultValue: string,
+  debounceMs: number = INPUT_URL_MIRROR_DEBOUNCE_MS,
+): [string, (value: string) => void] {
+  const { navigation } = useHostBridge();
+  const searchParams = navigation.useSearchParams();
+  const { pathname } = navigation.useLocation();
+
+  const urlValue = searchParams.get(stateKey) ?? defaultValue;
+
+  const [localValue, setLocalValue] = useState(urlValue);
+
+  // Resync local state when the URL param changes from the outside (real
+  // navigation, Clear button, back/forward). We compare against the value we
+  // last mirrored so our own debounced writes don't bounce back and clobber
+  // freshly-typed characters.
+  const lastMirroredRef = useRef(urlValue);
+  useEffect(() => {
+    if (urlValue !== lastMirroredRef.current) {
+      lastMirroredRef.current = urlValue;
+      setLocalValue(urlValue);
+    }
+  }, [urlValue]);
+
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (debounceTimerRef.current !== null) {
+        clearTimeout(debounceTimerRef.current);
+      }
+    },
+    [],
+  );
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      // Instant: drive the input from local state synchronously.
+      setLocalValue(newValue);
+
+      if (debounceTimerRef.current !== null) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = null;
+        lastMirroredRef.current =
+          newValue === defaultValue ? defaultValue : newValue;
+        const next = new URLSearchParams(searchParams);
+        if (newValue === defaultValue || newValue.length === 0) {
+          next.delete(stateKey);
+        } else {
+          next.set(stateKey, newValue);
+        }
+        navigation.replace(buildPath(pathname, next));
+      }, debounceMs);
+    },
+    [debounceMs, defaultValue, stateKey, searchParams, pathname, navigation],
+  );
+
+  return [localValue, setValue];
+}
+
+/**
+ * Batch-update multiple page-state keys in a single navigation.
+ *
+ * Pass `null` for a value to delete the key (reset to default).
+ *
+ * Usage:
+ *   const batch = useBatchPageState();
+ *   batch({ selectedId: 'abc', mainTab: null, contextTab: null });
+ */
+export function useBatchPageState(): (
+  updates: Record<string, string | null>,
+) => void {
+  const { navigation } = useHostBridge();
+  const searchParams = navigation.useSearchParams();
+  const { pathname } = navigation.useLocation();
+
+  return useCallback(
+    (updates: Record<string, string | null>) => {
+      const next = new URLSearchParams(searchParams);
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === null || value === undefined) {
+          next.delete(key);
+        } else {
+          next.set(key, value);
+        }
+      }
+      navigation.push(buildPath(pathname, next));
+    },
+    [searchParams, pathname, navigation],
+  );
+}

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

@@ -0,0 +1,59 @@
+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.tsx

@@ -0,0 +1,165 @@
+import { FileQuestion, type LucideIcon } from 'lucide-react';
+import { type ReactNode } from 'react';
+
+import { useHostBridge, type PageBackTarget } from '../../lib/biome-host';
+import EmptyState from './EmptyState';
+import { Tabs, TabsList, TabsTrigger } from '../primitives/tabs';
+
+interface TabDef {
+  value: string;
+  label: string | ReactNode;
+  count?: number;
+  indicator?: boolean;
+}
+
+interface PageShellProps {
+  icon: LucideIcon;
+  title: string;
+  description?: string;
+  children?: ReactNode;
+  actions?: ReactNode;
+  tabs?: TabDef[];
+  activeTab?: string;
+  onTabChange?: (value: string) => void;
+  maxWidth?: string;
+  embedded?: boolean;
+  /** Mono caption rendered before the title in the topbar (parent context). */
+  eyebrow?: string;
+  /**
+   * Leftmost icon-only back affordance on the topbar. Pages with a parent
+   * context MUST set this and MUST NOT render their own in-body back button.
+   */
+  backTo?: PageBackTarget;
+  /**
+   * Optional right-aligned topbar action cluster. Use for primary CTAs
+   * (1-3 small buttons). Heavier in-page chrome (filter rows, search
+   * inputs) should keep using the `actions` slot which renders inside the
+   * page body.
+   */
+  topbarActions?: ReactNode;
+}
+
+/**
+ * Full-page shell — registers the topbar page-meta (via the HostBridge
+ * page-meta store) and renders an optional tab strip + action row above the
+ * scrollable content canvas. Host-framework-agnostic: reaches the page-meta
+ * store through the kernel `HostBridge` singleton, never a host import.
+ */
+export default function PageShell({
+  icon: _Icon,
+  title,
+  description,
+  children,
+  actions,
+  tabs,
+  activeTab,
+  onTabChange,
+  maxWidth,
+  embedded,
+  eyebrow,
+  backTo,
+  topbarActions,
+}: Readonly<PageShellProps>) {
+  // Single source of truth for the topbar title. Pages that bypass
+  // PageShell call the page-meta hook directly; PageShell wraps the same
+  // hook so consumers don't need to register meta twice.
+  useHostBridge().pageMeta.usePageMeta({ title, description, eyebrow, backTo, topbarActions });
+  if (embedded) {
+    // Embedded mode: the host page already provides the title + tabs +
+    // context, so we render ONLY the child content + any sub-tab strip +
+    // actions inline. This eliminates the legacy duplicate icon-and-title
+    // row that previously stole vertical space.
+    return (
+      <div className="flex h-full min-h-0 flex-col bg-paper">
+        {(tabs && tabs.length > 0) || actions ? (
+          <div className="shrink-0 border-b border-rule bg-paper-elev/40">
+            <div className="flex items-center gap-3 px-4 py-2 lg:px-6">
+              {tabs && tabs.length > 0 && (
+                <Tabs value={activeTab} onValueChange={onTabChange} className="flex-1 min-w-0">
+                  <div className="overflow-x-auto">
+                    <TabsList className="h-7 bg-transparent p-0 gap-0">
+                      {tabs.map((tab) => (
+                        <TabsTrigger
+                          key={tab.value}
+                          value={tab.value}
+                          className="rounded-none border-b-2 border-transparent px-2 py-1 text-body-2 font-medium text-ink-3 transition-colors data-[state=active]:border-primary data-[state=active]:text-ink data-[state=active]:bg-transparent data-[state=active]:shadow-none"
+                        >
+                          {tab.label}
+                          {tab.count !== undefined && (
+                            <span className="ml-1.5 text-caption tabular-nums opacity-70">{tab.count}</span>
+                          )}
+                          {tab.indicator && (
+                            <span className="ml-1.5 inline-block h-1.5 w-1.5 rounded-full bg-warning" />
+                          )}
+                        </TabsTrigger>
+                      ))}
+                    </TabsList>
+                  </div>
+                </Tabs>
+              )}
+              {!tabs && <div className="flex-1" />}
+              {actions && <div className="flex items-center gap-2 shrink-0">{actions}</div>}
+            </div>
+          </div>
+        ) : null}
+        <div className="flex-1 overflow-auto min-h-0">
+          <div className="flex h-full min-h-0 flex-col px-4 pb-4 pt-3 lg:px-6">{children}</div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex h-full min-h-0 flex-col ${maxWidth ?? ''}`}>
+      {/* Compact toolbar: tabs + actions on the same row */}
+      {(tabs || actions) && (
+        <div className="shrink-0 border-b border-border/50 px-4 sm:px-5 lg:px-8">
+          <div className="flex min-h-[34px] flex-col gap-2 py-1.5 sm:flex-row sm:items-center sm:gap-3 sm:py-0">
+            {tabs && tabs.length > 0 && (
+              <Tabs value={activeTab} onValueChange={onTabChange} className="flex-1 min-w-0">
+                <div className="overflow-x-auto">
+                  <TabsList className="h-7 bg-transparent p-0 gap-0">
+                    {tabs.map((tab) => (
+                      <TabsTrigger
+                        key={tab.value}
+                        value={tab.value}
+                        className="whitespace-nowrap rounded-none border-b-2 border-transparent px-2.5 py-1.5 text-caption font-medium text-ink-3/90 transition-colors data-[state=active]:border-primary data-[state=active]:bg-transparent data-[state=active]:text-ink data-[state=active]:shadow-none hover:text-ink"
+                      >
+                        {tab.label}
+                        {tab.count !== undefined && (
+                          <span className="ml-1.5 text-caption tabular-nums opacity-60">{tab.count}</span>
+                        )}
+                        {tab.indicator && (
+                          <span className="ml-1.5 inline-block h-1.5 w-1.5 rounded-full bg-warning" />
+                        )}
+                      </TabsTrigger>
+                    ))}
+                  </TabsList>
+                </div>
+              </Tabs>
+            )}
+            {!tabs && <div className="flex-1" />}
+            {actions && (
+              <div className="flex w-full flex-wrap items-center gap-2 sm:w-auto sm:shrink-0 sm:justify-end">
+                {actions}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Content area — full height. Padding sized to match other editorial
+          surfaces (PageHeader-rooted pages use the same `px-4 sm:px-6 py-5`
+          rhythm). */}
+      <div className="flex min-h-0 flex-1 flex-col overflow-auto px-4 pb-5 pt-4 sm:px-6 sm:pb-6 sm:pt-5">
+        {children || (
+          <EmptyState
+            icon={FileQuestion}
+            title="Nothing to show yet"
+            description="This page has no content to display. Check back once the workspace has data."
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/ui/chrome/scope-badge.tsx

@@ -0,0 +1,40 @@
+import { cn } from '../cn';
+import { TONE_STYLES, type Tone } from '../design-tokens';
+
+export interface ScopeBadgeProps {
+  /** Short label shown inside the chip. e.g. "system", "org", "override". */
+  label: string;
+  /** Visual tone — drives bg/text/border via design tokens. */
+  tone?: Tone;
+  /** Optional tooltip text. */
+  hint?: string;
+  className?: string;
+}
+
+/**
+ * Compact uppercase chip for closed-enum scope/source pills (workflow
+ * source, trigger scope, etc.). Distinct from `<StatusBadge>` which
+ * carries process-state semantics (running/succeeded/failed/…).
+ *
+ * Always renders at the smallest size (`text-[10px]`) because it sits
+ * inline next to other content on dense list rows.
+ */
+export default function ScopeBadge({
+  label,
+  tone = 'neutral',
+  hint,
+  className,
+}: ScopeBadgeProps) {
+  return (
+    <span
+      className={cn(
+        'inline-flex shrink-0 items-center rounded-sm border px-1.5 py-0 text-[10px] font-medium uppercase tracking-wide',
+        TONE_STYLES[tone],
+        className,
+      )}
+      title={hint}
+    >
+      {label}
+    </span>
+  );
+}

package/src/ui/chrome/status-badge.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { getStatusStyle } from '../design-tokens';
+import { Badge } from '../primitives/badge';
+
+export type StatusBadgeSize = 'xs' | 'sm' | 'md';
+
+export interface StatusBadgeProps {
+  status: string;
+  className?: string;
+  dot?: boolean;
+  size?: StatusBadgeSize;
+  /** Override the rendered label. Falls back to a capitalized version of `status`. */
+  children?: ReactNode;
+}
+
+interface SizeTokens {
+  badge: string;
+  dot: string;
+  gap: string;
+}
+
+const SIZE_TOKENS: Record<StatusBadgeSize, SizeTokens> = {
+  xs: {
+    badge: 'h-[18px] px-1.5 py-0 text-[10px] font-medium',
+    dot: 'h-1 w-1',
+    gap: 'gap-1',
+  },
+  sm: {
+    badge: 'h-5 px-2 py-0 text-caption font-medium',
+    dot: 'h-1.5 w-1.5',
+    gap: 'gap-1.5',
+  },
+  md: {
+    badge: 'px-2.5 py-0.5 text-body-1',
+    dot: 'h-1.5 w-1.5',
+    gap: 'gap-1.5',
+  },
+};
+
+/**
+ * Semantic status badge that reads from the design token system.
+ * Use across all pages for consistent status display.
+ *
+ * Size guidance:
+ *   - `xs` — dense list rows (Sessions, Brainstorming)
+ *   - `sm` — default list rows (Workflow Runs, Schedules, Triggers, dashboards)
+ *   - `md` — detail-page headers + hero surfaces
+ */
+export default function StatusBadge({
+  status,
+  className,
+  dot,
+  size = 'sm',
+  children,
+}: StatusBadgeProps) {
+  const style = getStatusStyle(status);
+  const sz = SIZE_TOKENS[size];
+  return (
+    <Badge
+      variant="outline"
+      className={cn(
+        'inline-flex items-center rounded-full',
+        sz.badge,
+        sz.gap,
+        style.badge,
+        className,
+      )}
+    >
+      {dot && <span className={cn('shrink-0 rounded-full', sz.dot, style.dot)} />}
+      {children ?? <span className="capitalize">{status.replace(/_/g, ' ')}</span>}
+    </Badge>
+  );
+}