astro-dev-edit 0.11.0

package/src/client/editors/fields.ts

@@ -0,0 +1,309 @@
+import type { FieldDescriptor, FieldType } from '../../shared/protocol.ts';
+import { inputEl, styled } from '../ui.ts';
+import { buildImageField } from './asset-picker.ts';
+
+/**
+ * Field controls for the entry drawer *and* the Settings drawer: one builder per
+ * FieldType, looked up through a registry (mirroring src/patcher/registry.ts).
+ * Adding a widget = add the FieldType to protocol.ts, register a builder here,
+ * and (if it should be schema-derived rather than config-forced) map it in
+ * server/schema-introspect.ts. Unknown types degrade to the read-only `json`
+ * builder, so a stale client never crashes on a new wire value.
+ *
+ * The Settings drawer describes each integration option as a synthesized
+ * {@link FieldDescriptor} and comes through here too, rather than growing a
+ * parallel control system. That is what `readOnly` and `help` on the descriptor
+ * are for: an option `astro.config.mjs` owns must render disabled (accepting
+ * input for a value resolution would discard is a lie), and an option needs a
+ * line of prose next to it far more often than a frontmatter key does.
+ */
+
+export interface FieldControl {
+  field: FieldDescriptor;
+  root: HTMLElement;
+  /** Current wire value for this field. */
+  value(): unknown;
+  /** Whether the user changed it from its initial state. */
+  dirty(): boolean;
+  setError(message: string | null): void;
+}
+
+/** Grey out and block input on every control a builder mounted. Applied after
+ *  the builder runs, so no builder has to know about `readOnly` — including the
+ *  image picker, whose button is not an input at all. */
+function lockControls(root: HTMLElement): void {
+  for (const el of root.querySelectorAll('input, textarea, select, button')) {
+    (el as HTMLInputElement | HTMLButtonElement).disabled = true;
+  }
+  root.dataset.locked = '';
+}
+
+/** What a builder must supply; buildControl adds the label/error chrome. */
+interface ControlParts {
+  value(): unknown;
+  dirty(): boolean;
+}
+
+interface ControlContext {
+  field: FieldDescriptor;
+  /** Raw parsed frontmatter value (undefined for a new entry). */
+  raw: unknown;
+  /** `raw` rendered for display (see displayValue). */
+  initial: string;
+  /** Schema-default hint shown when the key is absent from the file. */
+  placeholder: string;
+  /** Mount point: append the control's element(s) here. */
+  root: HTMLElement;
+  /** Repo-relative path of the entry being edited; '' for a new one. Needed by
+   *  controls whose values are relative to the file (see FieldDescriptor.assetRef). */
+  entryFile: string;
+}
+
+type ControlBuilder = (ctx: ControlContext) => ControlParts;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+
+/** Initial display value for a control, from the parsed frontmatter. */
+function displayValue(field: FieldDescriptor, raw: unknown): string {
+  if (raw === undefined || raw === null) return '';
+  if (field.type === 'tags' && Array.isArray(raw)) return raw.join(', ');
+  if (field.type === 'json') return JSON.stringify(raw, null, 2);
+  return String(raw);
+}
+
+// --- builders ----------------------------------------------------------------
+
+/** text / date / number / tags share a plain input. */
+const plainInput: ControlBuilder = ({ field, initial, placeholder, root }) => {
+  const input = inputEl('input', 'atx-field-input');
+  if (field.type === 'date' && (initial === '' || DATE_RE.test(initial))) {
+    input.type = 'date';
+    input.value = initial.slice(0, 10);
+  } else if (field.type === 'number') {
+    input.type = 'number';
+    input.value = initial;
+  } else {
+    input.type = 'text';
+    input.value = initial;
+  }
+  input.placeholder = placeholder;
+  const started = input.value;
+  root.append(input);
+  return {
+    value: () => {
+      if (field.type === 'number') return input.value === '' ? '' : Number(input.value);
+      if (field.type === 'tags') {
+        return input.value.split(',').map((s) => s.trim()).filter(Boolean);
+      }
+      return input.value;
+    },
+    dirty: () => input.value !== started,
+  };
+};
+
+const checkbox: ControlBuilder = ({ field, raw, root }) => {
+  // A span, not a label: wrapping the input in one would make the state word
+  // the control's accessible name — "On", where the field's own label says
+  // which thing is on. The words describe the box; the field label names it.
+  const wrap = styled('span', 'atx-field-check');
+  const input = styled('input', 'atx-field-input atx-field-checkbox');
+  input.type = 'checkbox';
+  input.checked = raw === true;
+  // A bare checkbox reads as unfinished UI, so the box is always accompanied by
+  // words: "not set" while the key is absent from the file (the state the entry
+  // drawer has to distinguish), and the plain on/off state once it is not.
+  // An absent key is not Off — the schema's default is what will apply — so the
+  // words say which default that is, and go back to saying it if the box is
+  // ticked and unticked again.
+  const hint = styled('span', 'atx-field-check-hint');
+  const stateWord = (): string => (input.checked ? 'On' : 'Off');
+  const unsetWord =
+    field.defaultValue === undefined
+      ? 'not set'
+      : `not set — defaults to ${field.defaultValue === true ? 'On' : 'Off'}`;
+  const render = (): void => {
+    hint.textContent = !field.present && !input.checked ? unsetWord : stateWord();
+  };
+  render();
+  input.addEventListener('change', render);
+  wrap.append(input, hint);
+  root.append(wrap);
+  return {
+    value: () => input.checked,
+    dirty: () => input.checked !== (raw === true),
+  };
+};
+
+const select: ControlBuilder = ({ field, initial, placeholder, root }) => {
+  const el = inputEl('select', 'atx-field-input atx-field-select');
+  const opts = [...(field.options ?? [])];
+  if (initial && !opts.includes(initial)) opts.unshift(initial);
+  if (!field.present) {
+    const blank = document.createElement('option');
+    blank.value = '';
+    blank.textContent = placeholder || '—';
+    el.append(blank);
+  }
+  for (const o of opts) {
+    const opt = document.createElement('option');
+    opt.value = o;
+    opt.textContent = o;
+    el.append(opt);
+  }
+  el.value = initial;
+  root.append(el);
+  return { value: () => el.value, dirty: () => el.value !== initial };
+};
+
+const textarea: ControlBuilder = ({ initial, placeholder, root }) => {
+  const input = inputEl('textarea', 'atx-field-input atx-field-textarea');
+  input.value = initial;
+  input.placeholder = placeholder;
+  root.append(input);
+  return { value: () => input.value, dirty: () => input.value !== initial };
+};
+
+const image: ControlBuilder = ({ field, initial, root, entryFile }) => {
+  let current = initial;
+  root.append(
+    buildImageField({
+      initial,
+      onChange: (next) => (current = next),
+      // An image() field stores a path relative to the entry file, not a web
+      // URL — the control resolves previews and writes picks in that shape.
+      ...(field.assetRef ? { assetRef: field.assetRef, entryFile } : {}),
+    }),
+  );
+  return { value: () => current, dirty: () => current !== initial };
+};
+
+/** Shapes the panel can't edit render read-only; saves never touch them. */
+const json: ControlBuilder = ({ raw, initial, root }) => {
+  const input = inputEl('textarea', 'atx-field-input atx-field-json');
+  input.value = initial;
+  input.readOnly = true;
+  input.title = 'This field has a shape the panel can’t edit — change it in the file.';
+  root.append(input);
+  return { value: () => raw, dirty: () => false };
+};
+
+const CONTROL_BUILDERS: Record<FieldType, ControlBuilder> = {
+  text: plainInput,
+  date: plainInput,
+  number: plainInput,
+  tags: plainInput,
+  boolean: checkbox,
+  select,
+  textarea,
+  image,
+  json,
+};
+
+// --- assembly ----------------------------------------------------------------
+
+/** Ids are only ever looked up inside the overlay's shadow root, so a counter
+ *  is enough to keep `for`/`aria-describedby` unambiguous. */
+let controlSeq = 0;
+
+export function buildControl(
+  field: FieldDescriptor,
+  raw: unknown,
+  entryFile = '',
+): FieldControl {
+  const root = styled('div', 'atx-field');
+  const id = `atx-field-${++controlSeq}`;
+
+  const label = styled('label', 'atx-field-label');
+  label.textContent = field.required ? `${field.label} *` : field.label;
+  label.htmlFor = id;
+  root.append(label);
+
+  const error = styled('div', 'atx-field-error');
+  // A live region, so the message is announced when it appears rather than
+  // only being found by someone who happens to navigate back over the field.
+  error.role = 'alert';
+  const setError = (message: string | null): void => {
+    error.textContent = message ?? '';
+    error.toggleAttribute('data-on', Boolean(message));
+    // The destructive border is drawn from aria-invalid rather than from a
+    // class of its own, so the thing a screen reader is told and the thing the
+    // eye is shown are the same fact instead of two that can disagree.
+    for (const el of root.querySelectorAll('[data-input]')) {
+      if (message) el.setAttribute('aria-invalid', 'true');
+      else el.removeAttribute('aria-invalid');
+    }
+  };
+
+  const initial = displayValue(field, raw);
+  const placeholder =
+    !field.present && field.defaultValue !== undefined
+      ? `${displayValue({ ...field, present: true }, field.defaultValue)} (default)`
+      : '';
+
+  const builder = CONTROL_BUILDERS[field.type] ?? json;
+  const parts = builder({ field, raw, initial, placeholder, root, entryFile });
+
+  // The visible label has to *be* the control's name, not a sibling that reads
+  // like one: a builder mounts whatever it likes, so the association is made
+  // here, on the first form element it mounted. That is the control proper in
+  // every builder — the image field's preview and Browse are buttons around
+  // its path input, and both open the same picker the label's click does not
+  // need to.
+  const control = root.querySelector('input, textarea, select');
+  if (control) control.id = id;
+
+  // Anything that qualifies the control rather than naming it is a description:
+  // the help line, and the checkbox's state word, which says "not set" where
+  // the box alone can only say unticked.
+  const described: string[] = [];
+  const hint = root.querySelector('.atx-field-check-hint');
+  if (hint) {
+    hint.id = `${id}-state`;
+    described.push(hint.id);
+  }
+
+  if (field.help) {
+    const help = styled('div', 'atx-field-help');
+    help.id = `${id}-help`;
+    help.textContent = field.help;
+    root.append(help);
+    described.push(help.id);
+  }
+
+  error.id = `${id}-error`;
+  described.push(error.id);
+  if (control) control.setAttribute('aria-describedby', described.join(' '));
+
+  root.append(error);
+
+  if (field.readOnly) {
+    lockControls(root);
+    // Reported clean regardless of what the control holds: a locked field can
+    // never contribute to a save, so `collectChanges` must not see it.
+    return { field, root, value: parts.value, dirty: () => false, setError };
+  }
+  return { field, root, value: parts.value, dirty: parts.dirty, setError };
+}
+
+/** The frontmatter payload for changed fields only. Clearing an optional
+ *  field maps to null (= remove the key); required fields send '' and let the
+ *  server's schema validation answer. */
+export function collectChanges(controls: FieldControl[]): Record<string, unknown> {
+  const changes: Record<string, unknown> = {};
+  for (const c of controls) {
+    if (!c.dirty()) continue;
+    const v = c.value();
+    const emptied = v === '' || (Array.isArray(v) && v.length === 0);
+    if (emptied && !c.field.required && c.field.present) changes[c.field.name] = null;
+    else if (emptied && !c.field.present) continue; // never present, still empty
+    else changes[c.field.name] = v;
+  }
+  return changes;
+}
+
+export function applyFieldErrors(
+  controls: FieldControl[],
+  fieldErrors: Record<string, string>,
+): void {
+  for (const c of controls) c.setError(fieldErrors[c.field.name] ?? null);
+}

package/src/client/editors/image.ts

@@ -0,0 +1,268 @@
+import type { ApplyOp, AssetInfo, AttrState, SourceLoc } from '../../shared/protocol.ts';
+import * as api from '../api.ts';
+import { clearHighlight } from '../hover.ts';
+import { trapFocus } from '../focus.ts';
+import * as state from '../state.ts';
+import { icon } from '../icons.ts';
+import {
+  basename,
+  buildBackdrop,
+  buildPanel,
+  footButton,
+  lockElement,
+  setFreshSrc,
+  styled,
+  toast,
+  wirePanelButtons,
+} from '../ui.ts';
+import { openMediaModal } from './media-modal.ts';
+import { webPathToUrl } from '../../shared/asset-path.ts';
+import { mount } from '../shadow.ts';
+
+/**
+ * Image swap panel: a preview of the image as it is now, its alt text, and a
+ * way to replace it.
+ *
+ * It stopped being a browser. Picking from hundreds of project images (or from
+ * Unsplash) is the media modal's job; this panel keeps only what belongs to
+ * *this* element — the preview, the alt field, and a strip of the few most
+ * recently added images for the common "swap in the thing I just uploaded"
+ * case, with `Browse all` opening the modal for everything else.
+ *
+ * Only statically-quoted attributes are patchable; a missing alt can be added.
+ * (spec §6.3)
+ */
+
+/** How many recent images the quick strip offers before you need the modal. */
+const RECENTS = 6;
+
+export async function beginImageEdit(
+  img: HTMLImageElement,
+  src: SourceLoc,
+  attrs: { src: AttrState; alt: AttrState },
+): Promise<void> {
+  clearHighlight();
+  const originalSrc = img.getAttribute('src') ?? '';
+  const originalAlt = img.getAttribute('alt') ?? '';
+  // Only statically-quoted attributes can be patched; expression values must be
+  // edited in the source. A missing alt can be added (img only). (spec §6.3)
+  const srcEditable = attrs.src === 'static';
+  const altEditable = attrs.alt !== 'dynamic';
+
+  const panel = buildPanel(`Image · ${basename(src.file)}:${src.loc}`, undefined, {
+    width: 'min(520px, 92vw)',
+  });
+  const body = panel.querySelector('[data-body]') as HTMLElement;
+
+  /**
+   * What the panel will save, in two shapes, because the picker's path and the
+   * attribute are not the same string.
+   *
+   * `chosenSrc` is the **web path** — what `/assets` lists and what the modal
+   * matches its selection against, so every comparison here uses it.
+   * `chosenSrcAttr` is that path in **URL form**, which is what goes into the
+   * source file. They differ only for a filename holding a character a URL path
+   * must encode; a space is the one that turns up. Both start as what the
+   * element already has, which is already a URL and is never re-encoded — a
+   * hand-written `%20` must survive an alt-only save untouched.
+   */
+  let chosenSrc = originalSrc;
+  let chosenSrcAttr = originalSrc;
+
+  // --- preview ---------------------------------------------------------------
+  // Shown even when the file cannot be swapped: writing alt text for an image
+  // you cannot see is the exact problem this fixes, and the preview is read
+  // from the DOM rather than from anything patchable.
+  const preview = styled('div', 'atx-image-preview');
+  const previewImg = styled('img', 'atx-image-preview-img');
+  previewImg.alt = '';
+  previewImg.decoding = 'async';
+  // A path that fails to load hides rather than showing a broken-image icon;
+  // a retry that finally succeeds undoes that — see ui.ts::setFreshSrc.
+  previewImg.addEventListener('error', () => previewImg.toggleAttribute('data-hidden', true));
+  previewImg.addEventListener('load', () => previewImg.toggleAttribute('data-hidden', false));
+  preview.append(previewImg);
+
+  const meta = styled('p', 'atx-image-meta');
+
+  /** `fresh` marks a file written seconds ago, which needs the retrying loader;
+   *  `path` is always the clean value the metadata line and the save refer to. */
+  const setPreview = (path: string, fresh = false): void => {
+    if (fresh) setFreshSrc(previewImg, path);
+    else previewImg.src = path;
+    meta.textContent = path ? basename(path) : '';
+    meta.title = path;
+  };
+  setPreview(originalSrc);
+  body.append(preview, meta);
+
+  if (!srcEditable) {
+    const note = styled('p', 'atx-note');
+    note.textContent =
+      'The image file is set from code (an expression or astro:assets), so it can’t be swapped here — only the alt text can be edited.';
+    body.append(note);
+  }
+
+  // --- alt text --------------------------------------------------------------
+  const altLabel = styled('label', 'atx-alt-label');
+  altLabel.textContent = 'Alt text';
+  const altInput = styled('input', 'atx-alt-input');
+  altInput.value = originalAlt;
+  if (!altEditable) {
+    altInput.disabled = true;
+    altInput.title = 'The alt text is set from an expression — edit it in the source.';
+    altInput.toggleAttribute('data-off', true);
+  }
+  body.append(altLabel, altInput);
+
+  const close = (commit: boolean): void => {
+    state.releaseIf(token);
+    releaseFocus();
+    panel.remove();
+    backdrop.remove();
+    if (!commit) {
+      img.setAttribute('src', originalSrc);
+      img.setAttribute('alt', originalAlt);
+      return;
+    }
+    const nextAlt = altInput.value;
+    if (chosenSrcAttr === originalSrc && nextAlt === originalAlt) return;
+    void commitImageEdit(img, src, { originalSrc, originalAlt, nextSrc: chosenSrcAttr, nextAlt });
+  };
+
+  const backdrop = buildBackdrop(() => close(false));
+  wirePanelButtons(panel, () => close(false), () => close(true));
+  const token = state.begin({ kind: 'panel', close: () => close(false) });
+  mount(backdrop, panel);
+  const releaseFocus = trapFocus(panel, { initial: altInput });
+
+  // --- replace ---------------------------------------------------------------
+  if (!srcEditable) return;
+
+  /** Stage a replacement: preview it here and on the page, but write nothing
+   *  until Save. `fresh` marks a file written seconds ago, which needs the
+   *  retrying loader to survive Vite's 404 window (see ui.ts::setFreshSrc). */
+  const stage = (webPath: string, fresh = false): void => {
+    chosenSrc = webPath;
+    chosenSrcAttr = webPathToUrl(webPath);
+    setPreview(webPath, fresh);
+    // Live preview on the page itself.
+    if (fresh) setFreshSrc(img, webPath);
+    else img.setAttribute('src', webPath);
+    paintRecents();
+  };
+
+  const strip = styled('div', 'atx-image-recents');
+  const stripLabel = styled('div', 'atx-image-recents-label');
+  const stripTitle = styled('span', 'atx-image-recents-title');
+  stripTitle.textContent = 'Recently added';
+  // The strip's corner action, on the same shape every other corner action in
+  // the overlay takes. The arrow is the chevron glyph rather than a "→" — a
+  // text arrow lands at a different weight and baseline in every platform font.
+  const browseAll = footButton('Browse all', 'outline', () => void browse());
+  browseAll.classList.add('atx-btn-sm', 'atx-image-browse-all');
+  browseAll.append(icon('chevronRight', 16));
+  stripLabel.append(stripTitle, browseAll);
+  body.append(stripLabel, strip);
+
+  let recents: AssetInfo[] = [];
+  const openedAt = Date.now();
+
+  function paintRecents(): void {
+    strip.textContent = '';
+    for (const asset of recents) {
+      const current = asset.path === chosenSrc;
+      const btn = styled('button', 'atx-image-recent');
+      btn.toggleAttribute('data-current', current);
+      btn.type = 'button';
+      btn.title = asset.path;
+      const thumb = styled('img', 'atx-image-recent-thumb');
+      // Anything written since this panel opened may still be in Vite's 404
+      // window, so it gets the retrying loader; everything else loads normally.
+      if (asset.mtime > openedAt) setFreshSrc(thumb, asset.path);
+      else thumb.src = asset.path;
+      thumb.alt = '';
+      thumb.loading = 'lazy';
+      thumb.decoding = 'async';
+      thumb.addEventListener('error', () => thumb.toggleAttribute('data-hidden', true));
+      // A retry that finally succeeds must undo that — see ui.ts::setFreshSrc.
+      thumb.addEventListener('load', () => thumb.toggleAttribute('data-hidden', false));
+      btn.append(thumb);
+      btn.addEventListener('click', () => stage(asset.path));
+      strip.append(btn);
+    }
+  }
+
+  /** Everything beyond the six most recent lives in the modal. */
+  async function browse(): Promise<void> {
+    const pick = await openMediaModal({
+      title: 'Replace image',
+      ...(chosenSrc ? { currentWebPath: chosenSrc } : {}),
+    });
+    if (!pick) return; // cancelled — nothing staged
+    stage(pick.webPath, pick.origin !== 'existing');
+    // A newly uploaded or imported file belongs at the head of the strip.
+    void loadRecents();
+  }
+
+  async function loadRecents(): Promise<void> {
+    try {
+      const { files } = await api.getAssets();
+      // Same rule as the modal's project pane: a plain `<img src>` can only
+      // reference paths that exist in the built site. The strip is six tiles of
+      // shortcut, so an unusable file is left out rather than shown disabled —
+      // the explaining is Browse all's job. (issue #9)
+      recents = files
+        .filter((f) => f.servable)
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, RECENTS);
+      // The current image's own metadata, now that we have the listing.
+      const self = files.find((f) => f.path === chosenSrc);
+      if (self) meta.textContent = `${basename(self.path)} · ${formatBytes(self.size)}`;
+      paintRecents();
+    } catch {
+      // The strip is a convenience; the modal's Browse all still works, and it
+      // reports its own failure with a Retry.
+      stripLabel.toggleAttribute('data-hidden', true);
+    }
+  }
+
+  void loadRecents();
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+async function commitImageEdit(
+  img: HTMLImageElement,
+  src: SourceLoc,
+  v: { originalSrc: string; originalAlt: string; nextSrc: string; nextAlt: string },
+): Promise<void> {
+  const busy = state.begin({ kind: 'busy' });
+  const release = lockElement(img);
+  try {
+    img.setAttribute('src', v.nextSrc);
+    img.setAttribute('alt', v.nextAlt);
+    // One batched apply: the server verifies both attrs and writes once, so a
+    // src+alt change can never leave the file half-updated. (spec §6.3)
+    const ops: ApplyOp[] = [];
+    if (v.nextSrc !== v.originalSrc) {
+      ops.push({ targetType: 'src', original: v.originalSrc, newText: v.nextSrc });
+    }
+    if (v.nextAlt !== v.originalAlt) {
+      ops.push({ targetType: 'alt', original: v.originalAlt, newText: v.nextAlt });
+    }
+    if (ops.length) await api.apply({ file: src.file, loc: src.loc, tag: 'img', ops });
+    toast(`Saved — ${basename(src.file)}:${src.loc}`, 'ok');
+  } catch (err) {
+    img.setAttribute('src', v.originalSrc);
+    img.setAttribute('alt', v.originalAlt);
+    toast(`Save failed — ${err instanceof Error ? err.message : 'unknown error'}`, 'err');
+  } finally {
+    release();
+    state.releaseIf(busy);
+  }
+}

package/src/client/editors/markup-insert.ts

@@ -0,0 +1,73 @@
+/**
+ * The markup popup's tag palette, and the pure text/caret math behind it.
+ *
+ * Separated from `markup.ts` so the wrapping and caret rules — the part with
+ * off-by-ones in it — can be unit-tested without a DOM. Nothing here touches
+ * the document; `markup.ts` applies the result to its textarea.
+ */
+
+export interface TagSpec {
+  tag: string;
+  /** Never closes — inserted alone, never wrapping. */
+  isVoid?: boolean;
+  /** Attribute pre-filled on insert, with the caret left inside its quotes. */
+  attr?: string;
+}
+
+/**
+ * The tags the palette offers. Kept in step with `INLINE_TAGS` in
+ * `src/patcher/astro.ts`, which is the authority: drift here shows up as a
+ * refusal on save, never as a bad write.
+ */
+export const TAGS: TagSpec[] = [
+  { tag: 'br', isVoid: true },
+  { tag: 'strong' },
+  { tag: 'em' },
+  { tag: 'b' },
+  { tag: 'i' },
+  { tag: 'u' },
+  { tag: 'a', attr: 'href=""' },
+  { tag: 'span' },
+  { tag: 'code' },
+  { tag: 'small' },
+  { tag: 'sup' },
+  { tag: 'sub' },
+];
+
+export interface Insertion {
+  /** Text to put in place of [start, end). */
+  text: string;
+  /** Selection to leave behind, as offsets from `start`. */
+  caretFrom: number;
+  caretTo: number;
+}
+
+/**
+ * What inserting `spec` should do to `selected` — the text currently
+ * highlighted in the popup, empty when the caret is just sitting somewhere.
+ *
+ * - A void tag is inserted at the caret and replaces any selection.
+ * - A pair with a selection wraps it and *keeps it selected*, so tags can be
+ *   stacked without re-selecting (`<em>` then `<strong>`).
+ * - A pair with no selection leaves the caret between the two halves.
+ * - A tag with a pre-filled attribute (`<a href="">`) always leaves the caret
+ *   inside the quotes instead, since the URL is the next thing to type.
+ */
+export function tagInsertion(selected: string, spec: TagSpec): Insertion {
+  if (spec.isVoid) {
+    const text = `<${spec.tag}>`;
+    return { text, caretFrom: text.length, caretTo: text.length };
+  }
+
+  const open = spec.attr ? `<${spec.tag} ${spec.attr}>` : `<${spec.tag}>`;
+  const text = `${open}${selected}</${spec.tag}>`;
+
+  if (spec.attr) {
+    const inQuotes = open.length - 2;
+    return { text, caretFrom: inQuotes, caretTo: inQuotes };
+  }
+  if (selected) {
+    return { text, caretFrom: open.length, caretTo: open.length + selected.length };
+  }
+  return { text, caretFrom: open.length, caretTo: open.length };
+}