mechanica-shared 2.0.0-alpha.9 → 2.0.2

package/src/page-format.ts

@@ -1,422 +0,0 @@
-import { Document, isCollection, isMap, isScalar, isSeq, parse as parseYaml } from 'yaml'
-import type { ContentBlock } from './types'
-
-/**
- * A parsed page document — the page envelope (everything but `content`) plus the
- * content tree. This is the in-memory shape the `.page.md` codec maps to/from;
- * it mirrors the dev store's `PageFile`.
- */
-export interface PageDoc {
-  name?: string
-  /**
-   * A work-in-progress page. Drafts render and edit normally in the dev server
-   * but are hidden from queries (`usePages`/`usePagination`) and skipped by the
-   * static export. Absent/false for published pages.
-   */
-  draft?: boolean
-  meta?: Record<string, unknown>
-  /** Page-scoped data overrides (defineData). */
-  data: Record<string, unknown>
-  content: ContentBlock[]
-  order?: number
-  orderAfter?: string | null
-  path?: string
-}
-
-/**
- * Adapter that lets the codec store rich-text fields as Markdown on disk while
- * keeping them as vuewrite `Block[]` JSON in page state. Supplied by the caller
- * (dev server / CLI) so this module stays DOM- and vuewrite-free.
- */
-export interface RichTextCodec {
-  /** Whether a top-level prop of the given block is a rich-text field. */
-  isRichText(blockId: string, prop: string): boolean
-  /** vuewrite `Block[]` → Markdown (written to disk). */
-  toMarkdown(blocks: unknown): string
-  /** Markdown → vuewrite `Block[]` (loaded into state). */
-  toBlocks(markdown: string): unknown
-}
-
-/** Options for {@link parsePage} / {@link serializePage}. */
-export interface PageCodecOptions {
-  /** Rich-text ⇄ Markdown adapter; when omitted, regions stay plain strings. */
-  richText?: RichTextCodec
-}
-
-/** Thrown by {@link parsePage} with the 1-based source line of the problem. */
-export class PageParseError extends Error {
-  constructor(
-    message: string,
-    public readonly line: number,
-  ) {
-    super(`${message} (line ${line})`)
-    this.name = 'PageParseError'
-    Object.setPrototypeOf(this, PageParseError.prototype)
-  }
-}
-
-// ── Tokenizer ────────────────────────────────────────────────────────────────
-// Structural tokens are recognized ONLY at column 0 (no leading whitespace), so
-// indented YAML block-scalar / nested-mapping content in a head is never mistaken
-// for a fence. Nesting comes from `:::` pairing, not indentation.
-
-type Token =
-  | { kind: 'open'; blockId: string; rest: string }
-  | { kind: 'close'; id?: string }
-  | { kind: 'field'; name: string }
-
-const CLOSE_BARE = /^:::[ \t]*$/
-const CLOSE_LABELED = /^:::[ \t]*\/[ \t]*([A-Za-z][\w-]*)?[ \t]*$/
-const OPEN = /^:::[ \t]+([A-Za-z][\w-]*)[ \t]*(.*)$/
-const FIELD = /^@([A-Za-z][\w.-]*)[ \t]*$/
-
-/** Classify a line as a structural token, or null when it's head/region content. */
-function classify(line: string): Token | null {
-  if (/^[ \t]/.test(line)) return null // indented → content, never a token
-  let m: RegExpExecArray | null
-  if (CLOSE_BARE.test(line)) return { kind: 'close' }
-  if ((m = CLOSE_LABELED.exec(line))) return { kind: 'close', id: m[1] || undefined }
-  if ((m = OPEN.exec(line))) return { kind: 'open', blockId: m[1]!, rest: m[2]! }
-  if ((m = FIELD.exec(line))) return { kind: 'field', name: m[1]! }
-  return null
-}
-
-/** Leading run of backticks/tildes that opens or closes a Markdown code fence. */
-function matchFence(line: string): string | null {
-  const m = /^[ \t]*([`~]{3,})/.exec(line)
-  return m ? m[1]! : null
-}
-
-/** Strip the common leading indentation from a block of lines (blank lines ignored). */
-function dedent(lines: string[]): string[] {
-  let min = Infinity
-  for (const line of lines) {
-    if (line.trim() === '') continue
-    min = Math.min(min, /^[ \t]*/.exec(line)![0].length)
-  }
-  if (!isFinite(min) || min === 0) return lines.slice()
-  return lines.map((line) => (line.trim() === '' ? line.trimStart() : line.slice(min)))
-}
-
-/** Set `data[a.b.c] = value`, creating intermediate objects. */
-function setPath(data: Record<string, unknown>, path: string, value: unknown): void {
-  const parts = path.split('.')
-  let target = data
-  for (let i = 0; i < parts.length - 1; i++) {
-    const key = parts[i]!
-    if (typeof target[key] !== 'object' || target[key] === null) target[key] = {}
-    target = target[key] as Record<string, unknown>
-  }
-  target[parts[parts.length - 1]!] = value
-}
-
-interface Frame {
-  block: ContentBlock
-  headBuf: string[]
-  region: { name: string; lines: string[]; fence: string | null } | null
-}
-
-/** Parse a `.page.md` document into a {@link PageDoc}. */
-export function parsePage(text: string, options?: PageCodecOptions): PageDoc {
-  const lines = text.replace(/\r\n/g, '\n').split('\n')
-  let i = 0
-
-  // 1. Frontmatter (the page envelope).
-  let envelope: Record<string, unknown> = {}
-  if (lines[0] === '---') {
-    let j = 1
-    while (j < lines.length && lines[j] !== '---') j++
-    if (j >= lines.length) throw new PageParseError('Unterminated frontmatter (missing closing ---)', 1)
-    try {
-      envelope = (parseYaml(lines.slice(1, j).join('\n')) as Record<string, unknown>) ?? {}
-    } catch (error) {
-      throw new PageParseError(`Invalid frontmatter YAML: ${(error as Error).message}`, 1)
-    }
-    i = j + 1
-  }
-
-  // 2. Block fences (the content tree).
-  const root: ContentBlock[] = []
-  const stack: Frame[] = []
-  const counter = { n: 0 }
-
-  const flushHead = (frame: Frame, line: number): void => {
-    if (frame.headBuf.length === 0) return
-    const yamlText = dedent(frame.headBuf).join('\n')
-    frame.headBuf = []
-    if (yamlText.trim() === '') return
-    let parsed: unknown
-    try {
-      parsed = parseYaml(yamlText)
-    } catch (error) {
-      throw new PageParseError(`Invalid block head YAML: ${(error as Error).message}`, line)
-    }
-    if (parsed && typeof parsed === 'object') Object.assign(frame.block.data, parsed)
-  }
-
-  const finalizeRegion = (frame: Frame): void => {
-    const region = frame.region!
-    const body = dedent(region.lines)
-    while (body.length && body[0]!.trim() === '') body.shift()
-    while (body.length && body[body.length - 1]!.trim() === '') body.pop()
-    const raw = body.join('\n')
-    const value = options?.richText?.isRichText(frame.block.blockId, region.name)
-      ? options.richText.toBlocks(raw)
-      : raw
-    setPath(frame.block.data, region.name, value)
-    frame.region = null
-  }
-
-  for (; i < lines.length; i++) {
-    const line = lines[i]!
-    const frame = stack[stack.length - 1]
-
-    // Region capture: a @field is open on the current block.
-    if (frame?.region) {
-      const region = frame.region
-      const fence = matchFence(line)
-      if (region.fence !== null) {
-        region.lines.push(line)
-        if (fence && fence.length >= region.fence.length && line.trimStart().startsWith(region.fence)) {
-          region.fence = null
-        }
-        continue
-      }
-      if (fence) {
-        region.lines.push(line)
-        region.fence = fence
-        continue
-      }
-      if (line.startsWith('\\:::') || /^\\@[A-Za-z]/.test(line)) {
-        region.lines.push(line.slice(1)) // de-escape a literal line-initial token
-        continue
-      }
-      if (classify(line) === null) {
-        region.lines.push(line)
-        continue
-      }
-      finalizeRegion(frame) // a structural token ends the region; fall through to handle it
-    }
-
-    const token = classify(line)
-    if (token === null) {
-      if (!frame) {
-        if (line.trim() === '') continue
-        throw new PageParseError(`Content outside any block: "${line.trim()}"`, i + 1)
-      }
-      frame.headBuf.push(line)
-      continue
-    }
-
-    if (token.kind === 'open') {
-      if (frame) flushHead(frame, i + 1)
-      const { id, slot, v } = parseAttrs(token.rest, i + 1)
-      const block: ContentBlock = { id: id ?? `auto${++counter.n}`, blockId: token.blockId, data: {} }
-      if (v !== undefined) block.v = v
-      attach(root, frame, block, slot, i + 1)
-      stack.push({ block, headBuf: [], region: null })
-    } else if (token.kind === 'field') {
-      if (!frame) throw new PageParseError(`@${token.name} outside any block`, i + 1)
-      flushHead(frame, i + 1)
-      frame.region = { name: token.name, lines: [], fence: null }
-    } else {
-      if (!frame) throw new PageParseError('Close ::: with no open block', i + 1)
-      flushHead(frame, i + 1)
-      if (token.id && token.id !== frame.block.blockId) {
-        throw new PageParseError(
-          `Labeled close "::: /${token.id}" does not match open block "::: ${frame.block.blockId}"`,
-          i + 1,
-        )
-      }
-      stack.pop()
-    }
-  }
-
-  if (stack.length) {
-    throw new PageParseError(`Unclosed block "::: ${stack[stack.length - 1]!.block.blockId}"`, lines.length)
-  }
-
-  return {
-    ...(typeof envelope.name === 'string' ? { name: envelope.name } : {}),
-    ...(envelope.draft === true ? { draft: true } : {}),
-    ...(envelope.meta !== undefined ? { meta: envelope.meta as Record<string, unknown> } : {}),
-    ...(typeof envelope.order === 'number' ? { order: envelope.order } : {}),
-    ...(envelope.orderAfter != null ? { orderAfter: envelope.orderAfter as string } : {}),
-    ...(typeof envelope.path === 'string' ? { path: envelope.path } : {}),
-    data: (envelope.data as Record<string, unknown>) ?? {},
-    content: root,
-  }
-}
-
-/** Parse the `#id` and `key=value` attributes after a block id on an open fence. */
-function parseAttrs(rest: string, line: number): { id?: string; slot?: string; v?: number } {
-  const out: { id?: string; slot?: string; v?: number } = {}
-  for (const part of rest.trim().split(/[ \t]+/).filter(Boolean)) {
-    if (part.startsWith('#')) out.id = part.slice(1)
-    else if (part.startsWith('slot=')) out.slot = part.slice(5)
-    else if (/^v=\d+$/.test(part)) out.v = Number(part.slice(2))
-    else throw new PageParseError(`Unknown block attribute "${part}"`, line)
-  }
-  return out
-}
-
-/** Place a freshly-opened block into its parent slot (or the page root). */
-function attach(
-  root: ContentBlock[],
-  parent: Frame | undefined,
-  block: ContentBlock,
-  slot: string | undefined,
-  line: number,
-): void {
-  if (!parent) {
-    if (slot) throw new PageParseError('A root-level block cannot have a slot', line)
-    root.push(block)
-    return
-  }
-  const owner = parent.block
-  if (slot) {
-    if (owner.children == null) owner.children = {}
-    if (Array.isArray(owner.children)) {
-      throw new PageParseError(`Block "::: ${owner.blockId}" mixes default and named slots`, line)
-    }
-    const map = owner.children as Record<string, ContentBlock[]>
-    ;(map[slot] ??= []).push(block)
-  } else {
-    if (owner.children == null) owner.children = []
-    if (!Array.isArray(owner.children)) {
-      throw new PageParseError(`Block "::: ${owner.blockId}" mixes default and named slots`, line)
-    }
-    owner.children.push(block)
-  }
-}
-
-// ── Serializer ───────────────────────────────────────────────────────────────
-
-/** A top-level string prop becomes an `@field` region past this length, or on any newline. */
-const REGION_THRESHOLD = 80
-const FLOW_MAX = 72
-
-/** Serialize a {@link PageDoc} into canonical `.page.md` text. */
-export function serializePage(doc: PageDoc, options?: PageCodecOptions): string {
-  const envelope: Record<string, unknown> = {}
-  if (doc.name !== undefined) envelope.name = doc.name
-  // Only emit `draft` when true — published pages stay clean (like `order`).
-  if (doc.draft) envelope.draft = true
-  if (doc.meta !== undefined) envelope.meta = doc.meta
-  envelope.data = doc.data ?? {}
-  if (doc.order !== undefined) envelope.order = doc.order
-  if (doc.orderAfter != null) envelope.orderAfter = doc.orderAfter
-  if (doc.path !== undefined) envelope.path = doc.path
-
-  const out: string[] = ['---', emitYaml(envelope), '---', '']
-  for (const block of doc.content) emitBlock(block, undefined, out, options)
-  return out.join('\n').replace(/\n+$/, '') + '\n'
-}
-
-function emitBlock(
-  block: ContentBlock,
-  slot: string | undefined,
-  out: string[],
-  options?: PageCodecOptions,
-): void {
-  let open = `::: ${block.blockId}`
-  if (block.id) open += ` #${block.id}`
-  if (slot) open += ` slot=${slot}`
-  if (block.v !== undefined) open += ` v=${block.v}`
-  out.push(open)
-
-  const head: Record<string, unknown> = {}
-  const regions: [string, string][] = []
-  for (const [key, value] of Object.entries(block.data)) {
-    // Rich-text fields are always written as a Markdown region (vuewrite Block[]
-    // → Markdown), regardless of length, so they read as prose on disk.
-    if (options?.richText?.isRichText(block.blockId, key) && Array.isArray(value)) {
-      regions.push([key, options.richText.toMarkdown(value)])
-    } else if (typeof value === 'string' && (value.includes('\n') || value.length > REGION_THRESHOLD)) {
-      regions.push([key, value])
-    } else {
-      head[key] = value
-    }
-  }
-  if (Object.keys(head).length) out.push(emitYaml(head))
-  for (const [name, value] of regions) {
-    out.push(`@${name}`)
-    out.push(escapeRegion(value))
-  }
-
-  let hasChildren = false
-  const children = block.children
-  if (Array.isArray(children)) {
-    for (const child of children) emitBlock(child, undefined, out, options)
-    hasChildren = children.length > 0
-  } else if (children && typeof children === 'object') {
-    for (const [slotName, list] of Object.entries(children)) {
-      for (const child of list) emitBlock(child, slotName, out, options)
-      if (list.length) hasChildren = true
-    }
-  }
-
-  out.push(hasChildren ? `::: /${block.blockId}` : ':::')
-  out.push('')
-}
-
-/** Backslash-escape any line-initial structural token in raw region text (outside code fences). */
-function escapeRegion(text: string): string {
-  let fence: string | null = null
-  return text
-    .split('\n')
-    .map((line) => {
-      const mark = matchFence(line)
-      if (fence !== null) {
-        if (mark && mark.length >= fence.length && line.trimStart().startsWith(fence)) fence = null
-        return line
-      }
-      if (mark) {
-        fence = mark
-        return line
-      }
-      return classify(line) !== null ? '\\' + line : line
-    })
-    .join('\n')
-}
-
-/**
- * Emit a value as YAML. The root mapping always stays block style (one prop per
- * line); only nested collections collapse to flow when short and all-scalar.
- */
-function emitYaml(value: unknown): string {
-  const doc = new Document(value)
-  const root = doc.contents as YamlNode
-  if (isSeq(root)) for (const item of root.items) applyFlow(item)
-  else if (isMap(root)) for (const pair of root.items) applyFlow(pair.value)
-  return doc.toString({ lineWidth: 0 }).replace(/\n$/, '')
-}
-
-type YamlNode = any
-
-function applyFlow(node: YamlNode): void {
-  if (isSeq(node)) {
-    for (const item of node.items) if (isCollection(item)) applyFlow(item)
-    node.flow = node.items.length === 0 || (node.items.every(isScalar) && inlineLen(node) <= FLOW_MAX)
-  } else if (isMap(node)) {
-    for (const pair of node.items) if (isCollection(pair.value)) applyFlow(pair.value)
-    node.flow =
-      node.items.length === 0 ||
-      (node.items.every((pair: YamlNode) => isScalar(pair.value)) && inlineLen(node) <= FLOW_MAX)
-  }
-}
-
-function inlineLen(node: YamlNode): number {
-  if (isScalar(node)) return String(node.value ?? 'null').length + 2
-  if (isSeq(node)) return 4 + node.items.reduce((sum: number, item: YamlNode) => sum + inlineLen(item) + 2, 0)
-  if (isMap(node)) {
-    return (
-      4 +
-      node.items.reduce(
-        (sum: number, pair: YamlNode) => sum + String(pair.key?.value ?? pair.key).length + 2 + inlineLen(pair.value) + 2,
-        0,
-      )
-    )
-  }
-  return 0
-}

package/src/query-engine.ts

@@ -1,175 +0,0 @@
-import { getValueByPath } from './schema'
-
-/**
- * The query engine: resolves the runtime's query keys (`usePages`,
- * `usePagination`, `useFetch`) against an abstract {@link QuerySource}. One
- * implementation, three callers — the dev server (live `.mech` store), the
- * static export (resolved at build time and baked into `window.state.query`),
- * and a future hosted backend (its own source). Pure and DOM/fs-free; the
- * source supplies all I/O.
- */
-
-/** A page entry as the engine consumes it (requested data entries embedded). */
-export interface PageQueryItem {
-  path: string
-  name: string
-  folderPath?: string | null
-  order?: number
-  orderAfter?: string | null
-  /** Draft pages are dropped from query results (see {@link resolvePagesQuery}). */
-  draft?: boolean
-  [dataId: string]: unknown
-}
-
-/** What a caller must supply for the engine to resolve queries. */
-export interface QuerySource {
-  /**
-   * List all pages, with the requested page-scoped data entries embedded. With
-   * a `locale` (a non-default code) only pages translated to it are listed, and
-   * each item's data/name come from the translation — so a translated listing
-   * shows translated content and never links to an untranslated page.
-   */
-  listPages(options: { data?: { id: string }[]; locale?: string }): PageQueryItem[]
-  /** Fetch external JSON (`useFetch`). Omit to disable fetch queries. */
-  fetchJson?(options: { url: string } & Record<string, unknown>): Promise<unknown>
-}
-
-/** Arguments of a `getPages` query (the JSON part of its key). */
-export interface PagesQueryArgs {
-  /** Only pages inside this folder path (e.g. `'blog'`). */
-  folderName?: string
-  /** Page-scoped data entries to embed in each result. */
-  data?: { id: string }[]
-  /**
-   * Sort field: `'name'`, `'path'`, or a dotted path into an included data
-   * entry (e.g. `'postMeta.date'`). Default: the store's page order.
-   */
-  sort?: { by: string; dir?: 'asc' | 'desc' }
-  /** Cap the number of results (non-paginated queries). */
-  limit?: number
-  /** Split results into pages of this size — the query becomes paginated. */
-  pageSize?: number
-}
-
-/** The shape a paginated `getPages` query resolves to. */
-export interface PaginatedPagesResult {
-  items: PageQueryItem[]
-  /** Current page number (1-based, clamped to `pageCount`). */
-  page: number
-  pageCount: number
-  pageSize: number
-  total: number
-}
-
-/** Extra context for resolving a key (which paginated variant to slice). */
-export interface QueryContext {
-  /** 1-based page number for paginated queries. Default 1. */
-  page?: number
-  /** The locale to resolve `getPages` against (multi-language sites); a non-default code. */
-  locale?: string
-}
-
-/** Split a query key (`"<type>.<json-args>"`) into its type and parsed args. */
-export function parseQueryKey(key: string): { type: string; args: Record<string, unknown> } {
-  const dot = key.indexOf('.')
-  if (dot === -1) return { type: key, args: {} }
-  const type = key.slice(0, dot)
-  const raw = key.slice(dot + 1)
-  try {
-    const parsed: unknown = JSON.parse(raw || '{}')
-    return { type, args: parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {} }
-  } catch {
-    return { type, args: {} }
-  }
-}
-
-/** Whether a key is a paginated `getPages` query (drives export page-splitting). */
-export function isPaginatedQuery(key: string): boolean {
-  const { type, args } = parseQueryKey(key)
-  return type === 'getPages' && typeof args.pageSize === 'number' && args.pageSize > 0
-}
-
-/** Compare possibly-missing values: numbers numerically, everything else as strings. */
-function compareValues(a: unknown, b: unknown): number {
-  if (a == null && b == null) return 0
-  if (a == null) return 1 // missing values sort last regardless of direction
-  if (b == null) return -1
-  if (typeof a === 'number' && typeof b === 'number') return a - b
-  return String(a).localeCompare(String(b))
-}
-
-/**
- * Resolve a `getPages` query: filter by folder, sort, and either cap (`limit`)
- * or paginate (`pageSize`). Internal ordering fields are stripped from results.
- */
-export function resolvePagesQuery(
-  source: QuerySource,
-  args: PagesQueryArgs,
-  context: QueryContext = {},
-): PageQueryItem[] | PaginatedPagesResult {
-  // Drafts are never visible to queries (`usePages`/`usePagination`), across
-  // every caller (dev server, static export, future backend). On a translated
-  // page the listing is resolved in that locale (translated data, translated
-  // pages only).
-  let pages = source.listPages({ data: args.data, locale: context.locale }).filter((page) => !page.draft)
-
-  if (args.folderName) {
-    // "Pages in this folder" means its children — the folder's own index page
-    // (usually the page doing the listing) is excluded.
-    const indexPath = '/' + args.folderName.replace(/^\/+|\/+$/g, '')
-    pages = pages.filter((page) => page.folderPath === args.folderName && page.path !== indexPath)
-  }
-
-  if (args.sort?.by) {
-    const { by, dir } = args.sort
-    const sign = dir === 'desc' ? -1 : 1
-    pages = pages
-      .map((page) => ({ page, field: getValueByPath(page, by) }))
-      .sort((a, b) => {
-        // Missing values sort last in either direction.
-        if (a.field == null || b.field == null) return compareValues(a.field, b.field)
-        return compareValues(a.field, b.field) * sign
-      })
-      .map((entry) => entry.page)
-  }
-
-  const items = pages.map(({ order, orderAfter, folderPath, draft, ...rest }) => rest)
-
-  if (args.pageSize && args.pageSize > 0) {
-    const total = items.length
-    const pageCount = Math.max(1, Math.ceil(total / args.pageSize))
-    const page = Math.min(Math.max(1, context.page ?? 1), pageCount)
-    return {
-      items: items.slice((page - 1) * args.pageSize, page * args.pageSize),
-      page,
-      pageCount,
-      pageSize: args.pageSize,
-      total,
-    }
-  }
-
-  return typeof args.limit === 'number' && args.limit >= 0 ? items.slice(0, args.limit) : items
-}
-
-/**
- * Resolve any query key against a source. Unknown types resolve to `{}` (the
- * runtime containers keep their initial shape). `fetch` keys require the
- * source to provide `fetchJson`.
- */
-export async function resolveQueryKey(
-  source: QuerySource,
-  key: string,
-  context: QueryContext = {},
-): Promise<unknown> {
-  const { type, args } = parseQueryKey(key)
-
-  if (type === 'getPages') return resolvePagesQuery(source, args as PagesQueryArgs, context)
-
-  if (type === 'fetch') {
-    if (!source.fetchJson) return {}
-    if (typeof args.url !== 'string' || !args.url) return {}
-    return source.fetchJson(args as { url: string })
-  }
-
-  return {}
-}