@xemahq/ui-kernel 0.10.0 → 0.11.1

package/src/ui/charts/sparkline.tsx

@@ -1,12 +1,12 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // Sparkline — tiny inline trend line, pure SVG, no axes/legend (Wave 9.2)
 // ═══════════════════════════════════════════════════════════════════════════
-import type { ReactNode } from 'react';
 
 import { cn } from '../cn';
+import { chartColorAt, defaultFormatValue, niceScale } from './chart-utils';
 
 import type { ChartValueFormatter } from './chart-types';
-import { chartColorAt, defaultFormatValue, niceScale } from './chart-utils';
+import type { ReactNode } from 'react';
 
 const VIEW_W = 100;
 const VIEW_H = 28;
@@ -36,8 +36,13 @@ export function Sparkline({
 }: SparklineProps): ReactNode {
   const format = formatValue ?? defaultFormatValue;
   const finite = values.filter((v) => Number.isFinite(v));
+  // Read the endpoints BEFORE the empty guard so the guard itself narrows them:
+  // both are `undefined` exactly when `finite` is empty, which is the case the
+  // guard already returns for.
+  const first = finite[0];
+  const last = finite[finite.length - 1];
 
-  if (finite.length === 0) {
+  if (first === undefined || last === undefined) {
     return (
       <span
         role="img"
@@ -49,7 +54,9 @@ export function Sparkline({
     );
   }
 
-  const scale = niceScale(Math.min(...finite), Math.max(...finite), { pinZero: false });
+  const scale = niceScale(Math.min(...finite), Math.max(...finite), {
+    pinZero: false,
+  });
   const span = scale.max - scale.min;
   const yToPx = (v: number): number =>
     VIEW_H - PAD_Y - ((v - scale.min) / span) * (VIEW_H - 2 * PAD_Y);
@@ -60,17 +67,18 @@ export function Sparkline({
   const segments: string[] = [];
   let current: string[] = [];
   values.forEach((v, i) => {
-    if (Number.isFinite(v)) current.push(`${xToPx(i)},${yToPx(v)}`);
-    else if (current.length > 0) {
+    if (Number.isFinite(v)) {
+      current.push(`${xToPx(i)},${yToPx(v)}`);
+    } else if (current.length > 0) {
       segments.push(current.join(' '));
       current = [];
     }
   });
-  if (current.length > 0) segments.push(current.join(' '));
+  if (current.length > 0) {
+    segments.push(current.join(' '));
+  }
 
   const stroke = chartColorAt(0, color);
-  const first = finite[0];
-  const last = finite[finite.length - 1];
   const summary =
     ariaLabel ??
     `${title}: trend of ${finite.length} points, from ${format(first)} to ${format(last)}.`;

package/src/ui/chrome/AsyncBoundary.tsx

@@ -1,10 +1,10 @@
-import type { LucideIcon } from 'lucide-react';
-import type { ReactNode } from 'react';
-
-import ErrorCard, { type ErrorMessageFormatter } from './ErrorCard';
 import EmptyState from './EmptyState';
+import ErrorCard, { type ErrorMessageFormatter } from './ErrorCard';
 import LoadingState, { type LoadingStateVariant } from './LoadingState';
 
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
 interface AsyncBoundaryEmpty {
   icon: LucideIcon;
   title: string;
@@ -55,11 +55,19 @@ export default function AsyncBoundary({
   }
 
   if (error) {
-    return <ErrorCard error={error} onRetry={onRetry} formatError={formatError} />;
+    return (
+      <ErrorCard error={error} onRetry={onRetry} formatError={formatError} />
+    );
   }
 
   if (isEmpty && empty) {
-    return <EmptyState icon={empty.icon} title={empty.title} description={empty.description} />;
+    return (
+      <EmptyState
+        icon={empty.icon}
+        title={empty.title}
+        description={empty.description}
+      />
+    );
   }
 
   return <>{children}</>;

package/src/ui/chrome/EmptyState.tsx

@@ -1,11 +1,14 @@
-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';
+import type { LucideIcon } from 'lucide-react';
+import type { ComponentType, ReactNode } from 'react';
+
+export type EmptyStateVariant =
+  | 'not-configured'
+  | 'no-results'
+  | 'disabled-context';
 
 /**
  * Visual density.
@@ -45,67 +48,94 @@ interface EmptyStateSecondaryAction {
   href: string;
 }
 
-interface EmptyStateProps {
-  icon: LucideIcon;
+interface EmptyStateCommonProps {
   title: string;
   description?: ReactNode;
+  action?: EmptyStateAction;
+  secondaryAction?: EmptyStateSecondaryAction;
+  /** Host link component for `secondaryAction.href` (defaults to `<a>`). */
+  linkComponent?: EmptyStateLinkComponent;
+  className?: string;
+}
+
+/** `comfortable` / `dense` render an icon block, so the icon is required. */
+interface EmptyStateIconicProps extends EmptyStateCommonProps {
+  size?: Exclude<EmptyStateSize, 'inline'>;
+  icon: LucideIcon;
   /** 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 }> = {
+/**
+ * `inline` is text-only by definition — no icon block, therefore no icon,
+ * illustration, variant or icon tint. They are typed `never` rather than
+ * silently ignored: an accepted-but-unrendered prop is how callers ended up
+ * importing a lucide icon that renders nowhere.
+ */
+interface EmptyStateInlineProps extends EmptyStateCommonProps {
+  size: 'inline';
+  icon?: never;
+  illustration?: never;
+  variant?: never;
+  iconBg?: never;
+  iconColor?: never;
+}
+
+type EmptyStateProps = EmptyStateIconicProps | EmptyStateInlineProps;
+
+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>) {
+export default function EmptyState(props: Readonly<EmptyStateProps>) {
+  const { title, description, action, secondaryAction, linkComponent, className } =
+    props;
   const Link = linkComponent ?? DefaultLink;
-  const defaults = VARIANT_DEFAULTS[variant];
-  const resolvedIconBg = iconBg ?? defaults.iconBg;
-  const resolvedIconColor = iconColor ?? defaults.iconColor;
 
-  if (size === 'inline') {
+  if (props.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={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">
+                <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
+                  asChild
+                  size="sm"
+                  variant="ghost"
+                  className="h-7 px-2 text-body-2"
+                >
+                  <Link href={secondaryAction.href}>
+                    {secondaryAction.label}
+                  </Link>
                 </Button>
               )}
             </div>
@@ -115,6 +145,18 @@ export default function EmptyState({
     );
   }
 
+  const {
+    icon: Icon,
+    illustration,
+    variant = 'not-configured',
+    size = 'comfortable',
+    iconBg,
+    iconColor,
+  } = props;
+  const defaults = VARIANT_DEFAULTS[variant];
+  const resolvedIconBg = iconBg ?? defaults.iconBg;
+  const resolvedIconColor = iconColor ?? defaults.iconColor;
+
   if (size === 'dense') {
     return (
       <div
@@ -124,24 +166,41 @@ export default function EmptyState({
         )}
       >
         {illustration ?? (
-          <div className={cn('h-9 w-9 rounded-xl flex items-center justify-center mb-3', resolvedIconBg)}>
+          <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>
+          <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">
+              <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">
+              <Button
+                asChild
+                size="sm"
+                variant="ghost"
+                className="h-7 px-2 text-body-2"
+              >
                 <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
               </Button>
             )}
@@ -152,21 +211,35 @@ export default function EmptyState({
   }
 
   return (
-    <Card className={cn('border-2 border-dashed border-border/50 rounded-xl', className)}>
+    <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}`}>
+          <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>
+          <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">
+              <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>

package/src/ui/chrome/RecordCardList.tsx

@@ -0,0 +1,98 @@
+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/page-shell.spec.tsx

@@ -0,0 +1,117 @@
+/**
+ * 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([]);
+  });
+});