@bison-lab/payload-core 3.13.0 → 3.15.0

package/README.md

@@ -25,7 +25,7 @@ lockstep.
 | `@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 and Features matrices, and the Users Roles checklist               | Admin. Referenced by import-map string; `generate:importmap` writes it.    |
+| `@bison-lab/payload-core/admin`    | Theme 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
@@ -125,13 +125,13 @@ The sitemap is the site's: filter `meta.noIndex` out of it.
 
 ## Adopting the Theme global
 
-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
+Theme in the admin nav is one Global (`theme`) in `admin.group: "Theme"`.
+Colors, Typography, Appearance, and Identity are field tabs on that
+document, not custom views and not extra Globals. Save is Payload's Save
+on the whole form — every tab is hydrated from the live row, so an
+untouched tab does not revert. `getPublishedTheme` reads that same row.
+Document locking is off. 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
@@ -194,7 +194,7 @@ 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
+Then `payload generate:importmap` (the Theme fields resolve from
 `@bison-lab/payload-core/admin`), `payload generate:types`, and
 `payload migrate:create`.
 
@@ -261,10 +261,13 @@ 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
+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 (plus extras). The package never writes `developer`
@@ -272,38 +275,63 @@ onto a user row.
 
 ```ts
 createRoles({
-  extras: [{ role: "editor", label: "Editor", content: true, brand: false, publish: false, users: false }],
+  extras: [{ role: "editor", label: "Editor", grants: ["content"] }],
 });
 ```
 
 ## 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`.
+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), Media, Theme (Colors, Typography, Appearance, Identity, Brand
+assets), and Users (Users, Roles). Features itself is not a row. The
+document API tab and Better Editor overlay settings are not rows either
+— they stay code-locked to Developer (`adminOnlyApiTab`,
+`developerOnlyAccess` / `hideUnlessDeveloper`). A site may pass `extras`
+into `createFeatures` — those rows appear only there, including a
+future Navigation global:
 
 ```ts
 createFeatures({
-  extras: [{ slug: "doctors", label: "Doctor search" }],
+  extras: [
+    { slug: "doctors", label: "Doctor search", group: "users" },
+    { slug: "navigation", label: "Navigation" },
+  ],
 });
+
+// On that Global:
+//   access: { update: canUseFeature("navigation") }
+// Drafts use the same Publish tick as Pages to go live.
 ```
 
+`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`.
+`admin.hidden` is presentation; Access Control is enforcement. Nav
+hiding follows `user.allowedFeatures` on the JWT (computed at user
+read from the live Features and Roles Globals) so Payload's
+`admin.hidden({ user })` matches the API.
+
 ## 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.
+path. Create follows the Content tick. Update without Publish is
+constrained to `_status: draft` — an Author can save a draft and cannot
+publish or edit a live page. Users sit under Settings next to Roles,
+take `secureCookies`, and offer whatever rows the Global (or the seed
+plus the same `extras`) has. `users.roles` and `users.allowedFeatures`
+set `saveToJWT: true`. The checklist labels are the editable names.
+`adminOnlyApiTab` shows the document API tab only to Developer. Overlay
+settings (Better Editor) take `developerOnlyAccess` and
+`hideUnlessDeveloper` on the site — the package does not add that
+plugin as a peer.
 
 ## No generated types
 

package/dist/admin.d.mts

@@ -1,7 +1,7 @@
 
 import { ThemeConfig } from "@bison-lab/tokens";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
-import { ArrayFieldClientComponent, GroupFieldClientComponent, SelectFieldClientComponent, TextFieldClientComponent, UIFieldClientComponent } from "payload";
+import { ArrayFieldClientComponent, GroupFieldClientComponent, JSONFieldClientComponent, SelectFieldClientComponent, TextFieldClientComponent, UIFieldClientComponent } from "payload";
 
 //#region src/admin/color-field.d.ts
 /**
@@ -104,7 +104,8 @@ declare const LookField: TextFieldClientComponent;
 //#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.
+ * rows have no remove. Developer stays in the saved array and is shown
+ * only to a Developer. Reset restores seed ticks and package labels.
  */
 declare const RolesMatrixField: ArrayFieldClientComponent;
 //#endregion
@@ -120,6 +121,13 @@ declare function RolesRowLabel(): react_jsx_runtime0.JSX.Element;
  */
 declare const RoleSlugField: TextFieldClientComponent;
 //#endregion
+//#region src/admin/role-name-field.d.ts
+/**
+ * Role name. Letters and spaces only, so the hidden slug stays
+ * `the-greatest-designer` from `The Greatest Designer`.
+ */
+declare const RoleNameField: TextFieldClientComponent;
+//#endregion
 //#region src/admin/roles-field.d.ts
 /**
  * Users Roles checklist. Order and labels come from the field options (the
@@ -128,12 +136,24 @@ declare const RoleSlugField: TextFieldClientComponent;
  */
 declare const RolesField: SelectFieldClientComponent;
 //#endregion
+//#region src/admin/roles-grants-field.d.ts
+/**
+ * Released catalogue rows as ticks. Unreleased features do not appear,
+ * except on Developer: every catalogue row is shown granted and locked
+ * so a new Feature is visibly included.
+ */
+declare const RolesGrantsField: JSONFieldClientComponent;
+//#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.
+ * One release switch per catalogue row, grouped. Off hides the tick on
+ * Roles; Developer still has the feature.
+ *
+ * Writes both the array value and each row's `released` checkbox path.
+ * Payload still registers those child fields; toggling only the parent
+ * array leaves them false and Save stores the old flags.
  */
 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 };
+export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FeaturesMatrixField, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, RoleNameField, RoleSlugField, RolesField, RolesGrantsField, 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","../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"}
+{"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/role-name-field.tsx","../src/admin/roles-field.tsx","../src/admin/roles-grants-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;;;;;;;;cCsBX,gBAAA,EAAkB,yBAAA;;;;;;iBC3Bf,aAAA,CAAA,GAAa,kBAAA,CAAA,GAAA,CAAA,OAAA;;;;;;cCChB,aAAA,EAAe,wBAAA;;;;;;;cCCf,aAAA,EAAe,wBAAA;;;;;;;;cC8Cf,UAAA,EAAY,0BAAA;;;;;;;;cChCZ,gBAAA,EAAkB,wBAAA;;;;;;;;AlBZ/B;;;cmB0Ca,mBAAA,EAAqB,yBAAA"}