astro-dev-edit 0.11.0

package/src/client/editors/settings-panel.ts

@@ -0,0 +1,457 @@
+import type { FieldDescriptor, OptionDescriptor, SettingsResponse } from '../../shared/protocol.ts';
+import * as api from '../api.ts';
+import { setFeatures } from '../features.ts';
+import { coerceImportWidth } from '../../shared/unsplash.ts';
+import { clearHighlight } from '../hover.ts';
+import { icon } from '../icons.ts';
+import {
+  inputEl,
+  buildTabs,
+  footButton,
+  setButtonEnabled,
+  styled,
+  toast,
+} from '../ui.ts';
+import { card, fieldGroup } from '../group.ts';
+import { openDrawer } from './drawer.ts';
+import { applyFieldErrors, buildControl, collectChanges, type FieldControl } from './fields.ts';
+
+/**
+ * The Settings drawer — every integration option, editable in place.
+ *
+ * **The panel does not know what the options are.** `GET /settings` returns a
+ * list of {@link OptionDescriptor}s — label, help, control type, current value,
+ * provenance — and this module renders whatever arrives, grouped into tabs by
+ * the `group` each one declares. Adding an option is one entry in the server's
+ * `OPTION_SPECS` table and no client change at all. Each descriptor becomes a
+ * synthesized {@link FieldDescriptor} so the controls come from the entry
+ * editor's own `buildControl` registry rather than a parallel one.
+ *
+ * **`locked` is rendered, not hidden.** An option `astro.config.mjs` sets cannot
+ * be changed from here, because config wins at resolve time. The control renders
+ * disabled and says where the value came from. Hiding those rows would be worse:
+ * the user would wonder why the option they can see in their config isn't listed.
+ *
+ * **The access key has two axes, not one.** `locked` is a single bit; a key can
+ * be *writable but not clearable* — one in `.env` is overridden by the
+ * `.env.local` a save writes, yet removing a line from `.env.local` cannot unset
+ * it. So the server sends `writable` and `clearable` separately and this panel
+ * renders them, rather than re-deriving either from `source`: which env file won
+ * decides the answer, and a second copy of that precedence here would drift.
+ *
+ * **The access key stays one-way.** It is never pre-filled — a read returns only
+ * a masked hint — the input is `type="password"` with an explicit reveal, and the
+ * value goes straight to the localhost-gated `/settings` endpoint. That POST is
+ * the one moment the key crosses the wire in plaintext, unavoidable for a
+ * paste-it-here UI, and its destination is the same `.env.local` a developer
+ * would otherwise have opened in their editor.
+ */
+
+const UNSPLASH_APPS_URL = 'https://unsplash.com/oauth/applications';
+
+/** Where a resolved key came from, in words. `env-file` prefers the actual
+ *  filename the server reported, since which file it is decides what the user
+ *  has to do about it. */
+const SOURCE_LABEL: Record<string, string> = {
+  config: 'astro.config.mjs',
+  'env-shell': 'an exported shell variable',
+  'env-file': 'a .env file',
+  file: '.astro-dev-edit.json (older location)',
+};
+
+const sourceLabel = (u: SettingsResponse['unsplash']): string =>
+  (u.source === 'env-file' && u.sourceFile) || SOURCE_LABEL[u.source ?? ''] || 'stored settings';
+
+/** Tabs, in render order. A group with no options is dropped, so a server that
+ *  predates a group simply shows fewer tabs. */
+const GROUPS: ReadonlyArray<{ id: string; label: string; blurb: string }> = [
+  {
+    id: 'general',
+    label: 'General',
+    blurb: 'What the editor is allowed to touch, and how it finds your source.',
+  },
+  {
+    id: 'editing',
+    label: 'Editing',
+    blurb: 'Which editing surfaces the overlay offers.',
+  },
+  {
+    id: 'media',
+    label: 'Media',
+    blurb: 'Where images are read from, and where new ones are written.',
+  },
+  {
+    id: 'unsplash',
+    label: 'Unsplash',
+    blurb: 'An optional photo source in the media picker.',
+  },
+];
+
+export interface SettingsPanelOptions {
+  /** Open on a particular tab. Used by the media modal's "no key configured"
+   *  card, which wants the Unsplash tab specifically. */
+  tab?: string;
+  /** Stacking layer, when opened above something already raised — that same
+   *  card opens this from the media modal's own layer. */
+  layer?: number;
+  /** Run after the drawer closes, whatever the outcome. */
+  onClose?(): void;
+}
+
+export function openSettingsPanel(opts: SettingsPanelOptions = {}): void {
+  clearHighlight();
+
+  let controls: FieldControl[] = [];
+  let current: SettingsResponse | null = null;
+  let saving = false;
+  /** Set once the key input has been typed into — the only dirty state the key
+   *  field can report, since it never pre-fills. */
+  const keyDirty = (): boolean => keyInput.value.trim().length > 0;
+
+  const isDirty = (): boolean =>
+    !saving && (keyDirty() || Object.keys(collectChanges(controls)).length > 0);
+
+  const shell = openDrawer('Settings', {
+    isDirty,
+    discardMessage: 'Discard unsaved settings changes?',
+    width: 'min(max(520px, 44vw), 94vw)',
+    ...(opts.layer !== undefined ? { layer: opts.layer, restoreState: true } : {}),
+    ...(opts.onClose ? { onClose: opts.onClose } : {}),
+  });
+  const { body, foot } = shell;
+
+  // --- the option panes ------------------------------------------------------
+  const panes = new Map<string, HTMLElement>();
+  for (const g of GROUPS) {
+    const pane = styled('div', `atx-settings-pane atx-settings-pane-${g.id}`);
+    panes.set(g.id, pane);
+  }
+
+  const status = styled('p', 'atx-settings-status');
+
+  const error = styled('p', 'atx-settings-error');
+
+  // --- the Unsplash key section, which is not an option ----------------------
+  const keyCard = card({ title: 'Access key' });
+  const keySection = keyCard.root;
+  keySection.classList.add('atx-settings-key-section');
+
+  const keyBlurb = styled('p', 'atx-settings-blurb');
+  const appsLink = styled('a', 'atx-settings-link');
+  appsLink.href = UNSPLASH_APPS_URL;
+  appsLink.target = '_blank';
+  appsLink.rel = 'noreferrer';
+  appsLink.textContent = 'Create an application';
+  keyBlurb.append(
+    appsLink,
+    document.createTextNode(' to get an access key — the demo tier allows 50 searches an hour.'),
+  );
+
+  const keyStatus = styled('p', 'atx-settings-key-status');
+
+  const keyRow = styled('div', 'atx-settings-row');
+  // No masked input exists anywhere else in the overlay, so this is a plain
+  // control wearing the shared baseline rather than a reusable widget.
+  const keyInput = inputEl('input', 'atx-settings-key');
+  keyInput.type = 'password';
+  keyInput.autocomplete = 'off';
+  keyInput.spellcheck = false;
+  keyInput.placeholder = 'Paste your Unsplash access key';
+
+  const reveal = footButton('Show', 'outline', () => {
+    const hidden = keyInput.type === 'password';
+    keyInput.type = hidden ? 'text' : 'password';
+    reveal.textContent = hidden ? 'Hide' : 'Show';
+  });
+  keyRow.append(keyInput, reveal);
+
+  const keyHint = styled('p', 'atx-settings-hint');
+
+  const clearKeyBtn = footButton('Clear key', 'destructive', () => void save({ clearKey: true }));
+  const keyActions = styled('div', 'atx-settings-key-actions');
+  keyActions.append(clearKeyBtn);
+
+  keyCard.body.append(keyBlurb, keyStatus, keyRow, keyHint);
+  keyCard.foot().append(keyActions);
+
+  const warning = styled('p', 'atx-settings-warning');
+
+  const tabs = buildTabs(
+    GROUPS.map((g) => ({ id: g.id, label: g.label, pane: panes.get(g.id)! })),
+    { classPrefix: 'settings' },
+  );
+  body.append(status, tabs.strip, tabs.host, warning, error);
+
+  // --- rendering the server's answer -----------------------------------------
+  const paint = (data: SettingsResponse): void => {
+    current = data;
+    controls = [];
+    status.textContent = '';
+
+    const options = data.options ?? [];
+    for (const g of GROUPS) {
+      const pane = panes.get(g.id)!;
+      pane.textContent = '';
+      const mine = options.filter((o) => o.group === g.id);
+
+      // One card per tab: the group's name and its one-line blurb are the
+      // card's header, so the pane says what it governs instead of opening
+      // with an unattributed sentence above a run of controls.
+      const group = fieldGroup();
+      for (const o of mine) {
+        const control = buildControl(toFieldDescriptor(o), o.value);
+        if (o.locked) control.root.append(lockNote(o));
+        controls.push(control);
+        group.append(control.root);
+      }
+      if (mine.length > 0) {
+        const optionCard = card({ title: g.label, description: g.blurb });
+        optionCard.body.append(group);
+        pane.append(optionCard.root);
+      }
+
+      // The access key belongs to the Unsplash tab but is not an option: it is
+      // a secret with its own endpoint semantics and its own precedence — so
+      // it is a card of its own rather than a heading inside the options one.
+      if (g.id === 'unsplash') pane.append(keySection);
+    }
+
+    paintKey(data);
+    paintWarning(data);
+    setButtonEnabled(saveBtn, true);
+  };
+
+  const paintKey = (data: SettingsResponse): void => {
+    const u = data.unsplash;
+    keyStatus.textContent = '';
+
+    if (!u.enabled) {
+      // The old dead end lived here: this used to read "add `unsplash: {}` to
+      // astro.config.mjs, then restart the dev server". The toggle above is now
+      // the answer, so point at it instead.
+      keyStatus.append(
+        icon('dot', 16),
+        text('Turn the photo source on above to add a key', 'muted'),
+      );
+      keySection.toggleAttribute('data-off', true);
+      keyInput.disabled = true;
+      setButtonEnabled(reveal, false);
+      keyHint.textContent = '';
+      clearKeyBtn.toggleAttribute('data-hidden', true);
+      return;
+    }
+
+    keySection.toggleAttribute('data-off', false);
+
+    if (u.configured) {
+      keyStatus.append(icon('check', 16), text(`Configured via ${sourceLabel(u)}`, 'ok'));
+      if (u.hint) keyStatus.append(text(u.hint, 'muted', true));
+    } else {
+      keyStatus.append(icon('dot', 16), text('Not configured', 'muted'));
+    }
+
+    // `writable` is the server's answer, not ours — see the header.
+    const overridden = !u.writable;
+    keyInput.disabled = overridden;
+    setButtonEnabled(reveal, !overridden);
+    keyInput.placeholder = overridden
+      ? 'Overridden — remove the other key first'
+      : 'Paste your Unsplash access key';
+
+    if (overridden) {
+      keyHint.textContent =
+        `A key from ${sourceLabel(u)} takes precedence over the .env.local this panel ` +
+        'writes. Remove it to manage the key from here.';
+    } else if (u.staleStoredKey) {
+      // The one case worth nagging about: a secret in a file that is not where
+      // secrets go any more. Saving anything moves it.
+      keyHint.textContent =
+        'An older copy of your key is still stored in .astro-dev-edit.json. Save a key here ' +
+        'to move it into .env.local and remove that copy.';
+    } else if (!u.clearable && u.configured) {
+      keyHint.textContent =
+        `A key is also set in ${u.sourceFile ?? '.env'}. Saving here writes .env.local, which ` +
+        'takes precedence — remove that one when you are ready.';
+    } else {
+      keyHint.textContent =
+        'Saved to .env.local at your project root as UNSPLASH_ACCESS_KEY, readable only by ' +
+        'you (0600). It is never sent back to the browser.';
+    }
+    clearKeyBtn.toggleAttribute('data-hidden', !(u.configured && u.clearable));
+  };
+
+  /**
+   * The uncommitted-secret warning, painted from `paint` rather than from
+   * `paintKey`: it is a fact about files, not about the key. Scoping it to the
+   * key left it unreachable in exactly the case it is for — the photo source
+   * off, so `paintKey` returns early, while a file already sits untracked on
+   * disk holding whatever General or Media last saved. It lives under the tab
+   * host for the same reason, so it is on screen whichever tab is open.
+   *
+   * The server sends the list, because whether `.env.local` is even present is
+   * a question only it can answer.
+   */
+  const paintWarning = (data: SettingsResponse): void => {
+    const files = data.gitignoreWarning ?? [];
+    if (files.length > 0) {
+      const subject = files.length === 1 ? `${files[0]} is not listed` : `${files.join(' and ')} are not listed`;
+      warning.textContent =
+        `${subject} in this project’s .gitignore. They hold your settings and your Unsplash ` +
+        'access key — add them to your ignore rules before either can be committed. ' +
+        '(This integration cannot edit your ignore rules for you.)';
+      warning.toggleAttribute('data-on', true);
+    } else {
+      warning.toggleAttribute('data-on', false);
+    }
+  };
+
+  const text = (value: string, tone: 'muted' | 'ok' | 'warn', mono = false): HTMLElement => {
+    const el = styled('span', 'atx-settings-text');
+    el.dataset.tone = tone;
+    if (mono) el.dataset.mono = '';
+    el.textContent = value;
+    return el;
+  };
+
+  /** Why a control is disabled, under the control. */
+  const lockNote = (o: OptionDescriptor): HTMLElement => {
+    // Muted, not amber: an option the project set in its own config is a
+    // normal state, and painting a third of the panel in warning colour would
+    // spend the one colour that should mean "something is wrong" — which here
+    // is the uncommitted-secret warning at the bottom.
+    const note = styled('p', 'atx-settings-lock');
+    note.append(
+      icon('lock', 12),
+      document.createTextNode(
+        o.restartRequired
+          ? 'Read before the dev server starts, so it lives in astro.config.mjs and changing it needs a restart.'
+          : 'Set in astro.config.mjs, which takes precedence. Remove it there to change it from here.',
+      ),
+    );
+    return note;
+  };
+
+  /** Freeze the drawer during a write. Un-freezing repaints from the current
+   *  response rather than blanket-enabling, so a control disabled *by state* —
+   *  a config-overridden key field — stays that way. */
+  const setBusy = (busy: boolean): void => {
+    saving = busy;
+    keyInput.readOnly = busy;
+    for (const btn of shell.body.querySelectorAll('button')) setButtonEnabled(btn, !busy);
+    for (const btn of foot.querySelectorAll('button')) setButtonEnabled(btn, !busy);
+    if (!busy) {
+      // Rebuilt by the paint that follows a successful save; on a failure this
+      // restores the pre-save enablement.
+      if (current) paintKey(current);
+      setButtonEnabled(saveBtn, current !== null);
+    }
+  };
+
+  const showError = (message: string): void => {
+    error.textContent = message;
+    error.toggleAttribute('data-on', true);
+  };
+
+  const save = async (o: { clearKey?: boolean } = {}): Promise<void> => {
+    error.toggleAttribute('data-on', false);
+    applyFieldErrors(controls, {});
+
+    const options = collectChanges(controls);
+    const key = o.clearKey ? '' : keyInput.value;
+    const sendKey = o.clearKey || key.trim().length > 0;
+    if (Object.keys(options).length === 0 && !sendKey) {
+      showError('Nothing has changed yet.');
+      return;
+    }
+
+    setBusy(true);
+    try {
+      const next = await api.saveSettings({
+        ...(Object.keys(options).length > 0 ? { options } : {}),
+        ...(sendKey ? { unsplash: { accessKey: key } } : {}),
+      });
+      // Feature flags the overlay reads are option-derived, so a save repaints
+      // the page's affordances without a reload.
+      setFeatures({
+        ok: true,
+        name: 'astro-dev-edit',
+        milestone: 1,
+        root: '',
+        cssInspector: valueOf(next, 'cssInspector') === true,
+        openInEditor: valueOf(next, 'openInEditor') === true,
+        entryEditor: valueOf(next, 'entryEditor') === true,
+        unsplash: next.unsplash.configured,
+        // A `select`'s value is a string on the wire; setFeatures parses it, so
+        // the picker's size select moves with a saved default. `?? undefined`
+        // because a null here would read as "the server has no such option".
+        unsplashImportWidth:
+          coerceImportWidth(valueOf(next, 'unsplashImportWidth')) ?? undefined,
+      });
+      keyInput.value = '';
+      keyInput.type = 'password';
+      reveal.textContent = 'Show';
+      paint(next);
+      toast(
+        o.clearKey ? 'Unsplash access key cleared' : 'Settings saved',
+        'ok',
+      );
+    } catch (err) {
+      if (err instanceof api.SettingsRefusal) {
+        applyFieldErrors(controls, err.fieldErrors);
+        showError(err.message);
+      } else {
+        showError(err instanceof Error ? err.message : 'Could not save.');
+      }
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  // --- footer ----------------------------------------------------------------
+  const closeBtn = footButton('Close', 'outline', () => shell.close());
+  const saveBtn = footButton('Save', 'default', () => void save());
+  foot.append(closeBtn, saveBtn);
+
+  // --- boot ------------------------------------------------------------------
+  status.append(icon('spinner', 16), text('Reading settings…', 'muted'));
+  setButtonEnabled(saveBtn, false);
+  clearKeyBtn.toggleAttribute('data-hidden', true);
+
+  void api.getSettings().then(
+    (data) => {
+      paint(data);
+      if (opts.tab) tabs.show(opts.tab);
+    },
+    (err: unknown) => {
+      status.textContent = '';
+      status.append(icon('alert', 16), text('Could not read settings', 'warn'));
+      showError(err instanceof Error ? err.message : 'The dev server did not answer.');
+    },
+  );
+}
+
+/** An option, described as a field so `buildControl` can render it.
+ *
+ *  `present: true` and `required: false` throughout: an option always has an
+ *  effective value (there is no "absent" state to hint a default for), and none
+ *  of them can be cleared to nothing — `coerceOptionPatch` refuses an empty
+ *  string or an empty list, so `collectChanges`' clear-to-null path is dead
+ *  weight here rather than a hazard. */
+function toFieldDescriptor(o: OptionDescriptor): FieldDescriptor {
+  return {
+    name: o.key,
+    label: o.label,
+    type: o.type,
+    required: false,
+    present: true,
+    source: 'inferred',
+    help: o.help,
+    ...(o.choices ? { options: o.choices } : {}),
+    ...(o.locked ? { readOnly: true } : {}),
+  };
+}
+
+/** An option's value out of a response, by key. */
+function valueOf(data: SettingsResponse, key: string): unknown {
+  return data.options?.find((o) => o.key === key)?.value;
+}

package/src/client/editors/source-popup.ts

@@ -0,0 +1,166 @@
+import { trapFocus } from '../focus.ts';
+import { icon } from '../icons.ts';
+import type { Interaction } from '../state.ts';
+import * as state from '../state.ts';
+import { mount } from '../shadow.ts';
+import {
+  inputEl,
+  buildBackdrop,
+  buildPanel,
+  pillButton,
+  styled,
+  wirePanelButtons,
+} from '../ui.ts';
+
+/**
+ * The panel shape shared by every editor that edits *source* rather than
+ * rendered text — the markup popup and the traced-expression popup. Inline
+ * contenteditable can't serve either: one would escape the tags, the other
+ * would rewrite the template instead of the string behind it.
+ *
+ * What this owns, so its callers don't each re-implement it:
+ *
+ * - panel + backdrop + the interaction token, released exactly once;
+ * - the dirty flag the admin bar's exit button reads;
+ * - Cmd/Ctrl+Enter to save (plain Enter stays a newline — a panel has a Save
+ *   button, unlike an inline edit);
+ * - **staying open when a save is refused.** A refusal here is an ordinary
+ *   outcome — a disallowed tag, an ambiguous match — that the user fixes and
+ *   retries, so the reason is shown inside the panel with the text intact
+ *   rather than closing and losing the work.
+ */
+
+export interface SourcePopupOptions {
+  /** Panel title bar, e.g. `Markup · index.astro:44:13`. */
+  title: string;
+  /** Label above the box. */
+  label: string;
+  /** Initial (and baseline) text. */
+  value: string;
+  /** Minimum height of the editing box. */
+  minHeight?: string;
+  /** Monospace box (source) rather than proportional (prose). */
+  mono?: boolean;
+  /** Optional controls under the box, built with the live textarea. */
+  tools?: (input: HTMLTextAreaElement, markDirty: () => void) => HTMLElement;
+  /**
+   * Write the edit. Resolve `null` on success — the panel then closes — or the
+   * message to show inside the still-open panel.
+   */
+  save: (value: string) => Promise<string | null>;
+  /**
+   * Jump to the source in the user's editor. Adds an **open** button to the
+   * title bar: what these popups edit *is* source, so the file it came from
+   * should be one click away — the same escape hatch the hover pill and the
+   * refusal notice offer. Editing continues; the panel stays open.
+   */
+  openSource?: () => void;
+}
+
+export function openSourcePopup(opts: SourcePopupOptions): void {
+  let jump: HTMLElement | undefined;
+  if (opts.openSource) {
+    const btn = pillButton(
+      'atx-panel-open',
+      'open',
+      'Open this location in your editor',
+      { marginLeft: '0', flex: '0 0 auto' },
+      icon('external', 12),
+    );
+    btn.addEventListener('click', () => opts.openSource?.());
+    jump = btn;
+  }
+
+  const panel = buildPanel(opts.title, jump);
+  const body = panel.querySelector('[data-body]') as HTMLElement;
+
+  const label = styled('label', 'atx-popup-label');
+  label.textContent = opts.label;
+
+  // Only the caller's height override stays inline; the face is a flag, since
+  // both faces are fixed and only the choice between them is the caller's.
+  const input = inputEl(
+    'textarea',
+    'atx-popup-input',
+    opts.minHeight ? { minHeight: opts.minHeight } : undefined,
+  );
+  if (opts.mono) input.dataset.mono = '';
+  input.value = opts.value;
+
+  const error = styled('p', 'atx-popup-error');
+
+  const markDirty = (): void => {
+    state.setSavePhase(input.value.trim() === opts.value.trim() ? 'clean' : 'dirty');
+  };
+
+  body.append(label, input);
+  if (opts.tools) body.append(opts.tools(input, markDirty));
+  body.append(error);
+
+  // `commit` is what leaving edit mode runs: an action labelled "Save & exit"
+  // must write the draft in the box, not drop it. A refusal keeps the panel
+  // open (see `run`), and the error phase keeps edit mode open with it.
+  const claim = (): Interaction =>
+    state.begin({ kind: 'panel', close: () => close(false), commit: () => close(true) });
+
+  let token = claim();
+  let saving = false;
+
+  const teardown = (): void => {
+    state.releaseIf(token);
+    releaseFocus();
+    panel.remove();
+    backdrop.remove();
+  };
+
+  const setBusy = (busy: boolean): void => {
+    for (const btn of panel.querySelectorAll('button')) btn.disabled = busy;
+    input.readOnly = busy;
+  };
+
+  const run = async (): Promise<void> => {
+    saving = true;
+    setBusy(true);
+    error.toggleAttribute('data-on', false);
+
+    const failure = await opts.save(input.value);
+
+    saving = false;
+    if (!failure) {
+      teardown();
+      return;
+    }
+    // The in-flight `busy` interaction released the slot; re-claim it so the
+    // still-open panel keeps owning the page's clicks.
+    token = claim();
+    setBusy(false);
+    error.textContent = failure;
+    error.toggleAttribute('data-on', true);
+    input.focus();
+  };
+
+  const close = (commit: boolean): void => {
+    if (saving) return; // the write is in flight; let it settle
+    if (!commit || input.value.trim() === opts.value.trim()) {
+      teardown();
+      state.setSavePhase('clean');
+      return;
+    }
+    void run();
+  };
+
+  const backdrop = buildBackdrop(() => close(false));
+  wirePanelButtons(panel, () => close(false), () => close(true));
+
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      close(true);
+    }
+  });
+  input.addEventListener('input', markDirty);
+
+  mount(backdrop, panel);
+  const releaseFocus = trapFocus(panel, { initial: input });
+  input.setSelectionRange(input.value.length, input.value.length);
+}