@forumone/throughline-design-system 0.0.0 → 1.0.0-next.0

package/dist/generate/blocks.js

@@ -0,0 +1,118 @@
+import { groupOf } from '../contract/index.js';
+import { withAltFallback } from '../altText.js';
+import { toPayloadField } from './fields.js';
+import { blockGuidance, humanize } from './guidance.js';
+import { groupLabel } from './labels.js';
+import { arrange, blockSummaryFields } from './layout.js';
+const BLOCK_SUMMARY = '@forumone/throughline-design-system/client#BlockSummary';
+/**
+ * Which components are authorable as blocks.
+ *
+ * `inline` placement means the component is a building block used *inside*
+ * another one — a `Card` within a `CardGrid`, a `Button` within a CTA. It
+ * reaches the page through its parent's fields, so offering it in the palette
+ * would let an author drop a bare card onto a page with nothing around it.
+ *
+ * `page` and `section` are the two that stand on their own. `notABlock` in the
+ * overrides removes the handful that are page-level but not authored — the
+ * chrome a template renders rather than a block an author places.
+ */
+export function isBlockCandidate(component, overrides) {
+    if (overrides[component.name]?.notABlock)
+        return false;
+    return component.composition.placement.some(p => p === 'page' || p === 'section');
+}
+/**
+ * The block slug is the manifest component name, byte for byte.
+ *
+ * Not a stylistic choice. `@forumone/throughline/publishing`'s composition step maps
+ * `blockType` straight to `type` with no transformation and looks it up in the
+ * manifest; a miss is an `unknown-component` **error**, which blocks publish.
+ * Kebab-casing the slugs would make every block on every page unpublishable,
+ * and the error would point at the design system rather than at the naming.
+ */
+export function generateBlock(component, options) {
+    const ctx = {
+        component: component.name,
+        overrides: options.overrides,
+        mediaCollection: options.mediaCollection,
+        linkCollections: options.linkCollections,
+        resolveSelectOptions: options.resolveSelectOptions,
+        resolveNamedOptions: options.resolveNamedOptions,
+        ...(options.optionLabels ? { optionLabels: options.optionLabels } : {}),
+    };
+    // Arranged for an author to read — pairs grouped, settings behind a
+    // disclosure. Presentational only; see `./layout.ts`. An alt beside its image
+    // falls back to the media's, so it is generated optional; see `../altText.ts`.
+    const contract = withAltFallback(component.content.fields);
+    const generated = contract.map(field => toPayloadField(field, ctx));
+    const fields = arrange(contract, generated, { disclose: true });
+    const preview = options.resolvePreview?.(component.name) ?? null;
+    const guidance = blockGuidance(component.intent, Object.keys(options.manifest.components));
+    // The picker's name for it. An override for the few names a mechanical split
+    // gets wrong — `AtAGlance` → "At AGlance" — or that mislead.
+    const label = options.overrides[component.name]?.label ?? humanize(component.name);
+    return {
+        slug: component.name,
+        interfaceName: `${component.name}Block`,
+        // The preview is described by the block's label, not its slug: a screen
+        // reader announced "A preview of the HighImpactCTA component".
+        ...(preview
+            ? { imageURL: preview.url, imageAltText: preview.alt ?? `A preview of the ${label} block` }
+            : {}),
+        labels: {
+            singular: label,
+            plural: label,
+        },
+        admin: {
+            // A collapsed block says what it holds, not only what type it is — see
+            // `../admin/BlockSummary.tsx`. Every block gets it, including one with
+            // no text to show, so every header on a page is drawn by the same code.
+            components: {
+                Label: {
+                    path: BLOCK_SUMMARY,
+                    clientProps: {
+                        fields: blockSummaryFields(component.content.fields, generated),
+                        singular: label,
+                        slug: component.name,
+                    },
+                },
+            },
+            // Which shelf of the picker this block sits on.
+            //
+            // `groupOf` is the contract's resolver: a component's `group` when it
+            // sets one, its `category` when it does not. Both fields are read through
+            // it rather than either directly, so a component that has not been given
+            // a group still lands somewhere sensible instead of on a nameless shelf.
+            //
+            // The two are different questions. `category` is what the component *is*,
+            // and other consumers read it that way — the components MCP server
+            // filters on it. `group` is where an author looks for it. Grouping on
+            // `category` alone put over half the picker under "Section", which is the
+            // flat list the grouping exists to avoid.
+            group: groupLabel(groupOf(component)),
+        },
+        // A block with no authorable fields is still legitimate: some components
+        // are entirely presentational. Payload needs a field array, not a non-empty
+        // one.
+        //
+        // Headed by what the block is for — see `./guidance.ts`. A `ui` field, so
+        // it stores nothing and is absent from the generated types.
+        fields: guidance ? [guidanceField(guidance), ...fields] : fields,
+    };
+}
+const BLOCK_GUIDANCE = '@forumone/throughline-design-system/client#BlockGuidance';
+function guidanceField(text) {
+    return {
+        name: 'blockGuidance',
+        type: 'ui',
+        admin: { components: { Field: { path: BLOCK_GUIDANCE, clientProps: { text } } } },
+    };
+}
+export function generateBlocks(options) {
+    return Object.values(options.manifest.components)
+        .filter(component => isBlockCandidate(component, options.overrides))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map(component => ({ block: generateBlock(component, options), component }));
+}
+//# sourceMappingURL=blocks.js.map

package/dist/generate/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../../src/generate/blocks.ts"],"names":[],"mappings":"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"}

package/dist/generate/fields.d.ts

@@ -0,0 +1,60 @@
+import type { Field } from 'payload';
+import { type Overrides } from '../overrides.js';
+/**
+ * One field of a component's content model, as the manifest describes it.
+ * Restated rather than imported from `@forumone/throughline-design-system/contract`
+ * because that package exports the Zod-inferred shape, and this only needs the
+ * parts the generator reads.
+ */
+export interface ContentField {
+    name: string;
+    type: 'text' | 'richtext' | 'link' | 'image' | 'video' | 'select' | 'group' | 'array' | 'boolean' | 'number';
+    required: boolean;
+    maxLength?: number;
+    /** `boolean` only — see the contract schema. */
+    defaultValue?: boolean;
+    constraints?: string;
+    /**
+     * An optional field most authors should leave alone: an override of a
+     * default the component already chooses well, or screen-reader and status
+     * copy it already supplies. Drawn in a collapsed "More options" section —
+     * see `./layout.ts`.
+     */
+    advanced?: boolean;
+    of?: ContentField[];
+}
+export interface FieldContext {
+    /** Component name, for override lookup and error messages. */
+    component: string;
+    overrides: Overrides;
+    /** Upload collection an `image` field points at. */
+    mediaCollection: string;
+    /** Collections an internal link may target. */
+    linkCollections: string[];
+    /** Resolves `select` options for `<Component>.<path>`, or null if it cannot. */
+    resolveSelectOptions: (component: string, path: string) => readonly string[] | null;
+    /** Resolves a named exported union — used for the global icon set. */
+    resolveNamedOptions: (typeName: string) => readonly string[] | null;
+    /** The host's words for option values particular to its design system — see `optionLabel`. */
+    optionLabels?: Readonly<Record<string, string>>;
+}
+/**
+ * A link, as one group rather than 41 ad-hoc ones.
+ *
+ * Internal links hold a relationship, not a path, so renaming a page cannot
+ * break every link that pointed at it — the renderer resolves the current slug
+ * at read time.
+ *
+ * `required` is enforced by a validate rather than by Payload's own flag, for
+ * the reason `requiredLink` gives.
+ */
+export declare function linkField(name: string, ctx: FieldContext, description?: string, required?: boolean): Field;
+/**
+ * Turns one contract field into one Payload field.
+ *
+ * Returns null when the field is deliberately not authorable — an omitted
+ * runtime-state field, or a slot, which is a component position rather than
+ * content and is filled by the template.
+ */
+export declare function toPayloadField(field: ContentField, ctx: FieldContext, path?: string): Field | null;
+//# sourceMappingURL=fields.d.ts.map

package/dist/generate/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/generate/fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,KAAK,EAAE,MAAM,SAAS,CAAA;AAGpD,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAI/D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EACA,MAAM,GACN,UAAU,GACV,MAAM,GACN,OAAO,GACP,OAAO,GACP,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,QAAQ,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,EAAE,CAAC,EAAE,YAAY,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAA;IACvB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,gFAAgF;IAChF,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACnF,sEAAsE;IACtE,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACnE,8FAA8F;IAC9F,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD;AAsCD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,YAAY,EACjB,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,UAAQ,GACf,KAAK,CA0DP;AAED;;;;;;GAMG;AAwCH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,YAAY,EACjB,IAAI,GAAE,MAAmB,GACxB,KAAK,GAAG,IAAI,CAKd"}

package/dist/generate/fields.js

@@ -0,0 +1,478 @@
+import { formatLabels } from 'payload/shared';
+import { withAltFallback } from '../altText.js';
+import { fieldOverride } from '../overrides.js';
+import { labelFor, optionLabel, selectDescription } from './labels.js';
+import { arrange, oneLine, summaryFields } from './layout.js';
+/** The design system's exported union of every glyph name. */
+const ICON_NAME_TYPE = 'IconName';
+/** The import-map path of the header a generated array row draws. */
+const ROW_SUMMARY = '@forumone/throughline-design-system/client#RowSummary';
+/** Above this, a single-line input stops being the right control. */
+const TEXTAREA_THRESHOLD = 160;
+function describe(field) {
+    return field.constraints;
+}
+/**
+ * A select, with every option labelled and its description rid of the
+ * sentences that only listed the options — see `optionLabel` and
+ * `selectDescription` in `./labels.ts`. Every generated select comes through
+ * here, whichever branch resolved its values.
+ */
+function selectField(field, values, ctx, required) {
+    const label = (value) => optionLabel(value, ctx.optionLabels);
+    const description = selectDescription(describe(field), values, label);
+    return {
+        name: field.name,
+        type: 'select',
+        options: values.map(value => ({ label: label(value), value })),
+        ...required,
+        ...(description ? { admin: { description } } : {}),
+    };
+}
+/**
+ * A link, as one group rather than 41 ad-hoc ones.
+ *
+ * Internal links hold a relationship, not a path, so renaming a page cannot
+ * break every link that pointed at it — the renderer resolves the current slug
+ * at read time.
+ *
+ * `required` is enforced by a validate rather than by Payload's own flag, for
+ * the reason `requiredLink` gives.
+ */
+export function linkField(name, ctx, description, required = false) {
+    return {
+        name,
+        type: 'group',
+        ...(description ? { admin: { description } } : {}),
+        ...(required ? { validate: requiredLink() } : {}),
+        fields: [
+            {
+                name: 'mode',
+                type: 'radio',
+                label: 'Links to',
+                defaultValue: 'internal',
+                options: [
+                    { label: 'A page on this site', value: 'internal' },
+                    { label: 'Another site', value: 'external' },
+                    { label: 'Somewhere on this page', value: 'anchor' },
+                ],
+                admin: { layout: 'horizontal' },
+            },
+            {
+                name: 'reference',
+                type: 'relationship',
+                label: 'Page',
+                // The package is generic over any Payload config, so it cannot know
+                // this project's slugs; `CollectionSlug` is generated per app.
+                relationTo: ctx.linkCollections,
+                admin: { condition: (_d, sibling) => sibling?.mode === 'internal' },
+            },
+            {
+                name: 'url',
+                type: 'text',
+                label: 'URL',
+                admin: {
+                    condition: (_d, sibling) => sibling?.mode === 'external',
+                    description: 'Include the protocol — https://…',
+                },
+            },
+            {
+                name: 'anchor',
+                type: 'text',
+                label: 'Anchor',
+                admin: {
+                    condition: (_d, sibling) => sibling?.mode === 'anchor',
+                    description: 'The id of the element to scroll to, without the #.',
+                },
+            },
+            {
+                name: 'newTab',
+                type: 'checkbox',
+                label: 'Open in a new tab',
+                admin: {
+                    condition: (_d, sibling) => sibling?.mode === 'external',
+                    description: 'Opening a new tab takes the back button away, so reserve it for leaving the site.',
+                },
+            },
+        ],
+    };
+}
+/**
+ * Turns one contract field into one Payload field.
+ *
+ * Returns null when the field is deliberately not authorable — an omitted
+ * runtime-state field, or a slot, which is a component position rather than
+ * content and is filled by the template.
+ */
+/*
+An upload field cannot be stopped from editing the document it points at.
+
+Worth writing down, because the fix looks obvious, was tried, shipped inert in
+0.4.3, and would be tried again.
+
+Payload's upload field offers two actions side by side and they look alike. The
+picker changes which library document this block points at: local to the block,
+carried by the draft, published when the page is. The edit pencil opens that
+document in a drawer whose file can be removed and replaced: global, immediate,
+and shared by every block that picked it. Downstream that turned "change the
+photograph on this page" into "change it on all five pages that picked this
+photograph, now, while the page you are looking at is still a draft".
+
+`admin: { allowEdit: false }` does not prevent it, for three independent
+reasons, in payload 3.87.1:
+
+  - it is not an option. `UploadAdmin` is `allowCreate` and `isSortable`;
+    `allowEdit` belongs to `RelationshipAdmin`, a different field type
+  - it would not survive the trip. `UploadAdminClient` is
+    `AdminClient & Pick<UploadAdmin, 'allowCreate' | 'isSortable'>`
+  - and the component does not read it. `@payloadcms/ui`'s
+    `fields/Upload/HasOne` renders `allowEdit: !readonly`, hardcoded. Compare
+    `allowCreate`, which *is* wired through `fields/Upload/index.js`
+
+So the only way to lose the pencil is `readOnly`, which takes the picker with
+it. The asymmetry with `allowCreate` looks like an upstream oversight rather
+than a decision, and is filed as such — until it moves, this is a Payload
+behaviour a host has to design around rather than a generator setting.
+
+**How the inert version passed every gate**, which is the part worth keeping.
+It was written through a helper returning `{ admin: Record<string, unknown> }`,
+and that widening is exactly what suppresses the excess-property check: written
+inline, `tsc` rejects `allowEdit` on an upload's admin, and does so today. The
+tests then asserted `allowEdit` was present *on the generated config object* —
+one end of a string whose other end nothing reads. That is the same shape as a
+cache tag nobody listens to, and it is why the assertions in this file are
+about behaviour wherever behaviour is reachable.
+*/
+export function toPayloadField(field, ctx, path = field.name) {
+    const built = buildField(field, ctx, path);
+    // Every generated field is labelled explicitly — see `./labels.ts` for why
+    // Payload's own title-cased fallback is not good enough.
+    return built ? { ...built, label: labelFor(field) } : null;
+}
+function buildField(field, ctx, path) {
+    const override = fieldOverride(ctx.overrides, ctx.component, path);
+    if (override?.omit)
+        return null;
+    const description = describe(field);
+    const admin = description ? { admin: { description } } : {};
+    const required = field.required ? { required: true } : {};
+    if (override?.as === 'icon') {
+        const options = override.options ??
+            ctx.resolveSelectOptions(ctx.component, path) ??
+            ctx.resolveNamedOptions(ICON_NAME_TYPE);
+        if (!options) {
+            throw new Error(`${ctx.component}.${path} is marked as an icon field but no options could be resolved, ` +
+                `and neither could the design system's ${ICON_NAME_TYPE}.`);
+        }
+        return selectField(field, options, ctx, required);
+    }
+    switch (field.type) {
+        case 'text': {
+            /*
+            A text field whose prop is a union of string literals is a select that
+            the contract could not say was one — `ContentField` has ten types and no
+            way to mean "one of these names". The component's own type does say it,
+            so read it: `IntroSection.actions[].icon` is `keyof typeof Icons`, and a
+            free-text box there would let an author type a glyph name that renders
+            nothing at all.
+            */
+            const asUnion = ctx.resolveSelectOptions(ctx.component, path);
+            if (asUnion) {
+                return selectField(field, asUnion, ctx, required);
+            }
+            // A 600-character answer in a single-line input is a usability bug, not
+            // a styling preference. `text` and `textarea` are separate field types in
+            // Payload, so the branch has to produce whole objects rather than a
+            // computed `type`.
+            const long = field.maxLength === undefined || field.maxLength > TEXTAREA_THRESHOLD;
+            const length = field.maxLength === undefined ? {} : { maxLength: field.maxLength };
+            return long
+                ? { name: field.name, type: 'textarea', ...length, ...required, ...admin }
+                : { name: field.name, type: 'text', ...length, ...required, ...admin };
+        }
+        case 'number':
+            return { name: field.name, type: 'number', ...required, ...admin };
+        case 'boolean':
+            // `required` on a checkbox would mean "must be ticked", which is never
+            // what a contract means by it.
+            //
+            // `defaultValue` was hardcoded `false` here, which made a component's own
+            // default unreachable: `coerce` turns whatever is stored into a real
+            // boolean, so the prop is never `undefined` and a signature default like
+            // `hasFacade = true` can never apply. A contract that wants the box
+            // ticked to begin with now says so and is believed.
+            return {
+                name: field.name,
+                type: 'checkbox',
+                defaultValue: field.defaultValue ?? false,
+                ...admin,
+            };
+        case 'richtext':
+            return { name: field.name, type: 'richText', ...required, ...admin };
+        case 'image':
+            return {
+                name: field.name,
+                type: 'upload',
+                relationTo: ctx.mediaCollection,
+                ...required,
+                ...admin,
+            };
+        case 'video':
+            /*
+            Two kinds of video wear the same contract type, and the override is what
+            tells them apart.
+      
+            `videoUpload` is a file the site serves itself — `VideoHero`'s background
+            clip — so it is an upload against the same media collection an image
+            uses, which already accepts `video/mp4`. Everything else is a provider
+            embed URL: `VideoEmbed` takes a YouTube/Vimeo/Wistia src and has a
+            separate `poster` field that *is* an image.
+            */
+            if (override?.as === 'videoUpload') {
+                return {
+                    name: field.name,
+                    type: 'upload',
+                    relationTo: ctx.mediaCollection,
+                    ...required,
+                    ...admin,
+                };
+            }
+            return {
+                name: field.name,
+                type: 'text',
+                ...required,
+                admin: {
+                    description: description ?? 'A YouTube or Vimeo URL.',
+                },
+            };
+        case 'link':
+            return linkField(field.name, ctx, description, field.required);
+        case 'select': {
+            const options = override?.options ?? ctx.resolveSelectOptions(ctx.component, path);
+            if (!options) {
+                throw new Error(`${ctx.component}.${path} is a select, but its allowed values could not be resolved. ` +
+                    `The manifest does not carry them — they live in the component's own literal union ` +
+                    `type, or in an \`options\` override when it has none.`);
+            }
+            return selectField(field, options, ctx, required);
+        }
+        case 'group': {
+            // A group with no children is a *slot* — a place a component renders
+            // another component, declared in `composition.allowedSlots`. It holds no
+            // authored content, so there is nothing to put in the CMS.
+            if (!field.of || field.of.length === 0)
+                return null;
+            const of = withAltFallback(field.of);
+            const children = childFields(of, ctx, path);
+            /*
+            An optional group holds its children to a weaker promise than it looks.
+      
+            `ProseSection.image` is `required: false` with `src` and `alt` both
+            required inside it — meaning "an image is optional, but a *half* image is
+            not". Generated literally, Payload validates those children whether or
+            not the group has anything in it, so every block carrying an optional
+            image became a block that could not be published without one. Six of the
+            eight blocks on the About page failed that way.
+      
+            So inside an optional group the children are relaxed, and the promise the
+            contract actually made is enforced on the group instead: fill it or leave
+            it, but do not half-fill it.
+            */
+            if (field.required) {
+                return { name: field.name, type: 'group', ...admin, fields: children };
+            }
+            return {
+                name: field.name,
+                type: 'group',
+                ...admin,
+                validate: allOrNothing(of),
+                fields: relaxRequired(children),
+            };
+        }
+        case 'array': {
+            if (!field.of || field.of.length === 0) {
+                throw new Error(`${ctx.component}.${path} is an array with no \`of\` describing its rows.`);
+            }
+            // A row is drawn on one line and named by its contents where it can be
+            // — see the end of `./layout.ts`.
+            const of = withAltFallback(field.of);
+            const generated = generateChildren(of, ctx, path);
+            const summary = summaryFields(of, generated);
+            const rowLabel = summary.length > 0
+                ? {
+                    components: {
+                        RowLabel: {
+                            path: ROW_SUMMARY,
+                            clientProps: { fields: summary, singular: formatLabels(field.name).singular },
+                        },
+                    },
+                }
+                : {};
+            return {
+                name: field.name,
+                type: 'array',
+                // Payload has no "required array"; a minimum of one row is what the
+                // contract means.
+                ...(field.required ? { minRows: 1 } : {}),
+                ...(description || summary.length > 0
+                    ? { admin: { ...(description ? { description } : {}), ...rowLabel } }
+                    : {}),
+                fields: oneLine(childFields(of, ctx, path, generated)),
+            };
+        }
+    }
+}
+/**
+ * Strip `required` from a group's children, recursing into nested groups.
+ *
+ * Only ever applied inside an optional group — see the `group` case. An array
+ * keeps its `minRows`, because Payload does not enforce rows on an array whose
+ * parent group is empty.
+ */
+function relaxRequired(fields) {
+    return fields.map(field => {
+        const next = 'required' in field && field.required ? { ...field, required: false } : field;
+        return 'fields' in next && Array.isArray(next.fields) && next.type === 'group'
+            ? { ...next, fields: relaxRequired(next.fields) }
+            : next;
+    });
+}
+/**
+ * "Fill it or leave it, but do not half-fill it."
+ *
+ * The validation an optional group needs and Payload has no field-level way to
+ * express: silent while the group is empty, and demanding of exactly the
+ * children the contract marked required once any of them is filled in.
+ */
+function allOrNothing(children) {
+    const names = children.filter(child => child.required).map(child => child.name);
+    /*
+    Booleans this group defaults to ticked.
+  
+    `isEmpty` answers for a value alone and reads `false` as "nobody touched
+    this", which is right for a checkbox that starts unticked. A checkbox the
+    contract starts *ticked* says the same thing with the opposite value, and
+    `isEmpty` cannot know that without being told which field it is looking at.
+    Left unhandled, such a field makes its group permanently non-empty and
+    `allOrNothing` demands the group's required children of an author who has
+    typed nothing — the third route to the defect this file's `isEmpty` comment
+    describes.
+    */
+    const defaultTicked = new Set(children.filter(child => child.type === 'boolean' && child.defaultValue === true).map(child => child.name));
+    const untouched = (name, v) => defaultTicked.has(name) ? v === true || isEmpty(v) : isEmpty(v);
+    return (value) => {
+        if (!value || typeof value !== 'object')
+            return true;
+        const entries = Object.entries(value);
+        if (entries.every(([k, v]) => untouched(k, v)))
+            return true;
+        const missing = names.filter(name => isEmpty(value[name]));
+        if (missing.length === 0)
+            return true;
+        return missing.length === 1
+            ? `${missing[0]} is needed once anything else here is filled in. Clear the rest to leave this out entirely.`
+            : `${missing.join(' and ')} are needed once anything else here is filled in. Clear the rest to leave this out entirely.`;
+    };
+}
+/**
+ * A required link must actually go somewhere.
+ *
+ * `required: true` on a contract link field bought nothing for as long as this
+ * generator existed: the flag was read for every other field type and dropped
+ * for this one, and Payload's own `required` could not have replaced it anyway
+ * — on a group it asserts only that the object exists, which it always does,
+ * and on the children it would demand a `url` of a link whose author chose the
+ * internal mode. So the promise is kept here, against the branch the author
+ * actually picked.
+ *
+ * It cost a live defect. `FeaturedWork` marks each item's `href` required and
+ * types it `string`; two items on `/work` were saved with the link untouched,
+ * `resolveHref` returned `undefined`, React dropped the attribute, and the page
+ * shipped four `<a>` elements with no `href` — not links at all: skipped by
+ * crawlers, unreachable by keyboard, and scoring 0 on Lighthouse's
+ * `crawlable-anchors`. Nothing in the CMS had objected. See #483.
+ *
+ * **Silent until the surroundings are filled in.** A block or an array row
+ * Payload has only just created holds defaults, and refusing to save one before
+ * anybody has typed into it is the #354 defect — an error on a block the editor
+ * cannot yet act on. So the rule reads its siblings: everything around it empty
+ * means nobody has been here, and the link is left alone. That is the same
+ * bargain `allOrNothing` strikes one level up, and it lands on the case that
+ * matters — a row carrying a title and a paragraph and no destination.
+ */
+function requiredLink() {
+    return (value, options) => {
+        const link = (value ?? {});
+        const mode = link.mode ?? 'internal';
+        if (mode === 'internal' && !isEmpty(link.reference))
+            return true;
+        if (mode === 'external' && !isEmpty(link.url))
+            return true;
+        if (mode === 'anchor' && !isEmpty(link.anchor))
+            return true;
+        if (isEmpty(options?.siblingData))
+            return true;
+        if (mode === 'external')
+            return 'Enter the URL this link goes to.';
+        if (mode === 'anchor')
+            return 'Name the id this link scrolls to.';
+        return 'Choose the page this link goes to.';
+    };
+}
+/*
+"Nobody has been here yet", and why it has to be recursive — which is not
+obvious until it bites.
+
+A group holding a link sub-group is never literally empty: `linkField` gives
+`mode` a default of `'internal'`, so an untouched `caseStudy` arrives as
+`{ stat: {}, href: { mode: 'internal' } }`. Compared shallowly that is a filled
+group, and `allOrNothing` then demands the title of an author who has typed
+nothing — that validation firing on exactly the case it exists to allow.
+
+`mode` is skipped for that reason: it is a discriminator that says which *kind*
+of link this would be if there were one, and it is present whether or not
+anybody chose anything. It is never evidence that a group was filled in.
+
+**An unticked checkbox is the same thing, and is why `false` counts as empty.**
+`boolean` fields are generated with `defaultValue: false` unless the contract
+declares otherwise, so a group holding one is never literally empty either — and `false` is indistinguishable from
+"nobody touched this", because Payload stores the default and an author's
+deliberate untick identically. Treating it as filled makes the rule demand the
+group's required children of somebody who has typed nothing, which is the same
+defect this comment already describes, arriving by a second route.
+
+It did arrive: `ManagedForm.consent` holds a `required` boolean beside a
+required `text`, and adding the block failed to save with "Consent is invalid"
+before an editor could touch it.
+
+A checkbox the contract starts *ticked* says "nobody touched this" with `true`
+instead, which this function cannot see — it is handed a value, not a field.
+`allOrNothing` knows the field shapes and handles that case itself.
+
+`requiredLink` asks the same question of a link's *siblings*, which is what
+keeps it quiet on a block or a row nobody has typed into yet.
+*/
+function isEmpty(value) {
+    if (value === undefined || value === null || value === '')
+        return true;
+    if (value === false)
+        return true;
+    if (Array.isArray(value))
+        return value.every(isEmpty);
+    if (typeof value === 'object') {
+        return Object.entries(value).every(([key, held]) => key === 'mode' || isEmpty(held));
+    }
+    return false;
+}
+function generateChildren(children, ctx, parentPath) {
+    return children.map(child => toPayloadField(child, ctx, `${parentPath}.${child.name}`));
+}
+function childFields(children, ctx, parentPath, generated = generateChildren(children, ctx, parentPath)) {
+    const fields = arrange(children, generated, { disclose: false });
+    if (fields.length === 0) {
+        throw new Error(`${ctx.component}.${parentPath} has no authorable children left after overrides. ` +
+            `Payload rejects a group or array with an empty \`fields\`.`);
+    }
+    return fields;
+}
+//# sourceMappingURL=fields.js.map