@adecore/ui 0.38.0 → 0.40.0

package/src/RelativeTime.tsx

@@ -10,19 +10,22 @@ const TICK_MS = 30_000;
 export interface RelativeTimeProps {
     /* `null`, `undefined` or an invalid date for a moment that is not known, drawn as a dash. */
     at: Date | number | null | undefined;
+
     /* Off inside a row that is the focus target itself: no tab stop of its own, and the row shows the exact time. */
     tooltip?: boolean;
+
     tooltipSide?: TooltipSide;
     className?: string;
     ref?: Ref<HTMLElement>;
 }
 
-/* A moment as its age, `3m ago`, counting on while it is on screen, with the exact time on hover and on keyboard focus. */
+/* Counts on while it is on screen, with the exact time on hover and on keyboard focus. */
 export function RelativeTime({ at, tooltip = true, tooltipSide, className, ref }: RelativeTimeProps) {
     // The formatters read the locale from a module, not from an input, so a compiled render would keep its first words.
     'use no memo';
     useFormatLocale();
     const now = useNow(TICK_MS);
+
     if (at === null || at === undefined || Number.isNaN(new Date(at).getTime())) {
         return (
             <span ref={ref} className={className}>
@@ -30,6 +33,7 @@ export function RelativeTime({ at, tooltip = true, tooltipSide, className, ref }
             </span>
         );
     }
+
     if (!tooltip) {
         return (
             <time ref={ref as Ref<HTMLTimeElement>} dateTime={new Date(at).toISOString()} className={clsx('whitespace-nowrap', className)}>
@@ -37,6 +41,7 @@ export function RelativeTime({ at, tooltip = true, tooltipSide, className, ref }
             </time>
         );
     }
+
     return (
         <Tooltip label={formatDayClockWithYear(at)} side={tooltipSide}>
             {/* Text is no tab stop of its own, and a hint that only the pointer can open is lost to the keyboard. */}

package/src/SegmentBar.tsx

@@ -7,34 +7,37 @@ import { useMeasuredWidth } from './useMeasuredWidth.ts';
 export interface SegmentBarPart {
     /* Its length, in the unit of the bar's `range`. */
     value: number;
-    /* Where it starts, in the unit of the bar's `range`. Defaults to the end of the part before, or 0 for the first;
-       a later start leaves the stretch in between empty. Parts stay in order. */
+
+    /* Defaults to the end of the part before, or 0 for the first; a later start leaves the stretch in between empty. Parts stay in order. */
     start?: number;
+
     /* Drawn in the part where there is room for it, and always read by a screen reader. */
     label?: string;
-    /* Any CSS color, such as `var(--positive)`, in place of the theme's. It wins over the accent of `current`. */
+
+    /* Any CSS color. It wins over the accent of `current`. */
     color?: string;
-    /* The part a person is at, such as the section under the playhead. */
+
     current?: boolean;
 }
 
 export interface SegmentBarProps {
     parts: readonly SegmentBarPart[];
-    /* The stretch the bar shows, in the unit of the parts: the rest of a whole, or the visible part of a zoomed timeline.
-       Defaults to 0 up to the end of the last part. */
+
+    /* Defaults to 0 up to the end of the last part. */
     range?: readonly [from: number, to: number];
-    /* `md` draws each label in its part, `sm` is a thin bar that shows its labels only as a tooltip. */
+
+    /* `sm` is a thin bar that shows its labels only as a tooltip. */
     size?: 'sm' | 'md';
-    /* Makes every part a button, which calls this with its index in `parts`. */
+
+    /* Makes every part a button. */
     onSelect?(index: number): void;
-    /* The accessible name of the whole. */
+
     label?: string;
     className?: string;
     ref?: Ref<HTMLOListElement>;
 }
 
-/* A whole split into parts, each as wide as it lasts, so they compare at a glance. A part starts exactly at its
-   place; the gap between two parts that touch comes out of the one before. */
+/* A part starts exactly at its place; the gap between two parts that touch comes out of the one before. */
 export function SegmentBar({ parts, range, size = 'md', onSelect, label, className, ref }: SegmentBarProps) {
     const [measure, width] = useMeasuredWidth();
     const rootRef = mergeRefs(ref, measure);
@@ -42,11 +45,14 @@ export function SegmentBar({ parts, range, size = 'md', onSelect, label, classNa
     const [cut, setCut] = useState<readonly boolean[]>([]);
 
     let end = 0;
+
     const placed = parts.map((part, index) => {
         const from = part.start ?? end;
         end = from + Math.max(0, part.value);
+
         return { part, index, from, to: end };
     });
+
     const [from, to] = range ?? [0, end];
     const span = to - from;
     const visible = span > 0 ? placed.filter((placement) => placement.to > from && placement.from < to) : [];
@@ -73,6 +79,7 @@ export function SegmentBar({ parts, range, size = 'md', onSelect, label, classNa
                 const next = visible[i + 1];
                 // Less than a pixel apart they touch, whatever rounding the caller's starts carry.
                 const touches = next !== undefined && ((next.from - partTo) / span) * width < 1;
+
                 const fill = clsx(
                     'flex size-full min-w-0 items-center',
                     size === 'sm' ? 'rounded-full' : 'rounded-sm px-1.5 text-left text-xs',
@@ -81,6 +88,7 @@ export function SegmentBar({ parts, range, size = 'md', onSelect, label, classNa
                     !part.current && size === 'md' && 'text-text-muted',
                     onSelect !== undefined && 'cursor-pointer hover:opacity-80'
                 );
+
                 const text = (
                     <span
                         ref={(element) => {
@@ -91,7 +99,9 @@ export function SegmentBar({ parts, range, size = 'md', onSelect, label, classNa
                         {part.label}
                     </span>
                 );
+
                 const look = { className: fill, style: { backgroundColor: part.color }, 'aria-current': part.current ? true : undefined };
+
                 const body =
                     onSelect === undefined ? (
                         <span {...look}>{text}</span>
@@ -100,6 +110,7 @@ export function SegmentBar({ parts, range, size = 'md', onSelect, label, classNa
                             {text}
                         </button>
                     );
+
                 return (
                     <li
                         key={index}

package/src/Segmented.tsx

@@ -9,7 +9,8 @@ export interface SegmentedOption<T extends string> {
     id: T;
     label: string;
     icon?: LucideIcon;
-    /* Dims the option and takes it out of the tab order and the arrow keys; the rest of the group stays usable. */
+
+    /* Takes the option out of the tab order and the arrow keys; the rest of the group stays usable. */
     disabled?: boolean;
 }
 
@@ -17,15 +18,18 @@ export interface SegmentedProps<T extends string> {
     value: T;
     onValueChange(id: T): void;
     options: readonly SegmentedOption<T>[];
-    /* The accessible name of the group. */
     label: string;
     disabled?: boolean;
-    /* `vertical` stacks the options in a column as wide as its container, for labels too long to stand side by side. */
+
+    /* `vertical` is as wide as its container, for labels too long to stand side by side. */
     orientation?: 'horizontal' | 'vertical';
-    /* 32 pixels high at `md` and 28 at `sm`, the heights of `Input`, `Select` and `Button`. */
+
+    /* The heights of `Input`, `Select` and `Button`. */
     size?: 'md' | 'sm';
-    /* Draws every option with an icon as a square, the label as its accessible name and its tooltip. One without an icon keeps its label. */
+
+    /* An option with an icon draws as a square, its label as its accessible name and tooltip. One without an icon keeps its label. */
     iconOnly?: boolean;
+
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
@@ -35,10 +39,7 @@ const SIZE = {
     sm: { track: 'rounded-md', row: 'min-h-7', option: 'min-h-6 rounded-sm px-2.5 py-0.5', square: 'size-6 rounded-sm', icon: 12 }
 } as const;
 
-/*
- * One of a few options side by side in one sunken track, the picked one lifted out of it. A radio
- * group: one tab stop, and the arrows pick and focus the next option, around the ends.
- */
+/* A radio group: one tab stop, and the arrows pick and focus the next option, around the ends. */
 export function Segmented<T extends string>({
     value,
     onValueChange,
@@ -55,15 +56,17 @@ export function Segmented<T extends string>({
     const sizing = SIZE[size];
     const stop = segmentedStop(options, value);
 
-    function move(event: KeyboardEvent<HTMLButtonElement>, index: number) {
+    const move = (event: KeyboardEvent<HTMLButtonElement>, index: number): void => {
         const next = segmentedTarget(options, index, event.key);
+
         if (next === null) {
             return;
         }
+
         event.preventDefault();
         onValueChange(options[next]!.id);
         event.currentTarget.parentElement?.querySelectorAll<HTMLButtonElement>('[role="radio"]')[next]?.focus();
-    }
+    };
 
     return (
         <div
@@ -80,6 +83,7 @@ export function Segmented<T extends string>({
         >
             {options.map((option, index) => {
                 const square = iconOnly && option.icon !== undefined;
+
                 const button = (
                     <button
                         key={option.id}
@@ -100,6 +104,7 @@ export function Segmented<T extends string>({
                         {!square && option.label}
                     </button>
                 );
+
                 return square ? (
                     <Tooltip key={option.id} label={option.label} name>
                         {button}

package/src/Select.tsx

@@ -16,19 +16,25 @@ export interface SelectProps<T extends string> {
     value: T | null;
     onValueChange(value: T): void;
     items: SelectItem<T>[] | SelectGroup<T>[];
+
     /* The accessible name of the trigger; the row above it usually carries the visible one. */
     label: string;
+
     /* What the trigger shows while nothing is picked. */
     placeholder?: string;
+
     size?: 'sm' | 'md';
     variant?: 'outlined' | 'ghost';
     disabled?: boolean;
     align?: 'start' | 'end';
     truncateValue?: boolean;
+
     /* A search field above the options: `true` always, a number once the list has at least that many options. */
     searchable?: boolean | number;
+
     /* What the search field says while it is empty, and its accessible name. */
     searchPlaceholder?: string;
+
     className?: string;
     ref?: Ref<HTMLButtonElement>;
 }
@@ -41,10 +47,7 @@ function Row<T extends string>({ item, picked }: { item: SelectItem<T>; picked:
     );
 }
 
-/* The one select. A Base UI `Select` in the popup style the menus use, so a settings field and a
-   picker in a toolbar read the same. Base UI brings the keyboard along (arrows,
-   Home and End, typeahead, Enter, Escape), which a hand-rolled listbox would have to repeat.
-   A long list can ask for a search field, which swaps in a combobox with the same trigger and rows. */
+/* A long list can ask for a search field, which swaps in a combobox with the same trigger and rows. */
 export function Select<T extends string>(props: SelectProps<T>) {
     const { searchable, items } = props;
     const count = items.length > 0 && isGroup(items[0]!) ? (items as SelectGroup<T>[]).reduce((sum, group) => sum + group.items.length, 0) : items.length;

package/src/SelectSearch.tsx

@@ -32,13 +32,16 @@ export function SelectSearch<T extends string>({
     const flat = groups ? groups.flatMap((group) => group.items) : (items as SelectItem<T>[]);
     const byValue = new Map(flat.map((item) => [item.value, item]));
     const selected = value === null ? null : (byValue.get(value) ?? null);
+
     const comboboxItems = groups
         ? groups.map((group) => ({ value: group.label, items: group.items.map((item) => item.value) }))
         : flat.map((item) => item.value);
+
     const searchLabel = searchPlaceholder ?? t('select.search');
 
     const renderRow = (itemValue: T) => {
         const item = byValue.get(itemValue)!;
+
         return (
             <Combobox.Item key={item.value} className={rowClassName(item)} value={item.value} disabled={item.disabled}>
                 <RowContent item={item} picked={item.value === value} text={<span className="truncate">{item.label}</span>} />

package/src/ShortcutHints.tsx

@@ -15,35 +15,42 @@ const isSeen = (element: Element, rect: DOMRect): boolean => {
     if (rect.width === 0 || rect.height === 0 || rect.bottom <= 0 || rect.right <= 0 || rect.top >= window.innerHeight || rect.left >= window.innerWidth) {
         return false;
     }
+
     if (!element.checkVisibility({ opacityProperty: true, visibilityProperty: true })) {
         return false;
     }
+
     const hit = document.elementFromPoint((rect.left + rect.right) / 2, (rect.top + rect.bottom) / 2);
+
     return hit !== null && element.contains(hit);
 };
 
 const measureHints = (apple: boolean): PlacedHint[] => {
     const viewport = { width: window.innerWidth, height: window.innerHeight };
     const hints: PlacedHint[] = [];
+
     for (const [element, target] of shortcutHintTargets()) {
         const rect = element.getBoundingClientRect();
+
         if (!isSeen(element, rect)) {
             continue;
         }
+
         const placement = placeHint(rect, viewport);
+
         hints.push({
             id: target.id,
             text: formatShortcut(target.shortcut, apple),
             style: { left: placement.left, right: placement.right, top: placement.top, translate: `${placement.translateX} ${placement.translateY}` }
         });
     }
+
     return hints;
 };
 
 /*
- * Every visible button's shortcut, under the button, for as long as the modifier is held on its own.
- * Mounted once; the listener sits on the window in the capture phase so a terminal that keeps a key to
- * itself still takes the hints down. An embedded page (`<webview>`) has the keyboard to itself and shows none.
+ * The listener sits on the window in the capture phase so a terminal that keeps a key to itself still
+ * takes the hints down. An embedded page (`<webview>`) has the keyboard to itself and shows none.
  */
 export function ShortcutHints() {
     const [shown, setShown] = useState(false);
@@ -53,15 +60,20 @@ export function ShortcutHints() {
     useEffect(() => {
         const hold = new ModifierHold(isApplePlatform(), setShown);
         holdRef.current = hold;
+
         const onKeyDown = (e: KeyboardEvent): void => hold.keyDown(e);
+
         const onKeyUp = (e: KeyboardEvent): void => hold.keyUp(e);
+
         // A click or a zoom with the modifier down is a gesture, not someone looking for a shortcut.
         const cancel = (): void => hold.cancel();
+
         window.addEventListener('keydown', onKeyDown, true);
         window.addEventListener('keyup', onKeyUp, true);
         window.addEventListener('pointerdown', cancel, true);
         window.addEventListener('wheel', cancel, { capture: true, passive: true });
         window.addEventListener('blur', cancel);
+
         return () => {
             window.removeEventListener('keydown', onKeyDown, true);
             window.removeEventListener('keyup', onKeyUp, true);
@@ -77,30 +89,39 @@ export function ShortcutHints() {
         if (!shown) {
             return;
         }
+
         const apple = isApplePlatform();
         let frame = 0;
         let last = '';
+
         const measure = (): void => {
             // Focus that moved into a page takes the key-up with it, so the embedder never hears the modifier let go.
             if (document.activeElement?.tagName === 'WEBVIEW') {
                 holdRef.current?.cancel();
+
                 return;
             }
+
             const next = measureHints(apple);
             const signature = JSON.stringify(next);
+
             if (signature !== last) {
                 last = signature;
                 setHints(next);
             }
+
             frame = requestAnimationFrame(measure);
         };
+
         measure();
+
         return () => cancelAnimationFrame(frame);
     }, [shown]);
 
     if (!shown) {
         return null;
     }
+
     return createPortal(
         <div aria-hidden className="pointer-events-none fixed inset-0 z-(--z-shortcut-hints)">
             {hints.map((hint) => (

package/src/Skeleton.tsx

@@ -4,6 +4,7 @@ import clsx from 'clsx';
 export interface SkeletonProps {
     /* The width, and a height other than the one line of 16px. */
     className?: string;
+
     ref?: Ref<HTMLSpanElement>;
 }
 

package/src/Slider.tsx

@@ -10,18 +10,21 @@ export interface SliderProps {
     min: number;
     max: number;
     step?: number;
+
     /* Places after the separator, always shown. Defaults to the places `step` is written with. */
     decimals?: number;
+
     /* Printed right after the number, such as `px` or `%`. */
     unit?: string;
+
     /* Shown above the track and read as the slider's name. */
     label: string;
+
     disabled?: boolean;
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
 
-/* A number picked along a range: the label and the value on one line, the track under them. */
 export function Slider({ value, onValueChange, min, max, step = 1, decimals = placesOf(step), unit, label, disabled, className, ref }: SliderProps) {
     const labelId = useId();
     const reading = formatFixed(value, decimals);

package/src/SlidingColumn.tsx

@@ -9,48 +9,50 @@ const TRANSITION_MS = 200;
 
 export interface SlidingColumnProps {
     open: boolean;
+
     /* Already clamped by the caller, which knows what has to stay beside it (`clampColumnSize`). */
     width: number;
+
     /* Space before the surface, in pixels. Replaces the border and carries the resize handle. */
     gap?: number;
+
     bounds: { min: number; max(): number };
     onWidthChange(width: number): void;
-    /*
-     * The width lands without the motion, for a column whose place is being restored as the page
-     * loads; only what a person does afterwards should animate.
-     */
+
+    /* For a column whose place is restored as the page loads; only what a person does afterwards should animate. */
     instant?: boolean;
-    /*
-     * The column takes the keyboard itself, for a panel with shortcuts of its own. It is focusable
-     * by script alone, so opening something in it hands it the keys without a click first.
-     */
+
+    /* For a panel with shortcuts of its own. Focusable by script alone, so opening something in it hands it the keys without a click. */
     body?: {
         ref: RefObject<HTMLDivElement | null>;
         onKeyDown(event: ReactKeyboardEvent<HTMLDivElement>): void;
     };
+
     className?: string;
+
     /* The outer column, for bounds that measure what is beside it rather than the whole window. */
     ref?: Ref<HTMLElement>;
+
     children?: ReactNode;
 }
 
 /*
- * A panel that slides in and out along the right edge. The outer column is 0 wide and inert while
- * closed; the contents sit in an inner column of the stored width, so they do not reflow while it
- * moves, and they stay mounted until the slide is over, so a close plays out. The left edge is the
- * drag handle.
+ * The contents sit in an inner column of the stored width, so they do not reflow while the outer one
+ * moves, and stay mounted until the slide is over, so a close plays out.
  */
 export function SlidingColumn({ open, width, gap = 0, bounds, onWidthChange, instant = false, body, className, ref, children }: SlidingColumnProps) {
     /* Closed and done animating. */
     const [settled, setSettled] = useState(!open);
-    /* A width that lands without a transition fires no `transitionend`, so the motion it would have
-       ended is over in the same commit that starts it. */
+
+    /* A width that lands without a transition fires no `transitionend`. */
     if (instant && settled !== !open) {
         setSettled(!open);
     }
+
     const present = open || !settled;
     const column = useRef<HTMLElement>(null);
     const spacing = Math.max(0, Math.round(gap));
+
     const { startResize } = useColumnResize(column, {
         min: bounds.min + spacing,
         max: () => bounds.max() + spacing,
@@ -63,8 +65,10 @@ export function SlidingColumn({ open, width, gap = 0, bounds, onWidthChange, ins
         if (open || settled) {
             return;
         }
+
         // Reduced motion and a hidden tab paint no width change, so no `transitionend` arrives.
         const timer = window.setTimeout(() => setSettled(true), TRANSITION_MS + 50);
+
         return () => {
             window.clearTimeout(timer);
         };

package/src/Spinner.tsx

@@ -6,6 +6,7 @@ const DOTS = [0, 1, 2];
 export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'children'> {
     /* In pixels, on the steps of an icon: 12, 14, 16 or 20. */
     size?: number;
+
     /* What runs, read by a screen reader. Left out where the words beside it already say so, which hides the spinner as an icon is hidden. */
     label?: string;
 }

package/src/SplitButton.tsx

@@ -10,28 +10,28 @@ import { Tooltip } from './Tooltip.tsx';
 export interface SplitButtonProps extends Omit<ComponentProps<'button'>, 'ref'> {
     variant?: ButtonVariant;
     size?: ButtonSize;
+
     /* The hint on the action half. */
     tooltip?: ReactNode;
-    /* The rows of the menu the chevron opens: `Menu.Item`, `Menu.Separator` and the rest of a menu's parts. */
+
+    /* The rows of the menu the chevron opens. */
     menu: ReactNode;
+
     /* The accessible name of the chevron, and its hint unless `menuTooltip` says something else. */
     menuLabel: string;
+
     menuTooltip?: ReactNode;
     menuDisabled?: boolean;
-    /* Where the menu lines up under the whole control. */
     menuAlign?: MenuPopupProps['align'];
-    /* A width or a layout of the menu's own, such as `w-72`. */
     menuClassName?: string;
+
     /* On the box around both halves; every other prop goes to the action half. */
     className?: string;
+
     ref?: ComponentProps<'span'>['ref'];
 }
 
-/*
- * A primary action and a chevron that opens a menu of related ones, drawn as one button with a short
- * line between the halves. Each half is a button of its own, so each takes the focus, can be disabled
- * and carries its own hint; the menu hangs under the whole control.
- */
+/* Each half is a button of its own, so each takes the focus, can be disabled and carries its own hint; the menu hangs under the whole control. */
 export function SplitButton({
     variant = 'secondary',
     size = 'md',

package/src/Stepper.tsx

@@ -13,10 +13,13 @@ export interface StepperProps {
     min: number;
     max: number;
     step: number;
+
     /* Places after the separator, always shown: `1,0`, `1,5`. Defaults to the places `step` is written with. */
     decimals?: number;
+
     /* Printed right after the number, such as `px` or `%`. */
     unit?: string;
+
     label: string;
     className?: string;
     ref?: Ref<HTMLDivElement>;
@@ -25,16 +28,19 @@ export interface StepperProps {
 /* A number between minus and plus, in one sunken group so the three read as a single control. */
 export function Stepper({ value, onValueChange, min, max, step, decimals = placesOf(step), unit, label, className, ref }: StepperProps) {
     const { t } = useTranslation('ui');
+
     const reading = (amount: number) => (
         <>
             {formatFixed(amount, decimals)}
             {unit && <span className="text-text-muted">{unit}</span>}
         </>
     );
+
     const nudge = (direction: -1 | 1): void => {
         const next = Math.round((value + direction * step) * 100) / 100;
         onValueChange(Math.min(max, Math.max(min, next)));
     };
+
     return (
         <ButtonGroup
             ref={ref}

package/src/Switch.tsx

@@ -5,8 +5,10 @@ import { Switch as BaseSwitch } from '@base-ui/react/switch';
 export interface SwitchProps {
     checked: boolean;
     onCheckedChange(checked: boolean): void;
+
     /* The accessible name; the row it sits in usually carries the visible one. */
     label: string;
+
     disabled?: boolean;
     className?: string;
     ref?: Ref<HTMLButtonElement>;

package/src/TextMenu.tsx

@@ -15,11 +15,7 @@ export type TextMenuProps = ComponentProps<'div'> & {
     items?: ReactNode;
 };
 
-/*
- * A block of text and the menu that belongs to it: Copy for what is selected inside it, Select all
- * for the whole of it, on Cmd+A as well. Anywhere text can be selected a right-click has to offer
- * to copy it, and an app that draws every menu itself offers nothing at all without one of these.
- */
+/* An app that draws every menu itself offers no Copy on a right-click without one of these. */
 export function TextMenu({ children, items, ref, ...rest }: TextMenuProps) {
     const { t } = useTranslation('ui');
     const host = useRef<HTMLDivElement>(null);
@@ -30,6 +26,7 @@ export function TextMenu({ children, items, ref, ...rest }: TextMenuProps) {
         if (!matchesShortcut(EDIT_SHORTCUTS.selectAll, event, isApplePlatform())) {
             return;
         }
+
         event.preventDefault();
         selectAllWithin(host.current);
     };

package/src/Tile.tsx

@@ -6,19 +6,15 @@ import type { Shortcut } from './shortcut.ts';
 export interface TileProps extends Omit<ComponentProps<'button'>, 'title'> {
     icon: ReactNode;
     title: string;
-    /* One short line under the title: where it acts, or why it waits. */
     description?: ReactNode;
     shortcut?: Shortcut;
+
     /* The one tile a screen leads with. */
     primary?: boolean;
-    /* `sm` for a narrow column like the sidebar. */
+
     size?: 'md' | 'sm';
 }
 
-/*
- * One thing to start with, as a card that is a button: a start screen and the empty places of an app
- * use it, so a place to begin looks the same wherever it is offered.
- */
 export function Tile({ icon, title, description, shortcut, primary = false, size = 'md', className, type = 'button', ...rest }: TileProps) {
     return (
         <button