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

package/src/widgets/markdown.tsx

@@ -0,0 +1,267 @@
+import { Extension, type JSONContent, type MarkdownToken } from '@tiptap/core';
+import { Markdown, type MarkdownManager } from '@tiptap/markdown';
+import { EditorContent, useEditor, useEditorState } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import { ToggleButton, ToolButton, Toolbar, cx } from '@vespercms/ui';
+import { useEffect, useRef, useState } from 'react';
+import { LinkDialog } from '../body/BodyEditor.tsx';
+import { scrollClearOfToolbar, stuckToolbar } from '../body/scroll.ts';
+import { shortcut } from '../body/shortcuts.ts';
+import type { WidgetProps } from '../types.ts';
+import { inputClass } from './basic.tsx';
+
+/*
+ * Markdown in frontmatter (spec §6.3.2): a compact editor for short rich
+ * text, with bold, italic, code, links and (unless the field is inline)
+ * paragraphs and lists. Nothing is rewritten until someone edits it. A
+ * value that uses Markdown this editor can't show faithfully is edited as
+ * plain text, and the field says so.
+ */
+
+const ALLOWED = new Set([
+  'doc',
+  'paragraph',
+  'text',
+  'hardBreak',
+  'bulletList',
+  'orderedList',
+  'listItem',
+]);
+const INLINE_ALLOWED = new Set(['doc', 'paragraph', 'text', 'hardBreak']);
+
+function nodeTypes(node: JSONContent, found = new Set<string>()): Set<string> {
+  if (node.type) found.add(node.type);
+  for (const child of node.content ?? []) nodeTypes(child, found);
+  return found;
+}
+
+/*
+ * The tokens of marked, the lexer Tiptap parses with, that the editor holds.
+ * Tiptap's parser drops what no extension claims (a strikethrough's tildes,
+ * an image, a quote, a rule, a table, a link definition, a list in a
+ * one-line field), and the round trip can't see that: it's missing from both
+ * sides. HTML is a token too, so a code span holding `<` is still code.
+ */
+const INLINE_TOKENS = new Set([
+  'space',
+  'paragraph',
+  'text',
+  'escape',
+  'strong',
+  'em',
+  'codespan',
+  'link',
+  'br',
+]);
+const TOKENS = new Set([...INLINE_TOKENS, 'list', 'list_item']);
+
+/*
+ * Text marked keeps as text that the editor would change: a GFM footnote,
+ * which it writes back with the brackets escaped, and a named character
+ * reference Tiptap doesn't decode (any but `&lt;`, `&gt;`, `&quot;` and
+ * `&amp;`), which it shows as written and saves as `&amp;nbsp;`. Escaped
+ * characters are tokens of their own, so `\[^1]` and `\&nbsp;` don't match.
+ */
+const LOSSY_TEXT = /\[\^|&(?!(?:lt|gt|quot|amp);)[A-Za-z][A-Za-z0-9]*;/;
+
+function holds(tokens: MarkdownToken[], allowed: Set<string>): boolean {
+  return tokens.every(
+    (token) =>
+      allowed.has(token.type ?? '') &&
+      // A list item's text token carries its line's raw source, escapes and all.
+      !(token.type === 'text' && !token.tokens && LOSSY_TEXT.test(token.raw ?? '')) &&
+      holds(token.tokens ?? [], allowed) &&
+      holds(token.items ?? [], allowed),
+  );
+}
+
+/** Whether the compact editor can own this value: only tokens and nodes it holds, and it reads back the same. */
+function fits(markdown: MarkdownManager, value: string, inline: boolean): boolean {
+  try {
+    const tokens = markdown.instance.lexer(value) as MarkdownToken[];
+    if (!holds(tokens, inline ? INLINE_TOKENS : TOKENS)) return false;
+    const doc = markdown.parse(value);
+    const allowed = inline ? INLINE_ALLOWED : ALLOWED;
+    if (![...nodeTypes(doc)].every((type) => allowed.has(type))) return false;
+    if (inline && (doc.content?.length ?? 0) > 1) return false;
+    const again = markdown.parse(markdown.serialize(doc));
+    return JSON.stringify(again) === JSON.stringify(doc);
+  } catch {
+    return false;
+  }
+}
+
+export function MarkdownWidget(props: WidgetProps<string>) {
+  const { value, onChange, field, id, describedBy, invalid, disabled } = props;
+  const inline = field.widgetOptions?.inline === true;
+  const [plain, setPlain] = useState(false);
+  const [linkOpen, setLinkOpen] = useState(false);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  const toolbar = useRef<HTMLDivElement>(null);
+  const [extras] = useState(() =>
+    Extension.create({
+      name: 'vesperCompactKeys',
+      addKeyboardShortcuts() {
+        return {
+          'Mod-k': () => {
+            setLinkOpen(true);
+            return true;
+          },
+          Escape: () => {
+            toolbar.current?.querySelector<HTMLElement>('button')?.focus();
+            return true;
+          },
+          // An inline field is one paragraph.
+          ...(inline ? { Enter: () => true, 'Shift-Enter': () => true } : {}),
+        };
+      },
+    }),
+  );
+
+  const editor = useEditor({
+    immediatelyRender: true,
+    shouldRerenderOnTransaction: false,
+    editable: !disabled,
+    extensions: [
+      StarterKit.configure({
+        heading: false,
+        blockquote: false,
+        codeBlock: false,
+        horizontalRule: false,
+        strike: false,
+        underline: false,
+        trailingNode: false,
+        ...(inline
+          ? { bulletList: false, orderedList: false, listItem: false, listKeymap: false }
+          : {}),
+        link: { openOnClick: false, autolink: true, defaultProtocol: 'https' },
+      }),
+      Markdown,
+      extras,
+    ],
+    editorProps: {
+      handleScrollToSelection: (view) => scrollClearOfToolbar(view, toolbar.current),
+      attributes: {
+        id,
+        role: 'textbox',
+        'aria-multiline': inline ? 'false' : 'true',
+        'aria-labelledby': `${id}-label`,
+        'aria-describedby': [describedBy, `${id}-md`].filter(Boolean).join(' '),
+        ...(invalid ? { 'aria-invalid': 'true' } : {}),
+        ...(field.required ? { 'aria-required': 'true' } : {}),
+        class: cx(
+          'vesper-body w-full px-3 py-2 text-body text-content outline-none',
+          inline ? 'min-h-10' : 'min-h-24',
+        ),
+      },
+    },
+    onCreate: ({ editor: created }) => {
+      const text = typeof value === 'string' ? value : '';
+      const markdown = created.markdown as MarkdownManager;
+      if (text !== '' && !fits(markdown, text, inline)) {
+        setPlain(true);
+        return;
+      }
+      created.commands.setContent(markdown.parse(text), { emitUpdate: false });
+    },
+    onUpdate: ({ editor: updated }) => {
+      const text = updated.getMarkdown().trim();
+      onChangeRef.current(text === '' && !field.required ? undefined : text);
+    },
+  });
+
+  const state = useEditorState({
+    editor,
+    selector: ({ editor: e }) => ({
+      bold: e.isActive('bold'),
+      italic: e.isActive('italic'),
+      code: e.isActive('code'),
+      link: e.isActive('link'),
+    }),
+  });
+
+  if (plain) {
+    return (
+      <>
+        <textarea
+          id={id}
+          rows={inline ? 2 : 5}
+          value={typeof value === 'string' ? value : ''}
+          onChange={(event) => {
+            onChange(event.target.value === '' && !field.required ? undefined : event.target.value);
+          }}
+          aria-describedby={[describedBy, `${id}-md`].filter(Boolean).join(' ')}
+          aria-invalid={invalid || undefined}
+          aria-required={field.required || undefined}
+          disabled={disabled}
+          className={cx(inputClass, 'resize-y font-mono text-small')}
+        />
+        <p id={`${id}-md`} className="text-small text-content-muted">
+          This uses Markdown the compact editor can’t show, so it’s edited as text.
+        </p>
+      </>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Framed like the body: the toolbar and the text in one hairline box. */}
+      <div
+        className={cx(
+          'rounded-md border border-border-strong bg-surface-raised',
+          invalid && 'border-danger',
+          disabled && 'opacity-60',
+          'has-[.ProseMirror-focused]:outline-2 has-[.ProseMirror-focused]:outline-solid has-[.ProseMirror-focused]:outline-offset-2 has-[.ProseMirror-focused]:outline-focus',
+          'has-[.ProseMirror-focused]:ring-6 has-[.ProseMirror-focused]:ring-(color:--glow-focus)',
+        )}
+      >
+        {/* Stuck below the bar while a long value scrolls, as the body's is. */}
+        <div ref={toolbar} className={stuckToolbar}>
+          <Toolbar label={`Formatting for ${field.label}`}>
+            <ToggleButton
+              icon="bold"
+              label="Bold"
+              shortcut={shortcut('Mod', 'B')}
+              isDisabled={disabled}
+              isSelected={state.bold}
+              onChange={() => editor.chain().focus().toggleBold().run()}
+            />
+            <ToggleButton
+              icon="italic"
+              label="Italic"
+              shortcut={shortcut('Mod', 'I')}
+              isDisabled={disabled}
+              isSelected={state.italic}
+              onChange={() => editor.chain().focus().toggleItalic().run()}
+            />
+            <ToggleButton
+              icon="code"
+              label="Code"
+              shortcut={shortcut('Mod', 'E')}
+              isDisabled={disabled}
+              isSelected={state.code}
+              onChange={() => editor.chain().focus().toggleCode().run()}
+            />
+            <ToolButton
+              icon="link"
+              label={state.link ? 'Edit link' : 'Link'}
+              shortcut={shortcut('Mod', 'K')}
+              isDisabled={disabled}
+              onPress={() => {
+                setLinkOpen(true);
+              }}
+            />
+          </Toolbar>
+        </div>
+        <EditorContent editor={editor} />
+      </div>
+      <p id={`${id}-md`} className="text-small text-content-muted">
+        Saved as Markdown. Escape moves to the formatting buttons.
+      </p>
+      <LinkDialog editor={editor} isOpen={linkOpen} onOpenChange={setLinkOpen} />
+    </div>
+  );
+}

package/src/widgets/reference.tsx

@@ -0,0 +1,196 @@
+import { isPlainObject, type DataValue, type EntrySummary, type FieldModel } from '@vespercms/core';
+import { Button, Combobox, type Option } from '@vespercms/ui';
+import { useMemo, useRef } from 'react';
+import { useStudio } from '../app/context.tsx';
+import { useLoad } from '../app/load.ts';
+import { useEditor } from '../editor/context.tsx';
+import type { WidgetProps } from '../types.ts';
+
+/*
+ * References (spec §6.2): pick entries of another collection by title. The
+ * file stores what Astro's reference() reads, an entry ID, and an existing
+ * `{ collection, id }` object keeps that shape.
+ */
+
+/** The ID a stored reference points at. */
+export function referenceId(value: DataValue): string | undefined {
+  if (typeof value === 'string') return value;
+  if (isPlainObject(value)) {
+    const id = value.id ?? value.slug;
+    if (typeof id === 'string') return id;
+  }
+  return undefined;
+}
+
+/** A new reference in the same shape as the old one. */
+function withId(previous: DataValue, id: string): DataValue {
+  return isPlainObject(previous) ? { ...previous, id } : id;
+}
+
+function useEntryOptions(collection: string | undefined) {
+  const { api, collection: find } = useStudio();
+  const editor = useEditor();
+  const [load] = useLoad<EntrySummary[]>(
+    () => (collection ? api.listEntries(collection) : Promise.resolve([])),
+    collection ?? '',
+  );
+  const entries = useMemo(() => (load.state === 'ready' ? load.value : []), [load]);
+  const options = useMemo(() => {
+    // An entry can't point at itself.
+    const others = entries.filter(
+      (e) => !(collection === editor.collection.name && e.id === editor.entryId),
+    );
+    const titles = new Map<string, number>();
+    for (const e of others) titles.set(e.title, (titles.get(e.title) ?? 0) + 1);
+    return others.map((e): Option => ({
+      value: e.id,
+      // Two entries with one title are told apart by their IDs.
+      label: (titles.get(e.title) ?? 0) > 1 ? `${e.title} (${e.id})` : e.title,
+    }));
+  }, [entries, collection, editor.collection.name, editor.entryId]);
+  const label = (collection ? find(collection)?.label : undefined) ?? collection ?? 'entries';
+  return { options, load, label };
+}
+
+function labelFor(options: Option[], id: string): string {
+  return options.find((o) => o.value === id)?.label ?? `${id} (not found)`;
+}
+
+function targetOf(field: FieldModel): string | undefined {
+  return field.reference?.collection ?? field.children?.[0]?.reference?.collection;
+}
+
+/** One reference: a searchable list of the other collection's entries. */
+export function ReferenceWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<DataValue>) {
+  const { options, load, label } = useEntryOptions(targetOf(field));
+  const current = referenceId(value);
+  const all =
+    current && !options.some((o) => o.value === current)
+      ? [...options, { value: current, label: labelFor(options, current) }]
+      : options;
+  return (
+    <Combobox
+      id={id}
+      aria-labelledby={`${id}-label`}
+      aria-describedby={describedBy}
+      options={all}
+      value={current ?? null}
+      onChange={(next) => {
+        onChange(next === null ? undefined : withId(value, next));
+      }}
+      placeholder={load.state === 'loading' ? 'Loading…' : `Search ${label.toLowerCase()}`}
+      isInvalid={invalid}
+      isDisabled={disabled}
+    />
+  );
+}
+
+/**
+ * Several references, in order. Order usually matters (related posts), so
+ * each has Move up, Move down and Remove buttons, and new ones are added
+ * from a search box at the end.
+ */
+export function ReferencesWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<DataValue[]>) {
+  const { options, load, label } = useEntryOptions(targetOf(field));
+  const items: DataValue[] = Array.isArray(value) ? value : [];
+  const ids = items.map(referenceId);
+  const status = useRef<HTMLParagraphElement>(null);
+  const announce = (text: string) => {
+    if (status.current) status.current.textContent = text;
+  };
+  const update = (next: DataValue[]) => {
+    onChange(next.length === 0 && !field.required ? undefined : next);
+  };
+  const move = (from: number, to: number) => {
+    const next = [...items];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    update(next);
+    announce(`Moved ${labelFor(options, referenceId(moved) ?? '')} to position ${String(to + 1)}.`);
+  };
+  const available = options.filter((o) => !ids.includes(o.value));
+
+  return (
+    <div className="flex flex-col gap-3">
+      {items.length > 0 && (
+        <ol className="flex flex-col divide-y divide-border border-y border-border">
+          {items.map((item, index) => {
+            const name = labelFor(options, referenceId(item) ?? '');
+            return (
+              <li
+                key={`${String(referenceId(item))}-${String(index)}`}
+                className="flex flex-wrap items-center gap-2 py-2"
+              >
+                <span className="min-w-0 flex-1">{name}</span>
+                <Button
+                  variant="quiet"
+                  isDisabled={disabled || index === 0}
+                  onPress={() => {
+                    move(index, index - 1);
+                  }}
+                  aria-label={`Move ${name} up`}
+                >
+                  Up
+                </Button>
+                <Button
+                  variant="quiet"
+                  isDisabled={disabled || index === items.length - 1}
+                  onPress={() => {
+                    move(index, index + 1);
+                  }}
+                  aria-label={`Move ${name} down`}
+                >
+                  Down
+                </Button>
+                <Button
+                  variant="quiet"
+                  isDisabled={disabled}
+                  onPress={() => {
+                    update(items.filter((_, i) => i !== index));
+                    announce(`Removed ${name}.`);
+                    document.getElementById(id)?.focus();
+                  }}
+                  aria-label={`Remove ${name}`}
+                >
+                  Remove
+                </Button>
+              </li>
+            );
+          })}
+        </ol>
+      )}
+      <Combobox
+        id={id}
+        aria-labelledby={`${id}-label`}
+        aria-describedby={describedBy}
+        options={available}
+        value={null}
+        onChange={(next) => {
+          if (next === null) return;
+          update([...items, next]);
+          announce(`Added ${labelFor(options, next)}.`);
+        }}
+        placeholder={load.state === 'loading' ? 'Loading…' : `Add from ${label.toLowerCase()}`}
+        isInvalid={invalid}
+        isDisabled={disabled}
+      />
+      <p ref={status} role="status" className="sr-only" />
+    </div>
+  );
+}

package/src/widgets/registry.ts

@@ -0,0 +1,104 @@
+import type { FieldKind, FieldModel } from '@vespercms/core';
+import type { ComponentType } from 'react';
+import type { ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+import {
+  DateWidget,
+  EmailWidget,
+  NumberWidget,
+  RadioWidget,
+  RawWidget,
+  SelectWidget,
+  SwitchWidget,
+  TagsWidget,
+  TextAreaWidget,
+  TextWidget,
+} from './basic.tsx';
+import { GeoWidget } from './geo.tsx';
+import { GroupWidget, RepeaterWidget } from './group.tsx';
+import { IconWidget } from './icon.tsx';
+import { FileWidget, ImageWidget } from './image.tsx';
+import { ReferencesWidget, ReferenceWidget } from './reference.tsx';
+import { LazyMarkdownWidget } from './markdown-lazy.tsx';
+import { ColorWidget, DateTimeWidget, SlugWidget, UrlWidget } from './special.tsx';
+import { UnionWidget } from './union.tsx';
+
+// Built-ins receive values of every shape; the registry can't be narrower.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BuiltinWidgetProps = WidgetProps<any> & {
+  path: ValuePath;
+  /** The field is a list item in its own row, which already names it (a union's kind). */
+  inRow?: boolean;
+};
+
+export type BuiltinWidget = {
+  component: ComponentType<BuiltinWidgetProps>;
+  /**
+   * Renders as a fieldset whose legend is the label (objects, lists, radio
+   * groups); `'boxed'` also draws a hairline around it (an image, a map).
+   */
+  group?: true | 'boxed';
+  /** Renders each child (or item) as its own field, so their errors show there. */
+  rendersChildren?: true;
+  /**
+   * At the form's first level it's a section: a hairline above, its own
+   * heading, more space (DECISIONS.md, "Top-level groups are sections").
+   * Deeper, an object is set off by an indent guide instead of a frame.
+   */
+  section?: true;
+  /** Ids of controls it renders for some of its children, as suffixes of its own id (`alt` → `-alt`). */
+  childControls?: Readonly<Record<string, string>>;
+};
+
+const BUILTIN: Record<string, BuiltinWidget> = {
+  text: { component: TextWidget },
+  textarea: { component: TextAreaWidget },
+  email: { component: EmailWidget },
+  url: { component: UrlWidget },
+  number: { component: NumberWidget },
+  switch: { component: SwitchWidget },
+  date: { component: DateWidget },
+  datetime: { component: DateTimeWidget },
+  select: { component: SelectWidget },
+  radio: { component: RadioWidget, group: true },
+  icon: { component: IconWidget },
+  tags: { component: TagsWidget },
+  multiselect: { component: TagsWidget },
+  group: { component: GroupWidget, group: true, rendersChildren: true, section: true },
+  union: { component: UnionWidget, group: true, rendersChildren: true, section: true },
+  repeater: { component: RepeaterWidget, group: true, rendersChildren: true, section: true },
+  raw: { component: RawWidget },
+  markdown: { component: LazyMarkdownWidget },
+  slug: { component: SlugWidget },
+  color: { component: ColorWidget },
+  geo: { component: GeoWidget, group: 'boxed' },
+  reference: { component: ReferenceWidget },
+  references: { component: ReferencesWidget, group: true },
+  image: { component: ImageWidget, group: 'boxed', childControls: { alt: '-alt' } },
+  file: { component: FileWidget, group: true },
+};
+
+const BY_KIND: Partial<Record<FieldKind, string>> = {
+  string: 'text',
+  number: 'number',
+  boolean: 'switch',
+  date: 'date',
+  enum: 'select',
+  object: 'group',
+  union: 'union',
+  array: 'repeater',
+  reference: 'reference',
+  image: 'image',
+};
+
+/**
+ * The built-in control for a field: its resolved widget, else the one its
+ * type implies (spec §6.3 step 3), else the raw YAML field (step 4).
+ */
+export function builtinWidget(field: FieldModel): BuiltinWidget {
+  for (const name of [field.widget, field.inferredWidget, BY_KIND[field.kind]]) {
+    const widget = name ? BUILTIN[name] : undefined;
+    if (widget) return widget;
+  }
+  return BUILTIN.raw as BuiltinWidget;
+}