@bison-lab/payload-core 3.10.0 → 3.12.0

package/README.md

@@ -1,9 +1,9 @@
 # `@bison-lab/payload-core`
 
 Site-agnostic Payload CMS configuration for Bison Lab sites: the SEO tab on
-a collection, the Theme Global, and the readers a page route and a root
-layout use. The rest of the shared CMS layer (access matrix, collection
-factories, slug field) joins it here as it is extracted.
+a collection, the Theme Global, the Roles Global, and the readers a page
+route and a root layout use. Collection factories join it here as they
+are extracted.
 
 Full guide: <https://payload.bisonlab.ai/site/seo/>
 
@@ -22,10 +22,10 @@ lockstep.
 
 | Import                             | Contents                                                                                         | Runs where                                                                 |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `@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`          | `seoPlugin`, `createTheme`, `createBrandAssets`, `createRoles`, `createPages`, `createUsers`, `createMedia`, `adminOnlyApiTab`, `seedTheme`, `seedRoles`, predicates, `lookField`, `colorTokenField`, 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`, `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/theme`    | `getPublishedTheme`, `getPublishedIdentity`, `themeConfigFromDoc`, `themeHead`, `themeHeadFromDoc` | Server. What a root layout imports; it does not load the plugin or React.  |
+| `@bison-lab/payload-core/admin`    | Theme child fields, the Roles matrix field, and the Users Roles checklist                        | 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
@@ -125,22 +125,32 @@ The sitemap is the site's: filter `meta.noIndex` out of it.
 
 ## Adopting the Theme global
 
-Settings → Theme is one Global with field tabs: Colors, Typography, Appearance,
-and Identity. Publish in the document Save slot writes the open tab 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
-`update`.
+Theme in the admin nav is a group like Content and Settings: Colors,
+Typography, Appearance, and Identity. Those are ordinary Payload Globals
+(`admin.group: "Theme"`), not custom views. `createTheme` returns them plus
+a hidden store (`theme`) that `getPublishedTheme` already reads. Save on a
+page is Payload's Save; it writes that slice onto the store. Document
+locking is off — these are settings forms. Theme has no draft mode and
+no preview pane. Contrast is the automatic label on editable fills at 7:1; it
+is never enforced and lives in the Needs-attention modal, not on the page.
+`bison.config.json` is the seed a site starts from, not the source of truth.
+Pass `destructive` (or `seed.brandDestructive`); otherwise Theme uses the
+library’s `DESTRUCTIVE_SCALE_HEX` (`#ef4444`). Success falls back to `#22c55e`.
+
+**1. Register the Global.** Access is required — Theme does not read the
+Roles Global. Pass `canManageBrand` as `update`.
 
 ```ts
 // payload.config.ts
-import { BRAND_ASSETS_SLUG, createBrandAssets, createTheme } from "@bison-lab/payload-core";
+import {
+  BRAND_ASSETS_SLUG,
+  canManageBrand,
+  createBrandAssets,
+  createRoles,
+  createTheme,
+  isAuthenticated,
+} from "@bison-lab/payload-core";
 import bisonConfig from "../bison.config.json";
-import { canManageBrand, isAuthenticated } from "@/platform/access";
 
 export default buildConfig({
   collections: [
@@ -149,7 +159,8 @@ export default buildConfig({
     }),
   ],
   globals: [
-    createTheme({
+    createRoles(),
+    ...createTheme({
       access: { read: isAuthenticated, update: canManageBrand },
       seed: bisonConfig,
       logo: { collection: BRAND_ASSETS_SLUG },
@@ -176,11 +187,12 @@ so the site renders what `bison-theme.css` rendered before anyone opens the
 admin:
 
 ```ts
-import { seedTheme } from "@bison-lab/payload-core";
+import { seedRoles, seedTheme } from "@bison-lab/payload-core";
 import bisonConfig from "../bison.config.json";
 
 export async function up({ payload }) {
   await seedTheme(payload, bisonConfig);
+  await seedRoles(payload);
 }
 ```
 
@@ -201,6 +213,8 @@ const identity = await getPublishedIdentity(payload, {
   mark: { url: "/logo-mark.svg", alt: "Acme mark" },
 });
 const { css, preloads } = themeHead(theme, { identity });
+// Custom Colors need the Theme document: themeHeadFromDoc(doc, bisonConfig, { identity })
+// emits --coral-* and [data-look] so lookField keys paint.
 
 // <link rel="preload" as="font" type="font/woff2" crossOrigin="" href={href} />
 // <style dangerouslySetInnerHTML={{ __html: css }} />
@@ -226,17 +240,35 @@ 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`.
 
+## Roles
+
+Settings → Roles is an Admin-editable array. Rank is drag-to-reorder.
+Ticks are Content, Brand, Publish, and Users. The API tab is locked to
+Developer — it is not a column. Defaults ship in the package (Brand on
+Designer only; Admin + Designer both store; Developer is exclusive).
+`canManageBrand` and the other predicates read the saved Global and fall
+back to that seed. The package never writes `developer` onto a user row.
+
+## Pages, users, and media
+
+`createPages`, `createUsers`, `createMedia`, `slugField`, and
+`adminOnlyApiTab` ship from the same React-free entry. Pages take the
+site's hero and layout blocks, reserved-slug predicate, and preview
+path. Users take `secureCookies`; the Roles checklist reads the Global
+(or the seed) and has no second ORDER / WHAT list. `adminOnlyApiTab`
+shows the document API tab only to Developer.
+
 ## No generated types
 
 The package cannot import a site's `payload-types`, so the shapes it reads
-(`SeoMeta`, `SeoImageDoc`, `SeoPage`, `ThemeDoc`) are hand-written and
+(`SeoMeta`, `SeoImageDoc`, `SeoPage`, `ThemeDoc`, `RolesDoc`) are hand-written and
 structural. A generated `Page`, `Media` or Theme Global is assignable to
 them; nothing carries an index signature, since an interface will not assign
 to a type that has one.
 
 ## Changing a field
 
-`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.
+`noIndexField`, the plugin's own fields, the Theme Global fields, the
+Roles 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

@@ -12,15 +12,17 @@ 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.
+ * One system (or library row) color: hex, source step, include/exclude.
+ * Writes the group's stored fields. A committed hex or step rebuilds the scale.
  */
 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).
+ * Custom colors: the same scale controls as system colors. A row that is
+ * not referenced on a page deletes immediately. Rewriting in-use tokens
+ * (`rewriteColorToken`) waits on a site usage lookup — Theme cannot see
+ * page assignments by itself.
  */
 declare const LibraryField: ArrayFieldClientComponent;
 //#endregion
@@ -56,9 +58,8 @@ declare const GreyScaleField: SelectFieldClientComponent;
 //#endregion
 //#region src/admin/contrast-report.d.ts
 /**
- * Contrast used to be a Colors-tab list. Readability now lives on each
- * color card: Needs attention opens a popup. This field stays in the
- * schema so `contrastTarget` is still a Theme option; it paints nothing.
+ * Fill + automatic label only. Target 7:1, Light and Dark. No gray
+ * ContrastStrip. Warnings do not block save.
  */
 declare const ContrastReport: UIFieldClientComponent;
 //#endregion
@@ -69,18 +70,22 @@ declare const ContrastReport: UIFieldClientComponent;
 declare const SectionHeading: UIFieldClientComponent;
 //#endregion
 //#region src/admin/publish-child.d.ts
-/** @deprecated Theme publish is the document Save button */
 declare const PublishChild: UIFieldClientComponent;
 //#endregion
 //#region src/admin/save-button.d.ts
 /**
- * Payload's document Save slot — the same control row as Pages'
- * "Publish changes". Theme has no drafts; this publishes only the
- * open field tab. The tab is read after mount so SSR matches.
+ * Light/Dark preview for Colors, Typography, and Appearance. Lives in
+ * `beforeDocumentControls` so Payload's Save stays in the Save slot.
+ * Save writes that page's slice onto the stored Theme row.
+ */
+declare function ThemeDocumentControls(): react_jsx_runtime0.JSX.Element;
+/**
+ * Import-map Save slot used by the older single-Global Theme. Theme pages
+ * keep Payload's Save and put Light/Dark in `ThemeDocumentControls`.
  */
 declare function ThemeSaveButton(): react_jsx_runtime0.JSX.Element;
-/** Import-map alias — Theme still points `SaveButton` at this name. */
-declare const HiddenSaveButton: typeof ThemeSaveButton;
+/** @deprecated Import map alias — ThemeDocumentControls is the Save-adjacent slot. */
+declare function HiddenSaveButton(): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/admin/identity-fallback.d.ts
 /**
@@ -89,5 +94,27 @@ declare const HiddenSaveButton: typeof ThemeSaveButton;
  */
 declare const IdentityFallback: UIFieldClientComponent;
 //#endregion
-export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, PairingField, PublishChild, SectionHeading, ThemeSaveButton };
+//#region src/admin/look-field.d.ts
+/**
+ * Loads the Theme global and offers page-editor looks or included steps.
+ * A custom scale published on Colors appears here on the next load.
+ */
+declare const LookField: TextFieldClientComponent;
+//#endregion
+//#region src/admin/roles-matrix-field.d.ts
+/**
+ * Payload's array field: drag rank stays, add/remove go away. Reset writes
+ * the package seed back onto the field.
+ */
+declare const RolesMatrixField: ArrayFieldClientComponent;
+//#endregion
+//#region src/admin/roles-field.d.ts
+/**
+ * Users Roles checklist. Order and labels come from the field options (the
+ * Roles Global, or the seed). Copy is `roleDescription`. Developer is
+ * exclusive; Admin does not swallow Designer.
+ */
+declare const RolesField: SelectFieldClientComponent;
+//#endregion
+export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, RolesField, RolesMatrixField, SectionHeading, ThemeDocumentControls, ThemeSaveButton };
 //# 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/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","../src/admin/identity-fallback.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;;;;;;;;cCtDhB,cAAA,EAAgB,sBAAA;;;;;;cCFhB,cAAA,EAAgB,sBAAA;;;;cCmIhB,YAAA,EAAc,sBAAA;;;;;;;;iBC7HX,eAAA,CAAA,GAAe,kBAAA,CAAA,GAAA,CAAA,OAAA;AVA/B;AAAA,cU0Ba,gBAAA,SAAgB,eAAA;;;;;;;cC7BhB,gBAAA,EAAkB,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","../src/admin/identity-fallback.tsx","../src/admin/look-field.tsx","../src/admin/roles-matrix-field.tsx","../src/admin/roles-field.tsx"],"mappings":";;;;;;;;;;cAWa,UAAA,EAAY,wBAAA;;;;;;;cCsBZ,eAAA,EAAiB,yBAAA;;;;;;;;ADtB9B;cEca,YAAA,EAAc,yBAAA;;;;;;;;AFd3B;cGOa,SAAA,EAAW,0BAAA;;;;;;;cCNX,YAAA,EAAc,sBAAA;;;;;;;cCCd,eAAA,EAAiB,yBAAA;;;;;;;cCuDjB,cAAA,EAAgB,0BAAA;;;;;;;cChDhB,cAAA,EAAgB,sBAAA;;;;;;cCbhB,cAAA,EAAgB,sBAAA;;;cCgJhB,YAAA,EAAc,sBAAA;;;;;;;;iBC3IX,qBAAA,CAAA,GAAqB,kBAAA,CAAA,GAAA,CAAA,OAAA;AVDrC;;;;AAAA,iBUgBgB,eAAA,CAAA,GAAe,kBAAA,CAAA,GAAA,CAAA,OAAA;;iBA0Bf,gBAAA,CAAA,GAAgB,kBAAA,CAAA,GAAA,CAAA,OAAA;;;;;;;cC7CnB,gBAAA,EAAkB,sBAAA;;;;;;;cCIlB,SAAA,EAAW,wBAAA;;;;;;;cCDX,gBAAA,EAAkB,yBAAA;;;;;;;;cCkBlB,UAAA,EAAY,0BAAA"}