@unitninety/site-kit 1.6.4 → 1.6.5

package/README.md

@@ -5,13 +5,19 @@ The library a UnitNinety site is built on. It reads the site's content from Unit
 You do not usually add it by hand. The `u90` tool adds it when it converts a Next.js App Router site, at the one version that release of the tool works with:
 
 ```bash
-npx --yes @unitninety/u90@1.0.4 --version
+npx --yes @unitninety/u90@1.0.5 --version
 ```
 
 UnitNinety imports packages made for that version only, so keep the version the tool names.
 
 Documentation: [converting a site](https://unitninety.com/docs/convert), [importing it](https://unitninety.com/docs/import) and [the U90 package](https://unitninety.com/docs/package).
 
+### Layout reordering in Canvas
+
+Site Kit 1.6.5 gives every draft layout Slot its own preview address. Moving the Slot or placing a block before it updates immediately through the shared renderer, including nested layouts. The optimistic order stays visible while saving, and older responses cannot undo a newer move. Published output is unchanged.
+
+Use Site Kit 1.6.5 with `@unitninety/u90@1.0.5` for new sites. Existing sites must update their Site Kit dependency and redeploy to receive the fix; updating the platform alone does not update a site's bundled renderer.
+
 ### Fixed field values
 
 Use `lock: ['$']` on a leaf such as `number({ lock: ['$'] })` to retain a site-owned value without offering a content editor for it. Updates cannot change, clear, or remove that field, including when its previous value was absent. The stored value remains available to site reads and exports. Existing locks such as `lock: ['to']` on a link continue to protect only that subpath.
@@ -37,6 +43,24 @@ The form uses each field's label, default and text constraints. The list must co
 
 Creation saves a draft with the normal schema defaults and approved template. Routed entries open Canvas for images and sections; collections without pages keep their content editor in the CMS. The matching platform/Site Kit implementation must be deployed together before using this new metadata in an uploaded package.
 
+### Immediate authored-list previews
+
+Client components inside a draft block can opt in with `useDraftContent`:
+
+```tsx
+'use client'
+import { useDraftContent } from '@unitninety/site-kit/bridge'
+
+export function Header({ navigation }) {
+  const draft = useDraftContent(navigation, 'navigation')
+  return <nav>{draft.menuItems.map(item => <a key={item._id} href={item.href.href ?? '#'}>{item.label.text}</a>)}</nav>
+}
+```
+
+Call the hook on native reads before converting them for a presentation component. `renderBlocks` supplies the draft block path automatically; custom `DraftBlocks` renderers must supply each item's native `path`. Key rows by `_id`, not their editable label, URL or position. Existing server-only published content is unchanged.
+
+Canvas prepares locally resolvable list defaults with a stable random item ID, previews the same list in both inspector and site, then saves through the normal validated queue. Nested lists, empty lists and duplicate responsive renderings work without DOM cloning. Later edits survive older refresh responses; rejected or ambiguous structural saves reconcile with an authoritative read. Draft IDs cannot collide with an existing item. Media/reference defaults requiring resolution still use the server path, and references continue using their existing entry previews. This opt-in requires the updated Site Kit; older bridges retain their ordinary DOM previews and refresh behavior.
+
 ### Immediate collection-list previews
 
 Render a query's `EntriesRead` with `Entries` from `@unitninety/site-kit/components` when its
@@ -54,3 +78,47 @@ pending order/removal through slow refreshes; rejected saves reconcile to the se
 Published output is an ordinary div and server-rendered cards. Newly added entries whose markup
 is not already present appear when the save's server refresh arrives. Query results rendered
 with a plain `.map()` still work, but wait for that refresh to change their order or membership.
+
+### Shared blocks with page-only copies
+
+A shared block uses one content group whose declaration matches a Single:
+
+```tsx
+const enquiryContent = group({ heading: text(), contact: link() })
+const singles = defineSingles({ enquiry: enquiryContent })
+const enquiry = block('enquiry', {
+  label: 'Enquiry',
+  fields: { content: enquiryContent },
+  shared: { single: 'enquiry', field: 'content' },
+  component: Enquiry,
+})
+// Include enquiry in a normal zone's allow/default lists.
+```
+
+A shared block may retain additional design fields only when every leaf is locked with `lock: ['$']`. Optional `shared.previewFields` lists the content keys this placement actually renders (1–30 unique existing keys); it filters both linked and page-specific trees without deleting stored data. Shared content uses the same accordion and selected-field editor as ordinary blocks.
+
+The default `content: null` follows the Single. A content object is an independent copy owned by that block instance. Both render through the same component and retain the same block ID and controls. The Inspector labels the scope and offers shared editing or “Customise for this page”; customising copies the latest saved shared value. Templates seed the initial blocks, while an authored empty zone remains empty. Converting an existing hardcoded placement requires migrating its documents and renderer together.
+
+### Inspector-only canvas editing
+
+Pass `inlineEditing={false}` to `U90Bridge` in the root layout when clients should type only in the inspector. Canvas clicks still select and highlight fields; inspector text, rich-text and link-label previews remain immediate. The bridge keeps the `data-u90-edit` metadata for previews but does not add `contenteditable` or send canvas input edits. The option defaults to `true` for existing sites.
+
+### Featured-entry fields in the block tree
+
+Selections, relations and queries can declare the collection fields that their component displays:
+
+```ts
+selection('projects', {
+  many: true,
+  depth: 2,
+  previewFields: ['title', 'heroMedia', 'industry', 'client', 'date', 'location'],
+})
+```
+
+`previewFields` is optional editor metadata: unique top-level field keys (1–20). It does not change stored references, query rules, ordering or read shapes. The same expandable rows work on pages, collection entries and layouts. A referenced entry expands inside its block; choosing a leaf opens its primitive editor above the tree. A referenced field can itself declare `previewFields` to expose a nested list. Cycles and deep chains fall back to the ordinary reference editor. Derived relations retain their existing read-only editor.
+
+For example, KAW's Home declares `query('industries', { previewFields: ['name', 'description', 'capabilities'] })`. The Industries collection declares `relation('capabilities', { many: true, previewFields: ['name', 'heroMedia'] })`. Industry names, introductions, capability names and images still write to their original entry paths and update everywhere. Membership edits only change the owning reference. Queries preserve their rules and use pin/exclude/order controls; the plus control uses the existing tenant-scoped picker.
+
+The site component must reveal the selected entry in its own tabs/carousels, including when its data arrives after selection. `useEditing()` exposes `selected` and `selectedVia`: the latter contains outer-to-inner reference field paths, disambiguating an entry reused in several parents. Mark a displayed list container with `data-u90-reference={reference.$path}` in draft mode to preserve this context when selecting its content on the canvas. Keep `data-u90-field` on each entry's own fields and a root marker on the revealed entry for row highlighting. A relation's target entry path is not its parent relation field path. These attributes do not introduce visitor-facing editing controls.
+
+Deploy matching Site Kit/platform code before importing this metadata, and restart a running dev server after changing registry options so Payload validation hooks reload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "The client-site half of the UnitNinety platform contract: schema authoring, content fetching, the editing bridge and the pairing CLI.",
   "type": "module",
   "exports": {
@@ -60,7 +60,7 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "4.4.3"
+    "zod": "4.6.6"
   },
   "peerDependencies": {
     "react": ">=19",

package/src/elements/declaration.ts

@@ -84,7 +84,7 @@ export const CollectionDeclSchema = z.strictObject({
     seen.add(name)
   })
 })
-export const SingleDeclSchema = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/), field: FieldDeclSchema })
+export const SingleDeclSchema = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/), field: FieldDeclSchema, editor: z.enum(['cms', 'canvas']).optional() })
 export const SchemaSchema = z.strictObject({ blocks: z.record(z.string(), BlockDeclSchema), collections: z.record(z.string(), CollectionDeclSchema), singles: z.record(z.string(), SingleDeclSchema) })
 
 type Where = 'block' | 'collection' | 'single'

package/src/elements/define.ts

@@ -140,7 +140,7 @@ export type CollectionDecl = {
   defaultSort?: { field: string; dir: 'asc' | 'desc' } | 'manual'
   order?: string[]
 }
-export type SingleDecl = { key: string; field: FieldDecl }
+export type SingleDecl = { key: string; field: FieldDecl; editor?: 'cms' | 'canvas' }
 export type Schema = {
   blocks: Record<string, BlockDecl>
   collections: Record<string, CollectionDecl>

package/src/elements/ops/expand.ts

@@ -62,7 +62,10 @@ export function expandField(schema: Schema, decl: FieldDecl, value: unknown, ctx
     const item = items[i]
     const block = record(item) ? String(item._block) : ''
     const metadata = record(item) && typeof item._hidden === 'boolean' ? { _hidden: item._hidden } : {}
-    if (block === SLOT || !Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block, ...metadata }
+    // The slot has no fields, but it is still a movable layout item. DraftBlocks needs
+    // its address both to move the page content and to place other blocks before it.
+    if (block === SLOT) return { _id: c.key, _block: block, ...metadata, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}) }
+    if (!Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block, ...metadata }
     return { _id: c.key, _block: block, ...metadata, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
   })
 }

package/src/legacy/cli.mjs

@@ -2,7 +2,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 
 /**
- * `npx --yes @unitninety/u90@1.0.4 pair <code>` — the one command an operator hands over. The u90 tool
+ * `npx --yes @unitninety/u90@1.0.5 pair <code>` — the one command an operator hands over. The u90 tool
  * runs this file for `u90 pair`. The command is scoped and pinned because an unscoped name, run in a
  * repository with no local bin, fetches whatever package npm holds under that name.
  *
@@ -115,7 +115,7 @@ const run = async () => {
   const args = process.argv.slice(2)
 
   if (args[0] !== 'pair' || !args[1]) {
-    fail('Usage: npx --yes @unitninety/u90@1.0.4 pair <code> --site https://example.com [--platform https://cms…]')
+    fail('Usage: npx --yes @unitninety/u90@1.0.5 pair <code> --site https://example.com [--platform https://cms…]')
   }
 
   const code = args[1]

package/src/legacy/content.ts

@@ -360,7 +360,7 @@ export const createContentClient = ({
             : !platformUrl
               ? 'PLATFORM_URL is unset'
               : 'PAYLOAD_API_KEY is unset'
-        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.4 pair\` writes both.`,
+        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.5 pair\` writes both.`,
       )
     }
     return true

package/src/site/defineSite.ts

@@ -1,3 +1,4 @@
+import { FormsSchema, type FormDeclaration } from './forms'
 import { seedIssues, validateSchema, type BlockDecl, type CollectionDecl, type FieldDecl, type Issue, type Schema, type SeedKnown, type ZoneDecl } from '../elements'
 import { SLOT } from './documents'
 import type { BlockDef, CollectionDef, LayoutDef, PageDef, PageTypeDef, Seo, Singles, Site, SiteManifest } from './types'
@@ -35,7 +36,8 @@ const misplacedZones = (decl: FieldDecl, at: string, direct: boolean, into: Issu
 const PAGE_KEY = /^[a-z][a-zA-Z0-9_-]*$/
 const strip = (fields: Record<string, unknown>) => Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, JSON.parse(JSON.stringify(v))])) as Record<string, FieldDecl>
 
-export function defineSite(input: { singles: Singles; collections: Record<string, CollectionDef>; layouts: Record<string, LayoutDef>; pages: Record<string, PageDef>; pageTypes: Record<string, PageTypeDef>; seo?: Seo; knowledge?: KnowledgePolicyV1 }): Site {
+export function defineSite(input: { singles: Singles; collections: Record<string, CollectionDef>; layouts: Record<string, LayoutDef>; pages: Record<string, PageDef>; pageTypes: Record<string, PageTypeDef>; seo?: Seo; knowledge?: KnowledgePolicyV1; forms?: FormDeclaration[] }): Site {
+  const forms = input.forms === undefined ? undefined : FormsSchema.parse(input.forms)
   const defaults = Object.entries(input.layouts).filter(([, l]) => l.default)
   if (defaults.length !== 1) throw new Error(`A site needs exactly one default layout; found ${defaults.length}.`)
   const defaultLayout = defaults[0][0]
@@ -96,7 +98,7 @@ export function defineSite(input: { singles: Singles; collections: Record<string
   const schema: Schema = {
     blocks: Object.fromEntries([...blocks.values()].map((b) => [b.name, { name: b.name, label: b.label, fields: strip(b.fields), ...(b.shared ? { shared: b.shared } : {}), ...(b.entry ? { entry: b.entry.name } : {}), order: Object.keys(b.fields) } satisfies BlockDecl])),
     collections: Object.fromEntries(Object.values(input.collections).map((c) => [c.name, { name: c.name, label: c.label, fields: strip(c.fields), ...(c.authoring ? { authoring: JSON.parse(JSON.stringify(c.authoring)) } : {}), ...(c.template ? { template: JSON.parse(JSON.stringify(c.template.zone)) } : {}), ...(c.defaultSort ? { defaultSort: c.defaultSort } : {}), order: Object.keys(c.fields) } satisfies CollectionDecl])),
-    singles: Object.fromEntries(Object.values(input.singles).map((s) => [s.key, { key: s.key, field: JSON.parse(JSON.stringify(s.decl)) }])),
+    singles: Object.fromEntries(Object.values(input.singles).map((s) => [s.key, { key: s.key, ...(s.editor ? { editor: s.editor } : {}), field: JSON.parse(JSON.stringify(s.decl)) }])),
   }
   // Finding 1: seed entries were checked only when seeded, at the platform or in the defaults store.
   const known: SeedKnown = {
@@ -106,6 +108,7 @@ export function defineSite(input: { singles: Singles; collections: Record<string
   const badSeeds = Object.values(input.collections).flatMap((c) => (c.entries ?? []).flatMap((e) => seedIssues(schema, { kind: 'entry', collection: c.name }, { fields: e.fields, blocks: e.blocks }, `collections.${c.name}.entries.${e.slug}`, known)))
   if (badSeeds.length) throw new SiteDeclarationError(badSeeds)
   return {
+    ...(forms !== undefined ? { forms } : {}),
     ...(input.knowledge !== undefined ? { knowledge: input.knowledge } : {}),
     singles: input.singles, collections: input.collections, blocks: Object.fromEntries(blocks), schema, seo: input.seo ?? {}, defaultLayout,
     layouts: Object.fromEntries(Object.entries(input.layouts).map(([k, l]) => [k, { default: !!l.default, parent: l.parent, blocks: l.entries.map((e) => (e === SLOT ? 'SLOT' : e.name)) }])),
@@ -128,5 +131,5 @@ export function manifestFrom(site: Site): SiteManifest {
     pageTypes: Object.keys(site.pageTypes),
     layouts: Object.keys(site.layouts),
   }
-  return { ...(site.knowledge !== undefined ? { knowledge: site.knowledge } : {}), schema: r.schema, layouts: site.layouts, pages: site.pages, pageTypes: site.pageTypes, entries, collections, routes, seo: site.seo, bridgeVersion: 4, siteKitVersion: SITE_KIT_VERSION, order }
+  return { ...(site.forms !== undefined ? { forms: FormsSchema.parse(site.forms) } : {}), ...(site.knowledge !== undefined ? { knowledge: site.knowledge } : {}), schema: r.schema, layouts: site.layouts, pages: site.pages, pageTypes: site.pageTypes, entries, collections, routes, seo: site.seo, bridgeVersion: 4, siteKitVersion: SITE_KIT_VERSION, order }
 }

package/src/site/documents.ts

@@ -4,8 +4,8 @@ import type { BlockDef, CollectionDef, Decl, EntrySeed, Fields, LayoutDef, PageD
 export const SLOT = 'SLOT' as const
 export const humanise = (name: string) => name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase())
 
-export const defineSingles = <M extends Record<string, Decl<unknown>>>(map: M): { [K in keyof M]: SingleDef<M[K] extends Decl<infer R> ? R : never> } =>
-  Object.fromEntries(Object.entries(map).map(([key, decl]) => [key, { key, decl }])) as never
+export const defineSingles = <M extends Record<string, Decl<unknown>>>(map: M, authoring: Partial<Record<keyof M, { editor: 'cms' | 'canvas' }>> = {}): { [K in keyof M]: SingleDef<M[K] extends Decl<infer R> ? R : never> } =>
+  Object.fromEntries(Object.entries(map).map(([key, decl]) => [key, { key, decl, ...authoring[key] }])) as never
 export const collection = <F extends Fields>(name: string, o: { label?: string; fields: F; route?: string; defaultSort?: CollectionDef['defaultSort']; entries?: EntrySeed[]; authoring?: CollectionDef['authoring'] }): CollectionDef<F> =>
   ({ kind: 'collection', name, label: o.label ?? humanise(name), fields: o.fields, route: o.route, defaultSort: o.defaultSort, ...(o.authoring ? { authoring: o.authoring } : {}), ...(o.entries ? { entries: o.entries } : {}) })
 export const withTemplate = <C extends CollectionDef>(c: C, zone: Decl<unknown>, o: { layout?: string } = {}): C =>

package/src/site/forms.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+const identifier = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/).max(100)
+const label = z.string().trim().min(1).max(200)
+export const FormFieldSchema = z.strictObject({
+ name: identifier, label,
+ type: z.enum(['checkbox', 'date', 'email', 'number', 'select', 'tel', 'text', 'textarea']),
+ required: z.boolean().optional(), role: z.enum(['email', 'name', 'phone']).optional(),
+ options: z.array(label).max(200).optional(),
+}).superRefine((field, ctx) => {
+ if (field.type === 'select' && !field.options?.length) ctx.addIssue({ code: 'custom', path: ['options'], message: 'Select fields need options.' })
+ if (field.options && new Set(field.options).size !== field.options.length) ctx.addIssue({ code: 'custom', path: ['options'], message: 'Options must be unique.' })
+})
+export const FormDeclarationSchema = z.strictObject({
+ slug: identifier, label, fields: z.array(FormFieldSchema).min(1).max(100),
+ recipients: z.array(z.email()).max(50).optional(),
+}).superRefine((form, ctx) => {
+ const names = new Set<string>()
+ form.fields.forEach((field, i) => {
+  if (names.has(field.name)) ctx.addIssue({ code: 'custom', path: ['fields', i, 'name'], message: 'Field names must be unique.' })
+  names.add(field.name)
+ })
+})
+export const FormsSchema = z.array(FormDeclarationSchema).max(100).superRefine((forms, ctx) => {
+ const slugs = new Set<string>()
+ forms.forEach((form, i) => {
+  if (slugs.has(form.slug)) ctx.addIssue({ code: 'custom', path: [i, 'slug'], message: 'Form slugs must be unique.' })
+  slugs.add(form.slug)
+ })
+})
+export type FormDeclaration = z.infer<typeof FormDeclarationSchema>
+export type FormFieldDeclaration = z.infer<typeof FormFieldSchema>

package/src/site/index.ts

@@ -15,3 +15,5 @@ export { sitemapFor } from '../seo/sitemap'
 
 export { SeoSeedsSchema, DocumentSeoSeedSchema, SiteSeoSeedSchema, seoSeedIssues, seoSeedAssets, type SeoSeeds, type DocumentSeoSeed, type SiteSeoSeed } from '../seo/seeds'
 export { CollectionViewSchema, CollectionViewsSchema, collectionViewFields, defaultCollectionView, reconcileCollectionView, validateCollectionView, collectionViewsIssues, type CollectionView, type CollectionViews, type CollectionViewField } from './formView'
+
+export { FormsSchema, FormDeclarationSchema, FormFieldSchema, type FormDeclaration, type FormFieldDeclaration } from './forms'

package/src/site/types.ts

@@ -1,4 +1,5 @@
 import type { KnowledgePolicyV1 } from '../features/contracts/knowledgePolicy'
+import type { FormDeclaration } from './forms'
 import type { ReactNode } from 'react'
 import type { BlockDecl, CollectionDecl, FieldDecl, GroupDecl, LeafDecl, ListDecl, Schema, SingleDecl, ZoneDecl } from '../elements'
 
@@ -20,7 +21,7 @@ export type Simplify<T> = { [K in keyof T]: T[K] } & {}
  */
 export type ZoneNode = ReactNode
 
-export type SingleDef<R = unknown> = { key: string; decl: Decl<R> }
+export type SingleDef<R = unknown> = { key: string; decl: Decl<R>; editor?: 'cms' | 'canvas' }
 export type Singles = Record<string, SingleDef>
 /**
  * An entry a collection starts with: its slug (also the key a seed's `{ $ref: { key } }` names it
@@ -45,6 +46,7 @@ export type Seo = { titleTemplate?: string; defaultImage?: string; organisation?
 
 export type Site = {
   knowledge?: KnowledgePolicyV1
+  forms?: FormDeclaration[]
   singles: Singles; collections: Record<string, CollectionDef>
   layouts: Record<string, { default: boolean; parent?: string; blocks: string[] }>
   pages: Record<string, { route: string; layout: string; blocks: ZoneDecl }>
@@ -53,6 +55,7 @@ export type Site = {
 }
 export type SiteManifest = {
   knowledge?: KnowledgePolicyV1
+  forms?: FormDeclaration[]
   schema: Schema
   layouts: Site['layouts']; pages: Site['pages']; pageTypes: Site['pageTypes']
   /** Each collection's declared seed entries, by collection name; collections that declare none are absent. */

package/src/site/version.ts

@@ -1 +1 @@
-export const SITE_KIT_VERSION = '1.6.4'
+export const SITE_KIT_VERSION = '1.6.5'