@plannotator/ui 0.28.0 → 0.29.0

package/utils/themeRegistry.ts

@@ -1,3 +1,5 @@
+import { parseThemeMode, type Mode } from '../components/themeModes';
+
 export interface ThemeColors {
   primary: string;
   secondary: string;
@@ -133,6 +135,17 @@ export const BUILT_IN_THEMES: ThemeInfo[] = [
       light: { primary: '#3C7CAB', secondary: '#E8E8E8', accent: '#4C7F8C', background: '#FCFCFC', foreground: '#141414' },
     },
   },
+  {
+    id: 'colorblind',
+    name: 'Colorblind',
+    builtIn: true,
+    modeSupport: 'both',
+    syntaxHighlighting: true,
+    colors: {
+      dark: { primary: '#7fb0f2', secondary: '#2a2e37', accent: '#e5b84a', background: '#16181d', foreground: '#eaedf2' },
+      light: { primary: '#1a63b8', secondary: '#e7eaef', accent: '#946300', background: '#f8f9fb', foreground: '#22262e' },
+    },
+  },
   {
     id: 'dark-plus',
     name: 'Dark+',
@@ -565,3 +578,144 @@ export const BUILT_IN_THEMES: ThemeInfo[] = [
     },
   },
 ];
+
+/** Return the explicit mode a palette cannot render, if any. */
+export function getUnsupportedMode(themeId: string): 'light' | 'dark' | null {
+  const theme = BUILT_IN_THEMES.find(({ id }) => id === themeId);
+  if (theme?.modeSupport === 'dark-only') return 'light';
+  if (theme?.modeSupport === 'light-only') return 'dark';
+  return null;
+}
+
+/**
+ * Return whether a palette can honor a mode choice without coercion.
+ *
+ * @deprecated Every mode is always selectable now that a palette is assigned to
+ * one half of a light/dark pair: a palette that cannot render a mode simply
+ * never occupies that half. Use {@link themeSupportsHalf} to ask whether a
+ * palette may be ASSIGNED to a half. Kept for published consumers.
+ */
+export function isThemeModeAvailable(themeId: string, mode: Mode): boolean {
+  return mode === 'system' || getUnsupportedMode(themeId) !== mode;
+}
+
+/**
+ * Keep System intact while coercing an unsupported explicit mode.
+ *
+ * @deprecated Modes are no longer coerced. Assign the palette to the half it
+ * supports ({@link themeSupportsHalf}) and let {@link resolveThemeMode} handle
+ * rendering. Kept for published consumers.
+ */
+export function normalizeThemeMode(themeId: string, mode: Mode): Mode {
+  const unsupportedMode = getUnsupportedMode(themeId);
+  if (mode === 'system' || mode !== unsupportedMode) return mode;
+  return unsupportedMode === 'light' ? 'dark' : 'light';
+}
+
+/** Resolve the mode a palette actually renders. */
+export function resolveThemeMode(
+  themeId: string,
+  preferredMode: 'light' | 'dark',
+): 'light' | 'dark' {
+  const unsupportedMode = getUnsupportedMode(themeId);
+  if (preferredMode !== unsupportedMode) return preferredMode;
+  return unsupportedMode === 'light' ? 'dark' : 'light';
+}
+
+// --- Light/dark theme pairs -------------------------------------------------
+//
+// A user assigns one palette to the light half and one to the dark half. The
+// active palette is pair[preferredMode], so System mode flips between the two
+// (Kanagawa Lotus by day, Kanagawa Wave at night). Mode-restricted palettes are
+// only ever offered for the half they can render, which is why no mode needs to
+// be coerced any more.
+
+/** Which half of a light/dark pair a palette is assigned to. */
+export type ThemeHalf = 'light' | 'dark';
+
+/** A user's full appearance choice: which mode, and a palette for each half. */
+export interface ThemePair {
+  mode: Mode;
+  light: string;
+  dark: string;
+}
+
+/** The palette every fresh install starts on, in both halves. */
+export const DEFAULT_COLOR_THEME = 'plannotator';
+
+export const DEFAULT_THEME_PAIR: ThemePair = {
+  mode: 'dark',
+  light: DEFAULT_COLOR_THEME,
+  dark: DEFAULT_COLOR_THEME,
+};
+
+/** Return whether a palette is registered. */
+export function isKnownTheme(themeId: unknown): themeId is string {
+  return typeof themeId === 'string' && BUILT_IN_THEMES.some(({ id }) => id === themeId);
+}
+
+/** Return whether a palette can occupy one half of the pair. */
+export function themeSupportsHalf(themeId: string, half: ThemeHalf): boolean {
+  return getUnsupportedMode(themeId) !== half;
+}
+
+/** The palettes assignable to one half — `both` palettes appear in each. */
+export function themesForHalf(themes: ThemeInfo[], half: ThemeHalf): ThemeInfo[] {
+  return themes.filter(({ id }) => themeSupportsHalf(id, half));
+}
+
+/**
+ * Seed a pair from the single palette older versions persisted. A `both`
+ * palette takes over both halves; a mode-restricted one takes the half it
+ * supports and the other half falls back to the default palette.
+ */
+export function seedThemePair(colorThemeId: unknown, mode: Mode): ThemePair {
+  const id = isKnownTheme(colorThemeId) ? colorThemeId : DEFAULT_COLOR_THEME;
+  return {
+    mode,
+    light: themeSupportsHalf(id, 'light') ? id : DEFAULT_COLOR_THEME,
+    dark: themeSupportsHalf(id, 'dark') ? id : DEFAULT_COLOR_THEME,
+  };
+}
+
+/**
+ * Repair an untrusted pair (cookie, config.json, or an older release) so every
+ * half holds a registered palette that can actually render it.
+ */
+export function normalizeThemePair(
+  input: Partial<Record<keyof ThemePair, unknown>> | undefined,
+  fallback: ThemePair = DEFAULT_THEME_PAIR,
+): ThemePair {
+  const half = (key: ThemeHalf): string => {
+    const candidate = input?.[key];
+    if (isKnownTheme(candidate) && themeSupportsHalf(candidate, key)) return candidate;
+    return themeSupportsHalf(fallback[key], key) ? fallback[key] : DEFAULT_COLOR_THEME;
+  };
+  return {
+    mode: parseThemeMode(input?.mode, fallback.mode),
+    light: half('light'),
+    dark: half('dark'),
+  };
+}
+
+/** The palette a pair renders for the mode the user is actually seeing. */
+export function resolvePairTheme(pair: ThemePair, preferredMode: ThemeHalf): string {
+  return pair[preferredMode];
+}
+
+/* The pair a fresh install starts from. ThemeProvider installs its own props
+   here before the config store resolves, so a host embedding @plannotator/ui
+   keeps its `defaultTheme` / `defaultColorTheme` defaults. */
+let defaultThemePair: ThemePair = DEFAULT_THEME_PAIR;
+
+export function setDefaultThemePair(pair: ThemePair): void {
+  defaultThemePair = pair;
+}
+
+export function getDefaultThemePair(): ThemePair {
+  return defaultThemePair;
+}
+
+export function resetDefaultThemePair(): void {
+  defaultThemePair = DEFAULT_THEME_PAIR;
+}

package/utils/vimHud.ts

@@ -0,0 +1,263 @@
+import {
+  describeVimSelectionAction,
+  vimSelectionShortcuts,
+  type VimSelectionActionId,
+  type VimSelectionHudContext,
+} from '../shortcuts/plan-review/vimSelection.shortcuts';
+
+/** Semantic label displayed in the Vim key HUD. */
+export type VimHudPhase =
+  | 'BLOCK'
+  | 'INLINE'
+  | 'LINE'
+  | 'WORD'
+  | 'TEXT'
+  | 'VISUAL'
+  | 'ACTION';
+
+/** One successfully handled Vim command rendered by the key HUD. */
+export interface VimHudCommand {
+  readonly sequence: number;
+  readonly actionId: VimSelectionActionId;
+  readonly key: string;
+  readonly description: string;
+  readonly context: VimSelectionHudContext;
+}
+
+/** Stable section identifiers used by the expanded Vim HUD key map. */
+export type VimHudLegendGroupId =
+  | 'structure'
+  | 'text'
+  | 'selection'
+  | 'annotation'
+  | 'control';
+
+/** One registered Vim command projected into the expanded HUD key map. */
+export interface VimHudLegendItem {
+  readonly actionId: VimSelectionActionId;
+  readonly key: string;
+  readonly description: string;
+}
+
+/** One learnable command family rendered in the expanded HUD key map. */
+export interface VimHudLegendGroup {
+  readonly id: VimHudLegendGroupId;
+  readonly title: string;
+  readonly description: string;
+  readonly items: readonly VimHudLegendItem[];
+}
+
+interface VimHudLegendGroupSpec {
+  readonly id: VimHudLegendGroupId;
+  readonly title: string;
+  readonly description: string;
+  readonly context: VimSelectionHudContext;
+  readonly actionIds: readonly VimSelectionActionId[];
+}
+
+const VIM_HUD_LEGEND_GROUP_SPECS: readonly VimHudLegendGroupSpec[] = [
+  {
+    id: 'structure',
+    title: 'Document',
+    description: 'Move by blocks and semantic structure',
+    context: 'block',
+    actionIds: [
+      'moveDown',
+      'moveUp',
+      'documentStart',
+      'documentEnd',
+      'moveOut',
+      'refine',
+    ],
+  },
+  {
+    id: 'text',
+    title: 'Text',
+    description: 'Move by characters, lines, words, and paragraphs',
+    context: 'text',
+    actionIds: [
+      'moveOut',
+      'refine',
+      'moveDown',
+      'moveUp',
+      'wordForward',
+      'wordBackward',
+      'wordEnd',
+      'lineStart',
+      'lineEnd',
+      'previousTextBlock',
+      'nextTextBlock',
+    ],
+  },
+  {
+    id: 'selection',
+    title: 'Select',
+    description: 'Grow an exact or whole-block selection',
+    context: 'block',
+    actionIds: ['visual', 'visualBlock', 'swapSelectionEnds'],
+  },
+  {
+    id: 'annotation',
+    title: 'Annotate',
+    description: 'Act on the current target or selection',
+    context: 'block',
+    actionIds: [
+      'activeAnnotation',
+      'annotationMenu',
+      'comment',
+      'redline',
+      'markup',
+      'label',
+      'copy',
+    ],
+  },
+  {
+    id: 'control',
+    title: 'Control',
+    description: 'Back out or show this key map',
+    context: 'block',
+    actionIds: ['cancel', 'help'],
+  },
+];
+
+function normalizeVimHudKey(
+  actionId: VimSelectionActionId,
+  rawKey: string,
+): string {
+  if (actionId === 'documentStart') return 'gg';
+  if (rawKey === 'Escape') return 'esc';
+  if (rawKey === 'Enter') return 'enter';
+  if (rawKey === ' ' || rawKey === 'Space' || rawKey === 'Spacebar') return 'space';
+  return rawKey;
+}
+
+function formatVimLegendKey(
+  actionId: VimSelectionActionId,
+  binding: string,
+): string {
+  if (actionId === 'documentStart') return 'gg';
+  if (actionId === 'documentEnd') return 'G';
+  if (actionId === 'visualBlock') return 'V';
+  if (binding === 'Escape') return 'esc';
+  if (binding === 'Enter') return 'enter';
+  if (binding === 'Space') return 'space';
+  return binding.length === 1 ? binding.toLowerCase() : binding;
+}
+
+/**
+ * Build immutable HUD feedback from a command that the Vim controller handled.
+ */
+export function createVimHudCommand(
+  sequence: number,
+  actionId: VimSelectionActionId,
+  rawKey: string,
+  context: VimSelectionHudContext,
+): VimHudCommand {
+  return {
+    sequence,
+    actionId,
+    key: normalizeVimHudKey(actionId, rawKey),
+    description: describeVimSelectionAction(actionId, context),
+    context,
+  };
+}
+
+/**
+ * Project the registered Vim shortcut scope into learnable HUD groups.
+ *
+ * Movement actions intentionally appear in both Document and Text with
+ * contextual descriptions because the same Vim keys change granularity after
+ * the user refines into text.
+ */
+export function getVimHudLegendGroups(): readonly VimHudLegendGroup[] {
+  return VIM_HUD_LEGEND_GROUP_SPECS.map((group) => ({
+    id: group.id,
+    title: group.title,
+    description: group.description,
+    items: group.actionIds.map((actionId) => {
+      const shortcut = vimSelectionShortcuts.shortcuts[actionId];
+      return {
+        actionId,
+        key: formatVimLegendKey(actionId, shortcut.bindings[0] ?? ''),
+        description: describeVimSelectionAction(actionId, group.context),
+      };
+    }),
+  }));
+}
+
+/**
+ * Return whether a legend group represents the HUD's current movement level.
+ */
+export function isVimHudLegendGroupActive(
+  groupId: VimHudLegendGroupId,
+  phase: VimHudPhase,
+): boolean {
+  switch (phase) {
+    case 'BLOCK':
+    case 'INLINE':
+      return groupId === 'structure';
+    case 'LINE':
+    case 'WORD':
+    case 'TEXT':
+      return groupId === 'text';
+    case 'VISUAL':
+      return groupId === 'selection';
+    case 'ACTION':
+      return groupId === 'annotation';
+  }
+}
+
+/**
+ * Project live Vim navigation state and the latest motion into the video HUD's
+ * semantic phase vocabulary.
+ */
+export function getVimHudPhase(
+  state: VimSelectionHudContext,
+  actionId?: VimSelectionActionId,
+): VimHudPhase {
+  switch (state) {
+    case 'action':
+      return 'ACTION';
+    case 'visual':
+    case 'visual-block':
+      return 'VISUAL';
+    case 'inline':
+      return 'INLINE';
+    case 'block':
+    case 'inactive':
+      return 'BLOCK';
+    case 'text':
+      switch (actionId) {
+        case 'moveDown':
+        case 'moveUp':
+        case 'lineStart':
+        case 'lineEnd':
+          return 'LINE';
+        case 'wordForward':
+        case 'wordBackward':
+        case 'wordEnd':
+          return 'WORD';
+        case 'previousTextBlock':
+        case 'nextTextBlock':
+          return 'BLOCK';
+        case 'documentStart':
+        case 'documentEnd':
+        case 'moveOut':
+        case 'refine':
+        case 'visual':
+        case 'visualBlock':
+        case 'swapSelectionEnds':
+        case 'activeAnnotation':
+        case 'annotationMenu':
+        case 'comment':
+        case 'redline':
+        case 'markup':
+        case 'label':
+        case 'copy':
+        case 'cancel':
+        case 'help':
+        case undefined:
+          return 'TEXT';
+      }
+  }
+}

package/utils/vimModeAnnouncement.ts

@@ -0,0 +1,23 @@
+/**
+ * Tracks whether the user has seen the Vim controls announcement.
+ *
+ * Cookie-backed storage keeps the dismissal across Plannotator's random
+ * localhost ports while still honoring host-provided storage backends.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-vim-mode-announcement-seen';
+// v2 is the full interactive introduction with the live settings and HUD
+// showcase. Earlier development builds used v1 for a smaller notice.
+const CURRENT_VERSION = '2';
+
+/** Return whether the current announcement version has not been dismissed. */
+export function needsVimModeAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+/** Persist dismissal of the current announcement version in shared UI storage. */
+export function markVimModeAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}