mechanica-shared 2.0.0-alpha.0

package/src/schema.ts

@@ -0,0 +1,137 @@
+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/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Core data types shared between the plugin runtime, the editor, and the
+ * (future) render service. This module is intentionally DOM- and
+ * framework-free so the render side can import it cleanly.
+ */
+
+/** Scope at which a {@link DataEntry} lives. */
+export type DataScope = 'site' | 'folder' | 'page'
+
+/** Metadata about the current page, exposed via `usePageData`. */
+export interface PageMeta {
+  title?: string
+  path?: string
+  meta?: Record<string, unknown>
+  /**
+   * Set on paginated variants of a page (`/blog/2`, …): which chunk of its
+   * paginated query this URL shows. Page 1 is the base path and carries none.
+   */
+  pagination?: { page: number; pageCount?: number }
+}
+
+/**
+ * Editor-facing metadata describing a *block type* — its schema and palette
+ * presentation, not its placed content. Produced by the block compiler from a
+ * `defineBlock(...)` descriptor.
+ */
+export interface Block {
+  id: string
+  name: string
+  /** Palette grouping (was `group` in v1). */
+  category?: string
+  /** Icon key shown in the block palette. */
+  icon?: string
+  description?: string
+  /** Sort order within a category. */
+  order?: number
+  /** Hidden from the palette. */
+  hidden?: boolean
+  /** Available only in dev, stripped from production output. */
+  devOnly?: boolean
+  /**
+   * Restrict the block to pages under these folders (folder paths relative to
+   * `pages/`, e.g. `'docs'`; nested folders match by prefix). Omitted = offered
+   * everywhere. Placed blocks always keep rendering — this only filters what
+   * the palette offers.
+   */
+  folders?: string[]
+  /**
+   * Schema version of this block (defaults to 1). Bump it together with a
+   * `migrate` function whenever a saved page's data needs reshaping (renamed
+   * prop, changed type); placed blocks record the version they were written
+   * with and migrate on load.
+   */
+  version?: number
+  /**
+   * Upgrade a placed block's data from an older schema version. Receives the
+   * stored data and the version it was written with; mutate it in place or
+   * return the replacement. Must handle every `from < version`.
+   */
+  migrate?: (data: Record<string, unknown>, from: number) => Record<string, unknown> | undefined | void
+  /**
+   * Example prop values used when the block renders outside a page — the
+   * palette hover preview and the `/@mechanica/preview` route (`mechanica shot`).
+   * Merged over schema defaults, so it only needs the props that matter visually.
+   * A `$slots` key fills the block's slots with child blocks (see
+   * `PreviewSlotEntry` in `mechanica`); unfilled slots preview as placeholders.
+   */
+  previewData?: Record<string, unknown>
+  /** compact-json-schema describing the editable props. */
+  props?: Record<string, unknown>
+  /** Slot name → slot metadata (currently `true`). */
+  slots?: Record<string, unknown>
+}
+
+/** A block placed in a page's content tree. */
+export interface ContentBlock {
+  id: string
+  blockId: string
+  data: Record<string, unknown>
+  /** Schema version the data was written with (absent = 1); see `Block.version`. */
+  v?: number
+  /** Either a single default-slot list or a map of named-slot lists. */
+  children?: ContentBlock[] | Record<string, ContentBlock[]>
+}
+
+/** A shared data entry declared with `defineData`. */
+export interface DataEntry {
+  id: string
+  title?: string
+  /** compact-json-schema describing the data shape. */
+  props?: Record<string, unknown>
+}
+
+/**
+ * The runtime state serialized onto the page (`window.state`) and read back by
+ * the runtime to hydrate.
+ */
+export interface State {
+  content: ContentBlock[]
+  /** Effective data: site < folder < page merged, with schema defaults filled. */
+  data: Record<string, unknown>
+  query?: Record<string, unknown>
+  /**
+   * Scope buckets for the editor, so it can edit each level and tell which
+   * entries a page overrides. Only injected in dev (the runtime renders `data`).
+   */
+  siteData?: Record<string, unknown>
+  folderData?: Record<string, unknown>
+  pageData?: Record<string, unknown>
+  /** The folder this page lives in (null at the root), so the editor can offer folder scope. */
+  folder?: string | null
+  /** Base URL the page is served under (for routing/link resolution). */
+  baseUrl?: string
+  /** Current page metadata. */
+  page?: PageMeta
+}
+
+/** A link target produced by the `smartLink` field type. */
+export interface PageLink {
+  id: string
+  url?: string
+  query?: string
+  title: string
+  external?: boolean
+  openNewTab?: boolean
+}

package/src/validate-links.ts

@@ -0,0 +1,56 @@
+import type { Block } from './types'
+import { walkTree, walkSchema } from './schema'
+
+/** A link on a page pointing at an internal path no page is exported for. */
+export interface LinkIssue {
+  /** The page the broken link lives on. */
+  page: string
+  /** The internal URL with no matching page. */
+  url: string
+}
+
+/** Normalize an internal URL for page-path comparison (drop query/hash/trailing slash). */
+export function normalizeInternalUrl(url: string): string {
+  const bare = url.split(/[?#]/)[0]!
+  const trimmed = bare.replace(/\/+$/, '')
+  return trimmed === '' ? '/' : trimmed
+}
+
+/**
+ * Collect the internal link targets on a page: every `smartLink`-formatted
+ * field whose URL is site-relative (starts with `/`) and not marked external.
+ */
+export function collectInternalLinks(content: unknown[], blocksMap: Map<string, Block>): string[] {
+  const found: string[] = []
+  walkTree(content as never, (block: any) => {
+    const meta = blocksMap.get(block.blockId)
+    if (!meta) return
+    walkSchema(block.data, meta.props, (value: any, schema: any) => {
+      if (schema?.format !== 'smartLink' || value == null) return
+      const url = typeof value === 'string' ? value : value.url
+      const external = typeof value === 'object' && value.external === true
+      if (typeof url === 'string' && url.startsWith('/') && !external) found.push(url)
+    })
+  })
+  return found
+}
+
+/**
+ * Cross-check every page's internal `smartLink` targets against the set of
+ * page paths that actually exist. Returns the dead links (empty = all good).
+ * Meant for export/deploy time — a warning, not a hard failure, since a target
+ * may be intentionally served by something else (redirects, external hosting).
+ */
+export function validateLinks(
+  pages: Array<{ path: string; content?: unknown[] }>,
+  blocksMap: Map<string, Block>,
+): LinkIssue[] {
+  const known = new Set(pages.map((page) => normalizeInternalUrl(page.path)))
+  const issues: LinkIssue[] = []
+  for (const page of pages) {
+    for (const url of collectInternalLinks(page.content ?? [], blocksMap)) {
+      if (!known.has(normalizeInternalUrl(url))) issues.push({ page: page.path, url })
+    }
+  }
+  return issues
+}