astro-dev-edit 0.11.0

package/src/client/router.ts

@@ -0,0 +1,198 @@
+import type { ClassifyResult, SourceLoc } from '../shared/protocol.ts';
+import * as api from './api.ts';
+import { beginExpressionEdit } from './editors/expression.ts';
+import { beginImageEdit } from './editors/image.ts';
+import { beginMarkupEdit } from './editors/markup.ts';
+import type { NoticeOptions } from './editors/notice.ts';
+import { showDynamicNotice } from './editors/notice.ts';
+import { beginTextEdit } from './editors/text.ts';
+import { isOwnUi } from './shadow.ts';
+import { nearestSource, sourceFor } from './source-map.ts';
+import * as state from './state.ts';
+import { toast } from './ui.ts';
+
+/**
+ * Click routing: confirm the clicked target against the server's AST-truth
+ * classification, then open the matching editor. Capture-phase listeners
+ * swallow clicks on editable targets so wrapping links/buttons can't act.
+ */
+
+export interface RouterDeps {
+  isEditMode(): boolean;
+  /** True while the navigate modifier (Ctrl / Alt) is held in edit mode. */
+  isNavigating(): boolean;
+  openSource(src: SourceLoc): void;
+  /** Open the in-browser source-peek panel for a loc. */
+  openPeek(src: SourceLoc): void;
+}
+
+const IS_MAC = /Mac|iP(hone|ad|od)/.test(navigator.platform);
+
+/**
+ * In navigate mode, give links plain-click behavior despite the held
+ * modifier: natively Alt+click downloads the target and Ctrl+click opens a
+ * new tab, so we swallow the event and navigate ourselves. Non-link targets
+ * (buttons, form controls) pass through untouched.
+ */
+function navigateThrough(e: MouseEvent): void {
+  const a = e.target instanceof Element ? e.target.closest('a[href]') : null;
+  if (!(a instanceof HTMLAnchorElement)) return;
+  e.preventDefault();
+  e.stopPropagation();
+  e.stopImmediatePropagation();
+  window.location.assign(a.href);
+}
+
+/** What initRouter hands back: a programmatic open so the element-tree panel can
+ *  open the editor for a row (double-click) through the same classify → route
+ *  path a page click takes. */
+export interface RouterHandle {
+  openElementAt(el: HTMLElement): void;
+}
+
+/** Register the capture-phase click/mousedown listeners. */
+export function initRouter(deps: RouterDeps): RouterHandle {
+  /**
+   * Open the appropriate editor for a source-mapped element — after confirming
+   * the target with the server's AST classification. The DOM can't distinguish
+   * a resolved {expression} from literal text; the AST can. (spec §16.1)
+   */
+  async function openElement(
+    el: HTMLElement,
+    src: SourceLoc,
+    /**
+     * What the pointer actually landed on, when that is not `el`. Astro
+     * annotates only elements written in the file, so a component's or a
+     * slot's output has no loc of its own and `nearestSource` climbs to an
+     * ancestor — whose reason then describes an element the user never
+     * clicked. Carried through so the refusal can say which is which.
+     */
+    clicked?: EventTarget | null,
+  ): Promise<void> {
+    const via: NoticeOptions =
+      clicked instanceof Element && clicked !== el
+        ? { clickedTag: clicked.tagName.toLowerCase() }
+        : {};
+    // Claim the interaction slot synchronously: /classify is async, and without
+    // this a rapid second click during the round-trip could open a second editor.
+    const busy = state.begin({ kind: 'busy' });
+    let server: ClassifyResult;
+    try {
+      server = await api.classify({ file: src.file, loc: src.loc, tag: el.tagName.toLowerCase() });
+    } catch (err) {
+      state.releaseIf(busy);
+      toast(`Could not check editability — ${err instanceof Error ? err.message : 'unknown error'}`, 'err');
+      return;
+    }
+
+    if (server.kind === 'image' && el instanceof HTMLImageElement) {
+      const attrs = server.attrs ?? { src: 'dynamic', alt: 'dynamic' };
+      if (attrs.src !== 'static' && attrs.alt === 'dynamic') {
+        showDynamicNotice(
+          src,
+          'Both the image file and its alt text are set from code, so they must be edited in the source.',
+          deps.openSource,
+          deps.openPeek,
+          via,
+        );
+        return;
+      }
+      void beginImageEdit(el, src, attrs);
+    } else if (server.kind === 'text') {
+      beginTextEdit(el, src);
+    } else if (server.kind === 'markup' && server.markup) {
+      beginMarkupEdit(el, src, server.markup.html, deps.openSource);
+    } else if (server.kind === 'expression' && server.expression) {
+      beginExpressionEdit(el, src, server.expression, deps.openSource);
+    } else {
+      showDynamicNotice(
+        src,
+        server.reason ??
+          'This content is generated from a template expression or a loop, so editing it here could change behaviour, not just words. Edit it at the source instead.',
+        deps.openSource,
+        deps.openPeek,
+        via,
+      );
+    }
+  }
+
+  function onClick(e: MouseEvent): void {
+    if (!deps.isEditMode()) return;
+    if (isOwnUi(e)) return;
+
+    // Navigate mode: don't intercept anything, but fix up link clicks whose
+    // native modifier behavior isn't "navigate here".
+    if (deps.isNavigating()) {
+      navigateThrough(e);
+      return;
+    }
+
+    const el = nearestSource(e.target);
+    const src = el ? sourceFor(el) : undefined;
+
+    // Case A: an inline text edit is open. A click elsewhere should commit it
+    // and — if it landed on another editable target — open that one in the
+    // SAME gesture, rather than only dismissing and forcing a second click. (#1)
+    const interaction = state.get();
+    if (interaction?.kind === 'text') {
+      const active = document.querySelector('[data-astro-dev-edit-active="1"]');
+      if (el && el === active) return; // clicking within the edit: leave it be
+      e.preventDefault();
+      e.stopPropagation();
+      e.stopImmediatePropagation();
+      interaction.finish(true); // commit the current edit now
+      // and open the new target immediately
+      if (el && src) void openElement(el, src, e.target);
+      return;
+    }
+
+    // Case B: a modal interaction (image/dynamic panel) is open — its own
+    // backdrop/buttons handle dismissal — or a classify/save is in flight.
+    // Don't route background clicks.
+    if (interaction) return;
+
+    if (!el || !src) return;
+
+    // Fully swallow the click so a wrapping <a>/<button> can't navigate or submit.
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+    void openElement(el, src, e.target);
+  }
+
+  // In edit mode, also swallow mousedown on an editable target in capture
+  // phase — some browsers begin navigation/focus on mousedown before click
+  // fires. This stops a wrapping link from acting; our own UI is exempt.
+  function onMouseDown(e: MouseEvent): void {
+    if (!deps.isEditMode() || deps.isNavigating() || isOwnUi(e)) return;
+    const el = nearestSource(e.target);
+    if (el && sourceFor(el)) {
+      // Don't preventDefault when the mousedown is inside the active edit, or
+      // the caret won't move where the user clicked.
+      if (el.dataset.astroDevEditActive === '1') return;
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  }
+
+  // macOS turns Ctrl+click into a right-click — no click event ever fires,
+  // only contextmenu. In navigate mode, catch it on links and navigate
+  // instead of showing the menu; anywhere else the menu opens as usual.
+  function onContextMenu(e: MouseEvent): void {
+    if (!IS_MAC || !e.ctrlKey) return;
+    if (!deps.isEditMode() || !deps.isNavigating() || isOwnUi(e)) return;
+    navigateThrough(e);
+  }
+
+  // Capture phase so we intercept before links/buttons act on their default.
+  document.addEventListener('click', onClick, true);
+  document.addEventListener('mousedown', onMouseDown, true);
+  document.addEventListener('contextmenu', onContextMenu, true);
+
+  return {
+    openElementAt(el: HTMLElement): void {
+      const src = sourceFor(el);
+      if (src) void openElement(el, src);
+    },
+  };
+}

package/src/client/shadow.ts

@@ -0,0 +1,111 @@
+/**
+ * The overlay's shadow root — one host element, one stylesheet, one place that
+ * knows the boundary exists.
+ *
+ * Every piece of chrome the overlay draws lives in here. Host-page CSS cannot
+ * match a node inside a shadow root in either direction, which is the isolation
+ * the overlay needs on an arbitrary site: a `*{color:red!important}` rule on the
+ * page cannot reach us, because it cannot make the match in the first place.
+ * Astro's own dev toolbar solves the same problem the same way, in the same
+ * page.
+ *
+ * Inheritance is the one thing that *does* cross, so `overlayCss()` opens with
+ * `:host { all: initial }` and re-declares what we want inherited. That is the
+ * whole guard — see styles.ts.
+ *
+ * **Created lazily, never at module evaluation.** `ui.ts` imports this module,
+ * and `tests/contrast.test.ts` imports `ui.ts` in Node where there is no
+ * `document`. Nothing here may touch the DOM until something actually mounts.
+ */
+
+import { overlayCss } from './styles.ts';
+
+/** The custom element name. Also the selector users write to theme the overlay
+ *  (`astro-dev-edit { --atx-card: … }`), so it is a public name — see
+ *  docs/STYLING.md. Never registered with `customElements.define`: it needs no
+ *  behavior, and an unknown element is styleable all the same. */
+const HOST_TAG = 'astro-dev-edit';
+
+let host: HTMLElement | null = null;
+let root: ShadowRoot | null = null;
+
+function ensure(): ShadowRoot {
+  if (root) return root;
+  host = document.createElement(HOST_TAG);
+  // `display: contents` (set in overlayCss) means the host generates no box at
+  // all, so it cannot shift the page's layout by so much as a line box, and
+  // every absolutely-positioned child still resolves against the initial
+  // containing block exactly as it did when it was a child of <body>.
+  // Deliberately *not* position/transform/filter/contain: any of those would
+  // make the host a containing block and re-anchor our `position: fixed`
+  // panels to it.
+  document.body.append(host);
+  root = host.attachShadow({ mode: 'open' });
+  // `open` on purpose: a closed root buys no security — anything on the page can
+  // already read our source — and costs the ability to debug the overlay in
+  // DevTools.
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(overlayCss());
+  root.adoptedStyleSheets = [sheet];
+  return root;
+}
+
+/** The shadow root. Query it instead of `document` — `document.querySelector`
+ *  does not cross the boundary. */
+export function overlayRoot(): ShadowRoot {
+  return ensure();
+}
+
+/** The host element. Needed for `composedPath().includes(host)` and as the
+ *  parent for light-DOM content that is slotted back in (see `mountLight`). */
+export function overlayHost(): HTMLElement {
+  ensure();
+  return host as HTMLElement;
+}
+
+/** Mount overlay chrome. The shadow-root replacement for `document.body.append`
+ *  — every panel, drawer, bar and toast goes through here. */
+export function mount(...nodes: Node[]): void {
+  ensure().append(...nodes);
+}
+
+/**
+ * Mount a node into the **light DOM**, as a child of the host, for `<slot>`-ing
+ * back into the shadow tree.
+ *
+ * Exactly one thing needs this: the rich-text editor's `contenteditable`.
+ * Safari's selection and `execCommand` APIs are inert against a node inside a
+ * shadow root — `document.execCommand` silently does nothing and
+ * `getSelection().anchorNode` retargets to `<body>` — which would kill the
+ * markdown toolbar outright. A slotted node is composed into the shadow tree
+ * for layout while remaining a light-DOM node, so selection keeps working in
+ * every engine. Verified in Chrome, Firefox and WebKit.
+ *
+ * The cost is that host-page CSS *can* reach a slotted node. That is unchanged
+ * from how the editor already worked (its `CONTENT_CSS` is a document-level
+ * stylesheet), and it is the reason `content-visibility` of the RTE is styled
+ * there rather than in `overlayCss()`.
+ */
+export function mountLight(node: Node): void {
+  ensure();
+  (host as HTMLElement).append(node);
+}
+
+/**
+ * True when an event originated inside the overlay's own UI.
+ *
+ * `composedPath()` rather than `event.target`: a listener on `document` sees a
+ * target retargeted to the host element, so any `target.closest(...)` test
+ * silently starts answering wrong once the chrome moves in here. The composed
+ * path is the real path, and it includes slotted light-DOM nodes — which
+ * `root.contains()` would not.
+ */
+export function isOwnUi(e: Event): boolean {
+  return host !== null && e.composedPath().includes(host);
+}
+
+/** The focused element *inside* the overlay, or null.
+ *  `document.activeElement` reports the host for anything in here. */
+export function overlayActiveElement(): Element | null {
+  return root ? root.activeElement : null;
+}

package/src/client/source-map.ts

@@ -0,0 +1,150 @@
+import type { SourceLoc } from '../shared/protocol.ts';
+
+/**
+ * Source-location capture cache.
+ *
+ * Astro emits `data-astro-source-file` / `-loc` in the served HTML, but its
+ * dev-toolbar runtime STRIPS those attributes out of the DOM shortly after
+ * hydration. By hover time they are gone — querying them live finds nothing.
+ * (Verified against Astro 5.18: 254 attrs in served HTML, 0 in the live DOM.)
+ *
+ * So we snapshot every annotated element the instant it appears, before the
+ * toolbar clears them, and read hover/edit locations from the cache instead of
+ * from live attributes. This is the same approach the astro-click-to-source
+ * integration uses. It supersedes spec §4.2's "re-read attributes lazily on
+ * next hover", which is not viable here.
+ *
+ * Two-layer cache. The primary key is the element itself: when we see an
+ * annotated element we copy its {file, loc} onto a private JS property. A JS
+ * property survives the attribute-strip (Astro removes the HTML attribute, not
+ * our property) AND survives across hover with no path matching. The secondary
+ * path-keyed map is the fallback for the case where Astro REPLACES a node
+ * wholesale (new object, our property gone): we re-resolve by structural path.
+ *
+ * The critical timing fix: we don't snapshot once and hope. A MutationObserver
+ * watches for the attributes being added (initial render / HMR) and stamps them
+ * onto the element the moment they appear — so we always capture the value
+ * before the toolbar's own observer strips it, regardless of ordering.
+ *
+ * TIMING CONTRACT: this module has no top-level side effects. The entry module
+ * (overlay.ts) must call startCapture() synchronously at module evaluation to
+ * win the race against the toolbar's stripping.
+ */
+
+const PROP = '__astroDevEditSrc' as const;
+
+interface Stamped extends HTMLElement {
+  [PROP]?: SourceLoc;
+}
+
+const sourceByPath = new Map<string, SourceLoc>();
+
+/** Structural path: `tag:nth-of-type` chain to the document root. Computed from
+ *  the live DOM at both stamp and lookup time, so the two always agree. */
+function elementPath(el: HTMLElement): string {
+  const parts: string[] = [];
+  let cur: HTMLElement | null = el;
+  while (cur && cur.parentElement) {
+    const parent: HTMLElement = cur.parentElement;
+    const tag = cur.tagName;
+    let idx = 1;
+    for (const sib of parent.children) {
+      if (sib === cur) break;
+      if (sib.tagName === tag) idx++;
+    }
+    parts.unshift(`${tag.toLowerCase()}:nth-of-type(${idx})`);
+    cur = parent;
+  }
+  return parts.join('>');
+}
+
+/** Record an annotated element's source loc into both cache layers. */
+function stamp(el: Stamped): void {
+  if (el[PROP]) return;
+  const file = el.getAttribute('data-astro-source-file');
+  if (!file) return;
+  const loc = el.getAttribute('data-astro-source-loc') ?? '';
+  const src: SourceLoc = { file, loc };
+  el[PROP] = src;
+  sourceByPath.set(elementPath(el), src);
+}
+
+/** Snapshot everything currently annotated in the DOM. Called at capture start
+ *  and again after HMR re-renders (which re-annotate the fresh DOM). */
+export function cacheSourceMappings(): void {
+  for (const el of document.querySelectorAll<Stamped>('[data-astro-source-file]')) {
+    stamp(el);
+  }
+}
+
+/**
+ * Every live element that carries a captured source loc, in document order.
+ *
+ * The `data-astro-source-*` attributes are gone by now (the toolbar stripped
+ * them), so we can't query them — we read the stamped JS property instead,
+ * which persists. This is the only way to enumerate annotated elements after
+ * boot; the element-tree panel derives its structure from it. Assumes the DOM
+ * has already been stamped (startCapture / cacheSourceMappings), which the boot
+ * and HMR paths guarantee before this is called.
+ */
+export function annotatedElements(root: HTMLElement = document.body): HTMLElement[] {
+  const out: HTMLElement[] = [];
+  for (const el of root.querySelectorAll<Stamped>('*')) {
+    if (el[PROP]) out.push(el);
+  }
+  return out;
+}
+
+/** The structural path used as the cache's fallback key — a stable identity for
+ *  an element across HMR re-renders (which replace the element object). The tree
+ *  panel keys its collapse/selection state on this so both survive a save. */
+export function pathFor(el: HTMLElement): string {
+  return elementPath(el);
+}
+
+/** Resolve a live element's source loc: property first, path fallback. */
+export function sourceFor(el: HTMLElement): SourceLoc | undefined {
+  return (el as Stamped)[PROP] ?? sourceByPath.get(elementPath(el));
+}
+
+/**
+ * Nearest ancestor (or self) with a cached source location. Reads the
+ * snapshot cache, not live attributes — the attributes are gone by now.
+ */
+export function nearestSource(node: EventTarget | null): HTMLElement | null {
+  let el = node as HTMLElement | null;
+  while (el && el !== document.body) {
+    if (sourceFor(el)) return el;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+// Stamp attributes the instant they appear, before the dev toolbar strips them.
+// This wins the race regardless of script ordering. (verified fix)
+const stampObserver = new MutationObserver((records) => {
+  for (const rec of records) {
+    if (rec.type === 'attributes' && rec.target instanceof HTMLElement) {
+      stamp(rec.target);
+    }
+    for (const node of rec.addedNodes) {
+      if (node instanceof HTMLElement) {
+        if (node.hasAttribute('data-astro-source-file')) stamp(node);
+        for (const el of node.querySelectorAll<Stamped>('[data-astro-source-file]')) {
+          stamp(el);
+        }
+      }
+    }
+  }
+});
+
+/** Begin capturing: snapshot what's present, then observe for the rest. */
+export function startCapture(): void {
+  cacheSourceMappings(); // grab whatever is already present
+  stampObserver.observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ['data-astro-source-file', 'data-astro-source-loc'],
+  });
+}

package/src/client/state.ts

@@ -0,0 +1,153 @@
+/**
+ * Interaction state controller — the single slot for "what editing
+ * interaction is open right now". Replaces the trio of coordinated flags
+ * (editingActive / activeCloser / activeTextFinish) whose invariants every
+ * editor had to re-implement.
+ *
+ * Exactly one interaction can be active:
+ *   - 'busy'  — a /classify round-trip or a save is in flight; clicks are
+ *               ignored until it settles.
+ *   - 'text'  — an inline contenteditable edit; `finish(commit)` commits or
+ *               cancels it (cancel restores the original text).
+ *   - 'panel' — a modal panel (image swap / refusal notice); `close()` tears
+ *               it down without committing. A panel that holds a draft of its
+ *               own — the source popups — also supplies `commit()`, so leaving
+ *               edit mode writes that draft instead of dropping it.
+ *
+ * The token pattern makes async completion safe: `begin()` returns the
+ * interaction as a token, and `releaseIf(token)` only frees the slot if that
+ * token still owns it — a commit (or a click-to-re-target) may have started a
+ * NEW interaction by the time the previous async save settles. A new editor
+ * kind is one `begin()` call; there are no flags to keep consistent.
+ */
+
+export type Interaction =
+  | { kind: 'busy' }
+  | { kind: 'text'; finish(commit: boolean): void }
+  | { kind: 'panel'; close(): void; commit?(): void };
+
+let current: Interaction | null = null;
+
+/** The open interaction, or null when idle. */
+export function get(): Interaction | null {
+  return current;
+}
+
+/** Claim the slot (replacing whatever held it). Returns the token to release with. */
+export function begin(interaction: Interaction): Interaction {
+  current = interaction;
+  return interaction;
+}
+
+/** Free the slot — but only if `token` still owns it. */
+export function releaseIf(token: Interaction): void {
+  if (current === token) current = null;
+}
+
+/**
+ * Hand the slot back to whoever held it before `token` claimed it — the
+ * counterpart to `begin()` for a **nested** interaction.
+ *
+ * `begin()` replaces the current holder outright. That is right when one thing
+ * is open at a time, but wrong when something opens *above* something else: the
+ * media modal can open over the CMS drawer, and a plain `releaseIf` would leave
+ * the still-open drawer owning nothing — its Escape and backdrop would silently
+ * stop working, with the user's unsaved fields still in it.
+ *
+ * Capture `get()` immediately before `begin()`, and pass it here on close. If a
+ * third interaction has since taken the slot, this does nothing rather than
+ * stealing it back.
+ */
+export function releaseTo(token: Interaction, previous: Interaction | null): void {
+  if (current !== token) return;
+  current = previous;
+}
+
+/**
+ * Tear down whatever is open: a panel closes, a text edit cancels (restoring
+ * the original text), a busy marker is simply dropped. The slot is cleared
+ * BEFORE the teardown runs, so closers that release their own token can't
+ * re-enter.
+ */
+export function dismiss(): void {
+  const interaction = current;
+  current = null;
+  if (!interaction) return;
+  if (interaction.kind === 'panel') interaction.close();
+  else if (interaction.kind === 'text') interaction.finish(false);
+}
+
+/**
+ * Close whatever is open, *keeping* the user's work: a text edit commits
+ * (writing to disk) instead of reverting; a panel that declared a `commit()`
+ * runs it, and one that did not just closes, since it owns its own Save
+ * button. The counterpart to `dismiss()` — leaving edit mode must never
+ * silently discard typing, so the exit path goes through here.
+ *
+ * A committing panel may refuse (a save can come back with a reason) and
+ * re-claim the slot from inside `commit()`, which is why the slot is cleared
+ * first: the panel's own `begin()` then wins, and the exit path reads the save
+ * phase to decide whether it may leave.
+ */
+export function commit(): void {
+  const interaction = current;
+  current = null;
+  if (!interaction) return;
+  if (interaction.kind === 'panel') (interaction.commit ?? interaction.close)();
+  else if (interaction.kind === 'text') interaction.finish(true);
+}
+
+// --- Save phase --------------------------------------------------------------
+
+/**
+ * How the on-disk state of the page relates to what's on screen — the admin
+ * bar's exit button renders this, so "are my changes saved?" is answerable at a
+ * glance:
+ *
+ *   - 'clean'  — nothing pending; everything typed has been written
+ *   - 'dirty'  — an inline edit has unsaved keystrokes in it
+ *   - 'saving' — a write is in flight
+ *   - 'saved'  — a write just landed (decays back to 'clean')
+ *   - 'error'  — the last write failed and its change was rolled back
+ *
+ * It lives beside the interaction slot because the same editors drive both, but
+ * it is deliberately *reported* rather than derived: only the editor knows
+ * whether the keystrokes so far differ from the original, and only the commit
+ * knows whether the server accepted them.
+ */
+export type SavePhase = 'clean' | 'dirty' | 'saving' | 'saved' | 'error';
+
+/** How long 'saved' stays on screen before decaying to 'clean'. */
+const SAVED_LINGER = 1400;
+
+let phase: SavePhase = 'clean';
+let decayTimer: number | null = null;
+const phaseListeners = new Set<(p: SavePhase) => void>();
+
+export function savePhase(): SavePhase {
+  return phase;
+}
+
+/** Report a phase change. Repeats are dropped, so an editor may call this on
+ *  every keystroke without waking any listener more than once. */
+export function setSavePhase(next: SavePhase): void {
+  if (next === phase) return;
+  if (decayTimer !== null) {
+    clearTimeout(decayTimer);
+    decayTimer = null;
+  }
+  phase = next;
+  for (const fn of phaseListeners) fn(phase);
+  if (phase === 'saved') {
+    decayTimer = window.setTimeout(() => {
+      decayTimer = null;
+      setSavePhase('clean');
+    }, SAVED_LINGER);
+  }
+}
+
+/** Subscribe to phase changes; returns an unsubscribe. */
+export function onSavePhase(fn: (p: SavePhase) => void): () => void {
+  phaseListeners.add(fn);
+  return () => phaseListeners.delete(fn);
+}