portal-mojo 0.1.0

package/src/admin/storage/storage-dialogs.tsx

@@ -0,0 +1,80 @@
+import { useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { CollectionSelect, modal } from '../../ui';
+import { useCan } from '../../client';
+import {
+    GROUP_DIRECTORY_PERMS, USER_DIRECTORY_PERMS, SUPPORTED_FILE_MANAGER_BACKENDS,
+    saveFileManagerAtomic, storageRefreshFailure, storageRelationId, type FileManagerRow, type RelationRow,
+} from './models';
+
+type ManagerEditorMode = 'create' | 'general' | 'credentials' | 'owner';
+
+function ManagerEditor({ row, mode, close }: { row: FileManagerRow | null; mode: ManagerEditorMode; close: (value: FileManagerRow | null) => void }) {
+    const queryClient = useQueryClient();
+    const groupDirectory = useCan(GROUP_DIRECTORY_PERMS).can;
+    const userDirectory = useCan(USER_DIRECTORY_PERMS).can;
+    const me = useCan([]).me;
+    const inFlight = useRef(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+    const [name, setName] = useState(row?.name ?? '');
+    const [use, setUse] = useState(row?.use ?? 'uploads');
+    const [backendType, setBackendType] = useState(row?.backend_type && ['file', 's3'].includes(row.backend_type) ? row.backend_type : 'file');
+    const [backendUrl, setBackendUrl] = useState(row?.backend_url ?? '');
+    const [active, setActive] = useState(row?.is_active ?? true);
+    const [isDefault, setDefault] = useState(row?.is_default ?? false);
+    const [isPublic, setPublic] = useState(row?.is_public ?? false);
+    const [region, setRegion] = useState(row?.aws_region ?? '');
+    const [key, setKey] = useState('');
+    const [secret, setSecret] = useState('');
+    const [origins, setOrigins] = useState((row?.allowed_origins ?? []).join('\n'));
+    const [group, setGroup] = useState<number | null>(storageRelationId(row?.group));
+    const [user, setUser] = useState<number | null>(storageRelationId(row?.user));
+    const canSystem = Boolean(me?.is_superuser);
+
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        if (inFlight.current) return;
+        setError('');
+        const ownerMode = mode === 'create' || mode === 'owner';
+        if (ownerMode && !canSystem && group == null && user == null) { setError('Choose an authorized group or user owner.'); return; }
+        if ((mode === 'create' || mode === 'general') && row && row.is_public !== isPublic) {
+            const ok = await modal.confirm({ title: isPublic ? 'Make backend public?' : 'Make backend private?', message: 'This changes prefix policy on the backing storage provider. Continue only after reviewing the blast radius.', confirmText: isPublic ? 'Make public' : 'Make private', danger: isPublic });
+            if (!ok) return;
+        }
+        const changes: Record<string, unknown> = mode === 'credentials'
+            ? { aws_region: region || null, aws_key: key, aws_secret: secret, allowed_origins: origins.split(/\r?\n/).map((value) => value.trim()).filter(Boolean) }
+            : mode === 'owner'
+                ? { group, user }
+                : { name, use, backend_type: backendType, backend_url: backendUrl, is_active: active, is_default: isDefault, is_public: mode === 'create' ? false : isPublic, allowed_origins: origins.split(/\r?\n/).map((value) => value.trim()).filter(Boolean), ...(ownerMode ? { group, user } : {}) };
+        inFlight.current = true; setBusy(true);
+        try {
+            const saved = await saveFileManagerAtomic({ queryClient, id: row?.id ?? null, changes, ...(ownerMode ? { expectedOwner: { group, user } } : {}) });
+            close(saved);
+        } catch (cause) {
+            const primary = cause instanceof Error ? cause.message : 'Backend save failed';
+            setError(storageRefreshFailure(cause) === undefined
+                ? primary
+                : `${primary} Authoritative refresh also failed; refresh before another action.`);
+        } finally { inFlight.current = false; setBusy(false); }
+    };
+
+    return <div className="modal-pad storage-manager-editor"><h2 className="modal-title">{mode === 'create' ? 'Create storage backend' : mode === 'credentials' ? 'Update credentials' : mode === 'owner' ? 'Change owner scope' : 'Edit storage backend'}</h2>{error && <div className="form-alert">{error}</div>}<form onSubmit={(event) => void submit(event)}>
+        {(mode === 'create' || mode === 'general') && <div className="form-grid">
+            <label className="field"><span className="field-label">Name</span><input value={name} onChange={(event) => setName(event.target.value)} required /></label>
+            <label className="field"><span className="field-label">Use</span><input value={use} onChange={(event) => setUse(event.target.value)} required /></label>
+            <label className="field"><span className="field-label">Backend</span><select value={backendType} disabled={mode !== 'create'} onChange={(event) => setBackendType(event.target.value)}>{SUPPORTED_FILE_MANAGER_BACKENDS.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}</select></label>
+            <label className="field"><span className="field-label">Backend URL</span><input value={backendUrl} onChange={(event) => setBackendUrl(event.target.value)} required /></label>
+            <label className="field switch-field"><input type="checkbox" checked={active} onChange={(event) => setActive(event.target.checked)} /> Active</label>
+            <label className="field switch-field"><input type="checkbox" checked={isDefault} onChange={(event) => setDefault(event.target.checked)} /> Default</label>
+            {mode === 'general' && <label className="field switch-field"><input type="checkbox" checked={isPublic} onChange={(event) => setPublic(event.target.checked)} /> Public prefix</label>}
+        </div>}
+        {mode === 'credentials' && <div className="form-grid"><p className="storage-span"><b>Current key:</b> {row?.aws_key_masked || 'Not configured'} · <b>Current secret:</b> {row?.aws_secret_masked || 'Not configured'}. Blank values preserve the existing secret.</p><label className="field"><span className="field-label">AWS region</span><input value={region} onChange={(event) => setRegion(event.target.value)} /></label><label className="field"><span className="field-label">New access key</span><input value={key} onChange={(event) => setKey(event.target.value)} autoComplete="off" /></label><label className="field"><span className="field-label">New secret key</span><input type="password" value={secret} onChange={(event) => setSecret(event.target.value)} autoComplete="new-password" /></label><label className="field storage-span"><span className="field-label">Allowed origins, one per line</span><textarea value={origins} onChange={(event) => setOrigins(event.target.value)} rows={4} /></label></div>}
+        {(mode === 'create' || mode === 'owner') && <div className="storage-owner-grid">{groupDirectory && <CollectionSelect<RelationRow> endpoint="/api/group" value={group} onChange={(id) => { setGroup(id == null ? null : Number(id)); if (id != null) setUser(null); }} label="Group owner" placeholder="Search authorized groups" />}{userDirectory && <CollectionSelect<RelationRow> endpoint="/api/user" value={user} onChange={(id) => { setUser(id == null ? null : Number(id)); if (id != null) setGroup(null); }} label="User owner" labelField="display_name" placeholder="Search authorized users" />}{canSystem && <button type="button" className="btn" onClick={() => { setGroup(null); setUser(null); }}>Use System scope</button>}</div>}
+        <div className="modal-actions"><button type="button" className="btn" disabled={busy} onClick={() => close(null)}>Cancel</button><button className="btn btn-primary" disabled={busy}>{busy ? 'Saving…' : 'Save'}</button></div>
+    </form></div>;
+}
+
+export function openFileManagerEditor(mode: ManagerEditorMode, row: FileManagerRow | null = null): Promise<FileManagerRow | null> {
+    return modal.open<FileManagerRow>((close) => <ManagerEditor row={row} mode={mode} close={(value) => close(value as FileManagerRow)} />).then((value) => value ?? null);
+}

package/src/charts/CircularProgress.tsx

@@ -0,0 +1,281 @@
+// CircularProgress — SVG ring progress, ported from web-mojo
+// src/extensions/charts/CircularProgress.js (740 lines, read in full).
+// Carries: value/min/max, size presets (xs–xl) or explicit px with
+// auto-scaled stroke width, variant colors, partial arcs (gap), rotation,
+// rounded caps, gradient stroke, center value/label/icon with the
+// percentage/fraction/value formats, multi-segment mode with segment gaps,
+// and the dash-offset animation (value changes glide via CSS transition).
+//
+// Deviations, deliberate:
+//   · colors are theme tokens (variant → var(--ok)/--bad/--warn/--info/
+//     --accent; track → var(--surface2)) instead of hardcoded Bootstrap
+//     hexes; the 'dark'/'light' THEME presets are dropped — data-theme
+//     tokens make them meaningless here;
+//   · the Bootstrap-popover tooltip is dropped (no Bootstrap); pass `title`
+//     for a native tooltip or wrap the component;
+//   · the imperative API (setValue/animateTo/pulse/complete) is the `value`
+//     prop — the CSS transition animates every change;
+//   · valueFormat falls back to 'percentage' WITH a console.warn on unknown
+//     values (the source fell back silently through DataFormatter).
+import { useEffect, useId, useState } from 'react';
+
+export type CircularProgressSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
+
+const SIZE_PRESETS: Record<string, number> = { xs: 40, sm: 60, md: 80, lg: 120, xl: 180 };
+const STROKE_PRESETS: Record<string, number> = { xs: 4, sm: 6, md: 8, lg: 12, xl: 16 };
+
+function resolveSize(size: CircularProgressSize): { px: number; preset: string | null } {
+    if (typeof size === 'number' && Number.isFinite(size) && size > 0) return { px: size, preset: null };
+    if (typeof size === 'string' && SIZE_PRESETS[size] != null) return { px: SIZE_PRESETS[size]!, preset: size };
+    console.warn(`CircularProgress: unknown size "${String(size)}" — falling back to "md"`);
+    return { px: SIZE_PRESETS.md!, preset: 'md' };
+}
+
+function autoStrokeWidth(size: CircularProgressSize, px: number): number {
+    if (typeof size === 'string' && STROKE_PRESETS[size] != null) return STROKE_PRESETS[size]!;
+    if (px <= 40) return 4;
+    if (px <= 60) return 6;
+    if (px <= 80) return 8;
+    if (px <= 120) return 12;
+    return 16;
+}
+
+export type CircularProgressVariant = 'default' | 'success' | 'danger' | 'warning' | 'info';
+
+const VARIANT_COLOR: Record<CircularProgressVariant, string> = {
+    default: 'var(--accent)',
+    success: 'var(--ok)',
+    danger: 'var(--bad)',
+    warning: 'var(--warn)',
+    info: 'var(--info)',
+};
+
+export interface CircularProgressSegment {
+    value: number;
+    color?: string;
+    label?: string;
+}
+
+export type CircularProgressFormat = 'percentage' | 'fraction' | 'value';
+
+export interface CircularProgressProps {
+    value?: number;
+    min?: number;
+    max?: number;
+    size?: CircularProgressSize;
+    /** 'auto' scales with size (preset table); a number pins it. */
+    strokeWidth?: number | 'auto';
+    /** Progress color; overrides `variant`. Tokens welcome. */
+    color?: string;
+    trackColor?: string;
+    variant?: CircularProgressVariant;
+    /** Two+ stops render the stroke through an SVG linearGradient. */
+    gradientColors?: string[];
+    /** Arc start in degrees; -90 = 12 o'clock (source default). */
+    rotation?: number;
+    /** Degrees left open (0 = full circle; 90 = three-quarter gauge). */
+    gap?: number;
+    rounded?: boolean;
+    showValue?: boolean;
+    /** 'percentage' | 'fraction' | 'value'. Unknown → warn + percentage. */
+    valueFormat?: CircularProgressFormat;
+    /** Wins over valueFormat. */
+    valueFormatter?: (value: number, min: number, max: number) => string;
+    /** Small line under the center value. */
+    label?: string;
+    /** Icon class replaces the center value ('bi bi-check-lg'). */
+    icon?: string;
+    /** Multi-segment mode — replaces `value`. Total > max warns + clamps visually. */
+    segments?: CircularProgressSegment[];
+    /** Degrees between segments. */
+    segmentGap?: number;
+    animate?: boolean;
+    animationDuration?: number;
+    onClick?: () => void;
+    title?: string;
+    className?: string;
+}
+
+export function CircularProgress({
+    value = 0,
+    min = 0,
+    max = 100,
+    size = 'md',
+    strokeWidth = 'auto',
+    color,
+    trackColor = 'var(--surface2)',
+    variant = 'default',
+    gradientColors,
+    rotation = -90,
+    gap = 0,
+    rounded = true,
+    showValue = true,
+    valueFormat = 'percentage',
+    valueFormatter,
+    label,
+    icon,
+    segments,
+    segmentGap = 2,
+    animate = true,
+    animationDuration = 600,
+    onClick,
+    title,
+    className = '',
+}: CircularProgressProps) {
+    const uid = useId();
+    const gradientId = `cprog-grad-${uid}`;
+
+    const { px, preset } = resolveSize(size);
+    const sw = strokeWidth === 'auto' || strokeWidth == null ? autoStrokeWidth(size, px) : strokeWidth;
+
+    let mainColor = color ?? VARIANT_COLOR[variant];
+    if (color == null && VARIANT_COLOR[variant] == null) {
+        console.warn(`CircularProgress: unknown variant "${String(variant)}" — falling back to "default"`);
+        mainColor = VARIANT_COLOR.default;
+    }
+    const useGradient = Array.isArray(gradientColors) && gradientColors.length > 1;
+    const strokePaint = useGradient ? `url(#${gradientId})` : mainColor;
+
+    const center = px / 2;
+    const radius = (px - sw) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const arcDeg = gap > 0 ? 360 - gap : 360;
+    const arcLen = (arcDeg / 360) * circumference;
+
+    const range = max - min;
+    const pctOf = (v: number): number => (range === 0 ? 0 : ((v - min) / range) * 100);
+    const clamped = Math.max(min, Math.min(max, value));
+    const percentage = pctOf(clamped);
+
+    // Mount-from-empty so the first paint animates like the source did:
+    // render offset=arcLen for one frame, then transition to the target.
+    const [mounted, setMounted] = useState(!animate);
+    useEffect(() => {
+        if (!animate) return;
+        const raf = requestAnimationFrame(() => setMounted(true));
+        return () => cancelAnimationFrame(raf);
+    }, [animate]);
+
+    const transition = animate ? `stroke-dashoffset ${animationDuration}ms ease-out` : undefined;
+
+    const segList = Array.isArray(segments) && segments.length > 0 ? segments : null;
+    if (segList) {
+        const totalSeg = segList.reduce((s, seg) => s + (seg.value || 0), 0);
+        if (totalSeg > max) {
+            console.warn('CircularProgress: segment total exceeds max — the overflow is clipped to the arc');
+        }
+    }
+
+    const formatCenter = (): string => {
+        if (valueFormatter) return valueFormatter(clamped, min, max);
+        switch (valueFormat) {
+            case 'percentage': return `${Math.round(percentage)}%`;
+            case 'fraction': return `${clamped}/${max}`;
+            case 'value': return String(clamped);
+            default:
+                console.warn(`CircularProgress: unknown valueFormat "${String(valueFormat)}" — falling back to "percentage"`);
+                return `${Math.round(percentage)}%`;
+        }
+    };
+
+    // Segment geometry: running dash offsets along the arc (source verbatim,
+    // including the gapLen between painted segments).
+    let runningOffset = 0;
+    const segmentEls = (segList ?? []).map((seg, i) => {
+        const segLen = (pctOf(min + (seg.value || 0)) / 100) * arcLen;
+        const gapLen = (segmentGap / 360) * circumference;
+        if (segLen <= 0) return null;
+        const offset = -runningOffset;
+        runningOffset += segLen + gapLen;
+        return (
+            <circle
+                key={i}
+                cx={center} cy={center} r={radius}
+                fill="none"
+                stroke={seg.color ?? mainColor}
+                strokeWidth={sw}
+                strokeLinecap={rounded ? 'round' : 'butt'}
+                strokeDasharray={`${segLen} ${circumference}`}
+                strokeDashoffset={mounted ? offset : arcLen}
+                transform={`rotate(${rotation} ${center} ${center})`}
+                style={{ transition, transitionDelay: animate ? `${i * 100}ms` : undefined }}
+                className="cprog-segment"
+            >
+                {seg.label != null && <title>{seg.label}</title>}
+            </circle>
+        );
+    });
+
+    const progressLen = (percentage / 100) * arcLen;
+    const dashOffset = arcLen - progressLen;
+
+    const clickable = onClick != null;
+    const rootClass = [
+        'cprog',
+        preset ? `cprog-${preset}` : '',
+        clickable ? 'cprog-clickable' : '',
+        className,
+    ].filter(Boolean).join(' ');
+    const rootStyle = { width: px, height: px };
+
+    const body = (
+        <>
+            <svg width={px} height={px} viewBox={`0 0 ${px} ${px}`} className="cprog-svg" role="img">
+                {useGradient && (
+                    <defs>
+                        <linearGradient id={gradientId} x1="0%" y1="0%" x2="100%" y2="100%">
+                            {gradientColors!.map((c, i) => (
+                                <stop key={i} offset={`${(i / (gradientColors!.length - 1)) * 100}%`} stopColor={c} />
+                            ))}
+                        </linearGradient>
+                    </defs>
+                )}
+                <circle
+                    cx={center} cy={center} r={radius}
+                    fill="none"
+                    stroke={trackColor}
+                    strokeWidth={sw}
+                    strokeLinecap={rounded ? 'round' : 'butt'}
+                    strokeDasharray={gap > 0 ? `${arcLen} ${circumference}` : undefined}
+                    transform={`rotate(${rotation} ${center} ${center})`}
+                />
+                {segList ? segmentEls : (
+                    <circle
+                        cx={center} cy={center} r={radius}
+                        fill="none"
+                        stroke={strokePaint}
+                        strokeWidth={sw}
+                        strokeLinecap={rounded ? 'round' : 'butt'}
+                        strokeDasharray={`${arcLen} ${circumference}`}
+                        strokeDashoffset={mounted ? dashOffset : arcLen}
+                        transform={`rotate(${rotation} ${center} ${center})`}
+                        style={{ transition }}
+                        className="cprog-bar"
+                    />
+                )}
+            </svg>
+            <div className="cprog-center">
+                {icon ? (
+                    <i className={icon} aria-hidden="true" />
+                ) : showValue ? (
+                    <>
+                        <div className="cprog-value">{formatCenter()}</div>
+                        {label && <div className="cprog-label">{label}</div>}
+                    </>
+                ) : label ? (
+                    <div className="cprog-label">{label}</div>
+                ) : null}
+            </div>
+        </>
+    );
+
+    return clickable ? (
+        <button type="button" className={rootClass} style={rootStyle} onClick={onClick} title={title}>
+            {body}
+        </button>
+    ) : (
+        <div className={rootClass} style={rootStyle} title={title}>
+            {body}
+        </div>
+    );
+}

package/src/charts/KPIStrip.tsx

@@ -0,0 +1,162 @@
+// KPIStrip — a responsive row of KPITiles fed by ONE batched metrics fetch.
+// Ported from web-mojo src/extensions/charts/KPIStrip.js (273 lines, read in
+// full), re-shaped for the one-cache world:
+//
+//   · ONE /api/metrics/fetch (via mojoMetrics — the single normalize
+//     boundary) covers values, deltas AND sparklines: value = the latest
+//     bucket, delta = latest − previous, deltaPct omitted when the previous
+//     bucket was 0 (the tile then shows the absolute delta — the same
+//     convention /api/metrics/series?with_delta=true uses on the wire, so a
+//     later server-delta variant is a drop-in).
+//   · The source's parallel REST count tiles are the `value` override on a
+//     spec: pages already have count queries (size:0) — pass the number in
+//     rather than teaching the strip a second fetch path. `sparklineSlug`
+//     still lets a count tile borrow a metric trail + delta (source
+//     feature).
+//
+// A slug the response does not carry renders '—' and warns once — a missing
+// metric is a config bug, not a silent blank.
+import { useEffect, useRef, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { mojoMetrics } from '../client/client';
+import type { Params } from '../client/types';
+import { KPITile, type KpiSeverity, type KpiTone } from './KPITile';
+import { quickRangeWindow } from './stats';
+
+export interface KpiTileSpec {
+    /** Metric slug — drives value/delta/sparkline from the batched fetch. */
+    slug?: string;
+    /** Identity for onTileClick when there is no slug. */
+    key?: string;
+    label: string;
+    tone?: KpiTone | null;
+    severity?: KpiSeverity | null;
+    formatter?: (v: number) => string;
+    /**
+     * Caller-supplied value (count tiles — the source's REST tiles). Wins
+     * over the metric value; undefined means "metric tile".
+     */
+    value?: number | string | null;
+    /** Borrow a metric's trail (and its delta) for a caller-value tile. */
+    sparklineSlug?: string;
+}
+
+export interface KPIStripProps {
+    tiles: KpiTileSpec[];
+    account?: string;
+    /** Bucket size for the window — 'days' gives day-over-day deltas. */
+    granularity?: string;
+    /** Quick range fetched for the sparklines ('7d' default, source parity). */
+    range?: string;
+    sparklineHeight?: number;
+    /** Extra wire params merged under the built-ins. */
+    apiParams?: Params;
+    onTileClick?: (e: { slug: string | null; key: string }) => void;
+    className?: string;
+}
+
+export function KPIStrip({
+    tiles,
+    account = 'global',
+    granularity = 'days',
+    range = '7d',
+    sparklineHeight = 36,
+    apiParams,
+    onTileClick,
+    className = '',
+}: KPIStripProps) {
+    const slugs = Array.from(new Set([
+        ...tiles.map((t) => t.slug).filter((s): s is string => !!s),
+        ...tiles.map((t) => t.sparklineSlug).filter((s): s is string => !!s),
+    ]));
+
+    // Window anchored once per mount — a stable key; web-mojo stamped its
+    // window at construction the same way.
+    const [anchor] = useState(() => Date.now());
+    const { startMs, endMs } = quickRangeWindow(range, anchor);
+    const wire: Params = {
+        ...apiParams,
+        slugs: slugs.join(','),
+        granularity,
+        account,
+        // `range` is the mock's window param; dt_start/dt_end (epoch seconds)
+        // are the real backend's. Send both — each side ignores the other's.
+        range,
+        dt_start: Math.floor(startMs / 1000),
+        dt_end: Math.floor(endMs / 1000),
+    };
+
+    const query = useQuery({
+        queryKey: ['metrics', wire],
+        queryFn: () => mojoMetrics(wire),
+        enabled: slugs.length > 0,
+    });
+
+    const warnedRef = useRef<Set<string>>(new Set());
+    useEffect(() => {
+        if (!query.data) return;
+        const have = new Set(query.data.datasets.map((d) => d.label));
+        for (const slug of slugs) {
+            if (!have.has(slug) && !warnedRef.current.has(slug)) {
+                warnedRef.current.add(slug);
+                console.warn(`KPIStrip: metrics response carries no series for slug "${slug}" — tile shows '—'`);
+            }
+        }
+        // slugs is derived from tiles; the join is its identity.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [query.data, slugs.join(',')]);
+
+    const seriesFor = (slug: string | undefined): number[] | null => {
+        if (!slug || !query.data) return null;
+        const ds = query.data.datasets.find((d) => d.label === slug);
+        return ds ? ds.data : null;
+    };
+
+    return (
+        <div className={`kpi-strip${className ? ` ${className}` : ''}`}>
+            {query.isError && (
+                <div className="kpi-strip-error" role="alert">
+                    <i className="bi bi-exclamation-triangle" />
+                    <span>{query.error instanceof Error ? query.error.message : 'Failed to load metrics'}</span>
+                    <button className="btn btn-compact" onClick={() => void query.refetch()}>Retry</button>
+                </div>
+            )}
+            <div className="kpi-strip-grid">
+                {tiles.map((spec, i) => {
+                    const trail = seriesFor(spec.slug ?? spec.sparklineSlug);
+                    const latest = trail && trail.length > 0 ? trail[trail.length - 1]! : null;
+                    const prev = trail && trail.length > 1 ? trail[trail.length - 2]! : null;
+
+                    let delta: number | null = null;
+                    let deltaPct: number | null = null;
+                    if (latest != null && prev != null) {
+                        delta = latest - prev;
+                        // prev 0 → pct omitted; the tile falls back to the
+                        // absolute delta (never Infinity%).
+                        deltaPct = prev === 0 ? null : ((latest - prev) / Math.abs(prev)) * 100;
+                    }
+
+                    const isMetricTile = spec.value === undefined;
+                    const value = isMetricTile ? latest : spec.value;
+                    const key = spec.key ?? spec.slug ?? `tile-${i}`;
+                    return (
+                        <KPITile
+                            key={key}
+                            label={spec.label}
+                            value={value}
+                            formatter={spec.formatter}
+                            delta={delta}
+                            deltaPct={deltaPct}
+                            tone={spec.tone ?? null}
+                            severity={spec.severity ?? null}
+                            sparkline={trail}
+                            sparklineHeight={sparklineHeight}
+                            loading={isMetricTile && !!spec.slug && query.isPending}
+                            onClick={onTileClick ? () => onTileClick({ slug: spec.slug ?? null, key }) : undefined}
+                        />
+                    );
+                })}
+            </div>
+        </div>
+    );
+}

package/src/charts/KPITile.tsx

@@ -0,0 +1,125 @@
+// KPITile — compact dashboard tile: small label, big tabular-numerals value,
+// color-coded delta badge, embedded sparkline. Ported from web-mojo
+// src/extensions/charts/KPITile.js (176 lines, read in full).
+//
+// Presentation-only, exactly like the source: no fetch, no settings — one
+// parent (KPIStrip, or any page) fetches once and feeds many tiles. The
+// delta logic is the source's, verbatim via deltaBadge(): finite deltaPct →
+// "+12%"; pct absent (prev was 0) but delta present → "+4" absolute; both
+// absent → no badge. Never renders Infinity%. `tone` decides whether rising
+// is green or red; `severity` adds the left-stripe accent.
+//
+// Deviation: severity/spark colors are theme tokens ('high' shares the warn
+// token — there is no orange in the 8-token palette), and the value
+// formatter is a typed function.
+import type { ReactNode } from 'react';
+import { MiniChart } from './MiniChart';
+import { deltaBadge } from './stats';
+
+export type KpiSeverity = 'critical' | 'high' | 'warn' | 'info' | 'good';
+export type KpiTone = 'good' | 'bad';
+
+const SEVERITY_COLOR: Record<KpiSeverity, string> = {
+    critical: 'var(--bad)',
+    high: 'var(--warn)',
+    warn: 'var(--warn)',
+    info: 'var(--info)',
+    good: 'var(--ok)',
+};
+
+const KNOWN_SEVERITIES: readonly KpiSeverity[] = ['critical', 'high', 'warn', 'info', 'good'];
+
+export interface KPITileProps {
+    label: string;
+    /** null → '—'. Strings render verbatim; numbers go through `formatter`. */
+    value: number | string | null | undefined;
+    formatter?: (v: number) => string;
+    /** Absolute change vs the comparison bucket. */
+    delta?: number | null;
+    /** Percent change; omit when the previous bucket was 0. */
+    deltaPct?: number | null;
+    /** 'bad' = rising is bad (errors); 'good' = rising is good. Default neutral. */
+    tone?: KpiTone | null;
+    /** Left-stripe accent for tiles that ARE the alert. */
+    severity?: KpiSeverity | null;
+    sparkline?: readonly number[] | null;
+    sparklineColor?: string;
+    sparklineHeight?: number;
+    /** Extra line under the value (the strip does not use it; pages may). */
+    hint?: ReactNode;
+    onClick?: () => void;
+    /** Skeleton state — value/badge render as shimmer placeholders. */
+    loading?: boolean;
+    className?: string;
+}
+
+export function KPITile({
+    label,
+    value,
+    formatter,
+    delta = null,
+    deltaPct = null,
+    tone = null,
+    severity = null,
+    sparkline = null,
+    sparklineColor,
+    sparklineHeight = 36,
+    hint,
+    onClick,
+    loading = false,
+    className = '',
+}: KPITileProps) {
+    let sev: KpiSeverity | null = severity;
+    if (sev != null && !KNOWN_SEVERITIES.includes(sev)) {
+        console.warn(`KPITile: unknown severity "${String(severity)}" — ignoring`);
+        sev = null;
+    }
+
+    const display = value == null
+        ? '—'
+        : typeof value === 'number'
+            ? (formatter ? formatter(value) : value.toLocaleString())
+            : String(value);
+
+    const badge = deltaBadge(delta, deltaPct, tone);
+    // Default to the info tone when no severity is set — a neutral grey line
+    // blends into the dark surface (source note carried over).
+    const sparkColor = sparklineColor ?? (sev ? SEVERITY_COLOR[sev] : 'var(--info)');
+    const hasSpark = Array.isArray(sparkline) && sparkline.length > 1;
+
+    const rootClass = `kpi-tile${sev ? ` kpi-tile-${sev}` : ''}${onClick ? ' kpi-tile-clickable' : ''}${className ? ` ${className}` : ''}`;
+    const body = (
+        <>
+            <span className="kpi-tile-label">{label}</span>
+            {loading ? (
+                <span className="kpi-tile-value"><span className="skel skel-w-60" /></span>
+            ) : (
+                <span className="kpi-tile-value">{display}</span>
+            )}
+            {!loading && badge && <span className={`kpi-tile-delta kpi-tile-delta-${badge.tone}`}>{badge.text}</span>}
+            {!loading && hint != null && <span className="kpi-tile-hint">{hint}</span>}
+            <span className="kpi-tile-spark">
+                {hasSpark && (
+                    <MiniChart
+                        data={sparkline as number[]}
+                        chartType="line"
+                        height={sparklineHeight}
+                        color={sparkColor}
+                        fill
+                        smoothing={0.3}
+                        showTooltip={false}
+                        showCrosshair={false}
+                        padding={2}
+                        animate={false}
+                    />
+                )}
+            </span>
+        </>
+    );
+
+    return onClick ? (
+        <button type="button" className={rootClass} onClick={onClick}>{body}</button>
+    ) : (
+        <div className={rootClass}>{body}</div>
+    );
+}