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

package/src/editor/PagePicker.tsx

@@ -0,0 +1,102 @@
+import type { PageLink } from '@vespercms/core';
+import { Button, Combobox, Dialog } from '@vespercms/ui';
+import { useEffect, useMemo, useState } from 'react';
+import type { StudioApi } from '../app/api.ts';
+import { useStudio } from '../app/context.tsx';
+
+/*
+ * The link picker (spec §6.15.6): editors find a page by its title, and the
+ * editor writes that page's current address. Content stays plain Markdown
+ * or a plain string, and a move later rewrites the link.
+ */
+
+const cache = new WeakMap<StudioApi, Promise<PageLink[]>>();
+
+/** Every page with a URL on the site, loaded once per studio. Empty until it arrives, or if it fails. */
+export function usePages(): PageLink[] {
+  const { api } = useStudio();
+  const [pages, setPages] = useState<PageLink[]>([]);
+  useEffect(() => {
+    let live = true;
+    let pending = cache.get(api);
+    if (!pending) {
+      pending = api.listPages();
+      cache.set(api, pending);
+    }
+    pending.then(
+      (found) => {
+        if (live) setPages(found);
+      },
+      () => {
+        // Without the list, links are typed by hand, as before.
+        cache.delete(api);
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [api]);
+  return pages;
+}
+
+/** Pages as link suggestions: found by title, inserted as their address. */
+export function pageSuggestions(pages: readonly PageLink[]) {
+  return pages.map((page) => ({ value: page.url, label: page.title, detail: page.url }));
+}
+
+/**
+ * "Choose a page…" beside a URL field: a dialog with a searchable list of
+ * pages. `absolute` puts the site's address in front, for fields whose
+ * schema accepts only full URLs.
+ */
+export function ChoosePageButton({
+  onPick,
+  absolute,
+  fieldLabel,
+  isDisabled,
+}: {
+  onPick: (url: string) => void;
+  absolute?: string;
+  fieldLabel: string;
+  isDisabled?: boolean;
+}) {
+  const pages = usePages();
+  const [open, setOpen] = useState(false);
+  const options = useMemo(
+    () =>
+      pages.map((page) => ({
+        value: absolute ? new URL(page.url, absolute).href : page.url,
+        label: `${page.title} (${page.url})`,
+      })),
+    [pages, absolute],
+  );
+  if (pages.length === 0) return null;
+  return (
+    <>
+      <Button
+        variant="quiet"
+        {...(isDisabled ? { isDisabled } : {})}
+        onPress={() => {
+          setOpen(true);
+        }}
+        aria-label={`Choose a page for ${fieldLabel}`}
+      >
+        Choose a page…
+      </Button>
+      <Dialog title="Choose a page" isOpen={open} onOpenChange={setOpen}>
+        <Combobox
+          label="Page"
+          description="Search by title. Its address goes in the field."
+          options={options}
+          value={null}
+          onChange={(value) => {
+            if (value) {
+              onPick(value);
+              setOpen(false);
+            }
+          }}
+        />
+      </Dialog>
+    </>
+  );
+}

package/src/editor/arrange.ts

@@ -0,0 +1,98 @@
+import type { CollectionManifest, FieldModel } from '@vespercms/core';
+import { keyOf } from './values.ts';
+
+/*
+ * Where each field goes in the editor (spec §10.3, and DECISIONS.md, "The
+ * entry editor has tabs"): the title as the document heading, above the
+ * tabs; the main fields on Content, in schema order; secondary frontmatter
+ * on Details; and fields placed on a tab vesper.config.ts declares, on that
+ * tab. A field's `placement` (from `.meta()` or vesper.config.ts) always
+ * wins; otherwise slugs, dates, tags, ordering, SEO fields and scheduling
+ * go to Details.
+ * "Hide from site search" is absent, not disabled, where the collection
+ * isn't searched or has no pages (spec §6.19): the manifest then names no
+ * `searchHidden` field.
+ */
+
+const TITLE_KEYS = ['title', 'name', 'heading', 'label'];
+
+const DETAIL_KEYS = new Set([
+  'slug',
+  'tags',
+  'draft',
+  'order',
+  'weight',
+  'sort',
+  'layout',
+  'template',
+  'permalink',
+  'canonical',
+  'canonicalurl',
+  'noindex',
+  'nofollow',
+  'aliases',
+  'redirects',
+  'seo',
+  'meta',
+]);
+
+const DETAIL_WIDGETS = new Set(['slug', 'date', 'datetime', 'tags']);
+
+export type ArrangedFields = {
+  title: FieldModel | undefined;
+  main: FieldModel[];
+  details: FieldModel[];
+  /** The collection's own tabs, in the order it declares them, each with its fields. */
+  tabs: { id: string; label: string; fields: FieldModel[] }[];
+};
+
+export function arrangeFields(collection: CollectionManifest): ArrangedFields {
+  const searched = collection.presentation.searchHidden !== undefined;
+  const fields = (collection.fields ?? []).filter(
+    (field) => !field.hidden && (searched || field.search !== 'hide'),
+  );
+  const title = fields.find(
+    (field) =>
+      field.kind === 'string' && TITLE_KEYS.includes(keyOf(field)) && field.placement !== 'details',
+  );
+  const schedule = collection.presentation.schedule;
+  // Where visitors go once it comes down belongs with the times.
+  const scheduled = new Set(
+    schedule
+      ? [
+          schedule.publishAt,
+          schedule.unpublishAt,
+          schedule.unpublishRedirect ?? 'unpublishRedirect',
+        ]
+      : [],
+  );
+
+  const main: FieldModel[] = [];
+  const details: FieldModel[] = [];
+  const tabs = (collection.presentation.tabs ?? []).map((tab) => ({
+    ...tab,
+    fields: [] as FieldModel[],
+  }));
+  for (const field of fields) {
+    if (field === title) continue;
+    const own = tabs.find((tab) => tab.id === field.placement);
+    if (own) own.fields.push(field);
+    else if (field.placement === 'main') main.push(field);
+    else if (field.placement === 'details' || isDetail(field, scheduled)) details.push(field);
+    else main.push(field);
+  }
+  return { title, main, details, tabs: tabs.filter((tab) => tab.fields.length > 0) };
+}
+
+function isDetail(field: FieldModel, scheduled: ReadonlySet<string>): boolean {
+  const key = keyOf(field);
+  const lower = key.toLowerCase();
+  return (
+    scheduled.has(key) ||
+    DETAIL_KEYS.has(lower) ||
+    field.kind === 'date' ||
+    DETAIL_WIDGETS.has(field.widget ?? '') ||
+    /^(seo|meta|og)[A-Z_]|^seo$|Seo$/.test(key) ||
+    /(At|On|Date)$/.test(key)
+  );
+}

package/src/editor/context.tsx

@@ -0,0 +1,31 @@
+import type { A11yNote, CollectionManifest, DataObject, DataValue } from '@vespercms/core';
+import { createContext, useContext } from 'react';
+import type { ValuePath } from './values.ts';
+
+/** What every field in the open entry shares. */
+export type EditorState = {
+  collection: CollectionManifest;
+  values: DataObject;
+  setValue: (path: ValuePath, value: DataValue) => void;
+  /** Validation messages by `pathKey`, from the last save. */
+  issues: ReadonlyMap<string, readonly string[]>;
+  /** Accessibility notes by `pathKey` of the field they're shown under (spec §6.18). */
+  notes?: ReadonlyMap<string, readonly A11yNote[]>;
+  disabled: boolean;
+  /** The entry hasn't been saved yet. */
+  isNew: boolean;
+  /** The entry's file, site-relative; for a new entry, where it will most likely be saved. */
+  entryPath: string;
+  /** The open entry's ID (`null` until a new entry is saved). */
+  entryId: string | null;
+  /** Prefix for field ids in a form that isn't the entry's own (a block's settings). */
+  idPrefix?: string;
+};
+
+export const EditorContext = createContext<EditorState | null>(null);
+
+export function useEditor(): EditorState {
+  const editor = useContext(EditorContext);
+  if (!editor) throw new Error('useEditor() must be used inside an entry editor.');
+  return editor;
+}

package/src/editor/copy.ts

@@ -0,0 +1,30 @@
+import type { CollectionManifest, DataObject } from '@vespercms/core';
+import { arrangeFields } from './arrange.ts';
+import { keyOf } from './values.ts';
+
+/**
+ * A copy's starting values (Duplicate, spec §10.3): every value as it is,
+ * " (copy)" after the title, and the fields that hold the entry's own address
+ * left empty so the copy gets its own. Those are the slug widget's, which then
+ * follow the new title, and a top-level `slug`, which Astro takes as the
+ * entry's ID. Images are shared, so their focal points and crops come along.
+ */
+export function copiedValues(collection: CollectionManifest, values: DataObject): DataObject {
+  const title = arrangeFields(collection).title;
+  const titleKey = title ? keyOf(title) : null;
+  const addresses = new Set([
+    'slug',
+    ...(collection.fields ?? [])
+      .filter((field) => field.path.length === 1 && field.widget === 'slug')
+      .map(keyOf),
+  ]);
+  return Object.fromEntries(
+    Object.entries(values)
+      .filter(([key]) => !addresses.has(key))
+      .map(([key, value]) =>
+        key === titleKey && typeof value === 'string' && value.trim() !== ''
+          ? [key, `${value} (copy)`]
+          : [key, value],
+      ),
+  );
+}

package/src/editor/reveal.ts

@@ -0,0 +1,38 @@
+/*
+ * A field inside a closed list item is in the page but hidden (the item's
+ * panel is `hidden="until-found"`). Going to it — from the error summary or
+ * the notes drawer — first asks every closed item around it to open: the
+ * event bubbles from the field through each list it's nested in, and each
+ * list opens the item it passes through (DECISIONS.md, "Top-level groups are
+ * sections, and list items are rows that open in place").
+ */
+
+export const REVEAL_EVENT = 'vesper:reveal';
+
+/** True while `element` or something around it is hidden: a closed item, or a tab not chosen. */
+function isHidden(element: Element): boolean {
+  return element.closest('[hidden], [inert]') !== null;
+}
+
+/**
+ * Focuses an element as soon as it's on screen (a field on another tab
+ * shows once its tab is chosen; one inside a closed list item, once the
+ * item opens), and scrolls it into view.
+ */
+export function focusWhenShown(id: string, tries = 20, asked = false): void {
+  const element = document.getElementById(id);
+  if (element && !isHidden(element)) {
+    element.scrollIntoView({ block: 'center' });
+    element.focus();
+    return;
+  }
+  if (element && !asked) {
+    element.dispatchEvent(new CustomEvent(REVEAL_EVENT, { bubbles: true }));
+    asked = true;
+  }
+  if (tries > 0) {
+    setTimeout(() => {
+      focusWhenShown(id, tries - 1, asked);
+    }, 25);
+  }
+}

package/src/editor/target.ts

@@ -0,0 +1,104 @@
+import {
+  fieldChildren,
+  isPlainObject,
+  type DataValue,
+  type FieldIssue,
+  type FieldModel,
+} from '@vespercms/core';
+import { itemNames } from '../widgets/group.tsx';
+import { builtinWidget } from '../widgets/registry.ts';
+import { kindRow } from '../widgets/union.tsx';
+import { fieldId, keyOf, type ValuePath } from './values.ts';
+
+/**
+ * Where an issue is shown: the deepest field on screen along its path. An
+ * issue inside a raw field, or in a nested value no control shows, lands on
+ * the nearest field that is shown.
+ */
+export function issueTarget(
+  fields: readonly FieldModel[],
+  path: FieldIssue['path'],
+): { path: ValuePath; focusId: string; label: string } {
+  let models: readonly FieldModel[] = fields;
+  let model: FieldModel | undefined;
+  const matched: (string | number)[] = [];
+  for (const segment of path) {
+    if (typeof segment === 'number') {
+      const item = model?.kind === 'array' ? model.children?.[0] : undefined;
+      if (!item || !usesChildren(model)) break;
+      model = item;
+      models = fieldChildren(item);
+    } else {
+      // A kind's fields are found by key among every kind's: their ids come from the value's path.
+      const next = models.find((candidate) => keyOf(candidate) === segment);
+      if (!next || (model && !usesChildren(model))) break;
+      model = next;
+      models = fieldChildren(next);
+    }
+    matched.push(segment);
+  }
+  if (!model) return { path: [], focusId: 'main', label: 'Entry' };
+  const id = fieldId(matched);
+  const widget = builtinWidget(model);
+  // A widget that draws its own control for the child at fault (an image's alt text) gets focus there.
+  const child = path[matched.length];
+  const childSuffix = typeof child === 'string' ? widget.childControls?.[child] : undefined;
+  const childLabel = models.find((m) => keyOf(m) === child)?.label;
+  return {
+    path: matched,
+    focusId: childSuffix ? `${id}${childSuffix}` : widget.group ? `${id}-label` : id,
+    label: childSuffix && childLabel ? `${model.label}, ${childLabel.toLowerCase()}` : model.label,
+  };
+}
+
+/** Whether a field's widget shows its children as their own fields (groups and repeaters do). */
+function usesChildren(field: FieldModel | undefined): boolean {
+  if (!field) return true;
+  return builtinWidget(field).rendersChildren === true;
+}
+
+/**
+ * Where an issue is, in words, for a list of notes away from the form:
+ * "Section 2 (Showcase) › Image, alt". Beside its field, the field's own
+ * label is enough, but in the notes drawer two images in blocks would both
+ * read "Image, alt". A list item is named by its place and, in blocks, its
+ * kind, which says the list's name too ("Section 2"), so the list's own
+ * label is left out before it.
+ */
+export function issuePlace(
+  fields: readonly FieldModel[],
+  path: FieldIssue['path'],
+  values: DataValue,
+): string {
+  const target = issueTarget(fields, path);
+  const parts: string[] = [];
+  let models: readonly FieldModel[] = fields;
+  let model: FieldModel | undefined;
+  let value: DataValue | undefined = values;
+  for (const segment of target.path) {
+    if (typeof segment === 'number') {
+      const item = model?.children?.[0];
+      if (!model || !item) break;
+      const held = Array.isArray(value) ? value[segment] : undefined;
+      const one = itemNames(model).one;
+      const kind = item.kind === 'union' ? ` (${kindRow(held ?? null, item).name})` : '';
+      parts.pop();
+      parts.push(
+        `${one.charAt(0).toLocaleUpperCase()}${one.slice(1)} ${String(segment + 1)}${kind}`,
+      );
+      model = item;
+      models = fieldChildren(item);
+      value = held;
+    } else {
+      const next = models.find((candidate) => keyOf(candidate) === segment);
+      if (!next) break;
+      parts.push(next.label);
+      model = next;
+      models = fieldChildren(next);
+      value = isPlainObject(value) ? value[segment] : undefined;
+    }
+  }
+  // The field itself keeps the name it has beside the control ("Image, alt").
+  if (typeof target.path.at(-1) === 'string') parts.splice(-1, 1, target.label);
+  return parts.length > 0 ? parts.join(' › ') : target.label;
+}

package/src/editor/values.ts

@@ -0,0 +1,71 @@
+import { isPlainObject, type DataObject, type DataValue, type FieldModel } from '@vespercms/core';
+
+/** A concrete path into an entry's values: keys and array indexes. */
+export type ValuePath = readonly (string | number)[];
+
+export function getIn(root: DataValue, path: ValuePath): DataValue {
+  let current: DataValue = root;
+  for (const segment of path) {
+    if (typeof segment === 'number') {
+      current = Array.isArray(current) ? current[segment] : undefined;
+    } else {
+      current = isPlainObject(current) ? current[segment] : undefined;
+    }
+    if (current === undefined) return undefined;
+  }
+  return current;
+}
+
+/**
+ * Returns a copy of `root` with the value at `path` replaced. `undefined`
+ * removes an object key (the file then loses that line) and leaves array
+ * items in place. Missing parents are created.
+ */
+export function setIn(root: DataObject, path: ValuePath, value: DataValue): DataObject {
+  return setAt(root, path, 0, value) as DataObject;
+}
+
+function setAt(node: DataValue, path: ValuePath, index: number, value: DataValue): DataValue {
+  if (index === path.length) return value;
+  const segment = path[index] as string | number;
+  if (typeof segment === 'number') {
+    const list = Array.isArray(node) ? [...node] : [];
+    list[segment] = setAt(list[segment], path, index + 1, value);
+    return list;
+  }
+  const object: DataObject = isPlainObject(node) ? { ...node } : {};
+  const next = setAt(object[segment], path, index + 1, value);
+  if (next === undefined) Reflect.deleteProperty(object, segment);
+  else object[segment] = next;
+  return object;
+}
+
+/** A DOM id for the control at `path`: stable, unique per entry, and safe in selectors. */
+export function fieldId(path: ValuePath, prefix = 'field'): string {
+  // Segments joined with dots, and no hyphens anywhere: ids built by adding
+  // `-label`, `-help` and so on to a field's id can then never equal another
+  // field's id (a group's `-label` legend and a child field called `label`).
+  // A form other than the entry's (a block's settings) uses its own prefix.
+  return `${prefix}.${path.map((s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')).join('.')}`;
+}
+
+/** Key for matching validation issues to fields. */
+export function pathKey(path: ValuePath): string {
+  return path.map(String).join('.');
+}
+
+/** A field model's own key: the last segment of its path (`'[]'` for array items). */
+export function keyOf(field: FieldModel): string {
+  return field.path.at(-1) ?? '';
+}
+
+/** The value a new entry starts with: each field's static default, where it has one. */
+export function initialValues(fields: readonly FieldModel[] | null): DataObject {
+  const values: DataObject = {};
+  for (const field of fields ?? []) {
+    if (field.default !== undefined && !field.defaultDynamic) {
+      values[keyOf(field)] = structuredClone(field.default) as DataValue;
+    }
+  }
+  return values;
+}