mechanica-shared 2.0.0-alpha.9 → 2.0.2

package/src/fields.ts

@@ -1,155 +0,0 @@
-import { registerAlias, type SchemaItem } from 'compact-json-schema'
-
-/**
- * Per-field cropping config for the `image` field, declared as an annotation on
- * a block/data schema — e.g. `{ type: 'image', crop: { width: 1200, height: 630 } }`.
- * `true` enables a free crop frame; `{ width, height }` locks the frame's aspect
- * to `width/height` and downscales the derivative to that box; `{ aspect }` locks
- * the ratio without a size cap. The editor's crop dialog reads this off the
- * unfolded schema; the runtime ignores it. See `ImageValue` for what a crop
- * produces on the value (`crop` rect + `croppedSrc`).
- */
-export type ImageCropConfig =
-  | boolean
-  | {
-      /** Target output width in px (locks the crop aspect to width/height). */
-      width?: number
-      /** Target output height in px. */
-      height?: number
-      /** Lock the crop ratio without a size cap; ignored when width & height are set. */
-      aspect?: number
-    }
-
-// Mechanica uses compact-json-schema's `format` keyword for its field aliases
-// (`image`, `smartLink`, …). The library keeps `SchemaAnnotations` minimal
-// (`default` only), so declare `format` here — that's what lets the schemas
-// below (and any block/data schema) carry `format` without an `as SchemaItem`
-// cast. `crop` rides the same channel: an extra keyword on an `image` field that
-// survives unfolding onto the field editor's `schema` prop. The output types for
-// the alias shorthands live in mechanica's `core/field-types.ts` (SchemaTypesMap).
-declare module 'compact-json-schema' {
-  interface SchemaAnnotations {
-    format?: string
-    crop?: ImageCropConfig
-  }
-}
-
-/**
- * A built-in or user-defined editable field type. The *runtime* half lives here
- * (the compact-json-schema alias + a default value); the editor component half
- * is attached separately in the plugin via `defineFieldType`.
- */
-export interface FieldType {
-  /** Format name, e.g. `'image'`. Used as the compact-json-schema alias. */
-  name: string
-  /** The compact-json-schema definition this alias expands to. */
-  schema: SchemaItem
-  /** Default value, or a factory returning a fresh one. */
-  default?: unknown | (() => unknown)
-}
-
-/** The field types registered by default. */
-export const builtinFields: FieldType[] = [
-  {
-    name: 'image',
-    // `alt` is authored in the editor (image SEO + accessibility); `width` /
-    // `height` are the intrinsic pixel size of the *original*, captured when the
-    // image is chosen, so blocks can render dimension attributes and avoid
-    // layout shift. `focalX`/`focalY` are a 0..1 focal point (drives
-    // `object-position` / `background-position`); `crop` is a normalized crop
-    // rectangle over the original whose baked-down result is `croppedSrc`
-    // (`croppedWidth`/`croppedHeight` its intrinsic size). Non-destructive: the
-    // original `src` + `crop` stay on the value, so a crop is always re-editable.
-    schema: {
-      type: 'object',
-      format: 'image',
-      properties: {
-        src: 'string',
-        previewSrc: 'string?',
-        alt: 'string?',
-        width: 'number?',
-        height: 'number?',
-        focalX: 'number?',
-        focalY: 'number?',
-        crop: {
-          type: 'object?',
-          properties: { x: 'number', y: 'number', width: 'number', height: 'number' },
-        },
-        croppedSrc: 'string?',
-        croppedWidth: 'number?',
-        croppedHeight: 'number?',
-      },
-    },
-    // Start empty so the editor shows its upload/pick affordance rather than a
-    // placeholder image (and pages render nothing until an image is chosen).
-    default: () => ({ src: '' }),
-  },
-  {
-    name: 'file',
-    schema: { type: 'object', format: 'file', properties: { src: 'string' } },
-    default: () => ({ src: '' }),
-  },
-  {
-    name: 'text',
-    schema: { type: 'string', format: 'text' },
-  },
-  {
-    name: 'color',
-    schema: { type: 'string', format: 'color' },
-  },
-  {
-    name: 'smartLink',
-    schema: {
-      type: 'object',
-      format: 'smartLink',
-      properties: { url: 'string', title: 'string', external: 'boolean', openNewTab: 'boolean' },
-    },
-  },
-  {
-    name: 'multiselect',
-    schema: { type: 'array', format: 'multiselect', items: 'string' },
-  },
-  {
-    name: 'richText',
-    schema: {
-      type: 'array',
-      format: 'richText',
-      items: { type: 'object', properties: { text: 'string', type: 'string?', styles: 'object?' } },
-    },
-    default: () => [{ text: '' }],
-  },
-]
-
-export type RegisterAlias = typeof registerAlias
-
-const fieldDefaults = new Map<string, unknown | (() => unknown)>()
-let registered = false
-
-/**
- * Register field types as compact-json-schema aliases and record their default
- * values. Call once per runtime before unfolding any block/data schema.
- *
- * @param register Override the alias registrar (defaults to compact-json-schema's).
- * @param fields   Field set to register (defaults to {@link builtinFields}).
- */
-export function registerFieldSchemas(
-  register: RegisterAlias = registerAlias,
-  fields: FieldType[] = builtinFields,
-): void {
-  for (const field of fields) {
-    register(field.name as never, field.schema as never)
-    if (field.default !== undefined) fieldDefaults.set(field.name, field.default)
-  }
-  registered = true
-}
-
-/** Resolve the default value for a registered field format, or `undefined`. */
-export function getFieldDefault(format: string): unknown {
-  const value = fieldDefaults.get(format)
-  return typeof value === 'function' ? (value as () => unknown)() : value
-}
-
-/** Whether {@link registerFieldSchemas} has run in this runtime. */
-export function areFieldSchemasRegistered(): boolean {
-  return registered
-}

package/src/generate-page.ts

@@ -1,212 +0,0 @@
-import type { Block } from './types'
-import type { LocalesConfig } from './locale'
-import { passDefaultValue, walkTree, walkSchema, getValueByPath } from './schema'
-
-const HTML_ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }
-
-/** Escape a templated value so it's safe in element text and attribute values. */
-function escapeHtml(value: string): string {
-  return value.replace(/[&<>"]/g, (char) => HTML_ESCAPES[char]!)
-}
-
-/**
- * Substitute `{{ a.b }}` placeholders in an HTML string with data values. Used to
- * template the `<head>` (title, meta, Open Graph, …) from `defineData` values and
- * the current page. Resolved values are HTML-escaped. The triple-brace form
- * `{{{ a.b }}}` serializes the value as raw JSON instead (script-safe, see
- * {@link serializeState}) — for JSON-LD structured data inside a
- * `<script type="application/ld+json">`, where HTML-escaping would corrupt it.
- */
-export function passDataToHTML(html: string, data: any): string {
-  return html.replace(/\{\{\{(.+?)\}\}\}|\{\{(.+?)\}\}/g, (_match, rawExpr, escapedExpr) => {
-    if (rawExpr !== undefined) {
-      const value = getValueByPath(data, rawExpr.trim())
-      return value === undefined ? '' : serializeState(value)
-    }
-    return escapeHtml(String(getValueByPath(data, escapedExpr.trim()) ?? ''))
-  })
-}
-
-export interface PageState {
-  content: any[]
-  data: Record<string, any>
-  page?: {
-    title?: string
-    path?: string
-    meta?: Record<string, unknown>
-    /** Set on paginated variants: which chunk of the page's paginated query this is. */
-    pagination?: { page: number; pageCount?: number }
-    /** The locale this page renders in (multi-language sites). */
-    locale?: string
-    /** Which locales this logical page has a translation for. */
-    locales?: string[]
-  }
-}
-
-/** What `render` may return: bare HTML, or HTML plus the queries it resolved. */
-export type RenderResult = string | { html: string; query?: Record<string, unknown> }
-
-export interface GeneratePageOptions {
-  /** The index.html template. */
-  index: string
-  /** Block metadata keyed by blockId. */
-  blocksMap: Map<string, Block>
-  /** The page to render. */
-  state: PageState
-  /** Declared data entries (with unfolded schemas) for default-filling. */
-  dataEntries: { id: string; props: any }[]
-  /** Site-level data merged under page data. */
-  projectData?: Record<string, any>
-  /** Site identity, exposed to `{{ site.url }}` / `{{ site.name }}` templating. */
-  site?: { url?: string; name?: string }
-  /** The site's locale config — baked into `state.locales` so the runtime can
-   *  prefix internal links for the page's locale. Omitted when i18n is off. */
-  locales?: LocalesConfig
-  baseUrl?: string
-  path?: string
-  /**
-   * Serve build assets from this base URL (a CDN origin like
-   * `https://cdn.example.com`). Root-relative `/assets/…` references in the
-   * HTML are prefixed with it — `/assets/x.js` → `<assetsUrl>/assets/x.js` — so
-   * the built `assets/` folder can live on a CDN. A trailing slash is ignored,
-   * and an already-absolute `https://…/assets/` URL is left untouched. Uploaded
-   * media (`/media/…`) is rewritten by the export's `onFile`, not here.
-   */
-  assetsUrl?: string
-  /**
-   * Extra `<link>` tags for this page's content, injected before `</head>` —
-   * used by the export to preload the block chunks/CSS the page uses (blocks
-   * are code-split out of the client entry).
-   */
-  pageLinks?: (content: any[]) => string[]
-  /**
-   * Render the page state to HTML (provided by the SSR bundle). May also
-   * return the query results resolved during the render — they're baked into
-   * `window.state.query` so the client hydrates them synchronously.
-   */
-  render: (state: any, path: string) => Promise<RenderResult> | RenderResult
-}
-
-/** Render a single page into the index template with serialized state. */
-export async function generatePage(
-  options: GeneratePageOptions,
-): Promise<{ html: string; query: Record<string, unknown> }> {
-  // Fill block-data defaults from each block's schema.
-  walkTree(options.state.content, (block: any) => {
-    const meta = options.blocksMap.get(block.blockId)
-    if (meta) passDefaultValue(block.data, meta.props)
-  })
-
-  // Merge and default the shared data entries.
-  const merged = { ...options.projectData, ...options.state.data }
-  const data = Object.fromEntries(
-    options.dataEntries.map((entry) => [entry.id, passDefaultValue(merged[entry.id] ?? {}, entry.props)]),
-  )
-
-  const state: Record<string, unknown> = {
-    content: options.state.content,
-    data,
-    baseUrl: options.baseUrl,
-    // The page's own path rides along (pagination pathFor, `{{ page.path }}`).
-    page: { path: options.path, ...options.state.page },
-  }
-  // The locale config rides the state so the runtime prefixes internal links
-  // for `page.locale` and language switchers can enumerate translations.
-  if (options.locales) state.locales = options.locales
-
-  const result = await options.render(state, options.path ?? '')
-  const rendered = typeof result === 'string' ? result : result.html
-  const query = (typeof result === 'string' ? undefined : result.query) ?? {}
-  // Bake resolved queries into the hydration state — the client reads them
-  // synchronously, so hydration matches the server markup with no refetch.
-  if (Object.keys(query).length) state.query = query
-
-  // Template against data plus the page identity and site config, so
-  // `{{ page.meta.title }}`, `{{ page.path }}` and `{{ site.url }}` all work.
-  // Uses `state.page` (not `options.state.page`) so `path` is present — the
-  // same shape dev's transformIndexHtml templates against.
-  let index = passDataToHTML(options.index, { ...data, site: options.site, page: state.page })
-
-  // Inject the rendered markup into the #app container. A template without it
-  // would export empty pages — fail loudly instead of silently shipping shells.
-  const appMatch = index.match(/(<div[^>]*\bid="app"[^>]*>)([\s\S]*?)<\/div>/)
-  if (!appMatch) {
-    throw new Error(
-      'index.html has no <div id="app"> container — the rendered page has nowhere to go. ' +
-        'Add <div id="app"></div> to the template body.',
-    )
-  }
-  const start = appMatch.index! + appMatch[1]!.length
-  const end = appMatch.index! + appMatch[0].length - '</div>'.length
-  index = index.slice(0, start) + rendered + index.slice(end)
-
-  const links = options.pageLinks?.(options.state.content) ?? []
-  if (links.length) index = index.replace('</head>', `${links.join('\n')}\n</head>`)
-
-  if (options.assetsUrl) {
-    const base = options.assetsUrl.replace(/\/+$/, '')
-    // Prefix only genuine root-relative refs (right after a quote/paren/equals),
-    // so an already-absolute `https://…/assets/` URL is never double-prefixed.
-    index = index.replace(/(["'(=])\/assets\//g, (_, edge) => `${edge}${base}/assets/`)
-  }
-
-  const stateScript = `<script>window.state=${serializeState(state)}</script>`
-  return { html: index.replace('</body>', `${stateScript}\n</body>`), query }
-}
-
-// Characters that can break out of an inline <script>: `<` (closes the tag via
-// `</script>`, or opens `<script`/`<!--`) and the line separators U+2028 / U+2029
-// (invalid in JS string literals). Built from char codes so the source stays
-// plain ASCII.
-const UNSAFE_IN_SCRIPT = new RegExp(`[${[0x3c, 0x2028, 0x2029].map((c) => '\\u' + c.toString(16).padStart(4, '0')).join('')}]`, 'g')
-
-/**
- * Serialize runtime state for embedding in an inline `<script>`. Plain JSON is
- * unsafe (a `</script>` in the data would close the tag early), so the few
- * dangerous characters are escaped to their `\uXXXX` form — valid JSON/JS that
- * `window.state` and the router's regex read back unchanged.
- */
-export function serializeState(state: unknown): string {
-  return JSON.stringify(state).replace(UNSAFE_IN_SCRIPT, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'))
-}
-
-export interface GenerateProjectOptions extends Omit<GeneratePageOptions, 'state' | 'path'> {
-  pages: Array<{ content: any[]; data: Record<string, any>; path: string; page?: PageState['page'] }>
-  /** Map an asset path to its emitted path (and copy it). */
-  onFile?: (path: string) => string
-}
-
-/** Render every page of a project, yielding the html, path and resolved queries. */
-export async function* generateProject(
-  options: GenerateProjectOptions,
-): AsyncGenerator<{ html: string; path: string; query: Record<string, unknown> }> {
-  for (const page of options.pages) {
-    page.content = page.content ?? []
-    if (options.onFile) collectFiles(page.content, options.blocksMap, options.onFile)
-    const { html, query } = await generatePage({ ...options, state: page, path: page.path })
-    yield { html, path: page.path, query }
-  }
-}
-
-/** Rewrite asset references (image/file/richText) through `onFile`. */
-function collectFiles(content: any[], blocksMap: Map<string, Block>, onFile: (path: string) => string): void {
-  walkTree(content, (block) => {
-    const meta = blocksMap.get(block.blockId)
-    if (!meta) return
-    walkSchema(block.data, meta.props, (value: any, schema: any) => {
-      if (!value) return
-      if (schema.format === 'image' || schema.format === 'file') {
-        if (value.src) value.src = onFile(value.src)
-        if (value.previewSrc) value.previewSrc = onFile(value.previewSrc)
-        if (value.croppedSrc) value.croppedSrc = onFile(value.croppedSrc)
-      }
-      if (schema.format === 'richText' && schema.type === 'array') {
-        for (const row of value) {
-          if (row.image?.src) row.image.src = onFile(row.image.src)
-          if (row.image?.previewSrc) row.image.previewSrc = onFile(row.image.previewSrc)
-          if (row.image?.croppedSrc) row.image.croppedSrc = onFile(row.image.croppedSrc)
-        }
-      }
-    })
-  })
-}

package/src/index.ts

@@ -1,119 +0,0 @@
-export type {
-  Block,
-  ContentBlock,
-  ComposedBlockDefinition,
-  ComposerComponentDefinition,
-  ComposerComponentEntry,
-  ComposerManifest,
-  ComposerClassDefinition,
-  ComposerClassEntry,
-  ComposerClassDef,
-  ComposerElementKind,
-  ComposerBreakpoints,
-  PropBinding,
-  DataEntry,
-  DataScope,
-  PageMeta,
-  State,
-  PageLink,
-  VirtualPage,
-} from './types'
-
-export { normalizeClassManifest } from './composer-manifest'
-
-export {
-  normalizeLocales,
-  isLocale,
-  parseLocalePath,
-  localePath,
-  localeLabel,
-  type LocalesConfig,
-  type LocalesOption,
-} from './locale'
-
-export {
-  resolveComposedTemplate,
-  resolveBindings,
-  templateBlockIds,
-  isBinding,
-} from './compose'
-
-export {
-  type FieldType,
-  type ImageCropConfig,
-  type RegisterAlias,
-  builtinFields,
-  registerFieldSchemas,
-  getFieldDefault,
-  areFieldSchemasRegistered,
-} from './fields'
-
-export {
-  getDefaultValue,
-  passDefaultValue,
-  buildPreviewData,
-  mergePreviewData,
-  walkTree,
-  walkSchema,
-  getValueByPath,
-} from './schema'
-
-export {
-  generatePage,
-  generateProject,
-  passDataToHTML,
-  serializeState,
-  type GeneratePageOptions,
-  type GenerateProjectOptions,
-  type PageState,
-  type RenderResult,
-} from './generate-page'
-
-export {
-  validateLinks,
-  collectInternalLinks,
-  normalizeInternalUrl,
-  type LinkIssue,
-} from './validate-links'
-
-export {
-  pageUrl,
-  paginationVariantPath,
-  applySeoTags,
-  auditPageHtml,
-  buildSitemap,
-  buildRobotsTxt,
-  type SeoTagOptions,
-  type SitemapEntry,
-} from './seo'
-
-export { migrateContent, findUnknownBlocks } from './migrate'
-
-export {
-  mergeTranslation,
-  diffTranslation,
-  mergeValue,
-  diffValue,
-  mergeBlocks,
-  diffBlocks,
-  deepEqual,
-  type TranslationDoc,
-} from './translation'
-
-// The `.page.md` codec is deliberately NOT re-exported here: it pulls in the
-// YAML parser, and this barrel is imported by the client runtime — nothing in
-// a production page needs to parse pages. Server-side callers (dev store,
-// CLI, rich-text codec) import from 'mechanica-shared/page-format'.
-
-export {
-  parseQueryKey,
-  isPaginatedQuery,
-  resolvePagesQuery,
-  resolveQueryKey,
-  type QuerySource,
-  type QueryContext,
-  type PageQueryItem,
-  type PagesQueryArgs,
-  type PaginatedPagesResult,
-} from './query-engine'
-

package/src/locale.ts

@@ -1,88 +0,0 @@
-/**
- * Multi-language (i18n) helpers — pure, DOM-free path math shared by the dev
- * server, the runtime and the static export. A logical page has one canonical
- * path (`/about`); each non-default locale is served under a `/<code>` prefix
- * (`/ru/about`). The default locale is always unprefixed.
- */
-
-/** The site's locale configuration (from the plugin's `locales` option). */
-export interface LocalesConfig {
-  /** The default locale code — served at unprefixed URLs. */
-  default: string
-  /** Every locale the site publishes, the default included. */
-  all: string[]
-  /** Optional human labels for the editor UI, keyed by code (`{ ru: 'Русский' }`). */
-  labels?: Record<string, string>
-}
-
-/** A raw `locales` plugin option: the full config or a bare list of codes. */
-export type LocalesOption = LocalesConfig | string[] | undefined
-
-/**
- * Normalize a raw `locales` option into a config, or `null` when i18n is off:
- * the option is omitted/empty, or it resolves to a single locale (nothing to
- * prefix or translate). The default is forced into `all`; duplicates drop.
- */
-export function normalizeLocales(option: LocalesOption): LocalesConfig | null {
-  if (!option) return null
-  const raw = Array.isArray(option) ? { default: option[0] ?? '', all: option } : option
-  const all = raw.all.filter((code, i) => !!code && raw.all.indexOf(code) === i)
-  const fallbackDefault = raw.default || all[0] || ''
-  if (!fallbackDefault) return null
-  if (!all.includes(fallbackDefault)) all.unshift(fallbackDefault)
-  // A single-locale site needs no prefixing or variants.
-  if (all.length < 2) return null
-  return { default: fallbackDefault, all, labels: (raw as LocalesConfig).labels }
-}
-
-/** Whether `code` is a locale this config knows about. */
-export function isLocale(config: LocalesConfig | null | undefined, code: string): boolean {
-  return !!config && config.all.includes(code)
-}
-
-/**
- * Split a URL path into its locale and logical path. A leading `/<code>`
- * segment naming a non-default locale is stripped; everything else stays as-is
- * under the default locale.
- *
- *   parseLocalePath('/ru/blog', cfg) → { locale: 'ru', path: '/blog' }
- *   parseLocalePath('/blog', cfg)    → { locale: 'en', path: '/blog' }   // en = default
- *   parseLocalePath('/ru', cfg)      → { locale: 'ru', path: '/' }
- */
-export function parseLocalePath(
-  urlPath: string,
-  config: LocalesConfig | null | undefined,
-): { locale: string; path: string } {
-  if (!config) return { locale: '', path: urlPath }
-  const match = urlPath.match(/^\/([^/]+)(\/.*)?$/)
-  const head = match?.[1]
-  if (head && head !== config.default && config.all.includes(head)) {
-    return { locale: head, path: match![2] || '/' }
-  }
-  return { locale: config.default, path: urlPath }
-}
-
-/**
- * Prefix a logical path for a locale. The default locale (or no config, or an
- * unknown code) returns the path unchanged; other locales get a `/<code>`
- * prefix.
- *
- *   localePath('/blog', 'ru', cfg) → '/ru/blog'
- *   localePath('/', 'ru', cfg)     → '/ru'
- *   localePath('/blog', 'en', cfg) → '/blog'   // en = default
- */
-export function localePath(
-  path: string,
-  locale: string | undefined,
-  config: LocalesConfig | null | undefined,
-): string {
-  if (!config || !locale || locale === config.default) return path
-  if (!config.all.includes(locale)) return path
-  const clean = path === '/' ? '' : path
-  return `/${locale}${clean}`
-}
-
-/** The human label for a locale — the config's `labels`, else the code itself. */
-export function localeLabel(config: LocalesConfig | null | undefined, code: string): string {
-  return config?.labels?.[code] ?? code
-}

package/src/migrate.ts

@@ -1,44 +0,0 @@
-import type { Block, ContentBlock } from './types'
-import { walkTree } from './schema'
-
-/**
- * Upgrade placed blocks whose data was written with an older schema version.
- *
- * Each placed block records the schema version it was saved with (`v`, absent
- * = 1). When a block type declares a newer `version`, its `migrate` hook runs
- * with the stored data and the version it came from, then the block is
- * stamped with the current version. Runs on load (dev state, export) so pages
- * never render stale-shaped data; the upgrade persists with the next save.
- *
- * Returns whether anything changed.
- */
-export function migrateContent(content: ContentBlock[], blocksMap: Map<string, Block>): boolean {
-  let changed = false
-  walkTree(content, (block) => {
-    const meta = blocksMap.get(block.blockId)
-    const version = meta?.version
-    if (!version) return
-    const from = block.v ?? 1
-    if (from >= version) return
-    if (meta!.migrate) {
-      const result = meta!.migrate(block.data ?? {}, from)
-      if (result) block.data = result
-    }
-    block.v = version
-    changed = true
-  })
-  return changed
-}
-
-/**
- * Block ids referenced by the content tree that the block registry doesn't
- * know (deleted or renamed block types). These render as nothing — callers
- * should surface them (export warning, editor badge).
- */
-export function findUnknownBlocks(content: ContentBlock[], blocksMap: Map<string, Block>): string[] {
-  const unknown = new Set<string>()
-  walkTree(content, (block) => {
-    if (!blocksMap.has(block.blockId)) unknown.add(block.blockId)
-  })
-  return [...unknown]
-}