@vespercms/admin 0.0.0-stage → 0.1.0-next.1

package/src/body/catalog.ts

@@ -0,0 +1,198 @@
+import {
+  humanize,
+  jsxClosing,
+  jsxOpening,
+  markdocClosing,
+  markdocOpening,
+  type BodyFormat,
+  type FieldModel,
+  type Manifest,
+} from '@vespercms/core';
+
+/*
+ * What the writing view knows how to show as a block (spec §6.5.1, §6.5.2):
+ * the site's Markdoc tags, Markdoc's own `partial` and `if`, and declared
+ * MDX components. Anything else is a protected source chip.
+ */
+
+export type BlockShape = 'container' | 'card' | 'inline';
+
+export type BlockKind = {
+  /** `markdoc:callout`, `mdx:Callout`. */
+  key: string;
+  syntax: 'markdoc' | 'mdx';
+  name: string;
+  label: string;
+  summary?: string;
+  description?: string;
+  /** How a new one is inserted at a block position, or null when it can only go inline. */
+  block: Exclude<BlockShape, 'inline'> | null;
+  /** Whether it can go inside a line of text. */
+  inline: boolean;
+  /** Written without content (`/%}`, `/>`). */
+  selfClosing: boolean;
+  /** Markdoc's allowed child node types (containers); absent means anything. */
+  children?: string[];
+  /** The settings form. */
+  fields: FieldModel[];
+  /** Attribute order, for placing new attributes and writing new tags. */
+  order: string[];
+  /** Built-in constructs the studio handles itself: partials, conditions and pipe tables. */
+  builtin?: 'partial' | 'if' | 'else' | 'table';
+};
+
+export type Catalog = {
+  format: BodyFormat;
+  kinds: Map<string, BlockKind>;
+  /** The kind for a tag or component name in this body's syntax. */
+  find: (syntax: 'markdoc' | 'mdx', name: string) => BlockKind | undefined;
+};
+
+const PARTIAL_FIELD: FieldModel = {
+  path: ['file'],
+  kind: 'string',
+  required: true,
+  label: 'File',
+  description: 'The partial’s file, shown here as part of this page.',
+};
+
+export function catalogOf(manifest: Manifest, format: BodyFormat): Catalog {
+  const kinds = new Map<string, BlockKind>();
+  if (format === 'mdoc') {
+    for (const tag of manifest.markdoc?.tags ?? []) {
+      const block: BlockKind['block'] =
+        tag.inline === true ? null : tag.selfClosing ? 'card' : 'container';
+      // A tag that doesn't say may go either way in Markdoc. Offered inline,
+      // it's one that neither holds blocks nor stands alone as a card.
+      const inline =
+        tag.inline === true || (tag.inline === undefined && !tag.selfClosing && !tag.children);
+      kinds.set(`markdoc:${tag.name}`, {
+        key: `markdoc:${tag.name}`,
+        syntax: 'markdoc',
+        name: tag.name,
+        label: tag.label,
+        ...(tag.summary ? { summary: tag.summary } : {}),
+        ...(tag.description ? { description: tag.description } : {}),
+        block,
+        inline,
+        selfClosing: tag.selfClosing,
+        ...(tag.children ? { children: tag.children } : {}),
+        fields: tag.fields,
+        order: tag.attributes.map((a) => a.name),
+      });
+    }
+    if (!kinds.has('markdoc:partial')) {
+      kinds.set('markdoc:partial', {
+        key: 'markdoc:partial',
+        syntax: 'markdoc',
+        name: 'partial',
+        label: 'Partial',
+        summary: 'file',
+        description: 'Text kept in its own file and shown here.',
+        block: 'card',
+        inline: false,
+        selfClosing: true,
+        fields: [PARTIAL_FIELD],
+        order: ['file', 'variables'],
+        builtin: 'partial',
+      });
+    }
+    kinds.set('markdoc:if', {
+      key: 'markdoc:if',
+      syntax: 'markdoc',
+      name: 'if',
+      label: 'Conditional content',
+      block: 'container',
+      inline: false,
+      selfClosing: false,
+      fields: [],
+      order: [],
+      builtin: 'if',
+    });
+    kinds.set('markdoc:else', {
+      key: 'markdoc:else',
+      syntax: 'markdoc',
+      name: 'else',
+      label: 'Otherwise',
+      block: 'card',
+      inline: false,
+      selfClosing: true,
+      fields: [],
+      order: [],
+      builtin: 'else',
+    });
+  }
+  if (format === 'mdx') {
+    for (const component of manifest.mdx?.components ?? []) {
+      kinds.set(`mdx:${component.name}`, {
+        key: `mdx:${component.name}`,
+        syntax: 'mdx',
+        name: component.name,
+        label: component.label,
+        ...(component.summary ? { summary: component.summary } : {}),
+        ...(component.description ? { description: component.description } : {}),
+        block: component.inline ? null : component.children ? 'container' : 'card',
+        inline: component.inline,
+        selfClosing: !component.children,
+        fields: component.fields ?? [],
+        order: (component.fields ?? []).map((f) => f.path[0] ?? ''),
+      });
+    }
+  }
+  return {
+    format,
+    kinds,
+    find: (syntax, name) => kinds.get(`${syntax}:${name}`),
+  };
+}
+
+/** Kinds a person can insert (built-in conditions are protected, so they aren't offered). */
+/**
+ * A pipe table, insertable in every format (PLAN.md, call T4). It isn't one
+ * of the catalog's kinds, so Markdoc's own `{% table %}` is never taken for it.
+ */
+export const TABLE_KIND: BlockKind = {
+  key: 'table',
+  syntax: 'markdoc',
+  name: 'table',
+  label: 'Table',
+  block: 'card',
+  inline: false,
+  selfClosing: true,
+  fields: [],
+  order: [],
+  builtin: 'table',
+};
+
+export function insertable(catalog: Catalog): BlockKind[] {
+  return [
+    ...[...catalog.kinds.values()].filter(
+      (kind) => kind.builtin !== 'if' && kind.builtin !== 'else',
+    ),
+    TABLE_KIND,
+  ];
+}
+
+/** A new tag's text in house style: attributes in schema order, empty and default values left out. */
+export function newTagText(
+  kind: BlockKind,
+  attributes: Readonly<Record<string, unknown>>,
+  shape: BlockShape,
+  inner = '',
+): { open: string; close: string; whole: string } {
+  const pairs = kind.order.map((name) => [name, attributes[name]] as const);
+  const selfClosing = shape === 'card' || (shape === 'inline' && kind.selfClosing);
+  if (kind.syntax === 'markdoc') {
+    const open = markdocOpening(kind.name, pairs, selfClosing);
+    const close = selfClosing ? '' : markdocClosing(kind.name);
+    return { open, close, whole: shape === 'inline' ? open + inner + close : open };
+  }
+  const open = jsxOpening(kind.name, pairs, selfClosing);
+  const close = selfClosing ? '' : jsxClosing(kind.name);
+  return { open, close, whole: shape === 'inline' ? open + inner + close : open };
+}
+
+/** A friendly name for a tag nobody described: the humanized name, or the component's own. */
+export function fallbackLabel(syntax: 'markdoc' | 'mdx', name: string): string {
+  return syntax === 'mdx' ? name : humanize(name);
+}

package/src/body/checks.ts

@@ -0,0 +1,83 @@
+import {
+  issuesFromZod,
+  markdocConfigFromManifest,
+  partialChecker,
+  validateMarkdocBody,
+  validateMdxBody,
+  type BodyFormat,
+  type BodyIssue,
+  type Manifest,
+  type MdxComponentCheck,
+} from '@vespercms/core';
+
+/*
+ * Body validation for the studio (spec §6.5.1, "Validation"): Markdoc with
+ * the config rebuilt from the manifest (the site's real config checks every
+ * save again, in the dev API), and MDX props with the components' own Zod
+ * schemas. Markdoc, micromark and Zod are large, so this module, like the
+ * body editor, loads the first time an entry with a body is opened.
+ */
+
+export type BodyChecks = {
+  /** Validates a whole body, or one block's text, as the site's build would. */
+  validate: (text: string) => Promise<BodyIssue[]>;
+  /** The same, synchronously, for Markdoc (MDX props schemas load on first use). */
+  validateSync: (text: string) => BodyIssue[] | null;
+};
+
+type ZodResult = { success: boolean; error?: { issues: unknown[] } };
+type PropsSchema = { safeParseAsync?: (value: unknown, params?: object) => Promise<ZodResult> };
+
+export function bodyChecks(options: {
+  manifest: Manifest;
+  format: BodyFormat;
+  /** Declared MDX components' Zod props schemas, loaded when first needed. */
+  loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+  partials: readonly string[] | null;
+  entryPath: string;
+}): BodyChecks {
+  const { manifest, format, partials, entryPath } = options;
+  if (format === 'mdoc') {
+    const config = markdocConfigFromManifest(manifest.markdoc);
+    const run = (text: string) =>
+      validateMarkdocBody(text, {
+        config,
+        ...(manifest.markdoc
+          ? { parse: manifest.markdoc.options, tags: manifest.markdoc.tags }
+          : {}),
+        ...(partials ? { partialExists: partialChecker(entryPath, partials) } : {}),
+      });
+    return { validate: (text) => Promise.resolve(run(text)), validateSync: run };
+  }
+  if (format === 'mdx' && (manifest.mdx?.components.length ?? 0) > 0) {
+    let checks: Promise<Map<string, MdxComponentCheck>> | null = null;
+    const load = () => {
+      checks ??= options.loadMdxProps().then((schemas) => {
+        const map = new Map<string, MdxComponentCheck>();
+        for (const component of manifest.mdx?.components ?? []) {
+          const schema = schemas[component.name] as PropsSchema | undefined;
+          const parse = schema?.safeParseAsync?.bind(schema);
+          if (!parse) continue;
+          map.set(component.name, {
+            label: component.label,
+            fields: component.fields,
+            validate: async (props) => {
+              const result = await parse(props, { reportInput: true });
+              return result.success ? [] : issuesFromZod(result.error?.issues ?? []);
+            },
+          });
+        }
+        return map;
+      });
+      return checks;
+    };
+    return {
+      validate: async (text) => {
+        const map = await load();
+        return map.size > 0 ? validateMdxBody(text, map) : [];
+      },
+      validateSync: () => null,
+    };
+  }
+  return { validate: () => Promise.resolve([]), validateSync: () => [] };
+}

package/src/body/chips.ts

@@ -0,0 +1,150 @@
+import { jsxTagLayout, markdocTags, type InlineChip } from '@vespercms/core';
+
+/*
+ * Inline chips (an inline tag, a variable, an annotation, inline JSX) inside
+ * Markdown blocks. The Markdown parser and serializer see each chip as one
+ * private-use placeholder holding the chip's source as hex, so marks can
+ * span chips and nothing ever escapes or rewraps them. After serializing,
+ * placeholders turn back into each chip's current source.
+ */
+
+const OPEN = '';
+const CLOSE = '';
+const PLACEHOLDER = /([0-9a-f]*)/g;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function chipPlaceholder(source: string): string {
+  let hex = '';
+  for (const byte of encoder.encode(source)) hex += byte.toString(16).padStart(2, '0');
+  return `${OPEN}${hex}${CLOSE}`;
+}
+
+export function decodeHex(hex: string): string {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return decoder.decode(bytes);
+}
+
+/** Text with every placeholder replaced by the chip source it holds. */
+export function restoreChips(text: string): string {
+  return text.replace(PLACEHOLDER, (_, hex: string) => decodeHex(hex));
+}
+
+/** A block's text with its chips (offsets relative to the text) replaced by placeholders. */
+export function withPlaceholders(
+  text: string,
+  chips: readonly { start: number; end: number }[],
+): string {
+  let out = '';
+  let cursor = 0;
+  for (const chip of chips) {
+    out += text.slice(cursor, chip.start) + chipPlaceholder(text.slice(chip.start, chip.end));
+    cursor = chip.end;
+  }
+  return out + text.slice(cursor);
+}
+
+/** True when the text holds a private-use character the placeholders rely on. */
+export function hasPlaceholderCharacters(text: string): boolean {
+  return text.includes(OPEN) || text.includes(CLOSE);
+}
+
+export type TagValues = {
+  /** Attribute values the settings form can edit. */
+  values: Record<string, unknown>;
+  /** Attributes set by code (variables, functions, JSX expressions): shown, never edited. */
+  code: Record<string, string>;
+};
+
+/** A tag's attributes, read from its opening (Markdoc) or its opening or whole element (MDX). */
+export function tagValues(syntax: 'markdoc' | 'mdx', text: string): TagValues {
+  const values: Record<string, unknown> = {};
+  const code: Record<string, string> = {};
+  if (syntax === 'markdoc') {
+    const [token] = markdocTags(text);
+    for (const attribute of token?.attributes ?? []) {
+      if (attribute.type !== 'attribute' || attribute.name === 'primary') continue;
+      if (isMarkdocCode(attribute.value)) code[attribute.name] = describeCode(attribute.value);
+      else values[attribute.name] = attribute.value;
+    }
+    return { values, code };
+  }
+  const layout = jsxTagLayout(text);
+  for (const attribute of layout?.attributes ?? []) {
+    if (!attribute.name) continue;
+    if (attribute.readable) values[attribute.name] = attribute.value;
+    else code[attribute.name] = text.slice(attribute.start, attribute.end);
+  }
+  return { values, code };
+}
+
+function isMarkdocCode(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false;
+  if ('$$mdtype' in value) return true;
+  return Object.values(value).some(isMarkdocCode);
+}
+
+function describeCode(value: unknown): string {
+  const node = value as { $$mdtype?: string; path?: unknown[]; name?: string };
+  if (node.$$mdtype === 'Variable' && Array.isArray(node.path)) return `$${node.path.join('.')}`;
+  if (node.$$mdtype === 'Function' && node.name) return `${node.name}(…)`;
+  return 'a value set by code';
+}
+
+export type ChipInfo = {
+  syntax: 'markdoc' | 'mdx';
+  kind: InlineChip['kind'];
+  name?: string;
+  /** For tags and components: the opening, the content between, and the closing. */
+  open?: string;
+  inner?: string;
+  close?: string;
+};
+
+/** What a chip's source is: its kind, name and parts. */
+export function chipInfo(source: string): ChipInfo {
+  if (source.startsWith('{%')) {
+    const tokens = markdocTags(source);
+    const first = tokens[0];
+    const last = tokens.at(-1);
+    if (!first) return { syntax: 'markdoc', kind: 'variable' };
+    if (first.kind === 'variable') return { syntax: 'markdoc', kind: 'variable' };
+    if (first.kind === 'annotation') return { syntax: 'markdoc', kind: 'annotation' };
+    const name = first.name;
+    if (first.kind === 'tag') {
+      return {
+        syntax: 'markdoc',
+        kind: 'tag',
+        ...(name ? { name } : {}),
+        open: source,
+        inner: '',
+        close: '',
+      };
+    }
+    const closeStart =
+      last && last.kind === 'tag_close' && last.end === source.length ? last.start : source.length;
+    return {
+      syntax: 'markdoc',
+      kind: 'tag',
+      ...(name ? { name } : {}),
+      open: source.slice(0, first.end),
+      inner: source.slice(first.end, closeStart),
+      close: source.slice(closeStart),
+    };
+  }
+  if (source.startsWith('<')) {
+    const layout = jsxTagLayout(source);
+    if (!layout) return { syntax: 'mdx', kind: 'component' };
+    const close = layout.selfClosing ? '' : (/<\/[^>]*>$/.exec(source)?.[0] ?? '');
+    return {
+      syntax: 'mdx',
+      kind: 'component',
+      name: layout.name,
+      open: source.slice(0, layout.openEnd),
+      inner: source.slice(layout.openEnd, source.length - close.length),
+      close,
+    };
+  }
+  return { syntax: 'mdx', kind: 'expression' };
+}

package/src/body/commands.ts

@@ -0,0 +1,191 @@
+import type { Editor, JSONContent } from '@tiptap/core';
+import { Fragment } from '@tiptap/pm/model';
+import { NodeSelection, TextSelection, type EditorState } from '@tiptap/pm/state';
+import type { BlockKind, BlockShape } from './catalog.ts';
+import { newTagText } from './catalog.ts';
+import type { ContainerTypes } from './nodes.ts';
+import { newTableValue } from './table.ts';
+
+/*
+ * Keyboard-reachable block operations (spec §6.5.1, "Accessibility of
+ * blocks"): every tag can be inserted, configured, moved and removed
+ * without a mouse.
+ */
+
+/** Node types that are blocks the studio manages: tags, components and protected blocks. */
+export function isManaged(type: string, containers: ContainerTypes): boolean {
+  return (
+    type === 'vesperCard' ||
+    type === 'vesperInline' ||
+    type === 'vesperTable' ||
+    type === 'sourceBlock' ||
+    containers.kindOf(type) !== undefined
+  );
+}
+
+/** The managed node the selection is on (a node selection), or null. */
+export function selectedNode(
+  editor: Editor,
+  containers: ContainerTypes,
+): { pos: number; type: string } | null {
+  const { selection } = editor.state;
+  if (selection instanceof NodeSelection && isManaged(selection.node.type.name, containers)) {
+    return { pos: selection.from, type: selection.node.type.name };
+  }
+  return null;
+}
+
+/** The innermost container the cursor is inside, or null. */
+export function enclosingContainer(editor: Editor, containers: ContainerTypes): number | null {
+  const { $from } = editor.state.selection;
+  for (let depth = $from.depth; depth > 0; depth--) {
+    if (containers.kindOf($from.node(depth).type.name)) return $from.before(depth);
+  }
+  return null;
+}
+
+/** Selects the block at `pos` as a whole, so its frame shows focus and Enter opens its settings. */
+export function selectBlock(editor: Editor, pos: number): void {
+  const tr = editor.state.tr.setSelection(NodeSelection.create(editor.state.doc, pos));
+  editor.view.dispatch(tr.scrollIntoView());
+  editor.view.focus();
+}
+
+/** Moves the block at `pos` past its previous or next sibling. Returns its new position, or null. */
+export function moveBlock(editor: Editor, pos: number, direction: -1 | 1): number | null {
+  const { state } = editor;
+  const $pos = state.doc.resolve(pos);
+  const node = state.doc.nodeAt(pos);
+  if (!node || node.isInline) return null;
+  const parent = $pos.parent;
+  const index = $pos.index();
+  const sibling = index + direction;
+  if (sibling < 0 || sibling >= parent.childCount) return null;
+  const other = parent.child(sibling);
+  const tr = state.tr;
+  let target: number;
+  if (direction === -1) {
+    const otherPos = pos - other.nodeSize;
+    tr.delete(pos, pos + node.nodeSize).insert(otherPos, node);
+    target = otherPos;
+  } else {
+    tr.delete(pos, pos + node.nodeSize);
+    const after = pos + other.nodeSize;
+    tr.insert(after, node);
+    target = after;
+  }
+  tr.setSelection(NodeSelection.create(tr.doc, target)).scrollIntoView();
+  editor.view.dispatch(tr);
+  editor.view.focus();
+  return target;
+}
+
+/** Removes the block or chip at `pos`, leaving the cursor where it was. */
+export function removeBlock(editor: Editor, pos: number): void {
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node) return;
+  const tr = editor.state.tr.delete(pos, pos + node.nodeSize);
+  const at = Math.min(pos, tr.doc.content.size);
+  tr.setSelection(TextSelection.near(tr.doc.resolve(at)));
+  editor.view.dispatch(tr.scrollIntoView());
+  editor.view.focus();
+}
+
+/** The editor node a new block of `kind` starts as. */
+export function newNode(
+  kind: BlockKind,
+  shape: BlockShape,
+  containers: ContainerTypes,
+  attributes: Readonly<Record<string, unknown>> = {},
+  inner = '',
+): JSONContent {
+  if (kind.builtin === 'table') {
+    return { type: 'vesperTable', attrs: { value: newTableValue() } };
+  }
+  const text = newTagText(kind, attributes, shape, inner);
+  if (shape === 'inline') return { type: 'vesperInline', attrs: { source: text.whole } };
+  const container = shape === 'container' ? containers.typeOf(kind) : undefined;
+  if (container) {
+    return {
+      type: container,
+      attrs: { syntax: kind.syntax, name: kind.name, open: text.open, close: text.close },
+      content: [{ type: 'paragraph' }],
+    };
+  }
+  return {
+    type: 'vesperCard',
+    attrs: { syntax: kind.syntax, name: kind.name, source: text.whole },
+  };
+}
+
+/** Where a kind can go at the cursor: as a block, inline, or not at all. Reads only the state. */
+export function placementAt(
+  state: EditorState,
+  kind: BlockKind,
+  containers: ContainerTypes,
+): BlockShape | null {
+  const { $from } = state.selection;
+  const block = $from.parent;
+  if (!block.isTextblock) return null;
+  // An empty line (or one holding only the "/" being typed) takes a block; a line of text, a chip.
+  const emptyLine = block.type.name === 'paragraph' && /^\/?[^\s]*$/.test(block.textContent);
+  // Asked of the schema directly: inserting through ProseMirror would make
+  // a block "fit" by splitting the frame it's in, which isn't what fits here.
+  const fitsBlock = (shape: BlockShape) => {
+    const depth = $from.depth - 1;
+    if (depth < 0) return false;
+    const node = state.schema.nodeFromJSON(newNode(kind, shape, containers));
+    const parent = $from.node(depth);
+    const index = $from.index(depth);
+    return emptyLine
+      ? parent.canReplace(index, index + 1, Fragment.from(node))
+      : parent.canReplaceWith(index + 1, index + 1, node.type);
+  };
+  if (kind.block && (emptyLine || !kind.inline) && fitsBlock(kind.block)) return kind.block;
+  const chip = state.schema.nodes.vesperInline;
+  if (kind.inline && chip && block.canReplaceWith($from.index(), $from.index(), chip)) {
+    return 'inline';
+  }
+  return null;
+}
+
+/**
+ * Inserts a new block or chip of `kind` at the cursor (replacing `range`,
+ * the "/" text, when given) and returns its position.
+ */
+export function insertBlock(
+  editor: Editor,
+  kind: BlockKind,
+  shape: BlockShape,
+  containers: ContainerTypes,
+  range?: { from: number; to: number },
+  attributes: Readonly<Record<string, unknown>> = {},
+): number | null {
+  const node = newNode(kind, shape, containers, attributes);
+  let chain = editor.chain().focus();
+  if (range) chain = chain.deleteRange(range);
+  const before = range ? range.from : editor.state.selection.from;
+  if (!chain.insertContent(node).run()) return null;
+  // Find the node just inserted: the first of its type at or after where the cursor was.
+  const found: { pos: number | null } = { pos: null };
+  editor.state.doc.nodesBetween(
+    Math.max(0, before - 2),
+    editor.state.doc.content.size,
+    (child, pos) => {
+      if (found.pos !== null) return false;
+      if (
+        child.type.name === node.type &&
+        JSON.stringify(child.attrs.source ?? child.attrs.open) ===
+          JSON.stringify(node.attrs?.source ?? node.attrs?.open)
+      ) {
+        found.pos = pos;
+        return false;
+      }
+      return true;
+    },
+  );
+  if (found.pos !== null && shape === 'container') {
+    editor.commands.setTextSelection(found.pos + 2);
+  }
+  return found.pos;
+}