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

package/src/body/table.ts

@@ -0,0 +1,192 @@
+import type { JSONContent } from '@tiptap/core';
+import type { MarkdownManager } from '@tiptap/markdown';
+import {
+  escapePipes,
+  tableValue,
+  unescapePipes,
+  type BodyTable,
+  type TableAlign,
+  type TableValue,
+} from '@vespercms/core';
+import { restoreChips, withPlaceholders } from './chips.ts';
+
+/*
+ * A table as the writing view holds it (DECISIONS.md, "Tables are edited as
+ * a grid, and a save splices cells"): core's `TableValue`, with each cell's
+ * chips as placeholders, so a cell is parsed, shown and edited like a line
+ * of the body. Every change to a table goes through these functions, so
+ * rows and columns keep the index they were loaded at.
+ */
+
+/** Inline nodes a cell may hold, beside text with its marks. */
+const CELL_NODES = new Set(['text', 'image', 'vesperInline']);
+
+/**
+ * A named character reference Tiptap doesn't decode (any but `<`, `>`,
+ * `"` and `&`): it shows as written, and an edit would save it as
+ * ` ` (DECISIONS.md, "The compact Markdown editor checks marked's
+ * tokens before the round trip").
+ */
+const UNDECODED = /&(?!(?:lt|gt|quot|amp);)[A-Za-z][A-Za-z0-9]*;/;
+
+/**
+ * A cell parsed on its own would start a block where it starts with a
+ * block's marker (`2. Second`, `# 1`, `- none`); in a table it's text.
+ */
+function asInline(text: string): string {
+  const ordered = /^(\d{1,9})[.)](\s|$)/.exec(text);
+  if (ordered?.[1]) return `${ordered[1]}\\${text.slice(ordered[1].length)}`;
+  return /^(#{1,6}(\s|$)|[-+*](\s|$)|>|([-*_][ \t]*){3,}$|`{3}|~{3})/.test(text)
+    ? `\\${text}`
+    : text;
+}
+
+/** A cell's inline nodes, from its text as written (pipes escaped, chips as placeholders). */
+export function parseCell(markdown: MarkdownManager, text: string): JSONContent[] | null {
+  try {
+    const nodes = markdown.parse(asInline(unescapePipes(text))).content ?? [];
+    if (nodes.length === 0) return [];
+    const [paragraph] = nodes;
+    if (nodes.length !== 1 || paragraph?.type !== 'paragraph') return null;
+    const inline = paragraph.content ?? [];
+    return inline.every((node) => CELL_NODES.has(node.type ?? '')) ? inline : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Inline nodes as a cell's text: one line, every pipe escaped. */
+export function cellText(markdown: MarkdownManager, inline: readonly JSONContent[]): string {
+  if (inline.length === 0) return '';
+  const doc = { type: 'doc', content: [{ type: 'paragraph', content: [...inline] }] };
+  return escapePipes(markdown.serialize(doc).trim());
+}
+
+/**
+ * The cell's inline nodes when the writing view can own it: one line of
+ * inline Markdown that reads back the same once written. Null otherwise.
+ */
+export function cellFits(markdown: MarkdownManager, text: string): JSONContent[] | null {
+  const inline = parseCell(markdown, text);
+  if (!inline) return null;
+  if (inline.some((node) => node.type === 'text' && UNDECODED.test(node.text ?? ''))) return null;
+  const again = parseCell(markdown, cellText(markdown, inline));
+  return JSON.stringify(again) === JSON.stringify(inline) ? inline : null;
+}
+
+/** The table as loaded, each cell with its chips as placeholders. */
+export function editorValue(text: string, table: BodyTable): TableValue {
+  const value = tableValue(text, table);
+  const lines = [table.header, ...table.rows];
+  return {
+    ...value,
+    rows: value.rows.map((row, r) => ({
+      ...row,
+      cells: row.cells.map((content, c) => {
+        const cell = lines[r]?.cells[c];
+        const base = cell?.contentStart ?? 0;
+        const chips = (cell?.chips ?? []).map((chip) => ({
+          start: chip.start - base,
+          end: chip.end - base,
+        }));
+        return withPlaceholders(content, chips);
+      }),
+    })),
+  };
+}
+
+/** The table with every chip's text back in place, for core's writer. */
+export function savedValue(value: TableValue): TableValue {
+  return {
+    ...value,
+    rows: value.rows.map((row) => ({ ...row, cells: row.cells.map(restoreChips) })),
+  };
+}
+
+/** A new table: a header row and one row, two columns, all empty. */
+export function newTableValue(): TableValue {
+  return {
+    align: [null, null],
+    columns: [null, null],
+    rows: [
+      { from: null, cells: ['', ''] },
+      { from: null, cells: ['', ''] },
+    ],
+  };
+}
+
+export function setCell(value: TableValue, row: number, column: number, text: string): TableValue {
+  return {
+    ...value,
+    rows: value.rows.map((r, i) =>
+      i === row ? { ...r, cells: r.cells.map((c, j) => (j === column ? text : c)) } : r,
+    ),
+  };
+}
+
+/** A new empty row at `at` (1 or more: the header stays first). */
+export function insertRow(value: TableValue, at: number): TableValue {
+  const rows = [...value.rows];
+  rows.splice(Math.max(1, at), 0, { from: null, cells: value.columns.map(() => '') });
+  return { ...value, rows };
+}
+
+/** A new empty column at `at`. */
+export function insertColumn(value: TableValue, at: number): TableValue {
+  const splice = <T>(list: readonly T[], item: T) => [
+    ...list.slice(0, at),
+    item,
+    ...list.slice(at),
+  ];
+  return {
+    align: splice(value.align, null),
+    columns: splice(value.columns, null),
+    rows: value.rows.map((row) => ({ ...row, cells: splice(row.cells, '') })),
+  };
+}
+
+/** Moves a row below the header to `to` (also below the header). */
+export function moveRow(value: TableValue, from: number, to: number): TableValue {
+  if (from < 1 || to < 1 || to >= value.rows.length || from >= value.rows.length) return value;
+  const rows = [...value.rows];
+  const [moved] = rows.splice(from, 1);
+  if (moved) rows.splice(to, 0, moved);
+  return { ...value, rows };
+}
+
+export function moveColumn(value: TableValue, from: number, to: number): TableValue {
+  const count = value.columns.length;
+  if (from < 0 || to < 0 || from >= count || to >= count) return value;
+  const move = <T>(list: readonly T[]) => {
+    const out = [...list];
+    const [moved] = out.splice(from, 1);
+    if (moved !== undefined) out.splice(to, 0, moved);
+    return out;
+  };
+  return {
+    align: move(value.align),
+    columns: move(value.columns),
+    rows: value.rows.map((row) => ({ ...row, cells: move(row.cells) })),
+  };
+}
+
+/** Deletes a row below the header. */
+export function deleteRow(value: TableValue, row: number): TableValue {
+  if (row < 1) return value;
+  return { ...value, rows: value.rows.filter((_, i) => i !== row) };
+}
+
+/** Deletes a column, unless it's the only one. */
+export function deleteColumn(value: TableValue, column: number): TableValue {
+  if (value.columns.length <= 1) return value;
+  const without = <T>(list: readonly T[]) => list.filter((_, i) => i !== column);
+  return {
+    align: without(value.align),
+    columns: without(value.columns),
+    rows: value.rows.map((row) => ({ ...row, cells: without(row.cells) })),
+  };
+}
+
+export function alignColumn(value: TableValue, column: number, align: TableAlign): TableValue {
+  return { ...value, align: value.align.map((a, i) => (i === column ? align : a)) };
+}

package/src/body/ui.ts

@@ -0,0 +1,77 @@
+import type { BodyIssue, TableEdit, TableValue } from '@vespercms/core';
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import type { BlockKind, Catalog } from './catalog.ts';
+import type { BodyChecks } from './checks.ts';
+import type { ContainerTypes } from './nodes.ts';
+
+/*
+ * What the body editor's node views share: the catalog of blocks, the
+ * actions their buttons start, and validation of one block's own text, so
+ * each block shows its own messages inline (spec §6.5.1, "Validation").
+ */
+
+export type BodyActions = {
+  openSettings: (pos: number) => void;
+  move: (pos: number, direction: -1 | 1) => void;
+  remove: (pos: number) => void;
+};
+
+export type BodyUi = BodyActions & {
+  catalog: Catalog;
+  containers: ContainerTypes;
+  disabled: boolean;
+  checks: BodyChecks;
+  /** Site-relative paths of the files a partial can point at, once loaded. */
+  partials: readonly string[] | null;
+  entryPath: string;
+  /** Says something in the body's polite status ("Row added below row 3."). */
+  announce: (message: string) => void;
+  /** Whether a table's change would save, through core's writer, against the table it was loaded from. */
+  checkTable: (path: string | null, value: TableValue) => TableEdit;
+  /** True once, for the table just inserted, so it starts with its first cell being edited. */
+  takeNewTable: () => boolean;
+};
+
+export const BodyUiContext = createContext<BodyUi | null>(null);
+
+export function useBodyUi(): BodyUi {
+  const ui = useContext(BodyUiContext);
+  if (!ui) throw new Error('useBodyUi() must be used inside the body editor.');
+  return ui;
+}
+
+/** One block's issues, from its own text: synchronous for Markdoc, after a tick for MDX. */
+export function useBlockIssues(text: string): BodyIssue[] {
+  const { checks } = useBodyUi();
+  const sync = useMemo(() => checks.validateSync(text), [checks, text]);
+  const [async, setAsync] = useState<BodyIssue[]>([]);
+  useEffect(() => {
+    if (sync !== null) return;
+    let live = true;
+    void checks.validate(text).then((issues) => {
+      if (live) setAsync(issues);
+    });
+    return () => {
+      live = false;
+    };
+  }, [checks, text, sync]);
+  return sync ?? async;
+}
+
+/** The header's summary: the summary attribute's value, shown with its option label. */
+export function summaryOf(
+  kind: BlockKind | undefined,
+  values: Readonly<Record<string, unknown>>,
+): string {
+  if (!kind) return '';
+  const name = kind.summary ?? (kind.builtin === 'partial' ? 'file' : undefined);
+  if (!name) return '';
+  const value = values[name];
+  const field = kind.fields.find((f) => f.path[0] === name);
+  const fallback = value === undefined ? field?.default : value;
+  if (fallback === undefined || fallback === null || fallback === '') return '';
+  const option = field?.constraints?.options?.find((o) => o.value === fallback);
+  const text =
+    option?.label ?? (typeof fallback === 'string' ? fallback : JSON.stringify(fallback));
+  return text.length > 60 ? `${text.slice(0, 57)}…` : text;
+}

package/src/body/views.tsx

@@ -0,0 +1,268 @@
+import {
+  NodeViewContent,
+  NodeViewWrapper,
+  useEditorState,
+  type ReactNodeViewProps,
+} from '@tiptap/react';
+import type { BodyIssue } from '@vespercms/core';
+import { Button, cx } from '@vespercms/ui';
+import { useId } from 'react';
+import { fallbackLabel } from './catalog.ts';
+import { chipInfo, tagValues } from './chips.ts';
+import { sourceLabel } from './document.ts';
+import { summaryOf, useBlockIssues, useBodyUi } from './ui.ts';
+
+/*
+ * How blocks look in the writing view (spec §6.5.1): a tag with content is
+ * a labelled frame, one without is a compact card, an inline tag is a chip,
+ * and anything the editor can't show is a protected block. Each frame and
+ * card is a group named after its tag, with a real Settings button, and
+ * shows its own validation messages in words.
+ *
+ * Buttons inside the text stay out of the Tab order (69 chips must never be
+ * 69 Tab stops), except the Settings button of the frame the cursor is in,
+ * so Tab from inside a frame reaches it. Everything they do is also on the
+ * keyboard: select a block and press Enter.
+ */
+
+/** A selected block shows a focus outline, but only while the text has focus. */
+const SELECTED = cx(
+  'in-[.ProseMirror-focused]:outline-2 in-[.ProseMirror-focused]:outline-solid in-[.ProseMirror-focused]:outline-offset-2 in-[.ProseMirror-focused]:outline-focus',
+  'in-[.ProseMirror-focused]:ring-6 in-[.ProseMirror-focused]:ring-(color:--glow-focus)',
+);
+
+function Issues({ id, issues }: { id: string; issues: readonly BodyIssue[] }) {
+  if (issues.length === 0) return null;
+  return (
+    <ul id={id} className="mt-2 flex flex-col gap-1 text-small">
+      {issues.map((issue) => (
+        <li
+          key={`${String(issue.line)}${issue.message}`}
+          className={issue.level === 'error' ? 'text-danger' : 'text-content-muted'}
+        >
+          {issue.level === 'error' ? issue.message : `Note: ${issue.message}`}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function headerText(label: string, summary: string): string {
+  return summary ? `${label} · ${summary}` : label;
+}
+
+/** A tag with editable content: the header, then the content, inside a hairline frame. */
+export function ContainerView({ node, getPos, selected, editor }: ReactNodeViewProps) {
+  const ui = useBodyUi();
+  const headerId = useId();
+  const issuesId = useId();
+  const syntax = node.attrs.syntax as 'markdoc' | 'mdx';
+  const name = String(node.attrs.name);
+  const open = String(node.attrs.open);
+  const close = String(node.attrs.close);
+  const kind = ui.catalog.find(syntax, name);
+  const label = kind?.label ?? fallbackLabel(syntax, name);
+  const summary =
+    kind?.builtin === 'if'
+      ? `shown when ${conditionOf(open)}`
+      : summaryOf(kind, tagValues(syntax, open).values);
+  // The attributes only: what's inside is checked as part of the whole body.
+  const issues = useBlockIssues(syntax === 'mdx' ? `${open}\n\n${close}` : `${open}\n${close}`);
+  // Tab from inside this frame reaches its Settings button, and no other frame's.
+  const inside = useEditorState({
+    editor,
+    selector: ({ editor: e }) => {
+      const pos = getPos();
+      if (typeof pos !== 'number') return false;
+      const { from, to } = e.state.selection;
+      return from > pos && to < pos + node.nodeSize;
+    },
+  });
+  return (
+    <NodeViewWrapper
+      as="div"
+      role="group"
+      aria-labelledby={headerId}
+      aria-describedby={issues.length > 0 ? issuesId : undefined}
+      className={cx(
+        'my-3 rounded-md border border-border p-3',
+        issues.some((i) => i.level === 'error') && 'border-danger',
+        selected && SELECTED,
+      )}
+    >
+      <div contentEditable={false} className="mb-2 flex items-center justify-between gap-2">
+        <p id={headerId} className="text-label text-content-muted">
+          {headerText(label, summary)}
+        </p>
+        <SettingsButton label={label} getPos={getPos} inTabOrder={inside} />
+      </div>
+      <NodeViewContent className="vesper-container-content" />
+      <div contentEditable={false}>
+        <Issues id={issuesId} issues={issues} />
+      </div>
+    </NodeViewWrapper>
+  );
+}
+
+function SettingsButton({
+  label,
+  getPos,
+  inTabOrder,
+}: {
+  label: string;
+  getPos: () => number | undefined;
+  inTabOrder: boolean;
+}) {
+  const ui = useBodyUi();
+  return (
+    <Button
+      variant="quiet"
+      excludeFromTabOrder={!inTabOrder}
+      aria-label={`Settings for ${label}`}
+      isDisabled={ui.disabled}
+      onPress={() => {
+        const pos = getPos();
+        if (typeof pos === 'number') ui.openSettings(pos);
+      }}
+      className="min-h-8 px-2 text-small"
+    >
+      Settings
+    </Button>
+  );
+}
+
+/** A tag or component without editable content. */
+export function CardView({ node, getPos, selected }: ReactNodeViewProps) {
+  const ui = useBodyUi();
+  const headerId = useId();
+  const issuesId = useId();
+  const syntax = node.attrs.syntax as 'markdoc' | 'mdx';
+  const name = String(node.attrs.name);
+  const source = String(node.attrs.source);
+  const kind = ui.catalog.find(syntax, name);
+  const label = kind?.label ?? fallbackLabel(syntax, name);
+  const summary =
+    kind?.builtin === 'else'
+      ? conditionOf(source)
+      : kind?.builtin === 'if'
+        ? ''
+        : summaryOf(kind, tagValues(syntax, source).values);
+  const issues = useBlockIssues(source);
+  return (
+    <NodeViewWrapper
+      as="div"
+      contentEditable={false}
+      role="group"
+      aria-labelledby={headerId}
+      aria-describedby={issues.length > 0 ? issuesId : undefined}
+      className={cx(
+        // The page's own surface, a step back from the writing surface around it.
+        'my-3 rounded-md border border-border bg-surface p-3',
+        issues.some((i) => i.level === 'error') && 'border-danger',
+        selected && SELECTED,
+      )}
+    >
+      <div className="flex items-center justify-between gap-2">
+        <p id={headerId} className="text-label text-content">
+          {headerText(label, summary)}
+        </p>
+        <SettingsButton label={label} getPos={getPos} inTabOrder={false} />
+      </div>
+      <Issues id={issuesId} issues={issues} />
+    </NodeViewWrapper>
+  );
+}
+
+/** The condition of `{% if … %}` or `{% else … /%}`, as written. */
+function conditionOf(tag: string): string {
+  return tag
+    .replace(/^\{%\s*(if|else)\b/, '')
+    .replace(/\/?%\}$/, '')
+    .trim();
+}
+
+/** An inline chip. Tags and components show their friendly name and text; the rest show their source. */
+export function InlineView({ node, selected }: ReactNodeViewProps) {
+  const ui = useBodyUi();
+  const source = String(node.attrs.source);
+  const info = chipInfo(source);
+  const kind = info.name ? ui.catalog.find(info.syntax, info.name) : undefined;
+  const isTag = info.kind === 'tag' || info.kind === 'component';
+  // Only a tag can be checked on its own; a variable or an annotation needs
+  // the text around it, so the whole body's check covers those.
+  const issues = useBlockIssues(isTag ? source : '').filter((issue) => issue.level === 'error');
+  const known = kind && isTag;
+  const text = known
+    ? headerText(
+        kind.label,
+        plainInner(info.inner) || summaryOf(kind, tagValues(info.syntax, info.open ?? '').values),
+      )
+    : source.length > 80
+      ? `${source.slice(0, 77)}…`
+      : source;
+  return (
+    <NodeViewWrapper
+      as="span"
+      // No contentEditable={false}: ProseMirror sets it on the node view's own
+      // element, which keeps the caret out. A second one in here looks to
+      // ProseMirror like a widget to step over, and ⌘← or ⌘→ next to a chip
+      // at either end of a line then does nothing (DECISIONS.md).
+      className={cx(
+        'mx-0.5 rounded-sm border border-border-strong bg-surface-sunken px-1 py-0.5 text-small',
+        !known && 'font-mono',
+        issues.length > 0 && 'border-danger',
+        selected && SELECTED,
+      )}
+    >
+      {text}
+      {issues.length > 0 && (
+        <span className="text-danger"> ({issues.map((i) => i.message).join(' ')})</span>
+      )}
+    </NodeViewWrapper>
+  );
+}
+
+/** An inline tag's content, when it's plain text. */
+function plainInner(inner: string | undefined): string {
+  if (!inner || /[{<*_`[\]\\]/.test(inner)) return '';
+  return inner;
+}
+
+/** A protected block: named, shown as source, editable as raw text. */
+export function SourceView({ node, getPos, selected }: ReactNodeViewProps) {
+  const ui = useBodyUi();
+  const text = String(node.attrs.text ?? '');
+  const lines = text.split('\n');
+  const label = sourceLabel(String(node.attrs.blockType ?? ''));
+  return (
+    <NodeViewWrapper
+      as="div"
+      contentEditable={false}
+      className={cx(
+        'my-3 rounded-md border border-dashed border-border-strong bg-surface-sunken p-3',
+        selected && SELECTED,
+      )}
+    >
+      <div className="mb-1 flex items-center justify-between gap-2">
+        <p className="text-label text-content-muted">{label}, kept as written.</p>
+        <Button
+          variant="quiet"
+          excludeFromTabOrder
+          aria-label={`Edit as text: ${label}`}
+          isDisabled={ui.disabled}
+          onPress={() => {
+            const pos = getPos();
+            if (typeof pos === 'number') ui.openSettings(pos);
+          }}
+          className="min-h-8 px-2 text-small"
+        >
+          Edit as text
+        </Button>
+      </div>
+      <pre className="overflow-x-auto font-mono text-small whitespace-pre-wrap text-content">
+        {lines.slice(0, 6).join('\n')}
+        {lines.length > 6 ? `\n… ${String(lines.length - 6)} more lines` : ''}
+      </pre>
+    </NodeViewWrapper>
+  );
+}

package/src/build.ts

@@ -0,0 +1,6 @@
+// The library build's entry. Importing the stylesheet here makes Vite compile
+// it to dist/studio.css; library mode keeps CSS out of the JavaScript, so
+// pages import '@vespercms/admin/studio.css' themselves.
+import './studio.css';
+
+export * from './index.ts';