@unitninety/site-kit 1.6.1 → 1.6.2

package/README.md

@@ -5,9 +5,27 @@ 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.0 --version
+npx --yes @unitninety/u90@1.0.1 --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).
+
+### Immediate collection-list previews
+
+Render a query's `EntriesRead` with `Entries` from `@unitninety/site-kit/components` when its
+cards should reorder and disappear immediately in Canvas. Pass the complete value, including
+its draft `$path`, and render one card per entry:
+
+```tsx
+<Entries value={projects} className="project-grid" empty={<p>No projects yet.</p>}>
+  {entry => <ProjectCard entry={entry} />}
+</Entries>
+```
+
+The card renderer runs on the server. In draft mode React owns the keyed cards and preserves
+pending order/removal through slow refreshes; rejected saves reconcile to the server result.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "The client-site half of the UnitNinety platform contract: schema authoring, content fetching, the editing bridge and the pairing CLI.",
   "type": "module",
   "exports": {

package/src/bridge/DraftEntries.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import { Fragment, useLayoutEffect, useRef, useState, type HTMLAttributes, type ReactNode } from 'react'
+import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+import { registry } from './registry'
+
+export type EntryItem = { id: string; content: ReactNode }
+export type EntryPicks = { order: string[]; exclude: string[]; pin: string[] }
+
+function picked(items: EntryItem[], picks: EntryPicks, pins: readonly string[]): EntryItem[] {
+  const excluded = new Set([...picks.exclude, ...pins.filter(id => !picks.pin.includes(id))])
+  const ranks = new Map(picks.order.map((id, index) => [id, index]))
+  return items.filter(item => !excluded.has(item.id)).sort((a, b) =>
+    (ranks.get(a.id) ?? Infinity) - (ranks.get(b.id) ?? Infinity))
+}
+
+/** React owns the cards so pending picks survive a slow server refresh without a DOM undo flash. */
+export function DraftEntries({ path, items, pins, empty, ...props }: HTMLAttributes<HTMLDivElement> & { path: string; items: EntryItem[]; pins: string[]; empty?: ReactNode }) {
+  const host = useRef<HTMLDivElement>(null)
+  const [shown, setShown] = useState({ source: items, pins, items, picks: null as EntryPicks | null })
+  const current = shown.source === items ? shown.items : shown.picks === null ? items : picked(items, shown.picks, pins)
+  if (shown.source !== items) setShown({ ...shown, source: items, pins, items: current })
+
+  useLayoutEffect(() => {
+    const handler = {
+      document: host.current!.ownerDocument,
+      // Clear only the picks included when this refresh starts, retaining the visible cards
+      // until its response arrives. A subsequent edit remains active across that older response.
+      beforeRefresh: () => setShown(value => ({ ...value, picks: null })),
+      pick: (at: string, picks: EntryPicks) => {
+        if (at !== path) return false
+        setShown(value => ({ ...value, items: picked(value.source, picks, value.pins), picks }))
+        return true
+      },
+    }
+    registry.entryLists.add(handler)
+    return () => { registry.entryLists.delete(handler) }
+  }, [path])
+
+  return <PreviewCommitBoundary source={items}><div {...props} data-u90-field={path} ref={host}>{current.length ? current.map(item => <Fragment key={item.id}>{item.content}</Fragment>) : empty}</div></PreviewCommitBoundary>
+}

package/src/bridge/createBridge.ts

@@ -529,7 +529,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
     else if (refreshAgain) requestRefresh()
   }
   function requestRefresh() {
-    if (refreshing && [...registry.blockOrders].some((owner) => owner.document === doc)) {
+    if (refreshing && [...registry.blockOrders, ...registry.entryLists].some((owner) => owner.document === doc)) {
       refreshAgain = true
       return
     }
@@ -540,7 +540,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
     }
     // One refresh boundary at a time: newer moves stay visible through the older render.
     // Clear only the moves included when THIS request starts, never when another is queued.
-    for (const owner of registry.blockOrders) if (owner.document === doc) owner.beforeRefresh()
+    for (const owner of [...registry.blockOrders, ...registry.entryLists]) if (owner.document === doc) owner.beforeRefresh()
     const restoreEditing = preserveEditing()
     try {
       undoPreviews()
@@ -554,6 +554,11 @@ export function createBridge(win: Window, opts: BridgeOptions) {
   const preview = (instruction: PreviewInstruction) => {
     // React-owned order is safe even while a refresh is pending. Only legacy DOM moves
     // still need the guard below; they can disagree with React's tree during a commit.
+    if (instruction.kind === 'entries') {
+      // All renderings of this placement update, including duplicate responsive layouts.
+      for (const owner of registry.entryLists) if (owner.document === doc) owner.pick(instruction.path, instruction)
+      return
+    }
     if (instruction.kind === 'move') {
       for (const owner of registry.blockOrders) {
         if (owner.document === doc && owner.move(instruction.path, instruction.before)) return

package/src/bridge/protocol.ts

@@ -57,6 +57,7 @@ const isBridgeLinkTarget = (to: unknown): to is LinkTo => {
  * `before` names the sibling to insert in front of; `null` appends.
  */
 export type PreviewInstruction =
+  | { kind: 'entries'; path: string; order: string[]; exclude: string[]; pin: string[] }
   | { kind: 'move'; path: string; before: string | null }
   | { kind: 'remove'; path: string }
   | { kind: 'media'; path: string; src: string }
@@ -75,7 +76,7 @@ export type PreviewInstruction =
    */
   | { kind: 'fragment'; path: string; block: string }
 
-const PREVIEW_KINDS = new Set(['move', 'remove', 'media', 'text', 'link-label', 'rich', 'insert', 'replace', 'fragment'])
+const PREVIEW_KINDS = new Set(['entries', 'move', 'remove', 'media', 'text', 'link-label', 'rich', 'insert', 'replace', 'fragment'])
 const isBefore = (v: unknown): boolean => v === null || typeof v === 'string'
 
 /** Whether a `u90:preview`'s instruction has a known kind and a well-formed payload. */
@@ -83,6 +84,7 @@ const isPreviewInstruction = (value: unknown): value is PreviewInstruction => {
   if (!(value && typeof value === 'object')) return false
   const r = value as Record<string, unknown>
   if (typeof r.kind !== 'string' || !PREVIEW_KINDS.has(r.kind) || typeof r.path !== 'string') return false
+  if (r.kind === 'entries') return [r.order, r.exclude, r.pin].every(ids => Array.isArray(ids) && ids.every(id => typeof id === 'string'))
   if (r.kind === 'media') return typeof r.src === 'string'
   if (r.kind === 'text' || r.kind === 'link-label') return typeof r.value === 'string'
   if (r.kind === 'rich') return Array.isArray(r.paragraphs) && r.paragraphs.every((paragraph) => typeof paragraph === 'string')

package/src/bridge/registry.ts

@@ -1,3 +1,4 @@
+import type { EntryPicks } from './DraftEntries'
 import type { Bridge } from './createBridge'
 
 /**
@@ -19,9 +20,11 @@ import type { Bridge } from './createBridge'
 export const registry: {
   current: Bridge | null
   reveals: Set<{ prefix: string; fn: () => void }>
+  entryLists: Set<{ document: Document; beforeRefresh(): void; pick(path: string, picks: EntryPicks): boolean }>
   blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; move(path: string, before: string | null): boolean }>
 } = {
   current: null,
   reveals: new Set(),
   blockOrders: new Set(),
+  entryLists: new Set(),
 }

package/src/components/Entries.tsx

@@ -0,0 +1,16 @@
+import { Fragment, type HTMLAttributes, type ReactNode } from 'react'
+import type { EntryRead } from '../elements/define'
+import type { EntriesRead } from '../elements/leaves/selection'
+import { DraftEntries } from '../bridge/DraftEntries'
+
+/** A placement-aware list of server-rendered cards. Draft picks update immediately in Canvas;
+ * published lists remain ordinary server markup. The renderer never crosses the client boundary. */
+export function Entries({ value, children, empty, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+  value: EntriesRead
+  children: (entry: EntryRead) => ReactNode
+  empty?: ReactNode
+}) {
+  const items = value.entries.map(entry => ({ id: String(entry.id), content: children(entry) }))
+  if (value.$path) return <DraftEntries key={value.$path} path={value.$path} items={items} pins={value.$pins ?? []} empty={empty} {...props} />
+  return <div {...props}>{items.length ? items.map(item => <Fragment key={item.id}>{item.content}</Fragment>) : empty}</div>
+}

package/src/components/index.ts

@@ -1,3 +1,4 @@
+export { Entries } from './Entries'
 export { Text } from './Text'
 export { RichText, richTextNodes } from './RichText'
 export { Link, isInternal } from './Link'

package/src/elements/leaves/query.ts

@@ -77,7 +77,7 @@ const stored = (o: O) =>
         ctx.addIssue({ code: 'custom', path: [k], message: 'Each entry may be listed once.', params: { code: 'duplicate' } })
     }
   })
-const expand = (v: QueryStored, o: O, ctx: ExpandCtx): EntriesRead => ({ ...ctx.query(o.to, v), ...(ctx.draft ? { $path: ctx.at } : {}) })
+const expand = (v: QueryStored, o: O, ctx: ExpandCtx): EntriesRead => ({ ...ctx.query(o.to, v), ...(ctx.draft ? { $path: ctx.at, $pins: (v.pin ?? []).map(String) } : {}) })
 
 export const query = defineElement({
   id: 'u90/query',

package/src/elements/leaves/selection.ts

@@ -5,8 +5,8 @@ import { EntryRef, resolveEntryRef, uniqueIds } from './relation'
 export const SelectionOptions = z.strictObject({ to: z.string().min(1), many: z.boolean().default(false), max: z.int().positive().optional(), depth: z.int().min(0).max(3).default(1) })
 type O = z.infer<typeof SelectionOptions>
 /** How a selection and a query read: the entries in order, how many there are, and `$path` in draft. */
-export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string }
-export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional() })
+export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string; $pins?: string[] }
+export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional(), $pins: z.array(z.string()).optional() })
 
 const stored = (o: O) => (o.many ? (o.max ? z.array(Id).max(o.max) : z.array(Id)).superRefine(uniqueIds) : Id.nullable())
 type SeedValue = z.infer<typeof EntryRef> | z.infer<typeof EntryRef>[] | null

package/src/legacy/cli.mjs

@@ -2,7 +2,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 
 /**
- * `npx --yes @unitninety/u90@1.0.0 pair <code>` — the one command an operator hands over. The u90 tool
+ * `npx --yes @unitninety/u90@1.0.1 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.0 pair <code> --site https://example.com [--platform https://cms…]')
+    fail('Usage: npx --yes @unitninety/u90@1.0.1 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.0 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.1 pair\` writes both.`,
       )
     }
     return true

package/src/site/version.ts

@@ -1 +1 @@
-export const SITE_KIT_VERSION = '1.6.1'
+export const SITE_KIT_VERSION = '1.6.2'