@bison-lab/payload-core 3.7.0 → 3.9.0

package/README.md

@@ -13,17 +13,20 @@ pnpm add @bison-lab/payload-core @payloadcms/plugin-seo @bison-lab/tokens @bison
 
 Peers: `payload` and `@payloadcms/plugin-seo` are required. `@bison-lab/tokens`
 and `@bison-lab/fonts` are needed to adopt the Theme Global; `@payloadcms/ui`
-and `react` are needed for its admin fields. Pin the plugin to the same
-version as `payload`; Payload releases them in lockstep.
+and `react` are needed for its admin fields; `@bison-lab/ui` and
+`@payloadcms/live-preview-react` are needed for the live theme preview.
+Pin the plugin to the same version as `payload`; Payload releases them in
+lockstep.
 
-## Four entry points, and why
+## Five entry points, and why
 
 | Import                             | Contents                                                                                         | Runs where                                                                 |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `@bison-lab/payload-core`          | `seoPlugin`, `createTheme`, `seedTheme`, import-map strings, title and text helpers, types       | Node. What `payload.config.ts` imports; it loads the plugin.               |
+| `@bison-lab/payload-core`          | `seoPlugin`, `createTheme`, `createBrandAssets`, `seedTheme`, import-map strings, title and text helpers, types | Node. What `payload.config.ts` imports; it loads the plugin. |
 | `@bison-lab/payload-core/metadata` | `pageMetadata`, the title helpers, the same types                                                | Server. What a page route imports; it does not load the plugin.            |
-| `@bison-lab/payload-core/theme`    | `getPublishedTheme`, `themeConfigFromDoc`, `themeHead`                                           | Server. What a root layout imports; it does not load the plugin or React.  |
-| `@bison-lab/payload-core/admin`    | `ColorField`, `FontField`, `ContrastReport`                                                      | Admin. Referenced by import-map string; `generate:importmap` writes it.    |
+| `@bison-lab/payload-core/theme`    | `getPublishedTheme`, `getPublishedIdentity`, `themeConfigFromDoc`, `themeHead`                    | Server. What a root layout imports; it does not load the plugin or React.  |
+| `@bison-lab/payload-core/admin`    | Theme child fields (color scale, library, gray family, fonts, appearance, publish)               | Admin. Referenced by import-map string; `generate:importmap` writes it.    |
+| `@bison-lab/payload-core/react`    | `ThemePreview` (legacy; Theme has no preview pane)                                               | Client. Kept so an older site import does not break.                       |
 
 ## What editors get
 
@@ -122,11 +125,12 @@ The sitemap is the site's: filter `meta.noIndex` out of it.
 
 ## Adopting the Theme global
 
-Settings → Theme: the five brand colours, grey scale, radius, shadow, motion,
-density, default theme, body and heading fonts, and an optional logo. Whoever
-holds brand rights edits a draft; publish is deliberate. Contrast is measured
-as they type and shown; it is never enforced. `bison.config.json` is the seed
-a site starts from, not the source of truth.
+Settings → Theme children: Colors, Typography, Appearance, and Identity. Each
+child has its own Publish — publishing Colors updates colors only. Theme has
+no draft mode and no preview pane. Contrast is the automatic label on editable
+fills at 7:1; it is never enforced. `bison.config.json` is the seed a site
+starts from, not the source of truth. Pass `destructive` (or
+`seed.brandDestructive`); there is no package default.
 
 **1. Register the Global.** Access is required — the predicates live in the
 site's `src/platform` until they move here. Pass `canManageBrand` as
@@ -134,16 +138,27 @@ site's `src/platform` until they move here. Pass `canManageBrand` as
 
 ```ts
 // payload.config.ts
-import { createTheme } from "@bison-lab/payload-core";
+import { BRAND_ASSETS_SLUG, createBrandAssets, createTheme } from "@bison-lab/payload-core";
 import bisonConfig from "../bison.config.json";
 import { canManageBrand, isAuthenticated } from "@/platform/access";
 
 export default buildConfig({
+  collections: [
+    createBrandAssets({
+      access: { read: () => true, update: canManageBrand },
+    }),
+  ],
   globals: [
     createTheme({
       access: { read: isAuthenticated, update: canManageBrand },
       seed: bisonConfig,
-      logo: { collection: "brand-assets" },
+      logo: { collection: BRAND_ASSETS_SLUG },
+      identity: {
+        fallback: {
+          lockup: { url: "/logo-lockup.svg", alt: "Acme" },
+          mark: { url: "/logo-mark.svg", alt: "Acme mark" },
+        },
+      },
       onPublish: async () => {
         revalidateTag("theme");
       },
@@ -152,8 +167,8 @@ export default buildConfig({
 });
 ```
 
-Then `payload generate:importmap` (the colour, font and contrast fields
-resolve from `@bison-lab/payload-core/admin`), `payload generate:types`, and
+Then `payload generate:importmap` (the Theme child fields resolve from
+`@bison-lab/payload-core/admin`), `payload generate:types`, and
 `payload migrate:create`.
 
 **2. Seed the row on deploy.** A migration `up()` writes a published version
@@ -177,20 +192,39 @@ you pass as `fontsBaseUrl` (default `/fonts`).
 
 ```ts
 // app/layout.tsx
-import { getPublishedTheme, themeHead } from "@bison-lab/payload-core/theme";
+import { getPublishedIdentity, getPublishedTheme, themeHead } from "@bison-lab/payload-core/theme";
 import bisonConfig from "../bison.config.json";
 
 const theme = await getPublishedTheme(payload, bisonConfig);
-const { css, preloads } = themeHead(theme);
+const identity = await getPublishedIdentity(payload, {
+  lockup: { url: "/logo-lockup.svg", alt: "Acme" },
+  mark: { url: "/logo-mark.svg", alt: "Acme mark" },
+});
+const { css, preloads } = themeHead(theme, { identity });
 
 // <link rel="preload" as="font" type="font/woff2" crossOrigin="" href={href} />
 // <style dangerouslySetInnerHTML={{ __html: css }} />
+// identity.lockup / identity.mark / identity.favicon — uploaded file or the fallback
 ```
 
 If the admin layout renders the same head, the admin panel restyles too.
 
-`getPublishedTheme` reads `draft: false` and falls back to the seed when
-nothing has been published. A newer draft never reaches the public site.
+`getPublishedTheme` reads the live row and falls back to the seed when
+the Global is empty. Empty logo, favicon, and mobile-menu mark use the
+fallback the site passed into `createTheme`. There is no Theme preview pane.
+
+## Brand assets
+
+Logo, favicon, and mobile-menu mark live in a locked cupboard, not in
+ordinary Media. Call `createBrandAssets` and point Theme at
+`BRAND_ASSETS_SLUG`. Access is the same shape as `createTheme`: `read` is
+typically public so the live site can load the file; `update` is
+`canManageBrand` and covers create, update, delete, and version history.
+SVG preferred, PNG and ICO allowed; an SVG is sanitized on upload.
+Versions stay on so a replaced file can be rolled back.
+
+Each row carries a label, usage notes, and required alt text so a logo
+has its accessible name. Then `payload migrate:create`.
 
 ## No generated types
 
@@ -202,6 +236,7 @@ to a type that has one.
 
 ## Changing a field
 
-`noIndexField`, the plugin's own fields, and the Theme Global fields are
-columns in every consuming site. A change to them is a schema change: say
-"run `payload migrate:create`" in the changeset.
+`noIndexField`, the plugin's own fields, the Theme Global fields, and the
+brand-assets collection fields are columns in every consuming site. A
+change to them is a schema change: say "run `payload migrate:create`" in
+the changeset.

package/dist/admin.d.mts

@@ -1,5 +1,5 @@
 
-import { SelectFieldClientComponent, TextFieldClientComponent, UIFieldClientComponent } from "payload";
+import { ArrayFieldClientComponent, GroupFieldClientComponent, SelectFieldClientComponent, TextFieldClientComponent, UIFieldClientComponent } from "payload";
 
 //#region src/admin/color-field.d.ts
 /**
@@ -8,21 +8,77 @@ import { SelectFieldClientComponent, TextFieldClientComponent, UIFieldClientComp
  */
 declare const ColorField: TextFieldClientComponent;
 //#endregion
+//#region src/admin/color-scale-field.d.ts
+/**
+ * One system (or library row) color: hex, source step, regenerate, stale,
+ * include/exclude, automatic label. Writes the group's stored fields.
+ */
+declare const ColorScaleField: GroupFieldClientComponent;
+//#endregion
+//#region src/admin/library-field.d.ts
+/**
+ * Custom colors: the same scale controls as system colors, plus add and
+ * in-use delete (one replacement scale; unused rows delete immediately).
+ */
+declare const LibraryField: ArrayFieldClientComponent;
+//#endregion
 //#region src/admin/font-field.d.ts
 /**
  * Listbox over the catalogue ids in `admin.custom.ids`. Each option is the
  * family name in that face, with the catalogue hint beneath. Faces load
- * from the site's font route the first time the picker opens.
+ * from the site's font route for the selected family, and for every
+ * catalogue id once the picker opens.
  */
 declare const FontField: SelectFieldClientComponent;
 //#endregion
+//#region src/admin/pairing-field.d.ts
+/**
+ * Pairing sample only — no weight, letter-spacing, line-height, or health
+ * scores. Faces load from the site's font route.
+ */
+declare const PairingField: UIFieldClientComponent;
+//#endregion
+//#region src/admin/appearance-field.d.ts
+/**
+ * Named appearance choices. Soft → pill, Gentle → minimal, Balanced →
+ * default, Follow device → system. No rem or ms.
+ */
+declare const AppearanceField: GroupFieldClientComponent;
+//#endregion
+//#region src/admin/grey-scale-field.d.ts
+/**
+ * Visual picker over the five grey-scale presets. Replaces the stock select
+ * on Colors; the stored value is still `colors.greyScale`.
+ */
+declare const GreyScaleField: SelectFieldClientComponent;
+//#endregion
 //#region src/admin/contrast-report.d.ts
 /**
- * Reads the five brand colours and grey scale from the form, runs
- * `auditTheme` client-side, and paints its own rows. Warn only: nothing
- * here touches validity.
+ * Fill + automatic label only. Target 7:1, Light and Dark. No gray
+ * ContrastStrip. Warnings do not block save.
  */
 declare const ContrastReport: UIFieldClientComponent;
 //#endregion
-export { ColorField, ContrastReport, FontField };
+//#region src/admin/section-heading.d.ts
+/**
+ * Unnamed UI heading between Theme fields. No document path.
+ */
+declare const SectionHeading: UIFieldClientComponent;
+//#endregion
+//#region src/admin/publish-child.d.ts
+/**
+ * Per-child Publish. Sets `publishChild` then submits; `beforeChange`
+ * writes only that slice. Confirmation lists this child's changes and,
+ * on Colors, remaining automatic-label shorts.
+ */
+declare const PublishChild: UIFieldClientComponent;
+//#endregion
+//#region src/admin/save-button.d.ts
+/**
+ * Theme children publish themselves. The stock Save would write every
+ * dirty tab at once, so it is hidden.
+ */
+declare function HiddenSaveButton(): null;
+//#endregion
+export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, LibraryField, PairingField, PublishChild, SectionHeading };
 //# sourceMappingURL=admin.d.mts.map

package/dist/admin.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"admin.d.mts","names":[],"sources":["../src/admin/color-field.tsx","../src/admin/font-field.tsx","../src/admin/contrast-report.tsx"],"mappings":";;;;;;AAWA;;cAAa,UAAA,EAAY,wBAAA;;;;;AAAzB;;;cCGa,SAAA,EAAW,0BAAA;;;;;ADHxB;;;cEqEa,cAAA,EAAgB,sBAAA"}
+{"version":3,"file":"admin.d.mts","names":[],"sources":["../src/admin/color-field.tsx","../src/admin/color-scale-field.tsx","../src/admin/library-field.tsx","../src/admin/font-field.tsx","../src/admin/pairing-field.tsx","../src/admin/appearance-field.tsx","../src/admin/grey-scale-field.tsx","../src/admin/contrast-report.tsx","../src/admin/section-heading.tsx","../src/admin/publish-child.tsx","../src/admin/save-button.tsx"],"mappings":";;;;;;;;cAWa,UAAA,EAAY,wBAAA;;;;;;;cCGZ,eAAA,EAAiB,yBAAA;;;;;;;cCQjB,YAAA,EAAc,yBAAA;;;;;;;AFX3B;;cGMa,SAAA,EAAW,0BAAA;;;;;;;cCNX,YAAA,EAAc,sBAAA;;;;;;;cCCd,eAAA,EAAiB,yBAAA;;;;;;;cCiDjB,cAAA,EAAgB,0BAAA;;;;;;;cC1ChB,cAAA,EAAgB,sBAAA;;;;;;cCdhB,cAAA,EAAgB,sBAAA;;;;;;;ARM7B;cS0Ea,YAAA,EAAc,sBAAA;;;;;;;iBCjFX,gBAAA,CAAA"}