@bespokeagentics/microdots-host 0.1.2 → 0.2.0

package/src/renderLayout.test.ts

@@ -0,0 +1,263 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { renderLayout } from './renderLayout.ts'
+import { ensureSection, ensureSlot, pruneGeneratedContainers } from './slotDom.ts'
+import { generatedSectionId } from './slotLayout.ts'
+import type { SlotSpec } from './slots.ts'
+
+/**
+ * The reconciler's contract, clause by clause — every one of these fails
+ * silently in the browser when broken: a slot div without an id renders
+ * nothing on a clean console; a rebuild instead of a reconcile restarts
+ * every mounted custom element on every poll; a prune of a non-empty slot
+ * throws away a user's mounted dot.
+ */
+
+const slot = (
+  overrides: Partial<SlotSpec> & Pick<SlotSpec, 'id'>,
+): SlotSpec => ({
+  kind: 'band',
+  row: 0,
+  ...overrides,
+})
+
+const manifestOf = (slots: ReadonlyArray<SlotSpec>): { slots: ReadonlyArray<SlotSpec> } => ({
+  slots,
+})
+
+let root: HTMLElement
+
+beforeEach(() => {
+  document.body.replaceChildren()
+  root = document.createElement('div')
+  root.id = 'generated-layout'
+  document.body.appendChild(root)
+})
+
+const MARKETING = [
+  slot({ id: 'site-header', kind: 'bar', row: 0, label: 'Header' }),
+  slot({ id: 'hero', kind: 'band', row: 1, label: 'Hero', description: 'The lead.' }),
+  slot({ id: 'sidebar', kind: 'rail', row: 2, width: '150px', label: 'Sidebar' }),
+  slot({ id: 'main', kind: 'grid', row: 2, label: 'Main' }),
+  slot({ id: 'aside', kind: 'rail', row: 2, width: '172px', label: 'Aside' }),
+]
+
+describe('renderLayout — creation', () => {
+  test('every created slot div carries its declared id — the invariant', () => {
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.created).toBe(5)
+    MARKETING.forEach(s => {
+      const div = document.getElementById(s.id)
+      expect(div).not.toBeNull()
+      expect(div?.getAttribute('data-microdots-layout')).toBe('slot')
+      expect(document.getElementById(generatedSectionId(s.id))).not.toBeNull()
+    })
+  })
+
+  test('rows group as declared: three row divs, the middle row holds rail/grid/rail', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const rows = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )
+    expect(rows.length).toBe(3)
+    const middle = rows[2]
+    expect(
+      Array.from(middle?.children ?? []).map(el => el.id),
+    ).toEqual(['section-sidebar', 'section-main', 'section-aside'])
+  })
+
+  test('label and description render in section chrome, not in the slot div', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroSection = document.getElementById('section-hero')
+    expect(heroSection?.textContent).toContain('Hero')
+    expect(heroSection?.textContent).toContain('The lead.')
+    expect(document.getElementById('hero')?.childElementCount).toBe(0)
+  })
+
+  test('geometry lands as inline styles: fixed rail width via the resize var, grid columns', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const sidebarSection = document.getElementById('section-sidebar')
+    expect(sidebarSection?.getAttribute('style')).toContain(
+      'var(--slot-size-sidebar,150px)',
+    )
+    const mainSlot = document.getElementById('main')
+    expect(mainSlot?.getAttribute('style')).toContain(
+      'repeat(12, minmax(0, 1fr))',
+    )
+  })
+
+  test('a generated host with no manifest renders an empty layout (D6)', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const report = renderLayout(manifestOf([]), root)
+    expect(report.removed).toBe(5)
+    expect(root.querySelectorAll('section').length).toBe(0)
+    expect(root.children.length).toBe(0)
+  })
+})
+
+describe('renderLayout — idempotence and reconciliation', () => {
+  test('equal input keeps node identity and reports all zeros', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroBefore = document.getElementById('section-hero')
+    const slotBefore = document.getElementById('hero')
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report).toEqual({
+      created: 0,
+      relabelled: 0,
+      moved: 0,
+      removed: 0,
+      deferred: [],
+    })
+    expect(document.getElementById('section-hero')).toBe(heroBefore)
+    expect(document.getElementById('hero')).toBe(slotBefore)
+  })
+
+  test('a copy edit reconciles textContent in place — no remount of the mounted child', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const mounted = document.createElement('div')
+    mounted.textContent = 'a mounted dot'
+    document.getElementById('hero')?.appendChild(mounted)
+
+    const edited = MARKETING.map(s =>
+      s.id === 'hero' ? { ...s, label: 'Big hero', description: 'New copy.' } : s,
+    )
+    const report = renderLayout(manifestOf(edited), root)
+    expect(report.relabelled).toBe(1)
+    expect(report.moved).toBe(0)
+    expect(document.getElementById('section-hero')?.textContent).toContain(
+      'Big hero',
+    )
+    // The mounted element is the SAME node — copy never remounts.
+    expect(document.getElementById('hero')?.firstElementChild).toBe(mounted)
+  })
+
+  test('a row move relocates only the affected section and reports it', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroSection = document.getElementById('section-hero')
+    const moved = MARKETING.map(s => (s.id === 'hero' ? { ...s, row: 2 } : s))
+    const report = renderLayout(manifestOf(moved), root)
+    expect(report.moved).toBe(1)
+    expect(report.created).toBe(0)
+    // Same node, new row div — the move is a reparent, not a rebuild.
+    expect(document.getElementById('section-hero')).toBe(heroSection)
+    const rows = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )
+    expect(rows[1]?.querySelector('#section-hero')).not.toBeNull()
+  })
+
+  test('an in-row order swap moves exactly one section', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const swapped = [
+      MARKETING[0],
+      MARKETING[1],
+      MARKETING[3], // main before sidebar
+      MARKETING[2],
+      MARKETING[4],
+    ].flatMap(s => (s === undefined ? [] : [s]))
+    const report = renderLayout(manifestOf(swapped), root)
+    expect(report.moved).toBe(1)
+    const middle = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )[2]
+    expect(Array.from(middle?.children ?? []).map(el => el.id)).toEqual([
+      'section-main',
+      'section-sidebar',
+      'section-aside',
+    ])
+  })
+
+  test('a kind flip clears the stale grid properties from the slot div', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const flipped = MARKETING.map(s =>
+      s.id === 'main' ? { ...s, kind: 'band' as const } : s,
+    )
+    renderLayout(manifestOf(flipped), root)
+    const style = document.getElementById('main')?.getAttribute('style') ?? ''
+    expect(style).not.toContain('grid-template-columns')
+    expect(style).toContain('flex-direction: column')
+  })
+
+  test('a resize variable set on the section survives re-render', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const section = document.getElementById('section-sidebar')
+    section?.style.setProperty('--slot-size-sidebar', '220px')
+    renderLayout(manifestOf(MARKETING), root)
+    expect(
+      document
+        .getElementById('section-sidebar')
+        ?.style.getPropertyValue('--slot-size-sidebar'),
+    ).toBe('220px')
+  })
+})
+
+describe('renderLayout — markup wins', () => {
+  test('a slot id owned by non-layout markup is untouched and deferred, with a warning', () => {
+    const stranger = document.createElement('div')
+    stranger.id = 'hero'
+    stranger.textContent = 'hand-written'
+    document.body.appendChild(stranger)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.deferred).toContain('hero')
+    expect(report.created).toBe(4)
+    expect(document.getElementById('hero')).toBe(stranger)
+    expect(stranger.textContent).toBe('hand-written')
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  test('a section id owned by non-layout markup defers the same way', () => {
+    const stranger = document.createElement('section')
+    stranger.id = 'section-hero'
+    document.body.appendChild(stranger)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.deferred).toContain('hero')
+    expect(document.getElementById('section-hero')).toBe(stranger)
+    warn.mockRestore()
+  })
+})
+
+describe('renderLayout — pruning', () => {
+  test('a stale empty section is pruned; a non-empty one is deferred until unmounted', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const mounted = document.createElement('div')
+    document.getElementById('hero')?.appendChild(mounted)
+
+    const withoutHeroAndHeader = MARKETING.filter(
+      s => s.id !== 'hero' && s.id !== 'site-header',
+    )
+    const report = renderLayout(manifestOf(withoutHeroAndHeader), root)
+    // site-header (empty) pruned; hero (mounted) deferred.
+    expect(report.removed).toBe(1)
+    expect(report.deferred).toEqual(['hero'])
+    expect(document.getElementById('section-site-header')).toBeNull()
+    expect(document.getElementById('section-hero')).not.toBeNull()
+
+    // The mount loop unmounts, the next pass completes the prune.
+    mounted.remove()
+    const second = renderLayout(manifestOf(withoutHeroAndHeader), root)
+    expect(second.removed).toBe(1)
+    expect(document.getElementById('section-hero')).toBeNull()
+  })
+
+  test('pruneGeneratedContainers never deletes a declared-but-empty generated slot', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    // The slotDom pruner looks for data-generated, which layout nodes never
+    // carry — the two generation paths are provably disjoint.
+    const removed = pruneGeneratedContainers(root)
+    expect(removed).toBe(0)
+    expect(document.getElementById('hero')).not.toBeNull()
+  })
+
+  test('slotDom-generated containers and layout sections coexist', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const section = ensureSection('legacy-section', root, 'x')
+    ensureSlot('legacy-slot', section, 'x')
+    const report = renderLayout(manifestOf(MARKETING), root)
+    // The reconciler leaves slotDom's containers alone entirely.
+    expect(report).toMatchObject({ created: 0, removed: 0 })
+    expect(document.getElementById('legacy-slot')).not.toBeNull()
+  })
+})

package/src/renderLayout.ts

@@ -0,0 +1,345 @@
+/**
+ * The generated-layout DOM reconciler — a manifest rendered AS the page.
+ *
+ * `slotDom.ts` is the authored-host fallback: markup wins, generation only
+ * backfills. This module is the inversion for a host that opted in
+ * (`layoutModeOf(topology) === 'generated'`): the DATA wins, and the DOM
+ * under `generatedRoot` is reconciled to match it — created, relabelled,
+ * moved and pruned in place rather than rebuilt, because rebuilding remounts
+ * every custom element on every poll.
+ *
+ * The contract, clause by clause (each one a test in
+ * `renderLayout.test.ts`):
+ *
+ * - Every created slot div receives its declared `id` unconditionally — the
+ *   repo's single most expensive failure is a mount container without one
+ *   (see `wiki/patterns-and-traps/mount-container-needs-an-id.md`).
+ * - Idempotent: equal input keeps node identity and reports all zeros.
+ * - An id already owned by non-layout markup is never touched: the slot is
+ *   `deferred` with a warning. Markup wins even in generated mode.
+ * - Label/description changes reconcile via `textContent` in place — copy
+ *   edits never remount a mounted dot.
+ * - A section moves only when its row or in-row order actually differs; a
+ *   structural move carries its mounted children with it, which restarts
+ *   them (ruling D11 — accepted v1 semantics, minimized here).
+ * - A stale section is pruned only while its slot div is EMPTY; a non-empty
+ *   one is `deferred` — the mount loop unmounts first, the next pass prunes.
+ * - Style application sets and removes only this module's own properties,
+ *   never `--slot-size-*` (a resize handle's writes survive every pass).
+ *
+ * Rows are unkeyed positional chrome; sections are keyed by slot id. The
+ * marker attribute is distinct from `slotDom.ts`'s `data-generated` so
+ * `pruneGeneratedContainers` provably never deletes a declared-but-empty
+ * generated slot.
+ */
+
+import type { SlotSpec } from './slots.ts'
+import {
+  generatedSectionId,
+  layoutRows,
+  rowStyle,
+  sectionStyle,
+  slotStyle,
+  type StylePairs,
+} from './slotLayout.ts'
+
+/** What a generated node IS: `row` and `chrome` are unkeyed structure,
+ *  `section` and `slot` are keyed by the slot's id. */
+export const LAYOUT_ATTRIBUTE = 'data-microdots-layout'
+
+export type RenderLayoutReport = {
+  readonly created: number
+  readonly relabelled: number
+  readonly moved: number
+  readonly removed: number
+  /** Slot ids left alone this pass: id collisions with non-layout markup,
+   *  and stale sections still holding mounted elements. */
+  readonly deferred: ReadonlyArray<string>
+}
+
+/** Every property either style function may emit — the removal catalog, so a
+ *  kind flip (grid → band) clears `grid-template-columns` instead of leaving
+ *  it to fight the new `display`. Custom properties are deliberately outside
+ *  the catalog: `--slot-size-*` belongs to `attachSlotResize`. */
+const SECTION_STYLE_PROPERTIES = [
+  'display',
+  'flex-direction',
+  'flex',
+  'min-width',
+  'width',
+  'gap',
+] as const
+const SLOT_STYLE_PROPERTIES = [
+  'min-height',
+  'display',
+  'grid-template-columns',
+  'gap',
+  'flex-direction',
+] as const
+
+const applyStyle = (
+  element: HTMLElement,
+  pairs: StylePairs,
+  catalog: ReadonlyArray<string>,
+): void => {
+  const declared = new Set(pairs.map(([property]) => property))
+  catalog.forEach(property => {
+    if (!declared.has(property)) element.style.removeProperty(property)
+  })
+  pairs.forEach(([property, value]) =>
+    element.style.setProperty(property, value),
+  )
+}
+
+const layoutRole = (node: Element): string | null =>
+  node.getAttribute(LAYOUT_ATTRIBUTE)
+
+/** The section's inner arrangement: chrome above the slot, stacked. */
+const sectionInnerStyle: StylePairs = [
+  ['display', 'flex'],
+  ['flex-direction', 'column'],
+  ['gap', '0.5rem'],
+]
+
+const buildSection = (slot: SlotSpec): HTMLElement => {
+  const section = document.createElement('section')
+  section.id = generatedSectionId(slot.id)
+  section.setAttribute(LAYOUT_ATTRIBUTE, 'section')
+
+  const chrome = document.createElement('div')
+  chrome.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  const label = document.createElement('div')
+  label.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  label.style.setProperty('font-weight', '600')
+  label.textContent = slot.label ?? ''
+  const description = document.createElement('div')
+  description.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  description.style.setProperty('opacity', '0.7')
+  description.textContent = slot.description ?? ''
+  chrome.appendChild(label)
+  chrome.appendChild(description)
+
+  const slotDiv = document.createElement('div')
+  // Never omit, never rename, never defer to a caller: a mount container
+  // without an id is the silent failure this repo has paid for the most.
+  slotDiv.id = slot.id
+  slotDiv.setAttribute(LAYOUT_ATTRIBUTE, 'slot')
+
+  section.appendChild(chrome)
+  section.appendChild(slotDiv)
+  return section
+}
+
+const chromeTexts = (
+  section: HTMLElement,
+): { label: Element; description: Element } | null => {
+  const chrome = Array.from(section.children).find(
+    child => layoutRole(child) === 'chrome',
+  )
+  if (chrome === undefined) return null
+  const label = chrome.children[0]
+  const description = chrome.children[1]
+  if (label === undefined || description === undefined) return null
+  return { label, description }
+}
+
+const slotDivOf = (section: HTMLElement): HTMLElement | null => {
+  const found = Array.from(section.children).find(
+    child => layoutRole(child) === 'slot',
+  )
+  return found instanceof HTMLElement ? found : null
+}
+
+/**
+ * Reconcile the DOM under `generatedRoot` to the manifest. Only the theme's
+ * `slots` matter to geometry, so the parameter is exactly that slice — a
+ * generated host with NO manifest passes `{ slots: [] }` and gets the legal
+ * "opted in, nothing declared" empty layout (ruling D6).
+ */
+export const renderLayout = (
+  manifest: { readonly slots: ReadonlyArray<SlotSpec> },
+  generatedRoot: HTMLElement,
+): RenderLayoutReport => {
+  const rows = layoutRows(manifest.slots)
+  let created = 0
+  let relabelled = 0
+  let moved = 0
+  let removed = 0
+  const deferred: string[] = []
+
+  // Row chrome is unkeyed, but reuse is by MAJORITY, not position: each
+  // declared row claims the existing row div already holding most of its
+  // sections, so a row merging away moves the one section that changed
+  // rather than reparenting (and remounting) every section below it.
+  const existingRowDivs = Array.from(generatedRoot.children).filter(
+    child => layoutRole(child) === 'row',
+  )
+  const claimed = new Set<Element>()
+  const claims = rows.map(row => {
+    const counts = new Map<Element, number>()
+    row.slots.forEach(rowSlot => {
+      const section = document.getElementById(generatedSectionId(rowSlot.id))
+      if (section === null || layoutRole(section) !== 'section') return
+      const parent = section.parentElement
+      if (
+        parent === null ||
+        layoutRole(parent) !== 'row' ||
+        parent.parentElement !== generatedRoot ||
+        claimed.has(parent)
+      )
+        return
+      counts.set(parent, (counts.get(parent) ?? 0) + 1)
+    })
+    const best = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]
+    if (best === undefined) return null
+    claimed.add(best[0])
+    return best[0]
+  })
+  const unclaimed = existingRowDivs.filter(div => !claimed.has(div))
+  const rowDivs = claims.map(claim => {
+    if (claim !== null) return claim
+    const reuse = unclaimed.shift()
+    if (reuse !== undefined) {
+      claimed.add(reuse)
+      return reuse
+    }
+    const rowDiv = document.createElement('div')
+    rowDiv.setAttribute(LAYOUT_ATTRIBUTE, 'row')
+    generatedRoot.appendChild(rowDiv)
+    return rowDiv
+  })
+  // Row divs must appear top-to-bottom in declared-row order; reorder with
+  // the same skip-the-strangers cursor the sections use below.
+  const rowDivSet = new Set(rowDivs)
+  let rowCursor: ChildNode | null = generatedRoot.firstChild
+  rowDivs.forEach(rowDiv => {
+    while (
+      rowCursor !== null &&
+      rowCursor !== rowDiv &&
+      !(rowCursor instanceof Element && rowDivSet.has(rowCursor))
+    ) {
+      rowCursor = rowCursor.nextSibling
+    }
+    if (rowCursor === rowDiv) {
+      rowCursor = rowCursor.nextSibling
+    } else {
+      generatedRoot.insertBefore(rowDiv, rowCursor)
+    }
+  })
+  rowDivs.forEach(rowDiv => {
+    if (rowDiv instanceof HTMLElement) applyStyle(rowDiv, rowStyle(), [])
+  })
+
+  const desiredSectionIds = new Set(
+    manifest.slots.map(slot => generatedSectionId(slot.id)),
+  )
+
+  rows.forEach((row, rowIndex) => {
+    const rowDiv = rowDivs[rowIndex]
+    if (!(rowDiv instanceof HTMLElement)) return
+
+    // Resolve or build each desired section, deferring on foreign ids.
+    const desired = row.slots.flatMap(slot => {
+      const sectionId = generatedSectionId(slot.id)
+      const existingSection = document.getElementById(sectionId)
+      if (existingSection !== null && layoutRole(existingSection) !== 'section') {
+        console.warn(
+          `[renderLayout] id "${sectionId}" is owned by non-layout markup — leaving it alone (markup wins)`,
+        )
+        deferred.push(slot.id)
+        return []
+      }
+      if (existingSection === null) {
+        const slotCollision = document.getElementById(slot.id)
+        if (slotCollision !== null && layoutRole(slotCollision) !== 'slot') {
+          console.warn(
+            `[renderLayout] slot id "${slot.id}" is owned by non-layout markup — leaving it alone (markup wins)`,
+          )
+          deferred.push(slot.id)
+          return []
+        }
+        const built = buildSection(slot)
+        created += 1
+        return [{ slot, section: built, isNew: true }]
+      }
+      // Copy reconciles in place — textContent only, never a rebuild.
+      const texts = chromeTexts(existingSection)
+      if (texts !== null) {
+        const nextLabel = slot.label ?? ''
+        const nextDescription = slot.description ?? ''
+        let changed = false
+        if (texts.label.textContent !== nextLabel) {
+          texts.label.textContent = nextLabel
+          changed = true
+        }
+        if (texts.description.textContent !== nextDescription) {
+          texts.description.textContent = nextDescription
+          changed = true
+        }
+        if (changed) relabelled += 1
+      }
+      return [{ slot, section: existingSection, isNew: false }]
+    })
+
+    const desiredSet = new Set<Element>(desired.map(entry => entry.section))
+
+    // Minimal-move ordering: advance a cursor past nodes that are staying
+    // put (deferred strangers, stale sections awaiting their prune); insert
+    // only the sections whose row or order actually differs.
+    let cursor: ChildNode | null = rowDiv.firstChild
+    desired.forEach(entry => {
+      while (
+        cursor !== null &&
+        cursor !== entry.section &&
+        !(cursor instanceof Element && desiredSet.has(cursor))
+      ) {
+        cursor = cursor.nextSibling
+      }
+      if (cursor === entry.section) {
+        cursor = cursor.nextSibling
+      } else {
+        rowDiv.insertBefore(entry.section, cursor)
+        if (!entry.isNew) moved += 1
+      }
+      if (entry.section instanceof HTMLElement) {
+        applyStyle(entry.section, [
+          ...sectionInnerStyle,
+          ...sectionStyle(entry.slot),
+        ], SECTION_STYLE_PROPERTIES)
+        const slotDiv = slotDivOf(entry.section)
+        if (slotDiv !== null) {
+          applyStyle(slotDiv, slotStyle(entry.slot), SLOT_STYLE_PROPERTIES)
+        }
+      }
+    })
+  })
+
+  // Prune stale sections — but ONLY once their slot div is empty. A section
+  // still holding a mounted element is deferred: the caller's mount loop
+  // unmounts on its own schedule, and the next pass completes the prune.
+  Array.from(
+    generatedRoot.querySelectorAll(`section[${LAYOUT_ATTRIBUTE}="section"]`),
+  ).forEach(section => {
+    if (desiredSectionIds.has(section.id)) return
+    if (!(section instanceof HTMLElement)) return
+    const slotDiv = slotDivOf(section)
+    if (slotDiv !== null && slotDiv.childElementCount > 0) {
+      deferred.push(slotDiv.id)
+      return
+    }
+    section.remove()
+    removed += 1
+  })
+
+  // Stale row chrome goes once it is empty; rows are structure, not
+  // content, so an unclaimed div holding a deferred section stays put.
+  Array.from(generatedRoot.children)
+    .filter(child => layoutRole(child) === 'row')
+    .forEach(rowDiv => {
+      if (!rowDivSet.has(rowDiv) && rowDiv.childElementCount === 0) {
+        rowDiv.remove()
+      }
+    })
+
+  return { created, relabelled, moved, removed, deferred }
+}