@adecore/ui 0.14.0

package/src/shortcut-hints.ts

@@ -0,0 +1,117 @@
+import type { Shortcut } from './shortcut.ts';
+
+/* How long the modifier has to be held on its own before every shortcut shows. */
+export const HINT_DELAY_MS = 500;
+
+export interface HintTarget {
+    id: number;
+    shortcut: Shortcut;
+}
+
+const targets = new Map<Element, HintTarget>();
+let nextId = 0;
+
+/* Called by every `Tooltip` whose `kbd` is a real shortcut; a phrase about a key is no shortcut to print. */
+export const registerShortcutHint = (element: Element, shortcut: Shortcut): (() => void) => {
+    nextId += 1;
+    targets.set(element, { id: nextId, shortcut });
+    return () => {
+        targets.delete(element);
+    };
+};
+
+export const shortcutHintTargets = (): ReadonlyMap<Element, HintTarget> => targets;
+
+export type HoldKey = Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'repeat'>;
+
+/*
+ * Whether the hints are up: the platform's modifier (Cmd on macOS, Ctrl elsewhere) held on its own for
+ * `HINT_DELAY_MS`. Any other key, the modifier coming up or the caller cancelling takes them down, so
+ * a shortcut pressed in passing never flashes them.
+ */
+export class ModifierHold {
+    private readonly apple: boolean;
+    private readonly onChange: (shown: boolean) => void;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private shown = false;
+
+    constructor(apple: boolean, onChange: (shown: boolean) => void) {
+        this.apple = apple;
+        this.onChange = onChange;
+    }
+
+    keyDown(event: HoldKey): void {
+        // A repeat is the key still held; only a fresh press starts the wait.
+        if (event.repeat && event.key === this.modifierKey()) {
+            return;
+        }
+        this.cancel();
+        if (event.key === this.modifierKey() && !this.otherModifierHeld(event)) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                this.shown = true;
+                this.onChange(true);
+            }, HINT_DELAY_MS);
+        }
+    }
+
+    keyUp(event: Pick<KeyboardEvent, 'key'>): void {
+        if (event.key === this.modifierKey()) {
+            this.cancel();
+        }
+    }
+
+    cancel(): void {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.shown) {
+            this.shown = false;
+            this.onChange(false);
+        }
+    }
+
+    private modifierKey(): string {
+        return this.apple ? 'Meta' : 'Control';
+    }
+
+    private otherModifierHeld(event: HoldKey): boolean {
+        return event.altKey || event.shiftKey || (this.apple ? event.ctrlKey : event.metaKey);
+    }
+}
+
+export interface HintRect {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+
+export interface HintPlacement {
+    left?: number;
+    right?: number;
+    top: number;
+    translateX: '0' | '-50%';
+    translateY: '0' | '-100%';
+}
+
+const HINT_GAP_PX = 2;
+/* Room a hint needs to be centered under its button; nearer a window edge it lines up with that edge instead. */
+const EDGE_ROOM_PX = 48;
+const HINT_HEIGHT_PX = 24;
+
+/* Under the button, centered, and above it where the window ends first. */
+export const placeHint = (rect: HintRect, viewport: { width: number; height: number }): HintPlacement => {
+    const below = rect.bottom + HINT_GAP_PX + HINT_HEIGHT_PX <= viewport.height;
+    const top = Math.round(below ? rect.bottom + HINT_GAP_PX : rect.top - HINT_GAP_PX);
+    const translateY = below ? '0' : '-100%';
+    const center = (rect.left + rect.right) / 2;
+    if (center < EDGE_ROOM_PX) {
+        return { left: Math.round(rect.left), top, translateX: '0', translateY };
+    }
+    if (center > viewport.width - EDGE_ROOM_PX) {
+        return { right: Math.round(viewport.width - rect.right), top, translateX: '0', translateY };
+    }
+    return { left: Math.round(center), top, translateX: '-50%', translateY };
+};

package/src/shortcut.ts

@@ -0,0 +1,170 @@
+/*
+ * One shortcut, written once. The same value decides whether a key event is the shortcut and how the
+ * shortcut is printed. `mod` is Cmd on macOS and Ctrl everywhere else; `ctrl` and `meta` name the
+ * physical key and exist for the few shortcuts that differ per platform on purpose.
+ */
+export interface Shortcut {
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+    /* An uppercase letter, a digit, a punctuation mark or a named key (`Enter`, `ArrowLeft`, `F2`).
+       Empty for modifiers held during a pointer gesture (`Mod` then "drag"), which never match a key. */
+    key: string;
+}
+
+/* What a shortcut is matched against. A real `KeyboardEvent` satisfies it, a test writes one by hand. */
+export type KeyLike = Pick<KeyboardEvent, 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'key' | 'code'>;
+
+/* Matched on the physical key: Shift turns `[` into `{` and Option turns most keys into a dead key. */
+const PUNCTUATION_CODES: Record<string, string> = {
+    ',': 'Comma',
+    '.': 'Period',
+    '/': 'Slash',
+    ';': 'Semicolon',
+    "'": 'Quote',
+    '`': 'Backquote',
+    '\\': 'Backslash',
+    '[': 'BracketLeft',
+    ']': 'BracketRight'
+};
+
+/* Matched on the character, because `+` sits on a different key per layout. */
+const CHARACTER_KEYS = new Set(['+', '-', '=']);
+
+const NAMED_KEYS = new Set(['Enter', 'Escape', 'Backspace', 'Delete', 'Tab', 'Space', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown']);
+
+const FUNCTION_KEY = /^F([1-9]|1[0-2])$/;
+
+const MODIFIER_WORDS = ['Mod', 'Ctrl', 'Meta', 'Alt', 'Shift'] as const;
+
+const isKey = (word: string): boolean =>
+    /^[A-Za-z0-9]$/.test(word) || word in PUNCTUATION_CODES || CHARACTER_KEYS.has(word) || NAMED_KEYS.has(word) || FUNCTION_KEY.test(word);
+
+/**
+ * Parses `Mod+Shift+K`. Throws on a word it does not know or on two keys, so a typo in a table fails
+ * the moment the module loads instead of leaving a shortcut that never fires.
+ */
+export const shortcut = (text: string): Shortcut => {
+    // A trailing `++` is the plus key itself, which a plain split would read as two empty words.
+    const words = text === '+' ? ['+'] : text.endsWith('++') ? [...text.slice(0, -2).split('+'), '+'] : text.split('+');
+    const result: Shortcut = { mod: false, ctrl: false, meta: false, alt: false, shift: false, key: '' };
+    for (const word of words) {
+        const modifier = MODIFIER_WORDS.find((candidate) => candidate === word);
+        if (modifier) {
+            result[modifier === 'Mod' ? 'mod' : modifier === 'Ctrl' ? 'ctrl' : modifier === 'Meta' ? 'meta' : modifier === 'Alt' ? 'alt' : 'shift'] = true;
+            continue;
+        }
+        if (!isKey(word)) {
+            throw new Error(`Unknown key "${word}" in shortcut "${text}"`);
+        }
+        if (result.key !== '') {
+            throw new Error(`Shortcut "${text}" names two keys`);
+        }
+        result.key = word.length === 1 ? word.toUpperCase() : word;
+    }
+    return result;
+};
+
+// Letters and digits match on `code`: with Shift held `key` says `!` for 1, and Option's dead keys change it on macOS.
+const matchesKey = (key: string, event: KeyLike): boolean => {
+    if (/^[A-Z]$/.test(key)) {
+        return event.code === `Key${key}`;
+    }
+    if (/^[0-9]$/.test(key)) {
+        return event.code === `Digit${key}`;
+    }
+    const code = PUNCTUATION_CODES[key];
+    if (code) {
+        return event.code === code;
+    }
+    if (key === 'Space') {
+        return event.code === 'Space';
+    }
+    return event.key === key;
+};
+
+/* Strict: every modifier the shortcut does not name has to be up, so Ctrl+K on macOS is not Cmd+K. */
+export const matchesShortcut = (target: Shortcut, event: KeyLike, apple: boolean): boolean => {
+    const meta = target.meta || (target.mod && apple);
+    const ctrl = target.ctrl || (target.mod && !apple);
+    if (target.key === '' || event.metaKey !== meta || event.ctrlKey !== ctrl || event.altKey !== target.alt || event.shiftKey !== target.shift) {
+        return false;
+    }
+    return matchesKey(target.key, event);
+};
+
+const KEY_LABELS: Record<string, { apple: string; other: string }> = {
+    Enter: { apple: '↩', other: 'Enter' },
+    Backspace: { apple: '⌫', other: 'Backspace' },
+    Delete: { apple: '⌦', other: 'Delete' },
+    Escape: { apple: 'Esc', other: 'Esc' },
+    Tab: { apple: '⇥', other: 'Tab' },
+    Space: { apple: 'Space', other: 'Space' },
+    ArrowLeft: { apple: '←', other: '←' },
+    ArrowRight: { apple: '→', other: '→' },
+    ArrowUp: { apple: '↑', other: '↑' },
+    ArrowDown: { apple: '↓', other: '↓' }
+};
+
+/* The modifiers and the key as separate caps, in the order the platform prints them. */
+export const shortcutParts = (target: Shortcut, apple: boolean): string[] => {
+    const parts: string[] = [];
+    if (apple) {
+        if (target.ctrl) {
+            parts.push('⌃');
+        }
+        if (target.alt) {
+            parts.push('⌥');
+        }
+        if (target.shift) {
+            parts.push('⇧');
+        }
+        if (target.meta || target.mod) {
+            parts.push('⌘');
+        }
+    } else {
+        if (target.ctrl || target.mod) {
+            parts.push('Ctrl');
+        }
+        if (target.alt) {
+            parts.push('Alt');
+        }
+        if (target.shift) {
+            parts.push('Shift');
+        }
+        if (target.meta) {
+            parts.push('Meta');
+        }
+    }
+    if (target.key !== '') {
+        const label = KEY_LABELS[target.key];
+        parts.push(label ? label[apple ? 'apple' : 'other'] : target.key);
+    }
+    return parts;
+};
+
+/* `⌥⇧⌘K` on macOS, `Ctrl+Alt+Shift+K` elsewhere. */
+export const formatShortcut = (target: Shortcut, apple: boolean): string => shortcutParts(target, apple).join(apple ? '' : '+');
+
+/* The browser's own editing shortcuts, which the app only ever prints in a menu. */
+export const EDIT_SHORTCUTS = {
+    copy: /* @__PURE__ */ shortcut('Mod+C'),
+    cut: /* @__PURE__ */ shortcut('Mod+X'),
+    paste: /* @__PURE__ */ shortcut('Mod+V'),
+    selectAll: /* @__PURE__ */ shortcut('Mod+A')
+} as const;
+
+/* Keys that are not a shortcut of their own but are printed as one in a hint. */
+export const KEY_SHORTCUTS = {
+    enter: /* @__PURE__ */ shortcut('Enter'),
+    modEnter: /* @__PURE__ */ shortcut('Mod+Enter'),
+    backspace: /* @__PURE__ */ shortcut('Backspace'),
+    escape: /* @__PURE__ */ shortcut('Escape'),
+    shift: /* @__PURE__ */ shortcut('Shift'),
+    rename: /* @__PURE__ */ shortcut('F2')
+} as const;
+
+/* Whether the platform's own modifier is down during a pointer gesture: Cmd on macOS, Ctrl elsewhere. */
+export const isModHeld = (event: Pick<KeyLike, 'metaKey' | 'ctrlKey'>, apple: boolean): boolean => (apple ? event.metaKey : event.ctrlKey);

package/src/testing/dedupe.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Glob, plugin } from 'bun';
+
+/*
+ * A preload for `bun test` in an app that links a checkout of this library: what `resolve.dedupe`
+ * does for Vite. The checkout has node_modules of its own, and a second React, i18next or Base UI
+ * breaks every hook, every word and every compound part. Bun has no dedupe and its resolve hook never
+ * sees a package import, so every file of these packages in the checkout loads as a stand-in for the
+ * same file in the app's copy. Does nothing for a package the checkout has no copy of, which is every
+ * package once the library is installed from the registry.
+ */
+const SHARED = ['react', 'react-dom', 'i18next', 'react-i18next', '@base-ui-components/react'];
+
+const NAME = '@adecore/ui';
+
+/* The package root, from `src/testing` or `dist/testing` alike. */
+const library = realpathSync(join(import.meta.dir, '..', '..'));
+
+interface Manifest {
+    workspaces?: string[] | { packages?: string[] };
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+
+const manifestOf = (folder: string): Manifest | null => {
+    const path = join(folder, 'package.json');
+    return existsSync(path) ? (JSON.parse(readFileSync(path, 'utf8')) as Manifest) : null;
+};
+
+const dependsOnLibrary = (manifest: Manifest | null): boolean =>
+    manifest !== null && [manifest.dependencies, manifest.devDependencies, manifest.peerDependencies].some((deps) => deps !== undefined && NAME in deps);
+
+/*
+ * Where the app's copies are found: the folder the tests run in, then each workspace of it that
+ * depends on the library. With an isolated install the root of a monorepo has no React of its own.
+ */
+const appFolders = (): string[] => {
+    const root = process.cwd();
+    const workspaces = manifestOf(root)?.workspaces;
+    const patterns = (Array.isArray(workspaces) ? workspaces : workspaces?.packages) ?? [];
+    const members = patterns
+        .flatMap((pattern) => [...new Glob(`${pattern}/package.json`).scanSync({ cwd: root, onlyFiles: true })])
+        .map((path) => join(root, dirname(path)))
+        .filter((folder) => dependsOnLibrary(manifestOf(folder)));
+    return [root, ...members];
+};
+
+/* The copy of a package that `from` resolves to, walking up the node_modules folders as Node does. */
+const copyFrom = (from: string, name: string): string | null => {
+    for (let folder = from; ; folder = dirname(folder)) {
+        const candidate = join(folder, 'node_modules', name);
+        if (existsSync(candidate)) {
+            return realpathSync(candidate);
+        }
+        if (dirname(folder) === folder) {
+            return null;
+        }
+    }
+};
+
+const folders = appFolders();
+
+const copies = SHARED.flatMap((name) => {
+    const theirs = join(library, 'node_modules', name);
+    if (!existsSync(theirs)) {
+        return [];
+    }
+    const real = realpathSync(theirs);
+    const ours = folders.map((folder) => copyFrom(folder, name)).find((copy): copy is string => copy !== null && !copy.startsWith(`${library}/`));
+    return ours === undefined || ours === real ? [] : [{ theirs: `${real}/`, ours: `${ours}/` }];
+});
+
+const escape = (text: string): string => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+
+// Bun refuses `export default` beside `export *`, so the stand-in names every export of the real file.
+const standIn = (path: string): string => {
+    const names = Object.keys(require(path) as object).filter((name) => name !== 'default' && /^[A-Za-z_$][\w$]*$/.test(name));
+    return [`import * as real from ${JSON.stringify(path)};`, 'export default real.default;', `export const { ${names.join(', ')} } = real;`].join('\n');
+};
+
+if (copies.length > 0) {
+    plugin({
+        name: 'adecore-ui-dedupe',
+        setup(build) {
+            build.onLoad({ filter: new RegExp(`^(${copies.map((copy) => escape(copy.theirs)).join('|')})`) }, (args) => {
+                const copy = copies.find((candidate) => args.path.startsWith(candidate.theirs))!;
+                return { contents: standIn(copy.ours + args.path.slice(copy.theirs.length)), loader: 'js' };
+            });
+        }
+    });
+}

package/src/testing/fake-source.ts

@@ -0,0 +1,21 @@
+import type { FormatSource } from '../format/locale.ts';
+import { FORMAT_LANGUAGE } from '../format/regions.ts';
+
+export interface FakeFormatSource extends FormatSource {
+    set(settings: { language?: string; region?: string }): void;
+}
+
+/* A source a test sets by hand: English, the region of the language, and no system locale of a shell. */
+export const fakeFormatSource = (): FakeFormatSource => {
+    let language = 'en';
+    let region: string = FORMAT_LANGUAGE;
+    return {
+        language: () => language,
+        region: () => region,
+        subscribe: () => () => {},
+        set: (settings) => {
+            language = settings.language ?? language;
+            region = settings.region ?? region;
+        }
+    };
+};

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+/* Fakes for an app's own tests. Nothing here belongs in a bundle that ships. */
+
+export { fakeFormatSource, type FakeFormatSource } from './fake-source.ts';