@adecore/ui 0.39.0 → 0.40.1

package/src/settings/MasterDetail.tsx

@@ -4,22 +4,17 @@ import clsx from 'clsx';
 const LIST_WIDTHS = { 280: 'w-70', 320: 'w-80', 340: 'w-85' } as const;
 
 export interface MasterDetailProps {
-    /* The column on the left, usually `MasterItem`s under their own headers. */
+    /* Usually `MasterItem`s under their own headers. */
     list: ReactNode;
+
     listWidth: keyof typeof LIST_WIDTHS;
-    /* Names the list for a screen reader. */
     listLabel: string;
     detail: ReactNode;
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
 
-/*
- * A list beside the detail of what is picked in it, for a pane of many things of one kind (accounts,
- * devices, shortcut categories). Each side scrolls on its own, and the detail takes the rest of the
- * width, like a single-column pane. Its section must be `split`, so the dialog hands the pane its whole height
- * instead of a padded scrolling column.
- */
+/* Its section must be `split`, so the dialog hands the pane its whole height instead of a padded scrolling column. */
 export function MasterDetail({ list, listWidth, listLabel, detail, className, ref }: MasterDetailProps) {
     return (
         <div ref={ref} className={clsx('flex min-h-0 min-w-0 grow border-t border-border max-[640px]:flex-col', className)}>
@@ -47,7 +42,6 @@ export interface MasterItemProps {
     ref?: Ref<HTMLButtonElement>;
 }
 
-/* One row of the list. The picked one is lifted a shade. */
 export function MasterItem({ selected, onSelect, children, className, ref }: MasterItemProps) {
     return (
         <button

package/src/settings/SettingsDialog.tsx

@@ -17,34 +17,40 @@ export interface SettingsSectionEntry {
     id: string;
     icon: LucideIcon;
     label: string;
-    /* One line under the pane title that says what the pane is about. */
     description: string;
+
     /* Rendered in a `LazyBoundary`, so a lazy component loads when its section is opened. */
     pane: ComponentType;
+
     /* A list beside a detail that scrolls on its own (`MasterDetail`), instead of one padded column. */
     split?: boolean;
-    /* A block above the pane that runs to its edges, with the title bar floating over its top. Loads with
-       the pane; a `split` section draws none. */
+
+    /* Runs to the pane's edges, with the title bar floating over its top; a `split` section draws none. */
     hero?: ComponentType;
 }
 
 export interface SettingsGroupEntry {
     /* The first group usually goes without one. */
     label: string | null;
+
     sections: readonly SettingsSectionEntry[];
 }
 
 export interface SettingsSearchResult {
     section: string;
+
     /* The row to reveal (a `SettingsRow` `searchId`), or null for a result that is the pane itself. */
     id: string | null;
+
     label: string;
 }
 
 export interface SettingsSearch {
     find(query: string): readonly SettingsSearchResult[];
-    /* The shortcut that focuses the field, as it is printed. */
+
+    /* The printed shortcut that focuses the field. */
     hint?: string;
+
     /* Focuses and selects the field each time it grows. */
     focusAt?: number;
 }
@@ -53,20 +59,24 @@ export interface SettingsDialogProps {
     open: boolean;
     onOpenChange(open: boolean): void;
     section: string;
-    /* A tab or a section picked, or a search result with the row it leads to. */
     onNavigate(next: { section: string; target?: string | null }): void;
     groups: readonly SettingsGroupEntry[];
-    /* At the foot of the navigation, under the groups. */
     footer?: readonly SettingsSectionEntry[];
+
     /* Under the footer sections, past a hairline: a section whose tab the app draws itself (a `Tabs.Tab`
        with the section's id as its value), such as an account. */
     account?: { section: SettingsSectionEntry; tab: ReactNode };
+
     search?: SettingsSearch;
+
     /* The row a search result jumped to, lit until `onTargetShown`. */
     target?: string | null;
+
     onTargetShown?(): void;
-    /* Extra on the popup. */
+
+    /* On the popup. */
     className?: string;
+
     ref?: Ref<HTMLDivElement>;
 }
 
@@ -87,6 +97,7 @@ function NavTab({ section }: { section: SettingsSectionEntry }) {
 
 function SettingsNav({ groups, footer, account }: Pick<SettingsDialogProps, 'groups' | 'footer' | 'account'>) {
     const { t } = useTranslation('ui');
+
     return (
         <Tabs.List aria-label={t('settings.sections')} activateOnFocus className="flex min-h-0 grow flex-col">
             <div className="flex min-h-0 flex-col gap-3.5 overflow-y-auto">
@@ -148,8 +159,10 @@ function SearchField({ search, query, onQuery, onPick }: SearchFieldProps) {
                         event.stopPropagation();
                         onQuery('');
                     }
+
                     if (event.key === 'Enter') {
                         const first = search.find(query)[0];
+
                         if (first) {
                             onPick(first);
                         }
@@ -183,7 +196,6 @@ interface SearchResultsProps {
     onPick(result: SettingsSearchResult): void;
 }
 
-/* In place of the navigation while a query is typed: the panes and rows that match, each a jump to where it lives. */
 function SearchResults({ search, query, labelOf, onPick }: SearchResultsProps) {
     const { t, i18n } = useTranslation('ui');
     // The language is a dependency the linter cannot see; every result reads its words off i18next.
@@ -193,6 +205,7 @@ function SearchResults({ search, query, labelOf, onPick }: SearchResultsProps) {
     if (results.length === 0) {
         return <p className="px-2.5 py-1 text-xs break-words text-text-muted">{t('settings.search.none', { query: query.trim() })}</p>;
     }
+
     return (
         <ul className="flex min-h-0 flex-col gap-0.5 overflow-y-auto" aria-label={t('settings.search.results')}>
             {results.map((result) => (
@@ -211,7 +224,7 @@ function SearchResults({ search, query, labelOf, onPick }: SearchResultsProps) {
     );
 }
 
-/* Sections on the left, one pane on the right. A pane mounts only while its section is open. */
+/* A pane mounts only while its section is open. */
 export function SettingsDialog({
     open,
     onOpenChange,
@@ -236,12 +249,15 @@ export function SettingsDialog({
     const barFill = useRef<HTMLDivElement>(null);
     // The latest callback behind a stable one, so a lit row's timer does not start over on every render.
     const latestShown = useRef(onTargetShown);
+
     useEffect(() => {
         latestShown.current = onTargetShown;
     });
+
     const targetValue = { target, shown: () => latestShown.current?.() };
 
     const labelOf = (id: string): string => sections.find((entry) => entry.id === id)?.label ?? id;
+
     const pick = (result: SettingsSearchResult): void => onNavigate({ section: result.section, target: result.id });
 
     return (
@@ -249,6 +265,7 @@ export function SettingsDialog({
             open={open}
             onOpenChange={(next) => {
                 onOpenChange(next);
+
                 if (!next) {
                     setQuery('');
                 }
@@ -302,6 +319,7 @@ export function SettingsDialog({
                             {sections.map((entry) => {
                                 const Pane = entry.pane;
                                 const Hero = entry.split ? undefined : entry.hero;
+
                                 return (
                                     <Tabs.Panel
                                         key={entry.id}

package/src/settings/SettingsRow.tsx

@@ -11,18 +11,25 @@ const TARGET_MS = 1600;
 export interface SettingsRowProps {
     label: ReactNode;
     description?: ReactNode;
-    /* The control, aligned right; it carries its own accessible name. */
+
+    /* It carries its own accessible name. */
     control?: ReactNode;
-    /* Content under the label line that needs the whole width, like a list of swatches. */
+
+    /* Under the label line, at the whole width. */
     children?: ReactNode;
-    /* Where the row only shows state, its whole line reads a shade softer. */
+
+    /* For a row that only shows state. */
     muted?: boolean;
-    /* Before the label, held to its first line (`TopIcon`) or a tile of its own. */
+
+    /* Held to the label's first line (`TopIcon`) or a tile of its own. */
     leading?: ReactNode;
-    /* A row that only makes sense under the one above it steps in. */
+
+    /* For a row that only makes sense under the one above it. */
     indent?: boolean;
+
     /* The id a search result names to lead here. */
     searchId?: string;
+
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
@@ -34,7 +41,7 @@ export interface TopIconProps {
     ref?: Ref<HTMLSpanElement>;
 }
 
-/* An icon beside text that may wrap: the box is one line of `text-sm` high, so the icon sits on the first line. */
+/* The box is one line of `text-sm` high, so the icon sits on the first line of text that may wrap. */
 export function TopIcon({ icon, size = 16, className, ref }: TopIconProps) {
     return (
         <span ref={ref} className="flex h-5.5 shrink-0 items-center">
@@ -43,10 +50,7 @@ export function TopIcon({ icon, size = 16, className, ref }: TopIconProps) {
     );
 }
 
-/*
- * One setting: what it is on the left, the control on the right. Where the two do not fit side by
- * side (a tablet, a narrow window) the control wraps under the label instead of widening the dialog.
- */
+/* Where label and control do not fit side by side, the control wraps under the label instead of widening the dialog. */
 export function SettingsRow({ label, description, control, children, muted = false, leading, indent = false, searchId, className, ref }: SettingsRowProps) {
     const row = useRef<HTMLDivElement>(null);
     const { target, shown } = useSettingsTarget();
@@ -56,8 +60,10 @@ export function SettingsRow({ label, description, control, children, muted = fal
         if (!targeted) {
             return;
         }
+
         row.current?.scrollIntoView({ block: 'center' });
         const timer = window.setTimeout(shown, TARGET_MS);
+
         return () => window.clearTimeout(timer);
     }, [targeted, shown]);
 

package/src/settings/SettingsSection.tsx

@@ -6,22 +6,27 @@ import { Icon } from '../Icon.tsx';
 export interface SettingsSectionProps {
     title?: string;
     description?: ReactNode;
-    /* Drawn before the title, muted, for a pane whose sections are kinds of thing. */
+
+    /* For a pane whose sections are kinds of thing. */
     icon?: LucideIcon;
-    /* A tag on the header line, after the action, such as where the settings apply. */
+
+    /* On the header line, after the action. */
     tag?: ReactNode;
-    /* A small control on the header line, aligned right. */
+
     action?: ReactNode;
-    /* A note under the card, in the faint color. */
+
+    /* A note under the card. */
     footer?: ReactNode;
+
     children: ReactNode;
     className?: string;
     ref?: Ref<HTMLElement>;
 }
 
-/* A titled group of rows in one card; rows divide themselves with a hairline. Without a title it is the card alone. */
+/* Rows divide themselves with a hairline. Without a title it is the card alone. */
 export function SettingsSection({ title, description, icon, tag, action, footer, children, className, ref }: SettingsSectionProps) {
     const hasHeader = title !== undefined || description !== undefined || tag !== undefined || action !== undefined;
+
     return (
         <section ref={ref} className={clsx('flex min-w-0 flex-col gap-2.5', className)} aria-label={title}>
             {hasHeader && (

package/src/settings/index.ts

@@ -1,8 +1,10 @@
 /* The settings dialog and the parts a pane is built from. */
 
 export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog.tsx';
+
 export { DetailHeader, type DetailHeaderProps } from './DetailHeader.tsx';
 export { MasterDetail, MasterItem, type MasterDetailProps, type MasterItemProps } from './MasterDetail.tsx';
+
 export {
     SettingsDialog,
     type SettingsDialogProps,
@@ -11,6 +13,7 @@ export {
     type SettingsSearchResult,
     type SettingsSectionEntry
 } from './SettingsDialog.tsx';
+
 export { SettingsRow, TopIcon, type SettingsRowProps, type TopIconProps } from './SettingsRow.tsx';
 export { SettingsSection, type SettingsSectionProps } from './SettingsSection.tsx';
 export { useSettingsTarget } from './target.ts';

package/src/settings/target.ts

@@ -3,6 +3,7 @@ import { createContext, useContext } from 'react';
 interface SettingsTarget {
     /* The row a search result jumped to, by its `searchId`. */
     target: string | null;
+
     /* Called once the row was lit long enough, so it is not lit again on the next render. */
     shown(): void;
 }

package/src/shortcut-hints.ts

@@ -15,6 +15,7 @@ let nextId = 0;
 export const registerShortcutHint = (element: Element, shortcut: Shortcut): (() => void) => {
     nextId += 1;
     targets.set(element, { id: nextId, shortcut });
+
     return () => {
         targets.delete(element);
     };
@@ -24,11 +25,7 @@ export const shortcutHintTargets = (): ReadonlyMap<Element, HintTarget> => targe
 
 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.
- */
+/* The platform's modifier held on its own for `HINT_DELAY_MS`; any other key takes the hints down, so a shortcut pressed in passing never flashes them. */
 export class ModifierHold {
     private readonly apple: boolean;
     private readonly onChange: (shown: boolean) => void;
@@ -45,7 +42,9 @@ export class ModifierHold {
         if (event.repeat && event.key === this.modifierKey()) {
             return;
         }
+
         this.cancel();
+
         if (event.key === this.modifierKey() && !this.otherModifierHeld(event)) {
             this.timer = setTimeout(() => {
                 this.timer = null;
@@ -66,6 +65,7 @@ export class ModifierHold {
             clearTimeout(this.timer);
             this.timer = null;
         }
+
         if (this.shown) {
             this.shown = false;
             this.onChange(false);
@@ -97,8 +97,10 @@ export interface HintPlacement {
 }
 
 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. */
@@ -107,11 +109,14 @@ export const placeHint = (rect: HintRect, viewport: { width: number; height: num
     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

@@ -1,7 +1,6 @@
 /*
- * 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.
+ * `mod` is Cmd on macOS and Ctrl everywhere else; `ctrl` and `meta` name the physical key, for the few
+ * shortcuts that differ per platform on purpose.
  */
 export interface Shortcut {
     mod: boolean;
@@ -9,12 +8,12 @@ export interface Shortcut {
     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. */
@@ -56,19 +55,25 @@ 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) {
         if (Object.hasOwn(MODIFIER_FIELDS, word)) {
             result[MODIFIER_FIELDS[word]!] = 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;
 };
 
@@ -77,16 +82,21 @@ 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;
 };
 
@@ -94,9 +104,11 @@ const matchesKey = (key: string, event: KeyLike): boolean => {
 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);
 };
 
@@ -113,19 +125,23 @@ const KEY_LABELS: Record<string, { apple: string; other: string }> = {
     ArrowDown: { apple: '↓', other: '↓' }
 };
 
-/* The modifiers and the key as separate caps, in the order the platform prints them. */
+/* 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('⌘');
         }
@@ -133,20 +149,25 @@ export const shortcutParts = (target: Shortcut, apple: boolean): string[] => {
         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;
 };
 
@@ -171,5 +192,4 @@ export const KEY_SHORTCUTS = {
     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/tabs/overflow.ts

@@ -1,27 +1,29 @@
-/*
- * The tabs a strip shows, by index, given the width of every tab, the room the strip has, the gap
- * between two tabs and the width of the button that opens the rest. Everything fits, or the tabs fit
- * from the start up to the button. The kept tabs (the picked one, the pinned ones) are never left to
- * the menu: they take the place of the last ones that no longer fit beside them.
- */
+/* The kept tabs (the picked one, the pinned ones) never go to the menu: they take the place of the last ones that no longer fit beside them. */
 export const shownTabs = (widths: readonly number[], room: number, gap: number, more: number, kept: readonly number[]): number[] => {
     const span = (indices: readonly number[]): number => indices.reduce((sum, index) => sum + widths[index]!, 0) + gap * Math.max(0, indices.length - 1);
+
     const all = widths.map((_, index) => index);
+
     // Half a pixel of slack, since a measured width is fractional and the room is not.
     if (span(all) <= room + 0.5) {
         return all;
     }
+
     const limit = room - more - gap + 0.5;
     const held = all.filter((index) => kept.includes(index));
     const shown: number[] = [];
+
     for (const index of all) {
         if (held.includes(index)) {
             continue;
         }
+
         if (span([...held, ...shown, index]) > limit) {
             break;
         }
+
         shown.push(index);
     }
+
     return [...held, ...shown].sort((left, right) => left - right);
 };