@prenta/admin 0.92.0 → 0.94.0

package/src/__tests__/lib/version-diff.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest'
+import {
+  changedSectionIds,
+  diffVersions,
+  formatValue,
+  groupChangesBySection,
+} from '../../lib/version-diff.js'
+import type { PageSection } from '../../lib/page-editor-service.js'
+
+function section(overrides: Partial<PageSection> & { id: string }): PageSection {
+  return {
+    sectionType: 'hero',
+    name: 'Hero Banner',
+    visible: true,
+    content: {},
+    settings: {},
+    ...overrides,
+  }
+}
+
+describe('formatValue', () => {
+  it('renders absent and blank values as an em dash so an empty diff cell is never blank', () => {
+    expect(formatValue(null)).toBe('—')
+    expect(formatValue(undefined)).toBe('—')
+    expect(formatValue('')).toBe('—')
+    expect(formatValue('   ')).toBe('—')
+    expect(formatValue([])).toBe('—')
+    expect(formatValue({})).toBe('—')
+  })
+
+  it('summarises structured values rather than dumping them', () => {
+    expect(formatValue([{ value: '1' }, { value: '2' }])).toBe('2 items')
+    expect(formatValue([{ value: '1' }])).toBe('1 item')
+    expect(formatValue({ name: 'hero.jpg', url: '/m/hero.jpg' })).toBe('hero.jpg')
+    // No name-ish key: fall back to a shape description, not "[object Object]".
+    expect(formatValue({ x: 1, y: 2 })).toBe('2 fields')
+  })
+
+  it('reads booleans and numbers as words the panel can show', () => {
+    expect(formatValue(true)).toBe('Yes')
+    expect(formatValue(false)).toBe('No')
+    expect(formatValue(0)).toBe('0')
+  })
+})
+
+describe('diffVersions', () => {
+  it('labels content fields through the section registry, not by raw key', () => {
+    const before = [section({ id: 's1', content: { heading: 'Old headline' } })]
+    const after = [section({ id: 's1', content: { heading: 'New headline' } })]
+
+    const changes = diffVersions(after, before)
+
+    expect(changes).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        // 'heading' is `label: 'Heading'` on the hero type in the registry.
+        field: 'Heading',
+        from: 'Old headline',
+        to: 'New headline',
+      },
+    ])
+  })
+
+  it('falls back to the raw key for a type the registry does not describe', () => {
+    const before = [section({ id: 's1', sectionType: 'opal-pricing', content: { tiers: 'a' } })]
+    const after = [section({ id: 's1', sectionType: 'opal-pricing', content: { tiers: 'b' } })]
+
+    expect(diffVersions(after, before)[0]?.field).toBe('tiers')
+  })
+
+  it('reports a field cleared to nothing — the key exists only in the older snapshot', () => {
+    const before = [section({ id: 's1', content: { heading: 'Something' } })]
+    const after = [section({ id: 's1', content: {} })]
+
+    expect(diffVersions(after, before)).toEqual([
+      { sectionId: 's1', sectionName: 'Hero Banner', field: 'Heading', from: 'Something', to: '—' },
+    ])
+  })
+
+  it('reports visibility as a state, because hiding a section is the one structural edit there is', () => {
+    const before = [section({ id: 's1', visible: true })]
+    const after = [section({ id: 's1', visible: false })]
+
+    expect(diffVersions(after, before)).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        field: 'Visibility',
+        from: 'Shown',
+        to: 'Hidden',
+      },
+    ])
+  })
+
+  it('reports added and removed sections', () => {
+    const before = [section({ id: 's1' })]
+    const after = [section({ id: 's1' }), section({ id: 's2', name: 'CTA', sectionType: 'cta' })]
+
+    expect(diffVersions(after, before)).toEqual([
+      { sectionId: 's2', sectionName: 'CTA', field: 'Section', from: '—', to: 'Added' },
+    ])
+
+    expect(diffVersions(before, after)).toEqual([
+      { sectionId: 's2', sectionName: 'CTA', field: 'Section', from: 'Present', to: 'Removed' },
+    ])
+  })
+
+  it('reports nothing when the snapshots match', () => {
+    const same = [section({ id: 's1', content: { heading: 'Same' } })]
+    expect(diffVersions(same, [section({ id: 's1', content: { heading: 'Same' } })])).toEqual([])
+  })
+
+  it('reports nothing against a missing predecessor', () => {
+    // The oldest version we hold is not the moment the page was created, so
+    // reporting every field as "added" would state something false.
+    expect(diffVersions([section({ id: 's1', content: { heading: 'x' } })], undefined)).toEqual([])
+    expect(diffVersions([section({ id: 's1' })], null)).toEqual([])
+  })
+
+  it('does not report a settings key that was merely absent versus explicitly default', () => {
+    // `{}` and `{ backgroundType: undefined }` format identically, so neither
+    // produces a row. Without this the first save after a schema addition
+    // would light up every section on the canvas.
+    const before = [section({ id: 's1', settings: {} })]
+    const after = [section({ id: 's1', settings: { backgroundType: undefined } as never })]
+    expect(diffVersions(after, before)).toEqual([])
+  })
+
+  it('labels known settings and reports a real background change', () => {
+    const before = [section({ id: 's1', settings: { backgroundType: 'none' } })]
+    const after = [section({ id: 's1', settings: { backgroundType: 'solid' } })]
+
+    expect(diffVersions(after, before)).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        field: 'Background type',
+        from: 'none',
+        to: 'solid',
+      },
+    ])
+  })
+})
+
+describe('diffVersions — structured fields', () => {
+  const stats = (rows: Array<{ value: string; label: string }>) =>
+    section({ id: 's1', sectionType: 'stats', name: 'By The Numbers', content: { stats: rows } })
+
+  it('catches an edit that keeps the row count', () => {
+    // The bug this exists for: deciding "did it change" from the DISPLAY
+    // summary collapses an array to "2 items", so retyping a row while keeping
+    // the count formats identically on both sides and the field reports no
+    // change — no panel row AND no outline on the canvas, which is exactly the
+    // edit a reviewer opened history to find.
+    const before = [
+      stats([
+        { value: '10k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+    const after = [
+      stats([
+        { value: '20k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+
+    const changes = diffVersions(after, before)
+
+    expect(changes).toHaveLength(1)
+    expect(changes[0]?.from).toBe('10k')
+    expect(changes[0]?.to).toBe('20k')
+    // Named down to the row and the sub-field, so "which one" has an answer.
+    expect(changes[0]?.field).toBe('Stats · Stat 1 · Value')
+    expect(changedSectionIds(changes).has('s1')).toBe(true)
+  })
+
+  it('never emits a row whose before and after both read as a bare count', () => {
+    const before = [
+      stats([
+        { value: 'a', label: 'x' },
+        { value: 'b', label: 'y' },
+      ]),
+    ]
+    const after = [
+      stats([
+        { value: 'c', label: 'x' },
+        { value: 'd', label: 'y' },
+      ]),
+    ]
+
+    for (const change of diffVersions(after, before)) {
+      expect(change.from).not.toBe(change.to)
+      expect(change.from).not.toMatch(/^\d+ items?$/)
+    }
+  })
+
+  it('reports added and removed rows', () => {
+    const before = [stats([{ value: '10k', label: 'Users' }])]
+    const after = [
+      stats([
+        { value: '10k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+
+    expect(diffVersions(after, before)).toEqual([
+      expect.objectContaining({ field: 'Stats · Stat 2', from: '—', to: 'Added' }),
+    ])
+    expect(diffVersions(before, after)).toEqual([
+      expect.objectContaining({ field: 'Stats · Stat 2', from: 'Present', to: 'Removed' }),
+    ])
+  })
+
+  it('catches a nested change inside a media object', () => {
+    // Same failure one level down: two media objects with the same `name` used
+    // to format identically while pointing at different files.
+    const media = (url: string) => ({ name: 'hero.jpg', url })
+    const before = [section({ id: 's1', content: { imageUrl: media('/a.jpg') } })]
+    const after = [section({ id: 's1', content: { imageUrl: media('/b.jpg') } })]
+
+    expect(diffVersions(after, before)).toHaveLength(1)
+  })
+
+  it('treats every spelling of blank as unchanged', () => {
+    // Tightening the comparison must not start reporting "— → —".
+    for (const [before, after] of [
+      ['', null],
+      [null, undefined],
+      [undefined, '   '],
+      [[], undefined],
+      [{}, null],
+    ] as Array<[unknown, unknown]>) {
+      const changes = diffVersions(
+        [section({ id: 's1', content: { heading: after } })],
+        [section({ id: 's1', content: { heading: before } })],
+      )
+      expect(changes, `${JSON.stringify(before)} → ${JSON.stringify(after)}`).toEqual([])
+    }
+  })
+
+  it('reports an unchanged repeater as no change at all', () => {
+    const rows = [{ value: '10k', label: 'Users' }]
+    expect(diffVersions([stats(rows)], [stats([...rows.map((r) => ({ ...r }))])])).toEqual([])
+  })
+})
+
+describe('groupChangesBySection', () => {
+  it('groups by section in first-seen order', () => {
+    const before = [
+      section({ id: 's1', content: { heading: 'a', body: 'a' } }),
+      section({ id: 's2', name: 'CTA', sectionType: 'cta', content: { heading: 'a' } }),
+    ]
+    const after = [
+      section({ id: 's1', content: { heading: 'b', body: 'b' } }),
+      section({ id: 's2', name: 'CTA', sectionType: 'cta', content: { heading: 'b' } }),
+    ]
+
+    const groups = groupChangesBySection(diffVersions(after, before))
+
+    expect(groups.map((g) => g.sectionId)).toEqual(['s1', 's2'])
+    expect(groups[0]?.changes).toHaveLength(2)
+    expect(groups[1]?.changes).toHaveLength(1)
+  })
+})
+
+describe('changedSectionIds', () => {
+  it('collapses several changes on one section to a single outline', () => {
+    const before = [section({ id: 's1', content: { heading: 'a', body: 'a' } })]
+    const after = [section({ id: 's1', content: { heading: 'b', body: 'b' } })]
+
+    const ids = changedSectionIds(diffVersions(after, before))
+
+    expect(ids.size).toBe(1)
+    expect(ids.has('s1')).toBe(true)
+  })
+})

package/src/__tests__/lib/version-history.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest'
+import {
+  dayLabel,
+  groupVersionsByDay,
+  initials,
+  toPageVersion,
+  versionKind,
+  type PageVersion,
+} from '../../lib/version-history.js'
+
+const NOW = new Date('2026-08-02T17:00:00Z')
+
+function version(id: string, createdAt: string): PageVersion {
+  return {
+    id,
+    changeType: 'UPDATE',
+    createdAt,
+    author: { id: 'u1', name: 'Sarah Mills' },
+    sections: [],
+  }
+}
+
+describe('toPageVersion', () => {
+  it('lifts the section snapshot out of the version payload', () => {
+    const mapped = toPageVersion({
+      id: 'v1',
+      changeType: 'PUBLISH',
+      createdAt: '2026-08-02T12:00:00Z',
+      data: {
+        sections: [
+          { id: 's1', sectionType: 'hero', name: 'Hero', visible: true, content: {}, settings: {} },
+        ],
+      },
+      changedBy: { id: 'u1', name: 'Sarah Mills', email: 's@example.com' },
+    })
+
+    expect(mapped.sections).toHaveLength(1)
+    expect(mapped.sections[0]?.id).toBe('s1')
+    expect(mapped.changeType).toBe('PUBLISH')
+    expect(mapped.author.name).toBe('Sarah Mills')
+  })
+
+  it('preserves an unmanaged section rather than dropping it from the snapshot', () => {
+    // Coercing a snapshot more strictly than the live document reads would
+    // make an externally-managed section look deleted in every version.
+    const mapped = toPageVersion({
+      id: 'v1',
+      changeType: 'UPDATE',
+      createdAt: '2026-08-02T12:00:00Z',
+      data: {
+        sections: [
+          { id: 's1', sectionType: 'opal-pricing', name: 'Pricing', visible: true, content: {} },
+        ],
+      },
+    })
+
+    expect(mapped.sections).toHaveLength(1)
+    expect(mapped.sections[0]?.sectionType).toBe('opal-pricing')
+  })
+
+  it('falls back through name → email → a real word for the avatar', () => {
+    expect(
+      toPageVersion({ id: 'v', changeType: 'UPDATE', createdAt: '', data: null }).author.name,
+    ).toBe('Unknown')
+
+    expect(
+      toPageVersion({
+        id: 'v',
+        changeType: 'UPDATE',
+        createdAt: '',
+        data: null,
+        changedBy: { id: 'u', name: '  ', email: 'a@b.com' },
+      }).author.name,
+    ).toBe('a@b.com')
+  })
+
+  it('yields no sections for a version whose payload has none', () => {
+    expect(
+      toPageVersion({ id: 'v', changeType: 'DELETE', createdAt: '', data: {} }).sections,
+    ).toEqual([])
+  })
+})
+
+describe('versionKind', () => {
+  it('marks a published snapshot as the one a visitor could have seen', () => {
+    expect(versionKind('PUBLISH')).toEqual({ label: 'Published', tone: 'live' })
+  })
+
+  it('calls UPDATE "Saved", never "Draft"', () => {
+    // Every row written before cms-core started recording PUBLISH is an UPDATE
+    // whether or not it went live, so "Draft" would be false for those.
+    expect(versionKind('UPDATE').label).toBe('Saved')
+  })
+
+  it('distinguishes a rollback from authored content', () => {
+    expect(versionKind('RESTORE').label).toBe('Restored')
+  })
+
+  it('degrades to a neutral label for an unrecognised type', () => {
+    expect(versionKind('SOMETHING_NEW').label).toBe('Saved')
+  })
+})
+
+describe('dayLabel', () => {
+  it('names today and yesterday', () => {
+    expect(dayLabel('2026-08-02T09:00:00', NOW)).toBe('Today')
+    expect(dayLabel('2026-08-01T23:59:00', NOW)).toBe('Yesterday')
+  })
+
+  it('drops the year within the current one and keeps it outside', () => {
+    expect(dayLabel('2026-07-27T09:00:00', NOW)).not.toMatch(/2026/)
+    expect(dayLabel('2025-07-27T09:00:00', NOW)).toMatch(/2025/)
+  })
+
+  it('does not throw on an unparseable timestamp', () => {
+    expect(dayLabel('not-a-date', NOW)).toBe('Unknown date')
+  })
+})
+
+describe('groupVersionsByDay', () => {
+  it('groups consecutive runs and keeps newest-first order', () => {
+    const groups = groupVersionsByDay(
+      [
+        version('v5', '2026-08-02T16:12:00'),
+        version('v4', '2026-08-02T11:03:00'),
+        version('v3', '2026-08-01T17:47:00'),
+        version('v1', '2026-07-27T09:30:00'),
+      ],
+      NOW,
+    )
+
+    expect(groups.map((g) => g.label)).toEqual(['Today', 'Yesterday', expect.stringMatching(/Jul/)])
+    expect(groups[0]?.versions.map((v) => v.id)).toEqual(['v5', 'v4'])
+  })
+
+  it('does not merge two non-adjacent runs that share a label', () => {
+    // A Map keyed on the label would silently reorder an unsorted page into
+    // something that reads as chronological but is not.
+    const groups = groupVersionsByDay(
+      [
+        version('a', '2026-08-02T16:00:00'),
+        version('b', '2026-08-01T16:00:00'),
+        version('c', '2026-08-02T09:00:00'),
+      ],
+      NOW,
+    )
+
+    expect(groups.map((g) => g.label)).toEqual(['Today', 'Yesterday', 'Today'])
+  })
+
+  it('returns nothing for an empty list', () => {
+    expect(groupVersionsByDay([], NOW)).toEqual([])
+  })
+})
+
+describe('initials', () => {
+  it('takes first and last for a full name, two letters for one word', () => {
+    expect(initials('Sarah Mills')).toBe('SM')
+    expect(initials('Sarah Jane Mills')).toBe('SM')
+    expect(initials('sarah')).toBe('SA')
+  })
+
+  it('never renders an empty monogram', () => {
+    expect(initials('   ')).toBe('?')
+  })
+})

package/src/__tests__/styles/canvas-container-queries.test.ts

@@ -0,0 +1,103 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The editor canvas renders a page at a device's real CSS width and scales it
+ * with a transform, so the page must reflow against the CANVAS width, not the
+ * browser viewport. Two invariants make that work, and both fail silently:
+ *
+ *   1. `.prenta-canvas` must establish an inline-size query container. Without
+ *      it, `@pv-*` variants never match and every breakpoint renders the
+ *      narrowest layout — which looks plausible enough to ship.
+ *   2. Section renderers must not use viewport variants (`sm:`, `md:`, `lg:`).
+ *      Those resolve against the editor window, so picking "Mobile" on a wide
+ *      monitor yields a 390px canvas still laid out for desktop — the exact
+ *      bug that made the old preview decorative.
+ */
+
+const SECTIONS_DIR = fileURLToPath(new URL('../../views/page-editor/sections/', import.meta.url))
+const THEME_CSS = fileURLToPath(new URL('../../styles/theme.css', import.meta.url))
+
+/** Viewport variants in a className position. Matches `sm:`…`2xl:` prefixes. */
+const VIEWPORT_VARIANT = /(?<![\w@[-])(?:sm|md|lg|xl|2xl):[a-z0-9[]/g
+
+function sectionFiles(): string[] {
+  return readdirSync(SECTIONS_DIR).filter((f) => f.endsWith('.tsx') || f.endsWith('.ts'))
+}
+
+describe('canvas container queries', () => {
+  it('makes .prenta-canvas an inline-size query container', () => {
+    const css = readFileSync(THEME_CSS, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+    expect(css).toMatch(/\.prenta-canvas\s*\{[^}]*container-type:\s*inline-size/)
+  })
+
+  it('defines every reflow step the handoff specifies', () => {
+    const css = readFileSync(THEME_CSS, 'utf8')
+    for (const [name, value] of [
+      ['--container-pv-sm', '460px'],
+      ['--container-pv-md', '700px'],
+      ['--container-pv-lg', '900px'],
+      ['--container-pv-xl', '1100px'],
+      ['--container-pv-2xl', '2000px'],
+    ]) {
+      expect(css, `${name} is missing or has moved`).toContain(`${name}: ${value}`)
+    }
+  })
+
+  it('uses no viewport breakpoints in any section renderer', () => {
+    const offenders: string[] = []
+    for (const file of sectionFiles()) {
+      const source = readFileSync(SECTIONS_DIR + file, 'utf8')
+      for (const match of source.matchAll(VIEWPORT_VARIANT)) {
+        offenders.push(`${file}: ${match[0]}`)
+      }
+    }
+    expect(
+      offenders,
+      'Section renderers must reflow on the canvas width. Use the @pv-* container ' +
+        'steps (theme.css) instead of sm:/md:/lg:.',
+    ).toEqual([])
+  })
+
+  it('restores the stock type scale inside the canvas, in the utilities layer', () => {
+    // The admin remaps six Tailwind size keys onto its own tokens (text-base =
+    // 13px). The canvas renders the consumer's website, where text-base must
+    // be 16px — and the reflow guard measures wrapping against these sizes, so
+    // a canvas on the admin scale makes every line count wrong.
+    const css = readFileSync(THEME_CSS, 'utf8')
+
+    // Layer order beats specificity: in @layer base this override would lose
+    // to the very utility it corrects.
+    const utilities = css.slice(css.indexOf('@layer utilities'))
+    expect(utilities, 'canvas type restoration must be in @layer utilities').toContain(
+      '.prenta-admin .prenta-canvas .text-base',
+    )
+
+    for (const [utility, size] of [
+      ['text-xs', '0.75rem'],
+      ['text-sm', '0.875rem'],
+      ['text-base', '1rem'],
+      ['text-lg', '1.125rem'],
+      ['text-xl', '1.25rem'],
+      ['text-2xl', '1.5rem'],
+    ]) {
+      const rule = new RegExp(
+        `\\.prenta-canvas \\.${utility}\\s*\\{[^}]*font-size:\\s*${size!.replace('.', '\\.')}`,
+      )
+      expect(utilities, `${utility} is not restored to its stock size`).toMatch(rule)
+    }
+  })
+
+  it('only references container steps that exist', () => {
+    const declared = new Set(['@pv-sm', '@pv-md', '@pv-lg', '@pv-xl', '@pv-2xl'])
+    const used = new Set<string>()
+    for (const file of sectionFiles()) {
+      const source = readFileSync(SECTIONS_DIR + file, 'utf8')
+      for (const match of source.matchAll(/@pv-[\w-]+?(?=:)/g)) used.add(match[0])
+    }
+    // A typo'd step (`@pv-xxl:`) compiles to nothing and silently never applies.
+    expect([...used].filter((u) => !declared.has(u))).toEqual([])
+    expect(used.size).toBeGreaterThan(0)
+  })
+})

package/src/__tests__/styles/packaging.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import pkg from '../../../package.json' with { type: 'json' }
+
+/**
+ * `@prenta/admin` exports a precompiled stylesheet
+ * (`@prenta/admin/styles/precompiled.css`) that consumers import purely for its
+ * side effects. `sideEffects: false` tells a bundler such an import is safe to
+ * eliminate — the admin would then render unstyled, with no error anywhere.
+ *
+ * The field is currently ABSENT, which is the safe default: bundlers assume
+ * side effects. This test exists so it stays safe. `@prenta/sections-react` hit
+ * exactly this problem and had to be corrected before publish.
+ *
+ * If someone does add the field to enable tree-shaking, it must be an array
+ * that keeps CSS side-effectful, not `false`.
+ */
+describe('@prenta/admin packaging', () => {
+  it('never declares itself free of side effects', () => {
+    const sideEffects = (pkg as { sideEffects?: unknown }).sideEffects
+    expect(
+      sideEffects,
+      'sideEffects: false lets bundlers drop the precompiled CSS import',
+    ).not.toBe(false)
+  })
+
+  it('keeps CSS side-effectful if the field is ever narrowed to an array', () => {
+    const sideEffects = (pkg as { sideEffects?: unknown }).sideEffects
+    if (!Array.isArray(sideEffects)) return
+    expect(
+      sideEffects.some((p) => String(p).endsWith('.css')),
+      'an array form must still list CSS',
+    ).toBe(true)
+  })
+
+  it('still exports the stylesheet consumers import', () => {
+    expect(pkg.exports['./styles/precompiled.css']).toBe('./dist/prenta-admin.css')
+  })
+})