@plutocms/docs 0.0.0-stage → 0.15.0

package/shared/utils/blocks/presets.ts

@@ -0,0 +1,383 @@
+// The blocks that work with no site config: the Nuxt UI prose components and
+// the Nuxt UI page components that a Markdown page can use. Pure data. Each
+// label and description is an i18n key of the layer, in the group
+// docs.blocks.<name>. A prop or a slot name shared by many blocks has
+// one key in the groups props and slots of the same namespace.
+
+import type {
+  PlutoBlockDefinition,
+  PlutoBlockPropDefinition,
+  PlutoBlockPropOption,
+  PlutoBlockPropType,
+  PlutoBlockSlotContent,
+  PlutoBlockSlotDefinition,
+} from './types'
+import { MDC_SNIPPETS } from '../mdc-snippets'
+
+/** The group ids of the palette, in order. A site can use any other text as a group. */
+export const BLOCK_GROUPS = [
+  'text',
+  'callouts',
+  'layout',
+  'code',
+  'landing',
+  'site',
+] as const
+
+/** The labels of the three built-in kinds of block. */
+export const BLOCK_KIND_LABELS = {
+  text: 'docs.blocks.kinds.text',
+  code: 'docs.blocks.kinds.code',
+  raw: 'docs.blocks.kinds.raw',
+} as const
+
+export function groupLabelKey(group: string): string {
+  return (BLOCK_GROUPS as readonly string[]).includes(group)
+    ? `docs.blocks.groups.${group}`
+    : group
+}
+
+const COLORS = [
+  'primary',
+  'secondary',
+  'success',
+  'info',
+  'warning',
+  'error',
+  'neutral',
+]
+const TARGETS = ['_self', '_blank']
+
+function prop(
+  type: PlutoBlockPropType,
+  name: string,
+  extra: Partial<PlutoBlockPropDefinition> = {}
+): PlutoBlockPropDefinition {
+  return { type, label: `docs.blocks.props.${name}`, ...extra }
+}
+
+function options(values: string[]): PlutoBlockPropOption[] {
+  return values.map((value) => ({ value }))
+}
+
+function slot(
+  name: string,
+  content: PlutoBlockSlotContent,
+  accepts?: string[]
+): PlutoBlockSlotDefinition {
+  return {
+    label: `docs.blocks.slots.${name}`,
+    content,
+    ...(accepts ? { accepts } : {}),
+  }
+}
+
+function snippet(id: string): string {
+  return MDC_SNIPPETS.find((item) => item.id === id)!.text
+}
+
+function block(
+  name: string,
+  group: string,
+  icon: string,
+  extra: Partial<PlutoBlockDefinition> = {}
+): PlutoBlockDefinition {
+  return {
+    name,
+    label: `docs.blocks.${name}.label`,
+    description: `docs.blocks.${name}.description`,
+    icon,
+    group,
+    ...extra,
+  }
+}
+
+const calloutProps = {
+  icon: prop('icon', 'icon'),
+  to: prop('link', 'to', { advanced: true }),
+  target: prop('select', 'target', {
+    options: options(TARGETS),
+    advanced: true,
+  }),
+}
+
+const DEFINITIONS: PlutoBlockDefinition[] = [
+  block('note', 'callouts', 'i-lucide-info', {
+    props: { ...calloutProps },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('note'),
+  }),
+  block('tip', 'callouts', 'i-lucide-lightbulb', {
+    props: { ...calloutProps },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('tip'),
+  }),
+  block('warning', 'callouts', 'i-lucide-triangle-alert', {
+    props: { ...calloutProps },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('warning'),
+  }),
+  block('caution', 'callouts', 'i-lucide-octagon-alert', {
+    props: { ...calloutProps },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('caution'),
+  }),
+  block('callout', 'callouts', 'i-lucide-message-square-quote', {
+    props: {
+      icon: prop('icon', 'icon'),
+      color: prop('select', 'color', { options: options(COLORS) }),
+      to: prop('link', 'to', { advanced: true }),
+      target: prop('select', 'target', {
+        options: options(TARGETS),
+        advanced: true,
+      }),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('callout'),
+  }),
+  block('card', 'layout', 'i-lucide-square', {
+    props: {
+      title: prop('string', 'title'),
+      icon: prop('icon', 'icon'),
+      color: prop('select', 'color', { options: options(COLORS) }),
+      to: prop('link', 'to'),
+      target: prop('select', 'target', {
+        options: options(TARGETS),
+        advanced: true,
+      }),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert:
+      '::card\n---\ntitle: Title\nicon: i-lucide-box\n---\nText of the card.\n::',
+  }),
+  block('card-group', 'layout', 'i-lucide-layout-grid', {
+    slots: { default: slot('default', 'blocks', ['card']) },
+    insert: snippet('card-group'),
+  }),
+  block('steps', 'layout', 'i-lucide-list-ordered', {
+    props: {
+      level: prop('select', 'level', { options: options(['2', '3', '4']) }),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert: snippet('steps'),
+  }),
+  block('accordion', 'layout', 'i-lucide-chevrons-up-down', {
+    props: {
+      type: prop('select', 'accordionType', {
+        options: options(['single', 'multiple']),
+      }),
+    },
+    slots: { default: slot('default', 'blocks', ['accordion-item']) },
+    insert: snippet('accordion'),
+  }),
+  block('accordion-item', 'layout', 'i-lucide-chevron-down', {
+    props: {
+      label: prop('string', 'label'),
+      icon: prop('icon', 'icon'),
+      description: prop('string', 'description'),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert:
+      '::accordion-item{label="Question" icon="i-lucide-circle-help"}\nAnswer.\n::',
+  }),
+  block('tabs', 'layout', 'i-lucide-panel-top', {
+    props: { sync: prop('string', 'sync', { advanced: true }) },
+    slots: { default: slot('default', 'blocks', ['tabs-item']) },
+    insert: snippet('tabs'),
+  }),
+  block('tabs-item', 'layout', 'i-lucide-panel-top-open', {
+    props: {
+      label: prop('string', 'label'),
+      icon: prop('icon', 'icon'),
+      description: prop('string', 'description'),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert:
+      '::tabs-item{label="Tab" icon="i-lucide-file"}\nText of the tab.\n::',
+  }),
+  block('collapsible', 'layout', 'i-lucide-chevrons-down-up', {
+    props: {
+      name: prop('string', 'name'),
+      openText: prop('string', 'openText', { advanced: true }),
+      closeText: prop('string', 'closeText', { advanced: true }),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert: '::collapsible\nHidden text.\n::',
+  }),
+  block('field-group', 'layout', 'i-lucide-list-tree', {
+    slots: { default: slot('default', 'blocks', ['field']) },
+    insert: snippet('field-group'),
+  }),
+  block('field', 'layout', 'i-lucide-text-cursor-input', {
+    props: {
+      name: prop('string', 'name'),
+      type: prop('string', 'fieldType'),
+      required: prop('boolean', 'required'),
+      description: prop('string', 'description'),
+    },
+    slots: { default: slot('default', 'rich') },
+    insert:
+      '::field{name="name" type="string" required}\nText of the field.\n::',
+  }),
+  block('code-group', 'code', 'i-lucide-square-code', {
+    props: { sync: prop('string', 'sync', { advanced: true }) },
+    slots: { default: slot('default', 'blocks') },
+    insert: snippet('code-group'),
+  }),
+  block('code-collapse', 'code', 'i-lucide-fold-vertical', {
+    props: { name: prop('string', 'name') },
+    slots: { default: slot('default', 'blocks') },
+    insert: '::code-collapse\n```ts [file.ts]\nconst value = 1\n```\n::',
+  }),
+  // Inline components. A Markdown page uses them inside a text, so the palette does not list them.
+  block('badge', 'text', 'i-lucide-badge', {
+    hidden: true,
+    props: {
+      label: prop('string', 'label'),
+      color: prop('select', 'color', { options: options(COLORS) }),
+    },
+  }),
+  block('kbd', 'text', 'i-lucide-keyboard', {
+    hidden: true,
+    props: { value: prop('string', 'value') },
+  }),
+  block('icon', 'text', 'i-lucide-smile', {
+    hidden: true,
+    props: { name: prop('icon', 'name') },
+  }),
+  block('u-page-hero', 'landing', 'i-lucide-panel-top', {
+    props: {
+      headline: prop('string', 'headline'),
+      title: prop('string', 'title'),
+      description: prop('text', 'description'),
+      orientation: prop('select', 'orientation', {
+        options: options(['vertical', 'horizontal']),
+      }),
+      reverse: prop('boolean', 'reverse'),
+    },
+    slots: {
+      headline: slot('headline', 'inline'),
+      title: slot('title', 'inline'),
+      description: slot('description', 'rich'),
+      links: slot('links', 'blocks', ['u-button']),
+      default: slot('default', 'blocks'),
+    },
+    insert:
+      '::u-page-hero\n#title\nYour title\n\n#description\nA short text about the page.\n::',
+  }),
+  block('u-page-section', 'landing', 'i-lucide-layout-template', {
+    props: {
+      headline: prop('string', 'headline'),
+      icon: prop('icon', 'icon'),
+      title: prop('string', 'title'),
+      description: prop('text', 'description'),
+      orientation: prop('select', 'orientation', {
+        options: options(['vertical', 'horizontal']),
+      }),
+      reverse: prop('boolean', 'reverse'),
+    },
+    slots: {
+      headline: slot('headline', 'inline'),
+      title: slot('title', 'inline'),
+      description: slot('description', 'rich'),
+      features: slot('features', 'blocks', ['u-page-feature']),
+      default: slot('default', 'blocks'),
+    },
+    insert:
+      '::u-page-section\n#title\nYour title\n\n#description\nA short text about the section.\n::',
+  }),
+  block('u-page-feature', 'landing', 'i-lucide-sparkle', {
+    props: {
+      title: prop('string', 'title'),
+      description: prop('text', 'description'),
+      icon: prop('icon', 'icon'),
+      to: prop('link', 'to'),
+      orientation: prop('select', 'orientation', {
+        options: options(['horizontal', 'vertical']),
+      }),
+    },
+    slots: {
+      title: slot('title', 'inline'),
+      description: slot('description', 'rich'),
+    },
+    insert:
+      '::u-page-feature\n---\nicon: i-lucide-sparkle\n---\n#title\nFeature\n\n#description\nA short text about the feature.\n::',
+  }),
+  block('u-page-card', 'landing', 'i-lucide-square-stack', {
+    props: {
+      title: prop('string', 'title'),
+      description: prop('text', 'description'),
+      icon: prop('icon', 'icon'),
+      to: prop('link', 'to'),
+      spotlight: prop('boolean', 'spotlight'),
+      orientation: prop('select', 'orientation', {
+        options: options(['vertical', 'horizontal']),
+      }),
+    },
+    slots: { default: slot('default', 'blocks') },
+    insert:
+      '::u-page-card\n---\ntitle: Title\ndescription: A short text.\nicon: i-lucide-box\n---\n::',
+  }),
+  block('u-page-grid', 'landing', 'i-lucide-grid-3x3', {
+    slots: { default: slot('default', 'blocks', ['u-page-card']) },
+    insert:
+      '::u-page-grid\n  :::u-page-card\n  ---\n  title: Title\n  description: A short text.\n  ---\n  :::\n::',
+  }),
+  block('u-page-c-t-a', 'landing', 'i-lucide-megaphone', {
+    props: {
+      title: prop('string', 'title'),
+      description: prop('text', 'description'),
+      variant: prop('select', 'variant', {
+        options: options(['outline', 'solid', 'soft', 'subtle', 'naked']),
+      }),
+      orientation: prop('select', 'orientation', {
+        options: options(['vertical', 'horizontal']),
+      }),
+      reverse: prop('boolean', 'reverse'),
+    },
+    slots: {
+      links: slot('links', 'blocks', ['u-button']),
+      default: slot('default', 'blocks'),
+    },
+    insert:
+      '::u-page-c-t-a\n---\ntitle: Ready to start?\ndescription: A short text.\n---\n::',
+  }),
+  block('u-button', 'landing', 'i-lucide-mouse-pointer-click', {
+    props: {
+      // A Markdown page often writes the text as the default slot (`:::u-button` ... `Get started`).
+      label: prop('string', 'label', { slot: 'default' }),
+      to: prop('link', 'to'),
+      icon: prop('icon', 'icon'),
+      color: prop('select', 'color', { options: options(COLORS) }),
+      variant: prop('select', 'variant', {
+        options: options([
+          'solid',
+          'outline',
+          'soft',
+          'subtle',
+          'ghost',
+          'link',
+        ]),
+      }),
+      size: prop('select', 'size', {
+        options: options(['xs', 'sm', 'md', 'lg', 'xl']),
+      }),
+      target: prop('select', 'target', {
+        options: options(TARGETS),
+        advanced: true,
+      }),
+    },
+    insert: '::u-button{label="Button" to="/"}\n::',
+  }),
+]
+
+/** The presets by component name. */
+export const BLOCK_PRESETS: Readonly<Record<string, PlutoBlockDefinition>> =
+  Object.freeze(
+    Object.fromEntries(
+      DEFINITIONS.map((definition) => [definition.name, definition])
+    )
+  )
+
+/** The props that no preset lists, and that the panel keeps out of the main section. */
+export const HIDDEN_PROP_NAMES = ['ui', 'as'] as const

package/shared/utils/blocks/preview-marks.ts

@@ -0,0 +1,98 @@
+// Marks the blocks in the parsed body of the preview page, so a click in the
+// preview selects the block under the pointer, an inner block too. Pure: no
+// DOM, no Nuxt. The nodes are the MDC AST of `parseMarkdown`.
+
+import type { PlutoPreviewChild } from './preview-protocol'
+
+/** The attribute that holds the block id on an element of the preview. */
+export const PREVIEW_BLOCK_ATTRIBUTE = 'data-pluto-block'
+
+/** The part of an MDC node that the marks read and write. */
+export interface PlutoMarkNode {
+  type: string
+  tag?: string
+  props?: Record<string, unknown>
+  children?: PlutoMarkNode[]
+}
+
+/** `UPageSection` and `u-page-section` are the same component. */
+function normalize(name: string): string {
+  return name
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+}
+
+/**
+ * The elements where an inner block of a component can be: its direct
+ * children (the default slot) and the children of its `template` elements
+ * (the named slots), in source order. An inline component inside a paragraph
+ * is never here, so it cannot take the place of an inner block.
+ */
+function slotElements(node: PlutoMarkNode): PlutoMarkNode[] {
+  const elements: PlutoMarkNode[] = []
+  for (const child of node.children ?? []) {
+    if (child.type !== 'element') {
+      continue
+    }
+    if (child.tag === 'template') {
+      elements.push(
+        ...(child.children ?? []).filter((inner) => inner.type === 'element')
+      )
+    } else {
+      elements.push(child)
+    }
+  }
+  return elements
+}
+
+/**
+ * Puts the ids of `children` on the matching component elements under `node`.
+ * The children are in source order over all slots, so the match goes in
+ * order, by component name. An element with another name (a paragraph, a
+ * list) is skipped. It changes the props of the matched elements in place,
+ * so call it on a body from a new parse. Returns the number of marked
+ * elements, at all levels.
+ */
+export function markPreviewChildren(
+  node: PlutoMarkNode,
+  children: PlutoPreviewChild[]
+): number {
+  let marked = 0
+  let next = 0
+  for (const element of slotElements(node)) {
+    const child = children[next]
+    if (!child) {
+      break
+    }
+    if (element.tag && normalize(element.tag) === normalize(child.name)) {
+      element.props = { ...element.props, [PREVIEW_BLOCK_ATTRIBUTE]: child.id }
+      marked += 1 + markPreviewChildren(element, child.children ?? [])
+      next++
+    }
+  }
+  return marked
+}
+
+/** The number of children in a tree, at all levels. */
+export function countPreviewChildren(
+  children: PlutoPreviewChild[] | undefined
+): number {
+  return (children ?? []).reduce(
+    (total, child) => total + 1 + countPreviewChildren(child.children),
+    0
+  )
+}
+
+/** The parent id of each child in a tree. A child of a top-level block has that block as parent. */
+export function previewParents(
+  blockId: string,
+  children: PlutoPreviewChild[] | undefined,
+  parents = new Map<string, string>()
+): Map<string, string> {
+  for (const child of children ?? []) {
+    parents.set(child.id, blockId)
+    previewParents(child.id, child.children, parents)
+  }
+  return parents
+}

package/shared/utils/blocks/preview-protocol.ts

@@ -0,0 +1,195 @@
+// The messages between the editor and the preview frame (`/_pluto/preview`).
+// Both sides check the origin and the shape of each message. Types and
+// validators only: no DOM, no Nuxt.
+
+export const PREVIEW_PATH = '/_pluto/preview'
+
+/** The version of the protocol. Change it when a message changes in a way that breaks the other side. */
+export const PREVIEW_PROTOCOL_VERSION = 1
+
+/** Every message has this `source`, so the frame ignores the messages of other scripts. */
+export const PREVIEW_SOURCE = 'pluto-preview'
+
+/** An inner component of a block, so the preview can mark it and a click can select it. */
+export interface PlutoPreviewChild {
+  id: string
+  /** The component name, as in the Markdown (`card`, `u-page-feature`). */
+  name: string
+  /** The label for the outline in the preview. */
+  label?: string
+  /** The inner components of this component, in source order over all slots. */
+  children?: PlutoPreviewChild[]
+}
+
+export interface PlutoPreviewBlock {
+  id: string
+  markdown: string
+  /** `false` shows a placeholder card instead of the block. */
+  preview?: boolean
+  /** The label for the placeholder card and the outline. */
+  label?: string
+  /** The inner components of a component block, in source order over all slots. */
+  children?: PlutoPreviewChild[]
+}
+
+interface Envelope<T extends string> {
+  source: typeof PREVIEW_SOURCE
+  version: typeof PREVIEW_PROTOCOL_VERSION
+  type: T
+}
+
+// The editor to the frame
+
+export interface PlutoPreviewRender extends Envelope<'render'> {
+  frontmatter: Record<string, unknown>
+  blocks: PlutoPreviewBlock[]
+  selectedId?: string | null
+}
+
+export interface PlutoPreviewSelect extends Envelope<'select'> {
+  /** `null` clears the selection. */
+  id: string | null
+}
+
+export interface PlutoPreviewScrollTo extends Envelope<'scroll-to'> {
+  id: string
+}
+
+export type PlutoPreviewToFrame =
+  PlutoPreviewRender | PlutoPreviewSelect | PlutoPreviewScrollTo
+
+// The frame to the editor
+
+export type PlutoPreviewReady = Envelope<'ready'>
+
+export interface PlutoPreviewHover extends Envelope<'hover'> {
+  id: string | null
+}
+
+export interface PlutoPreviewError extends Envelope<'error'> {
+  /** The block that failed, or none for an error of the whole page. */
+  id?: string
+  message: string
+}
+
+export type PlutoPreviewFromFrame =
+  PlutoPreviewReady | PlutoPreviewSelect | PlutoPreviewHover | PlutoPreviewError
+
+export type PlutoPreviewMessage = PlutoPreviewToFrame | PlutoPreviewFromFrame
+
+export type PlutoPreviewDirection = 'to-frame' | 'from-frame'
+
+export function previewMessage<T extends PlutoPreviewMessage['type']>(
+  type: T,
+  body: Omit<Extract<PlutoPreviewMessage, { type: T }>, keyof Envelope<T>>
+): Extract<PlutoPreviewMessage, { type: T }> {
+  return {
+    source: PREVIEW_SOURCE,
+    version: PREVIEW_PROTOCOL_VERSION,
+    type,
+    ...body,
+  } as Extract<PlutoPreviewMessage, { type: T }>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === 'string'
+}
+
+// A real page nests a few levels. The limit stops a message that nests without end.
+const MAX_CHILD_DEPTH = 16
+
+function isChildList(
+  value: unknown,
+  depth: number
+): value is PlutoPreviewChild[] {
+  return (
+    Array.isArray(value) &&
+    depth <= MAX_CHILD_DEPTH &&
+    value.every(
+      (child) =>
+        isRecord(child) &&
+        typeof child.id === 'string' &&
+        typeof child.name === 'string' &&
+        (child.label === undefined || typeof child.label === 'string') &&
+        (child.children === undefined || isChildList(child.children, depth + 1))
+    )
+  )
+}
+
+function isBlock(value: unknown): value is PlutoPreviewBlock {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.markdown === 'string' &&
+    (value.preview === undefined || typeof value.preview === 'boolean') &&
+    (value.label === undefined || typeof value.label === 'string') &&
+    (value.children === undefined || isChildList(value.children, 1))
+  )
+}
+
+const TO_FRAME = new Set(['render', 'select', 'scroll-to'])
+const FROM_FRAME = new Set(['ready', 'select', 'hover', 'error'])
+
+/**
+ * Checks the shape of a message that arrives from `postMessage`. It returns
+ * the typed message, or `undefined` for anything else: wrong source, wrong
+ * version, wrong direction, or a wrong field.
+ */
+export function parsePreviewMessage(
+  data: unknown,
+  direction: PlutoPreviewDirection
+): PlutoPreviewMessage | undefined {
+  if (
+    !isRecord(data) ||
+    data.source !== PREVIEW_SOURCE ||
+    data.version !== PREVIEW_PROTOCOL_VERSION ||
+    typeof data.type !== 'string'
+  ) {
+    return undefined
+  }
+  if (!(direction === 'to-frame' ? TO_FRAME : FROM_FRAME).has(data.type)) {
+    return undefined
+  }
+  switch (data.type) {
+    case 'render':
+      return isRecord(data.frontmatter) &&
+        Array.isArray(data.blocks) &&
+        data.blocks.every(isBlock) &&
+        (data.selectedId === undefined || isNullableString(data.selectedId))
+        ? (data as unknown as PlutoPreviewRender)
+        : undefined
+    case 'select':
+    case 'hover':
+      return isNullableString(data.id) &&
+        (data.type === 'hover' ||
+          direction === 'to-frame' ||
+          typeof data.id === 'string')
+        ? (data as unknown as PlutoPreviewSelect)
+        : undefined
+    case 'scroll-to':
+      return typeof data.id === 'string'
+        ? (data as unknown as PlutoPreviewScrollTo)
+        : undefined
+    case 'ready':
+      return data as unknown as PlutoPreviewReady
+    case 'error':
+      return typeof data.message === 'string' &&
+        (data.id === undefined || typeof data.id === 'string')
+        ? (data as unknown as PlutoPreviewError)
+        : undefined
+    default:
+      return undefined
+  }
+}
+
+/** True when the origin of a message is the expected one. The preview is same-origin, so `expected` is `location.origin`. */
+export function isTrustedPreviewOrigin(
+  origin: string,
+  expected: string
+): boolean {
+  return origin !== '' && origin !== 'null' && origin === expected
+}