@delmaredigital/payload-experiments 0.3.0-rc.4 → 0.4.0-rc.1

package/dist/admin/blocks/TestBlockField.js

@@ -0,0 +1,163 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, SelectInput, useAuth, useConfig, useDocumentInfo, useForm, useFormFields, useFormModified, useServerFunctions } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import { useMemo, useRef, useState } from 'react';
+import { hostBlocks } from '../../blocks/model.js';
+import { wrapExperimentBlock } from '../../blocks/formState.js';
+import { CreateRefused, createTest } from '../../puck/editor/createTest.js';
+import { createApi } from '../api.js';
+import { BLOCK_COPY, blockSaveNotice, blockTestName } from '../copy/blocks.js';
+import { API_MESSAGES } from '../copy/common.js';
+import { adaptClientBlocksField, BlockChangedError, dataAt, experimentBlockSlug, findClientBlocksField, replaceBlockRow, wrapMode } from './formApi.js';
+import { blockChoices, labelText } from './model.js';
+export function TestBlockField(props) {
+    const { permissions } = useAuth();
+    const testPermissions = permissions?.collections?.['xp-experiments'];
+    return testPermissions?.update === true ? /*#__PURE__*/ _jsx(ManagedTestBlockField, {
+        ...props
+    }) : null;
+}
+function ManagedTestBlockField({ blocksField, blockSlug: suppliedSlug }) {
+    const form = useForm(), modified = useFormModified(), document = useDocumentInfo();
+    const { config, getEntityConfig } = useConfig(), { getFormState } = useServerFunctions();
+    useFormFields(([fields])=>fields);
+    const collection = document.collectionSlug ? getEntityConfig({
+        collectionSlug: document.collectionSlug
+    }) : undefined;
+    const clientField = collection ? findClientBlocksField(collection.fields, blocksField) : undefined;
+    const field = useMemo(()=>clientField ? adaptClientBlocksField(clientField, config) : undefined, [
+        clientField,
+        config
+    ]);
+    const [choice, setChoice] = useState(), [busy, setBusy] = useState(false), [error, setError] = useState();
+    const wrapping = useRef(false);
+    if (!field || !collection || !document.collectionSlug) return null;
+    const blockSlug = suppliedSlug ?? experimentBlockSlug(field);
+    const rows = hostBlocks(form.getDataByPath(blocksField)), choices = blockChoices(rows, field, blockSlug);
+    const wrappers = rows.filter((block)=>block.blockType === blockSlug && typeof block.experiment === 'string');
+    async function wrap() {
+        if (!field || wrapping.current || !document.collectionSlug || !collection) return;
+        setError(undefined);
+        if (wrapMode === 'fallback' && modified) {
+            setError(BLOCK_COPY.saveFirst);
+            return;
+        }
+        const selected = blockChoices(form.getDataByPath(blocksField), field, blockSlug).find((item)=>String(item.index) === choice);
+        if (!selected) return;
+        const title = collection.admin?.useAsTitle ? form.getDataByPath(collection.admin.useAsTitle) : undefined;
+        const name = blockTestName(typeof title === 'string' && title.trim() ? title : labelText(collection.labels.singular) ?? collection.slug, selected.label);
+        const beforeCreate = JSON.stringify(form.getData());
+        wrapping.current = true;
+        setBusy(true);
+        try {
+            const test = await createTest(config.routes.api, {
+                kind: 'block',
+                name,
+                unitType: 'visitor'
+            });
+            if (wrapMode === 'fallback') {
+                if (JSON.stringify(form.getData()) !== beforeCreate) {
+                    setError(BLOCK_COPY.saveFirst);
+                    return;
+                }
+                if (document.id == null || !selected.block.id) {
+                    setError(BLOCK_COPY.wrapRefusals['wrap-target-missing']);
+                    return;
+                }
+                const result = await createApi(config.routes.api).wrapBlock({
+                    collection: document.collectionSlug,
+                    id: document.id,
+                    field: blocksField,
+                    blockId: selected.block.id,
+                    experiment: test.slug
+                });
+                if (!result.ok) {
+                    setError(result.code && Object.hasOwn(BLOCK_COPY.wrapRefusals, result.code) ? BLOCK_COPY.wrapRefusals[result.code] : API_MESSAGES.failed);
+                    return;
+                }
+                window.location.reload();
+            } else {
+                await replaceBlockRow({
+                    form,
+                    getFormState,
+                    collectionSlug: document.collectionSlug,
+                    id: document.id,
+                    field: blocksField,
+                    index: selected.index,
+                    expectedBlock: selected.block,
+                    rows: [
+                        wrapExperimentBlock(selected.block, test.slug, field, {}, blockSlug)
+                    ],
+                    docPermissions: document.docPermissions,
+                    docPreferences: await document.getDocPreferences?.()
+                });
+            }
+            setChoice(undefined);
+        } catch (cause) {
+            setError(cause instanceof CreateRefused || cause instanceof BlockChangedError ? cause.message : API_MESSAGES.failed);
+        } finally{
+            wrapping.current = false;
+            setBusy(false);
+        }
+    }
+    return /*#__PURE__*/ _jsxs("div", {
+        children: [
+            /*#__PURE__*/ _jsx("h3", {
+                children: BLOCK_COPY.testBlock
+            }),
+            choices.length ? /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsx(SelectInput, {
+                        name: "xpBlockChoice",
+                        path: "xpBlockChoice",
+                        label: BLOCK_COPY.pick,
+                        options: choices.map((item)=>({
+                                label: item.option,
+                                value: String(item.index)
+                            })),
+                        value: choice,
+                        readOnly: busy,
+                        onChange: (option)=>{
+                            if (!Array.isArray(option)) setChoice(option?.value);
+                        }
+                    }),
+                    /*#__PURE__*/ _jsx(Button, {
+                        disabled: busy || choice === undefined,
+                        onClick: ()=>void wrap(),
+                        children: BLOCK_COPY.testBlock
+                    })
+                ]
+            }) : /*#__PURE__*/ _jsx("p", {
+                children: BLOCK_COPY.empty
+            }),
+            error ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: error
+            }) : null,
+            wrappers.map((block)=>{
+                const slug = block.experiment;
+                const inSavedDocument = hostBlocks(dataAt(document.data, blocksField)).some((row)=>row.blockType === blockSlug && row.experiment === slug);
+                const saved = !modified && inSavedDocument;
+                return /*#__PURE__*/ _jsxs("p", {
+                    children: [
+                        !inSavedDocument ? /*#__PURE__*/ _jsxs(_Fragment, {
+                            children: [
+                                blockSaveNotice(Boolean(collection.versions?.drafts)),
+                                ' '
+                            ]
+                        }) : null,
+                        /*#__PURE__*/ _jsx("a", {
+                            "aria-disabled": !saved,
+                            href: saved ? formatAdminURL({
+                                adminRoute: config.routes.admin,
+                                path: `/experiments/by-slug/${encodeURIComponent(slug)}`
+                            }) : undefined,
+                            children: BLOCK_COPY.setup
+                        })
+                    ]
+                }, block.id ?? slug);
+            })
+        ]
+    });
+}

package/dist/admin/blocks/formApi.d.ts

@@ -0,0 +1,43 @@
+import type { ClientConfig, ClientField, Field } from 'payload';
+import type { useForm, useServerFunctions } from '@payloadcms/ui';
+import { type HostBlock } from '../../blocks/model.js';
+/** The only form-state failure with block-specific editor copy. */
+export declare class BlockChangedError extends Error {
+    constructor();
+}
+export type RowsField = Extract<Field, {
+    type: 'blocks';
+}>;
+export declare const wrapMode: 'form-api' | 'fallback';
+/** Client twin: unnamed layout containers do not contribute to a data path. */
+export declare function findClientBlocksField(fields: readonly ClientField[], name: string): Extract<ClientField, {
+    type: 'blocks';
+}> | undefined;
+/** Only schema structure is needed by the pure helpers, never server validators.
+ * Resolve references at every depth, including inside the Experiment slots field.
+ */
+export declare function adaptClientBlocksField(field: Extract<ClientField, {
+    type: 'blocks';
+}>, config: Pick<ClientConfig, 'blocks'>): RowsField;
+export declare function experimentBlockSlug(field: RowsField): string;
+export declare function rowLocation(path: string): {
+    field: string;
+    index: number;
+} | undefined;
+export declare function dataAt(data: unknown, path: string): unknown;
+/** Payload 3.90.2 and 4 beta.6 use the same row APIs. Sync replaces the whole
+ * wrapper so add/drop/reorder and the server-rendered component slots stay together.
+ * N=0 needs UPDATE: removeFieldRow alone serializes the empty field as number 0.
+ */
+export declare function replaceBlockRow(args: {
+    form: ReturnType<typeof useForm>;
+    getFormState: ReturnType<typeof useServerFunctions>['getFormState'];
+    collectionSlug: string;
+    id?: string | number;
+    field: string;
+    index: number;
+    rows: HostBlock[];
+    expectedBlock?: HostBlock;
+    docPermissions?: Parameters<ReturnType<typeof useServerFunctions>['getFormState']>[0]['docPermissions'];
+    docPreferences?: Parameters<ReturnType<typeof useServerFunctions>['getFormState']>[0]['docPreferences'];
+}): Promise<void>;

package/dist/admin/blocks/formApi.js

@@ -0,0 +1,153 @@
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks } from '../../blocks/model.js';
+import { BLOCK_COPY } from '../copy/blocks.js';
+/** The only form-state failure with block-specific editor copy. */ export class BlockChangedError extends Error {
+    constructor(){
+        super(BLOCK_COPY.blockChanged);
+    }
+}
+export const wrapMode = 'form-api';
+/** Client twin: unnamed layout containers do not contribute to a data path. */ export function findClientBlocksField(fields, name) {
+    for (const field of fields){
+        if (field.type === 'blocks' && field.name === name) return field;
+        if (field.type === 'row' || field.type === 'collapsible') {
+            const found = findClientBlocksField(field.fields, name);
+            if (found) return found;
+        }
+        if (field.type === 'tabs') for (const tab of field.tabs){
+            if ('name' in tab && tab.name) continue;
+            const found = findClientBlocksField(tab.fields, name);
+            if (found) return found;
+        }
+    }
+}
+/** Only schema structure is needed by the pure helpers, never server validators.
+ * Resolve references at every depth, including inside the Experiment slots field.
+ */ export function adaptClientBlocksField(field, config) {
+    function block(block) {
+        return {
+            ...block,
+            fields: block.fields.map(adapt)
+        };
+    }
+    function adapt(field) {
+        if (field.type === 'blocks') return {
+            ...field,
+            blocks: [
+                ...field.blocks.map(block),
+                ...(field.blockReferences ?? []).flatMap((reference)=>{
+                    const resolved = typeof reference === 'string' ? config.blocks?.find((item)=>item.slug === reference) : reference;
+                    return resolved ? [
+                        block(resolved)
+                    ] : [];
+                })
+            ],
+            blockReferences: []
+        };
+        if ('fields' in field) return {
+            ...field,
+            fields: field.fields.map(adapt)
+        };
+        if (field.type === 'tabs') return {
+            ...field,
+            tabs: field.tabs.map((tab)=>({
+                    ...tab,
+                    fields: tab.fields.map(adapt)
+                }))
+        };
+        return field;
+    }
+    return adapt(field);
+}
+export function experimentBlockSlug(field) {
+    return field.blocks.find((block)=>block.fields.some((field)=>'name' in field && field.name === 'xpBlockStatus'))?.slug ?? EXPERIMENT_BLOCK_SLUG;
+}
+export function rowLocation(path) {
+    const match = /^([^.]+)\.(\d+)(?:\.|$)/.exec(path);
+    return match ? {
+        field: match[1],
+        index: Number(match[2])
+    } : undefined;
+}
+export function dataAt(data, path) {
+    return path.split('.').reduce((value, key)=>value && typeof value === 'object' ? value[key] : undefined, data);
+}
+/** Payload 3.90.2 and 4 beta.6 use the same row APIs. Sync replaces the whole
+ * wrapper so add/drop/reorder and the server-rendered component slots stay together.
+ * N=0 needs UPDATE: removeFieldRow alone serializes the empty field as number 0.
+ */ export async function replaceBlockRow(args) {
+    const { form, getFormState, collectionSlug, id, field, index, rows } = args;
+    const data = form.getData(), before = hostBlocks(data[field]);
+    if (args.expectedBlock && JSON.stringify(before[index]) !== JSON.stringify(args.expectedBlock)) throw new BlockChangedError();
+    const original = JSON.stringify(data[field]);
+    const next = [
+        ...before.slice(0, index),
+        ...rows,
+        ...before.slice(index + 1)
+    ];
+    const result = await getFormState({
+        collectionSlug,
+        id,
+        schemaPath: collectionSlug,
+        data: {
+            ...data,
+            [field]: next
+        },
+        docPermissions: args.docPermissions,
+        docPreferences: args.docPreferences ?? {
+            fields: {}
+        },
+        operation: id == null ? 'create' : 'update',
+        renderAllFields: true,
+        skipValidation: true
+    });
+    if (JSON.stringify(form.getDataByPath(field)) !== original) throw new BlockChangedError();
+    if (!result.state) throw new Error('Missing server form state');
+    const state = result.state;
+    function subFieldState(rowIndex) {
+        const prefix = `${field}.${rowIndex}.`;
+        return Object.fromEntries(Object.entries(state).filter(([path])=>path.startsWith(prefix)).map(([path, value])=>[
+                path.slice(prefix.length),
+                value
+            ]));
+    }
+    if (!rows.length) {
+        form.removeFieldRow({
+            path: field,
+            rowIndex: index
+        });
+        if (next.length === 0) form.dispatchFields({
+            type: 'UPDATE',
+            path: field,
+            value: [],
+            disableFormData: false
+        });
+        return;
+    }
+    form.replaceFieldRow({
+        path: field,
+        rowIndex: index,
+        schemaPath: `${collectionSlug}.${field}`,
+        blockType: rows[0].blockType,
+        subFieldState: subFieldState(index)
+    });
+    for(let offset = 1; offset < rows.length; offset++)form.addFieldRow({
+        path: field,
+        rowIndex: index + offset,
+        schemaPath: `${collectionSlug}.${field}`,
+        blockType: rows[offset].blockType,
+        subFieldState: subFieldState(index + offset)
+    });
+    // REPLACE_ROW invents a metadata id even when the data id is unchanged.
+    // Keep server row metadata (including custom labels) and the wrapper React key:
+    // otherwise a sync remounts the status field and loses its save notice.
+    const oldRows = form.getFields()[field]?.rows ?? [];
+    const serverRows = state[field]?.rows;
+    if (serverRows) form.dispatchFields({
+        type: 'UPDATE',
+        path: field,
+        rows: serverRows.map((row)=>({
+                ...oldRows.find((old)=>old.id === row.id),
+                ...row
+            }))
+    });
+}

package/dist/admin/blocks/inject.d.ts

@@ -0,0 +1,7 @@
+import type { Field } from 'payload';
+/** Copy the coordinates supplied by CORE-L2, including every containing array. */
+export declare function injectTestBlock(fields: Field[], registration: {
+    field: string;
+    blockSlug?: string;
+    appliesTo?: (doc: Record<string, unknown>) => boolean;
+}): Field[];

package/dist/admin/blocks/inject.js

@@ -0,0 +1,41 @@
+import { findRegisteredBlocksField } from '../../blocks/formState.js';
+import { XP_TEST_BLOCK } from '../paths.js';
+/** Copy the coordinates supplied by CORE-L2, including every containing array. */ export function injectTestBlock(fields, registration) {
+    const found = findRegisteredBlocksField(fields, registration.field);
+    if (!found) return fields;
+    const ui = {
+        name: 'xpTestBlock',
+        type: 'ui',
+        admin: {
+            condition: (data)=>{
+                try {
+                    return registration.appliesTo ? registration.appliesTo(data) === true : true;
+                } catch  {
+                    return false;
+                }
+            },
+            components: {
+                Field: {
+                    path: XP_TEST_BLOCK,
+                    clientProps: {
+                        blocksField: registration.field,
+                        blockSlug: registration.blockSlug
+                    }
+                }
+            }
+        }
+    };
+    function insert(value, path) {
+        const [key, ...rest] = path;
+        if (key === undefined) return value;
+        const copy = Array.isArray(value) ? [
+            ...value
+        ] : {
+            ...value
+        };
+        if (!rest.length) copy.splice(Number(key) + 1, 0, ui);
+        else copy[key] = insert(value[key], rest);
+        return copy;
+    }
+    return insert(fields, found.path);
+}

package/dist/admin/blocks/model.d.ts

@@ -0,0 +1,17 @@
+import type { PlacementStatusResult } from '../../types/endpoints.js';
+import type { RowsField } from './formApi.js';
+export type BlockStatus = PlacementStatusResult['slugs'][string];
+export type LiveBlockStatus = Extract<BlockStatus, {
+    status: string;
+}>;
+export declare function liveStatus(status: BlockStatus | null): status is LiveBlockStatus;
+export declare function slotLabel(slot: string, status: BlockStatus | null): string;
+export declare function statusSentence(status: BlockStatus): string;
+export declare function isOrphan(status: BlockStatus): boolean;
+export declare function labelText(value: unknown): string | undefined;
+export declare function blockChoices(value: unknown, field: RowsField, blockSlug: string): {
+    block: import("../../blocks/model.js").HostBlock;
+    index: number;
+    label: string;
+    option: string;
+}[];

package/dist/admin/blocks/model.js

@@ -0,0 +1,45 @@
+import { hostBlocks } from '../../blocks/model.js';
+import { BLOCK_COPY, blockDecidedStatus, blockDraftStatus, blockFinishedStatus, blockPosition } from '../copy/blocks.js';
+export function liveStatus(status) {
+    return !!status && 'status' in status;
+}
+export function slotLabel(slot, status) {
+    return (liveStatus(status) ? status.arms.find((arm)=>arm.key !== 'holdout' && (arm.slot ?? arm.key) === slot)?.label : undefined) || BLOCK_COPY.slotLabels[slot] || slot;
+}
+export function statusSentence(status) {
+    if (!liveStatus(status)) return BLOCK_COPY.deleted;
+    const winner = status.arms.find((arm)=>arm.key === status.winnerArm);
+    const winnerLabel = winner?.label || BLOCK_COPY.slotLabels[status.winnerArm ?? 'control'] || status.winnerArm || BLOCK_COPY.slotLabels.control;
+    switch(status.status){
+        case 'draft':
+            return blockDraftStatus(status.name);
+        case 'running':
+            return BLOCK_COPY.running;
+        case 'stopped':
+            return BLOCK_COPY.stopped;
+        case 'decided':
+            return blockDecidedStatus(winnerLabel, status.rollout);
+        case 'archived':
+            return status.winnerArm ? blockFinishedStatus(winnerLabel) : BLOCK_COPY.discarded;
+    }
+}
+export function isOrphan(status) {
+    return !liveStatus(status) || status.status === 'archived' && !status.winnerArm;
+}
+export function labelText(value) {
+    return typeof value === 'string' ? value : value && typeof value === 'object' ? Object.values(value).find((item)=>typeof item === 'string') : undefined;
+}
+export function blockChoices(value, field, blockSlug) {
+    return hostBlocks(value).flatMap((block, index)=>{
+        if (block.blockType === blockSlug) return [];
+        const label = labelText(field.blocks.find((config)=>config.slug === block.blockType)?.labels?.singular) || block.blockType;
+        return [
+            {
+                block,
+                index,
+                label,
+                option: blockPosition(label, index + 1)
+            }
+        ];
+    });
+}

package/dist/admin/blocks/statusCache.d.ts

@@ -0,0 +1,7 @@
+import type { BlockStatus } from './model.js';
+export declare const validBlockSlug: (slug: unknown) => slug is string;
+/** Only status fields own reads. StrictMode replays the same mount token; a
+ * different owner after the last cleanup starts fresh, even in the same commit.
+ * Deferred eviction removes every entry with no live owner after that commit.
+ */
+export declare function useBlockStatus(api: string, slug: unknown, owner?: boolean): BlockStatus | null;

package/dist/admin/blocks/statusCache.js

@@ -0,0 +1,83 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
+import { createApi } from '../api.js';
+const cache = new Map();
+// Subscribers do not create status entries: a label alone owns no cached data.
+const listeners = new Map();
+const keyOf = (api, slug)=>JSON.stringify([
+        api,
+        slug
+    ]);
+const publish = (key)=>listeners.get(key)?.callbacks.forEach((listener)=>listener());
+export const validBlockSlug = (slug)=>typeof slug === 'string' && slug.length > 0 && slug.length <= 64;
+/** Only status fields own reads. StrictMode replays the same mount token; a
+ * different owner after the last cleanup starts fresh, even in the same commit.
+ * Deferred eviction removes every entry with no live owner after that commit.
+ */ export function useBlockStatus(api, slug, owner = false) {
+    const key = validBlockSlug(slug) ? keyOf(api, slug) : undefined;
+    const token = useRef({});
+    const subscribe = useCallback((listener)=>{
+        if (!key) return ()=>{};
+        let current = listeners.get(key);
+        if (!current) {
+            current = {
+                callbacks: new Set()
+            };
+            listeners.set(key, current);
+        }
+        current.callbacks.add(listener);
+        return ()=>{
+            current.callbacks = new Set([
+                ...current.callbacks
+            ].filter((item)=>item !== listener));
+            if (!current.callbacks.size) listeners.delete(key);
+        };
+    }, [
+        key
+    ]);
+    const status = useSyncExternalStore(subscribe, ()=>{
+        const current = key ? cache.get(key) : undefined;
+        // A new owner must not sync with the previous mount's snapshot before its
+        // effect registers ownership (or starts the fresh read).
+        return current && (!owner || current.mounts.has(token.current)) ? current.value : null;
+    }, ()=>null);
+    useEffect(()=>{
+        if (!key || !owner || !validBlockSlug(slug)) return;
+        let current = cache.get(key);
+        if (!current || !current.owners && !current.mounts.has(token.current)) {
+            current = {
+                value: null,
+                owners: 0,
+                mounts: new WeakSet()
+            };
+            cache.set(key, current);
+        }
+        const owned = current;
+        owned.owners++;
+        owned.mounts.add(token.current);
+        publish(key);
+        if (!owned.pending) owned.pending = createApi(api).placementStatus({
+            slugs: [
+                slug
+            ]
+        }).then((result)=>{
+            if (cache.get(key) !== owned) return;
+            owned.value = result.ok ? result.data?.slugs[slug] ?? null : null;
+            publish(key);
+        });
+        return ()=>{
+            owned.owners--;
+            queueMicrotask(()=>{
+                if (!owned.owners && cache.get(key) === owned) {
+                    cache.delete(key);
+                    publish(key);
+                }
+            });
+        };
+    }, [
+        api,
+        key,
+        slug,
+        owner
+    ]);
+    return status;
+}

package/dist/admin/blocks/useBlockForm.d.ts

@@ -0,0 +1,17 @@
+import { useConfig, useDocumentInfo, useForm } from '@payloadcms/ui';
+import { adaptClientBlocksField, rowLocation } from './formApi.js';
+import type { ClientCollectionConfig } from 'payload';
+import type { ExperimentBlock, HostBlock } from '../../blocks/model.js';
+/** Declared so the d.ts build can name Payload UI's form types through public exports. */
+export type BlockFormApi = {
+    form: ReturnType<typeof useForm>;
+    document: ReturnType<typeof useDocumentInfo>;
+    config: ReturnType<typeof useConfig>['config'];
+    collection: ClientCollectionConfig | undefined;
+    field: ReturnType<typeof adaptClientBlocksField> | undefined;
+    block: ExperimentBlock | undefined;
+    manager: boolean;
+    replace: (rows: HostBlock[]) => Promise<void>;
+    location: ReturnType<typeof rowLocation>;
+};
+export declare function useBlockForm(path: string): BlockFormApi;

package/dist/admin/blocks/useBlockForm.js

@@ -0,0 +1,46 @@
+import { useMemo } from 'react';
+import { useAuth, useConfig, useDocumentInfo, useForm, useFormFields, useServerFunctions } from '@payloadcms/ui';
+import { adaptClientBlocksField, findClientBlocksField, replaceBlockRow, rowLocation } from './formApi.js';
+export function useBlockForm(path) {
+    const form = useForm(), document = useDocumentInfo(), { config, getEntityConfig } = useConfig();
+    const { getFormState } = useServerFunctions(), { permissions } = useAuth();
+    // useForm's getters are stable; subscribe so changed slug/row paths are read again.
+    useFormFields(([fields])=>fields);
+    const location = rowLocation(path);
+    const collection = document.collectionSlug ? getEntityConfig({
+        collectionSlug: document.collectionSlug
+    }) : undefined;
+    const clientField = location && collection ? findClientBlocksField(collection.fields, location.field) : undefined;
+    const field = useMemo(()=>clientField ? adaptClientBlocksField(clientField, config) : undefined, [
+        clientField,
+        config
+    ]);
+    const block = location ? form.getDataByPath(`${location.field}.${location.index}`) : undefined;
+    const testPermissions = permissions?.collections?.['xp-experiments'];
+    const manager = testPermissions?.update === true;
+    async function replace(rows) {
+        if (!location || !document.collectionSlug) return;
+        await replaceBlockRow({
+            form,
+            getFormState,
+            collectionSlug: document.collectionSlug,
+            id: document.id,
+            ...location,
+            rows,
+            expectedBlock: block,
+            docPermissions: document.docPermissions,
+            docPreferences: await document.getDocPreferences?.()
+        });
+    }
+    return {
+        form,
+        document,
+        config,
+        collection,
+        field,
+        block,
+        manager,
+        replace,
+        location
+    };
+}

package/dist/admin/copy/actions.d.ts

@@ -1,3 +1,4 @@
+import type { AddMetricWarning } from '../../types/endpoints.js';
 export declare const ACTIONS_COPY: {
     readonly start: "Start";
     readonly restart: "Start a new round";
@@ -70,3 +71,4 @@ export declare const CONTENT_ENTRY_REFUSALS: {
     };
     readonly fallback: "This page can't be changed right now. Reload to see its current state.";
 };
+export declare function addMetricWarningCopy(warning: AddMetricWarning): string;

package/dist/admin/copy/actions.js

@@ -1,3 +1,4 @@
+import { asymmetricGoalsCopy, placementUncheckedCopy } from './readiness.js';
 export const ACTIONS_COPY = {
     start: 'Start',
     restart: 'Start a new round',
@@ -70,3 +71,11 @@ export const CONTENT_ENTRY_REFUSALS = {
     },
     fallback: ACTIONS_COPY.contentEntryFallback
 };
+export function addMetricWarningCopy(warning) {
+    if (warning.code === 'goal-added-mid-test') return "Clicks before this goal was added aren't counted (the same for every version).";
+    if (warning.code === 'placement-unchecked') {
+        const path = warning.detail?.path;
+        return placementUncheckedCopy(typeof path === 'string' ? path : 'This page');
+    }
+    return asymmetricGoalsCopy(warning.detail);
+}