mechanica-shared 2.0.0-alpha.11 → 2.0.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica-shared",
-  "version": "2.0.0-alpha.11",
+  "version": "2.0.0-alpha.13",
   "description": "DOM-free types, schema helpers and page-generation core shared across Mechanica",
   "license": "MIT",
   "repository": {
@@ -13,23 +13,19 @@
     "tag": "next"
   },
   "files": [
-    "src",
     "dist"
   ],
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./page-format": {
       "types": "./dist/types/page-format.d.ts",
-      "bun": "./src/page-format.ts",
       "import": "./dist/page-format.js"
     },
     "./block-format": {
       "types": "./dist/types/block-format.d.ts",
-      "bun": "./src/block-format.ts",
       "import": "./dist/block-format.js"
     }
   },

package/src/block-format.ts

@@ -1,105 +0,0 @@
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
-import type { ComposedBlockDefinition, ContentBlock } from './types'
-
-/**
- * Codec for the composed-block file format (`.mech/blocks/<id>.block.yml`) — a
- * single YAML document holding a {@link ComposedBlockDefinition}. Kept a
- * separate entry point (`mechanica-shared/block-format`), deliberately NOT
- * re-exported from the barrel: it pulls in the YAML parser, and the barrel is
- * imported by the client runtime, which never parses these files (only the dev
- * store, the plugin's collect step, and the CLI do). Mirrors the `page-format`
- * rule. See PLAN.md § 3.
- */
-
-/** Thrown by {@link parseComposedBlock} with a human-readable reason. */
-export class ComposedBlockParseError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'ComposedBlockParseError'
-    Object.setPrototypeOf(this, ComposedBlockParseError.prototype)
-  }
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** Validate the minimal shape of a content node (recurses into children). */
-function assertContentBlock(node: unknown, where: string): asserts node is ContentBlock {
-  if (!isPlainObject(node)) throw new ComposedBlockParseError(`${where}: expected a mapping`)
-  if (typeof node.blockId !== 'string' || node.blockId === '') {
-    throw new ComposedBlockParseError(`${where}: missing "blockId"`)
-  }
-  if (node.data !== undefined && !isPlainObject(node.data)) {
-    throw new ComposedBlockParseError(`${where}: "data" must be a mapping`)
-  }
-  const children = node.children
-  if (children === undefined) return
-  if (Array.isArray(children)) {
-    children.forEach((child, i) => assertContentBlock(child, `${where} › child ${i}`))
-  } else if (isPlainObject(children)) {
-    for (const [slot, list] of Object.entries(children)) {
-      if (!Array.isArray(list)) throw new ComposedBlockParseError(`${where}: slot "${slot}" must be a list`)
-      list.forEach((child, i) => assertContentBlock(child, `${where} › ${slot}[${i}]`))
-    }
-  } else {
-    throw new ComposedBlockParseError(`${where}: "children" must be a list or a slot mapping`)
-  }
-}
-
-/**
- * Parse a `.block.yml` document into a {@link ComposedBlockDefinition}.
- *
- * @param fallbackId Used as the id when the document omits one — the store and
- *                   plugin pass the filename base, so a hand-authored file may
- *                   omit `id` and be identified by its filename.
- */
-export function parseComposedBlock(text: string, fallbackId?: string): ComposedBlockDefinition {
-  let doc: unknown
-  try {
-    doc = parseYaml(text)
-  } catch (error) {
-    throw new ComposedBlockParseError(`invalid YAML: ${error instanceof Error ? error.message : error}`)
-  }
-  if (doc == null) doc = {}
-  if (!isPlainObject(doc)) throw new ComposedBlockParseError('expected a top-level mapping')
-
-  const id = typeof doc.id === 'string' && doc.id !== '' ? doc.id : fallbackId
-  if (!id) throw new ComposedBlockParseError('missing "id"')
-  if (typeof doc.name !== 'string' || doc.name === '') throw new ComposedBlockParseError('missing "name"')
-
-  const template = doc.template ?? []
-  if (!Array.isArray(template)) throw new ComposedBlockParseError('"template" must be a list')
-  template.forEach((node, i) => assertContentBlock(node, `template[${i}]`))
-
-  if (doc.props !== undefined && !isPlainObject(doc.props)) {
-    throw new ComposedBlockParseError('"props" must be a mapping')
-  }
-  if (doc.previewData !== undefined && !isPlainObject(doc.previewData)) {
-    throw new ComposedBlockParseError('"previewData" must be a mapping')
-  }
-
-  const def: ComposedBlockDefinition = { id, name: doc.name, template: template as ContentBlock[] }
-  if (typeof doc.icon === 'string') def.icon = doc.icon
-  if (typeof doc.category === 'string') def.category = doc.category
-  if (doc.hidden === true) def.hidden = true
-  if (doc.standalone === true) def.standalone = true
-  if (isPlainObject(doc.props)) def.props = doc.props
-  if (isPlainObject(doc.previewData)) def.previewData = doc.previewData
-  return def
-}
-
-/** Serialize a {@link ComposedBlockDefinition} to a `.block.yml` document. */
-export function serializeComposedBlock(def: ComposedBlockDefinition): string {
-  // Build an ordered object so the file reads header-first, tree-last.
-  const ordered: Record<string, unknown> = { id: def.id, name: def.name }
-  if (def.icon) ordered.icon = def.icon
-  if (def.category) ordered.category = def.category
-  // Only emit `hidden`/`standalone` when true — typical blocks stay clean.
-  if (def.hidden) ordered.hidden = true
-  if (def.standalone) ordered.standalone = true
-  if (def.props && Object.keys(def.props).length) ordered.props = def.props
-  if (def.previewData && Object.keys(def.previewData).length) ordered.previewData = def.previewData
-  ordered.template = def.template ?? []
-  return stringifyYaml(ordered, { lineWidth: 0 })
-}

package/src/compose.ts

@@ -1,155 +0,0 @@
-import type { ComposedBlockDefinition, ContentBlock, PropBinding } from './types'
-
-/**
- * Expansion of composed blocks into a concrete content tree. DOM- and
- * framework-free so the render side (client, SSR, export) shares one
- * implementation. See PLAN.md § 2.3 / § 4.4.
- */
-
-/** Reserved data keys the composer engine consumes (never passed as props). */
-const IF_KEY = '$if'
-const EACH_KEY = '$each'
-
-/** Whether a value is a prop binding (`{ $bind: 'name' }`). */
-export function isBinding(value: unknown): value is PropBinding {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    typeof (value as { $bind?: unknown }).$bind === 'string'
-  )
-}
-
-/**
- * Look up a binding name in a prop scope. Supports dot paths (`$item.title`,
- * `cta.url`) so a repeated subtree can bind fields of the current `$item` and a
- * binding can reach into an object prop without exposing each leaf separately.
- */
-export function lookupBinding(name: string, props: Record<string, unknown>): unknown {
-  if (name in props) return props[name]
-  if (!name.includes('.')) return undefined
-  let value: unknown = props
-  for (const part of name.split('.')) {
-    if (value === null || typeof value !== 'object') return undefined
-    value = (value as Record<string, unknown>)[part]
-  }
-  return value
-}
-
-/**
- * Deep-resolve a data value: substitute every `{ $bind: name }` with the named
- * prop, recursing through arrays and plain objects (so a bound value nested in
- * e.g. a `smartLink` object resolves too). Non-binding scalars pass through;
- * everything is cloned, so the returned value never aliases the template.
- */
-export function resolveBindings(value: unknown, props: Record<string, unknown>): unknown {
-  if (isBinding(value)) return lookupBinding(value.$bind, props)
-  if (Array.isArray(value)) return value.map((item) => resolveBindings(item, props))
-  if (value !== null && typeof value === 'object') {
-    const out: Record<string, unknown> = {}
-    for (const [key, item] of Object.entries(value)) out[key] = resolveBindings(item, props)
-    return out
-  }
-  return value
-}
-
-/** Resolve one template node, or `null` when a falsy `$if` binding drops it. */
-function resolveNode(
-  node: ContentBlock,
-  props: Record<string, unknown>,
-  prefix: string,
-  index: number,
-  idSuffix = '',
-): ContentBlock | null {
-  const raw = node.data ?? {}
-  // `$if` gates the node's presence — resolve it before anything else so a
-  // hidden element costs nothing downstream.
-  if (IF_KEY in raw && !resolveBindings(raw[IF_KEY], props)) return null
-
-  const data: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(raw)) {
-    if (key === IF_KEY || key === EACH_KEY) continue
-    data[key] = resolveBindings(value, props)
-  }
-
-  // Namespace ids under the placed instance so two placements of the same
-  // composed block produce distinct, stable vnode keys.
-  const id = `${prefix}:${node.id ?? index}${idSuffix}`
-  const resolved: ContentBlock = { id, blockId: node.blockId, data }
-  if (node.v != null) resolved.v = node.v
-  if (node.children) resolved.children = resolveChildren(node.children, props, id)
-  return resolved
-}
-
-function resolveList(list: ContentBlock[], props: Record<string, unknown>, prefix: string): ContentBlock[] {
-  const out: ContentBlock[] = []
-  list.forEach((child, index) => {
-    const each = child.data?.[EACH_KEY]
-    if (typeof each === 'string') {
-      // `$each: 'items'` repeats this node (and its subtree) once per array
-      // item. Inside the subtree, `$bind: '$item'` / `'$item.field'` resolve
-      // from the current item and `$bind: '$index'` from its position; other
-      // names still resolve from the block's props. A missing/non-array prop
-      // renders nothing — an empty list is empty, not broken.
-      const items = lookupBinding(each, props)
-      if (!Array.isArray(items)) return
-      items.forEach((item, i) => {
-        const scope = { ...props, $item: item, $index: i }
-        const resolved = resolveNode(child, scope, prefix, index, `@${i}`)
-        if (resolved) out.push(resolved)
-      })
-      return
-    }
-    const resolved = resolveNode(child, props, prefix, index)
-    if (resolved) out.push(resolved)
-  })
-  return out
-}
-
-function resolveChildren(
-  children: NonNullable<ContentBlock['children']>,
-  props: Record<string, unknown>,
-  prefix: string,
-): ContentBlock['children'] {
-  if (Array.isArray(children)) return resolveList(children, props, `${prefix}/d`)
-  const map: Record<string, ContentBlock[]> = {}
-  for (const [name, list] of Object.entries(children)) {
-    map[name] = resolveList(list, props, `${prefix}/${name}`)
-  }
-  return map
-}
-
-/**
- * Expand a composed block's template into a concrete content tree: substitute
- * `$bind` values from `props`, repeat `$each` nodes per array item, drop
- * `$if`-hidden nodes, and namespace every node id under `instanceId` (the
- * placed block's id — stable across renders). The result is rendered by the
- * normal block-render pipeline.
- */
-export function resolveComposedTemplate(
-  def: ComposedBlockDefinition,
-  props: Record<string, unknown> | undefined,
-  instanceId: string,
-): ContentBlock[] {
-  return resolveList(def.template ?? [], props ?? {}, instanceId)
-}
-
-/**
- * Block ids referenced anywhere in a composed template (recursing into slot
- * children). Used to expand a page's used-block set so the underlying compiled
- * blocks' chunks load before a composed block mounts. Element blocks (`mech:*`)
- * ship with the runtime; they need no loader but are harmless to include.
- */
-export function templateBlockIds(def: ComposedBlockDefinition): Set<string> {
-  const ids = new Set<string>()
-  const walk = (list: ContentBlock[]): void => {
-    for (const node of list) {
-      ids.add(node.blockId)
-      if (!node.children) continue
-      if (Array.isArray(node.children)) walk(node.children)
-      else for (const inner of Object.values(node.children)) walk(inner)
-    }
-  }
-  walk(def.template ?? [])
-  return ids
-}

package/src/composer-manifest.ts

@@ -1,45 +0,0 @@
-import type {
-  ComposerClassDef,
-  ComposerClassEntry,
-  ComposerElementKind,
-} from './types'
-
-/**
- * Normalize the Block Composer manifest's `classes` record into the flat list
- * the composer consumes — unfolding the string / array shorthands and defaulting
- * each title to its class name. Pure and DOM-free (the barrel is client-safe);
- * called from the generated `virtual:mechanica/components` module at runtime.
- * See COMPOSER-MANIFEST.md § 2.
- *
- * Shorthands:
- *  - `'text'`               → `{ on: ['text'] }`
- *  - `['frame', 'image']`   → `{ on: ['frame', 'image'] }`
- *  - `{ title?, on, group? }` → as written (only the full form carries a group)
- */
-export function normalizeClassManifest(
-  classes: Record<string, ComposerClassEntry> | undefined,
-): ComposerClassDef[] {
-  if (!classes) return []
-  const out: ComposerClassDef[] = []
-  for (const cls in classes) {
-    const entry = classes[cls]
-    if (entry == null) continue
-    const kinds = classKinds(entry)
-    if (!kinds.length) continue
-    const full = typeof entry === 'object' && !Array.isArray(entry) ? entry : null
-    const def: ComposerClassDef = { cls, title: full?.title || cls, kinds }
-    if (full?.group) def.group = full.group
-    out.push(def)
-  }
-  return out
-}
-
-const KINDS: readonly ComposerElementKind[] = ['frame', 'text', 'image']
-const isKind = (v: unknown): v is ComposerElementKind => KINDS.includes(v as ComposerElementKind)
-
-/** The element kinds a `classes` entry applies to (any shorthand), deduped. */
-function classKinds(entry: ComposerClassEntry): ComposerElementKind[] {
-  const raw = isKind(entry) ? [entry] : Array.isArray(entry) ? entry : entry.on
-  const list = Array.isArray(raw) ? raw : [raw]
-  return [...new Set(list.filter(isKind))]
-}

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
-}