@plutocms/docs 0.0.0-stage → 0.16.0

package/shared/utils/blocks/component-meta.ts

@@ -0,0 +1,285 @@
+// Make a block definition from the meta of a Vue component and the optional
+// `definePlutoBlock({...})` call in its file. Pure: the build step (a later
+// change) parses the files with `nuxt-component-meta` and passes the result in.
+// The result is the "component layer" of one component. Opt-in: the build step
+// calls this only for a component that has the macro.
+
+import type {
+  PlutoBlockPatch,
+  PlutoBlockPropDefinition,
+  PlutoBlockPropPatch,
+  PlutoBlockSlotDefinition,
+} from './types'
+import { BLOCK_COLORS, BLOCK_PRESETS } from './presets'
+import { blockKey, mergeBlockPatch } from './registry'
+
+// The parts of the output of `getComponentMeta` that this file reads. The real output has more.
+export interface PlutoMetaSchema {
+  kind?: string
+  type?: string
+  /** For `enum`: the members as text, by index. For `object`: the properties by name. */
+  schema?: Record<string, unknown> | string
+}
+
+export interface PlutoMetaProp {
+  name: string
+  /** The type as text, for example `"slow" | "fast" | undefined`. */
+  type: string
+  schema?: PlutoMetaSchema | string
+  /** The default as source text: `300`, `"normal"`, `false`. */
+  default?: string
+  /** The JSDoc text of the prop. */
+  description?: string
+  required?: boolean
+}
+
+export interface PlutoMetaSlot {
+  name: string
+  type?: string
+  schema?: PlutoMetaSchema | string
+  description?: string
+}
+
+export interface PlutoComponentMeta {
+  props?: PlutoMetaProp[]
+  slots?: PlutoMetaSlot[]
+}
+
+/** The block key of a component: `PlutoHero` gives `pluto-hero`, `UPageCTA` gives `u-page-c-t-a`. */
+export function componentBlockName(pascalName: string): string {
+  return blockKey(pascalName)
+}
+
+// --- Type to widget ---------------------------------------------------------------
+
+/** Split a union at its top-level bars, so a bar inside quotes or brackets stays. */
+function splitUnion(type: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let quote = ''
+  let current = ''
+  for (const char of type) {
+    if (quote) {
+      if (char === quote) {
+        quote = ''
+      }
+    } else if (char === '"' || char === "'" || char === '`') {
+      quote = char
+    } else if ('{[(<'.includes(char)) {
+      depth++
+    } else if ('}])>'.includes(char)) {
+      depth--
+    } else if (char === '|' && depth === 0) {
+      parts.push(current.trim())
+      current = ''
+      continue
+    }
+    current += char
+  }
+  parts.push(current.trim())
+  return parts.filter(Boolean)
+}
+
+/** The members of the type without `undefined` and `null`. */
+function typeMembers(prop: PlutoMetaProp): string[] {
+  const schema = prop.schema
+  const members =
+    typeof schema === 'object' &&
+    schema.kind === 'enum' &&
+    typeof schema.schema === 'object'
+      ? Object.values(schema.schema).map(String)
+      : splitUnion(prop.type)
+  return members.filter((member) => member !== 'undefined' && member !== 'null')
+}
+
+const STRING_LITERAL = /^(["'`])(.*)\1$/
+
+function stringLiteral(member: string): string | undefined {
+  return STRING_LITERAL.exec(member)?.[2]
+}
+
+function isIconName(name: string): boolean {
+  return name === 'icon' || name.endsWith('Icon')
+}
+
+/** The widget for a prop, or `undefined` when no widget fits. */
+function widgetFor(
+  name: string,
+  members: string[]
+): Pick<PlutoBlockPropDefinition, 'type' | 'options'> | undefined {
+  if (members.length === 0) {
+    return undefined
+  }
+  const literals = members.map(stringLiteral)
+  if (literals.every((value) => value !== undefined)) {
+    const options = (literals as string[]).map((value) => ({ value }))
+    return (literals as string[]).every((value) => BLOCK_COLORS.includes(value))
+      ? { type: 'color', options }
+      : { type: 'select', options }
+  }
+  const kinds = new Set(
+    members.map((member) => stringLiteral(member) ?? member)
+  )
+  const isBoolean = members.every((member) =>
+    ['boolean', 'true', 'false'].includes(member)
+  )
+  if (isBoolean) {
+    return { type: 'boolean' }
+  }
+  if (members.length === 1 && members[0] === 'number') {
+    return { type: 'number' }
+  }
+  const textLike = members.every(
+    (member) =>
+      stringLiteral(member) !== undefined ||
+      member === 'string' ||
+      member === 'number'
+  )
+  if (textLike && members.includes('string')) {
+    return {
+      type: isIconName(name) ? 'icon' : linkName(name) ? 'link' : 'string',
+    }
+  }
+  if (
+    linkName(name) &&
+    (kinds.has('string') || kinds.has('RouteLocationRaw'))
+  ) {
+    return { type: 'link' }
+  }
+  return undefined
+}
+
+function linkName(name: string): boolean {
+  return name === 'to' || name === 'href'
+}
+
+/** A simple default from source text: a number, a boolean or a string. Anything else gives `undefined`. */
+export function parseDefault(
+  source: string | undefined
+): string | number | boolean | undefined {
+  if (source === undefined) {
+    return undefined
+  }
+  const text = source.trim()
+  if (text === 'true') {
+    return true
+  }
+  if (text === 'false') {
+    return false
+  }
+  if (/^-?\d+(?:\.\d+)?$/.test(text)) {
+    return Number(text)
+  }
+  const literal = STRING_LITERAL.exec(text)
+  return literal && !literal[2]!.includes(literal[1]!) ? literal[2] : undefined
+}
+
+// --- Shared labels ----------------------------------------------------------------
+
+function sharedKeys(
+  pick: (block: (typeof BLOCK_PRESETS)[string]) => Array<string | undefined>,
+  prefix: string
+): Set<string> {
+  const names = new Set<string>()
+  for (const preset of Object.values(BLOCK_PRESETS)) {
+    for (const label of pick(preset)) {
+      if (label?.startsWith(prefix)) {
+        names.add(label.slice(prefix.length))
+      }
+    }
+  }
+  return names
+}
+
+const PROP_PREFIX = 'docs.blocks.props.'
+const SLOT_PREFIX = 'docs.blocks.slots.'
+let sharedProps: Set<string> | undefined
+let sharedSlots: Set<string> | undefined
+
+/** The shared label key of a prop (`icon`, `to`, `title`...) when the presets have one. */
+function propLabelKey(name: string): string | undefined {
+  sharedProps ??= sharedKeys(
+    (preset) => Object.values(preset.props ?? {}).map((prop) => prop.label),
+    PROP_PREFIX
+  )
+  return sharedProps.has(name) ? `${PROP_PREFIX}${name}` : undefined
+}
+
+function slotLabelKey(name: string): string | undefined {
+  sharedSlots ??= sharedKeys(
+    (preset) => Object.values(preset.slots ?? {}).map((slot) => slot.label),
+    SLOT_PREFIX
+  )
+  return sharedSlots.has(name) ? `${SLOT_PREFIX}${name}` : undefined
+}
+
+// --- The block --------------------------------------------------------------------
+
+function propFromMeta(prop: PlutoMetaProp): PlutoBlockPropPatch | undefined {
+  const widget = widgetFor(prop.name, typeMembers(prop))
+  if (!widget) {
+    return undefined
+  }
+  const label = propLabelKey(prop.name)
+  const fallback = parseDefault(prop.default)
+  return {
+    ...widget,
+    ...(label ? { label } : {}),
+    ...(prop.description ? { description: prop.description.trim() } : {}),
+    ...(fallback !== undefined ? { default: fallback } : {}),
+  }
+}
+
+/** `mdc-unwrap` on a `<slot>` shows as the binding `mdcUnwrap` in the meta. */
+function hasUnwrap(slot: PlutoMetaSlot): boolean {
+  const schema = slot.schema
+  return (
+    (typeof schema === 'object' &&
+      typeof schema.schema === 'object' &&
+      'mdcUnwrap' in schema.schema) ||
+    /\bmdcUnwrap\b/.test(slot.type ?? '')
+  )
+}
+
+function slotFromMeta(slot: PlutoMetaSlot): PlutoBlockSlotDefinition {
+  const label = slotLabelKey(slot.name)
+  return {
+    ...(label ? { label } : {}),
+    ...(hasUnwrap(slot) ? { content: 'inline' as const } : {}),
+  }
+}
+
+/**
+ * The component layer of one component: the props and slots of its meta, joined with the object of
+ * its `definePlutoBlock({...})` call. The macro wins, key by key (`false` removes a prop or a slot).
+ * `name` is the component name in Pascal case or kebab case. The result has the block key for the
+ * `PlutoBlocksConfig` of the component layer.
+ *
+ * Props that no widget fits (an object, an array, a function, a number literal) are left out. A
+ * page that sets one still shows it in Advanced. The macro can give such a prop a widget.
+ */
+export function blockFromComponentMeta(
+  name: string,
+  meta: PlutoComponentMeta,
+  macro?: PlutoBlockPatch | false
+): { name: string; definition: PlutoBlockPatch } {
+  const props: Record<string, PlutoBlockPropPatch> = {}
+  for (const prop of meta.props ?? []) {
+    const definition = propFromMeta(prop)
+    if (definition) {
+      props[prop.name] = definition
+    }
+  }
+  const slots: Record<string, PlutoBlockSlotDefinition> = {}
+  for (const slot of meta.slots ?? []) {
+    slots[slot.name] = slotFromMeta(slot)
+  }
+  const fromMeta: PlutoBlockPatch = {
+    ...(Object.keys(props).length ? { props } : {}),
+    ...(Object.keys(slots).length ? { slots } : {}),
+  }
+  return {
+    name: componentBlockName(name),
+    definition: mergeBlockPatch(fromMeta, macro),
+  }
+}

package/shared/utils/blocks/define.ts

@@ -0,0 +1,15 @@
+import type { PlutoBlockPatch } from './types'
+
+/**
+ * Describes a block in `app.config.ts`, or in a component file of `components/content/`.
+ * The module adds it as an auto-import, so a component file needs no import line.
+ *
+ * At run time it does nothing: it returns its argument. The build reads the call in the file and
+ * makes the block definition from it. See the block-model skill. With a generic,
+ * `definePlutoBlock<Props>({...})` checks that the keys of `props` are props of the component.
+ */
+export function definePlutoBlock<
+  Props extends object = Record<string, unknown>,
+>(definition: PlutoBlockPatch<Props>): PlutoBlockPatch<Props> {
+  return definition
+}

package/shared/utils/blocks/editor.ts

@@ -0,0 +1,357 @@
+// Pure helpers for the block editor UI: the label, icon and excerpt of a block,
+// the Markdown of a slot, the blocks sent to the preview, and the palette
+// entries. No Nuxt import, so plain Vitest tests them.
+
+import type { PlutoPreviewBlock, PlutoPreviewChild } from './preview-protocol'
+import type {
+  PlutoBlock,
+  PlutoBlockDefinition,
+  PlutoBlockDoc,
+  PlutoBlockSources,
+  PlutoComponentBlock,
+} from './types'
+import { blockMarkdown } from './operations'
+import { BLOCK_KIND_LABELS } from './presets'
+import { listPaletteBlocks, resolveBlockDefinition } from './registry'
+import { renderBlock } from './serialize'
+import { findBlock, flatChildren, pathOf } from './tree'
+
+export interface PlutoBlockInfo {
+  /** A plain text or an i18n key. */
+  label: string
+  icon: string
+  /** A short plain text from the content of the block. */
+  excerpt: string
+  /** The name of the component, for a component block. */
+  name?: string
+}
+
+const HEADING = /^#{1,6} +(\S.*)$/m
+
+/** Removes the Markdown marks of a short text, so it reads as plain text in a list. */
+export function plainExcerpt(markdown: string, max = 48): string {
+  const text = markdown
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/[`*_~>#]/g, '')
+    .replace(/\{[^}]*\}/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text
+}
+
+function textExcerpt(markdown: string): string {
+  const heading = HEADING.exec(markdown)
+  if (heading) {
+    return plainExcerpt(heading[1]!.replace(/ +#+$/, ''))
+  }
+  const first = markdown
+    .split('\n')
+    .find((line) => line.trim() !== '' && !/^\s*(?:---|:::?)/.test(line))
+  return plainExcerpt(first ?? '')
+}
+
+/** The first line of text in a component, for the excerpt of a block that has no title. */
+function firstText(component: PlutoComponentBlock): string {
+  for (const child of flatChildren(component)) {
+    if (child.kind === 'text') {
+      return textExcerpt(child.markdown)
+    }
+  }
+  return ''
+}
+
+/** The label, the icon and the excerpt of a block in the outline. */
+export function describeBlock(
+  block: PlutoBlock,
+  sources: PlutoBlockSources = {}
+): PlutoBlockInfo {
+  switch (block.kind) {
+    case 'text': {
+      const heading = HEADING.test(block.markdown)
+      return {
+        label: BLOCK_KIND_LABELS.text,
+        icon: heading ? 'i-lucide-heading' : 'i-lucide-pilcrow',
+        excerpt: textExcerpt(block.markdown),
+      }
+    }
+    case 'code':
+      return {
+        label: BLOCK_KIND_LABELS.code,
+        icon: 'i-lucide-code-xml',
+        excerpt: block.filename || block.lang || '',
+      }
+    case 'raw':
+      return {
+        label:
+          block.reason === 'table'
+            ? 'docs.blocks.kinds.table'
+            : BLOCK_KIND_LABELS.raw,
+        icon:
+          block.reason === 'table' ? 'i-lucide-table' : 'i-lucide-file-text',
+        excerpt: block.reason === 'table' ? '' : textExcerpt(block.markdown),
+      }
+    case 'component': {
+      const definition = resolveBlockDefinition(block.name, { sources })
+      const title =
+        typeof block.props.title === 'string'
+          ? block.props.title
+          : typeof block.props.label === 'string'
+            ? block.props.label
+            : ''
+      return {
+        label: definition.label,
+        icon: definition.icon,
+        excerpt: plainExcerpt(title || firstText(block)),
+        name: block.name,
+      }
+    }
+  }
+}
+
+/** The Markdown of the children of one slot, without the white space of the parent. */
+export function slotMarkdown(
+  component: PlutoComponentBlock,
+  slot: string
+): string {
+  return (component.slots[slot] ?? [])
+    .map((child) => blockMarkdown(child))
+    .join('\n\n')
+}
+
+export type PlutoSlotMode = 'rich' | 'inline' | 'blocks' | 'markdown'
+
+/**
+ * The editor for a slot. A `rich` or `inline` slot falls back when its content
+ * has a block or a syntax that the text editor would lose: it then shows the
+ * blocks, or a Markdown box.
+ */
+export function resolveSlotMode(
+  component: PlutoComponentBlock,
+  slot: string,
+  wanted: 'rich' | 'inline' | 'blocks' | undefined
+): PlutoSlotMode {
+  const children = component.slots[slot] ?? []
+  if (wanted === 'blocks') {
+    return 'blocks'
+  }
+  // A component or a code block inside the slot needs the list of blocks.
+  if (
+    !children.every((child) => child.kind === 'text' || child.kind === 'raw')
+  ) {
+    return 'blocks'
+  }
+  // The parser turns prose that the text editor would lose into a raw block. Markdown keeps it as it is.
+  if (children.some((child) => child.kind === 'raw')) {
+    return 'markdown'
+  }
+  const markdown = slotMarkdown(component, slot)
+  if (wanted === 'inline') {
+    return markdown.includes('\n') ? 'markdown' : 'inline'
+  }
+  return 'rich'
+}
+
+/**
+ * The block that the preview shows as selected: the deepest component on the
+ * path of the selected block, else its top-level block. The preview marks only
+ * the top-level blocks and the inner components, so a text inside a card shows
+ * the card.
+ */
+export function previewSelectionId(
+  doc: PlutoBlockDoc,
+  id: string | null
+): string | null {
+  if (!id) {
+    return null
+  }
+  const path = pathOf(doc, id)
+  for (let index = path.length - 1; index > 0; index--) {
+    if (findBlock(doc, path[index]!)?.block.kind === 'component') {
+      return path[index]!
+    }
+  }
+  return path[0] ?? null
+}
+
+/** The top-level blocks as the preview frame wants them. */
+export function toPreviewBlocks(
+  blocks: PlutoBlock[],
+  sources: PlutoBlockSources = {}
+): PlutoPreviewBlock[] {
+  return blocks.map((block) => {
+    const markdown = renderBlock(block)
+    if (block.kind !== 'component') {
+      return { id: block.id, markdown }
+    }
+    const definition = resolveBlockDefinition(block.name, { sources })
+    const children = previewChildren(block, sources)
+    return {
+      id: block.id,
+      markdown,
+      label: definition.label,
+      ...(definition.preview === false ? { preview: false } : {}),
+      ...(children.length ? { children } : {}),
+    }
+  })
+}
+
+/**
+ * The inner components of a component, in source order over all slots, for
+ * the marks of the preview (a click selects an inner block). Text, code and raw
+ * children are not here: a click on them selects the nearest component.
+ */
+export function previewChildren(
+  component: PlutoComponentBlock,
+  sources: PlutoBlockSources = {}
+): PlutoPreviewChild[] {
+  return flatChildren(component)
+    .filter((child): child is PlutoComponentBlock => child.kind === 'component')
+    .map((child) => {
+      const children = previewChildren(child, sources)
+      return {
+        id: child.id,
+        name: child.name,
+        label: resolveBlockDefinition(child.name, { sources, block: child })
+          .label,
+        ...(children.length ? { children } : {}),
+      }
+    })
+}
+
+/** The component names that a slot accepts, or `undefined` for any. */
+export function acceptedNames(
+  definition: PlutoBlockDefinition,
+  slot: string
+): string[] | undefined {
+  return definition.slots?.[slot]?.accepts
+}
+
+export type PlutoPaletteEntry =
+  | {
+      id: string
+      kind: 'text'
+      group: string
+      label: string
+      description: string
+      icon: string
+      markdown: string
+    }
+  | {
+      id: string
+      kind: 'code'
+      group: string
+      label: string
+      description: string
+      icon: string
+      markdown: string
+    }
+  | {
+      id: string
+      kind: 'table'
+      group: string
+      label: string
+      description: string
+      icon: string
+      markdown: string
+    }
+  | {
+      id: string
+      kind: 'component'
+      group: string
+      label: string
+      description: string
+      icon: string
+      name: string
+      markdown: string
+    }
+
+export interface PlutoPaletteGroup {
+  group: string
+  entries: PlutoPaletteEntry[]
+}
+
+const TABLE_MARKDOWN =
+  '| Column | Column |\n| ------ | ------ |\n| Cell | Cell |'
+
+/**
+ * The palette: the built-in blocks (text, code, table) first, then the
+ * component groups. `accepts` limits the list to some component names, for a
+ * target inside a component that takes only some children.
+ */
+export function buildPalette(
+  sources: PlutoBlockSources = {},
+  accepts?: string[]
+): PlutoPaletteGroup[] {
+  const groups: PlutoPaletteGroup[] = []
+  if (!accepts) {
+    groups.push({
+      group: 'text',
+      entries: [
+        {
+          id: 'builtin:text',
+          kind: 'text',
+          group: 'text',
+          label: BLOCK_KIND_LABELS.text,
+          description: 'docs.blocks.kinds.textDescription',
+          icon: 'i-lucide-pilcrow',
+          markdown: '## Title\n\nWrite your text here.',
+        },
+        {
+          id: 'builtin:table',
+          kind: 'table',
+          group: 'text',
+          label: 'docs.blocks.kinds.table',
+          description: 'docs.blocks.kinds.tableDescription',
+          icon: 'i-lucide-table',
+          markdown: TABLE_MARKDOWN,
+        },
+      ],
+    })
+    groups.push({
+      group: 'code',
+      entries: [
+        {
+          id: 'builtin:code',
+          kind: 'code',
+          group: 'code',
+          label: BLOCK_KIND_LABELS.code,
+          description: 'docs.blocks.kinds.codeDescription',
+          icon: 'i-lucide-code-xml',
+          markdown: "```ts\nconst hello = 'world'\n```",
+        },
+      ],
+    })
+  }
+  for (const { group, items } of listPaletteBlocks(sources)) {
+    const entries = items
+      .filter((item) => !accepts || accepts.includes(item.name))
+      .map((item): PlutoPaletteEntry => ({
+        id: `component:${item.name}`,
+        kind: 'component',
+        group,
+        label: item.label,
+        description: item.description ?? '',
+        icon: item.icon,
+        name: item.name,
+        markdown: item.insert ?? `::${item.name}\n::`,
+      }))
+    if (entries.length === 0) {
+      continue
+    }
+    const existing = groups.find((candidate) => candidate.group === group)
+    if (existing) {
+      existing.entries.push(...entries)
+    } else {
+      groups.push({ group, entries })
+    }
+  }
+  return groups
+}
+
+/** How many blocks a block holds, itself included. */
+export function countBlocks(block: PlutoBlock): number {
+  return block.kind === 'component'
+    ? 1 +
+        flatChildren(block).reduce((sum, child) => sum + countBlocks(child), 0)
+    : 1
+}