@plutocms/docs 0.15.0 → 0.16.0

package/modules/pluto-docs/index.ts

@@ -1,12 +1,22 @@
+import type { Nuxt } from '@nuxt/schema'
 import type { PlutoDocsOptions } from './options'
 import { join } from 'node:path'
 import {
+  addImports,
   addServerHandler,
+  addVitePlugin,
   createResolver,
   defineNuxtModule,
   useLogger,
 } from '@nuxt/kit'
 import { PREVIEW_PATH } from '../../shared/utils/blocks/preview-protocol'
+import {
+  BLOCK_MACRO,
+  BlockCatalog,
+  blocksModuleSource,
+  CONTENT_COMPONENTS_DIR,
+  MACRO_KEY,
+} from './blocks'
 import { buildContentManifest, manifestModuleSource } from './manifest'
 import { resolvePlutoDocsOptions } from './options'
 
@@ -33,7 +43,7 @@ export default defineNuxtModule<PlutoDocsOptions>({
       nuxt.options as { plutoGithub?: { enabled?: boolean | 'auto' } }
     ).plutoGithub
 
-    const { enabled, render, runtimeMaxAge, types, errors } =
+    const { enabled, render, runtimeMaxAge, types, blocks, errors } =
       resolvePlutoDocsOptions(options, {
         cmsEnabled: cms?.enabled !== false,
       })
@@ -41,6 +51,17 @@ export default defineNuxtModule<PlutoDocsOptions>({
     for (const error of errors) {
       logger.error(error)
     }
+    // `definePlutoBlock(...)` in a component file. A typed no-op at run time: the build reads the call.
+    addImports({
+      name: BLOCK_MACRO,
+      from: createResolver(import.meta.url).resolve(
+        '../../shared/utils/blocks/define'
+      ),
+    })
+
+    // The editor imports the virtual module even when the layer is off, so it always exists.
+    setupBlockDiscovery(nuxt, logger, enabled && blocks.discover)
+
     if (!enabled) {
       return
     }
@@ -121,3 +142,89 @@ export default defineNuxtModule<PlutoDocsOptions>({
     }
   },
 })
+
+/**
+ * The component layer of the block editor. The virtual module `#pluto-docs/blocks` holds the blocks
+ * of the `components/content/` folders. Only the two lazy editor roots import it, so it stays out of
+ * the public pages. The server build gets an empty object: the editor never renders on the server.
+ * The cost comes when the editor first loads, not at start-up. A change to a component file makes
+ * the module load again, and the catalog parses only the file that changed.
+ */
+function setupBlockDiscovery(
+  nuxt: Nuxt,
+  logger: ReturnType<typeof useLogger>,
+  discover: boolean
+) {
+  const id = '#pluto-docs/blocks'
+  // The `\0` prefix marks a virtual id. No `#` in it: a browser URL ends at the `#`.
+  const resolved = '\0pluto-docs-blocks'
+  // The app first, then its layers (the order of priority).
+  const dirs = () =>
+    nuxt.options._layers.map((layer) =>
+      join(layer.config.srcDir, CONTENT_COMPONENTS_DIR)
+    )
+
+  // The cache of the parser names a file from the text after the last slash, so give it slashes.
+  const slashes = (path: string) => path.replaceAll('\\', '/')
+
+  type Reader = typeof import('nuxt-component-meta/parser').getComponentMeta
+  let getComponentMeta: Reader | undefined
+  const catalog = new BlockCatalog(
+    dirs,
+    (file) =>
+      getComponentMeta!(slashes(file), {
+        rootDir: nuxt.options.rootDir,
+        cache: true,
+        cacheDir: join(nuxt.options.buildDir, 'cache/pluto-blocks'),
+        extendMetaFunctions: [
+          { name: BLOCK_MACRO, transform: (arg) => ({ [MACRO_KEY]: arg }) },
+        ],
+      }) as never,
+    logger
+  )
+
+  const isBlockFile = (file: string) =>
+    file.endsWith('.vue') &&
+    dirs().some((dir) => slashes(file).startsWith(slashes(dir)))
+
+  addVitePlugin({
+    name: 'pluto-docs:blocks',
+    enforce: 'pre',
+    resolveId(source) {
+      return source === id ? resolved : undefined
+    },
+    async load(loaded, options) {
+      if (loaded !== resolved) {
+        return undefined
+      }
+      if (options?.ssr || !discover) {
+        return blocksModuleSource({})
+      }
+      // The parser loads here, not at start-up, because it brings the TypeScript compiler.
+      getComponentMeta ||= (await import('nuxt-component-meta/parser'))
+        .getComponentMeta
+      return blocksModuleSource(catalog.collect())
+    },
+    configureServer(server) {
+      const invalidate = (file: string) => {
+        if (!isBlockFile(file)) {
+          return
+        }
+        const module = server.moduleGraph.getModuleById(resolved)
+        if (module) {
+          server.moduleGraph.invalidateModule(module)
+          server.ws.send({ type: 'full-reload' })
+        }
+      }
+      server.watcher.on('add', invalidate)
+      server.watcher.on('unlink', invalidate)
+    },
+    handleHotUpdate({ file, server }) {
+      if (!isBlockFile(file)) {
+        return undefined
+      }
+      const module = server.moduleGraph.getModuleById(resolved)
+      return module ? [module] : undefined
+    },
+  })
+}

package/modules/pluto-docs/options.ts

@@ -41,6 +41,16 @@ export interface PlutoDocsOptions {
    * It is short, so a save shows soon. `0` turns the cache header into `no-store`.
    */
   runtimeMaxAge?: number
+  /** How the block editor finds the block components of the site. */
+  blocks?: PlutoDocsBlocksOptions
+}
+
+export interface PlutoDocsBlocksOptions {
+  /**
+   * Read `components/content/` of the app and of its layers. A component that calls
+   * `definePlutoBlock(...)` becomes a block. Default `true`. `false` turns the search off.
+   */
+  discover?: boolean
 }
 
 export interface PlutoDocsResolveContext {
@@ -52,6 +62,7 @@ export interface PlutoDocsResolveResult {
   enabled: boolean
   render: PlutoDocsRender
   runtimeMaxAge: number
+  blocks: { discover: boolean }
   types: PlutoDocsTypeOptions[]
   errors: string[]
 }
@@ -110,6 +121,7 @@ export function resolvePlutoDocsOptions(
       enabled: false,
       render: 'build',
       runtimeMaxAge: DEFAULT_RUNTIME_MAX_AGE,
+      blocks: { discover: false },
       types: [],
       errors: [CMS_OFF_ERROR],
     }
@@ -143,6 +155,21 @@ export function resolvePlutoDocsOptions(
     }
   }
 
+  let discover = true
+  if (options.blocks !== undefined) {
+    if (!isRecord(options.blocks)) {
+      errors.push('plutoDocs.blocks must be an object.')
+    } else if (options.blocks.discover !== undefined) {
+      if (typeof options.blocks.discover === 'boolean') {
+        discover = options.blocks.discover
+      } else {
+        errors.push(
+          'plutoDocs.blocks.discover must be true or false. Using true.'
+        )
+      }
+    }
+  }
+
   const types: PlutoDocsTypeOptions[] = []
   const names = new Set<string>()
   const entries: unknown[] = Array.isArray(options.types) ? options.types : []
@@ -220,5 +247,12 @@ export function resolvePlutoDocsOptions(
     })
   }
 
-  return { enabled: true, render, runtimeMaxAge, types, errors }
+  return {
+    enabled: true,
+    render,
+    runtimeMaxAge,
+    blocks: { discover },
+    types,
+    errors,
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/docs",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Docs layer for Pluto: edit the Markdown pages of a Nuxt Content site in the Pluto admin",
   "author": "Victor Ribeiro",
   "license": "MIT",
@@ -25,8 +25,9 @@
   "dependencies": {
     "@nuxt/content": "^3.16.2",
     "@nuxtjs/mdc": "^0.23.2",
-    "@plutocms/core": ">=0.39.0 <1.0.0",
+    "@plutocms/core": ">=0.40.0 <1.0.0",
     "@types/sortablejs": "^1.15.9",
+    "nuxt-component-meta": "0.18.0",
     "reka-ui": "^2.11.0",
     "remark-gfm": "4.0.1",
     "remark-mdc": "3.11.1",

package/shared/types/pluto-blocks.d.ts

@@ -0,0 +1,10 @@
+// The component layer of the block editor: the blocks of the `components/content/` files that call
+// `definePlutoBlock`. The module makes it as a Vite virtual module. See modules/pluto-docs/blocks.ts.
+// This file has no top-level import, so the declaration is an ambient module.
+declare module '#pluto-docs/blocks' {
+  const blocks: Record<
+    string,
+    import('../utils/blocks/types').PlutoBlockOverride
+  >
+  export default blocks
+}

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

@@ -7,7 +7,7 @@ import type {
   PlutoBlock,
   PlutoBlockDefinition,
   PlutoBlockDoc,
-  PlutoBlocksConfig,
+  PlutoBlockSources,
   PlutoComponentBlock,
 } from './types'
 import { blockMarkdown } from './operations'
@@ -63,7 +63,7 @@ function firstText(component: PlutoComponentBlock): string {
 /** The label, the icon and the excerpt of a block in the outline. */
 export function describeBlock(
   block: PlutoBlock,
-  overrides: PlutoBlocksConfig = {}
+  sources: PlutoBlockSources = {}
 ): PlutoBlockInfo {
   switch (block.kind) {
     case 'text': {
@@ -91,7 +91,7 @@ export function describeBlock(
         excerpt: block.reason === 'table' ? '' : textExcerpt(block.markdown),
       }
     case 'component': {
-      const definition = resolveBlockDefinition(block.name, { overrides })
+      const definition = resolveBlockDefinition(block.name, { sources })
       const title =
         typeof block.props.title === 'string'
           ? block.props.title
@@ -176,15 +176,15 @@ export function previewSelectionId(
 /** The top-level blocks as the preview frame wants them. */
 export function toPreviewBlocks(
   blocks: PlutoBlock[],
-  overrides: PlutoBlocksConfig = {}
+  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, { overrides })
-    const children = previewChildren(block, overrides)
+    const definition = resolveBlockDefinition(block.name, { sources })
+    const children = previewChildren(block, sources)
     return {
       id: block.id,
       markdown,
@@ -202,16 +202,16 @@ export function toPreviewBlocks(
  */
 export function previewChildren(
   component: PlutoComponentBlock,
-  overrides: PlutoBlocksConfig = {}
+  sources: PlutoBlockSources = {}
 ): PlutoPreviewChild[] {
   return flatChildren(component)
     .filter((child): child is PlutoComponentBlock => child.kind === 'component')
     .map((child) => {
-      const children = previewChildren(child, overrides)
+      const children = previewChildren(child, sources)
       return {
         id: child.id,
         name: child.name,
-        label: resolveBlockDefinition(child.name, { overrides, block: child })
+        label: resolveBlockDefinition(child.name, { sources, block: child })
           .label,
         ...(children.length ? { children } : {}),
       }
@@ -279,7 +279,7 @@ const TABLE_MARKDOWN =
  * target inside a component that takes only some children.
  */
 export function buildPalette(
-  overrides: PlutoBlocksConfig = {},
+  sources: PlutoBlockSources = {},
   accepts?: string[]
 ): PlutoPaletteGroup[] {
   const groups: PlutoPaletteGroup[] = []
@@ -322,7 +322,7 @@ export function buildPalette(
       ],
     })
   }
-  for (const { group, items } of listPaletteBlocks(overrides)) {
+  for (const { group, items } of listPaletteBlocks(sources)) {
     const entries = items
       .filter((item) => !accepts || accepts.includes(item.name))
       .map((item): PlutoPaletteEntry => ({

package/shared/utils/blocks/presets.ts

@@ -37,7 +37,8 @@ export function groupLabelKey(group: string): string {
     : group
 }
 
-const COLORS = [
+/** The theme colors of Nuxt UI. */
+export const BLOCK_COLORS = [
   'primary',
   'secondary',
   'success',
@@ -125,7 +126,7 @@ const DEFINITIONS: PlutoBlockDefinition[] = [
   block('callout', 'callouts', 'i-lucide-message-square-quote', {
     props: {
       icon: prop('icon', 'icon'),
-      color: prop('select', 'color', { options: options(COLORS) }),
+      color: prop('select', 'color', { options: options(BLOCK_COLORS) }),
       to: prop('link', 'to', { advanced: true }),
       target: prop('select', 'target', {
         options: options(TARGETS),
@@ -139,7 +140,7 @@ const DEFINITIONS: PlutoBlockDefinition[] = [
     props: {
       title: prop('string', 'title'),
       icon: prop('icon', 'icon'),
-      color: prop('select', 'color', { options: options(COLORS) }),
+      color: prop('select', 'color', { options: options(BLOCK_COLORS) }),
       to: prop('link', 'to'),
       target: prop('select', 'target', {
         options: options(TARGETS),
@@ -234,7 +235,7 @@ const DEFINITIONS: PlutoBlockDefinition[] = [
     hidden: true,
     props: {
       label: prop('string', 'label'),
-      color: prop('select', 'color', { options: options(COLORS) }),
+      color: prop('select', 'color', { options: options(BLOCK_COLORS) }),
     },
   }),
   block('kbd', 'text', 'i-lucide-keyboard', {
@@ -348,7 +349,7 @@ const DEFINITIONS: PlutoBlockDefinition[] = [
       label: prop('string', 'label', { slot: 'default' }),
       to: prop('link', 'to'),
       icon: prop('icon', 'icon'),
-      color: prop('select', 'color', { options: options(COLORS) }),
+      color: prop('select', 'color', { options: options(BLOCK_COLORS) }),
       variant: prop('select', 'variant', {
         options: options([
           'solid',