@plutocms/docs 0.0.0-stage → 0.15.0

package/shared/utils/blocks/registry.ts

@@ -0,0 +1,163 @@
+// Join the presets, 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 it in.
+
+import type {
+  PlutoBlock,
+  PlutoBlockDefinition,
+  PlutoBlockOverride,
+  PlutoBlockPropDefinition,
+  PlutoBlocksConfig,
+  PlutoBlockSlotDefinition,
+  PlutoComponentBlock,
+} from './types'
+import { BLOCK_GROUPS, BLOCK_PRESETS, HIDDEN_PROP_NAMES } from './presets'
+
+/** The definition of a block that a site declares in `app.config.ts`. It gives type help. */
+export function definePlutoBlock<
+  T extends Partial<Omit<PlutoBlockDefinition, 'name'>>,
+>(definition: T): T {
+  return definition
+}
+
+export interface ResolveOptions {
+  /** The `plutoBlocks` value of the app config. */
+  overrides?: PlutoBlocksConfig
+  /** 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`. */
+export function humanizeName(name: string): string {
+  const text = name.replace(/^u-/, '').replace(/[-_]+/g, ' ').trim()
+  return text ? text[0]!.toUpperCase() + text.slice(1) : name
+}
+
+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,
+  }
+}
+
+function isOverrideObject(
+  override: PlutoBlockOverride | undefined
+): override is Exclude<PlutoBlockOverride, false> {
+  return typeof override === 'object' && override !== null
+}
+
+function mergeDefinition(
+  base: PlutoBlockDefinition,
+  override: PlutoBlockOverride | undefined
+): PlutoBlockDefinition {
+  if (override === false) {
+    return { ...base, hidden: true }
+  }
+  if (!isOverrideObject(override)) {
+    return base
+  }
+  return {
+    ...base,
+    ...override,
+    name: base.name,
+    props: { ...base.props, ...override.props },
+    slots: { ...base.slots, ...override.slots },
+  }
+}
+
+/** 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 site
+ * override over it, and the props and slots of `options.block` that neither
+ * lists. Found props go to the Advanced section.
+ */
+export function resolveBlockDefinition(
+  name: string,
+  options: ResolveOptions = {}
+): PlutoBlockDefinition {
+  const base = BLOCK_PRESETS[name] ?? automaticDefinition(name)
+  const merged = mergeDefinition(base, options.overrides?.[name])
+  const found = options.block?.kind === 'component' ? options.block : undefined
+  if (!found) {
+    return merged
+  }
+  const props = { ...merged.props }
+  for (const [key, value] of Object.entries(found.props)) {
+    if (
+      !(key in props) &&
+      !(HIDDEN_PROP_NAMES as readonly string[]).includes(key)
+    ) {
+      props[key] = propFromValue(value)
+    }
+  }
+  const slots = { ...merged.slots }
+  for (const [key, children] of Object.entries(found.slots)) {
+    if (!(key in slots)) {
+      slots[key] = 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 that only the site config declares. A hidden block, or a block set
+ * to `false`, is not in the list.
+ */
+export function listPaletteBlocks(
+  overrides: PlutoBlocksConfig = {}
+): PaletteGroup[] {
+  const names = [
+    ...Object.keys(BLOCK_PRESETS),
+    ...Object.keys(overrides).filter((name) => !(name in BLOCK_PRESETS)),
+  ]
+  const groups = new Map<string, PlutoBlockDefinition[]>()
+  for (const name of names) {
+    const definition = resolveBlockDefinition(name, { overrides })
+    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,165 @@
+// 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 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 site override: a partial definition, or `false` to hide the block from the palette. */
+export type PlutoBlockOverride =
+  Partial<Omit<PlutoBlockDefinition, 'name'>> | false
+
+export type PlutoBlocksConfig = Record<string, PlutoBlockOverride>

package/shared/utils/content-route.ts

@@ -0,0 +1,40 @@
+const NUMBER_PREFIX = /^\d+\./
+
+/**
+ * The public route of a Nuxt Content page, from its content id. Nuxt Content
+ * drops the number prefixes of the folders and files, and a final `index`
+ * segment. For example `1.getting-started/2.installation` gives
+ * `/getting-started/installation`, and `index` gives `/`. `prefix` is added in
+ * front of the path (for example `/docs`).
+ */
+export function contentRoutePath(id: string, prefix = ''): string {
+  const segments = String(id)
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(NUMBER_PREFIX, ''))
+
+  if (segments.at(-1) === 'index') {
+    segments.pop()
+  }
+
+  const base = prefix.split('/').filter(Boolean)
+  const path = [...base, ...segments].join('/')
+  return `/${path}`
+}
+
+/**
+ * The admin form of a content item: `/admin/content/<type>/<id>`. Each segment
+ * of the id is URL-encoded, and the slashes stay (like `contentIdPath` in core).
+ */
+export function contentEditPath(type: string, id: string): string {
+  const path = String(id)
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')
+  return `/admin/content/${encodeURIComponent(type)}/${path}`
+}
+
+/** The admin form that creates an item of a type: `/admin/content/<type>/new`. */
+export function contentNewPath(type: string): string {
+  return `/admin/content/${encodeURIComponent(type)}/new`
+}