@xemahq/ui-kernel 0.6.0 → 0.6.1

package/src/ui/charts/donut-chart.tsx

@@ -0,0 +1,111 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// DonutChart — proportional ring, pure SVG (Wave 9.2)
+//
+// Slices are built from finite, non-negative values (a slice needs a magnitude).
+// If no finite positive value remains, an explicit empty state renders instead
+// of a broken ring.
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
+import type { ChartBaseProps, ChartDatum } from './chart-types';
+import { buildAriaSummary, chartColorAt, defaultFormatValue } from './chart-utils';
+
+const SIZE = 200;
+const CX = SIZE / 2;
+const CY = SIZE / 2;
+const R_OUTER = 90;
+const R_INNER = 56;
+const FULL = Math.PI * 2;
+
+export interface DonutChartProps extends ChartBaseProps {
+  /** The slices — one per labelled datum. Negative/non-finite values are skipped. */
+  readonly data: readonly ChartDatum[];
+}
+
+/** Point on a circle at `angle` (radians, 0 = 12 o'clock, clockwise). */
+function polar(radius: number, angle: number): [number, number] {
+  return [CX + radius * Math.sin(angle), CY - radius * Math.cos(angle)];
+}
+
+/** Annulus-segment path from `start` to `end` (radians). */
+function slicePath(start: number, end: number): string {
+  const [ox1, oy1] = polar(R_OUTER, start);
+  const [ox2, oy2] = polar(R_OUTER, end);
+  const [ix2, iy2] = polar(R_INNER, end);
+  const [ix1, iy1] = polar(R_INNER, start);
+  const largeArc = end - start > Math.PI ? 1 : 0;
+  return [
+    `M ${ox1} ${oy1}`,
+    `A ${R_OUTER} ${R_OUTER} 0 ${largeArc} 1 ${ox2} ${oy2}`,
+    `L ${ix2} ${iy2}`,
+    `A ${R_INNER} ${R_INNER} 0 ${largeArc} 0 ${ix1} ${iy1}`,
+    'Z',
+  ].join(' ');
+}
+
+export function DonutChart({
+  data,
+  title,
+  ariaLabel,
+  formatValue,
+  className,
+  emptyLabel = 'No data',
+}: DonutChartProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+  const slices = data.filter((d) => Number.isFinite(d.value) && d.value > 0);
+  const total = slices.reduce((sum, d) => sum + d.value, 0);
+
+  if (slices.length === 0 || total <= 0) {
+    return <ChartEmpty title={title} label={emptyLabel} className={className} />;
+  }
+
+  const legend: ChartLegendItem[] = slices.map((d, i) => ({
+    label: d.label,
+    value: `${format(d.value)} (${Math.round((d.value / total) * 100)}%)`,
+    color: chartColorAt(i, d.color),
+  }));
+
+  const summaryPoints = slices.map((d) => ({ label: d.label, value: d.value }));
+  const summary = ariaLabel ?? buildAriaSummary(title, summaryPoints, format, 'slice');
+
+  let cursor = 0;
+  const arcs = slices.map((d, i) => {
+    const start = cursor;
+    // A lone full-circle slice can't be drawn as a single arc (start===end):
+    // nudge the end just shy of a full turn so the ring still closes visually.
+    const sweep = slices.length === 1 ? FULL - 1e-3 : (d.value / total) * FULL;
+    const end = start + sweep;
+    cursor = end;
+    return { path: slicePath(start, end), color: chartColorAt(i, d.color), key: `${d.label}-${i}` };
+  });
+
+  const plot = (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${SIZE} ${SIZE}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="mx-auto block h-auto w-full max-w-[240px] text-ink-4"
+    >
+      {arcs.map((a) => (
+        <path key={a.key} d={a.path} fill={a.color} stroke="var(--card, transparent)" strokeWidth={1} />
+      ))}
+      <text
+        x={CX}
+        y={CY}
+        textAnchor="middle"
+        dominantBaseline="middle"
+        fontSize={20}
+        fontWeight={600}
+        fill="currentColor"
+        className="text-ink"
+      >
+        {format(total)}
+      </text>
+    </svg>
+  );
+
+  return <ChartFrame plot={plot} legend={legend} className={className} />;
+}

package/src/ui/charts/index.ts

@@ -0,0 +1,27 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Chart primitives (Wave 9.2) — pure-SVG, responsive-by-construction dashboard
+// charts. The kernel ships NO chart library: a strict CSP blocks external
+// scripts/fonts/images, so every chart is inline SVG built from React.
+// ═══════════════════════════════════════════════════════════════════════════
+export type {
+  ChartDatum,
+  ChartLineSeries,
+  ChartValueFormatter,
+  ChartBaseProps,
+} from './chart-types';
+export {
+  CHART_PALETTE,
+  chartColorAt,
+  defaultFormatValue,
+  finitePoints,
+  niceScale,
+  buildAriaSummary,
+  type NiceScale,
+  type NiceScaleOptions,
+  type FiniteDatum,
+} from './chart-utils';
+export { ChartLegend, type ChartLegendItem } from './chart-frame';
+export { BarChart, type BarChartProps } from './bar-chart';
+export { LineChart, type LineChartProps } from './line-chart';
+export { Sparkline, type SparklineProps } from './sparkline';
+export { DonutChart, type DonutChartProps } from './donut-chart';

package/src/ui/charts/line-chart.tsx

@@ -0,0 +1,180 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// LineChart — one or more line series over shared x-labels, pure SVG (Wave 9.2)
+//
+// Non-finite points break the line (a new segment starts after the gap) rather
+// than emitting a NaN coordinate.
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
+import type { ChartBaseProps, ChartLineSeries } from './chart-types';
+import {
+  buildAriaSummary,
+  chartColorAt,
+  defaultFormatValue,
+  niceScale,
+} from './chart-utils';
+
+const VIEW_W = 640;
+const VIEW_H = 360;
+const PAD = { top: 12, right: 12, bottom: 44, left: 48 } as const;
+const PLOT_L = PAD.left;
+const PLOT_R = VIEW_W - PAD.right;
+const PLOT_T = PAD.top;
+const PLOT_B = VIEW_H - PAD.bottom;
+const PLOT_W = PLOT_R - PLOT_L;
+const PLOT_H = PLOT_B - PLOT_T;
+
+export interface LineChartProps extends ChartBaseProps {
+  /** One or more named line series. */
+  readonly series: readonly ChartLineSeries[];
+}
+
+/** Break a series' points into finite segments (a gap ends the current run). */
+function toSegments(
+  points: readonly { value: number }[],
+  xToPx: (i: number) => number,
+  yToPx: (v: number) => number,
+): string[] {
+  const segments: string[] = [];
+  let current: string[] = [];
+  points.forEach((p, i) => {
+    if (Number.isFinite(p.value)) {
+      current.push(`${xToPx(i)},${yToPx(p.value)}`);
+    } else if (current.length > 0) {
+      segments.push(current.join(' '));
+      current = [];
+    }
+  });
+  if (current.length > 0) segments.push(current.join(' '));
+  return segments;
+}
+
+export function LineChart({
+  series,
+  title,
+  ariaLabel,
+  formatValue,
+  className,
+  emptyLabel = 'No data',
+}: LineChartProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+
+  // Every finite value across all series drives the y-domain and the summary.
+  const finiteValues: number[] = [];
+  let maxLen = 0;
+  for (const s of series) {
+    maxLen = Math.max(maxLen, s.points.length);
+    for (const p of s.points) if (Number.isFinite(p.value)) finiteValues.push(p.value);
+  }
+
+  if (finiteValues.length === 0) {
+    return <ChartEmpty title={title} label={emptyLabel} className={className} />;
+  }
+
+  const scale = niceScale(Math.min(...finiteValues), Math.max(...finiteValues), {
+    pinZero: false,
+  });
+  const span = scale.max - scale.min;
+  const yToPx = (v: number): number => PLOT_B - ((v - scale.min) / span) * PLOT_H;
+  const xToPx = (i: number): number =>
+    maxLen <= 1 ? PLOT_L + PLOT_W / 2 : PLOT_L + (i / (maxLen - 1)) * PLOT_W;
+
+  // x labels from the longest series (deterministic pick: first of that length).
+  const xLabelSource = series.find((s) => s.points.length === maxLen)?.points ?? [];
+
+  const legend: ChartLegendItem[] = series.map((s, i) => ({
+    label: s.name,
+    color: chartColorAt(i, s.color),
+  }));
+
+  // Summarize the first series' points (or the union count) for the aria label.
+  const summaryPoints = series.flatMap((s) =>
+    s.points
+      .filter((p) => Number.isFinite(p.value))
+      .map((p) => ({ label: `${s.name} ${p.label}`, value: p.value })),
+  );
+  const summary = ariaLabel ?? buildAriaSummary(title, summaryPoints, format, 'point');
+
+  const plot = (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="block h-auto w-full overflow-visible text-ink-4"
+    >
+      {/* y gridlines + tick labels */}
+      {scale.ticks.map((t) => {
+        const y = yToPx(t);
+        return (
+          <g key={`y-${t}`}>
+            <line
+              x1={PLOT_L}
+              x2={PLOT_R}
+              y1={y}
+              y2={y}
+              stroke="currentColor"
+              strokeOpacity={0.12}
+            />
+            <text
+              x={PLOT_L - 8}
+              y={y}
+              textAnchor="end"
+              dominantBaseline="middle"
+              fontSize={12}
+              fill="currentColor"
+            >
+              {format(t)}
+            </text>
+          </g>
+        );
+      })}
+
+      {/* x labels */}
+      {xLabelSource.map((p, i) => (
+        <text
+          key={`x-${p.label}-${i}`}
+          x={xToPx(i)}
+          y={PLOT_B + 16}
+          textAnchor="middle"
+          fontSize={12}
+          fill="currentColor"
+        >
+          {p.label}
+        </text>
+      ))}
+
+      {/* lines */}
+      {series.map((s, si) => {
+        const color = chartColorAt(si, s.color);
+        const segments = toSegments(s.points, xToPx, yToPx);
+        return (
+          <g key={`line-${s.name}-${si}`}>
+            {segments.map((pts, gi) => (
+              <polyline
+                key={`seg-${gi}`}
+                points={pts}
+                fill="none"
+                stroke={color}
+                strokeWidth={2}
+                strokeLinejoin="round"
+                strokeLinecap="round"
+              />
+            ))}
+            {s.points.map((p, i) =>
+              Number.isFinite(p.value) ? (
+                <circle key={`pt-${i}`} cx={xToPx(i)} cy={yToPx(p.value)} r={2.5} fill={color}>
+                  <title>{`${s.name} — ${p.label}: ${format(p.value)}`}</title>
+                </circle>
+              ) : null,
+            )}
+          </g>
+        );
+      })}
+    </svg>
+  );
+
+  return <ChartFrame plot={plot} legend={legend} className={className} />;
+}

package/src/ui/charts/sparkline.tsx

@@ -0,0 +1,101 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Sparkline — tiny inline trend line, pure SVG, no axes/legend (Wave 9.2)
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { cn } from '../cn';
+
+import type { ChartValueFormatter } from './chart-types';
+import { chartColorAt, defaultFormatValue, niceScale } from './chart-utils';
+
+const VIEW_W = 100;
+const VIEW_H = 28;
+const PAD_Y = 3;
+
+export interface SparklineProps {
+  /** The ordered values. Non-finite entries break the line rather than plotting NaN. */
+  readonly values: readonly number[];
+  /** Title — the spine of the `aria-label` summary. */
+  readonly title: string;
+  readonly ariaLabel?: string;
+  readonly formatValue?: ChartValueFormatter;
+  /** Line color (CSS color / `currentColor` / `var(--…)`). Defaults to the brand palette slot 0. */
+  readonly color?: string;
+  readonly className?: string;
+  readonly emptyLabel?: string;
+}
+
+export function Sparkline({
+  values,
+  title,
+  ariaLabel,
+  formatValue,
+  color,
+  className,
+  emptyLabel = 'No data',
+}: SparklineProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+  const finite = values.filter((v) => Number.isFinite(v));
+
+  if (finite.length === 0) {
+    return (
+      <span
+        role="img"
+        aria-label={`${title}: ${emptyLabel}`}
+        className={cn('inline-block text-body-2 text-ink-4', className)}
+      >
+        {emptyLabel}
+      </span>
+    );
+  }
+
+  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);
+  const xToPx = (i: number): number =>
+    values.length <= 1 ? VIEW_W / 2 : (i / (values.length - 1)) * VIEW_W;
+
+  // Break into finite segments so a gap never yields a NaN coordinate.
+  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) {
+      segments.push(current.join(' '));
+      current = [];
+    }
+  });
+  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)}.`;
+
+  return (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="none"
+      className={cn('block h-auto w-full overflow-visible', className)}
+    >
+      {segments.map((pts, i) => (
+        <polyline
+          key={`seg-${i}`}
+          points={pts}
+          fill="none"
+          stroke={stroke}
+          strokeWidth={1.5}
+          strokeLinejoin="round"
+          strokeLinecap="round"
+          vectorEffect="non-scaling-stroke"
+        />
+      ))}
+    </svg>
+  );
+}

package/src/ui/hooks/use-is-mobile.ts

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+
+import { MOBILE_BREAKPOINT } from '../breakpoints';
+
+/**
+ * `true` when the viewport is narrower than the shared {@link MOBILE_BREAKPOINT}
+ * (Tailwind's `md`). Server-driven renderers use this to collapse tables to
+ * cards, reflow grids and go single-column WITHOUT the author declaring a
+ * breakpoint — responsiveness is a property of the primitive, not a checklist.
+ *
+ * Reads `window.innerWidth`, so it returns `false` until mounted on the client
+ * (SSR-safe: no layout thrash, no hydration mismatch beyond the first paint).
+ */
+export function useIsMobile(): boolean {
+  const [isMobile, setIsMobile] = useState<boolean | undefined>(undefined);
+
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = (): void => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener('change', onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return !!isMobile;
+}

package/src/ui/index.ts

@@ -15,8 +15,12 @@ export { cn } from './cn';
 // ── design tokens (semantic styling SSOT) ──
 export * from './design-tokens';
 
+// ── responsive breakpoint token (JS ↔ Tailwind `md`, single source) ──
+export { MOBILE_BREAKPOINT } from './breakpoints';
+
 // ── hooks ──
 export { useDebouncedValue } from './hooks/use-debounced-value';
+export { useIsMobile } from './hooks/use-is-mobile';
 
 // ── shadcn primitives ──
 export * from './primitives/button';
@@ -46,6 +50,22 @@ export * from './primitives/tag-multi-select';
 export * from './primitives/sheet';
 export * from './primitives/form-stepper';
 export * from './primitives/async-combobox';
+export {
+  PreviewDeviceFrame,
+  type PreviewDevice,
+} from './primitives/preview-device-frame';
+
+// ── chart primitives (Wave 9.2 — pure SVG, no external chart lib) ──
+export * from './charts';
+
+// ── runtime branding applier (Wave 8.4) ──
+export {
+  AppBrandingProvider,
+  useAppBranding,
+  APP_PRIMARY_COLOR_VAR,
+  type AppBrandingProviderProps,
+  type AppBrandingContextValue,
+} from './branding/app-branding-provider';
 
 // ── Xema chrome ──
 export { default as ErrorCard, type ErrorMessageFormatter } from './chrome/ErrorCard';
@@ -66,3 +86,5 @@ export { StateCard } from './chrome/StateCard';
 export { default as PageHeader, PageToolbar } from './chrome/PageHeader';
 export { default as LoadingState, type LoadingStateVariant } from './chrome/LoadingState';
 export { default as AsyncBoundary } from './chrome/AsyncBoundary';
+
+export { PdfPreview, type PdfPreviewProps } from './pdf/pdf-preview';

package/src/ui/pdf/pdf-preview.tsx

@@ -0,0 +1,122 @@
+'use client';
+
+/**
+ * PdfPreview — a reusable, canvas-rendered PDF viewer with in-app zoom, for any
+ * web biome or host surface (exported from `@xemahq/ui-kernel/ui`).
+ *
+ * WHY canvas, not an `<iframe>`: the bytes are frequently UNTRUSTED (user
+ * uploads, third-party artifacts). pdf.js renders each page to a `<canvas>` with
+ * NO iframe and NO script execution — strictly safer than embedding the file in
+ * a browser viewer — while giving zoom controls a fully-sandboxed iframe cannot.
+ * Text/annotation layers are disabled: this is a PREVIEW, not an editor.
+ *
+ * The component only renders from a resolved `url` (durable publicUrl, dataUrl,
+ * or `blob:`); the caller owns fetching/authing/revoking that URL.
+ */
+import { RotateCcw, ZoomIn, ZoomOut } from 'lucide-react';
+import { useCallback, useMemo, useState, type JSX } from 'react';
+import { Document, Page, pdfjs } from 'react-pdf';
+
+import { cn } from '../cn';
+
+// The pdf.js worker is loaded same-origin (CSP-safe, and CJS-build-safe — no
+// `import.meta`). The HOST app must serve the version-matched worker at this
+// path — host-web copies `pdfjs-dist/build/pdf.worker.min.mjs` into `public/`
+// via its `copy-pdf-worker` script (run on predev/prebuild). Overridable before
+// first render for hosts that serve it elsewhere.
+if (!pdfjs.GlobalWorkerOptions.workerSrc) {
+  pdfjs.GlobalWorkerOptions.workerSrc = '/pdf.worker.min.mjs';
+}
+
+const MIN_SCALE = 0.5;
+const MAX_SCALE = 3;
+const STEP = 0.25;
+const DEFAULT_SCALE = 1;
+
+const clampScale = (s: number): number =>
+  Math.min(MAX_SCALE, Math.max(MIN_SCALE, Math.round(s * 100) / 100));
+
+export interface PdfPreviewProps {
+  /** A resolved, fetchable URL: durable `publicUrl`, `dataUrl`, or `blob:`. */
+  readonly url: string;
+  /** Human label shown in the toolbar / used as the document title. */
+  readonly title?: string;
+  readonly className?: string;
+}
+
+export function PdfPreview({ url, title, className }: PdfPreviewProps): JSX.Element {
+  const [numPages, setNumPages] = useState(0);
+  const [scale, setScale] = useState(DEFAULT_SCALE);
+  const [error, setError] = useState<string | null>(null);
+
+  // Stable `file` identity so react-pdf doesn't re-fetch on every render.
+  const file = useMemo(() => ({ url }), [url]);
+
+  const zoomOut = useCallback(() => setScale((s) => clampScale(s - STEP)), []);
+  const zoomIn = useCallback(() => setScale((s) => clampScale(s + STEP)), []);
+  const reset = useCallback(() => setScale(DEFAULT_SCALE), []);
+
+  const btn =
+    'inline-flex h-7 w-7 items-center justify-center rounded text-neutral-600 ' +
+    'hover:bg-neutral-200/70 disabled:pointer-events-none disabled:opacity-40 ' +
+    'focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1';
+
+  return (
+    <div
+      className={cn(
+        'flex h-[520px] flex-col overflow-hidden rounded border border-neutral-200 bg-white',
+        className,
+      )}
+    >
+      <div className="flex items-center gap-1 border-b border-neutral-200 bg-neutral-50 px-2 py-1">
+        <button type="button" onClick={zoomOut} disabled={scale <= MIN_SCALE} aria-label="Zoom out" className={btn}>
+          <ZoomOut className="h-4 w-4" />
+        </button>
+        <span className="w-12 text-center text-xs tabular-nums text-neutral-500">
+          {Math.round(scale * 100)}%
+        </span>
+        <button type="button" onClick={zoomIn} disabled={scale >= MAX_SCALE} aria-label="Zoom in" className={btn}>
+          <ZoomIn className="h-4 w-4" />
+        </button>
+        <button type="button" onClick={reset} disabled={scale === DEFAULT_SCALE} aria-label="Reset zoom" className={btn}>
+          <RotateCcw className="h-4 w-4" />
+        </button>
+        {title ? (
+          <span className="ml-2 min-w-0 flex-1 truncate text-xs text-neutral-400" title={title}>
+            {title}
+          </span>
+        ) : null}
+      </div>
+
+      <div className="flex-1 overflow-auto bg-neutral-100 p-3">
+        {error ? (
+          <div className="p-4 text-xs text-neutral-500">
+            Couldn&apos;t render this PDF ({error}). Use the download affordance.
+          </div>
+        ) : (
+          <Document
+            file={file}
+            onLoadSuccess={({ numPages: n }) => {
+              setNumPages(n);
+              setError(null);
+            }}
+            onLoadError={(e) => setError(e.message)}
+            loading={<div className="p-4 text-xs text-neutral-500">Loading PDF…</div>}
+            className="flex flex-col items-center gap-3"
+          >
+            {Array.from({ length: numPages }, (_, i) => (
+              <Page
+                key={i}
+                pageNumber={i + 1}
+                scale={scale}
+                renderTextLayer={false}
+                renderAnnotationLayer={false}
+                className="shadow-sm"
+              />
+            ))}
+          </Document>
+        )}
+      </div>
+    </div>
+  );
+}