mechanica-shared 2.0.0-alpha.9 → 2.0.2

package/src/schema.ts

@@ -1,137 +0,0 @@
-import type { Block, ContentBlock } from './types'
-import { getFieldDefault } from './fields'
-
-/**
- * Compute the default value for a (compact-unfolded) schema node, consulting the
- * field registry for format-specific defaults (e.g. `image`, `richText`).
- */
-export function getDefaultValue(schema: any): any {
-  if (schema.default !== undefined) return schema.default
-  if (schema.nullable) return null
-
-  if (schema.format) {
-    const fieldDefault = getFieldDefault(schema.format)
-    if (fieldDefault !== undefined) return fieldDefault
-  }
-
-  if (schema.type === 'number' || schema.type === 'integer') return 0
-  if (schema.type === 'object') {
-    if (!schema.properties) return {}
-    return Object.fromEntries(
-      Object.entries(schema.properties).map(([key, value]) => {
-        if (!schema.required?.includes(key)) return [key, undefined]
-        return [key, getDefaultValue(value)]
-      }),
-    )
-  }
-  if (schema.type === 'array') return []
-  if (schema.type === 'boolean') return false
-  return ''
-}
-
-/**
- * Fill missing values in `state` with schema defaults, recursing into objects.
- * Returns `state` when present, otherwise a freshly generated default.
- */
-export function passDefaultValue(state: any, schema: any): any {
-  if (!schema) return state
-  if (schema.type === 'object' && state) {
-    for (const key in schema.properties) {
-      if (!(key in state) && !schema.required?.includes(key)) continue
-      state[key] = passDefaultValue(state[key], schema.properties[key])
-    }
-  }
-  return state ?? getDefaultValue(schema)
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** Deep-merge `patch` over `base`: plain objects merge, arrays and scalars replace. */
-export function mergePreviewData(
-  base: Record<string, unknown>,
-  patch: Record<string, unknown>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = { ...base }
-  for (const [key, value] of Object.entries(patch)) {
-    const current = out[key]
-    out[key] =
-      isPlainObject(current) && isPlainObject(value) ? mergePreviewData(current, value) : value
-  }
-  return out
-}
-
-/**
- * Resolve the data a block should render with outside a page: schema defaults,
- * overlaid with the block's authored `previewData`, overlaid with per-call
- * overrides (e.g. the `?data=` payload of the preview route).
- *
- * @param props Unfolded (JSON-schema shaped) props schema, as on `Block.props`.
- */
-export function buildPreviewData(
-  props: Record<string, unknown> | undefined,
-  previewData?: Record<string, unknown>,
-  overrides?: Record<string, unknown>,
-): Record<string, unknown> {
-  const defaults = props ? getDefaultValue(props) : {}
-  const base = isPlainObject(defaults) ? defaults : {}
-  return mergePreviewData(mergePreviewData(base, previewData ?? {}), overrides ?? {})
-}
-
-/** Depth-first walk over a content tree, including array and named-slot children. */
-export function walkTree(blocks: ContentBlock[], callback: (block: ContentBlock) => void): void {
-  for (const block of blocks) {
-    callback(block)
-    if (!block.children) continue
-    if (Array.isArray(block.children)) {
-      walkTree(block.children, callback)
-    } else {
-      for (const list of Object.values(block.children)) {
-        walkTree(list, callback)
-      }
-    }
-  }
-}
-
-type WalkSchemaCallback = (
-  value: any,
-  schema: any,
-  key?: string,
-  parent?: any,
-  isRequired?: boolean,
-) => void
-
-/** Walk a value alongside its schema, invoking `callback` for each described node. */
-export function walkSchema(obj: any, schema: Block['props'] | any, callback: WalkSchemaCallback): void {
-  if (schema.type === 'object' && schema.properties && obj) {
-    for (const [key, childSchema] of Object.entries(schema.properties)) {
-      const isRequired = schema.required?.includes(key) ?? false
-      callback(obj[key], childSchema, key, obj, isRequired)
-
-      const childType = (childSchema as any).type
-      if (childType === 'array' || childType === 'object') {
-        walkSchema(obj[key], childSchema, callback)
-      }
-    }
-  }
-
-  if (schema.type === 'array' && schema.items && obj) {
-    for (const value of obj) {
-      callback(value, schema.items)
-      if (schema.items.type === 'array' || schema.items.type === 'object') {
-        walkSchema(value, schema.items, callback)
-      }
-    }
-  }
-}
-
-/** Resolve a dotted path within a data object (`'postMeta.date'`). */
-export function getValueByPath(data: any, path: string): unknown {
-  let value = data
-  for (const key of path.split('.')) {
-    if (value == null) return value
-    value = value[key]
-  }
-  return value
-}

package/src/seo.ts

@@ -1,228 +0,0 @@
-import { serializeState } from './generate-page'
-
-/**
- * SEO helpers shared by `mechanica export` and the future render backend.
- * Everything here is pure string work over already-rendered HTML — DOM-free,
- * like the rest of this package.
- */
-
-/** The public URL of an exported page: origin + directory-style path. */
-export function pageUrl(siteUrl: string, path: string): string {
-  const base = siteUrl.replace(/\/+$/, '')
-  return path === '/' ? `${base}/` : `${base}${path}/`
-}
-
-/** The path of the n-th chunk of a paginated page (`/blog` → `/blog/2`). */
-export function paginationVariantPath(basePath: string, page: number): string {
-  if (page <= 1) return basePath
-  return `${basePath === '/' ? '' : basePath}/${page}`
-}
-
-export interface SeoTagOptions {
-  /** Absolute site origin (`https://example.com`). Enables all URL-based tags. */
-  siteUrl?: string
-  /** Site display name — emits WebSite JSON-LD on the root page. */
-  siteName?: string
-  /** The page's exported path (`/`, `/blog`, `/blog/2`). */
-  path: string
-  /** Inject `<meta name="robots" content="noindex">`. */
-  noindex?: boolean
-  /** Set for paginated pages (page 1 included) — emits prev/next + title suffix. */
-  pagination?: { page: number; pageCount: number; basePath: string }
-  /**
-   * True when the index template references `page.pagination` itself — the
-   * author handles variant titles, so no automatic "— Page N" suffix.
-   */
-  templateHandlesPagination?: boolean
-  /** Breadcrumb trail (root first) — emits BreadcrumbList JSON-LD. */
-  breadcrumbs?: { name: string; path: string }[]
-  /**
-   * Language alternates for a translated page — emits `<link rel="alternate"
-   * hreflang="…">` per locale plus an `x-default`. `path` is each locale's
-   * exported path (already locale-prefixed); `hreflang` its code (`x-default`
-   * for the default). Skipped when the page has only one locale.
-   */
-  alternates?: { hreflang: string; path: string }[]
-}
-
-/** Meta properties whose `content` must be an absolute URL per the OG/Twitter specs. */
-const ABSOLUTE_URL_METAS =
-  /^(?:og:url|og:image(?::url|:secure_url)?|og:video(?::url|:secure_url)?|og:audio(?::url|:secure_url)?|twitter:image(?::src)?)$/
-
-/**
- * Rewrite root-relative `content` values (`/media/x.jpg`) of Open Graph /
- * Twitter URL metas to absolute URLs — crawlers reject relative ones, so a
- * templated `{{ head.image.src }}` would otherwise silently break link previews.
- */
-function absolutizeSocialUrls(html: string, siteUrl: string): string {
-  const base = siteUrl.replace(/\/+$/, '')
-  return html.replace(/<meta\b[^>]*>/gi, (tag) => {
-    const name = tag.match(/(?:property|name)\s*=\s*["']([^"']+)["']/i)?.[1]
-    if (!name || !ABSOLUTE_URL_METAS.test(name)) return tag
-    // Root-relative only; `//host/…` protocol-relative URLs are left alone.
-    return tag.replace(/(content\s*=\s*["'])\/(?!\/)/i, `$1${base}/`)
-  })
-}
-
-/** An inline JSON-LD script (script-safe serialization — see serializeState). */
-function jsonLdScript(value: unknown): string {
-  return `<script type="application/ld+json">${serializeState(value)}</script>`
-}
-
-/**
- * Inject the SEO tags a page can't reasonably be asked to author by hand:
- * canonical URL, `og:url`, absolute social-image URLs, robots noindex,
- * pagination prev/next + "— Page N" titles, and WebSite / BreadcrumbList
- * JSON-LD. Tags the template already contains are never duplicated, so a
- * hand-authored `<head>` always wins.
- */
-export function applySeoTags(html: string, options: SeoTagOptions): string {
-  if (!html.includes('</head>')) return html
-  const { siteUrl, pagination } = options
-  const tags: string[] = []
-
-  if (siteUrl) {
-    html = absolutizeSocialUrls(html, siteUrl)
-    const url = pageUrl(siteUrl, options.path)
-    if (!/rel\s*=\s*["']canonical["']/i.test(html)) tags.push(`<link rel="canonical" href="${url}">`)
-    if (!/(?:property|name)\s*=\s*["']og:url["']/i.test(html)) {
-      tags.push(`<meta property="og:url" content="${url}">`)
-    }
-  }
-
-  if (options.noindex && !/name\s*=\s*["']robots["']/i.test(html)) {
-    tags.push('<meta name="robots" content="noindex">')
-  }
-
-  if (pagination) {
-    // Variants otherwise ship the base page's exact <title> — duplicate titles
-    // across /blog, /blog/2, … — unless the template handles pagination itself.
-    if (pagination.page > 1 && !options.templateHandlesPagination) {
-      html = html.replace(
-        /<title>([\s\S]*?)<\/title>/i,
-        (_match, title) => `<title>${title} — Page ${pagination.page}</title>`,
-      )
-    }
-    if (siteUrl) {
-      if (pagination.page > 1) {
-        const prev = paginationVariantPath(pagination.basePath, pagination.page - 1)
-        tags.push(`<link rel="prev" href="${pageUrl(siteUrl, prev)}">`)
-      }
-      if (pagination.page < pagination.pageCount) {
-        const next = paginationVariantPath(pagination.basePath, pagination.page + 1)
-        tags.push(`<link rel="next" href="${pageUrl(siteUrl, next)}">`)
-      }
-    }
-  }
-
-  // hreflang alternates for a translated page (each locale + x-default). Emitted
-  // only with a site url — the hrefs must be absolute for crawlers.
-  if (siteUrl && options.alternates && options.alternates.length > 1) {
-    for (const alt of options.alternates) {
-      const href = pageUrl(siteUrl, alt.path)
-      if (!new RegExp(`hreflang\\s*=\\s*["']${alt.hreflang}["']`, 'i').test(html)) {
-        tags.push(`<link rel="alternate" hreflang="${alt.hreflang}" href="${href}">`)
-      }
-    }
-  }
-
-  if (siteUrl && options.siteName && options.path === '/' && !/"@type"\s*:\s*"WebSite"/.test(html)) {
-    tags.push(
-      jsonLdScript({
-        '@context': 'https://schema.org',
-        '@type': 'WebSite',
-        name: options.siteName,
-        url: pageUrl(siteUrl, '/'),
-      }),
-    )
-  }
-
-  const crumbs = options.breadcrumbs
-  if (siteUrl && crumbs && crumbs.length > 1 && !/"@type"\s*:\s*"BreadcrumbList"/.test(html)) {
-    tags.push(
-      jsonLdScript({
-        '@context': 'https://schema.org',
-        '@type': 'BreadcrumbList',
-        itemListElement: crumbs.map((crumb, i) => ({
-          '@type': 'ListItem',
-          position: i + 1,
-          name: crumb.name,
-          item: pageUrl(siteUrl, crumb.path),
-        })),
-      }),
-    )
-  }
-
-  if (tags.length) html = html.replace('</head>', `${tags.join('\n')}\n</head>`)
-  return html
-}
-
-/**
- * Cheap regex-level SEO audit of a rendered page. Returns human-readable
- * issues (empty title, missing description, h1 problems, images without alt)
- * — the export surfaces them as warnings, same philosophy as the link validator.
- */
-export function auditPageHtml(html: string): string[] {
-  const issues: string[] = []
-
-  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
-  if (!title) issues.push('no <title> tag')
-  else if (!title[1]!.trim()) issues.push('empty <title>')
-
-  let description: string | undefined
-  for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
-    if (!/name\s*=\s*["']description["']/i.test(tag)) continue
-    description = tag.match(/content\s*=\s*["']([^"']*)["']/i)?.[1] ?? ''
-  }
-  if (description === undefined) issues.push('no meta description')
-  else if (!description.trim()) issues.push('empty meta description')
-
-  const h1Count = (html.match(/<h1[\s>]/gi) ?? []).length
-  if (h1Count === 0) issues.push('no <h1> heading')
-  else if (h1Count > 1) issues.push(`${h1Count} <h1> headings — search engines expect one`)
-
-  const missingAlt = (html.match(/<img\b[^>]*>/gi) ?? []).filter((tag) => !/\balt\s*=/i.test(tag)).length
-  if (missingAlt > 0) issues.push(`${missingAlt} <img> without alt text`)
-
-  return issues
-}
-
-export interface SitemapEntry {
-  path: string
-  /** ISO date (`2026-07-04`) — emitted as `<lastmod>`. */
-  lastmod?: string
-  /**
-   * Language alternates for a translated page — each locale's exported path
-   * plus `x-default` — emitted as `<xhtml:link rel="alternate" hreflang="…">`.
-   */
-  alternates?: { hreflang: string; path: string }[]
-}
-
-/** Build a sitemap.xml for the exported pages (directory-style URLs). */
-export function buildSitemap(siteUrl: string, entries: SitemapEntry[]): string {
-  const hasAlternates = entries.some((entry) => entry.alternates && entry.alternates.length > 1)
-  const urls = [...entries]
-    .sort((a, b) => a.path.localeCompare(b.path))
-    .map(({ path, lastmod, alternates }) => {
-      const suffix = lastmod ? `<lastmod>${lastmod}</lastmod>` : ''
-      const links =
-        alternates && alternates.length > 1
-          ? alternates
-              .map(
-                (alt) =>
-                  `<xhtml:link rel="alternate" hreflang="${alt.hreflang}" href="${pageUrl(siteUrl, alt.path)}"/>`,
-              )
-              .join('')
-          : ''
-      return `  <url><loc>${pageUrl(siteUrl, path)}</loc>${suffix}${links}</url>`
-    })
-  const urlsetOpen = hasAlternates
-    ? '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">'
-    : '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
-  return ['<?xml version="1.0" encoding="UTF-8"?>', urlsetOpen, ...urls, '</urlset>', ''].join('\n')
-}
-
-/** The default robots.txt emitted alongside a sitemap (unless the site ships its own). */
-export function buildRobotsTxt(siteUrl: string): string {
-  return `User-agent: *\nAllow: /\n\nSitemap: ${siteUrl.replace(/\/+$/, '')}/sitemap.xml\n`
-}

package/src/translation.ts

@@ -1,169 +0,0 @@
-/**
- * Translation overlays — pure, DOM-free helpers that let a page's `@locale`
- * file store *only* what it changes and inherit everything else from the
- * default-locale page. The mechanism mirrors the localized shared-data pattern
- * (diff-against-base), one level deeper: inside a page's block tree.
- *
- * Two directions:
- *  - {@link mergeTranslation} — read time (dev `buildPageState` + static export):
- *    overlay the sparse translation on the base so shared fields (images, links,
- *    colors, layout) resolve to the default-locale value automatically.
- *  - {@link diffTranslation} — save time: strip everything a translation shares
- *    with the base, so the file on disk carries only the genuinely translated
- *    fields (and stays a readable, reviewable diff).
- *
- * Two structural rules, both following the "**base owns structure**" model:
- *  - **Blocks** are matched by their stable `id`. The base owns which blocks
- *    exist and their order; a translation only fills fields on the blocks it
- *    shares. A block added to the base appears in every locale (untranslated).
- *  - Within a block's `data`, **objects deep-merge** (so an image's `alt` can be
- *    translated while its `src` inherits), while **arrays and scalars replace
- *    wholesale** — an array (rich text, a list of cards) is an atomic unit: a
- *    translation either inherits it or overrides it entirely, never a mix (which
- *    would interleave translated and untranslated entries).
- */
-
-import type { ContentBlock } from './types'
-
-type Data = Record<string, unknown>
-type Children = ContentBlock['children']
-
-function isPlainObject(value: unknown): value is Data {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** Structural deep-equality (objects key-insensitive to order, arrays ordered). */
-export function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return a.length === b.length && a.every((value, i) => deepEqual(value, b[i]))
-  }
-  if (isPlainObject(a) && isPlainObject(b)) {
-    const keys = Object.keys(a)
-    if (keys.length !== Object.keys(b).length) return false
-    return keys.every((key) => key in b && deepEqual(a[key], b[key]))
-  }
-  return false
-}
-
-/**
- * Overlay a translation `overlay` value on its `base`: objects deep-merge
- * (per-key inheritance), arrays and scalars are taken from the overlay when it
- * provides one, and an absent overlay (`undefined`) inherits the base.
- */
-export function mergeValue(base: unknown, overlay: unknown): unknown {
-  if (overlay === undefined) return base
-  if (isPlainObject(base) && isPlainObject(overlay)) {
-    const out: Data = { ...base }
-    for (const key of Object.keys(overlay)) out[key] = mergeValue(base[key], overlay[key])
-    return out
-  }
-  return overlay
-}
-
-/**
- * The sparse diff of a `full` value against its `base`: equal values collapse to
- * `undefined` (inherit), objects keep only their differing keys (recursively),
- * and arrays/scalars are kept whole when changed.
- */
-export function diffValue(base: unknown, full: unknown): unknown {
-  if (deepEqual(base, full)) return undefined
-  if (isPlainObject(base) && isPlainObject(full)) {
-    const out: Data = {}
-    for (const key of Object.keys(full)) {
-      const diff = diffValue(base[key], full[key])
-      if (diff !== undefined) out[key] = diff
-    }
-    return Object.keys(out).length ? out : undefined
-  }
-  return full
-}
-
-/** Overlay translated blocks on the base list, matched by `id` (base owns order). */
-export function mergeBlocks(base: ContentBlock[], overlay: ContentBlock[] | undefined): ContentBlock[] {
-  if (!overlay?.length) return base
-  const byId = new Map(overlay.map((block) => [block.id, block]))
-  return base.map((block) => mergeBlock(block, byId.get(block.id)))
-}
-
-function mergeBlock(base: ContentBlock, overlay: ContentBlock | undefined): ContentBlock {
-  if (!overlay) return base
-  const merged: ContentBlock = {
-    ...base,
-    data: mergeValue(base.data ?? {}, overlay.data ?? {}) as Data,
-  }
-  const children = mergeChildren(base.children, overlay.children)
-  if (children !== undefined) merged.children = children
-  return merged
-}
-
-function mergeChildren(base: Children, overlay: Children): Children {
-  if (base === undefined) return undefined
-  if (Array.isArray(base)) {
-    return mergeBlocks(base, Array.isArray(overlay) ? overlay : undefined)
-  }
-  const overlaySlots = overlay && !Array.isArray(overlay) ? overlay : undefined
-  const out: Record<string, ContentBlock[]> = {}
-  for (const slot of Object.keys(base)) out[slot] = mergeBlocks(base[slot] ?? [], overlaySlots?.[slot])
-  return out
-}
-
-/** Keep only the blocks (and fields) a `full` list changes vs `base` (base owns structure). */
-export function diffBlocks(base: ContentBlock[], full: ContentBlock[]): ContentBlock[] {
-  const byId = new Map(base.map((block) => [block.id, block]))
-  const out: ContentBlock[] = []
-  for (const block of full) {
-    const baseBlock = byId.get(block.id)
-    // Base owns structure: an overlay-only block never renders, so drop it.
-    if (!baseBlock) continue
-    const data = diffValue(baseBlock.data ?? {}, block.data ?? {}) as Data | undefined
-    const children = diffChildren(baseBlock.children, block.children)
-    if (data === undefined && children === undefined) continue
-    const sparse: ContentBlock = { id: block.id, blockId: block.blockId, data: data ?? {} }
-    if (block.v !== undefined) sparse.v = block.v
-    if (children !== undefined) sparse.children = children
-    out.push(sparse)
-  }
-  return out
-}
-
-function diffChildren(base: Children, full: Children): Children | undefined {
-  if (full === undefined) return undefined
-  if (!Array.isArray(full)) {
-    // Named slots.
-    const baseSlots = base && !Array.isArray(base) ? base : undefined
-    const out: Record<string, ContentBlock[]> = {}
-    for (const slot of Object.keys(full)) {
-      const diff = diffBlocks(baseSlots?.[slot] ?? [], full[slot] ?? [])
-      if (diff.length) out[slot] = diff
-    }
-    return Object.keys(out).length ? out : undefined
-  }
-  const diff = diffBlocks(Array.isArray(base) ? base : [], full)
-  return diff.length ? diff : undefined
-}
-
-/** The overlay-able projection of a page: its content tree, page data and frontmatter meta. */
-export interface TranslationDoc {
-  content?: ContentBlock[]
-  data?: Data
-  meta?: Data
-}
-
-/** Read-time: resolve a sparse translation against the default-locale page. */
-export function mergeTranslation(base: TranslationDoc, overlay: TranslationDoc): Required<TranslationDoc> {
-  return {
-    content: mergeBlocks(base.content ?? [], overlay.content),
-    data: mergeValue(base.data ?? {}, overlay.data ?? {}) as Data,
-    meta: mergeValue(base.meta ?? {}, overlay.meta ?? {}) as Data,
-  }
-}
-
-/** Save-time: reduce a full translation to only what differs from the base. */
-export function diffTranslation(base: TranslationDoc, full: TranslationDoc): Required<TranslationDoc> {
-  return {
-    content: diffBlocks(base.content ?? [], full.content ?? []),
-    data: (diffValue(base.data ?? {}, full.data ?? {}) as Data) ?? {},
-    meta: (diffValue(base.meta ?? {}, full.meta ?? {}) as Data) ?? {},
-  }
-}