@bison-lab/payload-core 3.11.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`, `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`, `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`, `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 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
@@ -137,15 +137,20 @@ 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 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: [
@@ -154,6 +159,7 @@ export default buildConfig({
     }),
   ],
   globals: [
+    createRoles(),
     ...createTheme({
       access: { read: isAuthenticated, update: canManageBrand },
       seed: bisonConfig,
@@ -181,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);
 }
 ```
 
@@ -233,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

@@ -101,5 +101,20 @@ 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/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","../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-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"}

package/dist/admin.mjs

@@ -1,8 +1,8 @@
 "use client";
 import { a as colorDocFromState, i as SYSTEM_COLOR_KEYS, n as pageEditorLooks, r as pageEditorTokens, s as stateFromColorDoc } from "./looks-BbL309kO.mjs";
-import { FieldDescription, FieldError, FieldLabel, useConfig, useField, useForm, useFormFields } from "@payloadcms/ui";
+import { ArrayField, CheckboxInput, FieldDescription, FieldError, FieldLabel, fieldBaseClass, useConfig, useField, useForm, useFormFields } from "@payloadcms/ui";
 import { GREY_SCALES, SHADE_STEPS, contrastForeground, contrastRatio, createColorScale, deriveDarkPalette, deriveLightPalette, hexToHSL, hslToString, includedShadeSteps, isThemeHex, presetHints, setColorScaleInclude } from "@bison-lab/tokens";
-import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
 import { findFont, fontFaceCss, isFontId } from "@bison-lab/fonts";
@@ -2406,6 +2406,239 @@ const LookField = ({ field, path, readOnly }) => {
 	});
 };
 //#endregion
-export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, SectionHeading, ThemeDocumentControls, ThemeSaveButton };
+//#region src/roles/types.ts
+/**
+* The Roles Global a site's generated types will describe. Optional and
+* nullable, no index signature: a generated Global is assignable to this,
+* never the reverse.
+*/
+const ROLES = [
+	"developer",
+	"admin",
+	"designer",
+	"author"
+];
+const ROLE_LABELS = {
+	developer: "Developer",
+	admin: "Admin",
+	designer: "Designer",
+	author: "Author"
+};
+const CAPABILITIES = [
+	"content",
+	"brand",
+	"publish",
+	"users"
+];
+function isRole(value) {
+	return typeof value === "string" && ROLES.includes(value);
+}
+//#endregion
+//#region src/roles/matrix.ts
+/**
+* Default rank and ticks. Brand is Designer only. The API tab is not a
+* column — it is locked to Developer in `isDeveloper`.
+*/
+const DEFAULT_ROLE_MATRIX = [
+	{
+		role: "developer",
+		content: true,
+		brand: true,
+		publish: true,
+		users: true
+	},
+	{
+		role: "admin",
+		content: true,
+		brand: false,
+		publish: true,
+		users: true
+	},
+	{
+		role: "designer",
+		content: false,
+		brand: true,
+		publish: false,
+		users: false
+	},
+	{
+		role: "author",
+		content: true,
+		brand: false,
+		publish: false,
+		users: false
+	}
+];
+const DEVELOPER_DESCRIPTION = "Everything Admin can do, plus the document API tab.";
+const CAPABILITY_LABELS = {
+	content: "Content",
+	brand: "Brand",
+	publish: "Publish",
+	users: "Users"
+};
+function defaultRolesFieldValue() {
+	return DEFAULT_ROLE_MATRIX.map((row) => ({
+		id: row.role,
+		...row
+	}));
+}
+function roleSelectOptions(matrix = DEFAULT_ROLE_MATRIX) {
+	return matrix.map((row) => ({
+		label: ROLE_LABELS[row.role],
+		value: row.role
+	}));
+}
+/** Capability copy only. Developer names the API tab; nothing about MCP or seed. */
+function roleDescription(role, matrix = DEFAULT_ROLE_MATRIX) {
+	if (role === "developer") return DEVELOPER_DESCRIPTION;
+	const row = matrix.find((entry) => entry.role === role);
+	if (!row) return "No capabilities";
+	return CAPABILITIES.filter((capability) => row[capability]).map((capability) => CAPABILITY_LABELS[capability]).join(", ") || "No capabilities";
+}
+//#endregion
+//#region src/admin/roles-matrix-field.tsx
+const HIDE_ROW_CHROME = `.bl-roles-matrix .array-field__add-row,.bl-roles-matrix .array-actions__add,.bl-roles-matrix .array-actions__remove,.bl-roles-matrix .array-actions__duplicate,.bl-roles-matrix .array-actions__copy{display:none}.bl-roles-matrix__toolbar{display:flex;justify-content:flex-end;margin-block-end:.75rem}.bl-roles-matrix__reset{min-height:2.25rem;padding:.35rem .9rem;border:1px solid var(--theme-elevation-150,#e2e8f0);border-radius:8px;background:transparent;color:inherit;font:inherit;cursor:pointer}`;
+/**
+* Payload's array field: drag rank stays, add/remove go away. Reset writes
+* the package seed back onto the field.
+*/
+const RolesMatrixField = (props) => {
+	const { setValue } = useField({ path: props.path });
+	return /* @__PURE__ */ jsxs("div", {
+		className: "bl-roles-matrix",
+		children: [
+			/* @__PURE__ */ jsx("style", {
+				href: "bl-roles-matrix",
+				precedence: "default",
+				children: HIDE_ROW_CHROME
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "bl-roles-matrix__toolbar",
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "bl-roles-matrix__reset",
+					onClick: () => setValue(defaultRolesFieldValue()),
+					children: "Reset to defaults"
+				})
+			}),
+			/* @__PURE__ */ jsx(ArrayField, { ...props })
+		]
+	});
+};
+//#endregion
+//#region src/admin/roles-field.tsx
+const GRID_CSS = `.bl-roles__grid{display:grid;gap:.75rem;grid-template-columns:repeat(auto-fit,minmax(12rem,1fr));margin-block:.35rem 0}.bl-roles__option{display:flex;flex-direction:column;gap:.25rem;padding:.65rem .75rem;border:1px solid var(--theme-elevation-150,#e2e8f0);border-radius:8px}.bl-roles__option.is-checked{border-color:var(--theme-elevation-400,#94a3b8)}.bl-roles__option.is-included{opacity:.7}.bl-roles__what{font-size:.8rem;line-height:1.35;color:var(--theme-elevation-500,#64748b)}`;
+function optionValue(option) {
+	return typeof option === "string" ? option : String(option.value);
+}
+function optionLabel(option) {
+	return typeof option === "string" ? option : String(option.label);
+}
+/**
+* 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.
+*/
+const RolesField = ({ field, path: pathFromProps, readOnly, validate }) => {
+	const { admin: { description } = {}, label, localized, options = [], required } = field;
+	const offered = (options.length ? options : roleSelectOptions()).map((option) => ({
+		value: optionValue(option),
+		label: optionLabel(option)
+	}));
+	const { disabled, errorMessage, path, setValue, showError, value } = useField({
+		potentiallyStalePath: pathFromProps,
+		validate: useCallback((value, validationOptions) => {
+			if (typeof validate === "function") return validate(value, {
+				...validationOptions,
+				hasMany: true,
+				options,
+				required
+			});
+			return true;
+		}, [
+			validate,
+			options,
+			required
+		])
+	});
+	const selected = Array.isArray(value) ? value : [];
+	const exclusive = selected.includes("developer") ? "developer" : null;
+	const locked = Boolean(readOnly) || disabled;
+	function toggle(role) {
+		if (locked) return;
+		if (role === "developer") {
+			setValue(selected.includes(role) ? [] : ["developer"]);
+			return;
+		}
+		if (exclusive) return;
+		setValue(selected.includes(role) ? selected.filter((entry) => entry !== role) : [...selected, role]);
+	}
+	const groupLabel = typeof label === "string" ? label : "Roles";
+	return /* @__PURE__ */ jsxs("div", {
+		className: [
+			fieldBaseClass,
+			"select",
+			"bl-roles",
+			showError && "error",
+			locked && "read-only"
+		].filter(Boolean).join(" "),
+		id: `field-${path.replace(/\./g, "__")}`,
+		children: [
+			/* @__PURE__ */ jsx("style", {
+				href: "bl-roles",
+				precedence: "default",
+				children: GRID_CSS
+			}),
+			/* @__PURE__ */ jsx(FieldLabel, {
+				as: "span",
+				label,
+				localized,
+				path,
+				required
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: `${fieldBaseClass}__wrap`,
+				children: [/* @__PURE__ */ jsx(FieldError, {
+					message: errorMessage,
+					path,
+					showError
+				}), /* @__PURE__ */ jsx("div", {
+					"aria-label": groupLabel,
+					className: "bl-roles__grid",
+					role: "group",
+					children: offered.map((option) => {
+						const role = isRole(option.value) ? option.value : null;
+						if (!role) return null;
+						const included = exclusive !== null && role !== exclusive;
+						const checked = selected.includes(role);
+						return /* @__PURE__ */ jsxs("div", {
+							className: [
+								"bl-roles__option",
+								checked && "is-checked",
+								included && "is-included"
+							].filter(Boolean).join(" "),
+							children: [/* @__PURE__ */ jsx(CheckboxInput, {
+								checked,
+								id: `${path}-${role}`,
+								label: option.label || ROLE_LABELS[role],
+								onToggle: () => toggle(role),
+								readOnly: locked || included
+							}), /* @__PURE__ */ jsx("span", {
+								className: "bl-roles__what",
+								children: included ? "Included in Developer" : roleDescription(role)
+							})]
+						}, role);
+					})
+				})]
+			}),
+			/* @__PURE__ */ jsx(FieldDescription, {
+				description,
+				path
+			})
+		]
+	});
+};
+//#endregion
+export { AppearanceField, ColorField, ColorScaleField, ContrastReport, FontField, GreyScaleField, HiddenSaveButton, IdentityFallback, LibraryField, LookField, PairingField, PublishChild, RolesField, RolesMatrixField, SectionHeading, ThemeDocumentControls, ThemeSaveButton };
 
 //# sourceMappingURL=admin.mjs.map