@appinternalleads/ui 0.2.0

package/dist/esm/components/threshold-flow/contract.js

@@ -0,0 +1,145 @@
+import { DATA_TYPES, HUES } from '../../tokens';
+/**
+ * **`threshold-flow/1` — the portable ThresholdFlow document.**
+ *
+ * ThresholdFlow is an ordered list of stages, each with a numeric threshold that must strictly
+ * increase from one stage to the next and an optional switch; a person edits them and activates the
+ * flow. One component, configured four different ways in the handoff's case studies (refund
+ * approval, resume shortlisting, alert escalation, usage alerts) — only the document changes.
+ *
+ * Source: `design_handoff_solarium_blocks_case_studies/threshold-flow.schema.json`, corrected — see
+ * `spec/families/threshold-flow.schema.json` and `docs/components/threshold-flow/THRESHOLD-FLOW.md`
+ * §2 for every correction and why. **The schema is authoritative** where it and the handoff's
+ * `case-studies-data.json` disagree; the four studies are re-expressed as schema-valid fixtures in
+ * `spec/examples/components/threshold-flow/`.
+ *
+ * **What is NOT in the document, on purpose.** No phase (editing / activating / live / error), no
+ * loading flag, no density, no per-stage validation message, no callbacks and no pixel value. Phase
+ * is runtime state (`engine.ts`); validation is derived; density is the host's presentation choice
+ * (`ThresholdFlowView`'s `density` prop). A document that carried any of them would render the same
+ * flow differently depending on where it was saved from.
+ */
+export const THRESHOLD_FLOW_SCHEMA = 'threshold-flow/1';
+/** The schema's `maxItems`. More stages than this is a routing table, not a flow. */
+export const MAX_STAGES = 8;
+/* ── Defaults ────────────────────────────────────────────────────────────── */
+export const DEFAULT_NOUN = { one: 'stage', other: 'stages' };
+/** The prototype's own default copy, used for any key the document omits. */
+export function copyFor(config) {
+    const noun = config.noun ?? DEFAULT_NOUN;
+    return {
+        action: 'Activate',
+        activating: 'Activating…',
+        retry: 'Try again',
+        live: 'Live',
+        checking: 'Checking…',
+        unit: '',
+        edit: `Edit ${noun.other}`,
+        emptyTitle: `No ${noun.other} yet`,
+        emptyBody: `Add a ${noun.one} to get started.`,
+        emptyCta: `Add first ${noun.one}`,
+        errorTitle: 'Couldn’t activate',
+        ...config.copy,
+    };
+}
+export function nounFor(config, count) {
+    const noun = config.noun ?? DEFAULT_NOUN;
+    return count === 1 ? noun.one : noun.other;
+}
+/** `$2,000`, `85 / 100`, `15 min`. en-US grouping, as the prototype. */
+export function formatValue(unit, value) {
+    return `${unit?.prefix ?? ''}${value.toLocaleString('en-US')}${unit?.suffix ?? ''}`;
+}
+const ID = /^[a-z0-9-]+$/;
+const KEY = /^[a-z][a-z0-9_]*$/;
+/**
+ * Validate a document the way the view needs it. Deterministic: the same document always yields
+ * the same issues in the same order. An empty array is a valid document.
+ *
+ * `defaultItems` must be strictly increasing — a flow must never OPEN invalid. (While a person is
+ * editing, an out-of-order value is an expected, transient state; that is `stageErrors`, not this.)
+ */
+export function validateThresholdFlow(doc) {
+    const issues = [];
+    const d = doc;
+    if (!d || typeof d !== 'object')
+        return [{ code: 'schema', message: 'Not an object.' }];
+    if (d.schema !== THRESHOLD_FLOW_SCHEMA)
+        issues.push({ code: 'schema', message: `schema must be "${THRESHOLD_FLOW_SCHEMA}".` });
+    if (typeof d.key !== 'string' || !KEY.test(d.key))
+        issues.push({ code: 'schema', message: 'key must match ^[a-z][a-z0-9_]*$.' });
+    const p = d.props;
+    if (!p || typeof p !== 'object')
+        return [...issues, { code: 'schema', message: 'props is required.' }];
+    for (const f of ['title', 'valueLabel']) {
+        if (typeof p[f] !== 'string' || !p[f])
+            issues.push({ code: 'schema', message: `props.${f} is required.` });
+    }
+    if (!Array.isArray(p.defaultItems))
+        return [...issues, { code: 'schema', message: 'props.defaultItems must be an array.' }];
+    if (p.type !== undefined && !DATA_TYPES.includes(p.type))
+        issues.push({ code: 'unknown-type', message: `Unknown type "${String(p.type)}".` });
+    if (p.hue !== undefined && !HUES.includes(p.hue))
+        issues.push({ code: 'unknown-hue', message: `Unknown hue "${String(p.hue)}".` });
+    if (p.defaultItems.length > MAX_STAGES)
+        issues.push({ code: 'too-many', message: `At most ${MAX_STAGES} stages.` });
+    const seen = new Set();
+    p.defaultItems.forEach((item, i) => {
+        if (typeof item?.id !== 'string' || !ID.test(item.id)) {
+            issues.push({ code: 'schema', message: `defaultItems[${i}].id must be kebab-case.` });
+            return;
+        }
+        if (seen.has(item.id))
+            issues.push({ code: 'duplicate-id', id: item.id, message: `Duplicate id "${item.id}".` });
+        seen.add(item.id);
+        if (typeof item.value !== 'number' || !(item.value > 0)) {
+            issues.push({ code: 'not-positive', id: item.id, message: `"${item.title}" must be greater than 0.` });
+        }
+        else if (p.unit?.max !== undefined && item.value > p.unit.max) {
+            issues.push({ code: 'over-max', id: item.id, message: `"${item.title}" is over the maximum of ${p.unit.max}.` });
+        }
+        const prev = p.defaultItems[i - 1];
+        if (prev && typeof prev.value === 'number' && typeof item.value === 'number' && item.value <= prev.value) {
+            issues.push({ code: 'not-increasing', id: item.id, message: `"${item.title}" (${item.value}) must be more than "${prev.title}" (${prev.value}).` });
+        }
+        if (item.toggle !== undefined && !p.toggleLabel) {
+            issues.push({ code: 'toggle-without-label', id: item.id, message: `"${item.title}" sets a switch, but the flow has no toggleLabel.` });
+        }
+    });
+    (p.templates ?? []).forEach((t, i, all) => {
+        const prev = all[i - 1];
+        if (prev && t.value <= prev.value) {
+            issues.push({ code: 'template-not-increasing', index: i, message: `Template ${i + 1} ("${t.title}") must be more than template ${i} ("${prev.title}").` });
+        }
+    });
+    return issues;
+}
+/**
+ * **Per-stage messages while a person edits** — the prototype's three strings, verbatim. A stage
+ * with no message is valid. Pure and derived: never stored, recomputed from the stages every render.
+ *
+ * `value` is `number | null`: `null` is an empty field, which is its own message rather than 0.
+ */
+export function stageErrors(stages, unit) {
+    const out = {};
+    stages.forEach((s, i) => {
+        if (s.value === null || !(s.value > 0)) {
+            out[s.id] = 'Enter a value greater than 0.';
+            return;
+        }
+        if (unit?.max !== undefined && s.value > unit.max) {
+            out[s.id] = `Must be ${formatValue(unit, unit.max)} or less.`;
+            return;
+        }
+        const prev = stages[i - 1];
+        if (prev && prev.value !== null && s.value <= prev.value) {
+            out[s.id] = `Must be more than ${prev.title} (${formatValue(unit, prev.value)}).`;
+        }
+    });
+    return out;
+}
+/** The activated stages under the document's answer key — what a host files. */
+export function answerOf(doc, items) {
+    return { [doc.key]: items };
+}
+//# sourceMappingURL=contract.js.map

package/dist/esm/components/threshold-flow/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/components/threshold-flow/contract.ts"],"names":[],"mappings":"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"}

package/dist/esm/components/threshold-flow/engine.d.ts

@@ -0,0 +1,105 @@
+import { type ThresholdFlowConfig, type ThresholdFlowDocument, type ThresholdItem } from './contract';
+/**
+ * **The ThresholdFlow state machine — pure, no React, no timers.**
+ *
+ * ```
+ *            activate (valid, non-empty)            resolve ok
+ *  editing ───────────────────────────▶ activating ───────────▶ live
+ *     ▲                                    │                     │
+ *     │ edit                               │ resolve fail        │ edit
+ *     │                                    ▼                     │
+ *     └──────────────────────────────── error ◀──────────────────┘ (via editing)
+ *                  activate (retry) ───────┘
+ * ```
+ *
+ * One `phase` field instead of `isLive`/`isActivating`/`isError` booleans that can disagree.
+ * `activating` and `live` LOCK the stages: every edit action is refused in them. `error` does not —
+ * the point of the error is that the person fixes something and tries again.
+ *
+ * **Stale results are refused by attempt number.** Each `activate` increments `attempt`, and a
+ * `resolve` carrying an older attempt is ignored — so a slow first attempt that lands after a retry
+ * cannot overwrite the retry's outcome. (The operations runner also aborts the superseded call;
+ * this is the second guard, and the one a test can prove without a clock.)
+ */
+export type ThresholdPhase = 'editing' | 'activating' | 'live' | 'error';
+/** A stage being edited. `value` is `null` while its field is empty. `leaving` is mid-exit (M2). */
+export type DraftStage = {
+    id: string;
+    title: string;
+    role?: string;
+    value: number | null;
+    toggle: boolean;
+    leaving?: boolean;
+};
+export type ActivationFailure = {
+    message: string;
+    stageId?: string;
+};
+export type ThresholdFlowState = {
+    phase: ThresholdPhase;
+    stages: DraftStage[];
+    /** Monotonic, per flow — added stages get `${slug}-${nextId}`. Never `Date.now()`. */
+    nextId: number;
+    attempt: number;
+    error: ActivationFailure | null;
+};
+export type ThresholdAction = {
+    type: 'edit-value';
+    id: string;
+    raw: string;
+} | {
+    type: 'toggle';
+    id: string;
+} | {
+    type: 'add';
+} | {
+    type: 'remove';
+    id: string;
+    immediate?: boolean;
+} | {
+    type: 'drop';
+    id: string;
+} | {
+    type: 'activate';
+} | {
+    type: 'resolve';
+    attempt: number;
+    outcome: {
+        ok: true;
+    } | ({
+        ok: false;
+    } & ActivationFailure);
+} | {
+    type: 'edit-flow';
+} | {
+    type: 'reset';
+    doc: ThresholdFlowDocument;
+};
+export declare function slug(title: string): string;
+/**
+ * The seed a flow opens with. `initial` restores a session — a story, a preview, a flow reopened
+ * live — and is never part of the document.
+ */
+export type ThresholdFlowSeed = {
+    phase?: Exclude<ThresholdPhase, 'activating'>;
+    error?: ActivationFailure;
+    /** Override stage values by id — `null` for an emptied field. */
+    values?: Record<string, number | null>;
+};
+export declare function initialState(doc: ThresholdFlowDocument, seed?: ThresholdFlowSeed): ThresholdFlowState;
+/** The stages that count — not mid-exit. */
+export declare const liveStages: (s: ThresholdFlowState) => DraftStage[];
+export declare const isLocked: (s: ThresholdFlowState) => boolean;
+/** Per-stage messages, derived. */
+export declare function errorsOf(s: ThresholdFlowState, config: ThresholdFlowConfig): Record<string, string>;
+export declare function canAdd(s: ThresholdFlowState, config: ThresholdFlowConfig): boolean;
+export declare function canActivate(s: ThresholdFlowState, config: ThresholdFlowConfig): boolean;
+/**
+ * The stages as the host receives them — numbers, no leaving rows, no empty fields. Only called
+ * on a flow that `canActivate`, so every value is a number; the filter is belt-and-braces.
+ */
+export declare function itemsOf(s: ThresholdFlowState): ThresholdItem[];
+/** Digits only, at most 9 — the prototype's input rule. Empty is `null`, not 0. */
+export declare function parseValue(raw: string): number | null;
+export declare function reduce(config: ThresholdFlowConfig, s: ThresholdFlowState, a: ThresholdAction): ThresholdFlowState;
+//# sourceMappingURL=engine.d.ts.map

package/dist/esm/components/threshold-flow/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/components/threshold-flow/engine.ts"],"names":[],"mappings":"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"}

package/dist/esm/components/threshold-flow/engine.js

@@ -0,0 +1,95 @@
+import { stageErrors, } from './contract';
+export function slug(title) {
+    return String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'stage';
+}
+export function initialState(doc, seed = {}) {
+    return {
+        phase: seed.phase ?? 'editing',
+        stages: doc.props.defaultItems.map(i => ({
+            id: i.id,
+            title: i.title,
+            ...(i.role !== undefined ? { role: i.role } : {}),
+            value: seed.values && i.id in seed.values ? seed.values[i.id] : i.value,
+            toggle: doc.props.toggleLabel ? Boolean(i.toggle) : false,
+        })),
+        nextId: 1,
+        attempt: 0,
+        error: seed.phase === 'error' ? (seed.error ?? { message: '' }) : null,
+    };
+}
+/** The stages that count — not mid-exit. */
+export const liveStages = (s) => s.stages.filter(x => !x.leaving);
+export const isLocked = (s) => s.phase === 'activating' || s.phase === 'live';
+/** Per-stage messages, derived. */
+export function errorsOf(s, config) {
+    return stageErrors(liveStages(s), config.unit);
+}
+export function canAdd(s, config) {
+    const n = liveStages(s).length;
+    return !isLocked(s) && (config.templates?.length ?? 0) > n;
+}
+export function canActivate(s, config) {
+    return (s.phase === 'editing' || s.phase === 'error')
+        && liveStages(s).length > 0
+        && Object.keys(errorsOf(s, config)).length === 0;
+}
+/**
+ * The stages as the host receives them — numbers, no leaving rows, no empty fields. Only called
+ * on a flow that `canActivate`, so every value is a number; the filter is belt-and-braces.
+ */
+export function itemsOf(s) {
+    return liveStages(s)
+        .filter((x) => x.value !== null)
+        .map(x => ({ id: x.id, title: x.title, ...(x.role !== undefined ? { role: x.role } : {}), value: x.value, toggle: x.toggle }));
+}
+/** Digits only, at most 9 — the prototype's input rule. Empty is `null`, not 0. */
+export function parseValue(raw) {
+    const digits = raw.replace(/[^0-9]/g, '').slice(0, 9);
+    return digits === '' ? null : Number(digits);
+}
+export function reduce(config, s, a) {
+    const editable = !isLocked(s);
+    const patch = (id, fn) => ({ ...s, stages: s.stages.map(x => (x.id === id ? fn(x) : x)) });
+    switch (a.type) {
+        case 'edit-value':
+            return editable ? patch(a.id, x => ({ ...x, value: parseValue(a.raw) })) : s;
+        case 'toggle':
+            return editable && config.toggleLabel ? patch(a.id, x => ({ ...x, toggle: !x.toggle })) : s;
+        case 'add': {
+            if (!canAdd(s, config))
+                return s;
+            const t = config.templates[liveStages(s).length];
+            const stage = {
+                id: `${slug(t.title)}-${s.nextId}`,
+                title: t.title,
+                ...(t.role !== undefined ? { role: t.role } : {}),
+                value: t.value,
+                toggle: config.toggleLabel ? Boolean(t.toggle) : false,
+            };
+            return { ...s, stages: [...s.stages, stage], nextId: s.nextId + 1 };
+        }
+        case 'remove':
+            if (!editable)
+                return s;
+            return a.immediate
+                ? { ...s, stages: s.stages.filter(x => x.id !== a.id) }
+                : patch(a.id, x => ({ ...x, leaving: true }));
+        case 'drop':
+            return { ...s, stages: s.stages.filter(x => x.id !== a.id) };
+        case 'activate':
+            if (!canActivate(s, config))
+                return s;
+            return { ...s, phase: 'activating', attempt: s.attempt + 1, error: null };
+        case 'resolve':
+            if (s.phase !== 'activating' || a.attempt !== s.attempt)
+                return s; // stale or superseded
+            return a.outcome.ok
+                ? { ...s, phase: 'live', error: null }
+                : { ...s, phase: 'error', error: { message: a.outcome.message, ...(a.outcome.stageId ? { stageId: a.outcome.stageId } : {}) } };
+        case 'edit-flow':
+            return s.phase === 'live' ? { ...s, phase: 'editing' } : s;
+        case 'reset':
+            return initialState(a.doc);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/esm/components/threshold-flow/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../../src/components/threshold-flow/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,GACZ,MAAM,YAAY,CAAC;AA2DpB,MAAM,UAAU,IAAI,CAAC,KAAa;IAChC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC;AAClG,CAAC;AAaD,MAAM,UAAU,YAAY,CAAC,GAA0B,EAAE,OAA0B,EAAE;IACnF,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS;QAC9B,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,KAAK,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK;YACxE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK;SAC1D,CAAC,CAAC;QACH,MAAM,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;KACvE,CAAC;AACJ,CAAC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAEtF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,YAAY,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC;AAElG,mCAAmC;AACnC,MAAM,UAAU,QAAQ,CAAC,CAAqB,EAAE,MAA2B;IACzE,OAAO,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAqB,EAAE,MAA2B;IACvE,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAqB,EAAE,MAA2B;IAC5E,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC;WAChD,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC;WACxB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,CAAqB;IAC3C,OAAO,UAAU,CAAC,CAAC,CAAC;SACjB,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC;SACpE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AACnI,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,MAA2B,EAAE,CAAqB,EAAE,CAAkB;IAC3F,MAAM,QAAQ,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAiC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAElI,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,YAAY;YACf,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/E,KAAK,QAAQ;YACX,OAAO,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9F,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC;gBAAE,OAAO,CAAC,CAAC;YACjC,MAAM,CAAC,GAAG,MAAM,CAAC,SAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAE,CAAC;YACnD,MAAM,KAAK,GAAe;gBACxB,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE;gBAClC,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK;aACvD,CAAC;YACF,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,CAAC;QACD,KAAK,QAAQ;YACX,IAAI,CAAC,QAAQ;gBAAE,OAAO,CAAC,CAAC;YACxB,OAAO,CAAC,CAAC,SAAS;gBAChB,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE;gBACvD,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAClD,KAAK,MAAM;YACT,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/D,KAAK,UAAU;YACb,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC;gBAAE,OAAO,CAAC,CAAC;YACtC,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC5E,KAAK,SAAS;YACZ,IAAI,CAAC,CAAC,KAAK,KAAK,YAAY,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC,CAAC,sBAAsB;YACzF,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE;gBACjB,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;gBACtC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpI,KAAK,WAAW;YACd,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/dist/esm/components/threshold-flow/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * **ThresholdFlow — the third component family.** Ordered stages with strictly increasing
+ * thresholds, an optional switch per stage, and an activation the host performs. Portable as a
+ * `threshold-flow/1` document (`spec/families/threshold-flow.schema.json`). Design:
+ * `docs/components/threshold-flow/THRESHOLD-FLOW.md`.
+ */
+export { THRESHOLD_FLOW_SCHEMA, MAX_STAGES, DEFAULT_NOUN, answerOf, copyFor, formatValue, nounFor, stageErrors, validateThresholdFlow, type ThresholdFlowConfig, type ThresholdFlowCopy, type ThresholdFlowDocument, type ThresholdFlowIssue, type ThresholdItem, type ThresholdTemplate, type ThresholdUnit, } from './contract';
+export { canActivate, canAdd, errorsOf, initialState, isLocked, itemsOf, liveStages, parseValue, reduce, slug, type ActivationFailure, type DraftStage, type ThresholdAction, type ThresholdFlowSeed, type ThresholdFlowState, type ThresholdPhase, } from './engine';
+export { useThresholdFlow, type ThresholdActivation, type ThresholdActivationResult, type ThresholdFlowOperations, type ThresholdFlowRuntime, } from './runtime';
+export { createMockThresholdOperations, CASE_STUDY_REFUSALS, THRESHOLD_LATENCY, type MockThresholdOperationsOptions, } from './mock';
+export { ThresholdFlowView, type ThresholdFlowViewProps } from './ThresholdFlowView';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/threshold-flow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/threshold-flow/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,qBAAqB,EAAE,UAAU,EAAE,YAAY,EAC/C,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAC3E,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,kBAAkB,EACrG,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,aAAa,GAC/D,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EACpG,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EACrF,KAAK,kBAAkB,EAAE,KAAK,cAAc,GAC7C,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,gBAAgB,EAChB,KAAK,mBAAmB,EAAE,KAAK,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,KAAK,oBAAoB,GAClH,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,6BAA6B,EAAE,mBAAmB,EAAE,iBAAiB,EACrE,KAAK,8BAA8B,GACpC,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/esm/components/threshold-flow/index.js

@@ -0,0 +1,12 @@
+/**
+ * **ThresholdFlow — the third component family.** Ordered stages with strictly increasing
+ * thresholds, an optional switch per stage, and an activation the host performs. Portable as a
+ * `threshold-flow/1` document (`spec/families/threshold-flow.schema.json`). Design:
+ * `docs/components/threshold-flow/THRESHOLD-FLOW.md`.
+ */
+export { THRESHOLD_FLOW_SCHEMA, MAX_STAGES, DEFAULT_NOUN, answerOf, copyFor, formatValue, nounFor, stageErrors, validateThresholdFlow, } from './contract';
+export { canActivate, canAdd, errorsOf, initialState, isLocked, itemsOf, liveStages, parseValue, reduce, slug, } from './engine';
+export { useThresholdFlow, } from './runtime';
+export { createMockThresholdOperations, CASE_STUDY_REFUSALS, THRESHOLD_LATENCY, } from './mock';
+export { ThresholdFlowView } from './ThresholdFlowView';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/threshold-flow/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/components/threshold-flow/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,qBAAqB,EAAE,UAAU,EAAE,YAAY,EAC/C,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,qBAAqB,GAG5E,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,GAGrG,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,gBAAgB,GAEjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,6BAA6B,EAAE,mBAAmB,EAAE,iBAAiB,GAEtE,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,iBAAiB,EAA+B,MAAM,qBAAqB,CAAC"}

package/dist/esm/components/threshold-flow/mock.d.ts

@@ -0,0 +1,40 @@
+import type { ThresholdActivation, ThresholdFlowOperations } from './runtime';
+/**
+ * **The deterministic mock activation — every timer in the ThresholdFlow family lives here.**
+ *
+ * The same constraint `createMockChecklistOperations` inherits: latency is a number or a function
+ * of the request and the 0-based call index, failure is a predicate, and there is no `Math.random`
+ * and no `Date.now`. A test that can make call 1 slower than call 2 can *prove* a superseded
+ * activation is discarded; a random one could only prove it usually is.
+ */
+/** The prototype's own activation time, and two presets either side of it. */
+export declare const THRESHOLD_LATENCY: {
+    readonly fast: 120;
+    readonly normal: 1400;
+    readonly slow: 4000;
+};
+export type MockThresholdOperationsOptions = {
+    latencyMs?: number | ((req: ThresholdActivation, callIndex: number) => number);
+    /**
+     * Refuse this call. Return a refusal (with the message and, optionally, the stage it concerns)
+     * or `null` to let it through. Deterministic by construction — a function of the call.
+     */
+    refuse?: (req: ThresholdActivation, callIndex: number) => {
+        message: string;
+        stageId?: string;
+    } | null;
+    /** Throw instead of refusing — a transport failure rather than a business refusal. */
+    throwWhen?: (req: ThresholdActivation, callIndex: number) => boolean;
+    onCall?: (req: ThresholdActivation, callIndex: number) => void;
+};
+export declare function createMockThresholdOperations(opts?: MockThresholdOperationsOptions): ThresholdFlowOperations;
+/**
+ * **The four case studies' refusals, verbatim from the handoff** — the error each study's
+ * prototype shows, and the stage it names. Keyed by document `key`. Kept here rather than in the
+ * fixtures because a refusal is the HOST'S answer, not part of the document.
+ */
+export declare const CASE_STUDY_REFUSALS: Record<string, {
+    message: string;
+    stageId: string;
+}>;
+//# sourceMappingURL=mock.d.ts.map

package/dist/esm/components/threshold-flow/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../../src/components/threshold-flow/mock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EAA6B,uBAAuB,EACxE,MAAM,WAAW,CAAC;AAEnB;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB;;;;CAAmD,CAAC;AAElF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC/E;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACvG,sFAAsF;IACtF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACrE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,IAAI,GAAE,8BAAmC,GAAG,uBAAuB,CAYhH;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBpF,CAAC"}

package/dist/esm/components/threshold-flow/mock.js

@@ -0,0 +1,49 @@
+import { abortableDelay, resolveLatency } from '../../runtime/operations';
+/**
+ * **The deterministic mock activation — every timer in the ThresholdFlow family lives here.**
+ *
+ * The same constraint `createMockChecklistOperations` inherits: latency is a number or a function
+ * of the request and the 0-based call index, failure is a predicate, and there is no `Math.random`
+ * and no `Date.now`. A test that can make call 1 slower than call 2 can *prove* a superseded
+ * activation is discarded; a random one could only prove it usually is.
+ */
+/** The prototype's own activation time, and two presets either side of it. */
+export const THRESHOLD_LATENCY = { fast: 120, normal: 1400, slow: 4000 };
+export function createMockThresholdOperations(opts = {}) {
+    let calls = 0;
+    return {
+        activate: async (req, { signal }) => {
+            const callIndex = calls++;
+            opts.onCall?.(req, callIndex);
+            await abortableDelay(resolveLatency(opts.latencyMs, req, callIndex), signal);
+            if (opts.throwWhen?.(req, callIndex))
+                throw new Error('The activation could not be sent.');
+            const refusal = opts.refuse?.(req, callIndex);
+            return refusal ? { ok: false, ...refusal } : { ok: true };
+        },
+    };
+}
+/**
+ * **The four case studies' refusals, verbatim from the handoff** — the error each study's
+ * prototype shows, and the stage it names. Keyed by document `key`. Kept here rather than in the
+ * fixtures because a refusal is the HOST'S answer, not part of the document.
+ */
+export const CASE_STUDY_REFUSALS = {
+    refund_approval: {
+        message: 'The Finance team has no approvers assigned, so refunds over $2,000 would never be paid out. Add an approver or turn on auto-approve for that stage, then try again.',
+        stageId: 'finance-review',
+    },
+    resume_shortlisting: {
+        message: 'The interview panel has no interviewers assigned, so candidates scoring 85 or more would stall. Assign an interviewer or turn on auto-advance for that stage, then try again.',
+        stageId: 'final-interview',
+    },
+    alert_escalation: {
+        message: 'Nobody is scheduled on the backup rotation this week, so unresolved alerts would skip straight to the manager. Add someone to the rotation or remove that level, then try again.',
+        stageId: 'secondary-on-call',
+    },
+    usage_alerts: {
+        message: 'This workspace has no admin email, so warnings at 75% would reach nobody. Add an admin email or turn off emails for that level, then try again.',
+        stageId: 'warn',
+    },
+};
+//# sourceMappingURL=mock.js.map

package/dist/esm/components/threshold-flow/mock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.js","sourceRoot":"","sources":["../../../../src/components/threshold-flow/mock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAK1E;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAW,CAAC;AAclF,MAAM,UAAU,6BAA6B,CAAC,OAAuC,EAAE;IACrF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO;QACL,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,EAAsC,EAAE;YACtE,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAC9B,MAAM,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;YAC7E,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;YAC3F,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAC9C,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QAC5D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAyD;IACvF,eAAe,EAAE;QACf,OAAO,EAAE,qKAAqK;QAC9K,OAAO,EAAE,gBAAgB;KAC1B;IACD,mBAAmB,EAAE;QACnB,OAAO,EAAE,+KAA+K;QACxL,OAAO,EAAE,iBAAiB;KAC3B;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,kLAAkL;QAC3L,OAAO,EAAE,mBAAmB;KAC7B;IACD,YAAY,EAAE;QACZ,OAAO,EAAE,iJAAiJ;QAC1J,OAAO,EAAE,MAAM;KAChB;CACF,CAAC"}

package/dist/esm/components/threshold-flow/runtime.d.ts

@@ -0,0 +1,53 @@
+import type { ThresholdFlowDocument, ThresholdItem } from './contract';
+import { type ThresholdAction, type ThresholdFlowSeed, type ThresholdFlowState } from './engine';
+/**
+ * **The ThresholdFlow runtime** — `Document → engine → runtime → View`.
+ *
+ * It owns the reducer and the ONE boundary operation, activation, through
+ * `src/runtime/operations` — the same runner Checklist and the File Upload engine use. Every
+ * timer lives in the host's operation (or `mock.ts`); the view never waits on anything.
+ *
+ * Without `operations` the flow is local-only: Activate goes live at once, because there is
+ * nothing to ask. That is a real mode (a builder previewing its own flow), not a stub.
+ */
+/** What the host is asked to do on Activate. */
+export type ThresholdActivation = {
+    key: string;
+    items: ThresholdItem[];
+};
+/**
+ * The host's answer. A refusal can name the stage it is about, which the view marks — "the
+ * Finance team has no approvers" points at the Finance stage. A thrown error is also a refusal,
+ * with its message; an abort (unmount, superseded retry) is neither and changes nothing.
+ */
+export type ThresholdActivationResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    stageId?: string;
+};
+export type ThresholdFlowOperations = {
+    activate: (req: ThresholdActivation, ctx: {
+        signal: AbortSignal;
+    }) => Promise<ThresholdActivationResult>;
+};
+export type ThresholdFlowRuntime = {
+    state: ThresholdFlowState;
+    errors: Record<string, string>;
+    canAdd: boolean;
+    canActivate: boolean;
+    locked: boolean;
+    dispatch: (a: ThresholdAction) => void;
+    activate: () => void;
+};
+export declare function useThresholdFlow({ doc, operations, initial, onChange, onActivate, }: {
+    doc: ThresholdFlowDocument;
+    operations?: ThresholdFlowOperations;
+    initial?: ThresholdFlowSeed;
+    /** The stages as numbers, every time they change. */
+    onChange?: (items: ThresholdItem[]) => void;
+    /** Fires once per successful activation, with the stages that went live. */
+    onActivate?: (items: ThresholdItem[]) => void;
+}): ThresholdFlowRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/esm/components/threshold-flow/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/components/threshold-flow/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAEL,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EACtE,MAAM,UAAU,CAAC;AAElB;;;;;;;;;GASG;AAEH,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAE1E;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExG,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC1G,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IACvC,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAC/C,EAAE;IACD,GAAG,EAAE,qBAAqB,CAAC;IAC3B,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAC5C,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;CAC/C,GAAG,oBAAoB,CA6DvB"}

package/dist/esm/components/threshold-flow/runtime.js

@@ -0,0 +1,63 @@
+'use client';
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useOperationRunner } from '../../runtime/operations';
+import { canActivate, canAdd, errorsOf, initialState, isLocked, itemsOf, reduce, } from './engine';
+export function useThresholdFlow({ doc, operations, initial, onChange, onActivate, }) {
+    const config = doc.props;
+    const [state, send] = useReducer((s, a) => reduce(config, s, a), undefined, () => initialState(doc, initial));
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const runner = useOperationRunner();
+    /* Reseed only when the document genuinely changes — the same rule `useChecklistRuntime` states:
+       a parent that re-renders with an equal document must not wipe the person's edits. */
+    const seeded = useRef(JSON.stringify(doc));
+    useEffect(() => {
+        const next = JSON.stringify(doc);
+        if (next === seeded.current)
+            return;
+        seeded.current = next;
+        runner.cancel('activate');
+        send({ type: 'reset', doc });
+    }, [doc, runner]);
+    /* Report the stages as numbers whenever the live set changes (not on a leaving flag). */
+    const items = useMemo(() => itemsOf(state), [state]);
+    const itemsKey = JSON.stringify(items);
+    const reported = useRef(null);
+    useEffect(() => {
+        if (reported.current === itemsKey)
+            return;
+        reported.current = itemsKey;
+        onChange?.(items);
+    }, [itemsKey, items, onChange]);
+    const activate = useCallback(() => {
+        const s = stateRef.current;
+        if (!canActivate(s, config))
+            return;
+        const attempt = s.attempt + 1;
+        const req = { key: doc.key, items: itemsOf(s) };
+        send({ type: 'activate' });
+        if (!operations) {
+            send({ type: 'resolve', attempt, outcome: { ok: true } });
+            onActivate?.(req.items);
+            return;
+        }
+        runner.run('activate', ctx => operations.activate(req, { signal: ctx.signal }), {
+            onOk: result => {
+                send({ type: 'resolve', attempt, outcome: result });
+                if (result.ok)
+                    onActivate?.(req.items);
+            },
+            onError: error => send({ type: 'resolve', attempt, outcome: { ok: false, message: error.message } }),
+        });
+    }, [config, doc.key, operations, runner, onActivate]);
+    return {
+        state,
+        errors: errorsOf(state, config),
+        canAdd: canAdd(state, config),
+        canActivate: canActivate(state, config),
+        locked: isLocked(state),
+        dispatch: send,
+        activate,
+    };
+}
+//# sourceMappingURL=runtime.js.map