astrolabe/docs/architecture/03-modal-system.md

03 · Modal System

How Astrolabe manages its modals: a single metadata-driven registry, a thin lifecycle coordinator, and one rendering shell. This document is the authoritative architecture for adding, opening, closing, and rendering modals.

Goals

• One source of truth for modal metadata — no switch statements scattered across the codebase keyed on the active modal.
• At most one modal open at a time (mandated by the product spec). Opening a modal closes any other; the two never overlap.
• Uniform dismissal: close button, Escape, or backdrop click — never a click inside the body. A modal holding in-progress work can opt out of the backdrop click (dismissOnBackdrop: false) so a stray click can't discard it (the Chart Builder does); close button and Escape still dismiss.
• Accessible by default: focus moves into the modal on open and returns to the trigger on close.
• Unsaved-change safety for editing modals, with an explicit opt-out for modals that apply changes immediately.

The system is three layers, each with a single responsibility:

Layer	Responsibility	Lives in
Registry	Static metadata per modal (title, validity, snapshot, init)	src/app/modals/modal-registry.ts
Coordinator	Lifecycle: open, close, URL sync, change detection	src/app/modals/ModalCoordinator.ts
Shell	Render exactly one modal; backdrop / Escape / focus trap	src/app/App.tsx + a useFocusTrap hook

---

The Modal Set

Astrolabe has a small, fixed set of modals. Model it as a closed union so the registry, coordinator, and shell are exhaustively type-checked.

// src/app/modals/types.ts
export type ModalName =
  | 'datasets' // Datasets manager (list / detail / new-dataset form)
  | 'about' // About & Help (shortcuts, privacy)
  | 'donate' // Donate
  | 'chartBuilder' // Visual no-JSON chart composition for a dataset
  | 'extract'; // Extract inline spec data into a new dataset
// Settings is NOT a modal — preferences are distributed to per-pane disclosure
// popovers (spec §01C/§07; see components/SettingsPopover).

export type ActiveModal = ModalName | null;

Two of these — chartBuilder and extract — are opened from within workflows (the Datasets manager and the snippet editor), not from the header toolbar. That is a UI wiring detail, not a structural one: every modal opens through the same coordinator regardless of where the trigger lives.

---

Layer 1 — Registry

Each modal is registered once with its metadata. The registry is a plain lookup object keyed by ModalName; order is irrelevant. Utility queries (title, validity, whether a modal participates in URL state) read from the registry so there is exactly one place to change when behavior shifts.

Config shape

// src/app/modals/modal-registry.ts
import type { ComponentType } from 'react';
import type { ModalName } from './types';

export interface ModalConfig {
  name: ModalName;
  title: string; // i18n key or literal
  component: ComponentType<any>; // the body rendered inside the shell

  /** Initialize transient modal state when it opens. `arg` carries an
   *  optional sub-target (e.g. a dataset id for chartBuilder/extract). */
  init?: (arg?: string) => void;

  /** Serializable snapshot of in-progress edits, used to detect unsaved
   *  changes on close. OMIT for modals with no in-progress edits to guard
   *  (about, donate) — omission opts out of the discard-confirmation. */
  getState?: () => Record<string, unknown> | null;

  /** Whether the modal's primary action (Save / Apply) should be blocked
   *  because the current input is invalid. Drives the disabled button. */
  hasError?: () => boolean;

  /** Human-readable reason for the disabled action, shown as a tooltip. */
  getError?: () => string | null;

  /** Whether this modal is reflected in the URL hash (back/forward, reload
   *  restore). Datasets and Chart Builder are navigable; About/Donate/Extract
   *  are not (spec §01E). */
  isUrlNavigable?: boolean;
}

Shipped divergence. The implemented registry (modals/modal-registry.ts) omits hasError/getError: each modal renders its own action row inside its body (the multi-view Datasets manager doesn't fit a single shell-level Save/Cancel), so validity is each modal's own concern. The shipped ModalConfig keeps only getState (close-time unsaved-change detection) plus init/isUrlNavigable. The generic-footer sketch through the rest of this section is retained as the simpler pattern for a single-action modal — treat it as illustrative, not a description of current code.

Example entries

import { DatasetsModal } from '../components/DatasetsModal';
import { ChartBuilderModal } from '../components/ChartBuilderModal';
import { ExtractModal } from '../components/ExtractModal';
import { DonateModal } from '../components/DonateModal';
import { AboutModal } from '../components/AboutModal';
import { useDatasetStore } from '../stores/DatasetStore';
import { useChartBuilderStore } from '../stores/ChartBuilderStore';
import { useExtractStore } from '../stores/ExtractStore';

// Per-modal transient state lives in the relevant feature store; the registry
// reads it via `getState()` (Zustand), never through component hooks.
export const MODAL_REGISTRY: Record<ModalName, ModalConfig> = {
  // Navigable, editing modal — snapshot guards unsaved work.
  datasets: {
    name: 'datasets',
    title: 'modals.datasets.title',
    component: DatasetsModal,
    isUrlNavigable: true,
    init: (datasetId) => useDatasetStore.getState().select(datasetId ?? null),
    getState: () => {
      const s = useDatasetStore.getState();
      return {
        view: s.view, // 'list' | 'detail' | 'new'
        draft: s.draftForm, // in-progress new/edit form
      };
    },
    hasError: () => useDatasetStore.getState().formError !== null,
    getError: () => useDatasetStore.getState().formError,
  },

  // Opened from a workflow (a specific dataset), navigable, editing.
  chartBuilder: {
    name: 'chartBuilder',
    title: 'modals.chartBuilder.title',
    component: ChartBuilderModal,
    isUrlNavigable: true,
    init: (datasetId) => useChartBuilderStore.getState().initFor(datasetId),
    getState: () => ({ encoding: useChartBuilderStore.getState().encoding }),
    hasError: () => !useChartBuilderStore.getState().markType,
    getError: () =>
      useChartBuilderStore.getState().markType ? null : 'modals.chartBuilder.pickMark',
  },

  // Opened from the snippet editor with the inline data to lift out.
  extract: {
    name: 'extract',
    title: 'modals.extract.title',
    component: ExtractModal,
    init: (sourceKey) => useExtractStore.getState().initFrom(sourceKey),
    getState: () => ({ name: useExtractStore.getState().name }),
    hasError: () => useExtractStore.getState().name.trim() === '',
    getError: () => (useExtractStore.getState().name.trim() ? null : 'modals.extract.nameRequired'),
  },

  // Pure info modals — no state, no validity, not navigable.
  about: { name: 'about', title: 'modals.about.title', component: AboutModal },
  donate: { name: 'donate', title: 'modals.donate.title', component: DonateModal },
};

Registry queries

All callers go through these helpers instead of inspecting the active modal directly:

export const getModalConfig = (name: ActiveModal): ModalConfig | undefined =>
  name ? MODAL_REGISTRY[name] : undefined;

export const getModalTitle = (name: ActiveModal): string => getModalConfig(name)?.title ?? '';

export const isUrlNavigable = (name: ActiveModal): boolean =>
  getModalConfig(name)?.isUrlNavigable ?? false;

Why metadata-driven? The alternative — branching on the active modal in the shell, the URL sync, the keyboard handler, and the close logic — spreads one decision across four files. Each new modal then means four edits and a chance to forget one. With the registry, a new modal is one entry plus its component.

Do

• Add a modal by appending one MODAL_REGISTRY entry and writing its component.
• Express validity through hasError / getError so the shell's action button and tooltip stay generic.
• Omit getState for any modal that commits changes immediately.

Don't

• Don't switch (activeModal) outside the shell's body render. Lookups belong in registry helpers.
• Don't put rendering or DOM concerns in the registry — it is pure metadata.
• Don't read rapidly-changing input state inside hasError/getState from component render paths; compute them with a selector at the shell boundary (see Shell layer) so a keystroke doesn't re-render the whole app.

---

Layer 2 — Coordinator

The coordinator owns the modal lifecycle. It mutates a single piece of state — the active modal name — plus a snapshot used for change detection, and keeps the URL in sync. It is framework-light: pure functions over a Zustand store, unit testable without a DOM.

State

The active modal name is cross-cutting UI chrome, so it lives on the central useAppStore (activeModal + the setActiveModal primitive — see docs/architecture/01). The coordinator never gets its own store; the only extra piece of state it needs is the change-detection snapshot, which is coordinator-internal (no component reads it), so it stays as a module-local variable rather than store state.

// useAppStore already exposes:
//   activeModal: ModalName | null
//   setActiveModal: (modal: ModalName | null) => void

Open / close

// src/app/modals/ModalCoordinator.ts
import { useAppStore } from '../stores/AppStore';
import { MODAL_REGISTRY, getModalConfig } from './modal-registry';
import { syncModalToUrl, clearModalFromUrl } from './UrlStateSync';

let confirmDiscard: (msg: string) => Promise<boolean> = async () => true;
export const setConfirm = (fn: typeof confirmDiscard) => {
  confirmDiscard = fn;
};

// Coordinator-internal: the getState() JSON captured at open, compared on close.
let stateSnapshot: string | null = null;

const snapshot = (name: ActiveModal) =>
  getModalConfig(name)?.getState ? JSON.stringify(getModalConfig(name)!.getState!()) : null;

/** Open `name`, optionally with a sub-target (dataset id, source key). */
export function openModal(name: ModalName, arg?: string): void {
  // Opening any modal replaces the previous one — at most one open at a time.
  useAppStore.getState().setActiveModal(name);
  getModalConfig(name)?.init?.(arg);
  stateSnapshot = snapshot(name);
  syncModalToUrl(name, arg); // no-op when !isUrlNavigable
}

/** Close the active modal. Prompts on unsaved changes unless `force`. */
export async function closeModal(force = false): Promise<void> {
  const name = useAppStore.getState().activeModal;
  if (!name) return;

  if (!force && hasUnsavedChanges()) {
    const ok = await confirmDiscard('modals.discardChanges');
    if (!ok) return;
  }

  clearModalFromUrl(name);
  useAppStore.getState().setActiveModal(null);
  stateSnapshot = null;
  getModalConfig(name)?.init?.(undefined); // optional: reset transient state
}

/** Cmd/Ctrl+K toggle for the Datasets manager. */
export function toggleDatasets(): void {
  if (useAppStore.getState().activeModal === 'datasets') void closeModal();
  else openModal('datasets');
}

Change detection

export function hasUnsavedChanges(): boolean {
  const name = useAppStore.getState().activeModal;
  if (!name || stateSnapshot === null) return false; // no snapshot ⇒ opted out
  const current = getModalConfig(name)?.getState?.();
  if (current == null) return false;
  return JSON.stringify(current) !== stateSnapshot;
}

The snapshot is taken once on open and compared on close. Modals without getState (about, donate) snapshot to null, so hasUnsavedChanges short-circuits and they close instantly — correct, because they hold nothing to lose.

Validity passthrough

export const activeModalHasError = (): boolean =>
  getModalConfig(useAppStore.getState().activeModal)?.hasError?.() ?? false;

export const activeModalError = (): string | null =>
  getModalConfig(useAppStore.getState().activeModal)?.getError?.() ?? null;

Why a coordinator instead of letting components open/close themselves? Centralizing means the "close the previous one", snapshot, URL-sync, and discard-prompt rules are enforced once. A component that opened a peer modal directly could bypass the discard check or leave the URL stale.

Do

• Route every open/close through openModal / closeModal.
• Take the snapshot in openModal (after init) and compare in closeModal.
• Keep the coordinator DOM-free so it can be tested with plain Vitest.

Don't

• Don't mutate activeModal directly from components or handlers.
• Don't skip closeModal's unsaved-change check by toggling state manually; pass force only when the user has explicitly saved or confirmed.

---

Layer 3 — Shell

App renders exactly one modal — whichever activeModal names — inside a single reusable shell. The shell provides the backdrop, header, focus trap, and the generic close/action affordances; the modal's registered component fills the body.

// src/app/App.tsx (modal portion)
import { useAppStore } from '../stores/AppStore';
import { getModalConfig, getModalTitle } from '../modals/modal-registry';
import { closeModal, activeModalHasError, activeModalError } from '../modals/ModalCoordinator';
import { useFocusTrap } from '../hooks/useFocusTrap';

export function App() {
  const name = useAppStore((s) => s.activeModal);
  const config = getModalConfig(name);

  // Move focus into the modal on open, return it to the trigger on close.
  const modalRef = useFocusTrap<HTMLDivElement>(name !== null);

  // Derived at the shell boundary so per-keystroke store reads don't
  // re-render the whole app tree.
  const hasError = activeModalHasError();
  const errorMsg = activeModalError();

  return (
    <div className={styles.app}>
      {/* ...library · editor · preview panes, header... */}

      {config && (
        <div
          className={styles.backdrop}
          onClick={() => void closeModal()} // backdrop dismisses
          onKeyDown={(e) => {
            if (e.key === 'Escape') void closeModal();
          }}
        >
          <div
            ref={modalRef}
            className={styles.modal}
            role="dialog"
            aria-modal="true"
            aria-labelledby="modal-title"
            onClick={(e) => e.stopPropagation()} // inside body never dismisses
          >
            <header className={styles.modalHeader}>
              <h2 id="modal-title">{t(getModalTitle(name))}</h2>
              <button aria-label={t('buttons.close')} onClick={() => void closeModal()}>
                ×
              </button>
            </header>

            <div className={styles.modalBody}>
              {/* The ONE place the active modal is mapped to a component. */}
              <config.component />
            </div>

            {/* Optional generic action row for editing modals. A modal with no
                primary action (about, donate) can render its own footer/none. */}
            {config.getState && (
              <footer className={styles.modalFooter}>
                <button className="btn-secondary" onClick={() => void closeModal()}>
                  {t('buttons.cancel')}
                </button>
                <button
                  className="btn-primary"
                  aria-disabled={hasError || undefined}
                  title={errorMsg ? t(errorMsg) : undefined}
                  onClick={() => {
                    if (!hasError) config.component /* invoke save handler */;
                  }}
                >
                  {t('buttons.save')}
                </button>
              </footer>
            )}
          </div>
        </div>
      )}
    </div>
  );
}

Rendering <config.component /> from the registry is the only modal-name→view mapping in the app. There is no name === 'datasets' && <DatasetsModal/> chain.

Focus trap

A small hook saves the previously focused element, focuses a focusable child on open, wraps Tab/Shift+Tab within the modal, and restores focus on close. The optional initialSelector picks which child takes focus (e.g. Cancel for a destructive confirm); it falls back to the first focusable child.

The trap wraps Tab only within the shell element: content portaled to <body> (a SelectControl panel or other disclosure popover opened from inside a modal) is outside both the trap's DOM subtree and its keydown listener. Such popovers must therefore handle Tab themselves — close and refocus their trigger (the native-select convention) — so focus can't strand outside the dialog while it is open.

// src/app/hooks/useFocusTrap.ts
import { useRef, useEffect } from 'react';

const FOCUSABLE =
  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), ' +
  'textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

export function useFocusTrap<T extends HTMLElement = HTMLDivElement>(
  active: boolean,
  initialSelector?: string,
) {
  const ref = useRef<T>(null);
  const returnTo = useRef<Element | null>(null);

  useEffect(() => {
    const el = ref.current;
    if (!active || !el) return;

    returnTo.current = document.activeElement;
    const initial =
      (initialSelector ? el.querySelector<HTMLElement>(initialSelector) : null) ??
      el.querySelector<HTMLElement>(FOCUSABLE);
    initial?.focus();

    const onKey = (e: KeyboardEvent) => {
      if (e.key !== 'Tab') return;
      const f = el.querySelectorAll<HTMLElement>(FOCUSABLE);
      if (!f.length) return;
      const first = f[0],
        last = f[f.length - 1];
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    };

    el.addEventListener('keydown', onKey);
    return () => {
      el.removeEventListener('keydown', onKey);
      (returnTo.current as HTMLElement | null)?.focus(); // restore focus on close
    };
  }, [active, initialSelector]);

  return ref;
}

Why one shell instead of each modal rendering its own chrome? Backdrop behavior, the focus trap, aria-modal, Escape handling, and the close button are identical for every modal and easy to get subtly wrong (e.g. a backdrop that dismisses on inner clicks). Centralizing guarantees consistency and means accessibility is fixed once.

Do

• Render the active modal via <config.component /> — the single mapping point.
• Put onClick={closeModal} on the backdrop and stopPropagation on the body.
• Compute hasError/getError/preview reads with a selector at the shell level.
• Gate the generic Save button on hasError and surface getError as its tooltip.

Don't

• Don't render two modals simultaneously, and don't stack a second backdrop.
• Don't attach the focus trap to the backdrop — attach it to the modal body so the backdrop click stays outside the trap.
• Don't dismiss on clicks inside the body, and don't let Escape fire when no modal is open (the handler only exists while a modal renders).

Sizing & backdrop opt-out. The shell picks a size tier by modal: a small form (Extract), a large two-pane manager (Datasets), or a near-fullscreen work surface (Chart Builder — a config pane plus a chart that wants room). The two larger tiers have a definite height so their inner panes scroll internally rather than the modal growing past the viewport. A modal opts a backdrop click out of dismissal with the registry's dismissOnBackdrop: false (above).

---

Confirmation & alert dialogs

The registry/coordinator/shell above governs the named feature modals — a fixed, registered, URL-navigable set with "at most one open at a time". A destructive confirmation ("Delete Name? This cannot be undone.") is a different animal and gets a separate, lighter layer rather than a ModalName entry. Three properties force the split:

• Ephemeral & content-on-call. A confirm isn't a fixed surface with a stored component; its title/message/labels are supplied at the call site. There's nothing to register.
• Stacks above a feature modal. The discard-changes prompt must appear over an already-open feature modal (e.g. Datasets or Chart Builder) — which directly violates the feature layer's "at most one open" rule. So confirmations live on a higher z-layer (z-index: 1000, above the future modal shell).
• Not navigable. A confirmation is never a URL destination or a reload-restore target; it only exists for the duration of one decision.

The primitive

A promise-based store + one globally-mounted renderer. confirm(opts) returns Promise<boolean> and is callable from anywhere — React components and non-React code alike:

// src/app/stores/ConfirmStore.ts
import { confirm } from '../stores/ConfirmStore';

const ok = await confirm({
  title: 'Delete snippet',
  message: `Delete "${name}"? This cannot be undone.`,
  confirmLabel: 'Delete',
  danger: true, // Carbon "danger" styling + Cancel-defaulted focus
});
if (ok) removeSnippet(id);

Piece	Responsibility	Lives in
useConfirmStore / confirm()	Hold the open request; resolve the awaiting promise	src/app/stores/ConfirmStore.ts
ConfirmDialog	Render the active request; backdrop, focus trap, Escape, danger	src/app/components/ConfirmDialog.tsx
useFocusTrap	Shared overlay focus trap (this dialog now, the shell later)	src/app/hooks/useFocusTrap.ts

ConfirmDialog is mounted once at the app root. Only one confirmation shows at a time; opening a second resolves the first false so no awaiter hangs.

Dismissal — Carbon's transactional rule

Confirmations follow Carbon's transactional / danger modal behavior, not the passive-modal behavior the feature shell uses:

• Escape and Cancel resolve false.
• A backdrop click does not dismiss — the user must pick an action, so a destructive choice is never made by an accidental outside click. (Contrast the feature shell, where backdrop-click dismiss is correct for passive modals.)
• For danger requests, initial focus goes to Cancel, so a stray Enter can't destroy anything; non-danger confirms focus the primary action.
• role="alertdialog" (not dialog) with aria-describedby on the message.

The coordinator seam

The feature-modal coordinator exposes setConfirm(fn) for its unsaved-change prompt. Once the feature-modal system lands, wire it to this same primitive:

setConfirm((message) => confirm({ title: 'Discard changes?', message, danger: true }));

That keeps every destructive/lossy decision — deletes, revert, reset, and discard-on-close — flowing through one consistent dialog. Per spec §10, all destructive actions confirm; per §01, non-blocking outcomes (success, info) are toasts, not dialogs — don't reach for a confirm where a toast is the right tool.

URL & Keyboard Integration

The coordinator is the join point for navigation:

• openModal calls syncModalToUrl; navigable modals write a hash (#datasets, #datasets/dataset-<id>, #datasets/dataset-<id>/build). Non-navigable modals (about, donate, extract) write nothing.
• closeModal calls clearModalFromUrl, returning to the underlying workspace hash.
• On load, the URL restorer reads the hash and calls openModal(name, arg) to rehydrate the right modal and sub-target.
• The global key handler maps Cmd/Ctrl+K → toggleDatasets() and Escape → closeModal() (a no-op when activeModal is null). Cmd/Ctrl+, opens the editor settings popover, not a modal (openSettingsPopover('editor-settings'); settings are distributed — spec §01C/§07).

Because all of these call the same coordinator functions, browser Back/Forward, keyboard shortcuts, and in-app triggers stay consistent — they share the open/close/snapshot/URL logic rather than reimplementing it.

---

Adding a Modal: Checklist

1. Add the name to the ModalName union.
2. Add one MODAL_REGISTRY entry (title, component; getState/hasError/ getError if it edits; isUrlNavigable + init(arg) if navigable; dismissOnBackdrop: false if it holds in-progress work).
3. Write the body component; it reads/writes its feature store (e.g. useDatasetStore, useChartBuilderStore) via a narrow selector.
4. If it isn't a small form, add its name to the size-tier mapping in ModalShell (isLarge/isXLarge) — the one shell edit a new modal can need; without it the modal renders at the small-form size.
5. If navigable, add its hash form to the URL sync and restore logic.
6. If it has a keyboard shortcut or workflow trigger, wire that to openModal(name, arg) — never to activeModal directly.

The shell render, close logic, and change detection need no edits: those are generic and driven entirely by the registry.