@plutocms/docs 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.16.0](https://github.com/plutocms/docs/compare/v0.15.0...v0.16.0) (2026-10-31)
+
+
+### Features
+
+* block sources and component meta mapping for the editor ([#75](https://github.com/plutocms/docs/issues/75)) ([cc04cf0](https://github.com/plutocms/docs/commit/cc04cf044112b6d4432817711c1e8ed34cce1b7e))
+* discover editor blocks from definePlutoBlock in components/content ([#78](https://github.com/plutocms/docs/issues/78)) ([0ce82b9](https://github.com/plutocms/docs/commit/0ce82b9672b276c6b50edf6f647fd42490595c84))
+
 ## [0.15.0](https://github.com/plutocms/nuxt-content/compare/v0.14.0...v0.15.0) (2026-10-31)
 
 

package/FEATURES.md

@@ -26,5 +26,9 @@ policies shared by every project here.
 - Block model: the pure model of the visual block editor (parse, serialize, edit, history,
   presets, registry, preview protocol). The text of an unedited block stays byte for byte. See
   @.claude/skills/block-model/SKILL.md.
+- Block discovery: a component in `components/content/` (the app or a layer) that calls
+  `definePlutoBlock({...})` becomes a block in the palette, with its props and slots read from its
+  TypeScript types. Opt-in. The option `plutoDocs.blocks.discover` turns it off. See
+  @.claude/skills/block-model/SKILL.md.
 - Block editor: the visual editor for the page body. A live preview, the block list, the palette, and
   the controls of the selected block, with no raw MDC. See @.claude/skills/block-editor/SKILL.md.

package/README.md

@@ -31,6 +31,7 @@ setup: the collections, the CSS entry, `PlutoRoot`, and the GitHub App.
 
 - A `docs` page type for nested, numbered Markdown pages.
 - A visual block editor with a live preview, and a Markdown mode.
+- Your own components in the palette: call `definePlutoBlock({ label, icon })` in a component of `components/content/`. The props and slots come from its TypeScript types.
 - Hybrid render mode (default): a save shows on the site at once, with no wait for a build. Build and runtime modes are options.
 - "New Page" and "Edit Page" in the admin bar, and an "Edit in admin" link for the public page.
 - The pages on the public API of Pluto (`/api/pluto/v1/content/<type>`), for a site in any stack.

package/app/components/Pluto/Docs/Blocks/PlutoBlockEditor.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// The component layer. Only the two editor roots import it, so it stays out of the public pages.
+import componentBlocks from '#pluto-docs/blocks'
 // The visual block editor: the canvas of the 'canvas' form layout. The canvas
 // shows the live preview of the page. The block list goes in the left panel,
 // and the controls of the selected block go in the right panel (a tab of the
@@ -24,12 +26,12 @@ const emit = defineEmits<{
 
 const { t } = usePlutoI18n()
 const form = usePlutoContentForm()
-const blocksConfig = usePlutoBlocksConfig()
+const blockSources = usePlutoBlockSources(componentBlocks)
 
 const editor = createPlutoBlockEditor({
   source: () => props.modelValue,
   emit: (value) => emit('update:modelValue', value),
-  overrides: blocksConfig,
+  sources: blockSources,
 })
 provide(plutoBlockEditorKey, editor)
 

package/app/components/Pluto/Docs/Blocks/PlutoBlockMarkdownSplit.vue

@@ -9,6 +9,8 @@
 // here: the block model only feeds the preview and never writes.
 import type { SplitterItem } from '@nuxt/ui'
 import type { PlutoMarkdownCodeEditor as CodeEditor } from '#components'
+// The component layer. Only the two editor roots import it, so it stays out of the public pages.
+import componentBlocks from '#pluto-docs/blocks'
 import { findBlock } from '../../../../../shared/utils/blocks/tree'
 import PlutoMdcInsertMenu from '../PlutoMdcInsertMenu.vue'
 import PlutoBlockModeSwitch from './PlutoBlockModeSwitch.vue'
@@ -28,12 +30,12 @@ const emit = defineEmits<{
 }>()
 
 const form = usePlutoContentForm()
-const blocksConfig = usePlutoBlocksConfig()
+const blockSources = usePlutoBlockSources(componentBlocks)
 
 const editor = createPlutoBlockEditor({
   source: () => props.modelValue,
   emit: () => {},
-  overrides: blocksConfig,
+  sources: blockSources,
 })
 provide(plutoBlockEditorKey, editor)
 

package/app/components/Pluto/Docs/Blocks/PlutoBlockPalette.vue

@@ -13,7 +13,6 @@ import { findBlock } from '../../../../../shared/utils/blocks/tree'
 
 const editor = usePlutoBlockEditor()
 const { t, tx } = usePlutoI18n()
-const blocksConfig = usePlutoBlocksConfig()
 
 const open = computed({
   get: () => editor.palette.value.open,
@@ -43,19 +42,21 @@ function findBlockById(id: string) {
 }
 
 const groups = computed<CommandPaletteGroup[]>(() =>
-  buildPalette(blocksConfig(), accepts.value).map(({ group, entries }) => ({
-    id: group,
-    label: tx(groupLabelKey(group)),
-    items: entries.map((entry): CommandPaletteItem => ({
-      label: tx(entry.label),
-      suffix: entry.description ? tx(entry.description) : undefined,
-      icon: entry.icon,
-      onSelect: () => {
-        editor.insert(entry, editor.palette.value.target)
-        open.value = false
-      },
-    })),
-  }))
+  buildPalette(editor.sources.value, accepts.value).map(
+    ({ group, entries }) => ({
+      id: group,
+      label: tx(groupLabelKey(group)),
+      items: entries.map((entry): CommandPaletteItem => ({
+        label: tx(entry.label),
+        suffix: entry.description ? tx(entry.description) : undefined,
+        icon: entry.icon,
+        onSelect: () => {
+          editor.insert(entry, editor.palette.value.target)
+          open.value = false
+        },
+      })),
+    })
+  )
 )
 </script>
 
@@ -64,7 +65,7 @@ const groups = computed<CommandPaletteGroup[]>(() =>
     v-model:open="open"
     :title="t('docs.editor.addBlock')"
     :description="t('docs.editor.addBlockDescription')"
-    :ui="{ content: 'max-w-xl', header: 'sr-only' }"
+    :ui="{ content: 'pluto-palette max-w-xl', header: 'sr-only' }"
   >
     <template #content>
       <UCommandPalette

package/app/components/Pluto/Docs/Blocks/PlutoBlockPreviewFrame.vue

@@ -22,7 +22,6 @@ const props = defineProps<{
 const editor = usePlutoBlockEditor()
 const { t, tx } = usePlutoI18n()
 const router = useRouter()
-const blocksConfig = usePlutoBlocksConfig()
 
 const DEBOUNCE_MS = 150
 const LOAD_TIMEOUT_MS = 12000
@@ -40,7 +39,7 @@ const shownId = computed(() =>
   previewSelectionId(editor.doc.value, editor.selectedId.value)
 )
 const blocks = computed(() =>
-  toPreviewBlocks(editor.doc.value.blocks, blocksConfig())
+  toPreviewBlocks(editor.doc.value.blocks, editor.sources.value)
 )
 
 function send(message: ReturnType<typeof previewMessage>) {

package/app/components/Pluto/Docs/Blocks/PlutoBlockPropControl.vue

@@ -62,12 +62,27 @@ function setText(value: string | undefined) {
   )
 }
 
+// The default of the component, as a text for a placeholder.
+const defaultText = computed(() =>
+  props.definition.default === undefined
+    ? undefined
+    : String(props.definition.default)
+)
+
+const switchOn = computed(() =>
+  props.modelValue === undefined
+    ? props.definition.default === true
+    : props.modelValue === true || props.modelValue === 'true'
+)
+
 function setBoolean(value: boolean) {
-  // Off removes the prop. An explicit `false` in the source stays false.
-  emit(
-    'update:modelValue',
-    value ? true : props.modelValue === false ? false : undefined
-  )
+  // The state of the default removes the prop. An explicit value in the source stays explicit.
+  const fallback = props.definition.default === true
+  if (value === fallback) {
+    emit('update:modelValue', props.modelValue === value ? value : undefined)
+  } else {
+    emit('update:modelValue', value)
+  }
 }
 
 const numberValue = computed(() => {
@@ -90,7 +105,12 @@ const selectItems = computed(() => {
   if (current && !items.some((item) => item.value === current)) {
     items.push({ value: current, label: current })
   }
-  return [{ value: DEFAULT, label: t('docs.editor.default') }, ...items]
+  // "Default (slow)": the item shows the value that the component uses.
+  const fallback = items.find((item) => item.value === defaultText.value)
+  const defaultLabel = defaultText.value
+    ? `${t('docs.editor.default')} (${fallback?.label ?? defaultText.value})`
+    : t('docs.editor.default')
+  return [{ value: DEFAULT, label: defaultLabel }, ...items]
 })
 
 const colorItems = computed(() =>
@@ -156,7 +176,7 @@ const iconPreview = computed(() =>
   >
     <USwitch
       v-if="type === 'boolean'"
-      :model-value="modelValue === true || modelValue === 'true'"
+      :model-value="switchOn"
       :disabled="disabled"
       :aria-label="label"
       @update:model-value="setBoolean($event)"
@@ -165,6 +185,7 @@ const iconPreview = computed(() =>
     <UInputNumber
       v-else-if="type === 'number'"
       :model-value="numberValue"
+      :placeholder="defaultText"
       :disabled="disabled"
       class="w-full"
       @update:model-value="emit('update:modelValue', $event ?? undefined)"
@@ -193,6 +214,7 @@ const iconPreview = computed(() =>
     <UTextarea
       v-else-if="type === 'text'"
       :model-value="text"
+      :placeholder="defaultText"
       :disabled="disabled"
       :rows="2"
       class="w-full"
@@ -217,7 +239,7 @@ const iconPreview = computed(() =>
       :model-value="text"
       :disabled="disabled"
       :icon="iconPreview"
-      placeholder="i-lucide-rocket"
+      :placeholder="defaultText ?? 'i-lucide-rocket'"
       spellcheck="false"
       autocomplete="off"
       class="w-full"
@@ -228,7 +250,7 @@ const iconPreview = computed(() =>
       v-else-if="type === 'link'"
       :model-value="text"
       :disabled="disabled"
-      :placeholder="t('docs.editor.linkPlaceholder')"
+      :placeholder="defaultText ?? t('docs.editor.linkPlaceholder')"
       icon="i-lucide-link"
       autocomplete="off"
       class="w-full"
@@ -238,6 +260,7 @@ const iconPreview = computed(() =>
     <UInput
       v-else
       :model-value="text"
+      :placeholder="defaultText"
       :disabled="disabled"
       class="w-full"
       @update:model-value="setText($event as string)"

package/app/composables/pluto-block-editor.ts

@@ -8,6 +8,7 @@ import type {
   PlutoBlockDoc,
   PlutoBlockLocation,
   PlutoBlocksConfig,
+  PlutoBlockSources,
   PlutoCodeBlock,
   PlutoPropValue,
 } from '../../shared/utils/blocks/types'
@@ -53,12 +54,14 @@ export interface PlutoBlockEditorOptions {
   source: () => string
   /** Called with the new text after each edit, undo and redo. Never called at the start. */
   emit: (value: string) => void
-  /** The `plutoBlocks` value of the app config. */
-  overrides?: () => PlutoBlocksConfig | undefined
+  /** The layers of the block definitions: the component layer and the `plutoBlocks` of the app config. */
+  sources?: () => PlutoBlockSources | undefined
   now?: () => number
 }
 
 export interface PlutoBlockEditor {
+  /** The layers of the block definitions. The palette, the preview and the labels read them here. */
+  sources: ComputedRef<PlutoBlockSources>
   doc: ComputedRef<PlutoBlockDoc>
   /** The message of a parse error. The editor then offers the Markdown mode only. */
   error: Ref<string | null>
@@ -156,7 +159,7 @@ export function createPlutoBlockEditor(
   options: PlutoBlockEditorOptions
 ): PlutoBlockEditor {
   const now = options.now ?? Date.now
-  const overrides = () => options.overrides?.() ?? {}
+  const sources = computed(() => options.sources?.() ?? {})
 
   const initial = tryParse(options.source())
   const error = ref<string | null>(initial.error)
@@ -244,7 +247,7 @@ export function createPlutoBlockEditor(
 
   function definitionOf(block: PlutoBlock): PlutoBlockDefinition | undefined {
     return block.kind === 'component'
-      ? resolveBlockDefinition(block.name, { overrides: overrides(), block })
+      ? resolveBlockDefinition(block.name, { sources: sources.value, block })
       : undefined
   }
 
@@ -332,6 +335,7 @@ export function createPlutoBlockEditor(
   }
 
   return {
+    sources,
     doc,
     error,
     selection,
@@ -378,7 +382,7 @@ export function createPlutoBlockEditor(
       }
     },
     definitionOf,
-    describe: (block) => describeBlock(block, overrides()),
+    describe: (block) => describeBlock(block, sources.value),
     siblings,
   }
 }
@@ -401,10 +405,22 @@ export function usePlutoBlocksConfig(): () => PlutoBlocksConfig | undefined {
   return () => appConfig.plutoBlocks as unknown as PlutoBlocksConfig | undefined
 }
 
+/**
+ * The layers of the block definitions for a block editor: the component layer and the
+ * `plutoBlocks` value of the app config. The caller passes the component layer in: the two editor
+ * roots import it from `#pluto-docs/blocks`, so the data stays in the lazy editor chunk.
+ */
+export function usePlutoBlockSources(
+  components: PlutoBlocksConfig = {}
+): () => PlutoBlockSources {
+  const blocksConfig = usePlutoBlocksConfig()
+  return () => ({ components, overrides: blocksConfig() })
+}
+
 /** The texts of the slots of a component: the title of a slot, and the label of its "Add" button. */
 export function usePlutoBlockLabels() {
   const { t, tx } = usePlutoI18n()
-  const blocksConfig = usePlutoBlocksConfig()
+  const editor = usePlutoBlockEditor()
 
   function slotLabel(
     definition: PlutoBlockDefinition | undefined,
@@ -428,7 +444,7 @@ export function usePlutoBlockLabels() {
     if (accepts?.length === 1) {
       return t('docs.editor.addItem', {
         name: tx(
-          resolveBlockDefinition(accepts[0]!, { overrides: blocksConfig() })
+          resolveBlockDefinition(accepts[0]!, { sources: editor.sources.value })
             .label
         ),
       })

package/modules/pluto-docs/blocks.ts

@@ -0,0 +1,217 @@
+// Find the block components of a site and read their definitions at build time.
+// A component is a block only when its file calls `definePlutoBlock(...)`. The props and slots come
+// from the TypeScript meta (`nuxt-component-meta`), the label, icon and more from the call.
+// This file has no Nuxt import, so plain Vitest tests it.
+
+import type { PlutoComponentMeta } from '../../shared/utils/blocks/component-meta'
+import type {
+  PlutoBlockPatch,
+  PlutoBlocksConfig,
+} from '../../shared/utils/blocks/types'
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { blockFromComponentMeta } from '../../shared/utils/blocks/component-meta'
+
+/** The name of the macro. A component file calls it in `<script setup>`. */
+export const BLOCK_MACRO = 'definePlutoBlock'
+
+/** The key of the macro argument in the output of the parser. */
+export const MACRO_KEY = 'pluto'
+
+/** The folder of the components that Nuxt Content renders, in the app and in each layer. */
+export const CONTENT_COMPONENTS_DIR = 'components/content'
+
+export interface BlockFile {
+  /** The component name in Pascal case: `PlutoHero`. */
+  name: string
+  file: string
+}
+
+/** The output of the parser, with the macro argument under `pluto`. */
+export type ParsedComponent = PlutoComponentMeta & {
+  [MACRO_KEY]?: PlutoBlockPatch
+}
+
+export type MetaReader = (file: string) => ParsedComponent
+
+export interface BlockEntry {
+  /** The hash of the file text. The entry is valid while the hash is the same. */
+  hash: string
+  block?: { name: string; definition: PlutoBlockPatch }
+  warnings: string[]
+  /** The time of the parse, in milliseconds. 0 when the entry came from the cache. */
+  ms: number
+}
+
+export interface BlockLog {
+  warn: (message: string) => void
+  debug: (message: string) => void
+}
+
+/** Whether the file text calls the macro: `definePlutoBlock(...)` or `definePlutoBlock<Props>(...)`. */
+export function hasBlockMacro(text: string): boolean {
+  return /\bdefinePlutoBlock\s*[(<]/.test(text)
+}
+
+/**
+ * The component files of the `components/content` folders. The folders come in order of priority
+ * (the app first, then its layers). When two files have the same name, the first one wins. A
+ * `Prose*` file is a prose override, an `.client` or `.server` file is a variant: none is a block.
+ */
+export function findContentComponents(dirs: string[]): BlockFile[] {
+  const found = new Map<string, BlockFile>()
+  const visit = (dir: string) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(path)
+        continue
+      }
+      if (!entry.name.endsWith('.vue')) {
+        continue
+      }
+      const name = basename(entry.name, '.vue')
+      if (
+        name.startsWith('Prose') ||
+        name.endsWith('.client') ||
+        name.endsWith('.server') ||
+        found.has(name)
+      ) {
+        continue
+      }
+      found.set(name, { name, file: path })
+    }
+  }
+  for (const dir of dirs) {
+    visit(dir)
+  }
+  return [...found.values()]
+}
+
+function hashOf(text: string): string {
+  return createHash('sha1').update(text).digest('hex')
+}
+
+/**
+ * Read the block of one component file. A file without the macro gives an entry with no block, and
+ * the parser does not run. A parse error gives a warning and no block. A macro that the parser
+ * cannot evaluate (for example, an argument that uses a local variable) gives a warning and no
+ * block: a half-read definition would hide the mistake.
+ */
+export function readBlockEntry(
+  { name, file }: BlockFile,
+  text: string,
+  read: MetaReader,
+  now: () => number = Date.now
+): BlockEntry {
+  const hash = hashOf(text)
+  if (!hasBlockMacro(text)) {
+    return { hash, warnings: [], ms: 0 }
+  }
+  const start = now()
+  let parsed: ParsedComponent
+  try {
+    parsed = read(file)
+  } catch (error) {
+    return {
+      hash,
+      warnings: [
+        `${BLOCK_MACRO} in ${file} was skipped. The component did not parse: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+      ms: now() - start,
+    }
+  }
+  const ms = now() - start
+  const macro = parsed[MACRO_KEY]
+  if (!macro) {
+    return {
+      hash,
+      warnings: [
+        `${BLOCK_MACRO} in ${file} was skipped. Its argument must be an object literal that does not use a local variable. It can use a constant imported from a file.`,
+      ],
+      ms,
+    }
+  }
+  // The key is not a block field. The meta is only props and slots.
+  const { [MACRO_KEY]: _macro, ...meta } = parsed
+  return {
+    hash,
+    block: blockFromComponentMeta(name, pickMeta(meta), macro),
+    warnings: [],
+    ms,
+  }
+}
+
+function pickMeta(meta: ParsedComponent): PlutoComponentMeta {
+  return { props: meta.props, slots: meta.slots }
+}
+
+/**
+ * The component layer of a site: the blocks of the component files, with a cache by file. A file
+ * is parsed again only when its text changed. Call `collect` for each build and each hot update.
+ */
+export class BlockCatalog {
+  private cache = new Map<string, BlockEntry>()
+
+  constructor(
+    private dirs: () => string[],
+    private read: MetaReader,
+    private log: BlockLog,
+    private now: () => number = Date.now
+  ) {}
+
+  collect(): PlutoBlocksConfig {
+    const start = this.now()
+    const files = findContentComponents(this.dirs())
+    const result: PlutoBlocksConfig = {}
+    const seen = new Set<string>()
+    let parsed = 0
+    for (const item of files) {
+      seen.add(item.file)
+      let text: string
+      try {
+        text = readFileSync(item.file, 'utf8')
+      } catch {
+        continue
+      }
+      let entry = this.cache.get(item.file)
+      if (!entry || entry.hash !== hashOf(text)) {
+        entry = readBlockEntry(item, text, this.read, this.now)
+        this.cache.set(item.file, entry)
+        for (const warning of entry.warnings) {
+          this.log.warn(warning)
+        }
+        if (entry.block) {
+          parsed++
+          this.log.debug(`${item.name}: ${entry.ms} ms`)
+        }
+      }
+      if (entry.block) {
+        result[entry.block.name] = entry.block.definition
+      }
+    }
+    for (const file of this.cache.keys()) {
+      if (!seen.has(file)) {
+        this.cache.delete(file)
+      }
+    }
+    if (parsed > 0) {
+      this.log.debug(
+        `Read ${parsed} block component(s) in ${this.now() - start} ms.`
+      )
+    }
+    return result
+  }
+}
+
+/** The source of the Vite virtual module for a component layer. */
+export function blocksModuleSource(blocks: PlutoBlocksConfig): string {
+  return `export default ${JSON.stringify(blocks)}\n`
+}