refactor: separate Layers panel presentation from lifecycle actions

src/ui/clearLayersControl.js

@@ -0,0 +1,18 @@
+/** Keep the clear action focusable while busy; the caller owns its transaction. */
+export function bindClearLayersControl(button, clear) {
+  let destroyed = false;
+  const click = () => { if (!destroyed) void clear(); };
+  button?.addEventListener('click', click);
+  return {
+    setBusy(busy) {
+      if (destroyed || !button) return;
+      button.setAttribute('aria-disabled', String(busy));
+      button.setAttribute('aria-busy', String(busy));
+      button.setAttribute('aria-label', busy ? 'Clearing selected data layers' : 'Clear selected data layers');
+    },
+    destroy() {
+      destroyed = true;
+      button?.removeEventListener('click', click);
+    },
+  };
+}

src/ui/layerPanel.js

@@ -0,0 +1,379 @@
+import { GUIDANCE_STATUSES } from '../loadingFeedback.js';
+const FEED_STATE_LABELS = Object.freeze({
+  nominal: 'ON',
+  loading: 'LOADING',
+  degraded: 'DEGRADED',
+  stale: 'STALE',
+  fallback: 'FALLBACK',
+  unavailable: 'UNAVAILABLE',
+});
+
+/**
+ * Normalize heterogeneous layer stats into one honest control-chip state.
+ * @param {object|null} stats Layer getStats() result.
+ * @returns {'nominal'|'loading'|'degraded'|'stale'|'fallback'|'unavailable'} Feed state.
+ */
+export function layerFeedState(stats = {}) {
+  const state = stats || {};
+  const status = typeof state.status === 'string' ? state.status.toLowerCase() : '';
+  const source = `${state.source || ''} ${state.coverage || ''}`;
+  const hasExplicitFallback = typeof state.fallback === 'boolean';
+  const hasPriorData = Number(state.count) > 0 || Boolean(state.lastUpdate);
+  const presentedError = state.error || state.lastError || state.managerRefreshError;
+  if (['unavailable', 'offline', 'down', 'error'].includes(status)) return 'unavailable';
+  if (
+    (presentedError || state.unavailable === true || state.available === false)
+    && !hasPriorData
+    && !GUIDANCE_STATUSES.includes(status)
+  ) {
+    return 'unavailable';
+  }
+  if (state.loading) return 'loading';
+  // Guidance states ask the user to act (zoom in, run a search) — normal
+  // operation, not feed faults. One honesty carve-out: layers keep their
+  // rendered records through the guidance state, so a genuinely stale cache
+  // still reads STALE; a guidance prompt alone never reads DEGRADED.
+  if (GUIDANCE_STATUSES.includes(status)) {
+    return state.stale ? 'stale' : 'nominal';
+  }
+  if (
+    state.fallback === true
+    || status === 'fallback'
+    || state.mode === 'sim'
+    || /\bfallback\b/i.test(source)
+    || (!hasExplicitFallback && /\badsb\.lol\b/i.test(source))
+  ) {
+    return 'fallback';
+  }
+  if (state.stale || status === 'stale') return 'stale';
+  if (
+    state.degraded
+    || presentedError
+    || state.unavailable === true
+    || state.available === false
+  ) return 'degraded';
+  return 'nominal';
+}
+
+
+/** Layer row presentation over supplied state and actions; no layer imports. */
+export class LayerPanel {
+  constructor({ getLayers, isEnabled, setEnabled, setLayerParams, getRowControls,
+    hasRowControls, subscribeRowControls, onHiddenRefresh = () => {} }) {
+    this.getAll = getLayers;
+    this.isEnabled = isEnabled;
+    this.setEnabled = setEnabled;
+    this.setLayerParams = setLayerParams;
+    this._rowControlsFor = getRowControls;
+    this.hasRowControls = hasRowControls;
+    this.subscribeRowControls = subscribeRowControls;
+    this.onHiddenRefresh = onHiddenRefresh;
+    this._generation = 0;
+    this._removers = [];
+    this._destroyed = false;
+  }
+  mount(container) {
+    if (this._destroyed) return;
+    this._releaseBindings();
+    this._toggleContainer = container;
+    this._renderToggles();
+  }
+  _bind(element, type, listener) {
+    element.addEventListener(type, listener);
+    this._removers.push(() => element.removeEventListener(type, listener));
+  }
+  _releaseBindings() {
+    this._generation++;
+    for (const remove of this._removers.splice(0)) remove();
+  }
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._releaseBindings();
+    this._toggleContainer = null;
+  }
+  _renderToggles() {
+    if (this._destroyed || !this._toggleContainer) return;
+    this._releaseBindings();
+    this._toggleContainer.innerHTML = '';
+
+    const generation = this._generation;
+    for (const layer of this.getAll()) {
+      if (!layer.showInTogglePanel) continue;
+      const row = document.createElement('div');
+      row.className = 'data-toggle-row';
+      row.dataset.layerId = layer.id;
+
+      const topRow = document.createElement('div');
+      topRow.className = 'data-toggle-top';
+
+      const left = document.createElement('div');
+      left.className = 'data-toggle-left';
+      const icon = document.createElement('span');
+      icon.className = 'data-icon';
+      icon.textContent = layer.icon;
+      const name = document.createElement('span');
+      name.className = 'data-name';
+      name.textContent = layer.name;
+      left.appendChild(icon);
+      left.appendChild(name);
+
+      const right = document.createElement('div');
+      right.className = 'data-toggle-right';
+
+      const count = document.createElement('span');
+      count.className = 'data-count';
+      count.textContent = layer.stats.count ? this._formatCount(layer.stats.count) : '—';
+
+      const toggle = document.createElement('button');
+      toggle.type = 'button';
+      toggle.className = `data-toggle-btn${layer.enabled ? ' active' : ''}`;
+      this._syncToggleButton(toggle, layer);
+      this._bind(toggle, 'click', async () => {
+        // Native `disabled` immediately evicts keyboard focus in Chromium. Keep
+        // the lifecycle control focusable while it is busy, and enforce the
+        // same single-flight interaction contract through ARIA instead.
+        if (this._destroyed || this._generation !== generation || toggle.getAttribute('aria-disabled') === 'true') return;
+        toggle.setAttribute('aria-disabled', 'true');
+        toggle.setAttribute('aria-busy', 'true');
+        try {
+          await this.setEnabled(layer.id, !this.isEnabled(layer.id), { origin: 'user' });
+        } catch (error) {
+          console.warn(`[Data] ${layer.id} toggle error:`, error);
+        } finally {
+          const current = this.getAll().find(({ id }) => id === layer.id);
+          if (!this._destroyed && current && this._generation === generation) this._syncToggleButton(toggle, current);
+        }
+      });
+
+      right.appendChild(count);
+      right.appendChild(toggle);
+      topRow.appendChild(left);
+      topRow.appendChild(right);
+
+      const bottomRow = document.createElement('div');
+      bottomRow.className = 'data-toggle-meta';
+      bottomRow.textContent = this._buildMetaText(layer);
+
+      row.appendChild(topRow);
+      row.appendChild(bottomRow);
+
+      // Optional per-layer sub-controls (chips + color legend). The click
+      // listener is delegated and attached once here, so it survives
+      // _refreshTogglePanel — which only rewrites the container's contents.
+      if (this.hasRowControls(layer.id)) {
+        // A layer whose controls settle asynchronously (a chunked catalog load
+        // that can also fail) pushes a re-render through this; nothing else
+        // would repaint the row before its next scheduled refresh.
+        const unsubscribe = this.subscribeRowControls(layer.id, () => this._refreshTogglePanel());
+        if (unsubscribe) this._removers.push(unsubscribe);
+        const controls = document.createElement('div');
+        controls.className = 'data-toggle-controls';
+        this._bind(controls, 'click', (event) => {
+          const button = event.target?.closest?.('.data-toggle-chip');
+          if (!button || button.disabled) return;
+          // Re-read the live descriptor rather than trusting the rendered
+          // chip, so a stale row can never apply an inverted toggle.
+          const chip = this._rowControlsFor(layer.id)?.chips
+            ?.find((entry) => entry.id === button.dataset.chipId);
+          if (chip?.params) this.setLayerParams(layer.id, chip.params, { origin: 'user' });
+        });
+        row.appendChild(controls);
+        this._syncRowControls(controls, layer);
+      }
+
+      this._toggleContainer.appendChild(row);
+    }
+  }
+
+  /**
+   * Read a layer's optional row-control descriptor, tolerating a throw so one
+   * misbehaving layer cannot blank the whole panel. Resolved from the registry
+   * rather than the `getAll()` projection, which deliberately omits `module`.
+   * @param {string} layerId Registered layer id.
+   * @returns {{ chips?: Array<object>, legend?: Array<object> }|null} Descriptor.
+   */
+
+  /**
+   * Render a layer's row chips and color legend, and keep the whole block
+   * hidden while the layer is off (or while a dependency owner has surrendered
+   * it) so a quiet row stays quiet.
+   *
+   * Chip BUTTONS are reconciled in place, keyed by chip id, rather than
+   * rebuilt: this runs on every panel refresh — including the one the chip's
+   * own click triggers — and replacing the node would drop keyboard focus
+   * mid-interaction. Legend entries hold no focus and no listeners, so they
+   * are replaced freely.
+   * @param {HTMLElement|null} container The row's `.data-toggle-controls` node.
+   * @param {object} layer Registered layer entry.
+   */
+  _syncRowControls(container, layer) {
+    if (!container) return;
+    const controls = layer.enabled ? this._rowControlsFor(layer.id) : null;
+    const chips = controls?.chips || [];
+    const legend = controls?.legend || [];
+    container.hidden = chips.length === 0 && legend.length === 0;
+
+    for (const node of [...container.children]) {
+      if (String(node.className).split(/\s+/).includes('data-toggle-legend-item')) node.remove();
+    }
+
+    const stale = new Map();
+    for (const node of [...container.children]) {
+      if (node.dataset?.chipId) stale.set(node.dataset.chipId, node);
+    }
+
+    for (const chip of chips) {
+      let button = stale.get(chip.id);
+      stale.delete(chip.id);
+      if (!button) {
+        button = document.createElement('button');
+        button.type = 'button';
+        button.dataset.chipId = chip.id;
+        container.appendChild(button);
+      }
+      const state = chip.state || (chip.active ? 'active' : 'idle');
+      button.className = `data-toggle-chip chip-${state}${chip.active ? ' active' : ''}`;
+      if (button.textContent !== chip.label) button.textContent = chip.label;
+      button.title = chip.title || '';
+      button.disabled = Boolean(chip.disabled);
+      button.setAttribute('aria-pressed', chip.active ? 'true' : 'false');
+      button.setAttribute('aria-busy', chip.busy ? 'true' : 'false');
+    }
+    for (const node of stale.values()) node.remove();
+
+    for (const item of legend) {
+      const entry = document.createElement('span');
+      entry.className = 'data-toggle-legend-item';
+      if (item.blurb) entry.title = item.blurb;
+      const swatch = document.createElement('span');
+      swatch.className = 'data-toggle-legend-swatch';
+      swatch.style.background = item.color;
+      const text = document.createElement('span');
+      text.textContent = `${item.label} ${this._formatCount(item.count)}`;
+      entry.append(swatch, text);
+      container.appendChild(entry);
+    }
+  }
+
+  _refreshTogglePanel() {
+    if (this._destroyed || !this._toggleContainer) return;
+    // Skip DOM churn while hidden; visibilitychange (main.js) triggers one
+    // refresh on return. (perf wave 2)
+    if (typeof document !== 'undefined' && document.hidden) {
+      this.onHiddenRefresh();
+      return;
+    }
+    for (const layer of this.getAll()) {
+      const row = this._toggleContainer.querySelector(`[data-layer-id="${layer.id}"]`);
+      if (!row) continue;
+
+      const btn = row.querySelector('.data-toggle-btn');
+      if (btn) {
+        this._syncToggleButton(btn, layer);
+      }
+
+      const count = row.querySelector('.data-count');
+      if (count) {
+        count.textContent = layer.stats.count ? this._formatCount(layer.stats.count) : '—';
+      }
+
+      const meta = row.querySelector('.data-toggle-meta');
+      if (meta) {
+        meta.textContent = this._buildMetaText(layer);
+      }
+
+      this._syncRowControls(row.querySelector('.data-toggle-controls'), layer);
+    }
+  }
+
+  _buildMetaText(layer) {
+    const stats = layer.stats || {};
+    const feedState = layerFeedState(stats);
+    const stateLabel = FEED_STATE_LABELS[feedState];
+    const source = stats.source || layer.source;
+    const lifecycleState = layer.lifecycleState || (layer.enabled ? 'enabled' : 'disabled');
+    if (lifecycleState === 'enabling' || lifecycleState === 'disabling') {
+      return `${lifecycleState.toUpperCase()} · ${source}`;
+    }
+    if (layer.lifecycleUncertain) {
+      return `UNCERTAIN · ${source} · lifecycle state requires reconciliation`;
+    }
+    const presentedError = stats.error || stats.lastError || stats.managerRefreshError;
+    if (presentedError) {
+      if (typeof stats.retryInSec === 'number' && stats.retryInSec > 0) {
+        return `${stateLabel} · ${source} · ${presentedError} · retry ${stats.retryInSec}s`;
+      }
+      return `${stateLabel} · ${source} · ${presentedError}`;
+    }
+    // A guidance status carries its prompt in `statusMessage`, not `error`, so
+    // the row still tells the operator what to do without reporting a fault.
+    if (GUIDANCE_STATUSES.includes(String(stats.status || '').toLowerCase())
+        && typeof stats.statusMessage === 'string' && stats.statusMessage.trim()) {
+      return `${source} · ${stats.statusMessage.trim()}`;
+    }
+    const ago = stats.lastUpdate ? this._timeAgo(stats.lastUpdate) : 'never';
+    if (stats.loading) {
+      const loadingLabel = typeof stats.loadingLabel === 'string' && stats.loadingLabel.trim()
+        ? stats.loadingLabel.trim()
+        : 'loading...';
+      return `${source} · ${loadingLabel}`;
+    }
+    if (feedState === 'fallback') {
+      const detail = typeof stats.loadingLabel === 'string' && stats.loadingLabel.trim()
+        ? stats.loadingLabel.trim()
+        : (stats.coverage || ago);
+      return `${stateLabel} · ${source} · ${detail}`;
+    }
+    if (feedState === 'stale') {
+      const retry = typeof stats.retryInSec === 'number' && stats.retryInSec > 0
+        ? ` · retrying in ${stats.retryInSec}s`
+        : '';
+      return `${stateLabel} · ${source} · ${ago}${retry}`;
+    }
+    if (typeof stats.loadingLabel === 'string' && stats.loadingLabel.trim()) {
+      return `${source} · ${stats.loadingLabel.trim()}`;
+    }
+    return `${source} · ${ago}`;
+  }
+
+  _syncToggleButton(button, layer) {
+    const feedState = layer.enabled ? layerFeedState(layer.stats) : 'off';
+    const transitioning = layer.lifecycleState === 'enabling' || layer.lifecycleState === 'disabling';
+    const uncertain = Boolean(layer.lifecycleUncertain);
+    button.classList.toggle('active', layer.enabled);
+    button.classList.toggle('transitioning', transitioning);
+    button.classList.toggle('enabling', layer.lifecycleState === 'enabling');
+    button.classList.toggle('disabling', layer.lifecycleState === 'disabling');
+    button.classList.toggle('lifecycle-uncertain', uncertain);
+    for (const state of Object.keys(FEED_STATE_LABELS)) {
+      button.classList.toggle(`feed-${state}`, layer.enabled && !uncertain && feedState === state);
+    }
+    button.dataset.feedState = transitioning
+      ? layer.lifecycleState
+      : (uncertain ? 'uncertain' : feedState);
+    // A busy toggle remains the keyboard focus owner. `aria-disabled` plus the
+    // click guard above prevents repeat activation without the focus loss caused
+    // by native `disabled`.
+    button.disabled = false;
+    button.setAttribute('aria-disabled', String(transitioning));
+    button.setAttribute('aria-busy', String(transitioning));
+    button.textContent = transitioning
+      ? layer.lifecycleState.toUpperCase()
+      : (uncertain ? 'UNCERTAIN' : (layer.enabled ? FEED_STATE_LABELS[feedState] : 'OFF'));
+    button.setAttribute('aria-label', `${layer.name}: ${button.textContent}`);
+  }
+
+  _formatCount(n) {
+    if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
+    return String(n);
+  }
+
+  _timeAgo(timestamp) {
+    const diff = Math.floor((Date.now() - timestamp) / 1000);
+    if (diff < 5) return 'just now';
+    if (diff < 60) return `${diff}s ago`;
+    if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+    return `${Math.floor(diff / 3600)}h ago`;
+  }
+}

src/ui/layers.js

@@ -0,0 +1,2 @@
+export { LayerPanel, layerFeedState } from './layerPanel.js';
+export { bindClearLayersControl } from './clearLayersControl.js';