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

package/CHANGELOG.md

@@ -0,0 +1,182 @@
+# @forumone/throughline-design-system
+
+## 1.0.0-next.2
+
+## 1.0.0-next.0
+
+### Major Changes
+
+- 825f4e9: `@forumone/throughline-design-system`: the 1.0 design-system package, from `@forumone/throughline-design-contract` and `@forumone/throughline-design-system-payload`, by `docs/spec/1.0-exports.md`. It is published for the first time: design-system-payload was private and shipped TypeScript source, and this package builds to `dist`.
+
+  - `@forumone/throughline-design-contract` is `/contract`, and its `/lint` is `/lint`.
+  - design-system-payload's `/generate`, `/render`, `/client` and `/testing` keep their names. Its root (`fieldOverride` and the override types) is part of `/generate`.
+  - The `check-block-props` bin is unchanged, and runs the built CLI.
+  - Admin component paths are `@forumone/throughline-design-system/client#BlockSummary`, `#BlockGuidance` and `#RowSummary`, so a site's `importMap.js` changes.
+  - `/contract` and `/lint` need no peers. `payload`, `react`, `@payloadcms/ui`, `typescript` (which `/generate` uses to read component source) and `vitest` (for `/testing`) are optional peers.
+
+  `@forumone/throughline/components` now reads manifests through `@forumone/throughline-design-system/contract`.
+
+The 0.x entries below are `@forumone/throughline-design-contract`'s. `@forumone/throughline-design-system-payload` was never published.
+
+## 0.6.0
+
+### Minor Changes
+
+- 2bf29e6: Generated blocks are arranged for an author to read, not in the shape the
+  component's props happen to take.
+  - Every generated field has an explicit, sentence-case label. Payload's own
+    fallback title-cased the prop name, so authors were asked for a "Cta Href"
+    and an "Image Alt". Now they see "Call to action", "Alt text", "Open on page
+    load", and a link's own controls read "Links to", "Page" and "URL".
+  - A `<prefix>Label` text field and its `<prefix>Href` or `<prefix>Url` link
+    are drawn as one group headed by what they are together ("Call to action",
+    "View all link"), with a matching `<prefix>Icon` inside it. This applies at
+    every level, array rows included.
+  - Top-level selects, checkboxes and numbers, plus any field a contract marks
+    with the new `advanced: true`, move to one collapsed "More options" section
+    at the end of the block. A required field is never tucked away.
+
+  All of this is presentational. An unnamed group and a collapsible store their
+  children flat, so the stored data, the generated types and `coerce` are
+  unchanged. A host test that walks `block.fields` for named fields now has to
+  look through those wrappers.
+
+  `advanced` is a new optional contract field property. It hints that most
+  authors, and most compositions, should leave the field empty. It is refused on
+  a required field.
+
+## 0.5.1
+
+### Patch Changes
+
+- 957403b: One `@types/node`, so a host does not end up with two copies of `@payloadcms/ui`
+
+  Twelve packages asked for `@types/node@^20.17.0` and `design-system-payload`
+  asked for `^24.13.2`. Inside this repository that is untidy. Inside a host that
+  consumes the suite from source — which is how `forumone/forumone-2026` uses it,
+  as a git submodule in one pnpm workspace — it is a runtime failure.
+
+  pnpm hashes a package's identity with its resolved peers. `publishing` and
+  `integrations` both take `@payloadcms/ui` as a peer _and_ as a devDependency, so
+  each got its own copy resolved against `@types/node@20`, while the host's copy
+  resolved against `@types/node@24`. Same version, 3.87.1, two directories:
+
+      apps/web                     → @payloadcms+ui@3.87.1_…_9ce0de5c…
+      packages/publishing          → @payloadcms+ui@3.87.1_…_13184ec4…
+      packages/integrations        → @payloadcms+ui@3.87.1_…_13184ec4…
+
+  Two directories are two module instances. Two instances of `@payloadcms/ui` are
+  two `ConfigContext` objects, and `PublishButton` read the one the admin's
+  provider had never populated:
+
+      TypeError: Cannot destructure property 'config' of useConfig() as it is undefined
+
+  The host saw an intermittent 500 on every admin document view — `PublishButton`
+  is installed on each collection with a publish policy, so lists, `/admin` and
+  the login screen were all fine and only editing broke. Nothing caught it:
+  install, `--frozen-lockfile`, typecheck, lint and every test passed, because the
+  two copies are byte-identical and the split exists only at module resolution.
+  forumone/forumone-2026#498.
+
+  Aligning on `^24.13.2` collapses them to one instance. Nothing here targets a
+  Node 20 API deliberately; the packages typecheck and test unchanged against the
+  newer types.
+
+  `create-throughline` keeps `^20.17.0` on purpose. It is the one package
+  declaring `engines.node: >=20.9.0`, and typechecking a CLI against types newer
+  than the runtime it promises to support is how a Node 24-only call ships to
+  somebody on Node 20.
+
+## 0.5.0
+
+### Minor Changes
+
+- 45724ee: A contract can say a boolean starts ticked, and be believed
+
+  `boolean` fields were generated as `{ type: 'checkbox', defaultValue: false }`,
+  with the `false` hardcoded. That made a component's own default unreachable from
+  the CMS. A checkbox is stored ticked or unticked and never absent, so `coerce`
+  always had a value to turn into a real boolean, the prop was never `undefined`,
+  and a signature default like `hasFacade = true` could not apply. Every boolean a
+  contract described arrived at its component as `false`, whatever the component
+  said.
+
+  It was not theoretical. `VideoEmbed.hasFacade` exists to keep a provider's
+  iframe — several hundred kilobytes and its third-party cookies — off the page
+  until a reader presses play, and its contract says "Leave on". Every embed an
+  author added shipped with it off: the YouTube iframe was in the server HTML from
+  first paint, setting cookies on readers who never pressed play, on a site whose
+  stated rule is that no third-party tracking runs before consent.
+
+  So `ContentField` gains an optional `defaultValue`, read by the checkbox branch
+  and rejected on any other field type — anywhere else it is a value the author
+  expects to take effect and nothing ever would.
+
+  `allOrNothing` had to learn about it too. That rule treats `false` as "nobody
+  touched this", which is right for a checkbox that starts unticked and exactly
+  wrong for one that starts ticked: left alone, a group holding a ticked-by-default
+  boolean would never look empty, and the rule would demand the group's required
+  children of an author who had typed nothing. It now takes a field's declared
+  default into account rather than the value alone.
+
+  **Existing stored values are untouched.** `defaultValue` applies to a field an
+  author has not yet filled in, so blocks already saved keep whatever is in the
+  database; a `VideoEmbed` saved before this change still renders without its
+  facade until someone edits it.
+
+## 0.4.0
+
+### Minor Changes
+
+- 14f2be4: A contract can say a boolean starts ticked, and be believed
+
+  `boolean` fields were generated as `{ type: 'checkbox', defaultValue: false }`,
+  with the `false` hardcoded. That made a component's own default unreachable from
+  the CMS. A checkbox is stored ticked or unticked and never absent, so `coerce`
+  always had a value to turn into a real boolean, the prop was never `undefined`,
+  and a signature default like `hasFacade = true` could not apply. Every boolean a
+  contract described arrived at its component as `false`, whatever the component
+  said.
+
+  It was not theoretical. `VideoEmbed.hasFacade` exists to keep a provider's
+  iframe — several hundred kilobytes and its third-party cookies — off the page
+  until a reader presses play, and its contract says "Leave on". Every embed an
+  author added shipped with it off: the YouTube iframe was in the server HTML from
+  first paint, setting cookies on readers who never pressed play, on a site whose
+  stated rule is that no third-party tracking runs before consent.
+
+  So `ContentField` gains an optional `defaultValue`, read by the checkbox branch
+  and rejected on any other field type — anywhere else it is a value the author
+  expects to take effect and nothing ever would.
+
+  `allOrNothing` had to learn about it too. That rule treats `false` as "nobody
+  touched this", which is right for a checkbox that starts unticked and exactly
+  wrong for one that starts ticked: left alone, a group holding a ticked-by-default
+  boolean would never look empty, and the rule would demand the group's required
+  children of an author who had typed nothing. It now takes a field's declared
+  default into account rather than the value alone.
+
+  **Existing stored values are untouched.** `defaultValue` applies to a field an
+  author has not yet filled in, so blocks already saved keep whatever is in the
+  database; a `VideoEmbed` saved before this change still renders without its
+  facade until someone edits it.
+
+## 0.3.0
+
+### Minor Changes
+
+- 24bd325: Add an optional `group` to the component contract, so an authoring UI can shelve components separately from what they are.
+
+  `category` was answering two questions at once — what a component _is_, and where an editor looks for it — and it is a bad answer to the second at any real size. A design system of sixty blocks files roughly half of them under `section`, so a picker grouped on `category` hands back the flat list the grouping was meant to avoid while `card` and `navigation` hold one entry each. Evening the shelves out within `category` would file components under the wrong kind for every consumer that reasons about kind, including `list_components`.
+
+  So `category` keeps its meaning and its enum, and `group` takes the second question with a vocabulary of shelf labels: `hero`, `narrative`, `proof`, `listing`, `media`, `form`, `cta`, `navigation`, `utility`. No `section`, which is the problem being solved; no `card` or `data`, which name a kind rather than a place to look.
+
+  New API: `groupOf(component)` resolves `group ?? category`, and `LoadedManifest` gains `listByGroup()` and `listGroups()` which match on the resolved value. Grouping consumers should call `groupOf` rather than reading either field.
+
+  Non-breaking. `group` is optional, and the fallback means a design system that sets none groups exactly as it did before.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#9](https://github.com/forumone/throughline/pull/9) [`337f2ca`](https://github.com/forumone/throughline/commit/337f2ca779a30d2f135845259bbae8e961a625ed) Thanks [@briangraves](https://github.com/briangraves)! - Initial release. Defines `ComponentContractSchema`, `ManifestSchema`, `loadManifest`, `loadManifestFromUrl`, and `lintManifest`. Every design system that satisfies this contract is a valid input to the framework's Component Server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forum One Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @forumone/throughline-design-system
+
+The design-system side of Throughline. A design system describes its components in a manifest; this package defines that manifest, lints it, and turns it into Payload blocks, rendering and admin components for a Throughline site.
+
+> **1.0 is in progress.** This package is `@forumone/throughline-design-contract` and `@forumone/throughline-design-system-payload` together; [Upgrading from 0.x](https://github.com/forumone/throughline/blob/main/docs/guides/upgrading.md) moves a 0.x site onto it. Pre-releases publish as `1.0.0-next.N` under the `next` dist-tag.
+
+| Subpath     | Holds                                                                                                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/contract` | `ComponentContractSchema`, `ManifestSchema`, `loadManifest`: the contract every component declares and the manifest they make; see [docs/contract.md](https://github.com/forumone/throughline/blob/main/docs/reference/design-system/contract.md) |
+| `/lint`     | `lintManifest`, `formatLintIssues`, `assertManifestClean`                                                                                                                                                                                         |
+| `/generate` | `generateBlocks` and friends, manifest to Payload blocks, and `fieldOverride` for a site's exceptions; see [docs/payload.md](https://github.com/forumone/throughline/blob/main/docs/reference/design-system/generate.md)                          |
+| `/render`   | `RenderBlocks` and `coerceBlock`: stored blocks back to React                                                                                                                                                                                     |
+| `/client`   | `BlockSummary`, `BlockGuidance`, `RowSummary`: admin components named in Payload's import map                                                                                                                                                     |
+| `/testing`  | `describeBlockInvariants`, `checkUntouchedBlocks`, `checkBlockProps`: invariants a site runs over its blocks                                                                                                                                      |
+| bin         | `check-block-props <manifest.json> <components-dir>…`: does each contract produce the props its component takes?                                                                                                                                  |
+
+```bash
+pnpm add @forumone/throughline-design-system@next
+```
+
+`/contract` and `/lint` have no peers, so a design system that only publishes a manifest needs nothing else. The rest expects `payload` and `react`, `/client` expects `@payloadcms/ui`, `/generate` reads component source with `typescript`, and `/testing` is a vitest suite.
+
+**Reference: [`docs/reference/design-system.md`](https://github.com/forumone/throughline/blob/main/docs/reference/design-system.md).**

package/bin/check-block-props.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/*
+Does each design-system contract produce the props its component takes?
+
+  check-block-props <manifest.json> <components-dir>... [--overrides <module>] [--tsconfig <file>]
+
+The args files and overrides it loads are TypeScript, so `tsx` is registered
+before anything is imported. The CLI itself is this package's built output.
+
+Both of tsx's hooks, not just the ESM one. A `.ts` file with no
+`"type": "module"` above it is CommonJS to Node, and before Node 22 the ESM
+hook hands such a file to Node's own CommonJS loader, which cannot read
+TypeScript. A design system's directory need not be an ES module package.
+
+`--tsconfig` is read here rather than by the CLI, because it has to be known
+before tsx is registered. An args file written in TSX compiles with whatever
+`jsx` the tsconfig tsx finds says, and tsx looks beside the working directory:
+for a site running this from its app, that is the app's tsconfig, not the
+design system's. A design system that keeps its `jsx` in a project reference
+(`tsconfig.app.json`) has to be named. #207.
+
+Stylesheets are stubbed (`./stub-styles.mjs`): a component imports its CSS, an
+args file imports its component, and Node cannot load a `.css` file.
+*/
+import { createRequire, register as registerHooks } from 'node:module'
+import path from 'node:path'
+import { register as registerCommonJs } from 'tsx/cjs/api'
+import { register } from 'tsx/esm/api'
+
+const argv = process.argv.slice(2)
+const flag = argv.indexOf('--tsconfig')
+const tsconfig = flag === -1 ? undefined : argv[flag + 1]
+if (tsconfig) process.env.TSX_TSCONFIG_PATH = path.resolve(tsconfig)
+
+registerCommonJs()
+register(tsconfig ? { tsconfig: path.resolve(tsconfig) } : {})
+// After tsx, so it runs first: hooks registered later are consulted earlier.
+registerHooks('./stub-styles.mjs', import.meta.url)
+
+// The CommonJS half of the same stub, for a design system that is not an ES
+// module package. A `require`d stylesheet becomes the same answer-any-name
+// object.
+const extensions = createRequire(import.meta.url).extensions
+for (const ext of ['.css', '.scss', '.sass', '.less']) {
+  extensions[ext] = (module) => {
+    module.exports = new Proxy({}, { get: (_, key) => (typeof key === 'string' ? key : undefined) })
+  }
+}
+
+const { main } = await import('../dist/testing/checkBlockPropsCli.js')
+process.exitCode = await main(argv)

package/bin/stub-styles.mjs

@@ -0,0 +1,28 @@
+/*
+Stylesheet imports, answered with a stand-in.
+
+An args file imports its component for the types, and a component imports its
+stylesheet — `import styles from './card.module.css'` — so loading an args file
+in Node reaches a `.css` file, which Node cannot load, and the whole check
+stops on a file it never needed. What this compares is the shape of the args,
+not anything a stylesheet holds.
+
+So each stylesheet becomes a module whose default export answers any class
+name with that name, the way a CSS module does at runtime, and which has
+nothing else in it. Registered from `check-block-props.mjs` after tsx, so it
+runs before tsx's own hook.
+*/
+
+const STYLESHEET = /\.(css|scss|sass|less)$/
+
+export async function load(url, context, nextLoad) {
+  if (STYLESHEET.test(new URL(url).pathname)) {
+    return {
+      format: 'module',
+      shortCircuit: true,
+      source:
+        "export default new Proxy({}, { get: (_, key) => (typeof key === 'string' ? key : undefined) })\n",
+    }
+  }
+  return nextLoad(url, context)
+}

package/dist/admin/BlockGuidance.d.ts

@@ -0,0 +1,13 @@
+export interface BlockGuidanceProps {
+    /** The sentence to show — see `../generate/guidance.ts`. Injected via `clientProps`. */
+    text: string;
+}
+/**
+ * The line at the head of an opened block saying what the block is for.
+ *
+ * A `ui` field, so it stores nothing and appears in no generated type. Drawn
+ * with Payload's own description class, so it reads as help text rather than
+ * as a field.
+ */
+export declare function BlockGuidance({ text }: BlockGuidanceProps): import("react").JSX.Element;
+//# sourceMappingURL=BlockGuidance.d.ts.map

package/dist/admin/BlockGuidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockGuidance.d.ts","sourceRoot":"","sources":["../../src/admin/BlockGuidance.tsx"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,kBAAkB,+BAMzD"}

package/dist/admin/BlockGuidance.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The line at the head of an opened block saying what the block is for.
+ *
+ * A `ui` field, so it stores nothing and appears in no generated type. Drawn
+ * with Payload's own description class, so it reads as help text rather than
+ * as a field.
+ */
+export function BlockGuidance({ text }) {
+    return (_jsx("p", { className: "field-description", style: { margin: '0 0 calc(var(--base) * 0.75)' }, children: text }));
+}
+//# sourceMappingURL=BlockGuidance.js.map

package/dist/admin/BlockGuidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockGuidance.js","sourceRoot":"","sources":["../../src/admin/BlockGuidance.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AAOZ;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,EAAE,IAAI,EAAsB;IACxD,OAAO,CACL,YAAG,SAAS,EAAC,mBAAmB,EAAC,KAAK,EAAE,EAAE,MAAM,EAAE,8BAA8B,EAAE,YAC/E,IAAI,GACH,CACL,CAAA;AACH,CAAC"}

package/dist/admin/BlockSummary.d.ts

@@ -0,0 +1,10 @@
+export interface BlockSummaryProps {
+    /** The block's field that names it, if it has one. Injected by the generator via `clientProps`. */
+    fields: string[];
+    /** The block's label, as the picker shows it — "Collage Hero". */
+    singular: string;
+    /** The block's slug, for Payload's per-block pill class. */
+    slug: string;
+}
+export declare function BlockSummary({ fields, singular, slug }: BlockSummaryProps): import("react").JSX.Element;
+//# sourceMappingURL=BlockSummary.d.ts.map

package/dist/admin/BlockSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockSummary.d.ts","sourceRoot":"","sources":["../../src/admin/BlockSummary.tsx"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,mGAAmG;IACnG,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;CACb;AAwDD,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,iBAAiB,+BAgDzE"}

package/dist/admin/BlockSummary.js

@@ -0,0 +1,73 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Pill, useForm, useRowLabel, useTranslation } from '@payloadcms/ui';
+import { summaryText } from './summary.js';
+/**
+ * The header of a generated block — Payload's own, with a better placeholder.
+ *
+ * Payload draws a block's header as its number, a pill naming the block type,
+ * and an input for the optional `blockName` whose placeholder is "Untitled".
+ * Nobody types a block name, so a collapsed page read "01 Collage Hero
+ * Untitled, 02 Logos Untitled, 03 Statement Section Untitled…", and finding the
+ * section about pricing meant opening each block in turn.
+ *
+ * So this is the same number and pill, with the same classes, followed by what
+ * the block holds: its heading as the author is typing it. A block with no text
+ * of its own (a carousel, a pair of images) reads "Untitled", as before.
+ *
+ * A name somebody did type — the importer writes one for a form it could not
+ * convert — still wins, in Payload's own editable input. An unnamed block shows
+ * its summary as text rather than as the input's placeholder, because the input
+ * is sized to what it shows and would then cover the header: a click meant to
+ * open the block would start editing a name instead. The trade is that a name
+ * can no longer be added to a block that has none, which the summary is what
+ * makes unnecessary.
+ *
+ * Neither the name nor the form is read through `useField`. Inside a custom
+ * block label it sent the edit view into a render loop that pinned the server
+ * and never painted; the row's data is already in hand from `useRowLabel`,
+ * and an edit is one `dispatchFields`.
+ *
+ * A custom block label replaces Payload's whole header rather than the part of
+ * it after the pill, which is why the number and the pill are redrawn here.
+ * Returned as a fragment so they stay direct children of Payload's
+ * `blocks-field__block-header`, which spaces them.
+ */
+/*
+One line, whatever the heading.
+
+Payload's header is a flex row whose items stretch to the tallest, so a
+heading that wrapped to three lines made the block pill three lines tall and
+the collapsed page a column of uneven boxes — the list this header exists to
+make scannable. So nothing here stretches, and the summary is a single line
+that ends in an ellipsis where it runs out of room. The row opens on a click
+anywhere on it, which shows the whole heading.
+*/
+const CENTRED = { alignSelf: 'center' };
+const SUMMARY = {
+    ...CENTRED,
+    color: 'var(--theme-elevation-500)',
+    pointerEvents: 'none',
+    flex: '1 1 auto',
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+};
+export function BlockSummary({ fields, singular, slug }) {
+    const { data, path, rowNumber } = useRowLabel();
+    const { t } = useTranslation();
+    const { dispatchFields, setModified } = useForm();
+    const namePath = `${path}.blockName`;
+    const name = typeof data?.blockName === 'string' ? data.blockName : '';
+    const summary = summaryText(data, fields) || t('general:untitled');
+    return (_jsxs(_Fragment, { children: [_jsx("span", { className: "blocks-field__block-number", style: CENTRED, children: String((rowNumber ?? 0) + 1).padStart(2, '0') }), _jsx("span", { style: { ...CENTRED, display: 'flex', flexShrink: 0 }, children: _jsx(Pill, { className: `blocks-field__block-pill blocks-field__block-pill-${slug}`, pillStyle: "white", size: "small", children: singular }) }), name ? (
+            // `data-value` is what sizes the input — see Payload's SectionTitle.
+            _jsx("div", { className: "section-title", "data-value": name, children: _jsx("input", { "aria-label": `Name for ${singular} block`, className: "section-title__input", id: namePath, name: namePath, onChange: event => {
+                        event.stopPropagation();
+                        event.preventDefault();
+                        dispatchFields({ type: 'UPDATE', path: namePath, value: event.target.value });
+                        setModified(true);
+                    }, type: "text", value: name }) })) : (_jsx("span", { className: "row-label", style: SUMMARY, children: summary }))] }));
+}
+//# sourceMappingURL=BlockSummary.js.map

package/dist/admin/BlockSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockSummary.js","sourceRoot":"","sources":["../../src/admin/BlockSummary.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AAEZ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAW1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;;;;;;;;;EASE;AACF,MAAM,OAAO,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAW,CAAA;AAEhD,MAAM,OAAO,GAAG;IACd,GAAG,OAAO;IACV,KAAK,EAAE,4BAA4B;IACnC,aAAa,EAAE,MAAM;IACrB,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,QAAQ;IAClB,YAAY,EAAE,UAAU;IACxB,UAAU,EAAE,QAAQ;CACZ,CAAA;AAEV,MAAM,UAAU,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAqB;IACxE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,WAAW,EAA2B,CAAA;IACxE,MAAM,EAAE,CAAC,EAAE,GAAG,cAAc,EAAE,CAAA;IAC9B,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAA;IACjD,MAAM,QAAQ,GAAG,GAAG,IAAI,YAAY,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,IAAI,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA;IACtE,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,kBAAkB,CAAC,CAAA;IAElE,OAAO,CACL,8BACE,eAAM,SAAS,EAAC,4BAA4B,EAAC,KAAK,EAAE,OAAO,YACxD,MAAM,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GACzC,EAEP,eAAM,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,YACzD,KAAC,IAAI,IACH,SAAS,EAAE,qDAAqD,IAAI,EAAE,EACtE,SAAS,EAAC,OAAO,EACjB,IAAI,EAAC,OAAO,YAEX,QAAQ,GACJ,GACF,EACN,IAAI,CAAC,CAAC,CAAC;YACN,qEAAqE;YACrE,cAAK,SAAS,EAAC,eAAe,gBAAa,IAAI,YAC7C,8BACc,YAAY,QAAQ,QAAQ,EACxC,SAAS,EAAC,sBAAsB,EAChC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,KAAK,CAAC,EAAE;wBAChB,KAAK,CAAC,eAAe,EAAE,CAAA;wBACvB,KAAK,CAAC,cAAc,EAAE,CAAA;wBACtB,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;wBAC7E,WAAW,CAAC,IAAI,CAAC,CAAA;oBACnB,CAAC,EACD,IAAI,EAAC,MAAM,EACX,KAAK,EAAE,IAAI,GACX,GACE,CACP,CAAC,CAAC,CAAC,CACF,eAAM,SAAS,EAAC,WAAW,EAAC,KAAK,EAAE,OAAO,YACvC,OAAO,GACH,CACR,IACA,CACJ,CAAA;AACH,CAAC"}

package/dist/admin/RowSummary.d.ts

@@ -0,0 +1,15 @@
+export interface RowSummaryProps {
+    /** The row's fields to show, in order. Injected by the generator via `clientProps`. */
+    fields: string[];
+    /** Payload's singular label for the array, for a row with nothing typed yet. */
+    singular: string;
+}
+/**
+ * The header of a generated array row — see `./summary.ts`.
+ *
+ * Reads the row from the form rather than from saved data, so the header
+ * follows what the author is typing. The class and the `pointer-events` are
+ * Payload's own fallback label's, so a click on the text still toggles the row.
+ */
+export declare function RowSummary({ fields, singular }: RowSummaryProps): import("react").JSX.Element;
+//# sourceMappingURL=RowSummary.d.ts.map

package/dist/admin/RowSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RowSummary.d.ts","sourceRoot":"","sources":["../../src/admin/RowSummary.tsx"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,eAAe,+BAO/D"}

package/dist/admin/RowSummary.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRowLabel } from '@payloadcms/ui';
+import { rowSummary } from './summary.js';
+/**
+ * The header of a generated array row — see `./summary.ts`.
+ *
+ * Reads the row from the form rather than from saved data, so the header
+ * follows what the author is typing. The class and the `pointer-events` are
+ * Payload's own fallback label's, so a click on the text still toggles the row.
+ */
+export function RowSummary({ fields, singular }) {
+    const { data, rowNumber } = useRowLabel();
+    return (_jsx("span", { className: "row-label", style: { pointerEvents: 'none' }, children: rowSummary(data, fields, singular, rowNumber) }));
+}
+//# sourceMappingURL=RowSummary.js.map

package/dist/admin/RowSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RowSummary.js","sourceRoot":"","sources":["../../src/admin/RowSummary.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AAEZ,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AASzC;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAmB;IAC9D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,WAAW,EAA2B,CAAA;IAClE,OAAO,CACL,eAAM,SAAS,EAAC,WAAW,EAAC,KAAK,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,YACzD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,GACzC,CACR,CAAA;AACH,CAAC"}

package/dist/admin/summary.d.ts

@@ -0,0 +1,18 @@
+/** How much of a row's text its header shows before it gives up. */
+export declare const SUMMARY_MAX = 80;
+/**
+ * The header for one row: its summary fields' text, or Payload's own
+ * "Stat 03" while the row is still empty.
+ *
+ * `rowIndex` is zero-based, as Payload's row-label context hands it over.
+ */
+export declare function rowSummary(data: unknown, fields: readonly string[], singular: string, rowIndex: number | undefined): string;
+/**
+ * The named fields' text, joined on one line and cut to a header's length —
+ * or `''` when none of them holds any.
+ *
+ * `rowSummary` falls back to a counter; a block header already has one, and
+ * falls back to Payload's "Untitled" instead. See `./BlockSummary.tsx`.
+ */
+export declare function summaryText(data: unknown, fields: readonly string[]): string;
+//# sourceMappingURL=summary.d.ts.map

package/dist/admin/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../src/admin/summary.ts"],"names":[],"mappings":"AAcA,oEAAoE;AACpE,eAAO,MAAM,WAAW,KAAK,CAAA;AAI7B;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CAOR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAS5E"}

package/dist/admin/summary.js

@@ -0,0 +1,48 @@
+/*
+What a collapsed array row says about itself.
+
+Payload's own row header is the array's name and a counter — "Stat 01",
+"Stat 02", "Stat 03" — which is true of every row and tells an author nothing
+about any of them. With six stats collapsed, finding the one that says "96%"
+means opening them in turn, and reordering them means doing it blind. So a
+generated array names its rows by what they hold: the first one or two short
+text fields of the row, joined, as the author typed them.
+
+Pure, and apart from the component that draws it, so the rule can be tested
+without React or a form.
+*/
+/** How much of a row's text its header shows before it gives up. */
+export const SUMMARY_MAX = 80;
+const SEPARATOR = ' · ';
+/**
+ * The header for one row: its summary fields' text, or Payload's own
+ * "Stat 03" while the row is still empty.
+ *
+ * `rowIndex` is zero-based, as Payload's row-label context hands it over.
+ */
+export function rowSummary(data, fields, singular, rowIndex) {
+    const text = summaryText(data, fields);
+    if (text === '') {
+        const number = rowIndex === undefined ? '' : ` ${String(rowIndex + 1).padStart(2, '0')}`;
+        return `${singular}${number}`;
+    }
+    return text;
+}
+/**
+ * The named fields' text, joined on one line and cut to a header's length —
+ * or `''` when none of them holds any.
+ *
+ * `rowSummary` falls back to a counter; a block header already has one, and
+ * falls back to Payload's "Untitled" instead. See `./BlockSummary.tsx`.
+ */
+export function summaryText(data, fields) {
+    const row = (data ?? {});
+    const text = fields
+        .map(name => row[name])
+        .filter((value) => typeof value === 'string')
+        .map(value => value.replace(/\s+/g, ' ').trim())
+        .filter(Boolean)
+        .join(SEPARATOR);
+    return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1).trimEnd()}…` : text;
+}
+//# sourceMappingURL=summary.js.map

package/dist/admin/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/admin/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAEF,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAA;AAE7B,MAAM,SAAS,GAAG,KAAK,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,IAAa,EACb,MAAyB,EACzB,QAAgB,EAChB,QAA4B;IAE5B,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACtC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;QACxF,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAA;IAC/B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,MAAyB;IAClE,MAAM,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAA;IACnD,MAAM,IAAI,GAAG,MAAM;SAChB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SACtB,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;SAC7D,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;SAC/C,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,SAAS,CAAC,CAAA;IAClB,OAAO,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1F,CAAC"}

package/dist/altText.d.ts

@@ -0,0 +1,16 @@
+import type { ContentField } from './generate/fields.js';
+/** The name of the field that carries an image field's alt text. */
+export declare function altFieldFor(imageField: string): string;
+/** Image field name → alt field name, for every image among `siblings` that has one. */
+export declare function pairedAltFields(siblings: readonly ContentField[]): Map<string, string>;
+/** Told to the author beside every alt field that falls back. */
+export declare const ALT_FALLBACK_NOTE = "Leave empty to use the alt text from the media library.";
+/**
+ * `siblings`, with every paired alt field made optional and saying why.
+ *
+ * Optional because a required alt would make the author type the fallback by
+ * hand, which is the duplication this exists to remove. Nothing is lost: the
+ * media collection already refuses an image without alt.
+ */
+export declare function withAltFallback(siblings: readonly ContentField[]): ContentField[];
+//# sourceMappingURL=altText.d.ts.map

package/dist/altText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"altText.d.ts","sourceRoot":"","sources":["../src/altText.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAkBxD,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAStF;AAED,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,4DAA4D,CAAA;AAE1F;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE,CAajF"}

package/dist/altText.js

@@ -0,0 +1,54 @@
+/*
+An image's alt text, beside the image, falls back to the media library's.
+
+The media collection asks for alt at upload, where the person who chose the
+image is still looking at it. A block that holds that image used to ask again,
+and render only what it was told — so the same description was typed twice,
+or not at all and the image went out as decorative. Now the block's own alt is
+an override: left empty, the media document's alt is used.
+
+Pairing is by name, the same convention `responsiveProps` in `render/coerce.ts`
+relies on: an image prop `image` has its alt in `imageAlt`, except where the
+image prop is `src` inside an `ImageRef` group or row, whose alt is the bare
+`alt` of the HTML attribute. Only siblings pair — the image and its alt have to
+sit in the same block, group or array row.
+*/
+/** The name of the field that carries an image field's alt text. */
+export function altFieldFor(imageField) {
+    return imageField === 'src' ? 'alt' : `${imageField}Alt`;
+}
+/** Image field name → alt field name, for every image among `siblings` that has one. */
+export function pairedAltFields(siblings) {
+    const names = new Set(siblings.map(field => field.name));
+    const pairs = new Map();
+    for (const field of siblings) {
+        if (field.type !== 'image')
+            continue;
+        const alt = altFieldFor(field.name);
+        if (names.has(alt))
+            pairs.set(field.name, alt);
+    }
+    return pairs;
+}
+/** Told to the author beside every alt field that falls back. */
+export const ALT_FALLBACK_NOTE = 'Leave empty to use the alt text from the media library.';
+/**
+ * `siblings`, with every paired alt field made optional and saying why.
+ *
+ * Optional because a required alt would make the author type the fallback by
+ * hand, which is the duplication this exists to remove. Nothing is lost: the
+ * media collection already refuses an image without alt.
+ */
+export function withAltFallback(siblings) {
+    const alts = new Set(pairedAltFields(siblings).values());
+    return siblings.map(field => alts.has(field.name)
+        ? {
+            ...field,
+            required: false,
+            constraints: field.constraints
+                ? `${field.constraints} ${ALT_FALLBACK_NOTE}`
+                : ALT_FALLBACK_NOTE,
+        }
+        : field);
+}
+//# sourceMappingURL=altText.js.map