@plutocms/docs 0.15.0 → 0.16.0

package/shared/utils/blocks/registry.ts

@@ -1,38 +1,69 @@
-// 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.
+// 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 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
-}
+// 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 `plutoBlocks` value of the app config. */
-  overrides?: PlutoBlocksConfig
+  /** 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`. */
+/** 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(/[-_]+/g, ' ').trim()
+  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,
@@ -57,31 +88,113 @@ function propFromValue(value: unknown): PlutoBlockPropDefinition {
   }
 }
 
-function isOverrideObject(
-  override: PlutoBlockOverride | undefined
-): override is Exclude<PlutoBlockOverride, false> {
-  return typeof override === 'object' && override !== null
+/** 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,
-  override: PlutoBlockOverride | undefined
+  layer: PlutoBlockOverride | undefined
 ): PlutoBlockDefinition {
-  if (override === false) {
+  if (layer === false) {
     return { ...base, hidden: true }
   }
-  if (!isOverrideObject(override)) {
+  if (typeof layer !== 'object' || layer === null) {
     return base
   }
   return {
     ...base,
-    ...override,
+    ...layer,
     name: base.name,
-    props: { ...base.props, ...override.props },
-    slots: { ...base.slots, ...override.slots },
+    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')
@@ -89,33 +202,50 @@ function slotFromChildren(children: PlutoBlock[]): PlutoBlockSlotDefinition {
 }
 
 /**
- * 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.
+ * 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 base = BLOCK_PRESETS[name] ?? automaticDefinition(name)
-  const merged = mergeDefinition(base, options.overrides?.[name])
+  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 = { ...merged.props }
-  for (const [key, value] of Object.entries(found.props)) {
+  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 (
-      !(key in props) &&
-      !(HIDDEN_PROP_NAMES as readonly string[]).includes(key)
+      !(prop in props) &&
+      !(HIDDEN_PROP_NAMES as readonly string[]).includes(prop)
     ) {
-      props[key] = propFromValue(value)
+      props[prop] = propFromValue(value)
     }
   }
   const slots = { ...merged.slots }
-  for (const [key, children] of Object.entries(found.slots)) {
-    if (!(key in slots)) {
-      slots[key] = slotFromChildren(children)
+  for (const [slot, children] of Object.entries(found.slots)) {
+    if (!(slot in slots)) {
+      slots[slot] = slotFromChildren(children)
     }
   }
   return { ...merged, props, slots }
@@ -133,19 +263,21 @@ export interface PaletteGroup {
 
 /**
  * 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.
+ * 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(
-  overrides: PlutoBlocksConfig = {}
+  sources: PlutoBlockSources = {}
 ): PaletteGroup[] {
-  const names = [
+  const names = new Set([
     ...Object.keys(BLOCK_PRESETS),
-    ...Object.keys(overrides).filter((name) => !(name in 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, { overrides })
+    const definition = resolveBlockDefinition(name, { sources })
     if (definition.hidden) {
       continue
     }

package/shared/utils/blocks/types.ts

@@ -128,6 +128,11 @@ export interface PlutoBlockPropDefinition {
    * 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. */
@@ -158,8 +163,33 @@ export interface PlutoBlockDefinition {
   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
+/** 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
+}