@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/composite/order-status-data.js

@@ -0,0 +1,202 @@
+// widgets/composite/order-status-data.ts: the pure half of order-status. It
+// turns the model's props into what the template only paints: a known status,
+// the step list with one state per step, the headline, the label of the when
+// line, clean events and actions, and finite map points. Nothing here throws;
+// bad items are skipped and bad fields degrade.
+//
+// Step rule (one place): steps before the active index are done; the active
+// one is current, or done once the pipeline is finished; a step with
+// `failed: true` is failed and becomes the active index whatever `status`
+// says, and the steps after it are pending behind dotted connectors. On the
+// default pipelines a failed or cancelled status with no failed step hides
+// the rail (the headline and pill carry it); on custom steps it marks the
+// current step failed. The last step is done, not in progress, once status
+// lands on it or it has `completedAt`; an explicit `current` on it without
+// either stays in progress.
+//
+// Status is read leniently: case, spaces and underscores are folded and a few
+// common words alias onto the known set (shipped is in-transit). A custom
+// step whose id is the raw word still matches it first.
+import { asText } from '@ripple-ui/core';
+import { plain } from '../data-kit/format.js';
+import { safeArray, uniqueKeys } from '../../utils/safe-props.js';
+const KNOWN = [
+    'placed',
+    'confirmed',
+    'preparing',
+    'in-transit',
+    'out-for-delivery',
+    'delivered',
+    'ready-for-pickup',
+    'picked-up',
+    'failed',
+    'cancelled'
+];
+const ALIAS = {
+    shipped: 'in-transit',
+    dispatched: 'in-transit',
+    canceled: 'cancelled',
+    ready: 'ready-for-pickup',
+    completed: 'delivered',
+    complete: 'delivered'
+};
+const DELIVERY_STEPS = [
+    ['placed', 'Placed'],
+    ['confirmed', 'Confirmed'],
+    ['preparing', 'Preparing'],
+    ['in-transit', 'In transit'],
+    ['out-for-delivery', 'Out for delivery'],
+    ['delivered', 'Delivered']
+].map(([id, label]) => ({ id, label, description: '', completedAt: '' }));
+const PICKUP_STEPS = [
+    ['placed', 'Placed'],
+    ['confirmed', 'Confirmed'],
+    ['preparing', 'Preparing'],
+    ['ready-for-pickup', 'Ready for pickup'],
+    ['picked-up', 'Picked up']
+].map(([id, label]) => ({ id, label, description: '', completedAt: '' }));
+/** Updates shown before the fold. */
+export const EVENT_FOLD = 4;
+/** The written status folded to a key: trimmed, lower case, spaces and underscores to `-`. */
+export function statusKey(v) {
+    return asText(v).trim().toLowerCase().replace(/[\s_]+/g, '-');
+}
+/** A known status, through the aliases; anything else is undefined. */
+export function normStatus(v) {
+    const k = statusKey(v);
+    if (KNOWN.includes(k))
+        return k;
+    return ALIAS[k];
+}
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** The step list and per-step states (see the rule in the header). */
+export function progress(rawSteps, rawStatus, currentStep) {
+    const status = normStatus(rawStatus);
+    const key = statusKey(rawStatus);
+    const custom = safeArray(rawSteps).filter(isRecord);
+    const pipeline = custom.length
+        ? 'custom'
+        : status === 'ready-for-pickup' || status === 'picked-up'
+            ? 'pickup'
+            : 'delivery';
+    const steps = pipeline === 'custom'
+        ? custom.map((s, i) => ({
+            id: asText(s.id) || String(i),
+            label: plain(s.label) || plain(s.id) || `Step ${i + 1}`,
+            description: plain(s.description),
+            completedAt: plain(s.completedAt)
+        }))
+        : (pipeline === 'pickup' ? PICKUP_STEPS : DELIVERY_STEPS).map((s) => ({ ...s }));
+    const flags = pipeline === 'custom' ? custom : [];
+    const bad = status === 'failed' || status === 'cancelled' ? status : undefined;
+    const last = steps.length - 1;
+    const find = (id) => (id ? steps.findIndex((s) => s.id === id) : -1);
+    const failedStep = flags.findIndex((s) => s.failed === true);
+    // The step the order is at, ignoring failure.
+    let at = find(asText(currentStep));
+    if (at < 0 && !bad)
+        at = find(key) >= 0 ? find(key) : status ? find(status) : -1;
+    if (at < 0)
+        at = flags.findIndex((s) => s.current === true);
+    if (at < 0) {
+        const open = steps.findIndex((s) => !s.completedAt);
+        at = open >= 0 ? open : last;
+    }
+    let failedAt = -1;
+    if (failedStep >= 0)
+        failedAt = failedStep;
+    else if (bad && pipeline === 'custom')
+        failedAt = at;
+    const anyBad = failedAt >= 0 ? (bad ?? 'failed') : bad;
+    const showRail = !(bad && failedAt < 0);
+    const active = !showRail ? -1 : failedAt >= 0 ? failedAt : at;
+    const finished = !anyBad && active === last && (key === steps[last]?.id || status === steps[last]?.id || Boolean(steps[last]?.completedAt));
+    const states = steps.map((_, i) => {
+        if (!showRail)
+            return 'pending';
+        if (i < active)
+            return 'done';
+        if (i > active)
+            return 'pending';
+        return failedAt >= 0 ? 'failed' : finished ? 'done' : 'active';
+    });
+    return { pipeline, steps, states, active, finished, bad: anyBad, showRail };
+}
+/** The card's headline: the title, else what the steps say now. */
+export function headline(title, p) {
+    const t = plain(title);
+    if (t)
+        return t;
+    if (p.bad === 'cancelled')
+        return 'Order cancelled';
+    if (p.bad)
+        return p.active >= 0 ? p.steps[p.active].label : 'Delivery failed';
+    if (p.finished)
+        return p.steps[p.steps.length - 1]?.label ?? 'Delivered';
+    return p.steps[p.active]?.label ?? 'Order status';
+}
+const firstWord = (t) => t.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+/**
+ * The word before the ETA value, or '' when the value already opens with the
+ * label's first word ("Next attempt tomorrow" needs no "Next step").
+ */
+export function etaLabel(p, eta = '') {
+    const label = p.bad
+        ? 'Next step'
+        : p.finished
+            ? (p.steps[p.steps.length - 1]?.label ?? 'Delivered')
+            : p.pipeline === 'pickup'
+                ? 'Pickup'
+                : 'Estimated arrival';
+    return eta && firstWord(eta) === firstWord(label) ? '' : label;
+}
+/** Events as given (newest first, never sorted); a label-less one is dropped. */
+export function cleanEvents(raw) {
+    const rows = safeArray(raw)
+        .filter(isRecord)
+        .map((e) => ({ label: plain(e.label), time: plain(e.time), location: plain(e.location), icon: asText(e.icon).trim() }))
+        .filter((e) => e.label);
+    const keys = uniqueKeys(rows, (e) => `${e.time}|${e.label}`);
+    return rows.map((e, i) => ({ ...e, key: keys[i] }));
+}
+/** Actions that can do something: one with neither an id nor handlers is dropped. */
+export function cleanActions(raw) {
+    const rows = safeArray(raw)
+        .filter(isRecord)
+        .map((a) => {
+        const v = asText(a.variant);
+        return {
+            id: asText(a.id).trim(),
+            label: plain(a.label),
+            icon: asText(a.icon).trim(),
+            variant: (v === 'default' || v === 'ghost' ? v : a.variant == null ? 'default' : 'outline'),
+            actions: (a.actions ?? undefined)
+        };
+    })
+        .filter((a) => a.label && (a.id || a.actions));
+    const keys = uniqueKeys(rows, (a, i) => a.id || `action-${i}`);
+    return rows.map((a, i) => ({ ...a, key: keys[i] }));
+}
+/** A finite [lat, lng] from a pair or a {lat, lng} object; 0 counts, strings do not. */
+export function point(v) {
+    const lat = Array.isArray(v) ? v[0] : isRecord(v) ? v.lat : undefined;
+    const lng = Array.isArray(v) ? v[1] : isRecord(v) ? v.lng : undefined;
+    return typeof lat === 'number' && typeof lng === 'number' && Number.isFinite(lat) && Number.isFinite(lng)
+        ? [lat, lng]
+        : undefined;
+}
+/** A place with plain text and a finite point; `fallback` names it only when an address exists. */
+export function cleanPlace(v, fallback) {
+    if (!isRecord(v))
+        return undefined;
+    const address = plain(v.address);
+    const name = plain(v.name) || (address ? fallback : '');
+    return { name, address, at: point(v), listed: Boolean(name || address) };
+}
+/** Carrier and number as text (a model may send numbers); no number, no tracking. */
+export function cleanTracking(v) {
+    if (!isRecord(v))
+        return undefined;
+    const number = asText(v.number).trim();
+    return number ? { carrier: plain(v.carrier), number, url: asText(v.url).trim() } : undefined;
+}

package/dist/widgets/composite/pipeline-dashboard.d.ts

@@ -0,0 +1,92 @@
+export interface Currency {
+    /** ISO 4217 code for Intl. */
+    code?: string;
+    /** An unknown symbol, printed before a plain number. */
+    prefix?: string;
+}
+/** '$' → USD, 'usd' → USD, '₩' → prefix '₩', absent → plain numbers. */
+export declare function readCurrency(v: unknown): Currency;
+/** A non-negative number from a number or "$1,200,000"-style text, else undefined. */
+export declare function amount(v: unknown): number | undefined;
+/** An amount in the currency; compact ("$1.8M") only when asked. */
+export declare function fmtAmount(n: number, cur: Currency, compact: boolean): string;
+/** "$420k" / "+$40k" → "$420K" / "+$40K", matching money()'s compact suffix; other text is unchanged. */
+export declare const suffixCase: (s: string) => string;
+/** Money text the way the quota prints it: "¥812,400,000" → "¥812.4M" from 10,000 up, "$420k" → "$420K"; other text is unchanged. */
+export declare function moneyText(s: string): string;
+/** Whole percent, except 99.5 to just under 100 reads 99 (never 100 before the target). */
+export declare function pctLabel(p: number): string;
+export interface QuotaView {
+    label: string;
+    period: string;
+    current: string;
+    /** Present only with a usable target (finite and above 0). */
+    target?: string;
+    pct?: number;
+    pctText?: string;
+    /** '$680K to go', '€6.2K over target' or 'Target reached'. */
+    foot?: string;
+    met?: boolean;
+}
+export declare function readQuota(raw: unknown): QuotaView | undefined;
+export interface Leader {
+    key: string;
+    rank: number;
+    name: string;
+    avatar?: string;
+    /** Display value; undefined shows a muted n/a. */
+    value?: string;
+    delta?: string;
+    dir: 'up' | 'down' | 'neutral';
+    sublabel: string;
+}
+/** Ranked rows: by `position` when every row has one (ties share a rank), else input order. */
+export declare function readLeaders(items: unknown, cur?: Currency): Leader[];
+/** Stages with a number; two or more make a usable funnel (conversion then is not drawn). */
+export declare function funnelStages(funnel: unknown): {
+    label: string;
+    value: number;
+}[];
+export declare const usableFunnel: (stages: readonly {
+    value?: unknown;
+}[]) => boolean;
+export interface Rate {
+    key: string;
+    from: string;
+    to: string;
+    pct: number;
+    text: string;
+    lowest: boolean;
+}
+/** A rate in percent: 41, "28.6%", or a fraction 0.225 written without %. */
+export declare function ratePct(v: unknown): number | undefined;
+export declare function readRates(conversion: unknown): Rate[];
+/** One deal cell as display text: arrays join, objects show label/name/title/value, null is empty. */
+export declare function cellText(v: unknown): string | number;
+export interface DealColumn {
+    key: string;
+    label: string;
+    align?: 'left' | 'right' | 'center';
+}
+/**
+ * Columns (from `columns`, else the first row's keys) and display rows; empty
+ * rows drop. A number in a right-aligned column becomes text: money when the
+ * column's other cells carry a currency symbol (in the dashboard's currency,
+ * else that symbol), grouped digits otherwise. An empty first cell stays empty; Table marks it Untitled.
+ */
+export declare function readDeals(deals: unknown, cur?: Currency): {
+    title: string;
+    columns: DealColumn[];
+    rows: Record<string, string | number>[];
+};
+export interface Event {
+    key: string;
+    label: string;
+    actor: string;
+    time: string;
+    icon: string;
+}
+/** Activity rows; a row with no label says nothing and drops. */
+export declare function readTicker(ticker: unknown): Event[];
+/** "Show 5 more" / "Show 16 earlier": always the hidden count, never "Show all". */
+export declare const moreLabel: (total: number, cap: number, noun?: string) => string;

package/dist/widgets/composite/pipeline-dashboard.js

@@ -0,0 +1,208 @@
+// widgets/composite/pipeline-dashboard.ts: every data rule behind the
+// `pipeline-dashboard` widget, pure and DOM-free so it is unit-tested alone.
+// The component only lays out what these functions return.
+//
+// Props are model output, so nothing here throws: arrays go through
+// safeArray, text through plain(), numbers may arrive as "$1,200,000" or
+// "1,240". The quota reads a currency from '$', 'usd' or 'EUR' (no dollar
+// default), compacts amounts once the quota reaches 10,000, and never shows
+// a percent without a usable target. Ranks follow `position` only when every
+// leader has one. Conversion rates read fractions (0.225) and "28.6%"
+// strings; a row without a number drops. Deal cells become display text
+// (numbers stay numbers so Table still right-aligns them, except in a column
+// set to align right, where they read as grouped or money text) and empty rows
+// drop. Money text in leaders and deals reads like the quota: "$420k" takes
+// money()'s upper-case suffix ("$420K") and "¥812,400,000" compacts ("¥812.4M").
+import { safeArray, uniqueKeys } from '../../utils/safe-props.js';
+import { finite, money, num, plain } from '../data-kit/format.js';
+import { parseValue } from '../data/funnel-math.js';
+const SYMBOLS = { $: 'USD', '€': 'EUR', '£': 'GBP', '¥': 'JPY', '₹': 'INR' };
+const COMPACT_FROM = 10_000;
+/** '$' → USD, 'usd' → USD, '₩' → prefix '₩', absent → plain numbers. */
+export function readCurrency(v) {
+    const s = plain(v);
+    if (!s)
+        return {};
+    if (SYMBOLS[s])
+        return { code: SYMBOLS[s] };
+    if (/^[a-z]{3}$/i.test(s))
+        return { code: s.toUpperCase() };
+    return { prefix: s };
+}
+/** A non-negative number from a number or "$1,200,000"-style text, else undefined. */
+export function amount(v) {
+    if (typeof v !== 'string')
+        return parseValue(v);
+    return parseValue(v.trim().replace(/^[^\d.+-]+/, ''));
+}
+/** An amount in the currency; compact ("$1.8M") only when asked. */
+export function fmtAmount(n, cur, compact) {
+    if (cur.code)
+        return money(n, cur.code, compact ? { compact: true } : { whole: true });
+    return `${cur.prefix ?? ''}${num(n, { compact, digits: compact ? 1 : 0 })}`;
+}
+/** "$420k" / "+$40k" → "$420K" / "+$40K", matching money()'s compact suffix; other text is unchanged. */
+export const suffixCase = (s) => s.replace(/^([+\-−]?[$€£¥₹]\s?[\d.,]+)([kmb])$/i, (_, n, k) => n + k.toUpperCase());
+/** Money text the way the quota prints it: "¥812,400,000" → "¥812.4M" from 10,000 up, "$420k" → "$420K"; other text is unchanged. */
+export function moneyText(s) {
+    const m = /^([+\-−]?)([$€£¥₹])\s?(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?$/.exec(s);
+    const n = m ? Number(m[3].replaceAll(',', '') + (m[4] ?? '')) : NaN;
+    return m && n >= COMPACT_FROM ? m[1] + money(n, SYMBOLS[m[2]], { compact: true }) : suffixCase(s);
+}
+/** Whole percent, except 99.5 to just under 100 reads 99 (never 100 before the target). */
+export function pctLabel(p) {
+    if (p >= 99.5 && p < 100)
+        return '99%';
+    return `${Math.round(p)}%`;
+}
+export function readQuota(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const q = raw;
+    const cur = amount(q.current);
+    if (cur === undefined)
+        return undefined;
+    const goal = amount(q.target);
+    const c = readCurrency(q.currency);
+    const compact = Math.max(cur, goal ?? 0) >= COMPACT_FROM;
+    const f = (n) => fmtAmount(n, c, compact);
+    const base = { label: plain(q.label) || (goal ? 'Target' : 'Progress'), period: plain(q.period), current: f(cur) };
+    if (!goal)
+        return base;
+    const pct = (cur / goal) * 100;
+    const met = cur >= goal;
+    const foot = cur === goal ? 'Target reached' : met ? `${f(cur - goal)} over target` : `${f(goal - cur)} to go`;
+    return { ...base, target: f(goal), pct, pctText: pctLabel(pct), foot, met };
+}
+/** Ranked rows: by `position` when every row has one (ties share a rank), else input order. */
+export function readLeaders(items, cur = {}) {
+    const rows = safeArray(items).filter((x) => !!x && typeof x === 'object');
+    const pos = rows.map((r) => finite(r.position));
+    const byPos = rows.length > 0 && pos.every((p) => p !== undefined);
+    const order = rows.map((r, i) => ({ r, p: pos[i], i }));
+    if (byPos)
+        order.sort((a, b) => a.p - b.p || a.i - b.i);
+    const keys = uniqueKeys(order, (o) => plain(o.r.name) || 'unnamed');
+    return order.map(({ r, p }, i) => {
+        const v = r.value;
+        const n = typeof v === 'number' ? amount(v) : undefined;
+        const text = typeof v === 'string' ? moneyText(plain(v)) : '';
+        const value = n !== undefined ? fmtAmount(n, cur, n >= COMPACT_FROM) : text || undefined;
+        const delta = moneyText(plain(r.delta));
+        const avatar = plain(r.avatar);
+        return {
+            key: keys[i],
+            rank: byPos ? p : i + 1,
+            name: plain(r.name),
+            avatar: avatar || undefined,
+            value,
+            delta: delta || undefined,
+            dir: delta.startsWith('+') ? 'up' : /^[-−]/.test(delta) ? 'down' : 'neutral',
+            sublabel: plain(r.sublabel)
+        };
+    });
+}
+/** Stages with a number; two or more make a usable funnel (conversion then is not drawn). */
+export function funnelStages(funnel) {
+    const f = funnel && typeof funnel === 'object' ? funnel : {};
+    return safeArray(f.stages).filter((s) => !!s && typeof s === 'object');
+}
+export const usableFunnel = (stages) => stages.filter((s) => parseValue(s.value) !== undefined).length >= 2;
+/** A rate in percent: 41, "28.6%", or a fraction 0.225 written without %. */
+export function ratePct(v) {
+    if (typeof v === 'string') {
+        const s = v.trim();
+        const n = finite(s.replace(/%$/, '').trim());
+        if (n === undefined)
+            return undefined;
+        return s.endsWith('%') || n > 1 ? n : n * 100;
+    }
+    const n = finite(v);
+    return n === undefined ? undefined : n > 1 ? n : n * 100;
+}
+export function readRates(conversion) {
+    const rows = safeArray(conversion)
+        .filter((x) => !!x && typeof x === 'object')
+        .map((r) => ({ from: plain(r.from), to: plain(r.to), pct: ratePct(r.rate) }))
+        .filter((r) => r.pct !== undefined && !!(r.from || r.to));
+    const low = rows.length > 1 ? Math.min(...rows.map((r) => r.pct)) : undefined;
+    const keys = uniqueKeys(rows, (r) => `${r.from}>${r.to}`);
+    let marked = false;
+    return rows.map((r, i) => {
+        const lowest = !marked && r.pct === low;
+        if (lowest)
+            marked = true;
+        return { ...r, key: keys[i], text: `${num(r.pct, { digits: 1 })}%`, lowest };
+    });
+}
+/** One deal cell as display text: arrays join, objects show label/name/title/value, null is empty. */
+export function cellText(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : '';
+    if (Array.isArray(v))
+        return v.map(cellText).filter((x) => x !== '').join(', ');
+    if (typeof v === 'object') {
+        const o = v;
+        for (const k of ['label', 'name', 'title', 'value']) {
+            const t = cellText(o[k]);
+            if (t !== '' && (typeof o[k] !== 'object' || o[k] === null))
+                return t;
+        }
+        return '';
+    }
+    return moneyText(plain(v));
+}
+/**
+ * Columns (from `columns`, else the first row's keys) and display rows; empty
+ * rows drop. A number in a right-aligned column becomes text: money when the
+ * column's other cells carry a currency symbol (in the dashboard's currency,
+ * else that symbol), grouped digits otherwise. An empty first cell stays empty; Table marks it Untitled.
+ */
+export function readDeals(deals, cur = {}) {
+    const d = deals && typeof deals === 'object' ? deals : {};
+    const raw = safeArray(d.rows).filter((x) => !!x && typeof x === 'object' && !Array.isArray(x));
+    let columns = safeArray(d.columns)
+        .map((c) => {
+        if (typeof c === 'string')
+            return c ? { key: c, label: c } : undefined;
+        if (!c || typeof c !== 'object')
+            return undefined;
+        const o = c;
+        const key = plain(o.key ?? o.accessorKey);
+        if (!key)
+            return undefined;
+        const align = o.align === 'left' || o.align === 'right' || o.align === 'center' ? o.align : undefined;
+        return { key, label: plain(o.label ?? o.header) || key, align };
+    })
+        .filter((c) => !!c);
+    if (!columns.length && raw[0])
+        columns = Object.keys(raw[0]).map((k) => ({ key: k, label: k }));
+    const rows = raw
+        .map((r) => Object.fromEntries(columns.map((c) => [c.key, cellText(r[c.key])])))
+        .filter((r) => Object.values(r).some((v) => v !== ''));
+    for (const c of columns) {
+        if (c.align !== 'right')
+            continue;
+        const sym = rows.map((r) => r[c.key]).find((v) => typeof v === 'string' && /[$€£¥₹]/.test(v))?.match(/[$€£¥₹]/)?.[0];
+        const cc = !sym ? undefined : cur.code || cur.prefix ? cur : readCurrency(sym);
+        for (const r of rows) {
+            const n = r[c.key];
+            if (typeof n === 'number')
+                r[c.key] = cc ? fmtAmount(n, cc, n >= COMPACT_FROM) : num(n);
+        }
+    }
+    return { title: plain(d.title), columns, rows };
+}
+/** Activity rows; a row with no label says nothing and drops. */
+export function readTicker(ticker) {
+    const rows = safeArray(ticker)
+        .filter((x) => !!x && typeof x === 'object')
+        .map((t) => ({ label: plain(t.label), actor: plain(t.actor), time: plain(t.time), icon: plain(t.icon) }))
+        .filter((t) => t.label);
+    const keys = uniqueKeys(rows, (t) => t.label);
+    return rows.map((t, i) => ({ ...t, key: keys[i] }));
+}
+/** "Show 5 more" / "Show 16 earlier": always the hidden count, never "Show all". */
+export const moreLabel = (total, cap, noun = 'more') => `Show ${total - cap} ${noun}`;

package/dist/widgets/composite/quiz.d.ts

@@ -0,0 +1,63 @@
+export declare const MAX_QUESTIONS = 12;
+export declare const MIN_CHOICES = 2;
+export declare const MAX_CHOICES = 5;
+export declare const SECONDS: {
+    readonly min: 3;
+    readonly max: 600;
+};
+export interface QuizItem {
+    id?: string;
+    prompt: string;
+    choices: string[];
+    /** Index into `choices` of the right one. */
+    answer: number;
+    why?: string;
+    image?: string;
+}
+export interface QuizValue {
+    /** The question on screen; `total` once the visitor is on the score screen. */
+    index: number;
+    /** Picked choice per answered question (original index); null = timed out. */
+    answers: (number | null)[];
+    score: number;
+    done: boolean;
+}
+/** The part of the value the visitor actually changes. */
+export type QuizPlay = Pick<QuizValue, 'index' | 'answers'>;
+export interface CleanQuestion {
+    key: string;
+    prompt: string;
+    choices: string[];
+    answer: number;
+    why: string;
+    image: unknown;
+}
+/**
+ * The playable questions. An unfinished one (no prompt, under two choices, a
+ * blank choice, no answer yet: all normal mid-stream) is dropped quietly; an
+ * answer that points outside the choices is dropped with a warning. Past 12
+ * the rest are cut, with a warning.
+ */
+export declare function cleanQuestions(raw: unknown, warn?: (msg: string) => void): CleanQuestion[];
+/** A bound value from the host, normalised; undefined when it is not one. */
+export declare function toPlay(v: unknown): QuizPlay | undefined;
+export declare function scoreOf(questions: readonly CleanQuestion[], answers: readonly (number | null)[]): number;
+/** Right answers in a row, counted back from the latest. */
+export declare function streakOf(questions: readonly CleanQuestion[], answers: readonly (number | null)[]): number;
+export declare function bestStreakOf(questions: readonly CleanQuestion[], answers: readonly (number | null)[]): number;
+export declare function toValue(questions: readonly CleanQuestion[], play: QuizPlay): QuizValue;
+export type Band = {
+    word: string;
+    line: string;
+    status: 'good' | 'info' | 'warn';
+};
+/** The end-screen verdict by share of right answers. */
+export declare function bandOf(score: number, total: number): Band;
+export declare function clampSeconds(v: unknown): number | undefined;
+/** Longest choice, in characters, that still pairs in two columns. */
+export declare const PAIR_MAX_CHARS = 28;
+/**
+ * Columns for a question's choices at wide card widths: two only for exactly
+ * 2 or 4 short choices (no orphan tile, no tall tile beside a short one).
+ */
+export declare function choiceColumns(choices: readonly string[]): 1 | 2;

package/dist/widgets/composite/quiz.js

@@ -0,0 +1,107 @@
+// widgets/composite/quiz.ts — the rules behind the `quiz` widget, kept out of
+// the component so they test without a DOM: cleaning the model's questions
+// (a bad one is skipped, never a crash), normalising the bound value, scoring,
+// the streak, the verdict band and how many columns the choices take.
+//
+// Invariants:
+// - `answers[i]` is the ORIGINAL choice index the visitor picked for the i-th
+//   playable question (null = ran out of time), so shuffling the display order
+//   never changes a score or the review list.
+// - `score` and `done` in the bound value are outputs: they are recomputed
+//   from `answers` against the questions, never trusted from the host.
+import { finite, plain } from '../data-kit/format.js';
+export const MAX_QUESTIONS = 12;
+export const MIN_CHOICES = 2;
+export const MAX_CHOICES = 5;
+export const SECONDS = { min: 3, max: 600 };
+const rec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {};
+/**
+ * The playable questions. An unfinished one (no prompt, under two choices, a
+ * blank choice, no answer yet: all normal mid-stream) is dropped quietly; an
+ * answer that points outside the choices is dropped with a warning. Past 12
+ * the rest are cut, with a warning.
+ */
+export function cleanQuestions(raw, warn = () => { }) {
+    if (!Array.isArray(raw))
+        return [];
+    if (raw.length > MAX_QUESTIONS)
+        warn(`[ripple] quiz: ${raw.length} questions, showing the first ${MAX_QUESTIONS}`);
+    return raw.slice(0, MAX_QUESTIONS).flatMap((item, i) => {
+        const q = rec(item);
+        const prompt = plain(q.prompt);
+        const choices = Array.isArray(q.choices) ? q.choices.slice(0, MAX_CHOICES).map((c) => plain(c)) : [];
+        if (!prompt || choices.length < MIN_CHOICES || choices.some((c) => !c))
+            return [];
+        const answer = finite(q.answer);
+        if (answer === undefined)
+            return [];
+        if (!Number.isInteger(answer) || answer < 0 || answer >= choices.length) {
+            warn(`[ripple] quiz: question ${i + 1} ("${prompt.slice(0, 40)}") has answer ${String(q.answer)} outside its ${choices.length} choices; skipped`);
+            return [];
+        }
+        return [{ key: `${typeof q.id === 'string' ? q.id : ''}:${i}`, prompt, choices, answer, why: plain(q.why), image: q.image }];
+    });
+}
+/** A bound value from the host, normalised; undefined when it is not one. */
+export function toPlay(v) {
+    const r = rec(v);
+    if (!Array.isArray(r.answers))
+        return undefined;
+    const answers = r.answers.slice(0, MAX_QUESTIONS).map((a) => {
+        const n = finite(a);
+        return n !== undefined && Number.isInteger(n) && n >= 0 ? n : null;
+    });
+    const index = Math.min(Math.max(Math.trunc(finite(r.index) ?? answers.length), 0), answers.length);
+    return { index, answers };
+}
+export function scoreOf(questions, answers) {
+    return questions.reduce((n, q, i) => n + (answers[i] === q.answer ? 1 : 0), 0);
+}
+/** Right answers in a row, counted back from the latest. */
+export function streakOf(questions, answers) {
+    let n = 0;
+    for (let i = Math.min(answers.length, questions.length) - 1; i >= 0 && answers[i] === questions[i].answer; i--)
+        n++;
+    return n;
+}
+export function bestStreakOf(questions, answers) {
+    let best = 0;
+    let run = 0;
+    questions.forEach((q, i) => {
+        run = i < answers.length && answers[i] === q.answer ? run + 1 : 0;
+        best = Math.max(best, run);
+    });
+    return best;
+}
+export function toValue(questions, play) {
+    return {
+        index: play.index,
+        answers: [...play.answers],
+        score: scoreOf(questions, play.answers),
+        done: questions.length > 0 && play.answers.length >= questions.length
+    };
+}
+/** The end-screen verdict by share of right answers. */
+export function bandOf(score, total) {
+    const pct = total > 0 ? score / total : 0;
+    if (pct >= 0.9)
+        return { word: 'Expert', line: 'You know this cold.', status: 'good' };
+    if (pct >= 0.7)
+        return { word: 'Sharp', line: 'A strong round.', status: 'good' };
+    if (pct >= 0.4)
+        return { word: 'Getting there', line: 'Read the misses and try again.', status: 'info' };
+    return { word: 'Warming up', line: 'Every miss below has its answer.', status: 'warn' };
+}
+export function clampSeconds(v) {
+    const n = finite(v);
+    return n === undefined || n <= 0 ? undefined : Math.min(Math.max(Math.round(n), SECONDS.min), SECONDS.max);
+}
+/** Longest choice, in characters, that still pairs in two columns. */
+export const PAIR_MAX_CHARS = 28;
+/**
+ * Columns for a question's choices at wide card widths: two only for exactly
+ * 2 or 4 short choices (no orphan tile, no tall tile beside a short one).
+ */
+export function choiceColumns(choices) {
+    return (choices.length === 2 || choices.length === 4) && choices.every((c) => c.length <= PAIR_MAX_CHARS) ? 2 : 1;
+}