@bison-lab/payload-blocks 3.11.0 → 3.21.0

package/README.md

@@ -24,7 +24,7 @@ Payload site already has).
 | `@bison-lab/payload-blocks` | Block configs, field builders, row types, `resolveMedia` | Node. This is what `payload.config.ts` imports, and it touches no React. |
 | `@bison-lab/payload-blocks/react` | Renderers, `RenderBlocks`, the image and link seams, the rendering types | Client (`"use client"`). |
 | `@bison-lab/payload-blocks/rich-text` | The `richText` renderer, `internalDocToHrefFrom`, and `richTextBlockRenderer()` to build one that resolves internal links | Client. Split out because it is the only thing that needs `@payloadcms/richtext-lexical`. |
-| `@bison-lab/payload-blocks/admin` | `MinRowsArrayField` and `LinkField`, the admin fields the configs reference by path | Client, inside the Payload admin. Resolved through the site's import map, never imported by hand. |
+| `@bison-lab/payload-blocks/admin` | `MinRowsArrayField`, `LinkField`, and `NavItemsField`, the admin fields the configs reference by path | Client, inside the Payload admin. Resolved through the site's import map, never imported by hand. |
 
 The renderers are client components because the blocks they render are: every
 `@bison-lab/ui` export is a client reference, and these blocks are interactive
@@ -337,60 +337,69 @@ stylesheet scans both packages:
 ## Wiring a header
 
 Two more blocks build a header rather than a page: `megaMenuBlock` and
-`LinkBlock`. They go in a global's `items` array, and the site owns that
-global. `megaMenuBlock` is a factory because the featured-link variants and
-the icon list are the site's — the CMS only ever offers approved values:
+`LinkBlock`. They go in `createNavigation({ blocks })`'s `header.items`.
+`megaMenuBlock` is a factory because the featured-link variants and
+the icon list are the site's — the CMS only ever offers approved values.
+The items field uses `NAV_ITEMS_FIELD` (the kit editor) instead of
+Payload's stock blocks UI:
 
 ```ts
+import { createNavigation } from '@bison-lab/payload-core'
 import { LinkBlock, megaMenuBlock } from '@bison-lab/payload-blocks'
 
-export const Navigation: GlobalConfig = {
-  slug: 'navigation',
-  fields: [
-    {
-      name: 'items',
-      type: 'blocks',
-      blocks: [
-        megaMenuBlock({
-          variants: [
-            { label: 'Lumbar', value: 'lumbar' },
-            { label: 'SI joint', value: 'si' },
-          ],
-          icons: [{ label: 'Help', value: 'help' }],
-        }),
-        LinkBlock,
-      ],
-    },
-  ],
-}
+globals: [
+  ...createNavigation({
+    blocks: [
+      megaMenuBlock({
+        variants: [
+          { label: 'Lumbar', value: 'lumbar' },
+          { label: 'SI joint', value: 'si' },
+        ],
+        icons: [{ label: 'Help', value: 'help' }],
+      }),
+      LinkBlock,
+    ],
+  }),
+]
 ```
 
-Then `payload generate:types` and `payload migrate:create`.
-
-An editor sees: label, landing page, the panel's max width, one to four
-columns (each a width, an optional divider, and sections of links), a footer
-with an overview link and a call to action, and an **Advanced** collapsible
-for CSS widths. The column widths, read as fractions, must add up to 100%:
-the rule is the array's own `validate`, so the editor sees "The columns add
-up to 75%. They need to add up to 100%." as they build, and the global's
-publish refuses the same. Custom widths skip it.
+Then `payload generate:types`, `payload generate:importmap`, and
+`payload migrate:create`. Until the import map includes
+`@bison-lab/payload-blocks/admin#NavItemsField`, the items field renders
+as nothing, not the stock blocks UI.
+
+An editor sees a rail of bar items (Link vs Mega type cards from
+`@bison-lab/admin-ui`), destinations
+through `LINK_FIELD`, a two-up column builder, and a sticky
+`FloatingNavBlock` preview under the published theme. Advanced CSS
+column widths stay on the schema so existing rows do not migrate; the
+kit does not render them. The column widths, read as fractions, must add
+up to 100%: the rule is the array's own `validate`, so the editor sees
+"The columns add up to 75%. They need to add up to 100%." as they build,
+and the global's publish refuses the same. Custom widths skip it. The
+mega trigger's landing page is now the same `type` / `page` / `href`
+picker as every other destination — a schema change, so sites run
+`payload migrate:create`.
 
-In the site header, one call turns the rows into `FloatingNavBlock` items.
-The variants and icons here are the looks behind the values above:
+In the site header, one call turns the fetched Header global into
+`FloatingNavBlock` props. Looks come from chrome roles
+(`megaMenuVariantsFromLooks`), not a list on Header:
 
 ```tsx
 'use client'
-import { FloatingNavBlock } from '@bison-lab/ui'
-import { headerItemsFromBlocks } from '@bison-lab/payload-blocks/react'
+import { FloatingNavBlock, megaMenuVariantsFromLooks } from '@bison-lab/ui'
+import { headerFromNavigation } from '@bison-lab/payload-blocks/react'
 import { usePathname } from 'next/navigation'
 
-export function SiteHeader({ items }: { items: Navigation['items'] }) {
+export function SiteHeader({ doc }: { doc: Navigation }) {
   const pathname = usePathname()
   return (
     <FloatingNavBlock
-      breakpoint="lg" // the panel flattens below lg; the bar must switch there too
-      items={headerItemsFromBlocks(items, {
-        variants: { lumbar: { chip: '…', title: '…', icon: <Marker region="lumbar" /> }, si: { … } },
+      {...headerFromNavigation(doc, {
+        looks: megaMenuVariantsFromLooks(['lumbar', 'si'], {
+          lumbar: <Marker region="lumbar" />,
+          si: <Marker region="si" />,
+        }),
         icons: { help: <CircleHelp className="size-4" aria-hidden /> },
         isActive: (href) => pathname.startsWith(href),
         linkComponent: NextBlockLink,
@@ -401,6 +410,20 @@ export function SiteHeader({ items }: { items: Navigation['items'] }) {
 }
 ```
 
+`headerItemsFromBlocks` is still the items half, if a site is not ready
+for the Settings fields.
+
+## Navigation settings
+
+Bar behaviour moved out of code and onto Header → Settings: `bar.hideOnScroll`,
+`bar.viewport`, and `bar.defaultMaxWidth`. Live preview stays on Header
+(the pane already points at the site's header route). The kit editor
+holds the edited mega row open through `openItem` so an admin sees the
+panel they are changing. Featured looks stay on the chrome-role registry
+(BIS-85 / SPI-89) — Header has no `variants` array. A site without the
+consume bump (SPI-99) never sees the Settings tab. After this schema
+change run `payload generate:types` and `payload migrate:create`.
+
 `MegaMenuBlockRenderer` renders one panel on its own, which is what a live
 preview of the row wants; it is not a page block and has no place in the
 registry. A row with no columns, or whose columns hold no complete links,

package/dist/admin.d.mts

@@ -1,5 +1,5 @@
 
-import { ArrayFieldClientComponent, RowFieldClientComponent } from "payload";
+import { ArrayFieldClientComponent, BlocksFieldClientComponent, RowFieldClientComponent } from "payload";
 
 //#region src/admin/link-field.d.ts
 declare const LinkField: RowFieldClientComponent;
@@ -26,5 +26,8 @@ declare const LinkField: RowFieldClientComponent;
  */
 declare const MinRowsArrayField: ArrayFieldClientComponent;
 //#endregion
-export { LinkField, MinRowsArrayField };
+//#region src/admin/nav-items-field.d.ts
+declare const NavItemsField: BlocksFieldClientComponent;
+//#endregion
+export { LinkField, MinRowsArrayField, NavItemsField };
 //# sourceMappingURL=admin.d.mts.map

package/dist/admin.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"admin.d.mts","names":[],"sources":["../src/admin/link-field.tsx","../src/admin/min-rows-array-field.tsx"],"mappings":";;;;cAuEa,SAAA,EAAW,uBAAA;;;;;AAAxB;;;;;;;;AChDA;;;;;;;;;cAAa,iBAAA,EAAmB,yBAAA"}
+{"version":3,"file":"admin.d.mts","names":[],"sources":["../src/admin/link-field.tsx","../src/admin/min-rows-array-field.tsx","../src/admin/nav-items-field.tsx"],"mappings":";;;;cAuEa,SAAA,EAAW,uBAAA;;;;;AAAxB;;;;;;;;AChDA;;;;;;;;ACqKA;cDrKa,iBAAA,EAAmB,yBAAA;;;cCqKnB,aAAA,EAAe,0BAAA"}