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

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

@@ -0,0 +1,61 @@
+import { EDITABLE_BY_STATUS, isEditable } from '../../collections/experiments/editability.js';
+import { lockedReason } from '../lockedNotice.model.js';
+const EDITABLE_FIELDS = [
+    'name',
+    'hypothesis',
+    'arms',
+    'targeting',
+    'allocation',
+    'flagPoint',
+    'metrics',
+    'analysis',
+    'exposurePolicy'
+];
+/** Drop unknown and locked keys even when the caller is untyped. Groups replace whole groups. */ export function editablePatch(status, partial) {
+    return Object.fromEntries(EDITABLE_FIELDS.flatMap((field)=>Object.hasOwn(partial, field) && partial[field] !== undefined && isEditable(status, field) ? [
+            [
+                field,
+                partial[field]
+            ]
+        ] : []));
+}
+function canonical(value) {
+    if (Array.isArray(value)) return value.map(canonical);
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).filter(([, nested])=>nested !== undefined).sort(([a], [b])=>a.localeCompare(b)).map(([key, nested])=>[
+            key,
+            canonical(nested)
+        ]));
+    return value;
+}
+/** Only changed top-level keys go on the wire; arrays and groups remain intact. */ export function changedPatch(saved, staged) {
+    return Object.fromEntries(Object.entries(editablePatch(saved.status, staged)).filter(([key, value])=>JSON.stringify(canonical(saved[key])) !== JSON.stringify(canonical(value))));
+}
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+/** Payload validation details may be nested under errors[0].data or top-level data. */ export function payloadFieldErrors(envelope, section = '_section', fallback = "Couldn't save these changes. Try again.") {
+    const root = object(envelope);
+    const errors = Array.isArray(root?.errors) ? root.errors : [];
+    const first = object(errors[0]);
+    const result = {};
+    const addDetails = (data)=>{
+        const details = object(data)?.errors;
+        if (!Array.isArray(details)) return;
+        for (const detail of details){
+            const error = object(detail);
+            if (typeof error?.message !== 'string') continue;
+            const path = typeof error.path === 'string' && error.path ? error.path : section;
+            result[path] = error.message;
+        }
+    };
+    addDetails(root?.data);
+    for (const error of errors)addDetails(object(error)?.data);
+    if (Object.keys(result).length === 0) {
+        const message = typeof first?.message === 'string' ? first.message : fallback;
+        const locked = /^(\S+) is locked in (\w+)$/.exec(message);
+        const field = locked?.[1];
+        const status = locked?.[2];
+        const reason = field && status && Object.hasOwn(EDITABLE_BY_STATUS, status) ? lockedReason(status, field, EDITABLE_BY_STATUS) : null;
+        if (field && reason) result[field] = reason;
+        else result[section] = message;
+    }
+    return result;
+}

package/dist/admin/surface/useTestDocument.d.ts

@@ -0,0 +1,22 @@
+import type { DocId } from '../../types/contracts.js';
+import type { PreflightResult } from '../../types/endpoints.js';
+import type { TestDocument, TestDocumentPatch } from './testDocument.model.js';
+/** Section data only: staging never saves. Call commit on blur or a section action. */
+export declare function useTestDocument(id: DocId, { apiRoute }: {
+    apiRoute: string;
+}): {
+    stage: (partial: TestDocumentPatch) => void;
+    commit: () => Promise<void>;
+    reload: () => Promise<void>;
+    refreshPreflight: () => Promise<void>;
+    doc: TestDocument | null;
+    preflight: PreflightResult | null;
+    preflightError: string | null;
+    preflightPending: boolean;
+    /** Includes staged edits and all queued or in-flight PATCHes. */
+    hasUnsaved: boolean;
+    loadState: "loading" | "ready" | "forbidden" | "missing" | "error";
+    saving: "idle" | "saving" | "saved" | "error";
+    /** Path-specific validation errors; _section is the fallback for a section-wide refusal. */
+    errors: Record<string, string>;
+};

package/dist/admin/surface/useTestDocument.js

@@ -0,0 +1,345 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { API_MESSAGES, refusalMessage } from '../copy/common.js';
+import { changedPatch, editablePatch, payloadFieldErrors } from './testDocument.model.js';
+// Saves outlive their mounted reader. Reopening the same document must wait for its queue.
+const drainingSaves = new Map();
+const initialView = ()=>({
+        doc: null,
+        preflight: null,
+        preflightError: null,
+        preflightPending: false,
+        hasUnsaved: false,
+        loadState: 'loading',
+        saving: 'idle',
+        errors: {}
+    });
+async function waitForDrain(draining, signal) {
+    if (!draining) return;
+    let timer;
+    let release;
+    const bounded = new Promise((resolve)=>{
+        release = resolve;
+        timer = setTimeout(resolve, 15_000);
+    });
+    signal.addEventListener('abort', release, {
+        once: true
+    });
+    try {
+        await Promise.race([
+            draining,
+            bounded
+        ]);
+    } finally{
+        clearTimeout(timer);
+        signal.removeEventListener('abort', release);
+    }
+}
+function optimistic(session) {
+    if (!session.saved) return null;
+    return [
+        ...session.queue,
+        session.pending
+    ].reduce((doc, patch)=>({
+            ...doc,
+            ...editablePatch(doc.status, patch)
+        }), session.saved);
+}
+function clearErrors(errors, patch) {
+    return Object.fromEntries(Object.entries(errors).filter(([path])=>!Object.hasOwn(patch, path.split('.')[0])));
+}
+function stage(session, partial) {
+    if (!session.saved || session.reloading || session.view.loadState !== 'ready' || session.controller.signal.aborted) return;
+    const patch = editablePatch(session.saved.status, partial);
+    if (!Object.keys(patch).length) return;
+    session.pending = {
+        ...session.pending,
+        ...patch
+    };
+    session.view.errors = clearErrors(session.view.errors, patch);
+    if (!session.queue.length) session.view.saving = 'idle';
+    session.publish();
+}
+/** Section data only: staging never saves. Call commit on blur or a section action. */ export function useTestDocument(id, { apiRoute }) {
+    const base = apiRoute.replace(/\/$/, '');
+    const documentId = String(id);
+    const key = JSON.stringify([
+        base,
+        documentId
+    ]);
+    const current = useRef(null);
+    const commitRef = useRef(null);
+    const defaultAttempts = useRef(new Set());
+    const [state, setState] = useState(()=>({
+            key,
+            view: initialView()
+        }));
+    const [reloadCount, setReloadCount] = useState(0);
+    useEffect(()=>{
+        const controller = new AbortController();
+        const session = {
+            key,
+            saved: null,
+            pending: {},
+            queue: [],
+            tail: Promise.resolve(),
+            view: initialView(),
+            controller,
+            reloading: false,
+            preflightReads: 0,
+            publish () {
+                if (controller.signal.aborted) return;
+                session.view.doc = session.view.loadState === 'ready' ? optimistic(session) : null;
+                session.view.hasUnsaved = session.queue.length > 0 || Object.keys(session.pending).length > 0;
+                session.view.preflightPending = session.preflightReads > 0;
+                setState({
+                    key,
+                    view: {
+                        ...session.view
+                    }
+                });
+            }
+        };
+        current.current = session;
+        const url = `${base}/xp-experiments/${encodeURIComponent(documentId)}?depth=0`;
+        let preflightRevision = 0;
+        async function refreshPreflight(initial = false) {
+            if (controller.signal.aborted) return;
+            const revision = ++preflightRevision;
+            session.preflightReads++;
+            session.publish();
+            // createApi has no signal option; this read must abort without cancelling submitted PATCHes.
+            let data;
+            let status = 0;
+            let message = API_MESSAGES.network;
+            try {
+                const response = await fetch(`${base}/xp/experiments/${encodeURIComponent(documentId)}/preflight`, {
+                    method: 'GET',
+                    credentials: 'include',
+                    signal: controller.signal
+                });
+                status = response.status;
+                const body = await response.json().catch(()=>undefined);
+                if (response.ok) {
+                    data = body;
+                    message = API_MESSAGES.unreadable;
+                } else {
+                    const envelope = body;
+                    const error = Array.isArray(envelope?.errors) ? envelope.errors[0] : undefined;
+                    message = refusalMessage(status === 501 ? 'not-implemented' : error?.code, status, typeof error?.message === 'string' ? error.message : undefined);
+                }
+            } catch  {
+                message = API_MESSAGES.network;
+            }
+            session.preflightReads--;
+            if (controller.signal.aborted) return;
+            if (revision !== preflightRevision) {
+                session.publish();
+                return;
+            }
+            if (data) {
+                session.view.preflight = data;
+                session.view.preflightError = null;
+                if (initial) session.view.loadState = 'ready';
+            } else {
+                if (initial) {
+                    session.view.loadState = status === 403 ? 'forbidden' : status === 404 ? 'missing' : 'error';
+                    session.view.errors = {
+                        ...session.view.errors,
+                        _section: message
+                    };
+                } else session.view.preflightError = message;
+            }
+            session.publish();
+        }
+        async function readDocument() {
+            const response = await fetch(url, {
+                method: 'GET',
+                credentials: 'include',
+                signal: controller.signal
+            });
+            if (!response.ok) throw new Error(API_MESSAGES.unreadable);
+            const doc = await response.json();
+            if (!doc || doc.id == null || !doc.status) throw new Error(API_MESSAGES.unreadable);
+            return doc;
+        }
+        // Capture each commit now, then diff against the latest server document when its turn arrives.
+        function commit() {
+            if (!session.saved || session.reloading || controller.signal.aborted || !Object.keys(session.pending).length) return session.tail;
+            const queued = session.pending;
+            session.pending = {};
+            session.queue.push(queued);
+            session.view.saving = 'saving';
+            session.publish();
+            const step = async ()=>{
+                let saved = false;
+                let changed = false;
+                let failed = false;
+                try {
+                    if (!session.saved) return;
+                    const patch = changedPatch(session.saved, queued);
+                    changed = Object.keys(patch).length > 0;
+                    if (changed) {
+                        const response = await fetch(url, {
+                            // Submitted saves belong to the queue, not the mounted reader's lifetime.
+                            method: 'PATCH',
+                            credentials: 'include',
+                            headers: {
+                                'Content-Type': 'application/json'
+                            },
+                            body: JSON.stringify(patch)
+                        });
+                        const body = await response.json().catch(()=>undefined);
+                        if (!response.ok) session.view.errors = {
+                            ...session.view.errors,
+                            ...payloadFieldErrors(body)
+                        };
+                        else {
+                            // Payload collection PATCH returns { doc, message }; GET returns the doc itself.
+                            const doc = body?.doc;
+                            const readable = doc && doc.id != null && doc.status;
+                            // A 2xx has applied even if its response body was lost. Preserve it while re-reading.
+                            session.saved = readable ? doc : {
+                                ...session.saved,
+                                ...patch
+                            };
+                            saved = true;
+                            // Keep readiness pending even while recovering an unreadable successful PATCH body.
+                            session.preflightReads++;
+                            session.publish();
+                            session.view.errors = clearErrors(session.view.errors, patch);
+                            delete session.view.errors._section;
+                            if (!readable && !controller.signal.aborted) session.saved = await readDocument();
+                        }
+                    }
+                } catch (error) {
+                    failed = true;
+                    session.view.errors = {
+                        ...session.view.errors,
+                        _section: error instanceof Error && error.message === API_MESSAGES.unreadable ? API_MESSAGES.unreadable : API_MESSAGES.network
+                    };
+                } finally{
+                    session.queue.shift();
+                    // Roll back only a refused commit. Later queued or uncommitted edits remain optimistic.
+                    session.view.saving = session.queue.length ? 'saving' : saved ? 'saved' : changed || failed ? 'error' : 'idle';
+                    session.publish();
+                }
+                if (saved) {
+                    try {
+                        await refreshPreflight();
+                    } finally{
+                        session.preflightReads--;
+                        session.publish();
+                    }
+                }
+            };
+            // Recover both the preceding tail and this step: unexpected throws must not strand later saves.
+            session.tail = session.tail.then(step, step).catch(()=>{
+                session.view.errors = {
+                    ...session.view.errors,
+                    _section: API_MESSAGES.network
+                };
+                session.view.saving = session.queue.length ? 'saving' : 'error';
+                session.publish();
+            });
+            return session.tail;
+        }
+        // Keep callbacks attached to the session, including during automatic default persistence.
+        commitRef.current = {
+            session,
+            commit,
+            refreshPreflight: ()=>refreshPreflight()
+        };
+        session.publish();
+        void (async ()=>{
+            try {
+                await waitForDrain(drainingSaves.get(key), controller.signal);
+                if (controller.signal.aborted) return;
+                const response = await fetch(url, {
+                    method: 'GET',
+                    credentials: 'include',
+                    signal: controller.signal
+                });
+                if (controller.signal.aborted) return;
+                if (!response.ok) {
+                    session.view.loadState = response.status === 403 ? 'forbidden' : response.status === 404 ? 'missing' : 'error';
+                    session.publish();
+                    return;
+                }
+                const doc = await response.json();
+                if (controller.signal.aborted) return;
+                if (doc.id == null || !doc.status) throw new Error(API_MESSAGES.unreadable);
+                session.saved = doc;
+                await refreshPreflight(true);
+                if (controller.signal.aborted) return;
+                session.publish();
+                if (!defaultAttempts.current.has(key) && session.view.loadState === 'ready' && (doc.status === 'draft' || doc.status === 'stopped') && doc.analysis?.plannedDurationDays == null) {
+                    defaultAttempts.current.add(key);
+                    stage(session, {
+                        analysis: {
+                            ...doc.analysis,
+                            plannedDurationDays: 28
+                        }
+                    });
+                    await commit();
+                }
+            } catch  {
+                if (controller.signal.aborted) return;
+                session.view.loadState = 'error';
+                session.view.errors = {
+                    _section: API_MESSAGES.unreadable
+                };
+                session.publish();
+            }
+        })();
+        return ()=>{
+            controller.abort();
+            if (!session.queue.length) return;
+            const draining = session.tail;
+            drainingSaves.set(key, draining);
+            void draining.finally(()=>{
+                if (drainingSaves.get(key) === draining) drainingSaves.delete(key);
+            });
+        };
+    }, [
+        key,
+        base,
+        documentId,
+        reloadCount
+    ]);
+    const stagePartial = useCallback((partial)=>{
+        const session = current.current;
+        if (session?.key === key) stage(session, partial);
+    }, [
+        key
+    ]);
+    const commit = useCallback(()=>{
+        const entry = commitRef.current;
+        return entry?.session.key === key ? entry.commit() : Promise.resolve();
+    }, [
+        key
+    ]);
+    const reload = useCallback(async ()=>{
+        const session = current.current;
+        if (session?.key !== key || session.reloading || session.controller.signal.aborted) return;
+        // Finish submitted saves before reading again; even an unexpected tail failure cannot reject reload.
+        session.reloading = true;
+        await session.tail.catch(()=>undefined);
+        if (current.current === session && !session.controller.signal.aborted) setReloadCount((count)=>count + 1);
+    }, [
+        key
+    ]);
+    const refreshPreflight = useCallback(()=>{
+        const entry = commitRef.current;
+        return entry?.session.key === key && entry.session.view.loadState === 'ready' && !entry.session.reloading ? entry.refreshPreflight() : Promise.resolve();
+    }, [
+        key
+    ]);
+    return {
+        ...state.key === key ? state.view : initialView(),
+        stage: stagePartial,
+        commit,
+        reload,
+        refreshPreflight
+    };
+}

package/dist/admin/targeting/targeting.model.js

@@ -1,5 +1,5 @@
 import { TARGETING_OPS, isOpValid } from '../../targeting/ops.js';
-import { NUMBER_OP_LABELS, STRING_OP_LABELS, WHO_COPY } from '../copy/who.js';
+import { NUMBER_OP_LABELS, STRING_OP_LABELS, AUDIENCE_COPY } from '../copy/audience.js';
 export function opsFor(type) {
     return type ? TARGETING_OPS[type] : [];
 }
@@ -40,7 +40,7 @@ export function rowPath(path) {
 export function emptyListHint(op, value) {
     if (op !== 'in' && op !== 'nin') return undefined;
     const list = coerceValue('string', op, value);
-    return Array.isArray(list) && list.length === 0 ? WHO_COPY.emptyListNote : undefined;
+    return Array.isArray(list) && list.length === 0 ? AUDIENCE_COPY.emptyListNote : undefined;
 }
 export function humaniseAttribute(key) {
     const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');

package/dist/admin/useLayerUsage.d.ts

@@ -8,8 +8,3 @@ export declare function useLayerExperiments(layerId: DocId | null): {
         slices: number;
     }[];
 } | null;
-export declare function useLayerUsage(layerId: DocId | null): {
-    name: string;
-    used: number;
-    free: number;
-} | null;

package/dist/admin/useLayerUsage.js

@@ -2,7 +2,7 @@
 import { useConfig } from '@payloadcms/ui';
 import { useEffect, useState } from 'react';
 import { layerUsage } from './layerUsage.model.js';
-// Shared by the layer document and the allocation field; all requests use the editor's access.
+// Used by the layer document; all requests use the editor's access.
 export function useLayerExperiments(layerId) {
     const { config } = useConfig();
     const api = config.routes.api;
@@ -52,41 +52,3 @@ export function useLayerExperiments(layerId) {
     ]);
     return id != null && state?.api === api && state.id === id ? state.usage : null;
 }
-export function useLayerUsage(layerId) {
-    const { config } = useConfig();
-    const api = config.routes.api;
-    const id = layerId == null ? null : String(layerId);
-    const usage = useLayerExperiments(layerId);
-    const [state, setState] = useState(null);
-    useEffect(()=>{
-        setState(null);
-        if (id == null) return;
-        const controller = new AbortController();
-        void fetch(`${api}/xp-layers/${encodeURIComponent(id)}?depth=0`, {
-            credentials: 'include',
-            signal: controller.signal
-        }).then(async (response)=>{
-            if (!response.ok) {
-                if (!controller.signal.aborted) setState(null);
-                return;
-            }
-            const doc = await response.json();
-            if (!controller.signal.aborted) setState({
-                api,
-                id,
-                name: doc.name
-            });
-        }).catch(()=>{
-            if (!controller.signal.aborted) setState(null);
-        });
-        return ()=>controller.abort();
-    }, [
-        api,
-        id
-    ]);
-    return usage && id != null && state?.api === api && state.id === id ? {
-        name: state.name,
-        used: usage.used,
-        free: usage.free
-    } : null;
-}

package/dist/admin/views/CollectionEditRedirect.d.ts

@@ -0,0 +1,4 @@
+import type { DocumentViewServerProps } from 'payload';
+type Props = Pick<DocumentViewServerProps, 'initPageResult' | 'params' | 'routeSegments'>;
+export declare function CollectionEditRedirect({ initPageResult, params, routeSegments }: Props): Promise<never>;
+export {};

package/dist/admin/views/CollectionEditRedirect.js

@@ -0,0 +1,14 @@
+import { formatAdminURL } from 'payload/shared';
+import { redirect } from 'next/navigation.js';
+export async function CollectionEditRedirect({ initPageResult, params, routeSegments }) {
+    const resolved = await params;
+    const segments = routeSegments ?? (Array.isArray(resolved?.segments) ? resolved.segments : []);
+    const collectionIndex = segments.indexOf('xp-experiments');
+    const tail = collectionIndex >= 0 ? segments.slice(collectionIndex + 1) : segments;
+    const id = tail[0] ?? resolved?.id ?? initPageResult.docID;
+    const path = id === undefined || id === 'create' ? '/experiments/new' : `/experiments/${encodeURIComponent(String(id))}${tail[1] === 'results' ? '/results' : ''}`;
+    return redirect(formatAdminURL({
+        adminRoute: initPageResult.req.payload.config.routes.admin,
+        path
+    }));
+}

package/dist/admin/views/CollectionListRedirect.d.ts

@@ -0,0 +1,2 @@
+import type { ListViewServerProps } from 'payload';
+export declare function CollectionListRedirect({ payload }: Pick<ListViewServerProps, 'payload'>): void;

package/dist/admin/views/CollectionListRedirect.js

@@ -0,0 +1,8 @@
+import { formatAdminURL } from 'payload/shared';
+import { redirect } from 'next/navigation.js';
+export function CollectionListRedirect({ payload }) {
+    redirect(formatAdminURL({
+        adminRoute: payload.config.routes.admin,
+        path: '/experiments'
+    }));
+}

package/dist/admin/views/ExperimentsRootView.d.ts

@@ -0,0 +1,2 @@
+import type { AdminViewServerProps } from 'payload';
+export declare function ExperimentsRootView({ initPageResult, params, searchParams }: Pick<AdminViewServerProps, 'initPageResult' | 'params' | 'searchParams'>): Promise<string | number | bigint | boolean | Iterable<import("react").ReactNode> | import("react").JSX.Element | null | undefined>;