@plutocms/docs 0.0.0-stage → 0.16.0

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

@@ -0,0 +1,232 @@
+<script setup lang="ts">
+import type { PlutoPreviewChild } from '../../../../../shared/utils/blocks/preview-protocol'
+import {
+  previewSelectionId,
+  toPreviewBlocks,
+} from '../../../../../shared/utils/blocks/editor'
+// The live preview of the page: an iframe of `/_pluto/preview` on the same
+// origin. This component sends the blocks to the frame (after 150 ms of
+// quiet), and tells the editor when a block is clicked or hovered in the frame.
+// Both sides check the origin and the shape of every message.
+import {
+  isTrustedPreviewOrigin,
+  parsePreviewMessage,
+  PREVIEW_PATH,
+  previewMessage,
+} from '../../../../../shared/utils/blocks/preview-protocol'
+
+const props = defineProps<{
+  frontmatter: Record<string, unknown>
+}>()
+
+const editor = usePlutoBlockEditor()
+const { t, tx } = usePlutoI18n()
+const router = useRouter()
+
+const DEBOUNCE_MS = 150
+const LOAD_TIMEOUT_MS = 12000
+
+const frame = useTemplateRef<HTMLIFrameElement>('frame')
+const ready = ref(false)
+const timedOut = ref(false)
+const frameKey = ref(0)
+const frameError = ref<string | null>(null)
+
+const src = computed(() => router.resolve(PREVIEW_PATH).href)
+// The preview marks the top-level blocks and their inner components. So the selection it shows
+// is the deepest component on the path of the selected block (a text inside a card shows the card).
+const shownId = computed(() =>
+  previewSelectionId(editor.doc.value, editor.selectedId.value)
+)
+const blocks = computed(() =>
+  toPreviewBlocks(editor.doc.value.blocks, editor.sources.value)
+)
+
+function send(message: ReturnType<typeof previewMessage>) {
+  frame.value?.contentWindow?.postMessage(message, window.location.origin)
+}
+
+/** The inner components with a readable label. */
+function translateChildren(
+  children: PlutoPreviewChild[] | undefined
+): PlutoPreviewChild[] | undefined {
+  return children?.map((child) => ({
+    ...child,
+    label: child.label ? tx(child.label) : '',
+    children: translateChildren(child.children),
+  }))
+}
+
+/** The blocks with a readable label: the label of a component is an i18n key or a plain text. */
+function messageBlocks() {
+  return blocks.value.map((block) => {
+    const source = editor.doc.value.blocks.find(
+      (candidate) => candidate.id === block.id
+    )
+    return {
+      ...block,
+      label: block.label
+        ? tx(block.label)
+        : source
+          ? tx(editor.describe(source).label)
+          : '',
+      ...(block.children
+        ? { children: translateChildren(block.children) }
+        : {}),
+    }
+  })
+}
+
+function sendRender() {
+  // A nested value of the form is a reactive proxy, and `postMessage` cannot clone a proxy.
+  // The front matter is YAML data, so a JSON copy is a plain copy.
+  const frontmatter = JSON.parse(JSON.stringify(props.frontmatter)) as Record<
+    string,
+    unknown
+  >
+  send(
+    previewMessage('render', {
+      frontmatter,
+      blocks: messageBlocks(),
+      selectedId: shownId.value,
+    })
+  )
+}
+
+let timer: ReturnType<typeof setTimeout> | undefined
+function scheduleRender() {
+  clearTimeout(timer)
+  timer = setTimeout(() => {
+    if (ready.value) {
+      sendRender()
+    }
+  }, DEBOUNCE_MS)
+}
+
+watch([blocks, () => props.frontmatter], scheduleRender, { deep: false })
+
+// The selection comes from the outline or the panel: draw it and scroll to it.
+watch(shownId, (id) => {
+  if (!ready.value) {
+    return
+  }
+  send(previewMessage('select', { id }))
+  if (id && editor.selection.value?.source === 'ui') {
+    send(previewMessage('scroll-to', { id }))
+  }
+})
+
+function onMessage(event: MessageEvent) {
+  if (
+    event.source !== frame.value?.contentWindow ||
+    !isTrustedPreviewOrigin(event.origin, window.location.origin)
+  ) {
+    return
+  }
+  const message = parsePreviewMessage(event.data, 'from-frame')
+  if (!message) {
+    return
+  }
+  switch (message.type) {
+    case 'ready':
+      ready.value = true
+      timedOut.value = false
+      frameError.value = null
+      // The first render goes at once.
+      sendRender()
+      break
+    case 'select':
+      editor.select(message.id, 'preview')
+      break
+    case 'hover':
+      editor.hoverId.value = message.id
+      break
+    case 'error':
+      frameError.value = message.message
+      break
+  }
+}
+
+let loadTimer: ReturnType<typeof setTimeout> | undefined
+function watchLoad() {
+  clearTimeout(loadTimer)
+  ready.value = false
+  timedOut.value = false
+  loadTimer = setTimeout(() => {
+    if (!ready.value) {
+      timedOut.value = true
+    }
+  }, LOAD_TIMEOUT_MS)
+}
+
+function reload() {
+  frameKey.value++
+  watchLoad()
+}
+
+onMounted(() => {
+  window.addEventListener('message', onMessage)
+  watchLoad()
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('message', onMessage)
+  clearTimeout(timer)
+  clearTimeout(loadTimer)
+})
+
+defineExpose({ reload })
+</script>
+
+<template>
+  <div class="relative size-full min-h-0 bg-muted">
+    <iframe
+      ref="frame"
+      :key="frameKey"
+      :src="src"
+      :title="t('docs.editor.previewTitle')"
+      class="size-full border-0 bg-default"
+      loading="eager"
+    />
+
+    <!--
+      While the preview loads: the shape of a page (core's canvas skeleton) and a small status
+      pill at the bottom, so the frame does not flash empty.
+    -->
+    <div
+      v-if="!ready && !timedOut"
+      class="pointer-events-none absolute inset-0 flex flex-col bg-default"
+      role="status"
+    >
+      <PlutoSkeletonCanvas />
+      <div class="absolute inset-x-0 bottom-6 flex justify-center">
+        <div
+          class="flex items-center gap-2 rounded-full bg-elevated px-3.5 py-1.5 text-xs font-medium text-muted shadow-sm ring ring-default"
+        >
+          <UIcon name="i-lucide-loader-circle" class="size-3.5 animate-spin" />
+          {{ t('docs.editor.previewLoading') }}
+        </div>
+      </div>
+    </div>
+
+    <div
+      v-if="timedOut"
+      class="absolute inset-0 flex items-center justify-center bg-default p-6"
+    >
+      <UEmpty
+        :title="t('docs.editor.previewFailedTitle')"
+        :description="t('docs.editor.previewFailed')"
+        :actions="[
+          {
+            label: t('docs.editor.previewRetry'),
+            icon: 'i-lucide-refresh-cw',
+            color: 'neutral',
+            variant: 'outline',
+            onClick: reload,
+          },
+        ]"
+        icon="i-lucide-triangle-alert"
+      />
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,269 @@
+<script setup lang="ts">
+// One setting of a component: a field with the right control for the type of
+// the prop (text, long text, switch, number, choice, icon, color, link). A
+// prop with an object or a list shows as YAML. An empty value removes the prop,
+// so the Markdown stays short.
+import type { PlutoBlockPropDefinition } from '../../../../../shared/utils/blocks/types'
+import { parse, stringify } from 'yaml'
+import { humanizeName } from '../../../../../shared/utils/blocks/registry'
+
+const props = defineProps<{
+  /** The name of the prop in the Markdown. */
+  name: string
+  definition: PlutoBlockPropDefinition
+  modelValue: unknown
+  disabled?: boolean
+}>()
+
+const emit = defineEmits<{
+  /** `undefined` removes the prop. */
+  'update:modelValue': [value: unknown]
+}>()
+
+const { t, tx } = usePlutoI18n()
+
+const DEFAULT = '__default__'
+type ChipColor =
+  'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
+const COLOR_CHIPS: Record<string, ChipColor> = {
+  primary: 'primary',
+  secondary: 'secondary',
+  success: 'success',
+  info: 'info',
+  warning: 'warning',
+  error: 'error',
+  neutral: 'neutral',
+}
+
+const label = computed(() =>
+  props.definition.label ? tx(props.definition.label) : humanizeName(props.name)
+)
+const description = computed(() =>
+  props.definition.description ? tx(props.definition.description) : undefined
+)
+
+const isStructured = computed(
+  () => typeof props.modelValue === 'object' && props.modelValue !== null
+)
+const type = computed(() =>
+  isStructured.value ? 'yaml' : props.definition.type
+)
+
+const text = computed(() =>
+  props.modelValue === undefined || props.modelValue === null
+    ? ''
+    : String(props.modelValue)
+)
+
+function setText(value: string | undefined) {
+  emit(
+    'update:modelValue',
+    value === undefined || value === '' ? undefined : value
+  )
+}
+
+// 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) {
+  // 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(() => {
+  const value =
+    typeof props.modelValue === 'number'
+      ? props.modelValue
+      : Number(props.modelValue)
+  return props.modelValue === undefined || Number.isNaN(value)
+    ? undefined
+    : value
+})
+
+const selectItems = computed(() => {
+  const items = (props.definition.options ?? []).map((option) => {
+    const value = typeof option === 'string' ? option : option.value
+    const text = typeof option === 'string' ? option : option.label
+    return { value, label: text ? tx(text) : value }
+  })
+  const current = text.value
+  if (current && !items.some((item) => item.value === current)) {
+    items.push({ value: current, label: current })
+  }
+  // "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(() =>
+  selectItems.value.map((item) =>
+    COLOR_CHIPS[item.value]
+      ? { ...item, chip: { color: COLOR_CHIPS[item.value] } }
+      : item
+  )
+)
+
+function setSelect(value: string) {
+  emit('update:modelValue', value === DEFAULT ? undefined : value)
+}
+
+// YAML for an object or a list. The text applies when the box loses the focus and the YAML is valid.
+const yamlDraft = ref(
+  isStructured.value ? stringify(props.modelValue).trimEnd() : ''
+)
+const yamlError = ref<string | null>(null)
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (typeof value === 'object' && value !== null) {
+      try {
+        if (JSON.stringify(parse(yamlDraft.value)) === JSON.stringify(value)) {
+          return
+        }
+      } catch {
+        return
+      }
+      yamlDraft.value = stringify(value).trimEnd()
+    }
+  }
+)
+
+function applyYaml() {
+  try {
+    const value =
+      yamlDraft.value.trim() === '' ? undefined : parse(yamlDraft.value)
+    yamlError.value = null
+    emit('update:modelValue', value)
+  } catch (error) {
+    yamlError.value =
+      error instanceof Error ? error.message.split('\n')[0]! : String(error)
+  }
+}
+
+const iconPreview = computed(() =>
+  text.value.startsWith('i-') || text.value.includes(':')
+    ? text.value
+    : undefined
+)
+</script>
+
+<template>
+  <UFormField
+    :label="label"
+    :description="description"
+    :error="yamlError ?? undefined"
+    :help="type === 'icon' ? t('docs.editor.iconHelp') : undefined"
+    class="w-full"
+  >
+    <USwitch
+      v-if="type === 'boolean'"
+      :model-value="switchOn"
+      :disabled="disabled"
+      :aria-label="label"
+      @update:model-value="setBoolean($event)"
+    />
+
+    <UInputNumber
+      v-else-if="type === 'number'"
+      :model-value="numberValue"
+      :placeholder="defaultText"
+      :disabled="disabled"
+      class="w-full"
+      @update:model-value="emit('update:modelValue', $event ?? undefined)"
+    />
+
+    <USelect
+      v-else-if="type === 'select'"
+      :model-value="text || DEFAULT"
+      :items="selectItems"
+      :disabled="disabled"
+      value-key="value"
+      class="w-full"
+      @update:model-value="setSelect($event as string)"
+    />
+
+    <USelect
+      v-else-if="type === 'color'"
+      :model-value="text || DEFAULT"
+      :items="colorItems"
+      :disabled="disabled"
+      value-key="value"
+      class="w-full"
+      @update:model-value="setSelect($event as string)"
+    />
+
+    <UTextarea
+      v-else-if="type === 'text'"
+      :model-value="text"
+      :placeholder="defaultText"
+      :disabled="disabled"
+      :rows="2"
+      class="w-full"
+      autoresize
+      @update:model-value="setText($event as string)"
+    />
+
+    <UTextarea
+      v-else-if="type === 'yaml'"
+      v-model="yamlDraft"
+      :disabled="disabled"
+      :rows="4"
+      :ui="{ base: 'font-mono text-xs' }"
+      class="w-full"
+      spellcheck="false"
+      autoresize
+      @blur="applyYaml"
+    />
+
+    <UInput
+      v-else-if="type === 'icon'"
+      :model-value="text"
+      :disabled="disabled"
+      :icon="iconPreview"
+      :placeholder="defaultText ?? 'i-lucide-rocket'"
+      spellcheck="false"
+      autocomplete="off"
+      class="w-full"
+      @update:model-value="setText($event as string)"
+    />
+
+    <UInput
+      v-else-if="type === 'link'"
+      :model-value="text"
+      :disabled="disabled"
+      :placeholder="defaultText ?? t('docs.editor.linkPlaceholder')"
+      icon="i-lucide-link"
+      autocomplete="off"
+      class="w-full"
+      @update:model-value="setText($event as string)"
+    />
+
+    <UInput
+      v-else
+      :model-value="text"
+      :placeholder="defaultText"
+      :disabled="disabled"
+      class="w-full"
+      @update:model-value="setText($event as string)"
+    />
+  </UFormField>
+</template>

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

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+// A Markdown box for one block that the visual editor does not edit as text:
+// a table, HTML, a footnote, or any block that the author wants to edit as
+// Markdown. `live` writes each key press (a Markdown block). Without it, the
+// box has an Apply button, because a block of another kind is parsed again
+// when the text changes.
+const props = defineProps<{
+  modelValue: string
+  disabled?: boolean
+  label: string
+  live?: boolean
+  rows?: number
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+const { t } = usePlutoI18n()
+
+const draft = ref(props.modelValue)
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (props.live || value !== draft.value) {
+      draft.value = value
+    }
+  }
+)
+
+function update(value: string) {
+  draft.value = value
+  if (props.live) {
+    emit('update:modelValue', value)
+  }
+}
+
+const changed = computed(() => draft.value !== props.modelValue)
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <PlutoMarkdownSource
+      :model-value="draft"
+      :disabled="disabled"
+      :aria-label="label"
+      :rows="rows ?? 8"
+      @update:model-value="update"
+    />
+    <div v-if="!live" class="flex justify-end gap-2">
+      <UButton
+        :label="t('docs.editor.applyMarkdown')"
+        :disabled="disabled || !changed"
+        size="xs"
+        color="primary"
+        icon="i-lucide-check"
+        @click="emit('update:modelValue', draft)"
+      />
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+// A small rich text editor for one Text block, or for one slot of a
+// component. It is the core Nuxt UI editor (Tiptap) with the toolbar of the
+// Pluto Markdown editor (`usePlutoMarkdownToolbar`). The Tiptap history is off:
+// the block editor has one undo stack for the whole page. The value is
+// Markdown. The editor emits only after the author types, so opening a block
+// never rewrites it.
+const props = defineProps<{
+  modelValue: string
+  disabled?: boolean
+  placeholder?: string
+  label: string
+  /** A shorter box, for a slot such as the text of a note. */
+  compact?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+const { t } = usePlutoI18n()
+
+// The editor writes the Markdown in its own form when it loads a text (and when the text changes
+// from outside, for example on Undo). That is not an edit. Only an update that follows an action
+// of the author (a key, a click, a paste, a drop) goes up, so opening a block never changes it.
+const touched = ref(false)
+let echo = false
+
+watch(
+  () => props.modelValue,
+  () => {
+    echo = true
+    nextTick(() => {
+      echo = false
+    })
+  }
+)
+
+function onUpdate(value: string) {
+  if (touched.value && !echo && value !== props.modelValue) {
+    emit('update:modelValue', value)
+  }
+}
+
+// The first group of the shared toolbar is Undo and Redo. The page has its own.
+const shared = usePlutoMarkdownToolbar({ link: true })
+const items = computed(() => shared.value.slice(1))
+</script>
+
+<template>
+  <!-- The editor root is a bordered box. A click anywhere in the box puts the cursor in the text. -->
+  <div
+    class="w-full"
+    @focusin="touched = true"
+    @keydown.capture="touched = true"
+    @pointerdown.capture="touched = true"
+    @paste.capture="touched = true"
+    @drop.capture="touched = true"
+  >
+    <UEditor
+      v-slot="{ editor }"
+      :model-value="modelValue"
+      :editable="!disabled"
+      :placeholder="placeholder ?? t('docs.editor.textPlaceholder')"
+      :starter-kit="{ undoRedo: false }"
+      :image="false"
+      :mention="false"
+      :ui="{
+        root: 'w-full',
+        content: compact ? 'min-h-24 cursor-text' : 'min-h-48 cursor-text',
+        base: compact
+          ? 'min-h-24 px-3 py-2 sm:px-3'
+          : 'min-h-48 px-3 py-2 sm:px-3',
+      }"
+      :aria-label="label"
+      content-type="markdown"
+      class="w-full rounded-md border border-default bg-default"
+      @update:model-value="onUpdate($event as string)"
+    >
+      <UEditorToolbar
+        :editor="editor"
+        :items="items"
+        :aria-label="t('pluto.github.editor.toolbar')"
+        class="sticky top-0 z-10 flex-wrap rounded-t-md border-b border-default bg-default px-1.5 py-1"
+      >
+        <template #link>
+          <PlutoGithubEditorLink :editor="editor" />
+        </template>
+      </UEditorToolbar>
+    </UEditor>
+  </div>
+</template>