@bison-lab/payload-core 3.11.0 → 3.13.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`, `lookField`, `colorTokenField`, 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`, `createFeatures`, `createPages`, `createUsers`, `createMedia`, `adminOnlyApiTab`, `seedTheme`, `seedRoles`, `seedFeatures`, 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`, `themeHeadFromDoc` | 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/admin`    | Theme child fields, the Roles and Features matrices, 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
@@ -137,25 +137,34 @@ is never enforced and lives in the Needs-attention modal, not on the page.
 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 — the predicates live in the
-site's `src/platform` until they move here. Pass `canManageBrand` as
-`update`.
+**1. Register the Global.** Access is required — Theme does not read the
+Roles or Features Global. Pass `canUseFeature("theme")` as `update`
+(sites can keep `canManageBrand` until they adopt the switchboard).
 
 ```ts
 // payload.config.ts
-import { BRAND_ASSETS_SLUG, createBrandAssets, createTheme } from "@bison-lab/payload-core";
+import {
+  BRAND_ASSETS_SLUG,
+  createBrandAssets,
+  canUseFeature,
+  createFeatures,
+  createRoles,
+  createTheme,
+  isAuthenticated,
+} 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 },
+      access: { read: () => true, update: canUseFeature("brand-assets") },
     }),
   ],
   globals: [
+    createRoles(),
+    createFeatures(),
     ...createTheme({
-      access: { read: isAuthenticated, update: canManageBrand },
+      access: { read: isAuthenticated, update: canUseFeature("theme") },
       seed: bisonConfig,
       logo: { collection: BRAND_ASSETS_SLUG },
       identity: {
@@ -164,6 +173,10 @@ export default buildConfig({
           mark: { url: "/logo-mark.svg", alt: "Acme mark" },
         },
       },
+      colorUsages: {
+        collections: ["pages"],
+        globals: ["navigation"],
+      },
       onPublish: async () => {
         revalidateTag("theme");
       },
@@ -172,6 +185,15 @@ export default buildConfig({
 });
 ```
 
+**Color usages.** `createTheme({ colorUsages })` is the only site wiring for
+"is this custom color assigned?" Name every collection and global that
+stores a `lookField` / `colorTokenField` (or a string token those fields
+wrote). The package scans those documents — drafts included — and
+rewrites tokens when Colors Delete needs a replacement. Omit the option,
+or pass empty arrays, and every additional color is unused and deletes
+immediately. A new look surface is added to `colorUsages`, not copied
+into a site helper. Site adopt names the slugs (SPI-93).
+
 Then `payload generate:importmap` (the Theme child fields resolve from
 `@bison-lab/payload-core/admin`), `payload generate:types`, and
 `payload migrate:create`.
@@ -181,11 +203,13 @@ so the site renders what `bison-theme.css` rendered before anyone opens the
 admin:
 
 ```ts
-import { seedTheme } from "@bison-lab/payload-core";
+import { seedFeatures, 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); // pass the same extras as createRoles, if any
+  await seedFeatures(payload); // pass the same extras as createFeatures, if any
 }
 ```
 
@@ -226,24 +250,72 @@ 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.
+`canUseFeature("brand-assets")` (or `canManageBrand` until the site
+adopts the switchboard) 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`.
 
+## Roles
+
+Settings → Roles is an Admin-editable array. Rank is drag-to-reorder.
+Ticks are Content, Brand, Publish, and Users. Defaults ship in the
+package (Brand on Designer only; Admin + Designer both store; Developer
+is exclusive). A site may pass `extras` into `createRoles` — each extra
+is a slug, a display label, and default ticks — and an Admin can add
+further custom rows and edit any row’s name. Seed slugs stay read-only.
+`canManageBrand` and the other predicates read the saved Global and fall
+back to that seed (plus extras). The package never writes `developer`
+onto a user row.
+
+```ts
+createRoles({
+  extras: [{ role: "editor", label: "Editor", content: true, brand: false, publish: false, users: false }],
+});
+```
+
+## Features
+
+Settings → Features is a feature × role grid. The catalogue is code:
+Pages, Media, Theme, Brand assets, Users, Roles, and Features. A site
+may pass `extras` into `createFeatures` — those rows appear only there.
+`canUseFeature(slug)` reads the saved grid and falls back to Content →
+Pages/Media and Brand → Theme/Brand assets when the Global is empty.
+Users, Roles, and Features cannot be turned off; Developer is always
+allowed. `createPages` / `createMedia` use `canUseFeature` for create
+and update (and `admin.hidden`). Theme and brand-assets still take
+`access` arguments — pass `canUseFeature("theme")` /
+`canUseFeature("brand-assets")` as `update`.
+
+```ts
+createFeatures({
+  extras: [{ slug: "doctors", label: "Doctor search" }],
+});
+```
+
+## 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 sit under Settings next to Roles, take `secureCookies`, and
+offer whatever rows the Global (or the seed plus the same `extras`) has.
+The checklist labels are the editable names. `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

@@ -19,10 +19,10 @@ declare const ColorScaleField: GroupFieldClientComponent;
 //#endregion
 //#region src/admin/library-field.d.ts
 /**
- * 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.
+ * Custom colors: the same scale controls as system colors. Unused: the
+ * Theme store's color-usages endpoint returns nothing and the row is
+ * gone. In use: pick a live replacement; confirm rewrites stored tokens
+ * then drops the row. Success and Destructive stay off that list.
  */
 declare const LibraryField: ArrayFieldClientComponent;
 //#endregion
@@ -101,5 +101,39 @@ declare const IdentityFallback: UIFieldClientComponent;
  */
 declare const LookField: TextFieldClientComponent;
 //#endregion
-export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, SectionHeading, ThemeDocumentControls, ThemeSaveButton };
+//#region src/admin/roles-matrix-field.d.ts
+/**
+ * Payload's array field: drag rank stays, add is for custom rows, seed
+ * rows have no remove. Reset restores seed ticks and package labels.
+ */
+declare const RolesMatrixField: ArrayFieldClientComponent;
+//#endregion
+//#region src/admin/roles-row-label.d.ts
+/**
+ * Array row header. Shows the current display name, not “Role 01”.
+ */
+declare function RolesRowLabel(): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/admin/role-slug-field.d.ts
+/**
+ * Seed slugs stay read-only. A custom row's slug is typed here.
+ */
+declare const RoleSlugField: TextFieldClientComponent;
+//#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 plus extras). Copy is `roleDescription`.
+ * Developer is exclusive; a custom role does not clear Designer.
+ */
+declare const RolesField: SelectFieldClientComponent;
+//#endregion
+//#region src/admin/features-matrix-field.d.ts
+/**
+ * Feature × role grid. Columns come from the Roles Global (or the seed).
+ * Locked rows and Developer cannot be cleared.
+ */
+declare const FeaturesMatrixField: ArrayFieldClientComponent;
+//#endregion
+export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FeaturesMatrixField, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, RoleSlugField, RolesField, RolesMatrixField, RolesRowLabel, 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","../src/admin/look-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"}
+{"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-row-label.tsx","../src/admin/role-slug-field.tsx","../src/admin/roles-field.tsx","../src/admin/features-matrix-field.tsx"],"mappings":";;;;;;;;;;cAWa,UAAA,EAAY,wBAAA;;;;;;;cCsBZ,eAAA,EAAiB,yBAAA;;;;;;;;ADtB9B;cEgBa,YAAA,EAAc,yBAAA;;;;;;;;AFhB3B;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;;;;;;;cCYX,gBAAA,EAAkB,yBAAA;;;;;;iBCjBf,aAAA,CAAA,GAAa,kBAAA,CAAA,GAAA,CAAA,OAAA;;;;;;cCChB,aAAA,EAAe,wBAAA;;;;;;;;cC+Cf,UAAA,EAAY,0BAAA;;;;;;;cCtCZ,mBAAA,EAAqB,yBAAA"}