@delmaredigital/payload-experiments 0.1.0-rc.7 → 0.2.0-rc.2

package/dist/admin/surface/readiness/ActionDialogs.js

@@ -0,0 +1,274 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Button, TextInput } from '@payloadcms/ui';
+import { DialogFrame } from '../../actions/ConfirmDialog.js';
+import { MakeContentResult } from '../../actions/MakeContentResult.js';
+import { expectedConfirm, matchesConfirm } from '../../../transitions/confirmPhrases.js';
+import { ACTIONS_COPY as A } from '../../copy/actions.js';
+import { REVIEW_COPY as R } from '../../copy/review.js';
+import { READINESS_COPY as C } from '../../copy/readiness.js';
+import { API_MESSAGES, refusalMessage } from '../../copy/common.js';
+import { createApi } from '../../api.js';
+import { useTransition } from './useTransition.js';
+/** Prop-driven ConfirmDialog adapter: same model/copy, section reload instead of a page reload. */ export function ConfirmAction({ test, surface, action, winnerLabel, onClose }) {
+    const api = createApi(surface.apiRoute);
+    const [typed, setTyped] = useState('');
+    const [content, setContent] = useState(null);
+    const transition = useTransition(test, onClose);
+    const phrase = action.confirm.phrase ? expectedConfirm(action.confirm.phrase.action, winnerLabel) : null;
+    const ready = action.id !== 'start' || Boolean(test.preflight && !test.preflightPending && !test.preflightError && test.preflight.checks.every((check)=>check.ok));
+    const enabled = ready && !transition.busy && !test.hasUnsaved && test.saving !== 'saving' && (!phrase || matchesConfirm(phrase, typed));
+    async function submit() {
+        if (!enabled || !test.doc) return;
+        const id = test.doc.id;
+        await transition.run(async ()=>{
+            if (action.archive) return api.archive(id, {
+                ...action.archive,
+                ...phrase ? {
+                    confirmation: typed.trim()
+                } : {}
+            });
+            if (action.id === 'start') return api.start(id);
+            if (action.id === 'stop') return api.stop(id);
+            if (action.id === 'release-holdout') return api.releaseHoldout(id);
+            const result = await api.makeContent(id);
+            if (result.ok && result.data) {
+                setContent(result.data);
+                return result;
+            }
+            return result.ok ? {
+                ok: false,
+                status: 0,
+                retryable: true,
+                message: API_MESSAGES.unreadable
+            } : result;
+        }, {
+            reloadOnSuccess: action.id !== 'make-content'
+        });
+    }
+    function close() {
+        if (transition.busy) return;
+        if (content) void test.reload();
+        onClose();
+    }
+    return /*#__PURE__*/ _jsxs(DialogFrame, {
+        title: action.confirm.title,
+        onClose: close,
+        children: [
+            content ? /*#__PURE__*/ _jsx(MakeContentResult, {
+                result: content,
+                onRetry: submit,
+                busy: transition.busy
+            }) : /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        children: action.confirm.body
+                    }),
+                    phrase ? /*#__PURE__*/ _jsxs(_Fragment, {
+                        children: [
+                            /*#__PURE__*/ _jsxs("p", {
+                                children: [
+                                    A.typePhrase,
+                                    " ",
+                                    /*#__PURE__*/ _jsx("strong", {
+                                        children: phrase
+                                    })
+                                ]
+                            }),
+                            /*#__PURE__*/ _jsx(TextInput, {
+                                path: "xp-confirmation",
+                                label: A.confirmation,
+                                value: typed,
+                                readOnly: transition.busy,
+                                onChange: (event)=>setTyped(event.target.value)
+                            })
+                        ]
+                    }) : null
+                ]
+            }),
+            transition.error ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: transition.error
+            }) : null,
+            !content ? /*#__PURE__*/ _jsx(Button, {
+                disabled: !enabled,
+                onClick: ()=>{
+                    void submit();
+                },
+                children: action.label
+            }) : null,
+            /*#__PURE__*/ _jsx(Button, {
+                disabled: transition.busy,
+                onClick: close,
+                children: content ? A.done : A.cancel
+            })
+        ]
+    });
+}
+/** AllocateDialog's validation and copy, with data supplied by the test document. */ export function AllocateAction({ test, surface, onClose }) {
+    const current = test.doc?.allocation ?? 100;
+    const [value, setValue] = useState(String(Math.min(100, current + 1)));
+    const transition = useTransition(test, onClose);
+    const allocation = Number(value);
+    const valid = value.trim() !== '' && Number.isInteger(allocation) && allocation > current && allocation <= 100;
+    const disabled = transition.busy || test.hasUnsaved || test.saving === 'saving';
+    return /*#__PURE__*/ _jsxs(DialogFrame, {
+        title: C.allocate,
+        onClose: ()=>{
+            if (!transition.busy) onClose();
+        },
+        children: [
+            /*#__PURE__*/ _jsx("p", {
+                children: R.allocationBody
+            }),
+            /*#__PURE__*/ _jsxs("label", {
+                children: [
+                    C.participation,
+                    /*#__PURE__*/ _jsx("input", {
+                        type: "number",
+                        min: current + 1,
+                        max: 100,
+                        step: 1,
+                        value: value,
+                        disabled: disabled,
+                        onChange: (event)=>setValue(event.target.value)
+                    })
+                ]
+            }),
+            !valid ? /*#__PURE__*/ _jsx("p", {
+                children: R.allocationInvalid
+            }) : null,
+            transition.error ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: transition.error
+            }) : null,
+            /*#__PURE__*/ _jsx(Button, {
+                disabled: disabled || !valid,
+                onClick: ()=>{
+                    if (valid && test.doc) void transition.run(()=>createApi(surface.apiRoute).allocate(test.doc.id, {
+                            allocation
+                        }));
+                },
+                children: C.allocate
+            }),
+            /*#__PURE__*/ _jsx(Button, {
+                disabled: transition.busy,
+                onClick: onClose,
+                children: A.cancel
+            })
+        ]
+    });
+}
+/** AddMetricDialog adapter; the primary goal is deliberately absent from the role picker. */ export function AddMetricAction({ test, surface, onClose }) {
+    const [metrics, setMetrics] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [metric, setMetric] = useState('');
+    const [role, setRole] = useState('secondary');
+    const transition = useTransition(test, onClose);
+    useEffect(()=>{
+        const controller = new AbortController();
+        void (async ()=>{
+            try {
+                const response = await fetch(`${surface.apiRoute.replace(/\/$/, '')}/xp-metrics?depth=0&limit=100`, {
+                    credentials: 'include',
+                    signal: controller.signal
+                });
+                if (!response.ok) throw new Error(refusalMessage(undefined, response.status));
+                const data = await response.json();
+                if (!Array.isArray(data.docs)) throw new Error(API_MESSAGES.unreadable);
+                if (!controller.signal.aborted) setMetrics(data.docs);
+            } catch (cause) {
+                if (!controller.signal.aborted) setLoadError(cause instanceof Error ? cause.message : API_MESSAGES.network);
+            } finally{
+                if (!controller.signal.aborted) setLoading(false);
+            }
+        })();
+        return ()=>controller.abort();
+    }, [
+        surface.apiRoute
+    ]);
+    const attached = new Set([
+        test.doc?.metrics?.primary,
+        ...test.doc?.metrics?.secondary ?? [],
+        ...test.doc?.metrics?.guardrails ?? []
+    ].filter((id)=>id != null).map(String));
+    const available = metrics.filter((item)=>!attached.has(String(item.id)));
+    const selected = available.find((item)=>String(item.id) === metric);
+    const disabled = transition.busy || test.hasUnsaved || test.saving === 'saving';
+    return /*#__PURE__*/ _jsxs(DialogFrame, {
+        title: C.addMetric,
+        onClose: ()=>{
+            if (!transition.busy) onClose();
+        },
+        children: [
+            loading ? /*#__PURE__*/ _jsx("p", {
+                role: "status",
+                children: R.loadingMetrics
+            }) : null,
+            /*#__PURE__*/ _jsxs("label", {
+                children: [
+                    R.role,
+                    /*#__PURE__*/ _jsxs("select", {
+                        value: role,
+                        disabled: disabled,
+                        onChange: (event)=>setRole(event.target.value),
+                        children: [
+                            /*#__PURE__*/ _jsx("option", {
+                                value: "secondary",
+                                children: R.supporting
+                            }),
+                            /*#__PURE__*/ _jsx("option", {
+                                value: "guardrail",
+                                children: R.guardrail
+                            })
+                        ]
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsxs("label", {
+                children: [
+                    R.metric,
+                    /*#__PURE__*/ _jsxs("select", {
+                        value: metric,
+                        disabled: disabled || loading,
+                        onChange: (event)=>setMetric(event.target.value),
+                        children: [
+                            /*#__PURE__*/ _jsx("option", {
+                                value: "",
+                                children: R.chooseMetric
+                            }),
+                            available.map((item)=>/*#__PURE__*/ _jsx("option", {
+                                    value: String(item.id),
+                                    children: item.name
+                                }, item.id))
+                        ]
+                    })
+                ]
+            }),
+            !loading && !loadError && !available.length ? /*#__PURE__*/ _jsx("p", {
+                children: R.noMetrics
+            }) : null,
+            loadError || transition.error ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: loadError ?? transition.error
+            }) : null,
+            /*#__PURE__*/ _jsx(Button, {
+                disabled: disabled || loading || !!loadError || !selected,
+                onClick: ()=>{
+                    if (selected && test.doc) void transition.run(()=>createApi(surface.apiRoute).addMetric(test.doc.id, {
+                            metric: selected.id,
+                            role
+                        }));
+                },
+                children: C.addMetric
+            }),
+            /*#__PURE__*/ _jsx(Button, {
+                disabled: transition.busy,
+                onClick: onClose,
+                children: A.cancel
+            })
+        ]
+    });
+}

package/dist/admin/surface/readiness/Banner.d.ts

@@ -0,0 +1,2 @@
+import type { SectionProps } from '../contracts.js';
+export declare function Banner(props: SectionProps): import("react").JSX.Element | null;

package/dist/admin/surface/readiness/Banner.js

@@ -0,0 +1,138 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Button } from '@payloadcms/ui';
+import { actionGroupLabel, availableActions } from '../../actions/actions.model.js';
+import { createApi } from '../../api.js';
+import { READINESS_COPY as C, decidedCopy, nextCopy, runningCopy, stoppedCopy } from '../../copy/readiness.js';
+import { daysRemaining, displayDate, nextStep } from './readiness.model.js';
+import { AddMetricAction, AllocateAction, ConfirmAction } from './ActionDialogs.js';
+import { useTransition } from './useTransition.js';
+const RUNNING_ACTIONS = [
+    'stop',
+    'add-metric',
+    'allocate'
+];
+export function Banner(props) {
+    return props.test.doc ? /*#__PURE__*/ _jsx(BannerContent, {
+        ...props
+    }, `${props.test.doc.id}/${props.test.doc.status}`) : null;
+}
+function BannerContent({ test, surface }) {
+    const [selected, setSelected] = useState(null);
+    const [people, setPeople] = useState(null);
+    const transition = useTransition(test);
+    const doc = test.doc;
+    useEffect(()=>{
+        let active = true;
+        setPeople(null);
+        if (surface.canReadResults && doc.status === 'running') {
+            void createApi(surface.apiRoute).summary([
+                doc.id
+            ]).then((result)=>{
+                const count = result.ok ? result.data?.[doc.id]?.exposures : undefined;
+                if (active) setPeople(typeof count === 'number' && Number.isFinite(count) ? count : null);
+            });
+        }
+        return ()=>{
+            active = false;
+        };
+    }, [
+        doc.id,
+        doc.status,
+        surface.apiRoute,
+        surface.canReadResults
+    ]);
+    const decision = doc.decision;
+    const winner = actionGroupLabel(decision?.winnerArm ?? 'control', doc.arms.find((item)=>item.key === decision?.winnerArm)?.label);
+    const next = nextStep(test.preflight, {
+        ...doc,
+        flagPoints: surface.flagPoints
+    });
+    const setup = doc.status === 'draft' || doc.status === 'stopped';
+    const ready = Boolean(test.preflight && !test.preflightPending && !test.preflightError && test.preflight.checks.every((check)=>check.ok));
+    const unsaved = test.hasUnsaved || test.saving === 'saving';
+    const startReason = unsaved ? C.saveFirst : next?.sentence ?? (!ready ? test.preflightError ? C.checkError : C.checking : undefined);
+    const actions = availableActions({
+        status: doc.status,
+        kind: doc.kind,
+        arms: doc.arms,
+        decision,
+        canManage: surface.canManage
+    }).filter((action)=>setup ? action.id === 'start' : doc.status === 'running' ? RUNNING_ACTIONS.includes(action.id) : true).sort((a, b)=>doc.status === 'running' ? RUNNING_ACTIONS.indexOf(a.id) - RUNNING_ACTIONS.indexOf(b.id) : 0).map((action)=>action.id === 'add-metric' ? {
+            ...action,
+            label: C.addMetric
+        } : action.id === 'allocate' ? {
+            ...action,
+            label: C.allocate
+        } : action);
+    const action = actions.find((item)=>item.id === selected);
+    const sentence = setup ? ready ? C.ready : next ? nextCopy(next.sentence) : test.preflightError ? C.checkError : C.checking : doc.status === 'running' ? runningCopy(displayDate(doc.startedAt), people, daysRemaining(doc, Date.now())) : doc.status === 'decided' ? decidedCopy(displayDate(doc.decidedAt), winner) : C.archived;
+    return /*#__PURE__*/ _jsxs("div", {
+        className: `xp-readiness xp-readiness--${setup && ready ? 'ready' : 'neutral'}`,
+        style: {
+            padding: '1rem',
+            border: '1px solid var(--theme-elevation-200)',
+            borderRadius: 'var(--style-radius-s)',
+            background: setup && ready ? 'var(--theme-success-100)' : 'var(--theme-elevation-50)',
+            color: 'var(--theme-text)'
+        },
+        children: [
+            /*#__PURE__*/ _jsx("p", {
+                role: "status",
+                children: setup && next && !ready && next.section !== 'header' ? /*#__PURE__*/ _jsx("a", {
+                    href: `#section-${next.section}`,
+                    children: sentence
+                }) : sentence
+            }),
+            doc.status === 'stopped' ? /*#__PURE__*/ _jsx("p", {
+                children: stoppedCopy(displayDate(doc.stoppedAt))
+            }) : null,
+            /*#__PURE__*/ _jsx("div", {
+                className: "xp-readiness__actions",
+                style: {
+                    display: 'flex',
+                    gap: '0.75rem',
+                    flexWrap: 'wrap',
+                    alignItems: 'center'
+                },
+                children: actions.map((item)=>{
+                    const reason = item.id === 'start' ? startReason : unsaved ? C.saveFirst : item.id === 'allocate' && doc.allocation >= 100 ? C.everyone : undefined;
+                    const disabled = transition.busy || !!selected || !!reason;
+                    return /*#__PURE__*/ _jsx("span", {
+                        title: reason,
+                        children: /*#__PURE__*/ _jsx(Button, {
+                            buttonStyle: item.tone === 'primary' ? 'primary' : 'secondary',
+                            disabled: disabled,
+                            onClick: ()=>{
+                                if (disabled) return;
+                                if (item.id === 'start' && doc.status === 'draft') void transition.run(()=>createApi(surface.apiRoute).start(doc.id));
+                                else setSelected(item.id);
+                            },
+                            children: item.label
+                        })
+                    }, item.id);
+                })
+            }),
+            transition.error ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: transition.error
+            }) : null,
+            action?.id === 'allocate' ? /*#__PURE__*/ _jsx(AllocateAction, {
+                test: test,
+                surface: surface,
+                onClose: ()=>setSelected(null)
+            }) : action?.id === 'add-metric' ? /*#__PURE__*/ _jsx(AddMetricAction, {
+                test: test,
+                surface: surface,
+                onClose: ()=>setSelected(null)
+            }) : action ? /*#__PURE__*/ _jsx(ConfirmAction, {
+                test: test,
+                surface: surface,
+                action: action,
+                winnerLabel: winner,
+                onClose: ()=>setSelected(null)
+            }) : null
+        ]
+    });
+}

package/dist/admin/surface/readiness/SaveStatus.d.ts

@@ -0,0 +1,4 @@
+import type { TestDocApi } from '../contracts.js';
+export declare function SaveStatus({ test }: {
+    test: TestDocApi;
+}): import("react").JSX.Element;

package/dist/admin/surface/readiness/SaveStatus.js

@@ -0,0 +1,50 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { Button } from '@payloadcms/ui';
+import { READINESS_COPY as C } from '../../copy/readiness.js';
+export function SaveStatus({ test }) {
+    const inFlight = useRef(false);
+    const [retrying, setRetrying] = useState(false);
+    async function retry() {
+        if (inFlight.current || test.preflightPending || test.hasUnsaved || test.saving === 'saving') return;
+        inFlight.current = true;
+        setRetrying(true);
+        try {
+            await test.refreshPreflight();
+        } finally{
+            inFlight.current = false;
+            setRetrying(false);
+        }
+    }
+    const message = test.saving === 'saving' ? C.saving : test.saving === 'saved' ? C.saved : test.saving === 'error' ? C.saveError : null;
+    return /*#__PURE__*/ _jsxs("div", {
+        className: "xp-save-status",
+        "aria-live": "polite",
+        children: [
+            message ? /*#__PURE__*/ _jsx("span", {
+                role: test.saving === 'error' ? 'alert' : 'status',
+                children: message
+            }) : null,
+            test.preflightError ? /*#__PURE__*/ _jsxs("div", {
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        role: "alert",
+                        children: C.checkError
+                    }),
+                    ' ',
+                    /*#__PURE__*/ _jsx("span", {
+                        title: test.hasUnsaved || test.saving === 'saving' ? C.saveFirst : undefined,
+                        children: /*#__PURE__*/ _jsx(Button, {
+                            disabled: retrying || test.preflightPending || test.hasUnsaved || test.saving === 'saving',
+                            onClick: ()=>{
+                                void retry();
+                            },
+                            children: C.retry
+                        })
+                    })
+                ]
+            }) : null
+        ]
+    });
+}

package/dist/admin/surface/readiness/parts.d.ts

@@ -0,0 +1,2 @@
+import type { ReadinessParts } from '../contracts.js';
+export declare const readinessParts: ReadinessParts;

package/dist/admin/surface/readiness/parts.js

@@ -0,0 +1,9 @@
+'use client';
+import { Banner } from './Banner.js';
+import { SaveStatus } from './SaveStatus.js';
+import { sectionDone } from './readiness.model.js';
+export const readinessParts = {
+    Banner,
+    SaveStatus,
+    sectionDone
+};

package/dist/admin/surface/readiness/readiness.model.d.ts

@@ -0,0 +1,22 @@
+import type { ReadinessCode, PreflightResult } from '../../../types/endpoints.js';
+import type { SerializedFlagPoint } from '../../../types/admin.js';
+import type { TestDocument } from '../testDocument.model.js';
+import { type SectionId } from '../contracts.js';
+export type ReadinessContext = Pick<TestDocument, 'arms' | 'unitType' | 'flagPoint'> & {
+    flagPoints?: readonly Pick<SerializedFlagPoint, 'id' | 'params'>[];
+};
+/** Exhaustive mapping of the checkStart ReadinessCode union, including all ten invariant checks. */
+export declare const READINESS: Record<ReadinessCode, {
+    section: SectionId | 'header';
+    next(detail: unknown, ctx: ReadinessContext): string | null;
+}>;
+export declare function nextStep(preflight: PreflightResult | null, ctx: ReadinessContext): {
+    section: "header" | SectionId;
+    sentence: string;
+    code: ReadinessCode;
+} | null;
+export declare function sectionDone(test: {
+    preflight: PreflightResult | null;
+}): Record<SectionId, boolean>;
+export declare function displayDate(value: unknown): string | null;
+export declare function daysRemaining(doc: TestDocument, now: number): number | null;

package/dist/admin/surface/readiness/readiness.model.js

@@ -0,0 +1,107 @@
+import { actionGroupLabel } from '../../actions/actions.model.js';
+import { READINESS_COPY as C, attributeNext, contentNext, goalPeopleNext, parameterNext, placementNext, ruleNext, versionsNext } from '../../copy/readiness.js';
+import { SECTION_ORDER } from '../contracts.js';
+const object = (value)=>value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const first = (value)=>object(Array.isArray(value) ? value[0] : value);
+const text = (value, fallback)=>typeof value === 'string' && value.trim() ? value.trim() : fallback;
+const detailText = (value, fallback)=>typeof value === 'string' ? text(value, fallback) : text(first(value).message ?? first(value).detail, fallback);
+const group = (key, ctx)=>{
+    const found = ctx.arms.find((item)=>item.key === key);
+    return found ? actionGroupLabel(found.key, found.label) : C.groupFallback;
+};
+const row = (section, next)=>({
+        section,
+        next
+    });
+const versions = row('versions', (detail)=>versionsNext(detailText(detail, C.versionFallback)));
+/** Exhaustive mapping of the checkStart ReadinessCode union, including all ten invariant checks. */ export const READINESS = {
+    'invalid-status': row('header', ()=>null),
+    'no-placements': row('what', ()=>C.noPlacements),
+    'empty-slot': row('versions', (detail, ctx)=>{
+        const placements = Array.isArray(detail) ? detail : [];
+        const missing = ctx.arms.find((item)=>item.kind !== 'holdout' && placements.some((placement)=>{
+                const slots = object(object(placement).slots);
+                return !item.slot || !(typeof slots[item.slot] === 'number' && Number(slots[item.slot]) > 0);
+            }));
+        return contentNext(group(missing?.key ?? first(detail).arm, ctx));
+    }),
+    'flag-no-point': row('what', ()=>C.noPoint),
+    'flag-params-invalid': row('versions', (detail, ctx)=>{
+        const issue = first(detail);
+        const point = ctx.flagPoints?.find((item)=>item.id === ctx.flagPoint);
+        const parameter = typeof issue.field === 'string' ? point?.params[issue.field]?.label ?? issue.field : C.parameterFallback;
+        return parameterNext(parameter, group(issue.arm, ctx));
+    }),
+    'flag-point-busy': row('what', ()=>C.busy),
+    'flag-placement-missing': row('versions', (detail, ctx)=>{
+        const value = object(detail);
+        const placement = first(value.placements);
+        const missing = Array.isArray(value.missing) ? value.missing[0] : undefined;
+        return placementNext(group(placement.arm ?? missing, ctx), detailText(typeof detail === 'string' ? detail : placement, ''));
+    }),
+    'no-primary-metric': row('win', ()=>C.noGoal),
+    'unknown-metric-source': row('win', ()=>C.unknownGoal),
+    'unit-source-mismatch': row('win', (_, ctx)=>goalPeopleNext(ctx.unitType === 'user' ? 'signed-in users' : 'visitors')),
+    'no-planned-duration': row('length', ()=>C.noDuration),
+    'no-reach-per-day': row('length', ()=>C.noReach),
+    'layer-full': row('versions', ()=>C.full),
+    'layer-unit-mismatch': row('header', ()=>C.differentPeople),
+    'page-no-targets': row('versions', ()=>C.noTargets),
+    'page-user-unit': row('header', ()=>C.pageVisitors),
+    'invalid-targeting-rule': row('who', (detail)=>{
+        const attributes = object(detail).attributes;
+        return ruleNext(detailText(detail, Array.isArray(attributes) && attributes.length ? attributes.map(String).join(', ') : C.ruleFallback));
+    }),
+    'undeclared-targeting-key': row('who', (detail)=>{
+        const attributes = object(detail).attributes;
+        return attributeNext(text(Array.isArray(attributes) ? attributes[0] : object(detail).attribute, C.attributeFallback));
+    }),
+    'weights-total': versions,
+    'control-count': versions,
+    'control-first': versions,
+    'holdout-count': versions,
+    'holdout-last': versions,
+    'variant-count': versions,
+    'invalid-key': versions,
+    'duplicate-key': versions,
+    'slot-required': versions,
+    'duplicate-slot': versions
+};
+export function nextStep(preflight, ctx) {
+    for (const section of [
+        'header',
+        ...SECTION_ORDER
+    ]){
+        for (const check of preflight?.checks ?? []){
+            const mapping = READINESS[check.code];
+            if (check.ok || mapping.section !== section) continue;
+            const sentence = mapping.next(check.detail, ctx);
+            if (sentence) return {
+                section,
+                sentence,
+                code: check.code
+            };
+        }
+    }
+    return null;
+}
+export function sectionDone(test) {
+    return Object.fromEntries(SECTION_ORDER.map((section)=>[
+            section,
+            test.preflight ? !test.preflight.checks.some((check)=>!check.ok && READINESS[check.code].section === section) : section === 'who' || section === 'advanced'
+        ]));
+}
+export function displayDate(value) {
+    if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) return null;
+    return new Intl.DateTimeFormat('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        timeZone: 'UTC'
+    }).format(new Date(value));
+}
+export function daysRemaining(doc, now) {
+    const days = doc.analysis?.plannedDurationDays;
+    const start = typeof doc.startedAt === 'string' ? Date.parse(doc.startedAt) : NaN;
+    return typeof days === 'number' && days > 0 && Number.isFinite(start) ? Math.max(0, Math.ceil(days - (now - start) / 86_400_000)) : null;
+}

package/dist/admin/surface/readiness/useTransition.d.ts

@@ -0,0 +1,10 @@
+import type { ApiResult } from '../../api.js';
+import type { TestDocApi } from '../contracts.js';
+/** The ref closes the gap before React renders the disabled button. */
+export declare function useTransition(test: TestDocApi, onSuccess?: () => void): {
+    busy: boolean;
+    error: string | null;
+    run: (request: () => Promise<ApiResult<unknown>>, { reloadOnSuccess }?: {
+        reloadOnSuccess?: boolean | undefined;
+    }) => Promise<void>;
+};

package/dist/admin/surface/readiness/useTransition.js

@@ -0,0 +1,34 @@
+'use client';
+import { useRef, useState } from 'react';
+import { API_MESSAGES } from '../../copy/common.js';
+/** The ref closes the gap before React renders the disabled button. */ export function useTransition(test, onSuccess) {
+    const inFlight = useRef(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    async function run(request, { reloadOnSuccess = true } = {}) {
+        if (inFlight.current || test.hasUnsaved || test.saving === 'saving') return;
+        inFlight.current = true;
+        setBusy(true);
+        setError(null);
+        try {
+            const result = await request();
+            if (result.ok) {
+                if (reloadOnSuccess) {
+                    await test.reload();
+                    onSuccess?.();
+                    // Keep the successful action locked until the reloaded document replaces this view.
+                    return;
+                }
+            } else setError(result.message);
+        } catch  {
+            setError(API_MESSAGES.network);
+        }
+        inFlight.current = false;
+        setBusy(false);
+    }
+    return {
+        busy,
+        error,
+        run
+    };
+}