@plutocms/docs 0.0.0-stage → 0.16.0

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

@@ -0,0 +1,80 @@
+<script setup lang="ts">
+// One block in the preview page, inside its own error boundary. A component
+// that throws (it needs data that the preview has no, for example) shows a
+// small card in place of the block, and the other blocks keep working.
+// `preview: false` in the block definition shows the same card, with a note.
+import type { MDCRoot } from '@nuxtjs/mdc'
+
+const props = defineProps<{
+  id: string
+  /** The parsed body, or `undefined` for a block that the preview does not render. */
+  body?: MDCRoot
+  /** The name of the block, for the card. */
+  label: string
+  /** A parse error of this block. */
+  error?: string
+}>()
+
+const emit = defineEmits<{
+  error: [id: string, message: string]
+}>()
+
+const { t } = usePlutoI18n()
+
+const failed = ref<string | null>(null)
+const value = computed(() => (props.body ? { body: props.body } : undefined))
+
+// The render options of the site page (`usePlutoPreviewRender` in the site's PlutoContentPreview).
+const renderOptions = inject(plutoPreviewRenderKey, {})
+const prose = computed(() => toValue(renderOptions).prose ?? true)
+const components = computed(() => toValue(renderOptions).components ?? {})
+
+// A new body gets a new chance to render.
+watch(
+  () => props.body,
+  () => {
+    failed.value = null
+  }
+)
+
+onErrorCaptured((error) => {
+  failed.value = error instanceof Error ? error.message : String(error)
+  emit('error', props.id, failed.value)
+  // Stop the error here, so the other blocks stay on screen.
+  return false
+})
+
+const note = computed(() => {
+  if (props.error) {
+    return t('docs.preview.parseError')
+  }
+  if (failed.value) {
+    return t('docs.preview.blockError')
+  }
+  return t('docs.preview.notShown')
+})
+</script>
+
+<template>
+  <ContentRenderer
+    v-if="value && !failed && !error"
+    :value="value"
+    :tag="false as unknown as string"
+    :prose="prose"
+    :components="components"
+  />
+
+  <div
+    v-else
+    :data-pluto-block="id"
+    class="my-4 flex items-center gap-3 rounded-lg border border-dashed border-default bg-elevated/50 px-4 py-3 text-sm text-muted"
+  >
+    <UIcon name="i-lucide-eye-off" class="size-5 shrink-0" />
+    <div class="min-w-0">
+      <p class="font-medium text-default">
+        {{ label }}
+      </p>
+      <p>{{ note }}</p>
+    </div>
+  </div>
+</template>

package/app/components/Pluto/Docs/PlutoFieldMdc.vue

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+// The `mdc` widget of the docs layer. It edits the Markdown (MDC) body
+// of a page in one of two modes:
+//
+// - Visual: the block editor. A live preview in the middle, the block list at
+//   the left and the controls of the selected block at the right. It needs the
+//   'canvas' form layout (the docs type uses it) and loads on demand, so
+//   Tiptap and the remark parser stay out of the other admin pages.
+// - Markdown: `PlutoMarkdownCodeEditor` of core (CodeMirror: the author sees all the MDC,
+//   with the format shown as they type, quick formats and an Insert menu). In a canvas form the live preview shows at
+//   its side, and a click on a block in the preview goes to that block in the
+//   Markdown (PlutoBlockMarkdownSplit, loaded on demand too).
+//
+// The first mode is the `editor` option of the field (`visual` or `source`). A
+// cookie keeps the last choice of the author. The model value is the Markdown
+// text, as it is. The widget contract: props `field`, `modelValue`, `disabled`,
+// and the `update:modelValue` event. The layer registers it as the widget `mdc`.
+import { defineAsyncComponent } from 'vue'
+import PlutoMdcInsertMenu from './PlutoMdcInsertMenu.vue'
+
+const props = defineProps<{
+  field: PlutoTextField
+  modelValue: unknown
+  disabled?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+// The block editor and the Markdown split load on demand. The skeleton shows while they load.
+const loadingComponent = () =>
+  h('div', { class: 'flex h-full flex-col gap-3 p-6' }, [
+    h(resolveComponent('USkeleton'), { class: 'h-8 w-1/3' }),
+    h(resolveComponent('USkeleton'), { class: 'h-64 w-full' }),
+  ])
+const PlutoBlockEditor = defineAsyncComponent({
+  loader: () => import('./Blocks/PlutoBlockEditor.vue'),
+  loadingComponent,
+  delay: 120,
+})
+const PlutoBlockMarkdownSplit = defineAsyncComponent({
+  loader: () => import('./Blocks/PlutoBlockMarkdownSplit.vue'),
+  loadingComponent,
+  delay: 120,
+})
+
+const { t } = usePlutoI18n()
+const form = usePlutoContentForm()
+
+const value = computed(() =>
+  typeof props.modelValue === 'string' ? props.modelValue : ''
+)
+
+// Visual needs the canvas layout: the panels live in the form.
+const canVisual = computed(() => Boolean(form?.canvas.value))
+
+type Mode = 'visual' | 'markdown'
+const saved = useCookie<Mode | null>('pluto-mdc-editor-mode', {
+  default: () => null,
+  maxAge: 60 * 60 * 24 * 365,
+  sameSite: 'lax',
+})
+const mode = ref<Mode>(
+  canVisual.value
+    ? (saved.value ?? (props.field.editor === 'source' ? 'markdown' : 'visual'))
+    : 'markdown'
+)
+
+function setMode(next: Mode) {
+  mode.value = next
+  saved.value = next
+}
+</script>
+
+<template>
+  <PlutoBlockEditor
+    v-if="mode === 'visual' && canVisual"
+    :model-value="value"
+    :disabled="disabled"
+    :mode="mode"
+    @update:model-value="emit('update:modelValue', $event)"
+    @update:mode="setMode"
+  />
+
+  <PlutoBlockMarkdownSplit
+    v-else-if="canVisual"
+    :model-value="value"
+    :disabled="disabled"
+    :mode="mode"
+    :placeholder="field.placeholder ?? t('docs.mdc.placeholder')"
+    :label="field.label"
+    @update:model-value="emit('update:modelValue', $event)"
+    @update:mode="setMode"
+  />
+
+  <!-- A form without the canvas layout: the Markdown only, with no preview and no Visual mode. -->
+  <UFormField
+    v-else
+    :label="field.label"
+    :description="field.description"
+    :required="field.required"
+  >
+    <!-- The core editor (CodeMirror) loads on demand, so the Visual mode does not load it. -->
+    <LazyPlutoMarkdownCodeEditor
+      :model-value="value"
+      :disabled="disabled"
+      :placeholder="field.placeholder ?? t('docs.mdc.placeholder')"
+      :aria-label="field.label"
+      @update:model-value="emit('update:modelValue', $event)"
+    >
+      <template #toolbar="{ insert }">
+        <PlutoMdcInsertMenu :insert="insert" :disabled="disabled" />
+      </template>
+    </LazyPlutoMarkdownCodeEditor>
+  </UFormField>
+</template>

package/app/components/Pluto/Docs/PlutoMdcInsertMenu.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// The Insert menu of the Markdown editor: one item for each MDC snippet. The
+// `insert` function is the one of the `toolbar` slot of PlutoMarkdownSource.
+const props = defineProps<{
+  insert: (text: string, options?: { block?: boolean }) => void
+  disabled?: boolean
+}>()
+
+const { t } = usePlutoI18n()
+
+const items = computed(() =>
+  MDC_SNIPPETS.map((snippet) => ({
+    label: t(snippet.label),
+    icon: snippet.icon,
+    onSelect: () => props.insert(snippet.text, { block: snippet.block }),
+  }))
+)
+</script>
+
+<template>
+  <UDropdownMenu
+    :items="items"
+    :content="{ align: 'start' }"
+    :disabled="disabled"
+  >
+    <UButton
+      :label="t('docs.mdc.insert')"
+      :disabled="disabled"
+      color="neutral"
+      variant="ghost"
+      size="xs"
+      icon="i-lucide-plus"
+      trailing-icon="i-lucide-chevron-down"
+    />
+  </UDropdownMenu>
+</template>

package/app/components/PlutoContentPreview.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+// The frame around the blocks in the preview page (`/_pluto/preview`). The
+// default is a generic docs-like page: a header with the title and the
+// description, and the blocks in the body. A site that wants the real layout
+// of its pages overrides this component. Put a component with the same name in
+// the app (`app/components/PlutoContentPreview.vue`) and render the default
+// slot where the blocks go. The slot must hold the blocks directly: no
+// wrapper element, because the prose styles read the first and last child.
+//
+// `frontmatter` is the front matter of the page being edited: the title, the
+// description and the other fields of the form. The preview never fetches.
+defineProps<{
+  frontmatter: Record<string, unknown>
+}>()
+</script>
+
+<template>
+  <UContainer>
+    <UPage>
+      <UPageHeader
+        v-if="typeof frontmatter.title === 'string' && frontmatter.title"
+        :title="frontmatter.title"
+        :description="
+          typeof frontmatter.description === 'string'
+            ? frontmatter.description
+            : undefined
+        "
+      />
+
+      <UPageBody>
+        <slot />
+      </UPageBody>
+    </UPage>
+  </UContainer>
+</template>