@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/lexical.ts

@@ -0,0 +1,170 @@
+/**
+ * The rich text vocabulary, and the only place it is spelled out.
+ *
+ * Lexical's serialised shape, narrowed to the nodes this kit renders and can serialise back.
+ * Closed on purpose: the DOM-to-Lexical inverse in `lexicalDom.ts` only has to invert what
+ * `richText.tsx` emits, and that argument holds only while both read from this list.
+ *
+ * **No `lexical` import.** This package is vendored into every client site, so a dependency
+ * here is a dependency in seven repositories. A builder for a documented JSON tree does not
+ * need the library that produced it.
+ */
+
+/** Lexical's inline format bitfield. */
+export const FORMAT = {
+  bold: 1,
+  code: 16,
+  italic: 2,
+  strikethrough: 4,
+  underline: 8,
+} as const
+
+export type RichTextNode = {
+  detail: number
+  format: number
+  mode: string
+  style: string
+  text: string
+  type: 'text'
+  version: number
+}
+
+export type RichLineBreak = { type: 'linebreak'; version: number }
+
+export type RichInline = RichLineBreak | RichLink | RichTextNode
+
+export type RichLink = {
+  children: (RichLineBreak | RichTextNode)[]
+  direction: 'ltr'
+  fields: { linkType: 'custom'; newTab: boolean; url: string }
+  format: ''
+  indent: number
+  type: 'link'
+  version: number
+}
+
+export type RichParagraph = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  textFormat: number
+  type: 'paragraph'
+  version: number
+}
+
+export type RichHeading = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  tag: 'h1' | 'h2' | 'h3'
+  type: 'heading'
+  version: number
+}
+
+export type RichListItem = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  type: 'listitem'
+  value: number
+  version: number
+}
+
+export type RichList = {
+  children: RichListItem[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  listType: 'bullet' | 'number'
+  start: number
+  tag: 'ol' | 'ul'
+  type: 'list'
+  version: number
+}
+
+export type RichBlock = RichHeading | RichList | RichParagraph
+
+export type RichTextValue = {
+  root: {
+    children: RichBlock[]
+    direction: 'ltr'
+    format: ''
+    indent: number
+    type: 'root'
+    version: number
+  }
+}
+
+export const text = (value: string, format = 0): RichTextNode => ({
+  detail: 0,
+  format,
+  mode: 'normal',
+  style: '',
+  text: value,
+  type: 'text',
+  version: 1,
+})
+
+export const lineBreak = (): RichLineBreak => ({ type: 'linebreak', version: 1 })
+
+export const link = (url: string, ...children: (RichLineBreak | RichTextNode)[]): RichLink => ({
+  children,
+  direction: 'ltr',
+  fields: { linkType: 'custom', newTab: false, url },
+  format: '',
+  indent: 0,
+  type: 'link',
+  version: 1,
+})
+
+export const paragraph = (...children: RichInline[]): RichParagraph => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  textFormat: 0,
+  type: 'paragraph',
+  version: 1,
+})
+
+export const heading = (tag: 'h1' | 'h2' | 'h3', ...children: RichInline[]): RichHeading => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  tag,
+  type: 'heading',
+  version: 1,
+})
+
+export const listItem = (...children: RichInline[]): RichListItem => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  type: 'listitem',
+  value: 1,
+  version: 1,
+})
+
+export const list = (
+  listType: 'bullet' | 'number',
+  ...children: RichListItem[]
+): RichList => ({
+  children: children.map((item, index) => ({ ...item, value: index + 1 })),
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  listType,
+  start: 1,
+  tag: listType === 'bullet' ? 'ul' : 'ol',
+  type: 'list',
+  version: 1,
+})
+
+export const doc = (...children: RichBlock[]): RichTextValue => ({
+  root: { children, direction: 'ltr', format: '', indent: 0, type: 'root', version: 1 },
+})

package/src/legacy/lexicalDom.ts

@@ -0,0 +1,166 @@
+import {
+  doc,
+  FORMAT,
+  heading,
+  lineBreak,
+  link,
+  list,
+  listItem,
+  paragraph,
+  type RichBlock,
+  type RichInline,
+  type RichListItem,
+  type RichTextValue,
+  text,
+} from './lexical'
+
+/**
+ * Edited markup, back to the document it came from.
+ *
+ * The inverse of `richText.tsx`, and only of that: it inverts the markup this kit emits, not
+ * HTML in general. That is what makes it tractable — the vocabulary is closed and the mark
+ * nesting is fixed, so every shape reaching here is one `richText.tsx` produced.
+ *
+ * **A structural node, not an `Element`.** `dashboard/sitemap/tree.ts` gives the reason: a pure
+ * function over hand-written input is one `verify` can exercise, and a serialiser only testable
+ * in a browser is one nobody tests. The frame feeds it a thin adapter over real nodes.
+ *
+ * **Accepted losses (confirmed in review, not bugs to chase).** The vocabulary this file inverts
+ * is `richText.tsx`'s, not arbitrary pasted HTML, so a few shapes a paste can introduce are
+ * deliberately not preserved:
+ *   - `<span style="font-weight:700">…</span>` (a Word/Google Docs bold) drops its formatting —
+ *     there is no inline-style parser, only the closed `MARK_BITS` tag vocabulary below.
+ *   - a `<ul>`/`<ol>` nested inside an `<li>` flattens into the parent item's inline run, rather
+ *     than nesting as its own list.
+ *   - `<div><br></div>` (a lone line break with no text) is dropped rather than producing an
+ *     empty paragraph.
+ */
+export type DomLike = {
+  attributes?: Record<string, string>
+  children?: DomLike[]
+  tag?: string
+  text?: string
+}
+
+/**
+ * Wrapper tag to the bit it sets. The inverse of `MARKS` in `richText.tsx`.
+ *
+ * `b`, `i` and `strike` are here although the reader never emits them: in-frame formatting is
+ * the browser's native `contentEditable` behaviour, and browsers disagree about which spelling
+ * they insert. Accepting both is what stops a client's ⌘B coming back as plain text.
+ */
+const MARK_BITS: Record<string, number> = {
+  b: FORMAT.bold,
+  code: FORMAT.code,
+  em: FORMAT.italic,
+  i: FORMAT.italic,
+  s: FORMAT.strikethrough,
+  strike: FORMAT.strikethrough,
+  strong: FORMAT.bold,
+  u: FORMAT.underline,
+}
+
+/** Block-level tags `blocks()` recurses on structurally rather than flattening into a paragraph. */
+const BLOCK_TAGS = new Set(['h1', 'h2', 'h3', 'ol', 'p', 'ul'])
+
+/** Tags that signal "this is inline content", the browser's `<a>` plus every mark alias above. */
+const INLINE_TAGS = new Set([...Object.keys(MARK_BITS), 'a'])
+
+const inlines = (nodes: DomLike[], format: number): RichInline[] =>
+  nodes.flatMap((node): RichInline[] => {
+    if (typeof node.text === 'string') {
+      // `&nbsp;` is what a browser inserts for a second consecutive space. Storing it means
+      // the words on record stop matching the words typed, so it is normalised here — the
+      // same thing `readEditedText` does on the plain-text path.
+      const value = node.text.replace(/\u00a0/g, ' ')
+      return value ? [text(value, format)] : []
+    }
+
+    const singleKey = node.attributes?.['data-single-key']
+    if (singleKey && /^[^{}\s]+$/.test(singleKey)) return [text(`{${singleKey}}`, format)]
+
+    const tag = (node.tag ?? '').toLowerCase()
+    if (tag === 'br') return [lineBreak()]
+
+    if (tag === 'a') {
+      const url = node.attributes?.href ?? '#'
+      const children = inlines(node.children ?? [], format).filter(
+        (child): child is Exclude<RichInline, ReturnType<typeof link>> => child.type !== 'link',
+      )
+      return [link(url, ...children)]
+    }
+
+    const bit = MARK_BITS[tag]
+    if (bit !== undefined) return inlines(node.children ?? [], format | bit)
+
+    return inlines(node.children ?? [], format)
+  })
+
+/**
+ * One block's inline content, with the browser's scaffolding removed.
+ *
+ * A `contentEditable` puts a filler `<br>` at the end of a block so an empty one stays
+ * selectable. It is not something the client typed, and storing it is how a document grows on
+ * every save: the reader draws the linebreak back, the browser pads the result again, and the
+ * next serialisation keeps both. Observed on a real privacy policy — 34 blocks became 43, with
+ * five linebreaks that appear nowhere in the source.
+ *
+ * Only the *last* one goes. A `<br>` between words is a line break the client asked for.
+ */
+const blockInlines = (kids: DomLike[]): RichInline[] => {
+  const content = inlines(kids, 0)
+  const last = content[content.length - 1]
+  return last && last.type === 'linebreak' ? content.slice(0, -1) : content
+}
+
+
+const blocks = (nodes: DomLike[]): RichBlock[] =>
+  nodes.flatMap((node): RichBlock[] => {
+    const tag = (node.tag ?? '').toLowerCase()
+    const kids = node.children ?? []
+    if (node.attributes?.['data-single-key']) return [paragraph(...inlines([node], 0))]
+
+    /*
+     * An empty block is kept. Stripping the filler `<br>` above is what stops the growth loop;
+     * dropping the block as well deleted the blank line a client had just made with Enter, and
+     * took their caret to the end of the document with it.
+     */
+    if (tag === 'p') return [paragraph(...blockInlines(kids))]
+    if (tag === 'h1' || tag === 'h2' || tag === 'h3') return [heading(tag, ...blockInlines(kids))]
+    if (tag === 'ul' || tag === 'ol') {
+      const items: RichListItem[] = kids
+        .filter((kid) => (kid.tag ?? '').toLowerCase() === 'li')
+        .map((kid) => listItem(...blockInlines(kid.children ?? [])))
+      return [list(tag === 'ol' ? 'number' : 'bullet', ...items)]
+    }
+
+    /*
+     * Anything else contributes its children rather than itself — the wrapper the frame puts
+     * around the field, and any element a paste survived.
+     *
+     * Chrome's `contentEditable` default block separator is a bare `<div>`, and pasted content
+     * arrives the same way, so a fallthrough node's own children are not necessarily further
+     * blocks — they are as likely to be the inline content of an unwrapped paragraph. If any
+     * *direct* child is itself a block tag, keep recursing block-wise (a wrapper around real
+     * blocks). Otherwise, if any direct child is text or one of the inline/mark tags, the whole
+     * node IS a paragraph's worth of inline content and must be routed through `inlines()` as
+     * one paragraph — recursing block-wise here would silently drop every mark and split one
+     * sentence into one paragraph per text run, which is exactly the data loss this file exists
+     * to prevent.
+     */
+    if (kids.some((kid) => BLOCK_TAGS.has((kid.tag ?? '').toLowerCase()))) {
+      return blocks(kids)
+    }
+    if (kids.some((kid) => typeof kid.text === 'string' || Boolean(kid.attributes?.['data-single-key']) || INLINE_TAGS.has((kid.tag ?? '').toLowerCase()))) {
+      return [paragraph(...blockInlines(kids))]
+    }
+
+    // A stray run of text with no block around it becomes a paragraph, because dropping it
+    // would lose a client's words.
+    if (typeof node.text === 'string') {
+      return node.text.trim() ? [paragraph(text(node.text))] : []
+    }
+    return blocks(kids)
+  })
+
+export const toRichText = (node: DomLike): RichTextValue => doc(...blocks(node.children ?? []))

package/src/legacy/media.ts

@@ -0,0 +1,272 @@
+import type { EditorBlock, EditorField } from './contract'
+import type { ImageSlot } from './image'
+import {
+  normalizeImageSeed,
+  imageSeedForImport,
+  validateImageValue,
+  type ImageValue,
+  type ImageSeedValue,
+  type ImageReadValue,
+  type ImageVariantDeclaration,
+  type MediaId,
+} from './image'
+import type { MediaRef } from './shape'
+
+export type MediaValidationIssue = { path: string; message: string }
+export type MediaValidationOptions = {
+  path?: string
+  mode: 'draft' | 'publish'
+  required?: boolean
+  duration?: number | null
+  posterVariants?: Record<string, ImageVariantDeclaration>
+}
+export type VideoSettings = {
+  posterTime: number
+  startTime: number
+  endTime: number | null
+  autoplay: boolean
+  muted: boolean
+  loop: boolean
+  controls: boolean
+  playsInline: boolean
+  preload: 'none' | 'metadata' | 'auto'
+}
+export type VideoValue = null | (VideoSettings & { asset: MediaId; poster: ImageValue })
+export type VideoSeedValue =
+  null | (Partial<VideoSettings> & { asset: MediaId | { source: string }; poster?: ImageSeedValue })
+export type VideoReadValue = null | (VideoSettings & { asset: MediaRef; poster: ImageReadValue })
+export type FileValue = null | {
+  asset: MediaId
+  label: string
+  description: string | null
+  downloadName: string | null
+}
+export type FileSeedValue = null | {
+  asset: MediaId | { source: string }
+  label?: string
+  description?: string | null
+  downloadName?: string | null
+}
+export type FileReadValue = null | (Omit<NonNullable<FileValue>, 'asset'> & { asset: MediaRef })
+const record = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === 'object' && !Array.isArray(v)
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
+const id = (v: unknown) =>
+  (finite(v) && Number.isInteger(v) && v > 0) || (typeof v === 'string' && !!v.trim())
+const at = (p: string, k: string) => (p ? `${p}.${k}` : k)
+const defaults: VideoSettings = {
+  posterTime: 0,
+  startTime: 0,
+  endTime: null,
+  autoplay: false,
+  muted: true,
+  loop: false,
+  controls: true,
+  playsInline: true,
+  preload: 'metadata',
+}
+export class MediaValidationError extends Error {
+  constructor(public issues: MediaValidationIssue[]) {
+    super(issues.map((i) => `${i.path}: ${i.message}`).join('; '))
+    this.name = 'MediaValidationError'
+  }
+}
+function validate(
+  value: unknown,
+  options: MediaValidationOptions,
+  kind: 'Video' | 'File',
+): MediaValidationIssue[] {
+  const path = options.path ?? '',
+    issues: MediaValidationIssue[] = []
+  const issue = (key: string, message: string) => issues.push({ path: at(path, key), message })
+  if (value == null)
+    return options.required && options.mode === 'publish'
+      ? [{ path, message: `A ${kind} is required for publication.` }]
+      : []
+  if (!record(value)) return [{ path, message: `Expected a ${kind} object or null.` }]
+  if (!id(value.asset))
+    issue('asset', 'Expected a media ID; expanded assets and seed sources are not write values.')
+  const keys =
+    kind === 'Video'
+      ? ['asset', 'poster', ...Object.keys(defaults)]
+      : ['asset', 'label', 'description', 'downloadName']
+  for (const key of Object.keys(value))
+    if (!keys.includes(key)) issue(key, `Unknown ${kind} property.`)
+  if (kind === 'File') {
+    if (typeof value.label !== 'string') issue('label', 'Label must be text.')
+    for (const key of ['description', 'downloadName'])
+      if (value[key] !== null && typeof value[key] !== 'string')
+        issue(key, 'Expected text or null.')
+  } else {
+    for (const key of ['posterTime', 'startTime', 'endTime']) {
+      const n = value[key]
+      if (key === 'endTime' && n === null) continue
+      if (!finite(n) || n < 0) issue(key, 'Time must be finite nonnegative seconds.')
+      else if (finite(options.duration) && n > options.duration)
+        issue(key, 'Time exceeds the video duration.')
+    }
+    if (finite(value.startTime) && finite(value.endTime) && value.endTime <= value.startTime)
+      issue('endTime', 'End time must be after start time.')
+    for (const key of ['autoplay', 'muted', 'loop', 'controls', 'playsInline'])
+      if (typeof value[key] !== 'boolean') issue(key, 'Expected a boolean.')
+    if (value.autoplay === true && value.muted !== true)
+      issue('muted', 'Autoplay requires muted playback.')
+    if (!['none', 'metadata', 'auto'].includes(value.preload as string))
+      issue('preload', 'Expected none, metadata or auto.')
+    issues.push(
+      ...validateImageValue(value.poster, {
+        ...options,
+        required: false,
+        path: at(path, 'poster'),
+        variants: options.posterVariants,
+      }),
+    )
+  }
+  return issues
+}
+export const validateVideoValue = (value: unknown, options: MediaValidationOptions) =>
+  validate(value, options, 'Video')
+export const validateFileValue = (value: unknown, options: MediaValidationOptions) =>
+  validate(value, options, 'File')
+function normalize(
+  value: unknown,
+  kind: 'Video' | 'File',
+  options: Pick<MediaValidationOptions, 'posterVariants'> = {},
+) {
+  if (value == null) return null
+  if (!record(value))
+    throw new MediaValidationError([
+      { path: '', message: `Expected a ${kind} seed object or null.` },
+    ])
+  const out: Record<string, unknown> = { ...value }
+  const defs =
+    kind === 'Video'
+      ? { ...defaults, poster: null }
+      : { label: '', description: null, downloadName: null }
+  for (const [key, v] of Object.entries(defs)) if (out[key] === undefined) out[key] = v
+  if (kind === 'Video') out.poster = normalizeImageSeed(out.poster)
+  const check = { ...out }
+  if (
+    record(check.asset) &&
+    Object.keys(check.asset).length === 1 &&
+    typeof check.asset.source === 'string' &&
+    check.asset.source.trim()
+  )
+    check.asset = check.asset.source
+  // Poster seed sources have already been validated by the Image normalizer.
+  if (kind === 'Video') check.poster = null
+  const issues = validate(check, { mode: 'draft', ...options }, kind)
+  if (
+    kind === 'Video' &&
+    record(out.poster) &&
+    record(out.poster.variants) &&
+    options.posterVariants
+  )
+    for (const key of Object.keys(out.poster.variants))
+      if (!Object.hasOwn(options.posterVariants, key))
+        issues.push({
+          path: `poster.variants.${key}`,
+          message: 'Variant is not declared by this field.',
+        })
+  if (issues.length) throw new MediaValidationError(issues)
+  return out
+}
+export const normalizeVideoSeed = (
+  value: unknown,
+  options: Pick<MediaValidationOptions, 'posterVariants'> = {},
+): VideoSeedValue => normalize(value, 'Video', options) as VideoSeedValue
+export const normalizeFileSeed = (value: unknown): FileSeedValue =>
+  normalize(value, 'File') as FileSeedValue
+export function videoSeedForImport(
+  value: unknown,
+  options: Pick<MediaValidationOptions, 'posterVariants'> = {},
+): VideoSeedValue {
+  const v = normalizeVideoSeed(value, options)
+  return v
+    ? {
+        ...v,
+        asset: typeof v.asset === 'object' ? v.asset.source : v.asset,
+        poster: imageSeedForImport(v.poster),
+      }
+    : null
+}
+export function fileSeedForImport(value: unknown): FileSeedValue {
+  const v = normalizeFileSeed(value)
+  return v ? { ...v, asset: typeof v.asset === 'object' ? v.asset.source : v.asset } : null
+}
+export type VideoHTMLProps = {
+  src?: string
+  poster?: string
+  autoPlay: boolean
+  muted: boolean
+  loop: boolean
+  controls: boolean
+  playsInline: boolean
+  preload: VideoSettings['preload']
+}
+/** Native attributes only. Components own seeking and bounded playback events. */
+export function videoProps(
+  value: VideoReadValue | undefined,
+  fallback: Pick<VideoHTMLProps, 'src' | 'poster'> = {},
+): VideoHTMLProps {
+  const v = value ?? defaults
+  return {
+    src: value?.asset?.url ?? fallback.src,
+    poster:
+      (value?.poster?.status === 'ready' ? value.poster.rendition?.url : undefined) ??
+      fallback.poster,
+    autoPlay: v.autoplay,
+    muted: v.muted,
+    loop: v.loop,
+    controls: v.controls,
+    playsInline: v.playsInline,
+    preload: v.preload,
+  }
+}
+
+export type MediaSlot = ImageSlot
+/** Atomic Video and File placements, including nested groups, arrays and block zones. */
+export function mediaSlots(
+  content: unknown,
+  blocks: EditorBlock[],
+  allBlocks: EditorBlock[] = blocks,
+): MediaSlot[] {
+  const slots: MediaSlot[] = []
+  function fields(schema: EditorField[], container: unknown, path: string) {
+    if (!record(container)) return
+    for (const field of schema) {
+      const p = at(path, field.name),
+        value = container[field.name]
+      if (field.type === 'group' && (field.element === 'video' || field.element === 'file')) {
+        slots.push({
+          field,
+          path: p,
+          get: () => container[field.name],
+          set: (v) => {
+            container[field.name] = v
+          },
+        })
+        continue
+      }
+      if (field.type === 'group') fields(field.fields ?? [], value, p)
+      if (field.type === 'array' && Array.isArray(value))
+        value.forEach((v, i) => fields(field.fields ?? [], v, at(p, String(i))))
+      if (field.type === 'blocks')
+        rows(
+          value,
+          field.blocks ??
+            (field.childBlocks ?? []).flatMap((slug) => allBlocks.filter((b) => b.slug === slug)),
+          p,
+        )
+    }
+  }
+  function rows(value: unknown, schema: EditorBlock[], path: string) {
+    if (!Array.isArray(value)) return
+    value.forEach((v, i) => {
+      const block = record(v) ? schema.find((b) => b.slug === v.blockType) : undefined
+      if (block) fields(block.fields, v, at(path, String(i)))
+    })
+  }
+  rows(content, blocks, '')
+  return slots
+}