@kgdiff/viewer 0.4.0 → 0.5.0

package/src/theme.ts

@@ -0,0 +1,167 @@
+/**
+ * The theme as CSS (RFC 0001 §6; decision 1: CSS is the theme's single source of truth).
+ *
+ * Colors and fonts are custom properties named `--kgdiff-*`. The built-in themes (dark / light
+ * × default / color-blind palette, `getTheme` in @kgdiff/scene, whose contrast is tested there)
+ * are token sets a root applies on `:host` (`tokenSheet`). The canvas is drawn with the tokens
+ * as computed on the root (`themeFromStyle`), so a token the host overrides with ordinary CSS
+ * changes the panels and the canvas alike. Motion and the interaction tints are written as
+ * tokens too, for the panels; the canvas keeps the theme's own (they stay in JavaScript).
+ */
+import { contrastRatio, type Theme } from '@kgdiff/scene';
+import { FAMILIES, sheetFor } from './styles.js';
+
+/** Token (after `--kgdiff-`) → where its value lives in a `Theme`. */
+const TOKENS: readonly (readonly [token: string, path: string])[] = [
+  ['bg', 'canvas.background'],
+  ['grid', 'canvas.grid'],
+  ['panel', 'surface.panel'],
+  ['raised', 'surface.raised'],
+  ['overlay', 'surface.overlay'],
+  ['border', 'surface.border'],
+  ['border-strong', 'surface.borderStrong'],
+  ['control-border', 'surface.controlBorder'],
+  ['shadow', 'surface.shadow'],
+  ['text', 'text.primary'],
+  ['text-2', 'text.secondary'],
+  ['text-3', 'text.muted'],
+  ['accent', 'accent.base'],
+  ['accent-strong', 'accent.strong'],
+  ['accent-soft', 'accent.soft'],
+  ['accent-text', 'accent.text'],
+  ['neutral', 'neutral.node'],
+  ['neutral-stroke', 'neutral.nodeStroke'],
+  ['neutral-edge', 'neutral.edge'],
+  ['neutral-label', 'neutral.label'],
+  ['font', 'font.family'],
+  ['mono', 'font.mono'],
+  ...FAMILIES.flatMap((f) => [
+    [f, `family.${f}.base`] as const,
+    [`${f}-strong`, `family.${f}.strong`] as const,
+    [`${f}-soft`, `family.${f}.soft`] as const,
+    [`${f}-text`, `family.${f}.text`] as const,
+  ]),
+];
+
+/** Tokens that are not colors (taken as they are). */
+const VERBATIM: ReadonlySet<string> = new Set(['shadow', 'font', 'mono']);
+
+type Tree = { readonly [key: string]: unknown };
+
+function get(theme: Theme, path: string): string {
+  let at: unknown = theme;
+  for (const key of path.split('.')) at = (at as Tree)[key];
+  return at as string;
+}
+
+/** A copy of `tree` with `value` at `keys` (copy on write: untouched branches are shared). */
+function put(tree: Tree, keys: readonly string[], value: string): Tree {
+  const [key = '', ...rest] = keys;
+  return { ...tree, [key]: rest.length > 0 ? put(tree[key] as Tree, rest, value) : value };
+}
+
+/** CSS custom properties for `theme` (a `:host` rule body). */
+export function themeVariables(theme: Theme): string {
+  const dark = theme.name === 'dark';
+  const vars: [string, string][] = [['color-scheme', dark ? 'dark' : 'light']];
+  for (const [token, path] of TOKENS) vars.push([token, get(theme, path)]);
+  vars.push(
+    ['fast', `${theme.motion.fast}ms`],
+    ['base', `${theme.motion.base}ms`],
+    ['slow', `${theme.motion.slow}ms`],
+    ['ease', `cubic-bezier(${theme.motion.easing.join(', ')})`],
+    // Derived interaction tints (not color-coded: hover / press / inputs / scrims).
+    ['hover', dark ? 'rgba(255,255,255,0.045)' : 'rgba(15,23,42,0.04)'],
+    ['press', dark ? 'rgba(255,255,255,0.08)' : 'rgba(15,23,42,0.07)'],
+    ['input', dark ? theme.surface.raised : '#F3F5F8'],
+    ['selected', dark ? theme.surface.raised : '#F5F7FB'],
+    ['scrim', dark ? 'rgba(5,7,11,0.56)' : 'rgba(15,23,42,0.18)'],
+    ['skeleton', dark ? 'rgba(255,255,255,0.05)' : 'rgba(15,23,42,0.05)'],
+    ['skeleton-hi', dark ? 'rgba(255,255,255,0.09)' : 'rgba(15,23,42,0.09)'],
+    ['track', dark ? 'rgba(255,255,255,0.08)' : 'rgba(15,23,42,0.08)'],
+    ['kbd', dark ? 'rgba(255,255,255,0.06)' : 'rgba(15,23,42,0.05)'],
+  );
+  return vars.map(([k, v]) => `${k === 'color-scheme' ? k : `--kgdiff-${k}`}: ${v};`).join(' ');
+}
+
+const sheets = new WeakMap<Document, Map<Theme, CSSStyleSheet>>();
+
+/** The built-in `theme` as a token set on `:host`, parsed once per document. */
+export function tokenSheet(theme: Theme, doc: Document): CSSStyleSheet {
+  let byTheme = sheets.get(doc);
+  if (!byTheme) {
+    byTheme = new Map();
+    sheets.set(doc, byTheme);
+  }
+  let sheet = byTheme.get(theme);
+  if (!sheet) {
+    sheet = sheetFor(doc, `:host { ${themeVariables(theme)} }`);
+    byTheme.set(theme, sheet);
+  }
+  return sheet;
+}
+
+let probe: CanvasRenderingContext2D | null | undefined;
+const warned = new Set<string>();
+
+/**
+ * `value` as a color the scene can parse (`#rrggbb`, `rgba()`), or null. A canvas normalizes
+ * whatever sRGB color syntax the browser knows (names, `hsl()`, `color-mix()`, …).
+ */
+function canvasColor(value: string): string | null {
+  probe ??=
+    typeof document === 'undefined' ? null : document.createElement('canvas').getContext('2d');
+  let color = value;
+  if (probe) {
+    probe.fillStyle = '#000';
+    probe.fillStyle = value;
+    color = String(probe.fillStyle);
+    probe.fillStyle = '#fff';
+    probe.fillStyle = value;
+    if (String(probe.fillStyle) !== color) return null;
+  }
+  try {
+    contrastRatio(color, color);
+    return color;
+  } catch {
+    return null;
+  }
+}
+
+/** Themes built from computed tokens, by base theme and overrides (stable identities). */
+const built = new Map<string, Theme>();
+
+/**
+ * The theme the canvas draws with: `base` (the built-in theme of the root's token set) with
+ * every token the root's computed `style` sets to another value. Unchanged tokens keep the
+ * base's identity, so caches keyed by the theme survive; a value the canvas cannot draw is
+ * ignored with a warning.
+ */
+export function themeFromStyle(
+  base: Theme,
+  style: { getPropertyValue(name: string): string },
+): Theme {
+  const overrides: [string, string][] = [];
+  for (const [token, path] of TOKENS) {
+    const raw = style.getPropertyValue(`--kgdiff-${token}`).trim();
+    if (!raw || raw === get(base, path)) continue;
+    const value = VERBATIM.has(token) ? raw : canvasColor(raw);
+    if (value === null) {
+      if (!warned.has(raw)) {
+        warned.add(raw);
+        console.warn(`[kgdiff] --kgdiff-${token}: ${raw} is not a color the canvas draws.`);
+      }
+    } else if (value !== get(base, path)) overrides.push([path, value]);
+  }
+  if (overrides.length === 0) return base;
+  const key = `${base.name}/${base.palette}|${overrides.join('|')}`;
+  let theme = built.get(key);
+  if (!theme) {
+    let tree: Tree = base as unknown as Tree;
+    for (const [path, value] of overrides) tree = put(tree, path.split('.'), value);
+    theme = tree as unknown as Theme;
+    if (built.size >= 16) built.clear();
+    built.set(key, theme);
+  }
+  return theme;
+}

package/src/ui/change-list.ts

@@ -0,0 +1,401 @@
+/**
+ * The change list (RFC 0001 §3, `<kgdiff-change-list>` from phase 2): the "Changes" title with
+ * the count and review progress, and the phase-grouped list of changes (virtualized, sticky
+ * group headers, a `listbox` with `aria-activedescendant`). While a search is active (the
+ * session's query is not blank) it steps aside. Registers itself as the root's `list` focus
+ * target.
+ */
+import type { SceneHunk } from '@kgdiff/scene';
+import { attr, h, icon, replace, setText } from '../dom.js';
+import type { ListItem } from '../list-model.js';
+import { frameOrTimeout } from '../schedule.js';
+import type { Topic } from '../session.js';
+import { sceneHunkGlyph, type UiContext } from './context.js';
+
+/** Row slot and group-header heights (px); rows are 52 px tall inside a 56 px slot. */
+export const ROW_SLOT = 56;
+export const HEADER_SLOT = 32;
+const OVERSCAN = 320;
+
+function itemHeight(item: ListItem): number {
+  return item.kind === 'header' ? HEADER_SLOT : ROW_SLOT;
+}
+
+export class ChangeList {
+  /** Title, count and review progress. */
+  readonly head: HTMLElement;
+  readonly list: HTMLElement;
+  readonly sticky: HTMLElement;
+  /** Visually hidden group names the options are described by. */
+  readonly phases: HTMLElement = h('div', { class: 'sr-only' });
+  readonly #title: HTMLElement;
+  readonly #count: HTMLElement;
+  readonly #progress: HTMLElement;
+  readonly #progressText: HTMLElement;
+  readonly #progressBar: HTMLElement;
+  readonly #listInner: HTMLElement;
+  #offsets: number[] = [];
+  #rendered = new Map<number, HTMLElement>();
+  #scrollQueued = false;
+
+  readonly #ctx: UiContext;
+
+  constructor(ctx: UiContext) {
+    this.#ctx = ctx;
+    const c = ctx.controller;
+    this.#title = h('h2', { id: 'kg-changes-title' });
+    this.#count = h('span', { class: 'count-badge' });
+    this.#progressText = h('span');
+    this.#progressBar = h('div');
+    this.#progress = h(
+      'div',
+      { class: 'progress' },
+      this.#progressText,
+      h('span', { class: 'bar', 'aria-hidden': 'true' }, this.#progressBar),
+    );
+    this.head = h('div', { class: 'sb-title' }, this.#title, this.#count, this.#progress);
+    this.#listInner = h('div', { class: 'list-inner', role: 'presentation' });
+    this.list = h(
+      'div',
+      {
+        class: 'list scroll',
+        role: 'listbox',
+        tabindex: '0',
+        'aria-labelledby': 'kg-changes-title',
+        'aria-keyshortcuts': 'J K X Enter Home End',
+      },
+      this.#listInner,
+    );
+    this.list.addEventListener('scroll', () => this.#queueWindow(), { passive: true });
+    this.list.addEventListener('click', (e) => this.#onListClick(e));
+    this.list.addEventListener('dblclick', (e) => {
+      const row = (e.target as Element).closest('.row');
+      if (row) c.flyToSelection();
+    });
+    this.sticky = h('div', { class: 'sticky', 'aria-hidden': 'true', hidden: true });
+    ctx.target('list', () => this.list.focus({ preventScroll: true }));
+  }
+
+  update(topics: ReadonlySet<Topic>): void {
+    const tr = this.#ctx.tr();
+    const all = topics.has('status') || topics.has('data') || topics.has('locale');
+    if (all) {
+      setText(this.#title, tr.t('sidebar.changes'));
+      const scene = this.#ctx.controller.scene;
+      setText(this.#count, tr.num(scene?.hunks.length ?? 0));
+      this.#count.hidden = !scene;
+    }
+    if (all || topics.has('filters')) this.#layoutList();
+    if (all || topics.has('review')) {
+      this.#renderProgress();
+      this.#refreshRows();
+    }
+    if (topics.has('selection')) {
+      this.#refreshRows();
+      this.#revealSelected();
+    }
+    if (all || topics.has('search')) this.#stepAside();
+  }
+
+  /**
+   * The search's results take the list's place while the query is not blank. Coming back, the
+   * list measures itself on the next frame, once every region has updated (the results it
+   * shared its space with are hidden by then, whatever order the regions update in).
+   */
+  #stepAside(): void {
+    const searching = this.#ctx.controller.query.trim() !== '';
+    if (this.list.hidden === searching) return;
+    this.list.hidden = searching;
+    if (searching) this.sticky.hidden = true;
+    else this.#queueWindow();
+  }
+
+  #renderProgress(): void {
+    const tr = this.#ctx.tr();
+    const state = this.#ctx.controller.reviewState();
+    const done = state.reviewed.length;
+    const total = state.total;
+    this.#progress.hidden = total === 0;
+    const complete = total > 0 && done === total;
+    attr(this.#progress, 'data-complete', String(complete));
+    setText(
+      this.#progressText,
+      complete ? tr.t('review.complete') : tr.t('review.progress', { done, total }),
+    );
+    this.#progressBar.style.transform = `scaleX(${total > 0 ? done / total : 0})`;
+  }
+
+  // ─── Virtual list ────────────────────────────────────────────────────────
+
+  #layoutList(): void {
+    const c = this.#ctx.controller;
+    const tr = this.#ctx.tr();
+    replace(
+      this.phases,
+      c.list.items.map((it) =>
+        it.kind === 'header'
+          ? h('span', {
+              id: `kg-phase-${it.phase}`,
+              text: `${tr.t(`phase.${it.phase}`)} (${tr.num(it.count)})`,
+            })
+          : null,
+      ),
+    );
+    for (const el of this.#rendered.values()) el.remove();
+    this.#rendered.clear();
+    const items = c.list.items;
+    this.#offsets = new Array(items.length);
+    let y = 0;
+    for (let i = 0; i < items.length; i++) {
+      this.#offsets[i] = y;
+      y += itemHeight(items[i] as ListItem);
+    }
+    this.#listInner.style.height = `${y + 8}px`;
+    this.#renderEmpty();
+    this.renderWindow();
+  }
+
+  #renderEmpty(): void {
+    const c = this.#ctx.controller;
+    const tr = this.#ctx.tr();
+    const existing = this.#listInner.querySelector('.list-empty, .skeleton');
+    existing?.remove();
+    if (c.status === 'loading' || c.status === 'idle') {
+      const sk = h('div', { class: 'skeleton', 'aria-hidden': 'true' });
+      if (c.status === 'loading') {
+        for (let i = 0; i < 6; i++) {
+          sk.appendChild(
+            h(
+              'div',
+              { class: 'skeleton-row shimmer' },
+              h('span', { class: 'g' }),
+              h('span', { class: 'b' }),
+            ),
+          );
+        }
+      }
+      this.#listInner.appendChild(sk);
+      return;
+    }
+    if (c.status !== 'ready' || c.list.items.length > 0) return;
+    const filtered = c.families.size > 0 && c.hunkCount > 0;
+    this.#listInner.appendChild(
+      h(
+        'div',
+        { class: 'list-empty' },
+        icon(filtered ? 'search' : 'check-circle'),
+        h('span', { text: tr.t(filtered ? 'sidebar.filteredEmpty' : 'sidebar.noChanges') }),
+        filtered
+          ? h('button', {
+              type: 'button',
+              class: 'btn',
+              text: tr.t('sidebar.clearFilters'),
+              onclick: () => c.setFamilies([]),
+            })
+          : null,
+      ),
+    );
+  }
+
+  #queueWindow(): void {
+    if (this.#scrollQueued) return;
+    this.#scrollQueued = true;
+    frameOrTimeout(() => {
+      this.#scrollQueued = false;
+      this.renderWindow();
+    });
+  }
+
+  /** First item index whose bottom is below `y` (binary search over offsets). */
+  #indexAt(y: number): number {
+    let lo = 0;
+    let hi = this.#offsets.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if ((this.#offsets[mid] as number) + ROW_SLOT <= y) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+
+  renderWindow(): void {
+    const items = this.#ctx.controller.list.items;
+    const top = this.list.scrollTop;
+    const height = this.list.clientHeight || 640;
+    const from = this.#indexAt(Math.max(0, top - OVERSCAN));
+    const limit = top + height + OVERSCAN;
+    const needed = new Set<number>();
+    for (let i = from; i < items.length && (this.#offsets[i] as number) < limit; i++) needed.add(i);
+    for (const [i, el] of this.#rendered) {
+      if (!needed.has(i)) {
+        el.remove();
+        this.#rendered.delete(i);
+      }
+    }
+    for (const i of needed) {
+      if (this.#rendered.has(i)) continue;
+      const el = this.#renderItem(items[i] as ListItem, this.#offsets[i] as number);
+      this.#rendered.set(i, el);
+      this.#listInner.appendChild(el);
+    }
+    this.#renderSticky(top);
+  }
+
+  #renderItem(item: ListItem, y: number): HTMLElement {
+    const tr = this.#ctx.tr();
+    const c = this.#ctx.controller;
+    if (item.kind === 'header') {
+      return h(
+        'div',
+        { class: 'group', role: 'presentation', style: `top: ${y}px` },
+        h('span', { text: tr.t(`phase.${item.phase}`) }),
+        h('span', { class: 'n', text: tr.num(item.count) }),
+      );
+    }
+    const hunk = c.scene?.hunks[item.hunk] as SceneHunk;
+    const reviewed = c.isReviewed(hunk.id);
+    // Pointer shortcut only: options hold no interactive children. Keyboard users press `x` or
+    // use the detail panel's "Reviewed" button.
+    const rv = h(
+      'span',
+      {
+        class: 'rv',
+        'aria-hidden': 'true',
+        'data-pressed': String(reviewed),
+        title: tr.t(reviewed ? 'review.unmark' : 'review.mark'),
+        'data-hunk': hunk.id,
+      },
+      h('span', { class: 'ring' }, icon('check')),
+    );
+    const rank = c.list.rank.get(item.hunk) ?? 0;
+    const row = h(
+      'div',
+      {
+        class: 'row',
+        role: 'option',
+        id: `kg-opt-${item.hunk}`,
+        'data-index': String(item.hunk),
+        'data-family': hunk.family,
+        'data-reviewed': String(reviewed),
+        'aria-selected': String(c.selectedHunk === item.hunk),
+        'aria-setsize': String(c.list.order.length),
+        'aria-posinset': String(rank + 1),
+        'aria-describedby': `kg-phase-${hunk.phase}`,
+        style: `top: ${y + 2}px`,
+      },
+      h('span', { class: 'glyph-box', 'aria-hidden': 'true', text: sceneHunkGlyph(hunk) }),
+      h(
+        'span',
+        { class: 'txt' },
+        h('span', { class: 'title', title: hunk.title, text: hunk.title }),
+        h('span', { class: 'sub', text: hunk.subtitle }),
+      ),
+      rv,
+    );
+    this.#labelRow(row, hunk, reviewed);
+    return row;
+  }
+
+  #labelRow(row: HTMLElement, hunk: SceneHunk, reviewed: boolean): void {
+    const tr = this.#ctx.tr();
+    const parts = [hunk.title];
+    if (hunk.subtitle) parts.push(hunk.subtitle);
+    if (reviewed) parts.push(tr.t('review.toggle'));
+    attr(row, 'aria-label', parts.join('. '));
+  }
+
+  /** Update selection / reviewed state of the rendered rows in place. */
+  #refreshRows(): void {
+    const c = this.#ctx.controller;
+    const tr = this.#ctx.tr();
+    for (const el of this.#rendered.values()) {
+      if (!el.classList.contains('row')) continue;
+      const index = Number(el.dataset.index);
+      const hunk = c.scene?.hunks[index];
+      if (!hunk) continue;
+      const reviewed = c.isReviewed(hunk.id);
+      attr(el, 'aria-selected', String(index === c.selectedHunk));
+      attr(el, 'data-reviewed', String(reviewed));
+      const rv = el.querySelector('.rv') as HTMLElement;
+      attr(rv, 'data-pressed', String(reviewed));
+      attr(rv, 'title', tr.t(reviewed ? 'review.unmark' : 'review.mark'));
+      this.#labelRow(el, hunk, reviewed);
+    }
+    const sel = c.selectedHunk;
+    attr(
+      this.list,
+      'aria-activedescendant',
+      sel >= 0 && c.list.rank.has(sel) ? `kg-opt-${sel}` : null,
+    );
+  }
+
+  #revealSelected(): void {
+    const c = this.#ctx.controller;
+    const item = c.list.itemOf.get(c.selectedHunk);
+    if (item === undefined) return;
+    const y = this.#offsets[item] as number;
+    const top = this.list.scrollTop;
+    // Not laid out yet (hidden sheet): position it for when it shows.
+    const height = this.list.clientHeight || 640;
+    // The first row of a group scrolls its group header into view too.
+    const above =
+      c.list.items[item - 1]?.kind === 'header'
+        ? (this.#offsets[item - 1] as number)
+        : y - HEADER_SLOT;
+    if (y < top + HEADER_SLOT) this.list.scrollTop = Math.max(0, above);
+    else if (y + ROW_SLOT > top + height) this.list.scrollTop = y + ROW_SLOT - height + 8;
+    this.renderWindow();
+    this.#refreshRows();
+  }
+
+  #renderSticky(top: number): void {
+    const items = this.#ctx.controller.list.items;
+    let current = -1;
+    let next = -1;
+    for (let i = 0; i < items.length; i++) {
+      if (items[i]?.kind !== 'header') continue;
+      if ((this.#offsets[i] as number) <= top) current = i;
+      else {
+        next = i;
+        break;
+      }
+    }
+    if (current < 0 || top <= 0) {
+      this.sticky.hidden = true;
+      return;
+    }
+    const item = items[current] as Extract<ListItem, { kind: 'header' }>;
+    const tr = this.#ctx.tr();
+    this.sticky.hidden = false;
+    const label = `${tr.t(`phase.${item.phase}`)}|${item.count}`;
+    if (this.sticky.dataset.key !== label) {
+      this.sticky.dataset.key = label;
+      replace(
+        this.sticky,
+        h(
+          'div',
+          { class: 'group' },
+          h('span', { text: tr.t(`phase.${item.phase}`) }),
+          h('span', { class: 'n', text: tr.num(item.count) }),
+        ),
+      );
+    }
+    const push = next >= 0 ? Math.min(0, (this.#offsets[next] as number) - top - HEADER_SLOT) : 0;
+    this.sticky.style.transform = `translateY(${push}px)`;
+  }
+
+  #onListClick(e: MouseEvent): void {
+    const c = this.#ctx.controller;
+    const target = e.target as Element;
+    const rv = target.closest('.rv') as HTMLElement | null;
+    if (rv?.dataset.hunk) {
+      e.stopPropagation();
+      c.toggleReviewed(rv.dataset.hunk);
+      return;
+    }
+    const row = target.closest('.row') as HTMLElement | null;
+    if (!row) return;
+    const index = Number(row.dataset.index);
+    if (Number.isInteger(index)) c.selectHunk(index);
+  }
+}

package/src/ui/context.ts

@@ -1,6 +1,6 @@
 /**
- * What UI components share: the controller, the current translator and element-level actions
- * (attribute-reflected preferences, sidebar, popovers).
+ * What UI components share: the session (`controller`), the layout's actions, the translator
+ * and the root's focus targets.
  */
 import type { AttrValue, HunkKind, Locale } from '@kgdiff/core';
 import type { ChangeFamily, PaletteName, SceneHunk } from '@kgdiff/scene';
@@ -8,8 +8,11 @@ import type { ViewerController } from '../controller.js';
 import type { Translator } from '../i18n.js';
 import type { ThemePreference, ViewerMode } from '../index.js';
 
-export interface UiContext {
-  readonly controller: ViewerController;
+/**
+ * What the layout does for the regions (preferences it reflects as attributes, the panels and
+ * popovers it owns).
+ */
+export interface UiActions {
   readonly tr: () => Translator;
   setMode(mode: ViewerMode): void;
   /** Toggle the `changes` scope (explains itself when it is locked). */
@@ -21,9 +24,22 @@ export interface UiContext {
   sidebarOpen(): boolean;
   toggleMenu(open?: boolean): void;
   openHelp(): void;
+  /** Show and focus the search (`/`). */
   focusSearch(): void;
-  /** Root of the shadow tree (for focus management). */
+}
+
+/** Elements of a region that others move focus to, through the root. */
+export type FocusTarget = 'search' | 'list';
+
+/** What a region gets from the root it is bound to: the session, the actions, focus moves. */
+export interface UiContext extends UiActions {
+  readonly controller: ViewerController;
+  /** Root of the region's shadow tree (for focus management). */
   readonly root: ShadowRoot;
+  /** Register `focus` as the root's `name` target; returns the function that unregisters it. */
+  target(name: FocusTarget, focus: () => void): () => void;
+  /** Focus the root's `name` target registered last; false when there is none. */
+  focus(name: FocusTarget): boolean;
 }
 
 /** One-character glyph of a hunk (docs/interaction.md §Change list): `+ − ~ ⇄ ⊕ ⑂`. */

package/src/ui/filters.ts

@@ -0,0 +1,79 @@
+/**
+ * The family filters (RFC 0001 §3, `<kgdiff-filters>` from phase 2): one chip per family the
+ * diff has, with its count and the legend's swatch, toggling the session's family filter, and
+ * "show all" while a filter is on.
+ */
+import { attr, h, setText } from '../dom.js';
+import { familyCounts } from '../list-model.js';
+import type { Topic } from '../session.js';
+import { FAMILIES } from '../styles.js';
+import type { UiContext } from './context.js';
+import { swatch } from './swatch.js';
+
+export class Filters {
+  readonly el: HTMLElement;
+  readonly #chips = new Map<string, HTMLButtonElement>();
+  readonly #showAll: HTMLButtonElement;
+
+  readonly #ctx: UiContext;
+
+  constructor(ctx: UiContext) {
+    this.#ctx = ctx;
+    const c = ctx.controller;
+    this.el = h('div', { class: 'filters', role: 'group' });
+    for (const f of FAMILIES) {
+      const chip = h(
+        'button',
+        {
+          type: 'button',
+          class: 'fchip',
+          'data-family': f,
+          'aria-pressed': 'false',
+          onclick: () => c.toggleFamily(f),
+        },
+        swatch(f),
+        h('span', { class: 'lbl' }),
+        h('span', { class: 'n' }),
+      );
+      this.#chips.set(f, chip);
+      this.el.appendChild(chip);
+    }
+    this.#showAll = h('button', {
+      type: 'button',
+      class: 'link-btn',
+      hidden: true,
+      onclick: () => c.setFamilies([]),
+    });
+    this.el.appendChild(this.#showAll);
+  }
+
+  update(topics: ReadonlySet<Topic>): void {
+    const all = topics.has('status') || topics.has('data') || topics.has('locale');
+    if (all) this.#renderChips();
+    if (all || topics.has('filters')) this.#renderState();
+  }
+
+  #renderChips(): void {
+    const tr = this.#ctx.tr();
+    const scene = this.#ctx.controller.scene;
+    const counts = scene ? familyCounts(scene) : null;
+    attr(this.el, 'aria-label', tr.t('sidebar.filters'));
+    setText(this.#showAll, tr.t('sidebar.clearFilters'));
+    this.el.hidden = !scene || scene.hunks.length === 0;
+    for (const [f, chip] of this.#chips) {
+      const n = counts ? counts[f as keyof typeof counts] : 0;
+      setText(chip.querySelector('.lbl') as Element, tr.t(`family.${f as keyof typeof counts}`));
+      setText(chip.querySelector('.n') as Element, tr.num(n));
+      chip.hidden = n === 0;
+      attr(chip, 'title', tr.t(`familyHint.${f as keyof typeof counts}`));
+    }
+  }
+
+  #renderState(): void {
+    const fams = this.#ctx.controller.families;
+    for (const [f, chip] of this.#chips) {
+      attr(chip, 'aria-pressed', String(fams.has(f as never)));
+    }
+    this.#showAll.hidden = fams.size === 0;
+  }
+}