@bison-lab/payload-core 3.12.0 → 3.14.0

package/README.md

@@ -22,10 +22,10 @@ lockstep.
 
 | Import                             | Contents                                                                                         | Runs where                                                                 |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `@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`          | `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, the Roles matrix field, and the Users Roles checklist                        | 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
@@ -138,14 +138,16 @@ 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`.
+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,
-  canManageBrand,
   createBrandAssets,
+  canUseFeature,
+  createFeatures,
   createRoles,
   createTheme,
   isAuthenticated,
@@ -155,13 +157,14 @@ import bisonConfig from "../bison.config.json";
 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: {
@@ -170,6 +173,10 @@ export default buildConfig({
           mark: { url: "/logo-mark.svg", alt: "Acme mark" },
         },
       },
+      colorUsages: {
+        collections: ["pages"],
+        globals: ["navigation"],
+      },
       onPublish: async () => {
         revalidateTag("theme");
       },
@@ -178,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`.
@@ -187,12 +203,13 @@ so the site renders what `bison-theme.css` rendered before anyone opens the
 admin:
 
 ```ts
-import { seedRoles, 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);
+  await seedRoles(payload); // pass the same extras as createRoles, if any
+  await seedFeatures(payload); // pass the same extras as createFeatures, if any
 }
 ```
 
@@ -233,7 +250,8 @@ 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.
 
@@ -243,20 +261,56 @@ 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).
+Ticks are the catalogue rows released on Features. Developer is
+implicit — every catalogue feature, including ones not released. That
+row is visible only to a Developer, with every tick on and locked.
+Defaults ship in the package (Theme
+screens on Designer; Designer also has Users and Roles; Admin + Designer
+both store). A site may pass `extras` into `createRoles` — each extra
+is a slug, a display label, and default `grants` — 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. The package never writes `developer` onto a user row.
+back to that seed (plus extras). The package never writes `developer`
+onto a user row.
+
+```ts
+createRoles({
+  extras: [{ role: "editor", label: "Editor", grants: ["content"] }],
+});
+```
+
+## Features
+
+Settings → Features is a Developer-only release valve: one switch per
+catalogue row. Off hides the tick on Roles; Developer still has the
+feature. The catalogue is code, grouped for the UI: Pages (Content,
+Publish, API tab), Media, Theme (Colors, Typography, Appearance,
+Identity, Brand assets), and Users (Users, Roles). Features itself is
+not a row. A site may pass `extras` into `createFeatures` — those rows
+appear only there. `canUseFeature(slug)` is true when the row is
+released and a held role is granted it, or when the login is Developer.
+An empty Global falls back to the catalogue defaults. Group slugs
+`pages` and `theme` are true when any child is. `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", group: "users" }],
+});
+```
 
 ## 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.
+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