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

package/dist/admin/surface/results/ResultsBody.d.ts

@@ -0,0 +1,7 @@
+import '../../styles.js';
+import type { DocId } from '../../../types/contracts.js';
+import type { SurfaceProps } from '../contracts.js';
+export declare function ResultsBody({ id, surface }: {
+    id: DocId;
+    surface: SurfaceProps;
+}): import("react").JSX.Element;

package/dist/admin/surface/results/ResultsBody.js

@@ -0,0 +1,262 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import '../../styles.js';
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '@payloadcms/ui';
+import { RESULTS_COPY as C } from '../../copy/results.js';
+import { RESULTS_SURFACE_COPY } from '../../copy/recommendation.js';
+import { ACTIONS_COPY } from '../../copy/actions.js';
+import { API_MESSAGES } from '../../copy/common.js';
+import { armLabel } from '../../labels.js';
+import { PreviewLinks } from '../../PreviewLinks.js';
+import { VerdictCard } from '../../results/VerdictCard.js';
+import { ArmTable } from '../../results/ArmTable.js';
+import { DataQualityPanel } from '../../results/DataQualityPanel.js';
+import { CiChart } from '../../results/CiChart.js';
+import { armRows, collectingLine, dataQuality, defaultRound, guardrailChips, powerLine, rolloutLine, roundOptions, verdictCard } from '../../results/results.model.js';
+import { recommendation } from './recommendation.model.js';
+import { useResults } from './useResults.js';
+import { DecideDialog } from '../../actions/DecideDialog.js';
+export function ResultsBody({ id, surface }) {
+    // A different test owns an independent selection and action lifecycle.
+    return /*#__PURE__*/ _jsx(ResultsContent, {
+        id: id,
+        surface: surface
+    }, `${surface.apiRoute}/${id}`);
+}
+function ResultsContent({ id, surface }) {
+    const results = useResults(id, surface);
+    const { api, doc, round, phases, state, data } = results;
+    const manage = surface.canManage && surface.canReadResults;
+    const [placements, setPlacements] = useState(null);
+    const [previewError, setPreviewError] = useState(null);
+    const [previewRefresh, setPreviewRefresh] = useState(0);
+    const [busy, setBusy] = useState(false);
+    const inFlight = useRef(false);
+    const mounted = useRef(true);
+    const [actionError, setActionError] = useState(null);
+    const [deciding, setDeciding] = useState(false);
+    useEffect(()=>{
+        mounted.current = true;
+        return ()=>{
+            mounted.current = false;
+        };
+    }, []);
+    useEffect(()=>{
+        let active = true;
+        setPlacements(null);
+        setPreviewError(null);
+        if (manage) void api.preflight(id).then((result)=>{
+            if (!active) return;
+            if (result.ok && result.data) setPlacements(result.data.placements);
+            else setPreviewError(result.ok ? API_MESSAGES.unreadable : result.message);
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        api,
+        id,
+        manage,
+        previewRefresh
+    ]);
+    async function recompute() {
+        if (!manage || inFlight.current) return;
+        inFlight.current = true;
+        setBusy(true);
+        setActionError(null);
+        try {
+            const result = await api.recompute(id);
+            if (!mounted.current) return;
+            if (result.ok) results.reload();
+            else setActionError(result.message);
+        } finally{
+            inFlight.current = false;
+            if (mounted.current) setBusy(false);
+        }
+    }
+    const phase = data?.phases.find((phase)=>phase.phase === round);
+    const snapshot = data?.snapshot;
+    const newestRound = defaultRound({
+        phases,
+        status: 'running'
+    });
+    const latestPhase = phases.find((phase)=>phase.phase === newestRound);
+    const decision = data?.decision ?? doc?.decision;
+    const status = doc?.status ?? (data?.decision ? 'decided' : latestPhase?.phaseKind === 'test' && latestPhase.endedAt === null ? 'running' : 'stopped');
+    // ADM-06b: an older round never inherits the live test's running status.
+    const lineStatus = status === 'running' && round === newestRound ? 'running' : 'stopped';
+    const isDecidedTestRound = status === 'decided' && phase?.phaseKind === 'test' && decision?.phase === round;
+    const winner = phase?.arms.find((arm)=>arm.key === decision?.winnerArm)?.label ?? armLabel(decision?.winnerArm ?? 'control');
+    const card = snapshot ? verdictCard({
+        snapshot,
+        decisionSnapshot: data?.decisionSnapshot,
+        isDecidedTestRound,
+        winnerLabel: winner
+    }) : null;
+    const context = {
+        phase,
+        inLayer: doc?.layer != null,
+        layerSlices: doc?.layerSlices,
+        allocation: doc?.allocation
+    };
+    const primary = phase?.metrics.find((metric)=>metric.role === 'primary');
+    // The endpoint decides the current round; historical rounds are read-only.
+    const canDecide = manage && (status === 'running' || status === 'stopped') && phase?.phaseKind === 'test' && round === newestRound && state === 'ready' && Boolean(snapshot);
+    return /*#__PURE__*/ _jsxs("div", {
+        className: "xp-results",
+        style: {
+            color: 'var(--theme-text)'
+        },
+        children: [
+            phases.length > 0 ? /*#__PURE__*/ _jsxs("label", {
+                children: [
+                    C.round,
+                    /*#__PURE__*/ _jsx("select", {
+                        disabled: deciding,
+                        value: round ?? '',
+                        onChange: (event)=>results.setRound(Number(event.target.value)),
+                        children: roundOptions(phases).map((option)=>/*#__PURE__*/ _jsx("option", {
+                                value: option.value,
+                                children: option.label
+                            }, option.value))
+                    })
+                ]
+            }) : null,
+            state === 'loading' ? /*#__PURE__*/ _jsx("p", {
+                role: "status",
+                children: data ? C.refreshing : C.loading
+            }) : state === 'forbidden' ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: C.forbidden
+            }) : state === 'missing' ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: RESULTS_SURFACE_COPY.missing
+            }) : state === 'error' ? /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        role: "alert",
+                        children: results.error
+                    }),
+                    /*#__PURE__*/ _jsx(Button, {
+                        onClick: results.reload,
+                        children: C.retry
+                    })
+                ]
+            }) : null,
+            phase && snapshot ? /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        style: {
+                            background: 'var(--theme-elevation-50)',
+                            paddingTop: '1rem'
+                        },
+                        children: [
+                            /*#__PURE__*/ _jsx("p", {
+                                className: "xp-recommendation",
+                                style: {
+                                    margin: '0 1rem'
+                                },
+                                children: recommendation({
+                                    snapshot,
+                                    phase,
+                                    status: lineStatus,
+                                    plannedDurationDays: round === newestRound ? doc?.analysis?.plannedDurationDays : undefined
+                                })
+                            }),
+                            /*#__PURE__*/ _jsx(VerdictCard, {
+                                model: card,
+                                guardrails: guardrailChips(snapshot),
+                                power: powerLine({
+                                    snapshot,
+                                    phaseKind: phase.phaseKind,
+                                    status: lineStatus
+                                }),
+                                collecting: collectingLine({
+                                    snapshot,
+                                    phaseKind: phase.phaseKind,
+                                    status: lineStatus
+                                }, context),
+                                sinceShipping: rolloutLine(snapshot, phase, phases, decision ?? undefined)
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx(DataQualityPanel, {
+                        items: dataQuality(snapshot, context)
+                    }),
+                    [
+                        'primary',
+                        'secondary',
+                        'guardrail'
+                    ].map((role)=>{
+                        const metrics = phase.metrics.filter((metric)=>metric.role === role);
+                        return metrics.length ? /*#__PURE__*/ _jsxs("section", {
+                            children: [
+                                /*#__PURE__*/ _jsx("h2", {
+                                    children: C[role]
+                                }),
+                                metrics.map((metric)=>/*#__PURE__*/ _jsx(ArmTable, {
+                                        caption: metric.name,
+                                        method: snapshot.method,
+                                        metricKind: metric.kind,
+                                        rows: armRows({
+                                            snapshot,
+                                            phase,
+                                            metricId: metric.metricId
+                                        })
+                                    }, metric.metricId))
+                            ]
+                        }, role) : null;
+                    }),
+                    primary ? /*#__PURE__*/ _jsx(CiChart, {
+                        series: data?.series,
+                        metricId: primary.metricId,
+                        metricName: primary.name,
+                        phase: phase,
+                        contentChanges: snapshot.contentChanges
+                    }) : null
+                ]
+            }) : state === 'empty' || state === 'ready' ? /*#__PURE__*/ _jsx("p", {
+                children: C.empty
+            }) : null,
+            manage && placements ? /*#__PURE__*/ _jsx(PreviewLinks, {
+                experimentId: id,
+                placements: placements,
+                arms: doc?.arms ?? []
+            }) : null,
+            manage && previewError ? /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        role: "alert",
+                        children: previewError
+                    }),
+                    /*#__PURE__*/ _jsx(Button, {
+                        onClick: ()=>setPreviewRefresh((value)=>value + 1),
+                        children: C.retryPreview
+                    })
+                ]
+            }) : null,
+            manage ? /*#__PURE__*/ _jsx(Button, {
+                disabled: busy || deciding,
+                onClick: ()=>{
+                    void recompute();
+                },
+                children: busy ? C.recomputing : C.recompute
+            }) : null,
+            canDecide ? /*#__PURE__*/ _jsx(Button, {
+                disabled: busy || deciding,
+                onClick: ()=>setDeciding(true),
+                children: ACTIONS_COPY.decide
+            }) : null,
+            deciding && manage && phase ? /*#__PURE__*/ _jsx(DecideDialog, {
+                id: id,
+                arms: phase.arms,
+                onClose: ()=>setDeciding(false)
+            }) : null,
+            actionError ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: actionError
+            }) : null
+        ]
+    });
+}

package/dist/admin/surface/results/recommendation.model.d.ts

@@ -0,0 +1,12 @@
+import type { PhaseSummary } from '../../../types/endpoints.js';
+import type { Status } from '../../../types/contracts.js';
+import type { Snapshot, VerdictCode } from '../../../types/snapshot.js';
+export interface RecommendationContext {
+    snapshot: Snapshot;
+    phase?: PhaseSummary;
+    plannedDurationDays?: number | null;
+    status?: Status;
+}
+/** Select stored findings and format them; never run inference in the admin. */
+export declare const RECOMMENDATION: Record<VerdictCode, (ctx: RecommendationContext) => string>;
+export declare const recommendation: (ctx: RecommendationContext) => string;

package/dist/admin/surface/results/recommendation.model.js

@@ -0,0 +1,59 @@
+import { armLabel } from '../../labels.js';
+import { formatCount, formatPercent } from '../../results/format.js';
+import { RECOMMENDATION_COPY as C, collectingRecommendation, guardrailRecommendation, mixedRecommendation, rolloutCollectingRecommendation, rolloutReadoutRecommendation, runningRecommendation, winnerRecommendation, worseRecommendation, storedGuardrailFinding } from '../../copy/recommendation.js';
+function label(ctx, key, fallback = C.group) {
+    const stored = ctx.phase?.arms.find((arm)=>arm.key === key)?.label.trim();
+    return stored || (key && [
+        'control',
+        'variantA',
+        'variantB',
+        'variantC',
+        'holdout'
+    ].includes(key) ? armLabel(key) : fallback);
+}
+const primary = ({ snapshot })=>snapshot.metrics.find((metric)=>metric.role === 'primary');
+const worse = (ctx)=>primary(ctx)?.comparisons.find((comparison)=>comparison.significant === 'worse' && ctx.phase?.arms.some((arm)=>arm.key === comparison.arm && arm.kind === 'variant'))?.arm;
+const winner = (ctx)=>label(ctx, ctx.snapshot.winnerArm ?? ctx.snapshot.verdict.recommendedArm, C.winner);
+/** Select stored findings and format them; never run inference in the admin. */ export const RECOMMENDATION = {
+    unavailable: ()=>C.unavailable,
+    'data-problem': ()=>C.dataProblem,
+    'guardrail-failing': (ctx)=>{
+        const guardrail = ctx.snapshot.guardrails.find((guardrail)=>guardrail.status === 'failing');
+        const metric = ctx.snapshot.metrics.find((metric)=>metric.metricId === guardrail?.metricId);
+        // Guardrail safety uses one-sided tests, distinct from comparison significance.
+        // Select the group the server named; do not re-infer harm from the table.
+        const group = ctx.phase?.arms.find((arm)=>ctx.snapshot.verdict.finding === storedGuardrailFinding(arm.label.trim() || armLabel(arm.key), metric?.name ?? C.guardrail));
+        return guardrailRecommendation(label(ctx, ctx.snapshot.verdict.worstArm ?? group?.key), metric?.name ?? C.guardrail);
+    },
+    collecting: (ctx)=>{
+        if (ctx.status === 'stopped') return C.stoppedCollecting;
+        const needed = ctx.snapshot.power.exposuresNeededPerArm;
+        const groups = ctx.phase?.arms.filter((arm)=>arm.kind !== 'holdout').length ?? ctx.snapshot.k + 1;
+        return needed === null ? C.collecting : collectingRecommendation(formatCount(Math.round(needed * groups)));
+    },
+    'original-better': ()=>C.originalBetter,
+    'worse-none-better': (ctx)=>worseRecommendation(label(ctx, worse(ctx))),
+    winner: (ctx)=>winnerRecommendation(label(ctx, ctx.snapshot.verdict.recommendedArm)),
+    mixed: (ctx)=>mixedRecommendation(label(ctx, ctx.snapshot.verdict.recommendedArm), label(ctx, worse(ctx))),
+    'keep-running': (ctx)=>{
+        // Same condition as the server's long-duration branch (src/results/verdict.ts).
+        const power = ctx.snapshot.power;
+        if (!power.feasible || power.daysRemaining !== null && power.daysRemaining > 90) return C.longDuration;
+        const days = ctx.plannedDurationDays;
+        const start = Date.parse(ctx.phase?.startedAt ?? '');
+        const end = days != null && Number.isFinite(days) && days > 0 ? start + days * 86_400_000 : NaN;
+        return Number.isFinite(end) ? runningRecommendation(new Intl.DateTimeFormat('en-US', {
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+            timeZone: 'UTC'
+        }).format(end)) : C.keepRunning;
+    },
+    'no-difference': ()=>C.noDifference,
+    'rollout-collecting': (ctx)=>rolloutCollectingRecommendation(winner(ctx)),
+    'rollout-readout': (ctx)=>rolloutReadoutRecommendation(winner(ctx), formatPercent(primary(ctx)?.comparisons.find((comparison)=>comparison.arm === (ctx.snapshot.winnerArm ?? ctx.snapshot.verdict.recommendedArm))?.lift, true))
+};
+export const recommendation = (ctx)=>{
+    const sentence = RECOMMENDATION[ctx.snapshot.verdict.code];
+    return sentence(ctx);
+};

package/dist/admin/surface/results/useResults.d.ts

@@ -0,0 +1,56 @@
+import type { DocId, Status } from '../../../types/contracts.js';
+import type { PhaseSummary, ResultsResponse } from '../../../types/endpoints.js';
+import { type ApiResult } from '../../api.js';
+export interface ResultsDocument {
+    status: Status;
+    arms: Array<{
+        key: string;
+        kind?: string;
+        label?: string;
+    }>;
+    decision?: {
+        phase: number;
+        winnerArm?: string;
+    } | null;
+    analysis?: {
+        plannedDurationDays?: number | null;
+    } | null;
+    layer?: unknown;
+    layerSlices?: number[];
+    allocation?: number;
+}
+export type ResultsLoadState = 'loading' | 'ready' | 'empty' | 'forbidden' | 'missing' | 'error';
+export declare function useResults(id: DocId, { apiRoute, canReadResults, canManage }: {
+    apiRoute: string;
+    canReadResults: boolean;
+    canManage?: boolean;
+}): {
+    api: {
+        start: (id: DocId) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        allocate: (id: DocId, body: import("../../../types/endpoints.js").AllocateBody) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        addMetric: (id: DocId, body: import("../../../types/endpoints.js").AddMetricBody) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        stop: (id: DocId) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        decide: (id: DocId, body: import("../../../types/endpoints.js").DecideBody) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        releaseHoldout: (id: DocId) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        makeContent: (id: DocId) => Promise<ApiResult<import("../../../types/endpoints.js").MakeContentResult>>;
+        archive: (id: DocId, body: import("../../../types/endpoints.js").ArchiveBody) => Promise<ApiResult<import("../../../types/endpoints.js").TransitionSuccess>>;
+        preflight: (id: DocId) => Promise<ApiResult<import("../../../types/endpoints.js").PreflightResult>>;
+        previewToken: (id: DocId, arm: string) => Promise<ApiResult<import("../../../types/endpoints.js").PreviewTokenResult>>;
+        results: (id: DocId, options?: {
+            phase?: number;
+            series?: boolean;
+        }) => Promise<ApiResult<ResultsResponse>>;
+        recompute: (id: DocId) => Promise<ApiResult<{
+            snapshotId: string;
+        }>>;
+        summary: (ids: readonly DocId[]) => Promise<ApiResult<import("../../../types/endpoints.js").SummaryResponse>>;
+    };
+    state: ResultsLoadState;
+    data: ResultsResponse | undefined;
+    phases: PhaseSummary[];
+    round: number | null;
+    doc: ResultsDocument | undefined;
+    error: string | undefined;
+    setRound: (next: number) => void;
+    reload: () => void;
+};

package/dist/admin/surface/results/useResults.js

@@ -0,0 +1,183 @@
+'use client';
+import { useEffect, useMemo, useState } from 'react';
+import { createApi } from '../../api.js';
+import { API_MESSAGES, refusalMessage } from '../../copy/common.js';
+import { defaultRound } from '../../results/results.model.js';
+// The shared API has no collection-document read.
+async function read(url, signal) {
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            credentials: 'include',
+            signal
+        });
+        const data = await response.json().catch(()=>undefined);
+        if (response.ok) return {
+            ok: true,
+            data
+        };
+        const envelope = data;
+        return {
+            ok: false,
+            status: response.status,
+            message: refusalMessage(undefined, response.status, envelope?.errors?.[0]?.message),
+            retryable: response.status >= 500
+        };
+    } catch  {
+        return {
+            ok: false,
+            status: 0,
+            message: API_MESSAGES.network,
+            retryable: true
+        };
+    }
+}
+export function useResults(id, { apiRoute, canReadResults, canManage = true }) {
+    const base = apiRoute.replace(/\/$/, '');
+    const key = JSON.stringify([
+        base,
+        String(id),
+        canReadResults,
+        canManage
+    ]);
+    const api = useMemo(()=>createApi(base), [
+        base
+    ]);
+    const [selection, setSelection] = useState({
+        key,
+        round: null
+    });
+    const round = selection.key === key ? selection.round : null;
+    const [refresh, setRefresh] = useState(0);
+    const [view, setView] = useState({
+        key,
+        round: null,
+        state: 'loading'
+    });
+    useEffect(()=>{
+        const controller = new AbortController();
+        const signal = controller.signal;
+        if (!canReadResults) {
+            setView({
+                key,
+                round,
+                state: 'forbidden'
+            });
+            return ()=>controller.abort();
+        }
+        setView((previous)=>({
+                key,
+                round,
+                state: 'loading',
+                ...previous.key === key ? {
+                    doc: previous.doc,
+                    phases: previous.phases,
+                    ...previous.round === round ? {
+                        data: previous.data
+                    } : {}
+                } : {}
+            }));
+        const encoded = encodeURIComponent(id);
+        void Promise.all([
+            canManage ? read(`${base}/xp-experiments/${encoded}?depth=0`, signal) : Promise.resolve({
+                ok: true,
+                data: undefined
+            }),
+            api.results(id, {
+                phase: round ?? undefined,
+                series: true
+            })
+        ]).then(([document, result])=>{
+            if (signal.aborted) return;
+            const failure = !document.ok ? document : !result.ok ? result : undefined;
+            if (failure || !document.ok || !result.ok || canManage && !document.data || !result.data) {
+                const state = failure?.status === 403 ? 'forbidden' : failure?.status === 404 ? 'missing' : 'error';
+                setView((previous)=>({
+                        key,
+                        round,
+                        state,
+                        phases: previous.key === key ? previous.phases : undefined,
+                        error: failure?.message ?? API_MESSAGES.unreadable,
+                        ...state === 'error' && previous.key === key && previous.round === round ? {
+                            data: previous.data,
+                            doc: previous.doc
+                        } : {}
+                    }));
+                return;
+            }
+            if (round === null) {
+                // Readers cannot GET the manager-only experiment collection. The results
+                // endpoint already selects the decision round (or latest test round).
+                const decision = result.data.decision ?? document.data?.decision;
+                const initial = defaultRound({
+                    phases: result.data.phases,
+                    decision,
+                    status: result.data.decision ? 'decided' : document.data?.status ?? 'running'
+                });
+                if (initial !== null && initial !== result.data.snapshot?.phase) {
+                    setView({
+                        key,
+                        round: null,
+                        state: 'loading',
+                        doc: document.data,
+                        phases: result.data.phases,
+                        data: {
+                            ...result.data,
+                            snapshot: null
+                        }
+                    });
+                    setSelection({
+                        key,
+                        round: initial
+                    });
+                    return;
+                }
+            }
+            setView({
+                key,
+                round: round ?? result.data.snapshot?.phase ?? null,
+                state: result.data.snapshot ? 'ready' : 'empty',
+                doc: document.data,
+                phases: result.data.phases,
+                data: result.data
+            });
+        });
+        return ()=>controller.abort();
+    }, [
+        api,
+        base,
+        id,
+        key,
+        canReadResults,
+        canManage,
+        round,
+        refresh
+    ]);
+    const current = view.key === key;
+    const matching = current && (round === null || view.round === round);
+    const selectedRound = round ?? (current ? view.round : null);
+    const state = !canReadResults ? 'forbidden' : matching ? view.state : 'loading';
+    const data = matching && canReadResults ? view.data : undefined;
+    // Preserve options while another round loads; its snapshot is never displayed.
+    const phases = current && canReadResults ? view.phases ?? [] : [];
+    return {
+        api,
+        state,
+        data,
+        phases,
+        round: selectedRound,
+        doc: current && canReadResults ? view.doc : undefined,
+        error: matching ? view.error : undefined,
+        setRound: (next)=>setSelection({
+                key,
+                round: next
+            }),
+        reload: ()=>{
+            setSelection({
+                key,
+                round: selectedRound
+            });
+            setRefresh((value)=>value + 1);
+        }
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { KindParts } from '../contracts.js';
+import './setting.css';
+export declare const settingParts: KindParts;