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

package/dist/blocks/bindings.js

@@ -0,0 +1,34 @@
+import { documentEditor, puckCollections } from '../options.js';
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks, isObject } from './model.js';
+/** Same document-kind rule as the scan; Payload blocks are top level, Puck is recursive. */ export function placementSlugs(options, collection, doc) {
+    if (!doc) return [];
+    const editor = documentEditor(options, collection, doc);
+    if (editor === 'blocks') {
+        const registration = options.blocks?.collections.find((r)=>r.slug === collection);
+        if (!registration) return [];
+        return [
+            ...new Set(hostBlocks(doc[registration.field]).flatMap((block)=>block.blockType === (registration.blockSlug ?? EXPERIMENT_BLOCK_SLUG) && typeof block.experiment === 'string' ? [
+                    block.experiment
+                ] : []))
+        ];
+    }
+    if (editor !== 'puck') return [];
+    const registration = puckCollections(options).find((r)=>r.slug === collection);
+    const found = new Set();
+    function walk(v) {
+        if (Array.isArray(v)) {
+            v.forEach(walk);
+            return;
+        }
+        if (!isObject(v)) return;
+        if (v.type === 'ExperimentSlot' && isObject(v.props)) {
+            const ref = v.props.experiment, slug = typeof ref === 'string' ? ref : isObject(ref) ? ref.slug : undefined;
+            if (typeof slug === 'string') found.add(slug);
+        }
+        Object.values(v).forEach(walk);
+    }
+    if (registration) walk(doc[registration.field]);
+    return [
+        ...found
+    ];
+}

package/dist/blocks/createExperimentBlock.d.ts

@@ -0,0 +1,6 @@
+import type { Block } from 'payload';
+export declare function validateExperimentSlots(value: unknown): true | string;
+export declare function createExperimentBlock({ blocks, slug }: {
+    blocks: Block[];
+    slug?: string;
+}): Block;

package/dist/blocks/createExperimentBlock.js

@@ -0,0 +1,77 @@
+import { XP_BLOCK_STATUS, XP_BLOCK_ROW_LABEL, XP_COPY_ORIGINAL } from '../admin/paths.js';
+import { BLOCK_SLOTS, EXPERIMENT_BLOCK_SLUG } from './model.js';
+export function validateExperimentSlots(value) {
+    if (!Array.isArray(value)) return true;
+    const slots = value.map((row)=>row?.slot);
+    return new Set(slots).size === slots.length ? true : 'Each version appears once';
+}
+export function createExperimentBlock({ blocks, slug = EXPERIMENT_BLOCK_SLUG }) {
+    if (blocks.some((block)=>block.slug === slug)) throw new Error('Experiment blocks cannot be nested.');
+    return {
+        slug,
+        labels: {
+            singular: 'Experiment',
+            plural: 'Experiments'
+        },
+        fields: [
+            {
+                name: 'xpBlockStatus',
+                type: 'ui',
+                admin: {
+                    components: {
+                        Field: XP_BLOCK_STATUS
+                    }
+                }
+            },
+            {
+                name: 'experiment',
+                label: 'Test',
+                type: 'text',
+                required: true
+            },
+            {
+                name: 'slots',
+                label: 'Versions',
+                type: 'array',
+                validate: validateExperimentSlots,
+                admin: {
+                    components: {
+                        RowLabel: XP_BLOCK_ROW_LABEL
+                    }
+                },
+                fields: [
+                    {
+                        name: 'xpCopyOriginal',
+                        type: 'ui',
+                        admin: {
+                            components: {
+                                Field: XP_COPY_ORIGINAL
+                            }
+                        }
+                    },
+                    {
+                        name: 'slot',
+                        label: 'Version',
+                        type: 'select',
+                        required: true,
+                        options: BLOCK_SLOTS.map((value, index)=>({
+                                value,
+                                label: [
+                                    'Original',
+                                    'Variant A',
+                                    'Variant B',
+                                    'Variant C'
+                                ][index]
+                            }))
+                    },
+                    {
+                        name: 'blocks',
+                        label: 'Content',
+                        type: 'blocks',
+                        blocks
+                    }
+                ]
+            }
+        ]
+    };
+}

package/dist/blocks/formState.d.ts

@@ -0,0 +1,31 @@
+import type { Block, Field, SanitizedConfig } from 'payload';
+import { type ExperimentBlock, type HostBlock } from './model.js';
+type RowConfig = {
+    blocks?: Block[];
+    localization?: SanitizedConfig['localization'];
+};
+type RowsField = Extract<Field, {
+    type: 'array' | 'blocks';
+}>;
+/** Mirror Payload 3.90.2's collections/operations/utilities/copyDataWithFreshRowIDs.js:
+ * walk configured row/subfield containers only. Mint ids for array/blocks rows, leaving
+ * opaque values (including json, richText, relationships and uploads) unchanged.
+ * Global block definitions resolve blockReferences; inline slot blocks retain host configs.
+ */
+export declare function freshBlockIds<T>(value: T, field: RowsField, config?: RowConfig, mint?: () => string): T;
+export declare function wrapExperimentBlock(block: HostBlock, experiment: string, field: RowsField, config?: RowConfig, blockSlug?: string): ExperimentBlock;
+export declare function syncExperimentSlots(block: ExperimentBlock, arms: readonly {
+    key: string;
+    kind?: string;
+    slot?: string | null;
+}[], field: RowsField, config?: RowConfig): ExperimentBlock;
+export declare function copyOriginalIntoVersion(block: ExperimentBlock, slot: string, field: RowsField, config?: RowConfig): ExperimentBlock;
+export declare function unwrapExperimentBlock(block: HostBlock, field: RowsField, slot?: string, config?: RowConfig): HostBlock[];
+/** Config coordinates include unnamed layout containers. No field component is injected here. */
+export declare function findRegisteredBlocksField(fields: readonly Field[], name: string): {
+    field: Extract<Field, {
+        type: 'blocks';
+    }>;
+    path: Array<string | number>;
+} | undefined;
+export {};

package/dist/blocks/formState.js

@@ -0,0 +1,146 @@
+import { BLOCK_SLOTS, EXPERIMENT_BLOCK_SLUG, isObject, slotBlocks } from './model.js';
+/** Mirror Payload 3.90.2's collections/operations/utilities/copyDataWithFreshRowIDs.js:
+ * walk configured row/subfield containers only. Mint ids for array/blocks rows, leaving
+ * opaque values (including json, richText, relationships and uploads) unchanged.
+ * Global block definitions resolve blockReferences; inline slot blocks retain host configs.
+ */ export function freshBlockIds(value, field, config = {}, mint = ()=>globalThis.crypto.randomUUID()) {
+    function copyObject(data, fields, parentIsLocalized = false) {
+        const result = {
+            ...data
+        };
+        for (const child of fields){
+            if (child.type === 'row' || child.type === 'collapsible' || child.type === 'group' && !('name' in child && child.name)) {
+                Object.assign(result, copyObject(result, child.fields, parentIsLocalized));
+            } else if (child.type === 'tabs') {
+                for (const tab of child.tabs){
+                    if ('name' in tab && tab.name) {
+                        if (Object.hasOwn(result, tab.name)) result[tab.name] = subfields(result[tab.name], tab.fields, tab.localized, parentIsLocalized);
+                    } else Object.assign(result, copyObject(result, tab.fields, parentIsLocalized));
+                }
+            } else if (child.type === 'group' && 'name' in child && child.name) {
+                if (Object.hasOwn(result, child.name)) result[child.name] = subfields(result[child.name], child.fields, child.localized, parentIsLocalized);
+            } else if (child.type === 'array' || child.type === 'blocks') {
+                if (Object.hasOwn(result, child.name)) result[child.name] = copyRows(result[child.name], child, parentIsLocalized || Boolean(child.localized));
+            }
+        }
+        return result;
+    }
+    function subfields(data, fields, localized, parentIsLocalized) {
+        if (!isObject(data)) return data;
+        const locales = config.localization ? config.localization.localeCodes : [];
+        if (localized && !parentIsLocalized && Object.keys(data).length > 0 && Object.keys(data).every((key)=>locales.includes(key))) return Object.fromEntries(Object.entries(data).map(([locale, value])=>[
+                locale,
+                isObject(value) ? copyObject(value, fields, true) : value
+            ]));
+        return copyObject(data, fields, parentIsLocalized || Boolean(localized));
+    }
+    function copyRows(data, rowsField, parentIsLocalized = false) {
+        if (Array.isArray(data)) return data.map((row)=>{
+            if (!isObject(row)) return row;
+            const fields = rowsField.type === 'array' ? rowsField.fields : (config.blocks?.find((block)=>block.slug === row.blockType) ?? [
+                ...rowsField.blocks,
+                ...(rowsField.blockReferences ?? []).filter((block)=>typeof block !== 'string')
+            ].find((block)=>block.slug === row.blockType))?.fields ?? [];
+            return {
+                ...copyObject(row, fields, parentIsLocalized),
+                id: mint()
+            };
+        });
+        if (isObject(data)) return Object.fromEntries(Object.entries(data).map(([locale, rows])=>[
+                locale,
+                Array.isArray(rows) ? copyRows(rows, rowsField, true) : rows
+            ]));
+        return data;
+    }
+    return copyRows(value, field);
+}
+export function wrapExperimentBlock(block, experiment, field, config = {}, blockSlug = EXPERIMENT_BLOCK_SLUG) {
+    if (block.blockType === blockSlug) throw new Error('Experiment blocks cannot be nested.');
+    return {
+        id: globalThis.crypto.randomUUID(),
+        blockType: blockSlug,
+        experiment,
+        slots: [
+            {
+                id: globalThis.crypto.randomUUID(),
+                slot: 'control',
+                blocks: [
+                    block
+                ]
+            },
+            {
+                id: globalThis.crypto.randomUUID(),
+                slot: 'variantA',
+                blocks: freshBlockIds([
+                    block
+                ], field, config)
+            }
+        ]
+    };
+}
+function copySlotBlocks(block, slot, field, config) {
+    // Traverse the wrapper too: slot content may use blocks defined only inside
+    // createExperimentBlock, rather than in the host's outer blocks field.
+    return slotBlocks(freshBlockIds([
+        block
+    ], field, config)[0], slot);
+}
+export function syncExperimentSlots(block, arms, field, config = {}) {
+    const wanted = arms.filter((a)=>a.kind !== 'holdout' && a.key !== 'holdout').map((a)=>a.slot ?? a.key).filter((slot)=>BLOCK_SLOTS.includes(slot));
+    const slots = [
+        ...new Set(wanted)
+    ].map((slot)=>block.slots.find((row)=>row.slot === slot) ?? {
+            id: globalThis.crypto.randomUUID(),
+            slot,
+            blocks: copySlotBlocks(block, 'control', field, config)
+        });
+    return {
+        ...block,
+        slots
+    };
+}
+export function copyOriginalIntoVersion(block, slot, field, config = {}) {
+    return {
+        ...block,
+        slots: block.slots.map((row)=>row.slot === slot && slot !== 'control' ? {
+                ...row,
+                blocks: copySlotBlocks(block, 'control', field, config)
+            } : row)
+    };
+}
+export function unwrapExperimentBlock(block, field, slot = 'control', config = {}) {
+    return copySlotBlocks(block, slot, field, config);
+}
+/** Config coordinates include unnamed layout containers. No field component is injected here. */ export function findRegisteredBlocksField(fields, name) {
+    function visit(fields, path) {
+        for(let i = 0; i < fields.length; i++){
+            const field = fields[i], here = [
+                ...path,
+                i
+            ];
+            if ('name' in field && field.name === name && field.type === 'blocks') return {
+                field,
+                path: here
+            };
+            if (field.type === 'tabs') for(let t = 0; t < field.tabs.length; t++){
+                const tab = field.tabs[t];
+                if ('name' in tab && tab.name) continue;
+                const found = visit(field.tabs[t].fields, [
+                    ...here,
+                    'tabs',
+                    t,
+                    'fields'
+                ]);
+                if (found) return found;
+            }
+            if (field.type === 'row' || field.type === 'collapsible') {
+                const found = visit(field.fields, [
+                    ...here,
+                    'fields'
+                ]);
+                if (found) return found;
+            }
+        }
+    }
+    return visit(fields, []);
+}

package/dist/blocks/model.d.ts

@@ -0,0 +1,41 @@
+import type { RenderedExposure } from '../types/assignments.js';
+export declare const EXPERIMENT_BLOCK_SLUG = "xpExperiment";
+export declare const BLOCK_SLOTS: readonly ["control", "variantA", "variantB", "variantC"];
+export interface HostBlock {
+    id?: string;
+    blockType: string;
+    blockName?: string;
+    [field: string]: unknown;
+}
+export interface ExperimentBlock extends HostBlock {
+    experiment: string;
+    slots: Array<{
+        id?: string;
+        slot: string;
+        blocks: HostBlock[];
+    }>;
+}
+export interface ExperimentBlockGroup {
+    slug: string;
+    expose?: RenderedExposure;
+}
+export type ResolvedHostBlock = HostBlock & {
+    xpGroup?: ExperimentBlockGroup;
+};
+export interface ResolvedExperimentBlocks {
+    blocks: ResolvedHostBlock[];
+    rendered: RenderedExposure[];
+    groups: Array<ExperimentBlockGroup & {
+        start: number;
+        end: number;
+    }>;
+}
+export declare const isObject: (v: unknown) => v is Record<string, unknown>;
+export declare const hostBlocks: (v: unknown) => HostBlock[];
+export declare function slotBlocks(block: HostBlock, slot: string): HostBlock[];
+/** Experiments-off rendering preserves stored row ids; only top-level wrappers are read. */
+export declare function controlOnlyBlocks(blocks: unknown, blockSlug?: string): HostBlock[];
+export declare function segmentExperimentBlocks(blocks: readonly ResolvedHostBlock[]): Array<{
+    group?: ExperimentBlockGroup;
+    blocks: HostBlock[];
+}>;

package/dist/blocks/model.js

@@ -0,0 +1,34 @@
+export const EXPERIMENT_BLOCK_SLUG = 'xpExperiment';
+export const BLOCK_SLOTS = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC'
+];
+export const isObject = (v)=>!!v && typeof v === 'object' && !Array.isArray(v);
+export const hostBlocks = (v)=>Array.isArray(v) ? v.filter((b)=>isObject(b) && typeof b.blockType === 'string') : [];
+export function slotBlocks(block, slot) {
+    const row = Array.isArray(block.slots) ? block.slots.find((row)=>isObject(row) && row.slot === slot) : undefined;
+    return isObject(row) ? hostBlocks(row.blocks) : [];
+}
+/** Experiments-off rendering preserves stored row ids; only top-level wrappers are read. */ export function controlOnlyBlocks(blocks, blockSlug = EXPERIMENT_BLOCK_SLUG) {
+    return hostBlocks(blocks).flatMap((block)=>block.blockType === blockSlug ? slotBlocks(block, 'control') : [
+            block
+        ]);
+}
+export function segmentExperimentBlocks(blocks) {
+    const runs = [];
+    for (const block of blocks){
+        const group = block.xpGroup, last = runs.at(-1);
+        if (last && last.group === group) last.blocks.push(block);
+        else runs.push({
+            ...group ? {
+                group
+            } : {},
+            blocks: [
+                block
+            ]
+        });
+    }
+    return runs;
+}

package/dist/client/ExperimentGroup.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import type { RenderedExposure } from '../types/assignments.js';
+export declare function ExperimentGroup({ expose, children }: {
+    expose?: RenderedExposure;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/client/ExperimentGroup.js

@@ -0,0 +1,9 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ViewportExposure } from './ViewportExposure.js';
+export function ExperimentGroup({ expose, children }) {
+    return /*#__PURE__*/ _jsx(ViewportExposure, {
+        expose: expose,
+        children: children
+    });
+}

package/dist/client/ExperimentsProvider.js

@@ -1,9 +1,12 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useLayoutEffect, useRef } from 'react';
+import { createContext, useContext, useLayoutEffect, useRef } from 'react';
 import { registerApiRoute, unregisterApiRoute } from './beacon.js';
+import { registerClickGoals, unregisterClickGoals } from './clickGoals.js';
 import { ExperimentsContext } from './context.js';
+const DepthContext = /*#__PURE__*/ createContext(0);
 export function ExperimentsProvider(props) {
+    const depth = useContext(DepthContext) + 1;
     const token = useRef(Symbol()).current;
     // Register committed providers before descendants can send from passive effects.
     useLayoutEffect(()=>{
@@ -15,8 +18,21 @@ export function ExperimentsProvider(props) {
     useLayoutEffect(()=>()=>unregisterApiRoute(token), [
         token
     ]);
-    return /*#__PURE__*/ _jsx(ExperimentsContext.Provider, {
-        value: props.value,
-        children: props.children
+    useLayoutEffect(()=>{
+        registerClickGoals(token, depth, props.value);
+    }, [
+        token,
+        depth,
+        props.value
+    ]);
+    useLayoutEffect(()=>()=>unregisterClickGoals(token), [
+        token
+    ]);
+    return /*#__PURE__*/ _jsx(DepthContext.Provider, {
+        value: depth,
+        children: /*#__PURE__*/ _jsx(ExperimentsContext.Provider, {
+            value: props.value,
+            children: props.children
+        })
     });
 }

package/dist/client/clickGoals.d.ts

@@ -0,0 +1,4 @@
+import type { ClientAssignments } from '../types/assignments.js';
+/** One delegated listener; depth, rather than React's child-first commit order, decides ownership. */
+export declare function registerClickGoals(token: symbol, depth: number, value: ClientAssignments): void;
+export declare function unregisterClickGoals(token: symbol): void;

package/dist/client/clickGoals.js

@@ -0,0 +1,43 @@
+'use client';
+import { CLICK_KEY } from '../goals/key.js';
+import { sendEvent } from './beacon.js';
+import { idempotencyKey } from './idempotency.js';
+const providers = new Map();
+let listening;
+function onClick(event) {
+    let owner;
+    for (const provider of providers.values()){
+        if (provider.value.clickGoalsArmed && (!owner || provider.depth >= owner.depth)) owner = provider;
+    }
+    if (!owner) return;
+    const target = event.target;
+    const element = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+    const key = element?.closest('[data-xp-goal]')?.getAttribute('data-xp-goal');
+    if (!key || !CLICK_KEY.test(key)) return;
+    sendEvent(owner.value.apiRoute, {
+        type: 'conversion',
+        eventName: `click:${key}`,
+        idempotencyKey: `${owner.pageviewId}:${key}`
+    });
+}
+/** One delegated listener; depth, rather than React's child-first commit order, decides ownership. */ export function registerClickGoals(token, depth, value) {
+    const previous = providers.get(token);
+    const pageviewId = previous?.value === value ? previous.pageviewId : idempotencyKey();
+    providers.delete(token);
+    providers.set(token, {
+        depth,
+        value,
+        pageviewId
+    });
+    if (!listening && typeof document !== 'undefined') {
+        listening = document;
+        listening.addEventListener('click', onClick);
+    }
+}
+export function unregisterClickGoals(token) {
+    providers.delete(token);
+    if (!providers.size && listening) {
+        listening.removeEventListener('click', onClick);
+        listening = undefined;
+    }
+}

package/dist/collections/experiments/config.js

@@ -5,8 +5,9 @@ import { TARGETING_OPS, isOpValid } from '../../targeting/ops.js';
 import { readListValue } from '../../targeting/values.js';
 import { createDefaults } from './createDefaults.js';
 import { flagControlParams } from './flagControlParams.js';
+import { pickExperimentSlug } from './pickSlug.js';
 import { lockHook } from './lockHook.js';
-import { deleteGuard, deleteGuardAfter } from './deleteGuard.js';
+import { deleteGuard, deleteGuardAfter, deleteGuardBeforeOperation } from './deleteGuard.js';
 import { checkArms } from './armInvariants.js';
 import { XpNotImplemented, XpRefusal } from '../../errors.js';
 const targetingValue = (rule)=>rule.op === 'in' || rule.op === 'nin' ? readListValue(rule.value) : rule.value;
@@ -81,12 +82,16 @@ export function experimentsCollection(options) {
             }
         },
         hooks: {
+            beforeOperation: [
+                deleteGuardBeforeOperation
+            ],
             beforeValidate: [
                 createDefaults
             ],
             beforeChange: [
                 flagControlParams,
-                lockHook
+                lockHook,
+                pickExperimentSlug
             ],
             beforeDelete: [
                 deleteGuard
@@ -166,6 +171,11 @@ export function experimentsCollection(options) {
                                     read: async (args)=>args.doc?.kind !== 'code' || adminOnly(args)
                                 }
                             },
+                            {
+                                name: 'pageCollection',
+                                type: 'text',
+                                validate: (value, { previousValue })=>value === previousValue || value == null || value === '' || options.pages?.collections.some((entry)=>entry.slug === value) || 'Choose a registered page collection.'
+                            },
                             {
                                 name: 'flagPoint',
                                 type: 'text',

package/dist/collections/experiments/deleteGuard.d.ts

@@ -1,3 +1,4 @@
-import type { CollectionAfterDeleteHook, CollectionBeforeDeleteHook } from 'payload';
+import type { CollectionBeforeOperationHook, CollectionAfterDeleteHook, CollectionBeforeDeleteHook } from 'payload';
 export declare const deleteGuard: CollectionBeforeDeleteHook;
 export declare const deleteGuardAfter: CollectionAfterDeleteHook;
+export declare const deleteGuardBeforeOperation: CollectionBeforeOperationHook;

package/dist/collections/experiments/deleteGuard.js

@@ -1,4 +1,5 @@
-import { deleteExperiment, deleteExperimentAfter } from '../../transitions/deleteExperiment.js';
+import { deleteExperiment, deleteExperimentAfter, prepareBulkDelete } from '../../transitions/deleteExperiment.js';
+import { xpOptionsFromReq } from '../../options/fromReq.js';
 export const deleteGuard = async ({ req, id })=>{
     await deleteExperiment(req, id);
 };
@@ -6,3 +7,13 @@ export const deleteGuardAfter = async ({ req, id, doc })=>{
     await deleteExperimentAfter(req, id);
     return doc;
 };
+export const deleteGuardBeforeOperation = async ({ operation, args, req })=>{
+    if (operation === 'delete' && 'where' in args && args.where) {
+        // Payload runs beforeOperation before access; only a manager, or an explicit overrideAccess call, may make the plugin discover and lock the delete scope.
+        if (args.overrideAccess !== true && await xpOptionsFromReq(req).access.manage({
+            req
+        }) !== true) return args;
+        await prepareBulkDelete(req, args.where);
+    }
+    return args;
+};

package/dist/collections/experiments/editability.js

@@ -8,7 +8,8 @@ export const EDITABLE_BY_STATUS = {
         'flagPoint',
         'metrics',
         'analysis',
-        'exposurePolicy'
+        'exposurePolicy',
+        'pageCollection'
     ],
     stopped: [
         'name',
@@ -18,7 +19,8 @@ export const EDITABLE_BY_STATUS = {
         'allocation',
         'metrics',
         'analysis',
-        'exposurePolicy'
+        'exposurePolicy',
+        'pageCollection'
     ],
     running: [
         'name',

package/dist/collections/experiments/pickSlug.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionBeforeChangeHook } from 'payload';
+export declare const pickExperimentSlug: CollectionBeforeChangeHook;

package/dist/collections/experiments/pickSlug.js

@@ -0,0 +1,8 @@
+import { pickSlug } from '../../db/slugs.js';
+import { pooledExecutor, txExecutor } from '../../db/executor.js';
+export const pickExperimentSlug = async ({ req, data, operation })=>{
+    if (operation !== 'create' || typeof data.slug !== 'string' || !data.slug) return data;
+    const transactional = await req.transactionID != null;
+    data.slug = await pickSlug(transactional ? txExecutor(req) : pooledExecutor(req.payload), data.slug, transactional);
+    return data;
+};

package/dist/collections/labels.d.ts

@@ -0,0 +1,3 @@
+import type { PayloadRequest } from 'payload';
+/** Payload labels may be translated strings or functions. Keep server entries dependency-safe. */
+export declare function collectionLabel(label: unknown, slug: string, req: PayloadRequest): string;

package/dist/collections/labels.js

@@ -0,0 +1,20 @@
+/** Payload labels may be translated strings or functions. Keep server entries dependency-safe. */ export function collectionLabel(label, slug, req) {
+    try {
+        if (typeof label === 'function') {
+            const value = label({
+                i18n: req.i18n,
+                t: req.i18n.t
+            });
+            return typeof value === 'string' ? value : slug;
+        }
+        if (typeof label === 'string') return label;
+        const translations = label && typeof label === 'object' ? label : {};
+        return [
+            translations[req.i18n?.language ?? 'en'],
+            translations.en,
+            ...Object.values(translations)
+        ].find((value)=>typeof value === 'string') ?? slug;
+    } catch  {
+        return slug;
+    }
+}

package/dist/collections/metrics.js

@@ -1,3 +1,4 @@
+import { CLICK_KEY, isClickSource, validClickSource } from '../goals/key.js';
 import { XP_METRIC_SOURCE_SELECT } from '../admin/paths.js';
 import { managedAccess } from './access.js';
 import { serializeMetricSources } from './serialize.js';
@@ -30,6 +31,14 @@ export function metricsCollection(options) {
             beforeValidate: [
                 ({ data, originalDoc })=>{
                     if (!data) return data;
+                    if (isClickSource(data.source ?? originalDoc?.source)) {
+                        data.source = `click:${data.slug ?? originalDoc?.slug ?? ''}`;
+                        data.direction = 'increase';
+                        data.capping = {
+                            type: null,
+                            value: null
+                        };
+                    }
                     const source = sources.find((source)=>source.id === (data.source ?? originalDoc?.source));
                     const capping = data.capping === undefined ? originalDoc?.capping : data.capping;
                     // Payload may submit an empty optional group as { type: null, value: null }.
@@ -58,6 +67,7 @@ export function metricsCollection(options) {
                 type: 'text',
                 required: true,
                 unique: true,
+                validate: (value, { data })=>!isClickSource(data?.source) || typeof value === 'string' && CLICK_KEY.test(value) || 'Use 1–64 lowercase letters, numbers, underscores or hyphens, starting with a letter or number.',
                 admin: {
                     description: 'Use a unique short name for code that refers to this goal.'
                 }
@@ -67,7 +77,7 @@ export function metricsCollection(options) {
                 label: 'Measured by',
                 type: 'text',
                 required: true,
-                validate: (value)=>sources.some((source)=>source.id === value) || 'Choose what this goal is measured by.',
+                validate: (value)=>(isClickSource(value) ? validClickSource(value) : sources.some((source)=>source.id === value)) || 'Choose what this goal is measured by.',
                 admin: {
                     description: 'Choose the outcome this goal measures.',
                     components: {
@@ -135,7 +145,7 @@ export function metricsCollection(options) {
                         },
                         validate: (value, { data, siblingData })=>{
                             const source = sources.find((source)=>source.id === data?.source);
-                            return validateCappingType(value, siblingData?.value, source?.kind);
+                            return validateCappingType(value, siblingData?.value, isClickSource(data?.source) ? 'binomial' : source?.kind);
                         }
                     },
                     {