@kgdiff/viewer 0.5.0 → 0.6.0

package/src/keyboard.ts

@@ -33,52 +33,108 @@ export interface KeyLike {
   readonly altKey?: boolean;
 }
 
-const MODE_KEYS: Readonly<Record<string, ViewerMode>> = {
-  '1': 'overlay',
-  '2': 'swipe',
-  '3': 'replay',
-};
-
 /** Divider steps for swipe, as a fraction of the width. */
 export const DIVIDER_STEP = 0.02;
 export const DIVIDER_STEP_LARGE = 0.1;
 
 /**
- * Map a key press to an action in `mode` and `scope`, or null when the key means nothing here.
- * Chords with Ctrl / Meta / Alt are never handled (they belong to the browser and the host page).
+ * The shortcuts a key can be bound to (`keymap`). `left` / `right` step the replay, or move the
+ * swipe divider (further with Shift); `play-pause` acts in replay, `expand` with the `changes`
+ * scope.
+ *
+ * @experimental New in 0.6: the list may grow as the canvas chrome becomes elements.
  */
-export function keyAction(
+export type ShortcutName =
+  | 'overlay'
+  | 'swipe'
+  | 'replay'
+  | 'scope'
+  | 'expand'
+  | 'next'
+  | 'prev'
+  | 'first'
+  | 'last'
+  | 'fly'
+  | 'escape'
+  | 'play-pause'
+  | 'left'
+  | 'right'
+  | 'fit'
+  | 'zoom-in'
+  | 'zoom-out'
+  | 'search'
+  | 'review'
+  | 'sidebar'
+  | 'theme'
+  | 'help';
+
+/**
+ * Keys (as `KeyboardEvent.key`) bound to a shortcut, or to `null` to leave the key unbound. A
+ * letter stands for both its cases (`x` also binds Shift+x, `X`) unless the other case is named
+ * too.
+ *
+ * @experimental New in 0.6, with `ShortcutName`.
+ */
+export type Keymap = Readonly<Record<string, ShortcutName | null>>;
+
+/** The default keyboard map (docs/interaction.md §Keyboard map); each letter once. */
+export const DEFAULT_KEYMAP: Keymap = {
+  '1': 'overlay',
+  '2': 'swipe',
+  '3': 'replay',
+  '4': 'scope',
+  j: 'next',
+  ArrowDown: 'next',
+  k: 'prev',
+  ArrowUp: 'prev',
+  Home: 'first',
+  End: 'last',
+  Enter: 'fly',
+  Escape: 'escape',
+  ' ': 'play-pause',
+  Spacebar: 'play-pause',
+  ArrowLeft: 'left',
+  ArrowRight: 'right',
+  f: 'fit',
+  '+': 'zoom-in',
+  '=': 'zoom-in',
+  '-': 'zoom-out',
+  _: 'zoom-out',
+  '−': 'zoom-out',
+  '/': 'search',
+  x: 'review',
+  '\\': 'sidebar',
+  t: 'theme',
+  e: 'expand',
+  '?': 'help',
+};
+
+/** Every shortcut (each is bound to a key by default). */
+export const SHORTCUT_NAMES: ReadonlySet<string> = new Set(
+  Object.values(DEFAULT_KEYMAP).filter((name) => name !== null),
+);
+
+/** What `name` does in `mode` and `scope`, or null when it does nothing there. */
+function resolve(
+  name: ShortcutName,
   e: KeyLike,
   mode: ViewerMode,
-  scope: ViewerScope = 'all',
+  scope: ViewerScope,
 ): KeyAction | null {
-  if (e.ctrlKey || e.metaKey || e.altKey) return null;
-  const key = e.key;
-  const mapped = MODE_KEYS[key];
-  if (mapped !== undefined) return { type: 'mode', mode: mapped };
-  switch (key) {
-    case '4':
+  switch (name) {
+    case 'overlay':
+    case 'swipe':
+    case 'replay':
+      return { type: 'mode', mode: name };
+    case 'scope':
       return { type: 'scope' };
-    case 'j':
-    case 'ArrowDown':
-      return { type: 'next' };
-    case 'k':
-    case 'ArrowUp':
-      return { type: 'prev' };
-    case 'Home':
-      return { type: 'first' };
-    case 'End':
-      return { type: 'last' };
-    case 'Enter':
-      return { type: 'fly' };
-    case 'Escape':
-      return { type: 'escape' };
-    case ' ':
-    case 'Spacebar':
+    case 'expand':
+      return scope === 'changes' ? { type: 'expand' } : null;
+    case 'play-pause':
       return mode === 'replay' ? { type: 'play-pause' } : null;
-    case 'ArrowLeft':
-    case 'ArrowRight': {
-      const direction = key === 'ArrowRight' ? 1 : -1;
+    case 'left':
+    case 'right': {
+      const direction = name === 'right' ? 1 : -1;
       if (mode === 'replay') return { type: 'step', direction };
       if (mode === 'swipe') {
         return {
@@ -88,34 +144,105 @@ export function keyAction(
       }
       return null;
     }
-    case 'f':
-    case 'F':
-      return { type: 'fit' };
-    case '+':
-    case '=':
-      return { type: 'zoom', direction: 1 };
-    case '-':
-    case '_':
-    case '−':
-      return { type: 'zoom', direction: -1 };
-    case '/':
-      return { type: 'search' };
-    case 'x':
-    case 'X':
-      return { type: 'review' };
-    case '\\':
-      return { type: 'sidebar' };
-    case 't':
-    case 'T':
-      return { type: 'theme' };
-    case 'e':
-    case 'E':
-      return scope === 'changes' ? { type: 'expand' } : null;
-    case '?':
-      return { type: 'help' };
+    case 'zoom-in':
+    case 'zoom-out':
+      return { type: 'zoom', direction: name === 'zoom-in' ? 1 : -1 };
     default:
-      return null;
+      return { type: name };
+  }
+}
+
+/**
+ * What `map` binds `key` to: the key itself, else the other case of a letter; undefined when
+ * `map` names neither.
+ */
+function lookup(map: Keymap, key: string): ShortcutName | null | undefined {
+  if (Object.hasOwn(map, key)) return map[key];
+  const lower = key.toLowerCase();
+  const other = key === lower ? key.toUpperCase() : lower;
+  return key.length === 1 && other !== key && Object.hasOwn(map, other) ? map[other] : undefined;
+}
+
+/**
+ * Map a key press to an action in `mode` and `scope`, or null when the key means nothing here.
+ * `keymap` overrides single keys of the default map (null unbinds one); a letter in either map
+ * stands for both its cases unless the other case is named too. Chords with Ctrl / Meta / Alt
+ * are never handled (they belong to the browser and the host page).
+ */
+export function keyAction(
+  e: KeyLike,
+  mode: ViewerMode,
+  scope: ViewerScope = 'all',
+  keymap: Keymap | null = null,
+): KeyAction | null {
+  if (e.ctrlKey || e.metaKey || e.altKey) return null;
+  const custom = keymap === null ? undefined : lookup(keymap, e.key);
+  const name = custom === undefined ? lookup(DEFAULT_KEYMAP, e.key) : custom;
+  return name ? resolve(name, e, mode, scope) : null;
+}
+
+/**
+ * Keys the default map binds for another key's sake: listed only when they do something else
+ * (the `+` key unshifted, `-` with Shift, the minus sign, the legacy name of the space bar).
+ */
+const ALIASES: Readonly<Record<string, string>> = { '=': '+', _: '-', '−': '-', Spacebar: ' ' };
+
+/**
+ * The keys bound to each shortcut with `keymap` over the default map, in the default map's
+ * order then `keymap`'s (what the shortcuts dialog lists). A letter is listed once for both its
+ * cases; a shortcut no key is bound to is absent.
+ */
+export function shortcutKeys(keymap: Keymap | null): ReadonlyMap<ShortcutName, readonly string[]> {
+  const candidates = new Set([...Object.keys(DEFAULT_KEYMAP), ...Object.keys(keymap ?? {})]);
+  const bound = (key: string): ShortcutName | null | undefined => {
+    const custom = keymap === null ? undefined : lookup(keymap, key);
+    return custom === undefined ? lookup(DEFAULT_KEYMAP, key) : custom;
+  };
+  const out = new Map<ShortcutName, string[]>();
+  for (const key of candidates) {
+    const name = bound(key);
+    if (!name) continue;
+    const lower = key.toLowerCase();
+    if (key.length === 1 && key !== lower && candidates.has(lower) && bound(lower) === name) {
+      continue;
+    }
+    const alias = ALIASES[key];
+    if (alias !== undefined && bound(alias) === name) continue;
+    const keys = out.get(name) ?? [];
+    keys.push(key);
+    out.set(name, keys);
   }
+  return out;
+}
+
+/** `Space` names the space bar in a `keymap` attribute. */
+const KEY_NAMES: Readonly<Record<string, string>> = { Space: ' ' };
+
+/**
+ * A keymap from an attribute (`"x:none r:review"`: `key:shortcut` pairs separated by spaces,
+ * `none` unbinds a key, `Space` is the space bar) or a property (an object of the same pairs).
+ * Pairs that name no shortcut are left out and returned in `invalid`.
+ */
+export function toKeymap(value: unknown): { keymap: Keymap | null; invalid: string[] } {
+  const invalid: string[] = [];
+  const out: Record<string, ShortcutName | null> = {};
+  const add = (key: string, name: unknown, raw: string): void => {
+    const k = KEY_NAMES[key] ?? key;
+    if (k === '' || !(name === null || name === 'none' || SHORTCUT_NAMES.has(name as string))) {
+      invalid.push(raw);
+    } else out[k] = name === null || name === 'none' ? null : (name as ShortcutName);
+  };
+  if (typeof value === 'string') {
+    for (const token of value.split(/\s+/)) {
+      if (token === '') continue;
+      const at = token.lastIndexOf(':');
+      if (at <= 0) invalid.push(token);
+      else add(token.slice(0, at), token.slice(at + 1), token);
+    }
+  } else if (typeof value === 'object' && value !== null) {
+    for (const [key, name] of Object.entries(value)) add(key, name, `${key}:${String(name)}`);
+  } else return { keymap: null, invalid };
+  return { keymap: Object.keys(out).length > 0 ? out : null, invalid };
 }
 
 /** Whether a key event comes from a place where the user types (shortcuts must not fire). */

package/src/layout-store.ts

@@ -0,0 +1,71 @@
+/**
+ * What the default layout remembers of the user's choices (RFC 0001 §4, decision 3): panel
+ * states, the sidebar's width, the split between the change list and the detail panel, theme,
+ * palette and language. One `localStorage` entry (`kgdiff:viewer`, or the viewer's
+ * `persist-key`), shared by the viewers of the origin that use the same key. Like review progress (`review-store.ts`), storage failures
+ * (private mode, quota, sandboxed iframes) never break the viewer: nothing is remembered then.
+ * Values are validated when read; an entry from another version is read as far as it is valid.
+ */
+import type { Locale } from '@kgdiff/core';
+import type { PaletteName } from '@kgdiff/scene';
+import type { ThemePreference, ViewerPanels } from './index.js';
+import { toPanels } from './panels.js';
+import { toLocale, toPalette, toTheme } from './prefs.js';
+import type { StorageLike } from './review-store.js';
+
+/** The default storage key (`persist-key`). */
+export const LAYOUT_KEY = 'kgdiff:viewer';
+
+export interface Remembered {
+  readonly panels: ViewerPanels;
+  readonly sidebarWidth?: number;
+  /** Null: the user reset the split (the detail panel takes its content's height). */
+  readonly detailShare?: number | null;
+  readonly theme?: ThemePreference;
+  readonly palette?: PaletteName;
+  readonly locale?: Locale;
+}
+
+const NOTHING: Remembered = { panels: {} };
+
+const finite = (x: unknown, min: number, max: number): number | undefined =>
+  typeof x === 'number' && Number.isFinite(x) && x >= min && x <= max ? x : undefined;
+
+export function readRemembered(storage: StorageLike | null, key = LAYOUT_KEY): Remembered {
+  if (!storage) return NOTHING;
+  try {
+    const raw = storage.getItem(key);
+    if (!raw) return NOTHING;
+    const v: unknown = JSON.parse(raw);
+    if (typeof v !== 'object' || v === null) return NOTHING;
+    const o = v as Record<string, unknown>;
+    const sidebarWidth = finite(o.sidebarWidth, 0, 10_000);
+    const detailShare = finite(o.detailShare, 0, 1);
+    const theme = toTheme(o.theme);
+    const palette = toPalette(o.palette);
+    const locale = toLocale(o.locale);
+    return {
+      panels: toPanels(o.panels).panels,
+      ...(sidebarWidth !== undefined ? { sidebarWidth } : {}),
+      ...(detailShare !== undefined ? { detailShare } : {}),
+      ...(theme ? { theme } : {}),
+      ...(palette ? { palette } : {}),
+      ...(locale ? { locale } : {}),
+    };
+  } catch {
+    return NOTHING;
+  }
+}
+
+export function writeRemembered(
+  storage: StorageLike | null,
+  value: Remembered,
+  key = LAYOUT_KEY,
+): void {
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify({ v: 1, ...value }));
+  } catch {
+    // Quota exceeded or storage blocked: the choice holds for this page only.
+  }
+}

package/src/panel-levels.ts

@@ -0,0 +1,53 @@
+/**
+ * Which level decides a panel's state in the default layout: the first of these that names the
+ * region. What the user changed in this page, the host (`panels`, then the presets `sidebar`,
+ * `header` and `chrome`), what the user changed before (remembered, `layout-store.ts`), the
+ * report's `view.panels`, the default.
+ */
+import type { PanelRegion, PanelStates, ViewerPanels } from './index.js';
+import { DEFAULT_PANELS, PANEL_REGIONS } from './panels.js';
+
+type MutablePanels = { -readonly [R in PanelRegion]?: PanelStates[R] };
+
+/** The regions of the sidebar (the bottom sheet below 760 px). */
+export const SIDEBAR_REGIONS: readonly PanelRegion[] = ['list', 'detail', 'search', 'filters'];
+
+/**
+ * What the existing switches stand for: `sidebar="closed"` (and `open`), `header="compact"`,
+ * `chrome="none"` (everything but the stage hidden; the legend stays, as one line).
+ */
+export function presetPanels(
+  sidebar: string | null,
+  header: string | null,
+  chrome: string | null,
+): ViewerPanels {
+  const out: MutablePanels = {};
+  if (chrome === 'none') {
+    for (const r of PANEL_REGIONS) if (r !== 'legend') out[r] = 'hidden';
+    return out;
+  }
+  if (sidebar === 'closed' || sidebar === 'open') {
+    for (const r of SIDEBAR_REGIONS) out[r] = sidebar === 'open' ? 'open' : 'collapsed';
+  }
+  if (header === 'compact') out.title = 'hidden';
+  return out;
+}
+
+/** Every region's state: the first of `levels` that names it, else the default. */
+export function resolvePanels(levels: readonly ViewerPanels[]): PanelStates {
+  const out = { ...DEFAULT_PANELS };
+  for (const r of PANEL_REGIONS) {
+    for (const level of levels) {
+      const state = level[r];
+      if (state !== undefined) {
+        out[r] = state;
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+export function samePanels(a: PanelStates, b: PanelStates): boolean {
+  return PANEL_REGIONS.every((r) => a[r] === b[r]);
+}

package/src/panels.ts

@@ -0,0 +1,81 @@
+/**
+ * `@kgdiff/viewer/panels`: the syntax of the default layout's panel states (RFC 0001 §4), every
+ * region `open`, `collapsed` or `hidden`. The `panels` attribute
+ * (`"detail:collapsed minimap:hidden"`), its object property, a report's `view.panels` and the
+ * CLI's `--panels` all go through `parsePanels` / `toPanels`. No DOM: the CLI imports it.
+ * Which level decides a region's state is `panel-levels.ts`.
+ */
+import type { PanelRegion, PanelState, PanelStates, ViewerPanels } from './index.js';
+
+export const PANEL_REGIONS: readonly PanelRegion[] = [
+  'list',
+  'detail',
+  'search',
+  'filters',
+  'dock',
+  'transport',
+  'legend',
+  'zoom',
+  'minimap',
+  'title',
+  'actions',
+];
+
+export const PANEL_STATES: readonly PanelState[] = ['open', 'collapsed', 'hidden'];
+
+/** Today's layout. The legend card starts folded to its head. */
+export const DEFAULT_PANELS: PanelStates = {
+  list: 'open',
+  detail: 'open',
+  search: 'open',
+  filters: 'open',
+  dock: 'open',
+  transport: 'open',
+  legend: 'collapsed',
+  zoom: 'open',
+  minimap: 'open',
+  title: 'open',
+  actions: 'open',
+};
+
+type MutablePanels = { -readonly [R in PanelRegion]?: PanelState };
+
+const isRegion = (r: unknown): r is PanelRegion => PANEL_REGIONS.includes(r as PanelRegion);
+const isState = (s: unknown): s is PanelState => PANEL_STATES.includes(s as PanelState);
+
+/**
+ * Read `"region:state …"` (pairs separated by spaces or commas). Pairs that name no region or
+ * no state are left out and returned in `invalid`; a region named twice takes the last state.
+ */
+export function parsePanels(text: string): { panels: ViewerPanels; invalid: string[] } {
+  const panels: MutablePanels = {};
+  const invalid: string[] = [];
+  for (const token of text.split(/[\s,]+/)) {
+    if (token === '') continue;
+    const [region, state, ...rest] = token.split(':');
+    if (rest.length === 0 && isRegion(region) && isState(state)) panels[region] = state;
+    else invalid.push(token);
+  }
+  return { panels, invalid };
+}
+
+/** Panels from an attribute, a property or a report (a string or an object), as `parsePanels`. */
+export function toPanels(value: unknown): { panels: ViewerPanels; invalid: string[] } {
+  if (typeof value === 'string') return parsePanels(value);
+  const panels: MutablePanels = {};
+  const invalid: string[] = [];
+  if (typeof value === 'object' && value !== null) {
+    for (const [region, state] of Object.entries(value)) {
+      if (isRegion(region) && isState(state)) panels[region] = state;
+      else invalid.push(`${region}:${String(state)}`);
+    }
+  } else if (value !== null && value !== undefined) invalid.push(String(value));
+  return { panels, invalid };
+}
+
+/** The attribute form of `panels`, in region order. */
+export function formatPanels(panels: ViewerPanels): string {
+  return PANEL_REGIONS.filter((r) => panels[r] !== undefined)
+    .map((r) => `${r}:${panels[r]}`)
+    .join(' ');
+}

package/src/prefs.ts

@@ -14,6 +14,7 @@ import type {
   ViewerMode,
   ViewerScope,
 } from './index.js';
+import { toPanels } from './panels.js';
 
 const MODES: readonly ViewerMode[] = ['overlay', 'swipe', 'replay'];
 const SCOPES: readonly ViewerScope[] = ['all', 'changes'];
@@ -69,8 +70,11 @@ export function toDelay(value: unknown): number | null {
 
 type View = NonNullable<ReportPayload['view']>;
 
-/** Keep only the valid fields of a report's `view` (warning about the rest). */
-export function sanitizeView(view: unknown): View | undefined {
+/**
+ * Keep only the valid fields of a report's `view`, warning about the rest (once per payload:
+ * `quiet` for a second read of the same view).
+ */
+export function sanitizeView(view: unknown, quiet = false): View | undefined {
   if (typeof view !== 'object' || view === null) return undefined;
   const v = view as Record<string, unknown>;
   const legacy = v.mode === LEGACY_CHANGES_MODE;
@@ -79,10 +83,13 @@ export function sanitizeView(view: unknown): View | undefined {
   const theme = toTheme(v.theme);
   const palette = toPalette(v.palette);
   const locale = toLocale(v.locale);
-  const dropped = (['mode', 'scope', 'theme', 'palette', 'locale'] as const).filter(
+  const read = v.panels === undefined ? null : toPanels(v.panels);
+  const panels = read && Object.keys(read.panels).length > 0 ? read.panels : null;
+  const dropped: string[] = (['mode', 'scope', 'theme', 'palette', 'locale'] as const).filter(
     (k) => v[k] !== undefined && { mode, scope, theme, palette, locale }[k] === null,
   );
-  if (dropped.length > 0 && typeof console !== 'undefined') {
+  if (read && read.invalid.length > 0) dropped.push(`panels (${read.invalid.join(' ')})`);
+  if (dropped.length > 0 && !quiet && typeof console !== 'undefined') {
     console.warn(`[kgdiff] ignoring invalid report view preferences: ${dropped.join(', ')}`);
   }
   return {
@@ -91,5 +98,6 @@ export function sanitizeView(view: unknown): View | undefined {
     ...(theme ? { theme } : {}),
     ...(palette ? { palette } : {}),
     ...(locale ? { locale } : {}),
+    ...(panels ? { panels } : {}),
   };
 }