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

package/src/body/nodes.ts

@@ -0,0 +1,287 @@
+import { Extension, Node, type AnyExtension } from '@tiptap/core';
+import type { BlockKind, Catalog } from './catalog.ts';
+import { chipPlaceholder, decodeHex } from './chips.ts';
+
+/*
+ * The editor's node types for bodies (DECISIONS.md, "The writing view owns
+ * only blocks it can round-trip"). Every block-level node carries the path
+ * of the original block it was loaded from (`vesperBlock`: "3", or "3.1" for
+ * a container's second child), so a save can keep its bytes when it's
+ * unchanged. Paths are never copied when a block is split or pasted.
+ */
+
+/** Editor node types a Markdown block may become. Anything else stays source. */
+export const WRITABLE_NODES = new Set([
+  'paragraph',
+  'heading',
+  'bulletList',
+  'orderedList',
+  'blockquote',
+  'codeBlock',
+  'horizontalRule',
+]);
+
+const blockPath = { default: null, keepOnSplit: false, rendered: false } as const;
+
+/** Remembers which original block a Markdown node came from. */
+export const BlockIndex = Extension.create({
+  name: 'vesperBlockIndex',
+  addGlobalAttributes() {
+    return [{ types: [...WRITABLE_NODES], attributes: { vesperBlock: blockPath } }];
+  },
+});
+
+/** A block the writing view can't show: kept exactly, editable as raw text. */
+export const SourceBlock = Node.create({
+  name: 'sourceBlock',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      vesperBlock: blockPath,
+      text: { default: '', rendered: false },
+      blockType: { default: '', rendered: false },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-vesper-source]',
+        getAttrs: (element) => ({
+          text: element.getAttribute('data-text') ?? '',
+          blockType: element.getAttribute('data-block-type') ?? '',
+        }),
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return [
+      'div',
+      {
+        'data-vesper-source': '',
+        'data-text': String(node.attrs.text ?? ''),
+        'data-block-type': String(node.attrs.blockType ?? ''),
+      },
+    ];
+  },
+});
+
+/** A tag or component without editable content (spec §6.5.1: "a compact card"). Its whole text is `source`. */
+export const VesperCard = Node.create({
+  name: 'vesperCard',
+  group: 'block vesperTag',
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      vesperBlock: blockPath,
+      syntax: { default: 'markdoc', rendered: false },
+      name: { default: '', rendered: false },
+      source: { default: '', rendered: false },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-vesper-card]',
+        getAttrs: (element) => ({
+          syntax: element.getAttribute('data-syntax') ?? 'markdoc',
+          name: element.getAttribute('data-name') ?? '',
+          source: element.getAttribute('data-source') ?? '',
+        }),
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return [
+      'div',
+      {
+        'data-vesper-card': '',
+        'data-syntax': String(node.attrs.syntax),
+        'data-name': String(node.attrs.name),
+        'data-source': String(node.attrs.source),
+      },
+    ];
+  },
+});
+
+/**
+ * A pipe table the writing view edits cell by cell (DECISIONS.md, "Tables
+ * are edited as a grid, and a save splices cells"). One atom, whose view is
+ * a grid that owns its own focus; `value` is the table as `table.ts` holds it.
+ */
+export const VesperTable = Node.create({
+  name: 'vesperTable',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      vesperBlock: blockPath,
+      value: { default: null, rendered: false },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-vesper-table]',
+        getAttrs: (element) => {
+          try {
+            return { value: JSON.parse(element.getAttribute('data-value') ?? 'null') as unknown };
+          } catch {
+            return false;
+          }
+        },
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return ['div', { 'data-vesper-table': '', 'data-value': JSON.stringify(node.attrs.value) }];
+  },
+});
+
+/**
+ * An inline chip: an inline tag, a variable, an annotation, inline JSX or an
+ * expression. Its text is `source`. To the Markdown parser and serializer it
+ * is one placeholder (see chips.ts).
+ */
+export const VesperInline = Node.create({
+  name: 'vesperInline',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return { source: { default: '', rendered: false } };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: 'span[data-vesper-chip]',
+        getAttrs: (element) => ({ source: element.getAttribute('data-source') ?? '' }),
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return ['span', { 'data-vesper-chip': '', 'data-source': String(node.attrs.source) }];
+  },
+  markdownTokenizer: {
+    name: 'vesperInline',
+    level: 'inline',
+    start: (src) => src.indexOf(''),
+    tokenize: (src) => {
+      const match = /^([0-9a-f]*)/.exec(src);
+      return match ? { type: 'vesperInline', raw: match[0], hex: match[1] } : undefined;
+    },
+  },
+  parseMarkdown: (token, helpers) =>
+    helpers.createNode('vesperInline', { source: decodeHex(String(token.hex ?? '')) }),
+  renderMarkdown: (node) => chipPlaceholder(String(node.attrs?.source ?? '')),
+});
+
+/** Markdoc child node types, as editor node types. */
+const CHILD_TYPES: Record<string, string[]> = {
+  paragraph: ['paragraph'],
+  list: ['bulletList', 'orderedList'],
+  heading: ['heading'],
+  blockquote: ['blockquote'],
+  fence: ['codeBlock'],
+  hr: ['horizontalRule'],
+  image: ['paragraph'],
+  table: ['vesperTable'],
+  tag: ['vesperTag'],
+};
+
+export type ContainerTypes = {
+  /** Editor node types for containers, one per kind that has content. */
+  extensions: AnyExtension[];
+  /** The editor node type for a kind's container. */
+  typeOf: (kind: BlockKind) => string | undefined;
+  /** The kind behind a container node type. */
+  kindOf: (type: string) => BlockKind | undefined;
+  /** Whether a node of `type` may sit directly inside a container of `kind`. */
+  allows: (kind: BlockKind, type: string) => boolean;
+};
+
+/**
+ * One container node type per tag or component with content. Its content
+ * expression comes from Markdoc's `children`, so only allowed node types
+ * fit inside (spec §6.5.1), and protected blocks always do.
+ */
+export function containerTypes(catalog: Catalog): ContainerTypes {
+  const byType = new Map<string, BlockKind>();
+  const typeByKey = new Map<string, string>();
+  const allowed = new Map<string, Set<string> | null>();
+  const extensions: AnyExtension[] = [];
+  let n = 0;
+  for (const kind of catalog.kinds.values()) {
+    if (kind.block !== 'container') continue;
+    const type = `vesperTag${String(n++)}_${kind.name.replace(/[^A-Za-z0-9]/g, '')}`;
+    byType.set(type, kind);
+    typeByKey.set(kind.key, type);
+    const children = kind.children?.flatMap((child) => CHILD_TYPES[child] ?? []);
+    const set = children ? new Set([...children, 'sourceBlock']) : null;
+    allowed.set(kind.key, set);
+    const content = set ? `(${[...set].join(' | ')})+` : 'block+';
+    extensions.push(containerNode(type, content, kind));
+  }
+  return {
+    extensions,
+    typeOf: (kind) => typeByKey.get(kind.key),
+    kindOf: (type) => byType.get(type),
+    allows: (kind, type) => {
+      const set = allowed.get(kind.key);
+      if (set === undefined || set === null) return true;
+      if (set.has(type)) return true;
+      return set.has('vesperTag') && (type === 'vesperCard' || byType.has(type));
+    },
+  };
+}
+
+function containerNode(type: string, content: string, kind: BlockKind): AnyExtension {
+  return Node.create({
+    name: type,
+    group: 'block vesperTag',
+    content,
+    defining: true,
+    isolating: true,
+    draggable: false,
+    selectable: true,
+    addAttributes() {
+      return {
+        vesperBlock: blockPath,
+        syntax: { default: kind.syntax, rendered: false },
+        name: { default: kind.name, rendered: false },
+        open: { default: '', rendered: false },
+        close: { default: '', rendered: false },
+      };
+    },
+    parseHTML() {
+      return [
+        {
+          tag: `div[data-vesper-container="${type}"]`,
+          getAttrs: (element) => ({
+            open: element.getAttribute('data-open') ?? '',
+            close: element.getAttribute('data-close') ?? '',
+          }),
+        },
+      ];
+    },
+    renderHTML({ node }) {
+      return [
+        'div',
+        {
+          'data-vesper-container': type,
+          'data-open': String(node.attrs.open),
+          'data-close': String(node.attrs.close),
+        },
+        0,
+      ];
+    },
+  });
+}

package/src/body/reveal.ts

@@ -0,0 +1,93 @@
+import type { Editor } from '@tiptap/core';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import { NodeSelection, TextSelection, type Selection } from '@tiptap/pm/state';
+import {
+  parseBody,
+  type BodyBlock,
+  type BodyFormat,
+  type MarkdocParseOptions,
+} from '@vespercms/core';
+import { isManaged } from './commands.ts';
+import type { ContainerTypes } from './nodes.ts';
+
+/*
+ * Taking someone to a place in the body (an accessibility note's "Show" and
+ * "Go to field"). Notes point at offsets in the body's text; the writing
+ * view's nodes are its blocks in the same order (DECISIONS.md, "The body
+ * editor splices changed blocks into the original text"), nested only
+ * inside containers. So the text is parsed again, the blocks holding the
+ * offset are found at each level, and the node at the same place is chosen.
+ */
+
+/** The index of the block holding `offset` at each level, going into containers' children. */
+export function blockPathAt(blocks: readonly BodyBlock[], offset: number): number[] {
+  const path: number[] = [];
+  let level = blocks;
+  while (level.length > 0) {
+    let index = level.findIndex((block) => offset >= block.start && offset <= block.end);
+    // Between two blocks: the one before, or the first.
+    if (index === -1)
+      index = Math.max(
+        0,
+        level.findLastIndex((block) => block.start <= offset),
+      );
+    path.push(index);
+    const children = level[index]?.tag?.children ?? [];
+    // An offset in a container's opening or closing selects the container itself.
+    if (!children.some((child) => offset >= child.start && offset <= child.end)) break;
+    level = children;
+  }
+  return path;
+}
+
+/** The node at that path in the editor's document, and where it starts. */
+function nodeAtPath(doc: PmNode, path: readonly number[]): { node: PmNode; pos: number } | null {
+  let parent = doc;
+  let contentStart = 0;
+  let found: { node: PmNode; pos: number } | null = null;
+  for (const wanted of path) {
+    if (parent.childCount === 0) break;
+    const index = Math.min(wanted, parent.childCount - 1);
+    let pos = contentStart;
+    for (let i = 0; i < index; i++) pos += parent.child(i).nodeSize;
+    const node = parent.child(index);
+    found = { node, pos };
+    if (node.isTextblock || node.isAtom) break;
+    parent = node;
+    contentStart = pos + 1;
+  }
+  return found;
+}
+
+/** Selects the block at `offset` of `text` in the writing view, focuses it and scrolls to it. */
+export function revealInEditor(
+  editor: Editor,
+  text: string,
+  offset: number,
+  options: { format: BodyFormat; markdoc?: MarkdocParseOptions; containers: ContainerTypes },
+): void {
+  const parsed = parseBody(
+    text,
+    options.format,
+    options.markdoc ? { markdoc: options.markdoc } : {},
+  );
+  const target = nodeAtPath(editor.state.doc, blockPathAt(parsed.blocks, offset));
+  // Focus first: the caret that focus brings would otherwise replace the selection.
+  editor.view.focus();
+  if (!target) return;
+  const { doc } = editor.state;
+  let selection: Selection;
+  if (target.node.isTextblock) selection = TextSelection.create(doc, target.pos + 1);
+  else if (isManaged(target.node.type.name, options.containers))
+    selection = NodeSelection.create(doc, target.pos);
+  else selection = TextSelection.near(doc.resolve(target.pos + 1));
+  editor.view.dispatch(editor.state.tr.setSelection(selection).scrollIntoView());
+}
+
+/** Selects a range of the source view's text, focuses it and scrolls to it. */
+export function revealInSource(textarea: HTMLTextAreaElement, start: number, end: number): void {
+  textarea.setSelectionRange(start, end);
+  // Focusing after the selection is set scrolls the text area to it.
+  textarea.blur();
+  textarea.focus();
+}

package/src/body/scroll.ts

@@ -0,0 +1,53 @@
+import { NodeSelection } from '@tiptap/pm/state';
+import type { EditorView } from '@tiptap/pm/view';
+
+/**
+ * A formatting toolbar inside its editor's frame, stuck below whatever
+ * already floats at the top of the scroller (`--sticky-top`, set by the
+ * screen or the pane), and only while its editor is on screen. Outside them,
+ * in a dialog, it sticks to the dialog's top.
+ */
+export const stuckToolbar =
+  'sticky top-[var(--sticky-top,0px)] z-1 rounded-t-md border-b border-border bg-surface-raised p-1';
+
+/** Less than the text's own padding, so a toolbar that isn't stuck never sets this off. */
+const GAP = 4;
+
+/**
+ * ProseMirror keeps the caret inside its scroller's box, but a stuck
+ * formatting toolbar (and the glass above it) covers that box's top, so the
+ * caret could move up beneath them out of sight. Before ProseMirror scrolls,
+ * this scrolls a caret that's under the toolbar clear of it; ProseMirror's
+ * own scrolling then does the rest. Always false, so it never replaces it.
+ */
+export function scrollClearOfToolbar(view: EditorView, toolbar: HTMLElement | null): boolean {
+  if (!toolbar) return false;
+  const { selection } = view.state;
+  let top: number;
+  try {
+    top = view.coordsAtPos(
+      selection instanceof NodeSelection ? selection.from : selection.head,
+    ).top;
+  } catch {
+    // No layout (jsdom).
+    return false;
+  }
+  const clear = toolbar.getBoundingClientRect().bottom + GAP;
+  // Above the text's own top, the caret is scrolled away inside a resized editor: ProseMirror's.
+  if (top >= clear || top < view.dom.getBoundingClientRect().top) return false;
+  scrollerOf(view.dom).scrollBy(0, top - clear);
+  return false;
+}
+
+function scrollerOf(element: HTMLElement): Element | Window {
+  for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+    const { overflowY } = getComputedStyle(parent);
+    if (
+      (overflowY === 'auto' || overflowY === 'scroll') &&
+      parent.scrollHeight > parent.clientHeight
+    ) {
+      return parent;
+    }
+  }
+  return window;
+}