@plutocms/docs 0.0.0-stage → 0.16.0

package/shared/utils/blocks/registry.ts

@@ -0,0 +1,295 @@
+// Join the presets, the component layer, the site overrides (`plutoBlocks` in
+// app.config.ts) and the props found in the document into one definition for
+// each component. Pure functions: the caller reads the app config and passes
+// the sources in.
+
+import type {
+  PlutoBlock,
+  PlutoBlockDefinition,
+  PlutoBlockOverride,
+  PlutoBlockPatch,
+  PlutoBlockPropDefinition,
+  PlutoBlocksConfig,
+  PlutoBlockSlotDefinition,
+  PlutoBlockSources,
+  PlutoComponentBlock,
+} from './types'
+import { BLOCK_GROUPS, BLOCK_PRESETS, HIDDEN_PROP_NAMES } from './presets'
+
+// The typed identity helper is in its own file, so a component file that auto-imports it does not load the registry.
+export { definePlutoBlock } from './define'
+
+export interface ResolveOptions {
+  /** The layers: the component layer and the `plutoBlocks` value of the app config. */
+  sources?: PlutoBlockSources
+  /** A block of the doc. Its props and slots fill what the definition does not list. */
+  block?: PlutoComponentBlock
+}
+
+/** A readable name from a component name: `pluto-hero` gives `Pluto hero`, `starCount` gives `Star count`. */
+export function humanizeName(name: string): string {
+  const text = name
+    .replace(/^u-/, '')
+    .replace(
+      /([a-z0-9])([A-Z])/g,
+      (_, before: string, letter: string) => `${before} ${letter.toLowerCase()}`
+    )
+    .replace(/[-_]+/g, ' ')
+    .trim()
+  return text ? text[0]!.toUpperCase() + text.slice(1) : name
+}
+
+/**
+ * The key of a component in the sources: the kebab name that `pascalCase` turns back into the
+ * component name. `PlutoHero` gives `pluto-hero`, and `UPageCTA` gives `u-page-c-t-a`. A name that
+ * is already kebab case stays as it is.
+ */
+export function blockKey(name: string): string {
+  return name.replace(/(?<!^|-)[A-Z]/g, (letter) => `-${letter}`).toLowerCase()
+}
+
+/** `star-count` gives `starCount`. */
+export function camelKey(name: string): string {
+  return name.replace(/-+([a-z0-9])/gi, (_, letter: string) =>
+    letter.toUpperCase()
+  )
+}
+
+/** The key of `map` that means `key`: the same key, else the same name in kebab or camel case. */
+function sameKey(map: object, key: string): string {
+  if (key in map) {
+    return key
+  }
+  const camel = camelKey(key)
+  return Object.keys(map).find((other) => camelKey(other) === camel) ?? key
+}
+
+function automaticDefinition(name: string): PlutoBlockDefinition {
+  return {
+    name,
+    label: humanizeName(name),
+    icon: 'i-lucide-puzzle',
+    group: 'site',
+    slots: { default: { content: 'blocks' } },
+  }
+}
+
+function propFromValue(value: unknown): PlutoBlockPropDefinition {
+  if (typeof value === 'boolean') {
+    return { type: 'boolean', advanced: true }
+  }
+  if (typeof value === 'number') {
+    return { type: 'number', advanced: true }
+  }
+  const text = typeof value === 'string' ? value : ''
+  return {
+    type: typeof value === 'string' && !text.includes('\n') ? 'string' : 'text',
+    advanced: true,
+  }
+}
+
+/** The layer of one block in a config. The key can be the kebab name or any form of it. */
+function layerFor(
+  config: PlutoBlocksConfig | undefined,
+  key: string
+): PlutoBlockOverride | undefined {
+  if (!config) {
+    return undefined
+  }
+  if (key in config) {
+    return config[key]
+  }
+  const other = Object.keys(config).find((name) => blockKey(name) === key)
+  return other === undefined ? undefined : config[other]
+}
+
+/**
+ * Join the entries of one map (props or slots) one by one. An entry of the patch changes the
+ * entry of the base key by key, and `false` removes it. An entry with no base starts from `fill`.
+ */
+function mergeEntries<T extends object>(
+  base: Record<string, T> | undefined,
+  patch: Record<string, Partial<T> | false | undefined> | undefined,
+  fill: Partial<T>
+): Record<string, T> {
+  const out = { ...base }
+  for (const [key, value] of Object.entries(patch ?? {})) {
+    if (value === undefined) {
+      continue
+    }
+    const target = sameKey(out, key)
+    if (value === false) {
+      delete out[target]
+    } else {
+      out[target] = { ...fill, ...out[target], ...value } as T
+    }
+  }
+  return out
+}
+
+/** The same join for two patches: `false` stays in the result, so a layer above can still remove. */
+function mergePatchEntries<T extends object>(
+  base: Record<string, Partial<T> | false | undefined> | undefined,
+  patch: Record<string, Partial<T> | false | undefined> | undefined
+): Record<string, Partial<T> | false | undefined> {
+  const out = { ...base }
+  for (const [key, value] of Object.entries(patch ?? {})) {
+    if (value === undefined) {
+      continue
+    }
+    const target = sameKey(out, key)
+    const current = out[target]
+    out[target] =
+      value === false || current === undefined || current === false
+        ? value
+        : { ...current, ...value }
+  }
+  return out
+}
+
+/**
+ * Put a layer over a definition. The fields of the layer replace the fields of the base. Props and
+ * slots join key by key (shallow). `false` removes a prop or a slot. `false` for the whole block
+ * hides it.
+ */
+function mergeDefinition(
+  base: PlutoBlockDefinition,
+  layer: PlutoBlockOverride | undefined
+): PlutoBlockDefinition {
+  if (layer === false) {
+    return { ...base, hidden: true }
+  }
+  if (typeof layer !== 'object' || layer === null) {
+    return base
+  }
+  return {
+    ...base,
+    ...layer,
+    name: base.name,
+    props: mergeEntries(base.props, layer.props, { type: 'string' }),
+    slots: mergeEntries(base.slots, layer.slots, {}),
+  }
+}
+
+/**
+ * Put one patch over another, for example the in-file macro over the block made from the
+ * component meta. The result is still a patch: `false` for a prop or a slot stays in it.
+ */
+export function mergeBlockPatch(
+  base: PlutoBlockPatch,
+  over: PlutoBlockPatch | false | undefined
+): PlutoBlockPatch {
+  if (over === undefined) {
+    return base
+  }
+  if (over === false) {
+    return { ...base, hidden: true }
+  }
+  const props = mergePatchEntries(base.props, over.props)
+  const slots = mergePatchEntries(base.slots, over.slots)
+  return {
+    ...base,
+    ...over,
+    ...(Object.keys(props).length ? { props } : {}),
+    ...(Object.keys(slots).length ? { slots } : {}),
+  } as PlutoBlockPatch
+}
+
+/** The slot content kind for a slot that no definition lists. */
+function slotFromChildren(children: PlutoBlock[]): PlutoBlockSlotDefinition {
+  const onlyText = children.every((child) => child.kind === 'text')
+  return { content: onlyText ? 'rich' : 'blocks' }
+}
+
+/**
+ * The definition of a component: the preset (or an automatic one), the
+ * component layer over it, the site override over that, and the props and
+ * slots of `options.block` that none of them lists. Found props go to the
+ * Advanced section.
+ *
+ * The name can be kebab case (`pluto-hero`) or the Pascal form that a page
+ * can use (`PlutoHero`). The definition has the kebab name. A prop of the
+ * definition takes the spelling that the block uses: when the page has
+ * `star-count` and the meta has `starCount`, the key is `star-count`, so an
+ * edit changes the prop of the page and adds no second one.
+ */
+export function resolveBlockDefinition(
+  name: string,
+  options: ResolveOptions = {}
+): PlutoBlockDefinition {
+  const key = blockKey(name)
+  const { components, overrides } = options.sources ?? {}
+  const merged = mergeDefinition(
+    mergeDefinition(
+      BLOCK_PRESETS[key] ?? automaticDefinition(key),
+      layerFor(components, key)
+    ),
+    layerFor(overrides, key)
+  )
+  const found = options.block?.kind === 'component' ? options.block : undefined
+  if (!found) {
+    return merged
+  }
+  const props: Record<string, PlutoBlockPropDefinition> = {}
+  for (const [prop, definition] of Object.entries(merged.props ?? {})) {
+    props[sameKey(found.props, prop)] = definition
+  }
+  for (const [prop, value] of Object.entries(found.props)) {
+    if (
+      !(prop in props) &&
+      !(HIDDEN_PROP_NAMES as readonly string[]).includes(prop)
+    ) {
+      props[prop] = propFromValue(value)
+    }
+  }
+  const slots = { ...merged.slots }
+  for (const [slot, children] of Object.entries(found.slots)) {
+    if (!(slot in slots)) {
+      slots[slot] = slotFromChildren(children)
+    }
+  }
+  return { ...merged, props, slots }
+}
+
+/** The text a palette inserts for a component. */
+export function insertTextFor(definition: PlutoBlockDefinition): string {
+  return definition.insert ?? `::${definition.name}\n::`
+}
+
+export interface PaletteGroup {
+  group: string
+  items: PlutoBlockDefinition[]
+}
+
+/**
+ * The blocks of the palette, in groups. The presets come first, then the
+ * components of the component layer (a component shows only when it is in
+ * that layer), then the components that only the site config declares. A
+ * hidden block, or a block set to `false`, is not in the list.
+ */
+export function listPaletteBlocks(
+  sources: PlutoBlockSources = {}
+): PaletteGroup[] {
+  const names = new Set([
+    ...Object.keys(BLOCK_PRESETS),
+    ...Object.keys(sources.components ?? {}).map(blockKey),
+    ...Object.keys(sources.overrides ?? {}).map(blockKey),
+  ])
+  const groups = new Map<string, PlutoBlockDefinition[]>()
+  for (const name of names) {
+    const definition = resolveBlockDefinition(name, { sources })
+    if (definition.hidden) {
+      continue
+    }
+    groups.set(definition.group, [
+      ...(groups.get(definition.group) ?? []),
+      definition,
+    ])
+  }
+  const known = BLOCK_GROUPS as readonly string[]
+  const order = [
+    ...known.filter((group) => groups.has(group)),
+    ...[...groups.keys()].filter((group) => !known.includes(group)),
+  ]
+  return order.map((group) => ({ group, items: groups.get(group)! }))
+}

package/shared/utils/blocks/serialize.ts

@@ -0,0 +1,107 @@
+// Write a block doc back to text. A block with `original` writes its source
+// bytes. The gaps between blocks are always the source text. Only an edited
+// block is built from the model, so one edit changes only the lines of that block.
+
+import type {
+  PlutoBlock,
+  PlutoBlockDoc,
+  PlutoCodeBlock,
+  PlutoComponentBlock,
+} from './types'
+import {
+  completeOrder,
+  isSameProps,
+  renderInlineProps,
+  renderYamlProps,
+} from './mdc-props'
+import { flatChildren } from './tree'
+
+/** Puts the indent before each non-blank line but the first. */
+export function indentLines(text: string, indent: string): string {
+  if (!indent) {
+    return text
+  }
+  return text
+    .split('\n')
+    .map((line, index) => (index > 0 && line !== '' ? indent + line : line))
+    .join('\n')
+}
+
+function renderCode(block: PlutoCodeBlock): string {
+  const char = block.fence[0] ?? '`'
+  let fence = block.fence.length >= 3 ? block.fence : char.repeat(3)
+  // A line of the code that looks like the fence needs a longer fence.
+  for (const line of block.code.split('\n')) {
+    const match = /^\s*([`~]{3,})\s*$/.exec(line)
+    if (match && match[1]![0] === char && match[1]!.length >= fence.length) {
+      fence = char.repeat(match[1]!.length + 1)
+    }
+  }
+  const info = [
+    block.lang,
+    block.filename === undefined ? '' : `[${block.filename}]`,
+    block.meta ?? '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+  const body = block.code === '' ? '' : `\n${block.code}`
+  return indentLines(`${fence}${info}${body}\n${fence}`, block.indent ?? '')
+}
+
+/** The opening line of a component, with its props. Unchanged props give the source text. */
+export function renderOpener(block: PlutoComponentBlock): string {
+  if (isSameProps(block.props, block.propOrder, block.propSource)) {
+    return block.openerText
+  }
+  const order = completeOrder(block.props, block.propOrder)
+  const head = `${':'.repeat(block.colons)}${block.name}`
+  if (block.propsStyle === 'yaml' && block.yamlHead !== undefined) {
+    const entries = renderYamlProps(block.props, order, block.propSource)
+    if (entries.length === 0) {
+      return head
+    }
+    const fenceIndent = block.yamlHead.slice(
+      block.yamlHead.lastIndexOf('\n') + 1
+    )
+    const yamlIndent = block.yamlIndent ?? ''
+    const inner = entries
+      .map((entry) => yamlIndent + indentLines(entry, yamlIndent))
+      .join('\n')
+    return `${head}${block.yamlHead}---\n${inner}\n${fenceIndent}---`
+  }
+  const body = renderInlineProps(block.props, order, block.propSource)
+  return body ? `${head}{${body}}` : head
+}
+
+function renderComponent(block: PlutoComponentBlock): string {
+  const children = flatChildren(block)
+  let out = renderOpener(block)
+  for (const [index, child] of children.entries()) {
+    out += (block.gaps[index] ?? '') + renderBlock(child)
+  }
+  return `${out}${block.gaps[children.length] ?? ''}${':'.repeat(block.colons)}`
+}
+
+/** The text of one block, without the white space before its first line. */
+export function renderBlock(block: PlutoBlock): string {
+  if (block.original) {
+    return block.original.text
+  }
+  switch (block.kind) {
+    case 'text':
+    case 'raw':
+      return indentLines(block.markdown, block.indent ?? '')
+    case 'code':
+      return renderCode(block)
+    case 'component':
+      return renderComponent(block)
+  }
+}
+
+export function serializeBlocks(doc: PlutoBlockDoc): string {
+  let out = doc.gaps[0] ?? ''
+  for (const [index, block] of doc.blocks.entries()) {
+    out += renderBlock(block) + (doc.gaps[index + 1] ?? '')
+  }
+  return out
+}

package/shared/utils/blocks/tree.ts

@@ -0,0 +1,85 @@
+// Helpers to walk the block tree. No Nuxt import.
+
+import type {
+  PlutoBlock,
+  PlutoBlockDoc,
+  PlutoBlockLocation,
+  PlutoComponentBlock,
+} from './types'
+
+/** The children of a component in source order, over all slots. */
+export function flatChildren(component: PlutoComponentBlock): PlutoBlock[] {
+  return Object.values(component.slots).flat()
+}
+
+/** Calls `visit` for each block, parents first. */
+export function walkBlocks(
+  blocks: PlutoBlock[],
+  visit: (block: PlutoBlock, parent?: PlutoComponentBlock) => void,
+  parent?: PlutoComponentBlock
+): void {
+  for (const block of blocks) {
+    visit(block, parent)
+    if (block.kind === 'component') {
+      walkBlocks(flatChildren(block), visit, block)
+    }
+  }
+}
+
+export function findBlock(
+  doc: PlutoBlockDoc,
+  id: string
+): PlutoBlockLocation | undefined {
+  const search = (
+    blocks: PlutoBlock[],
+    parent?: PlutoComponentBlock,
+    slot?: string
+  ): PlutoBlockLocation | undefined => {
+    for (const [index, block] of blocks.entries()) {
+      if (block.id === id) {
+        return { block, parent, slot, index }
+      }
+      if (block.kind === 'component') {
+        for (const [name, children] of Object.entries(block.slots)) {
+          const found = search(children, block, name)
+          if (found) {
+            return found
+          }
+        }
+      }
+    }
+    return undefined
+  }
+  return search(doc.blocks)
+}
+
+/** The ids from the top-level block down to the block. Empty when the id is unknown. */
+export function pathOf(doc: PlutoBlockDoc, id: string): string[] {
+  const search = (
+    blocks: PlutoBlock[],
+    trail: string[]
+  ): string[] | undefined => {
+    for (const block of blocks) {
+      const next = [...trail, block.id]
+      if (block.id === id) {
+        return next
+      }
+      if (block.kind === 'component') {
+        const found = search(flatChildren(block), next)
+        if (found) {
+          return found
+        }
+      }
+    }
+    return undefined
+  }
+  return search(doc.blocks, []) ?? []
+}
+
+let counter = 0
+
+/** A new id for a block that is not from a parse. */
+export function newBlockId(): string {
+  counter++
+  return `n${counter}`
+}

package/shared/utils/blocks/types.ts

@@ -0,0 +1,195 @@
+// Types of the block model. The model has no Nuxt import, so a package can
+// own it later. The truth stays the Markdown string: a block with `original`
+// is written back byte for byte.
+
+/** A part of the source text that a block came from. */
+export interface PlutoSlice {
+  start: number
+  end: number
+  text: string
+}
+
+interface PlutoBlockBase {
+  id: string
+  /** The source text of the block. An edit removes it from the block and its ancestors. */
+  original?: PlutoSlice
+  /** The white space before the first line of the block, inside a component. */
+  indent?: string
+}
+
+export interface PlutoTextBlock extends PlutoBlockBase {
+  kind: 'text'
+  /** Without the indent of the parent component. */
+  markdown: string
+}
+
+export interface PlutoCodeBlock extends PlutoBlockBase {
+  kind: 'code'
+  lang: string
+  filename?: string
+  /** The rest of the info string after the language and the file name. */
+  meta?: string
+  /** The fence characters, for example three backticks. */
+  fence: string
+  /** Without the indent of the parent component. */
+  code: string
+}
+
+export type PlutoPropValue = unknown
+
+export type PlutoPropsStyle = 'inline' | 'yaml'
+
+export interface PlutoComponentBlock extends PlutoBlockBase {
+  kind: 'component'
+  name: string
+  props: Record<string, PlutoPropValue>
+  /** Where the props are written: after the name `{a="b"}` or in a YAML block. */
+  propsStyle: PlutoPropsStyle
+  /** The order of the props in the source. New props go at the end. */
+  propOrder: string[]
+  /**
+   * The source of each prop, for a prop that has not changed. The key is a
+   * prop name. The value is the text of the token, or of the YAML entry.
+   */
+  propSource: Record<string, { value: PlutoPropValue; text: string }>
+  /** The colons of the opening line. */
+  colons: number
+  /** The slots in the order of the source. `default` is the content before the first `#name`. */
+  slots: Record<string, PlutoBlock[]>
+  /**
+   * The text between the children, in source order, over all slots. It has the
+   * `#name` lines of the slots. Its length is the number of children plus one.
+   */
+  gaps: string[]
+  /** For `yaml` style: the text between the opening line and the YAML block. */
+  yamlHead?: string
+  /** The opening line as it was in the source, for the check "did the props change". */
+  openerText: string
+  /** For `yaml` style: the indent of the YAML entries. */
+  yamlIndent?: string
+}
+
+export type PlutoRawReason =
+  'table' | 'html' | 'inline-mdc' | 'footnote' | 'task-list' | 'unknown'
+
+export interface PlutoRawBlock extends PlutoBlockBase {
+  kind: 'raw'
+  markdown: string
+  reason: PlutoRawReason
+}
+
+export type PlutoBlock =
+  PlutoTextBlock | PlutoCodeBlock | PlutoComponentBlock | PlutoRawBlock
+
+export interface PlutoBlockDoc {
+  blocks: PlutoBlock[]
+  /** The original text before, between and after the blocks. Its length is the number of blocks plus one. */
+  gaps: string[]
+}
+
+/** Where a block is in the tree. `parent` is undefined for a top-level block. */
+export interface PlutoBlockLocation {
+  block: PlutoBlock
+  parent?: PlutoComponentBlock
+  slot?: string
+  /** The index in the list of the document, or in the slot. */
+  index: number
+}
+
+// Block definitions: what the editor shows for a component.
+
+export type PlutoBlockPropType =
+  | 'string'
+  | 'text'
+  | 'boolean'
+  | 'number'
+  | 'select'
+  | 'icon'
+  | 'color'
+  | 'link'
+
+export interface PlutoBlockPropOption {
+  value: string
+  /** A plain text or an i18n key. */
+  label?: string
+}
+
+export interface PlutoBlockPropDefinition {
+  type: PlutoBlockPropType
+  /** A plain text or an i18n key. */
+  label?: string
+  description?: string
+  options?: Array<string | PlutoBlockPropOption>
+  /** A prop in the Advanced section of the panel. */
+  advanced?: boolean
+  /**
+   * A slot with the same text, for example the `default` slot of a button and its `label`. The
+   * panel shows one field for both: it edits the slot when the block has text in it (the slot wins
+   * on the site), else the prop. The slot does not show in the Content section.
+   */
+  slot?: string
+  /**
+   * The value the component uses when the prop is missing. The control shows it as the
+   * placeholder (or in the "Default" item of a choice). It never goes into the Markdown.
+   */
+  default?: string | number | boolean
+}
+
+/** The editor for the content of a slot. */
+export type PlutoBlockSlotContent = 'rich' | 'inline' | 'blocks'
+
+export interface PlutoBlockSlotDefinition {
+  label?: string
+  content?: PlutoBlockSlotContent
+  /** For `blocks`: the component names that the slot accepts. */
+  accepts?: string[]
+}
+
+export interface PlutoBlockDefinition {
+  name: string
+  /** A plain text or an i18n key. */
+  label: string
+  /** A plain text or an i18n key. */
+  description?: string
+  icon: string
+  group: string
+  props?: Record<string, PlutoBlockPropDefinition>
+  slots?: Record<string, PlutoBlockSlotDefinition>
+  /** The Markdown that the palette inserts. */
+  insert?: string
+  /** `false` shows a placeholder card instead of the component in the preview. */
+  preview?: boolean
+  /** Not in the palette. The block still shows with its label. */
+  hidden?: boolean
+}
+
+/** A change to one prop: a partial prop definition. A prop with no `type` is a `string`. */
+export type PlutoBlockPropPatch = Partial<PlutoBlockPropDefinition>
+
+/**
+ * A partial block definition: one layer of the sources (the component layer, or the site
+ * override). `Props` is the prop interface of a component, so `definePlutoBlock<Props>()` can
+ * check the keys of `props`. A prop or a slot set to `false` is removed from the layers below.
+ */
+export interface PlutoBlockPatch<
+  Props extends object = Record<string, unknown>,
+> extends Partial<Omit<PlutoBlockDefinition, 'name' | 'props' | 'slots'>> {
+  props?: { [Key in keyof Props & string]?: PlutoBlockPropPatch | false }
+  slots?: Record<string, PlutoBlockSlotDefinition | false>
+}
+
+/** One layer for one block: a partial definition, or `false` to hide the block from the palette. */
+export type PlutoBlockOverride = PlutoBlockPatch | false
+
+/** The blocks of one layer, by component name (kebab case). */
+export type PlutoBlocksConfig = Record<string, PlutoBlockOverride>
+
+/**
+ * The layers that join the preset into a block definition. The component layer comes from the
+ * component files (it is empty until the build step fills it). The overrides are `plutoBlocks`
+ * in `app.config.ts`, and they win.
+ */
+export interface PlutoBlockSources {
+  components?: PlutoBlocksConfig
+  overrides?: PlutoBlocksConfig
+}