@unitninety/site-kit 1.7.0 → 1.8.0

package/README.md

@@ -5,7 +5,7 @@ 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.1.0 --version
+npx --yes @unitninety/u90@1.2.0 --version
 ```
 
 UnitNinety imports packages made for that version only, so keep the version the tool names.
@@ -84,9 +84,43 @@ Call the hook on native reads before converting them for a presentation componen
 
 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 ordinary-list reordering
+
+Use `List` for repeated content such as service lines, navigation links and FAQ rows. It
+keeps existing rows and their media mounted while their order changes, before saving finishes:
+
+```tsx
+import { List, Text, draftFieldPath } from '@unitninety/site-kit/components'
+
+export function Services(props) {
+  return <List as="ul" value={props.lines} draftPath={draftFieldPath(props, 'lines')}>
+    {line => <li><Text value={line.name} as="h3" /></li>}
+  </List>
+}
+```
+
+The callback runs in the component that renders `List`; only rendered slots cross the client
+boundary. Server-only imports and async card children can stay on the server. `List` replaces the existing container: set `as` to its original tag and keep its attributes.
+It adds no extra DOM wrapper, so list, table and grid markup retain their structure. Published
+lists remain ordinary server markup. Group rows retain their native `_id` and `$path`; nullable
+leaf lists can pass `itemPaths={props.$listPaths?.photos}` when their paths live on the owner.
+Never use a row's label or array index as its draft identity.
+
+`List` immediately reorders existing items. New items and content replacements still arrive
+from the authoritative server render. For immediate additions and full field previews, use a
+client component with `useDraftPreview(props)` before reading its fields. Use `Entries` for
+collection placements. A plain server-side `.map()` has no live list owner and waits for the
+save/refresh even with the latest Site Kit installed. If row content depends on the current
+array index (such as a numbered label), use `useDraftPreview` so it recomputes immediately.
+
+Verify with the response held back: move a row, confirm the visible order immediately, move
+another row during the pending save, then release the response and confirm the saved order.
+Retain image nodes and dimensions throughout. Failed saves must restore the saved order.
+Server HTML checks alone cannot establish hydration or immediate browser updates.
+
 ### Stable block reorder previews
 
-Site Kit 1.6.6 keeps existing block content mounted while Canvas changes its order, including hidden destinations and repeated responsive views. The default `useDraftPreview(source)` preserves native field objects and pending edits instead of expanding a whole zone snapshot again.
+Site Kit keeps existing block content mounted while Canvas changes its order, including hidden destinations and repeated responsive views. Since 1.8.0, the same order-only path covers ordinary and nested lists, preserving resolved images and presentation values. The default `useDraftPreview(source)` preserves native field objects and pending edits instead of expanding a whole structural snapshot again.
 
 Custom presentation adapters retain their existing snapshot behavior. If every rendered block collection keeps its native `$path` values, opt into the shared order adapter:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "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/DraftList.tsx

@@ -0,0 +1,46 @@
+'use client'
+
+import { createElement, Fragment, useCallback, useLayoutEffect, useMemo, useRef, type JSX, type ReactNode } from 'react'
+import { useDraftPreview } from './useDraftContent'
+import { applyNativeOrder, type DraftOrder } from './nativeOrder'
+import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+import { needsEmbedReload, preserveBlockMoves } from './preserveBlockMoves'
+import { registry } from './registry'
+
+type Item = { id: string; $path: string; content: ReactNode }
+type Slots = { $path: string; $fieldPaths: { items: string }; items: Item[] }
+export type ListTag = keyof HTMLElementTagNameMap & keyof JSX.IntrinsicElements
+// Server-rendered slots have no client renderer for new values. Only a pure order
+// changes locally; membership and content continue to arrive from the saved render.
+const keepSlots = <T,>(source: T): T => source
+
+export function DraftList({ as, attributes, path, items }: { as: ListTag; attributes: Record<string, unknown>; path: string; items: Item[] }) {
+  const host = useRef<HTMLElement | null>(null)
+  const reload = useRef(false)
+  const attach = useCallback((element: HTMLElement | null) => {
+    host.current = element
+    const cleanup = preserveBlockMoves(element)
+    return () => { cleanup?.(); if (host.current === element) host.current = null }
+  }, [])
+  const reorder = useCallback((source: Slots, order: DraftOrder): Slots => {
+    const result = applyNativeOrder(source, order)
+    if (!result.matched) return source
+    if (result.value !== source && host.current && needsEmbedReload(host.current)) {
+      reload.current = true
+      // Acknowledge this order without moving a live iframe. The bridge reloads
+      // the saved page instead of allowing its legacy DOM fallback to move it.
+      return { ...source }
+    }
+    // Custom adapters signal ownership by returning a new value, even if the
+    // requested order is already visible (for example a duplicate snapshot).
+    return result.value === source ? { ...source } : result.value
+  }, [])
+  const source = useMemo(() => ({ $path: path, $fieldPaths: { items: path }, items }), [path, items])
+  const live = useDraftPreview(source, keepSlots, reorder)
+  useLayoutEffect(() => {
+    const owner = { document: host.current?.ownerDocument ?? document, beforeRefresh() {}, needsReload: () => reload.current, move: () => false }
+    registry.blockOrders.add(owner)
+    return () => { registry.blockOrders.delete(owner) }
+  }, [])
+  return <PreviewCommitBoundary source={items}>{createElement(as, { ...attributes, ref: attach }, live.items.map(item => <Fragment key={item.id}>{item.content}</Fragment>))}</PreviewCommitBoundary>
+}

package/src/bridge/nativeOrder.ts

@@ -1,23 +1,36 @@
 import { rememberDraftList } from '../elements/ops/draftPaths'
 import { nativeChildPath, nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from './nativePath'
 import type { DraftSnapshot } from './protocol'
+import type { FieldDecl } from '../elements/define'
 
 export type DraftOrder = { path: string; ids: string[] }
 export type NativeDraftOrder = DraftOrder
 const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
 
-/** A move's snapshot may start above its zone (for example a zone inside a group).
- * Read only the target's IDs; reconstructing its fields would discard site adapters. */
+/** A move's snapshot may start above its list/zone. Read only stable IDs:
+ * expanding a reorder would replace already-resolved media and presentation values. */
 export function snapshotOrder(snapshot: DraftSnapshot, movedPath: string): DraftOrder | undefined {
   const path = movedPath.slice(0, movedPath.lastIndexOf('/'))
   if (!safeDraftPath(path) || (path !== snapshot.path && !path.startsWith(`${snapshot.path}/`))) return
   let value: unknown = snapshot.value
+  let field: FieldDecl | undefined = snapshot.field
   for (const key of path.slice(snapshot.path.length).split('/').filter(Boolean)) {
     if (unsafe.has(key)) return
-    value = Array.isArray(value) ? value.find(item => item?._id === key)
-      : value && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, unknown>)[key] : undefined
+    if (Array.isArray(value)) {
+      value = value.find(item => item?._id === key)
+      if (field && 'container' in field && field.container === 'u90/list') {
+        field = field.item
+      } else if (field && 'container' in field && field.container === 'u90/zone') {
+        const block = value && typeof value === 'object' && '_block' in value ? snapshot.blocks?.[String(value._block)] : undefined
+        field = block ? { container: 'u90/group', fields: block.fields } : undefined
+      } else field = undefined
+    } else {
+      value = value && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, unknown>)[key] : undefined
+      field = field && 'container' in field && field.container === 'u90/group' && Object.hasOwn(field.fields, key) ? field.fields[key] : undefined
+    }
   }
-  if (!Array.isArray(value) || !value.every(item => item && typeof item._id === 'string' && typeof item._block === 'string')) return
+  const list = field && 'container' in field && field.container === 'u90/list'
+  if (!Array.isArray(value) || !value.every(item => item && typeof item._id === 'string' && (list || typeof item._block === 'string'))) return
   const ids = value.map(item => item._id as string)
   if (new Set(ids).size !== ids.length || !ids.includes(movedPath.slice(path.length + 1))) return
   return { path, ids }

package/src/bridge/preserveBlockMoves.ts

@@ -53,7 +53,7 @@ function restoreSheets(snapshots: SheetSnapshot[]) {
  * prototype changes. Atomic moves keep iframes/focus alive where supported. Both
  * kinds of move need the CSSOM safeguard for styles in an embedded shadow root.
  */
-export function preserveBlockMoves(host: HTMLDivElement | null): void | (() => void) {
+export function preserveBlockMoves(host: HTMLElement | null): void | (() => void) {
   if (!host) return
   const atomic = host as AtomicHost
   const insert = host.insertBefore

package/src/components/List.tsx

@@ -0,0 +1,26 @@
+import { createElement, Fragment, type ComponentPropsWithoutRef, type ReactNode } from 'react'
+import { DraftList, type ListTag } from '../bridge/DraftList'
+import { nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from '../bridge/nativePath'
+
+type Props<T, Tag extends ListTag> = { as: Tag; value: T[]; draftPath?: string; itemPaths?: readonly string[]; children: (item: T, index: number) => ReactNode }
+  & Omit<ComponentPropsWithoutRef<Tag>, 'as' | 'value' | 'children' | 'dangerouslySetInnerHTML'>
+
+/** Server-safe list rendering with immediate draft ordering. Replace the existing
+ * container with List as="ul" (or its original tag), preserving its attributes.
+ * The item renderer runs here; only rendered slots cross the client boundary. */
+export function List<T, Tag extends ListTag>({ as, value, draftPath, itemPaths, children, ...attributes }: Props<T, Tag>) {
+  const paths = itemPaths ?? nativeListPaths(value)
+  const first = paths?.[0]
+  const path = draftPath ?? (first ? first.slice(0, first.lastIndexOf('/')) : nativePath(value))
+  if (!path) return createElement(as, attributes, value.map((item, index) => <Fragment key={(item as { _id?: string } | null)?._id ?? index}>{children(item, index)}</Fragment>))
+  if (!safeDraftPath(path)) throw new Error('List requires a valid draft path.')
+  const seen = new Set<string>()
+  const items = value.map((item, index) => {
+    const at = nativeListItemPath(value, index, paths, path)
+    const id = at?.startsWith(`${path}/`) ? at.slice(path.length + 1) : undefined
+    if (!id || id.includes('/') || seen.has(id)) throw new Error('Draft List items require unique stable paths. Pass itemPaths for nullable leaf lists.')
+    seen.add(id)
+    return { id, $path: at!, content: children(item, index) }
+  })
+  return <DraftList key={path} as={as} attributes={attributes} path={path} items={items}/>
+}

package/src/components/index.ts

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

package/src/legacy/cli.mjs

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

package/src/site/version.ts

@@ -1 +1 @@
-export const SITE_KIT_VERSION = '1.7.0'
+export const SITE_KIT_VERSION = '1.8.0'