@scalewing/react 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @scalewing/react
 
+## 1.26.0
+
+### Minor Changes
+
+- e484799: `DescriptionList` and `DescriptionItem` (with `DescriptionListProps` and `DescriptionItemProps`): terms paired with what each says, one per row (`docs/requests/teisoro-description-list.md`, Teisoro F-006-S03).
+
+  - A `dl` of items, each a `div` grouping a `dt` (`term`) with its `dd` (`children`); the list and each item take their own HTML attributes and `className`.
+  - From `md` up the items share the list's two columns (`subgrid`): the term column as wide as the widest term, up to 40% of the list, then the detail. Every row aligns to its top, a hairline (`--sw-color-border`, `CanvasText` in forced colors) divides the rows, and the list is flush above its first row and below its last.
+  - Below `md` each term sits over its detail.
+  - A term and a detail are columns of lines: each child is its own line with its own line height, so a caption term starts level with a caption detail; each is as wide as its content unless it sets its own width (a `Progress` fills the detail), and long unbreakable words wrap. Wrap inline content in one element.
+  - New generated classes `sw-description-list`, `sw-description-item`, `sw-description-term` and `sw-description-detail`. No new tokens or dependencies.
+
+## 1.25.0
+
+### Minor Changes
+
+- 34131f3: `InfoTip` and `InfoTipProps`: a toggletip, a ghost icon-only `Button` whose only job is to show its tip (`docs/requests/teisoro-tooltip.md`, 2026-10-09 follow-up, Teisoro F-006-S11). Since 1.22.0 a tap on a `Button` presses it and never opens its `Tooltip`, so an ⓘ beside a figure could not show its help on a touch screen.
+
+  - `label` (the button's name), `content` (the tip, plain text), `children` (the decorative glyph), `size` (a Button size; `md` by default, and 44 px on a coarse pointer at every size).
+  - Hover and a visible focus show the tip as `Tooltip` does. A press (a tap, a click, Enter or Space) shows it and keeps it shown when the pointer leaves; the next press, Escape, blur or a press outside hides it.
+  - The tip is the button's description (`aria-describedby`). A press also puts it in a visually hidden polite live region (`role="status"`), so a screen reader user who presses the button hears it. Every InfoTip renders that `role="status"` element, empty until a press, and while a press holds the tip open its text is in the page twice (the bubble and the region): a test that finds a `status` or the tip's text should scope its query.
+  - `type="button"`: it never submits a form. An empty `label` or `content` throws a `RangeError`.
+  - New generated class `sw-info-tip` (the square icon button, shared with `sw-calendar-button`, whose rules are equivalent: same declarations and specificity, one block reordered).
+
+  `Tooltip`'s behavior is unchanged for every other trigger: a tap on a control still does what the control does and leaves its tooltip closed. No new tokens or dependencies.
+
 ## 1.24.0
 
 ### Minor Changes

package/README.md

@@ -20,7 +20,10 @@ import {
   Spinner,
   Progress,
   Tooltip,
+  InfoTip,
   Separator,
+  DescriptionList,
+  DescriptionItem,
   DenominationGrid,
   FilterChips,
   Grid,
@@ -291,10 +294,45 @@ A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `
 
 `Progress` shows a known value between zero and a positive maximum. It uses native progressbar semantics and displays the value and maximum beside the localized label. Invalid bounds throw instead of silently clamping. Optional `tone` is `accent`, `success`, or `danger`. `showCount={false}` hides the visible `value / max` count when the page shows its own count caption, so the count appears once; the progress bar still exposes its value and maximum.
 
-`Tooltip` adds supplementary plain-text help to one labelled, focusable trigger, or names an icon-only one (`relationship="label"`, below). Supply localized `content` and an existing trigger element; by default it has its own accessible name. It opens on hover or on a visible focus (`:focus-visible`: the keyboard, not the focus a click or a tap gives), closes on pointer leave, blur, Escape, or outside touch, and a tap toggles it only on a trigger that does nothing else on a tap, such as a focusable badge; a tap on a control (a button, a link, a form control or its label, an editable region, an element with a widget role, or anything inside one) does what the control does. The bubble is placed beside its trigger on the top layer while it shows and stays a `space-2` inset inside the screen. Keep required instructions visible outside the tooltip. `disabled` turns the tooltip off, not its trigger: the trigger stays mounted, enabled and focusable, and there is no tooltip, no `aria-describedby` from it, and Escape is left to the page. Use it when what the tooltip says is visible at some widths, such as text shown only from `md` up, instead of rendering the trigger with and without a `Tooltip`, which mounts a new trigger and drops its focus. Focus, hover and touch are still followed, so a trigger that still has focus, the pointer or an open touch toggle shows the tooltip as soon as it is enabled again (Escape pressed while disabled reaches the page and does not stop that). `disabled` must be the same in the server render and the first client render, or hydration mismatches; read a breakpoint through a hydration-safe store, such as `useSyncExternalStore` with a server snapshot. `relationship="label"` makes the tooltip its trigger's name instead of its description, for an icon-only control whose tooltip says what it is: the trigger gets `aria-labelledby` (after its own, if any) and no `aria-describedby` from the tooltip, so the text is read once. The tooltip stays in the page, hidden, so it names the trigger while it is not shown, and it wins over an `aria-label`. While `disabled` there is no tooltip to name the trigger, so give the trigger its own name for that state: visible text, such as a label shown only from `md` up, or an `aria-label`. Do not use `relationship="label"` while the trigger shows visible text that differs from `content`: the tooltip would replace that visible label as the name (WCAG 2.5.3, label in name). The default, `relationship="description"`, is the supplementary help above. `relationship` must also be the same in the server render and the first client render.
+`Tooltip` adds supplementary plain-text help to one labelled, focusable trigger, or names an icon-only one (`relationship="label"`, below). Supply localized `content` and an existing trigger element; by default it has its own accessible name. It opens on hover or on a visible focus (`:focus-visible`: the keyboard, not the focus a click or a tap gives), closes on pointer leave, blur, Escape, or outside touch, and a tap on a control (a button, a link, a form control or its label, an editable region, an element with a widget role, or anything inside one) does what the control does and leaves the tooltip closed, so on a touch screen a `Tooltip` on a `Button` is never shown. For an icon-only hint whose button does nothing but show it, such as an ⓘ beside a figure, use `InfoTip` (below), which a tap, a click, Enter or Space opens; do not make a non-control focusable to get a tap. A tap still toggles a `Tooltip` whose trigger does nothing else on a tap, such as an existing focusable badge. The bubble is placed beside its trigger on the top layer while it shows and stays a `space-2` inset inside the screen. Keep required instructions visible outside the tooltip. `disabled` turns the tooltip off, not its trigger: the trigger stays mounted, enabled and focusable, and there is no tooltip, no `aria-describedby` from it, and Escape is left to the page. Use it when what the tooltip says is visible at some widths, such as text shown only from `md` up, instead of rendering the trigger with and without a `Tooltip`, which mounts a new trigger and drops its focus. Focus, hover and touch are still followed, so a trigger that still has focus, the pointer or an open touch toggle shows the tooltip as soon as it is enabled again (Escape pressed while disabled reaches the page and does not stop that). `disabled` must be the same in the server render and the first client render, or hydration mismatches; read a breakpoint through a hydration-safe store, such as `useSyncExternalStore` with a server snapshot. `relationship="label"` makes the tooltip its trigger's name instead of its description, for an icon-only control whose tooltip says what it is: the trigger gets `aria-labelledby` (after its own, if any) and no `aria-describedby` from the tooltip, so the text is read once. The tooltip stays in the page, hidden, so it names the trigger while it is not shown, and it wins over an `aria-label`. While `disabled` there is no tooltip to name the trigger, so give the trigger its own name for that state: visible text, such as a label shown only from `md` up, or an `aria-label`. Do not use `relationship="label"` while the trigger shows visible text that differs from `content`: the tooltip would replace that visible label as the name (WCAG 2.5.3, label in name). The default, `relationship="description"`, is the supplementary help above. `relationship` must also be the same in the server render and the first client render.
+
+`InfoTip` is a toggletip: a ghost icon-only `Button` whose only job is to show its tip, built on `Tooltip`'s bubble and placement. `label` is the button's accessible name and `content` its tip, plain text as `Tooltip`'s, both localized by the consumer; `children` is the decorative glyph (a Lucide `Info` with `aria-hidden`); `size` is a Button size, and the default `md` and every size on a coarse pointer are a square 44 px target. Hover and a visible focus show the tip as `Tooltip` does. A press of the button (a tap, a click, Enter or Space) shows it and keeps it shown when the pointer leaves, and the next press hides it; Escape (taken only while the tip shows), blur and a press outside also hide it. The tip is the button's description (`aria-describedby`), read once on focus; a press also puts it in a visually hidden polite live region (`role="status"`, empty until a press opens the tip and emptied when it closes), so a screen reader user who presses the button hears it even with descriptions or hints turned off. The button is `type="button"` and never submits a form, and the ref reaches it. An empty `label` or `content` throws a `RangeError`. There is no `disabled`: where the tip is shown as text instead, render no `InfoTip`.
+
+```tsx
+<Inline gap={1}>
+  <Text>Expected waders: 128</Text>
+  <InfoTip
+    content="Counted at the last high tide, before the hides opened"
+    label="About the expected waders"
+  >
+    <Info aria-hidden size={16} />
+  </InfoTip>
+</Inline>
+```
 
 `Separator` divides sections with a token-colored line. It is horizontal by default; use `orientation="vertical"` in a flex row. Set `decorative` when the line only supports layout so assistive technology ignores it.
 
+`DescriptionList` pairs terms with what each says, one `DescriptionItem` per row: a `dl` whose items each group a `dt` (`term`) with its `dd` (`children`). From `md` up the term sits in a start column as wide as the widest term, up to 40% of the list, and the detail beside it; every row aligns to its top, so a term and its detail's first line start level, and a hairline divides the rows, with no space above the first row or below the last. Below `md` each term sits over its detail. The list sets only the layout: pass your own `Text` for the term and the detail. Each child of a term or a detail is its own line with its own line height (a column), as wide as its content unless it sets its own width (a `Progress` fills the detail; a `Field` keeps its input's width): wrap inline content, such as words and a link on one line, in one element such as an `Inline`. Long unbreakable words wrap inside their column. A `dl` has no ARIA role, so name a list with a visible heading, and `aria-labelledby` on the `section` around it, rather than an `aria-label` on the list.
+
+```tsx
+<DescriptionList>
+  <DescriptionItem
+    term={
+      <Text variant="caption" color="muted">
+        Wetland
+      </Text>
+    }
+  >
+    <Inline align="start" gap={2} wrap>
+      <Text variant="data">12 herons</Text>
+      <Text variant="caption" color="muted">
+        Recounted
+      </Text>
+    </Inline>
+  </DescriptionItem>
+</DescriptionList>
+```
+
 `Card` defaults to `glass`; `outlined` and `elevated` are solid surfaces, and `filled` is a quiet `--sw-color-subtle` fill with no border for plain information apart from pressable rows.
 
 `--sw-color-accentSubtle` is the accent tint from `@scalewing/tokens`: a quiet fill behind accent text or glyphs that keeps 4.5:1. The stylesheet and every palette file set it, and a palette that moves the accent or surface retints it.

package/dist/components/DescriptionList.d.ts

@@ -0,0 +1,28 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'children'> & {
+    /** The list's `DescriptionItem`s. */
+    children: ReactNode;
+};
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export declare function DescriptionList({ children, className, ...rest }: DescriptionListProps): import("react").JSX.Element;
+export type DescriptionItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /**
+     * What the row describes, such as a name; the consumer's own `Text`. Each
+     * child of the term, and of the detail, is its own line.
+     */
+    term: ReactNode;
+    /**
+     * What the term says: text, a link, or several lines. Each child is its
+     * own line, as wide as its content unless it sets its own width (a
+     * `Progress` fills the detail); wrap words and a link that share a line
+     * in one element such as `Inline`.
+     */
+    children: ReactNode;
+};
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export declare function DescriptionItem({ term, children, className, ...rest }: DescriptionItemProps): import("react").JSX.Element;

package/dist/components/DescriptionList.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export function DescriptionList({ children, className, ...rest }) {
+    return (_jsx("dl", { className: cx('sw-description-list', className), ...rest, children: children }));
+}
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export function DescriptionItem({ term, children, className, ...rest }) {
+    return (_jsxs("div", { className: cx('sw-description-item', className), ...rest, children: [_jsx("dt", { className: "sw-description-term", children: term }), _jsx("dd", { className: "sw-description-detail", children: children })] }));
+}

package/dist/components/InfoTip.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+import { type ButtonSize } from './Button.js';
+export type InfoTipProps = {
+    /**
+     * The button's accessible name, such as "About the expected balance".
+     * Localized by the consumer.
+     */
+    label: string;
+    /**
+     * The tip: plain text, as `Tooltip`'s `content`. It is the button's
+     * description, and a press also says it once in a polite live region.
+     */
+    content: string;
+    /** The glyph, such as a Lucide `Info`; decorative, the label names it. */
+    children: ReactNode;
+    /** A Button size; md (default) is 44 px, and a coarse pointer always gets 44 px. */
+    size?: ButtonSize;
+};
+/**
+ * A toggletip: a ghost icon-only button whose only job is to show its tip.
+ * Hover and a visible focus show it as `Tooltip` does; a press (a tap, a
+ * click, Enter or Space) shows it and keeps it shown until the next press,
+ * Escape, blur or a press outside. The button never submits a form. The ref
+ * reaches the `<button>`.
+ */
+export declare const InfoTip: import("react").ForwardRefExoticComponent<InfoTipProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/InfoTip.js

@@ -0,0 +1,19 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { Button } from './Button.js';
+import { TooltipAnchor } from './tooltip/TooltipAnchor.js';
+/** The press is the anchor's: it toggles the tip on the button's click. */
+function pressShowsTheTip() { }
+/**
+ * A toggletip: a ghost icon-only button whose only job is to show its tip.
+ * Hover and a visible focus show it as `Tooltip` does; a press (a tap, a
+ * click, Enter or Space) shows it and keeps it shown until the next press,
+ * Escape, blur or a press outside. The button never submits a form. The ref
+ * reaches the `<button>`.
+ */
+export const InfoTip = forwardRef(function InfoTip({ children, content, label, size = 'md' }, ref) {
+    if (typeof label !== 'string' || label.trim() === '')
+        throw new RangeError('label must be non-empty text');
+    return (_jsx(TooltipAnchor, { content: content, pressToggles: true, trigger: _jsx(Button, { "aria-label": label, className: "sw-info-tip", onPress: pressShowsTheTip, ref: ref, size: size, type: "button", variant: "ghost", children: children }) }));
+});

package/dist/components/Tooltip.d.ts

@@ -28,4 +28,9 @@ export type TooltipProps = {
     relationship?: TooltipRelationship;
     trigger: ReactElement<TooltipTriggerAria>;
 };
+/**
+ * Supplementary help for a trigger that has its own name, or the name of an
+ * icon-only trigger (`relationship="label"`). For a glyph whose only job is
+ * to show its help, use `InfoTip`, which a press opens.
+ */
 export declare function Tooltip({ content, disabled, relationship, trigger, }: TooltipProps): import("react").JSX.Element;

package/dist/components/Tooltip.js

@@ -1,62 +1,11 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, useEffect, useId, useRef, useState, } from 'react';
-import { focusIsVisible, tapActs } from './tooltip/tooltip-open.js';
-import { useTooltipPlacement } from './tooltip/use-tooltip-placement.js';
-import { tooltipTriggerAria, } from './tooltip-trigger-aria.js';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TooltipAnchor } from './tooltip/TooltipAnchor.js';
+/**
+ * Supplementary help for a trigger that has its own name, or the name of an
+ * icon-only trigger (`relationship="label"`). For a glyph whose only job is
+ * to show its help, use `InfoTip`, which a press opens.
+ */
 export function Tooltip({ content, disabled = false, relationship = 'description', trigger, }) {
-    if (!content.trim())
-        throw new RangeError('content must not be empty');
-    // `open` follows focus, hover and touch even while disabled; `shown` is
-    // what the page gets.
-    const [open, setOpen] = useState(false);
-    const shown = open && !disabled;
-    const id = useId();
-    const wrapperRef = useRef(null);
-    const tooltipRef = useRef(null);
-    useTooltipPlacement(shown, tooltipRef, wrapperRef);
-    const triggerAria = tooltipTriggerAria(trigger.props, disabled ? undefined : id, relationship);
-    useEffect(() => {
-        if (!open)
-            return;
-        function dismissOutside(event) {
-            if (event.target instanceof Node &&
-                !wrapperRef.current?.contains(event.target))
-                setOpen(false);
-        }
-        document.addEventListener('pointerdown', dismissOutside);
-        return () => document.removeEventListener('pointerdown', dismissOutside);
-    }, [open]);
-    return (_jsxs("span", { className: "sw-tooltip-anchor", onBlurCapture: (event) => {
-            if (!event.currentTarget.contains(event.relatedTarget))
-                setOpen(false);
-        }, onFocusCapture: (event) => {
-            // A click or a tap focuses the trigger too; only a visible focus
-            // (the keyboard) opens the tooltip, so a clicked control does not
-            // keep its help shown until the focus moves.
-            if (focusIsVisible(event.target))
-                setOpen(true);
-        }, onKeyDownCapture: (event) => {
-            // Escape hides a visible tooltip and nothing else, so a surrounding
-            // Dialog does not also close. A hidden tooltip leaves Escape alone.
-            if (event.key !== 'Escape' || !shown)
-                return;
-            event.preventDefault();
-            setOpen(false);
-        }, onPointerEnter: (event) => {
-            if (event.pointerType === 'mouse' || event.pointerType === 'pen')
-                setOpen(true);
-        }, onPointerLeave: (event) => {
-            if (event.pointerType === 'mouse' || event.pointerType === 'pen')
-                setOpen(false);
-        }, onPointerDownCapture: (event) => {
-            if (event.pointerType !== 'touch')
-                return;
-            // A tap on a control does what the control does; only a trigger
-            // that does nothing else on a tap toggles its help.
-            if (tapActs(event.target, event.currentTarget))
-                setOpen(false);
-            else
-                setOpen((current) => !current);
-        }, ref: wrapperRef, children: [cloneElement(trigger, triggerAria), disabled ? null : (_jsx("span", { className: "sw-tooltip", hidden: !shown, id: id, ref: tooltipRef, role: "tooltip", children: content }))] }));
+    return (_jsx(TooltipAnchor, { content: content, disabled: disabled, relationship: relationship, trigger: trigger }));
 }

package/dist/components/tooltip/TooltipAnchor.d.ts

@@ -0,0 +1,19 @@
+import { type ReactElement } from 'react';
+import { type TooltipRelationship, type TooltipTriggerAria } from '../tooltip-trigger-aria.js';
+export type TooltipAnchorProps = {
+    content: string;
+    disabled?: boolean;
+    /**
+     * Internal, for `InfoTip`: a press of the trigger toggles the tooltip, and
+     * the tooltip a press opens is also said once in a polite live region.
+     */
+    pressToggles?: boolean;
+    relationship?: TooltipRelationship;
+    trigger: ReactElement<TooltipTriggerAria>;
+};
+/**
+ * The anchor `span` around a trigger and its tooltip: the bubble, its
+ * reference from the trigger, and what opens and closes it. `Tooltip` and
+ * `InfoTip` are this anchor; only `InfoTip` turns `pressToggles` on.
+ */
+export declare function TooltipAnchor({ content, disabled, pressToggles, relationship, trigger, }: TooltipAnchorProps): import("react").JSX.Element;

package/dist/components/tooltip/TooltipAnchor.js

@@ -0,0 +1,27 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cloneElement, useId, useRef } from 'react';
+import { tooltipTriggerAria, } from '../tooltip-trigger-aria.js';
+import { useTooltipOpen } from './use-tooltip-open.js';
+import { useTooltipPlacement } from './use-tooltip-placement.js';
+/**
+ * The anchor `span` around a trigger and its tooltip: the bubble, its
+ * reference from the trigger, and what opens and closes it. `Tooltip` and
+ * `InfoTip` are this anchor; only `InfoTip` turns `pressToggles` on.
+ */
+export function TooltipAnchor({ content, disabled = false, pressToggles = false, relationship = 'description', trigger, }) {
+    if (!content.trim())
+        throw new RangeError('content must not be empty');
+    const id = useId();
+    const wrapperRef = useRef(null);
+    const tooltipRef = useRef(null);
+    const { handlers, pressed, shown } = useTooltipOpen({
+        disabled,
+        pressToggles,
+        tooltipRef,
+        wrapperRef,
+    });
+    useTooltipPlacement(shown, tooltipRef, wrapperRef);
+    const triggerAria = tooltipTriggerAria(trigger.props, disabled ? undefined : id, relationship);
+    return (_jsxs("span", { className: "sw-tooltip-anchor", ref: wrapperRef, ...handlers, children: [cloneElement(trigger, triggerAria), disabled ? null : (_jsx("span", { className: "sw-tooltip", hidden: !shown, id: id, ref: tooltipRef, role: "tooltip", children: content })), pressToggles ? (_jsx("span", { className: "sw-sr-only", role: "status", children: pressed && shown ? content : null })) : null] }));
+}

package/dist/components/tooltip/use-tooltip-open.d.ts

@@ -0,0 +1,33 @@
+import { type FocusEvent, type KeyboardEvent, type MouseEvent, type PointerEvent as ReactPointerEvent, type RefObject } from 'react';
+export type TooltipOpenOptions = {
+    /** Whether the tooltip is enabled: only a shown tooltip takes Escape. */
+    disabled: boolean;
+    /**
+     * The toggletip: a press of the trigger (a tap, a click, Enter or Space)
+     * shows the tooltip and keeps it shown, and the next press hides it.
+     * Without it, a tap toggles only a trigger that does nothing else.
+     */
+    pressToggles: boolean;
+    tooltipRef: RefObject<HTMLElement | null>;
+    wrapperRef: RefObject<HTMLElement | null>;
+};
+/**
+ * Whether a tooltip is open, and the anchor's handlers that open and close
+ * it. `open` follows focus, hover, touch and presses even while disabled;
+ * `shown` is what the page gets. `pressed` is a tooltip a press opened: it
+ * stays open when the pointer leaves, until the next press, Escape, blur or
+ * a press outside the anchor.
+ */
+export declare function useTooltipOpen({ disabled, pressToggles, tooltipRef, wrapperRef, }: TooltipOpenOptions): {
+    handlers: {
+        onBlurCapture(event: FocusEvent<HTMLElement>): void;
+        onFocusCapture(event: FocusEvent<HTMLElement>): void;
+        onKeyDownCapture(event: KeyboardEvent<HTMLElement>): void;
+        onPointerEnter(event: ReactPointerEvent<HTMLElement>): void;
+        onPointerLeave(event: ReactPointerEvent<HTMLElement>): void;
+        onPointerDownCapture(event: ReactPointerEvent<HTMLElement>): void;
+        onClick: ((event: MouseEvent<HTMLElement>) => void) | undefined;
+    };
+    pressed: boolean;
+    shown: boolean;
+};

package/dist/components/tooltip/use-tooltip-open.js

@@ -0,0 +1,90 @@
+'use client';
+import { useEffect, useState, } from 'react';
+import { focusIsVisible, tapActs } from './tooltip-open.js';
+function isHover(event) {
+    return event.pointerType === 'mouse' || event.pointerType === 'pen';
+}
+/**
+ * Whether a tooltip is open, and the anchor's handlers that open and close
+ * it. `open` follows focus, hover, touch and presses even while disabled;
+ * `shown` is what the page gets. `pressed` is a tooltip a press opened: it
+ * stays open when the pointer leaves, until the next press, Escape, blur or
+ * a press outside the anchor.
+ */
+export function useTooltipOpen({ disabled, pressToggles, tooltipRef, wrapperRef, }) {
+    const [open, setOpen] = useState(false);
+    const [pressed, setPressed] = useState(false);
+    const shown = open && !disabled;
+    function close() {
+        setOpen(false);
+        setPressed(false);
+    }
+    useEffect(() => {
+        if (!open)
+            return;
+        function dismissOutside(event) {
+            if (event.target instanceof Node &&
+                !wrapperRef.current?.contains(event.target)) {
+                setOpen(false);
+                setPressed(false);
+            }
+        }
+        document.addEventListener('pointerdown', dismissOutside);
+        return () => document.removeEventListener('pointerdown', dismissOutside);
+    }, [open, wrapperRef]);
+    const handlers = {
+        onBlurCapture(event) {
+            if (!event.currentTarget.contains(event.relatedTarget))
+                close();
+        },
+        onFocusCapture(event) {
+            // A click or a tap focuses the trigger too; only a visible focus
+            // (the keyboard) opens the tooltip, so a clicked control does not
+            // keep its help shown until the focus moves.
+            if (focusIsVisible(event.target))
+                setOpen(true);
+        },
+        onKeyDownCapture(event) {
+            // Escape hides a visible tooltip and nothing else, so a surrounding
+            // Dialog does not also close. A hidden tooltip leaves Escape alone.
+            if (event.key !== 'Escape' || !shown)
+                return;
+            event.preventDefault();
+            close();
+        },
+        onPointerEnter(event) {
+            if (isHover(event))
+                setOpen(true);
+        },
+        onPointerLeave(event) {
+            if (isHover(event) && !pressed)
+                setOpen(false);
+        },
+        onPointerDownCapture(event) {
+            // A toggletip's tap is a press, which its click handles.
+            if (event.pointerType !== 'touch' || pressToggles)
+                return;
+            // A tap on a control does what the control does; only a trigger
+            // that does nothing else on a tap toggles its help.
+            if (tapActs(event.target, event.currentTarget))
+                setOpen(false);
+            else
+                setOpen((current) => !current);
+        },
+        onClick: pressToggles
+            ? (event) => {
+                // A press inside the bubble is not a press of the trigger.
+                if (event.target instanceof Node &&
+                    tooltipRef.current?.contains(event.target))
+                    return;
+                if (pressed)
+                    close();
+                else {
+                    setOpen(true);
+                    setPressed(true);
+                }
+            }
+            : undefined,
+    };
+    return { handlers, pressed, shown };
+}

package/dist/css/css-calendar-button.js

@@ -1,30 +1,10 @@
-import { buttonSizes } from '@scalewing/tokens';
-import { coarsePointerQuery, touchTarget } from './touch-target.js';
-/* Square at every Button size: as wide as the size's control height. */
-function squareRules() {
-    return buttonSizes
-        .map((size) => `.sw-button-${size}.sw-calendar-button { min-width: var(--sw-control-${size}-min-height); }`)
-        .join('\n');
-}
+import { iconButtonRules } from './css-icon-button.js';
 export function cssCalendarButtonClasses() {
-    return `.sw-button.sw-calendar-button {
-  flex: none;
-  padding-inline: 0;
-}
-
-${squareRules()}
+    return `${iconButtonRules('sw-calendar-button')}
 
 .sw-calendar-button:not(.sw-button-md) .sw-date-field-glyph {
   height: var(--sw-space-4);
   width: var(--sw-space-4);
-}
-
-/* A coarse pointer gets the full touch target at the smaller sizes too. */
-@media ${coarsePointerQuery} {
-  .sw-button.sw-calendar-button {
-    min-height: ${touchTarget};
-    min-width: ${touchTarget};
-  }
 }`;
 }
 export function calendarButtonClassCatalog() {

package/dist/css/css-components.js

@@ -20,8 +20,10 @@ import { cssTextClasses } from './css-text.js';
 import { cssSpinnerClasses } from './css-spinner.js';
 import { cssProgressClasses } from './css-progress.js';
 import { cssTooltipClasses } from './css-tooltip.js';
+import { cssInfoTipClasses } from './css-info-tip.js';
 import { cssSeparatorClasses } from './css-separator.js';
 import { cssStatTileClasses } from './css-stat-tile.js';
+import { cssDescriptionListClasses } from './css-description-list.js';
 import { cssTabsClasses } from './css-tabs.js';
 import { cssResponsiveClasses } from './css-responsive.js';
 import { cssFilterChipsClasses } from './css-filter-chips.js';
@@ -144,10 +146,14 @@ ${cssProgressClasses()}
 
 ${cssTooltipClasses()}
 
+${cssInfoTipClasses()}
+
 ${cssSeparatorClasses()}
 
 ${cssStatTileClasses()}
 
+${cssDescriptionListClasses()}
+
 ${cssTabsClasses()}
 
 ${cssFilterChipsClasses()}

package/dist/css/css-description-list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The description list: a two-column grid whose items share its columns
+ * (`subgrid`), so every term starts the same column and every detail the
+ * next. The term column fits the widest term up to 40% of the list. A
+ * hairline divides the rows, the list sits flush with no space above the
+ * first row or below the last, and each row aligns to its top. Below `md`
+ * a term sits over its detail. A term and a detail are columns of lines:
+ * each child is its own line with its own line height, so a caption term
+ * starts level with a caption detail instead of on the list's taller line.
+ */
+export declare function cssDescriptionListClasses(): string;
+export declare function descriptionListClassCatalog(): string[];

package/dist/css/css-description-list.js

@@ -0,0 +1,63 @@
+import { breakpointQuery } from './breakpoints.js';
+/**
+ * The description list: a two-column grid whose items share its columns
+ * (`subgrid`), so every term starts the same column and every detail the
+ * next. The term column fits the widest term up to 40% of the list. A
+ * hairline divides the rows, the list sits flush with no space above the
+ * first row or below the last, and each row aligns to its top. Below `md`
+ * a term sits over its detail. A term and a detail are columns of lines:
+ * each child is its own line with its own line height, so a caption term
+ * starts level with a caption detail instead of on the list's taller line.
+ */
+export function cssDescriptionListClasses() {
+    return `.sw-description-list {
+  column-gap: var(--sw-space-4);
+  display: grid;
+  grid-template-columns: fit-content(40%) minmax(0, 1fr);
+  margin: 0;
+  min-width: 0;
+}
+
+.sw-description-item {
+  align-items: start;
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  padding-block: var(--sw-space-2);
+  row-gap: var(--sw-space-1);
+}
+
+.sw-description-item:first-child { padding-top: 0; }
+
+.sw-description-item:last-child { padding-bottom: 0; }
+
+.sw-description-item + .sw-description-item {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-description-term,
+.sw-description-detail {
+  align-items: flex-start;
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+@media ${breakpointQuery('below', 'md')} {
+  .sw-description-list { grid-template-columns: minmax(0, 1fr); }
+}
+
+@media (forced-colors: active) {
+  .sw-description-item + .sw-description-item { border-top-color: CanvasText; }
+}`;
+}
+export function descriptionListClassCatalog() {
+    return [
+        'sw-description-list',
+        'sw-description-item',
+        'sw-description-term',
+        'sw-description-detail',
+    ];
+}

package/dist/css/css-icon-button.d.ts

@@ -0,0 +1 @@
+export declare function iconButtonRules(className: string): string;

package/dist/css/css-icon-button.js

@@ -0,0 +1,26 @@
+import { buttonSizes } from '@scalewing/tokens';
+import { coarsePointerQuery, touchTarget } from './touch-target.js';
+/*
+ * An icon-only Button drawn by `className` (CalendarButton, InfoTip): square
+ * at every Button size, as wide as the size's control height, and the full
+ * touch target on a coarse pointer at the smaller sizes too. The coarse
+ * pointer's rule follows the squares, which it outranks only by order.
+ */
+export function iconButtonRules(className) {
+    const squares = buttonSizes
+        .map((size) => `.sw-button-${size}.${className} { min-width: var(--sw-control-${size}-min-height); }`)
+        .join('\n');
+    return `.sw-button.${className} {
+  flex: none;
+  padding-inline: 0;
+}
+
+${squares}
+
+@media ${coarsePointerQuery} {
+  .sw-button.${className} {
+    min-height: ${touchTarget};
+    min-width: ${touchTarget};
+  }
+}`;
+}

package/dist/css/css-info-tip.d.ts

@@ -0,0 +1,2 @@
+export declare function cssInfoTipClasses(): string;
+export declare function infoTipClassCatalog(): string[];

package/dist/css/css-info-tip.js

@@ -0,0 +1,8 @@
+import { iconButtonRules } from './css-icon-button.js';
+/* InfoTip's glyph button; its bubble is the generated `.sw-tooltip`. */
+export function cssInfoTipClasses() {
+    return iconButtonRules('sw-info-tip');
+}
+export function infoTipClassCatalog() {
+    return ['sw-info-tip'];
+}

package/dist/css/stylesheet.js

@@ -10,8 +10,10 @@ import { radioGroupClassCatalog } from './css-radio-group.js';
 import { spinnerClassCatalog } from './css-spinner.js';
 import { progressClassCatalog } from './css-progress.js';
 import { tooltipClassCatalog } from './css-tooltip.js';
+import { infoTipClassCatalog } from './css-info-tip.js';
 import { separatorClassCatalog } from './css-separator.js';
 import { statTileClassCatalog } from './css-stat-tile.js';
+import { descriptionListClassCatalog } from './css-description-list.js';
 import { tabsClassCatalog } from './css-tabs.js';
 import { responsiveClassCatalog } from './css-responsive.js';
 import { filterChipsClassCatalog } from './css-filter-chips.js';
@@ -72,8 +74,10 @@ export function utilityClassCatalog() {
         ...spinnerClassCatalog(),
         ...progressClassCatalog(),
         ...tooltipClassCatalog(),
+        ...infoTipClassCatalog(),
         ...separatorClassCatalog(),
         ...statTileClassCatalog(),
+        ...descriptionListClassCatalog(),
         ...tabsClassCatalog(),
         ...filterChipsClassCatalog(),
         ...gridClassCatalog(),

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { Checkbox, type CheckboxProps } from './components/Checkbox.js';
 export { Spinner, type SpinnerProps, type SpinnerSize, } from './components/Spinner.js';
 export { Progress, type ProgressProps, type ProgressTone, } from './components/Progress.js';
 export { Tooltip, type TooltipProps, type TooltipRelationship, } from './components/Tooltip.js';
+export { InfoTip, type InfoTipProps } from './components/InfoTip.js';
 export { RadioGroup, type RadioGroupOption, type RadioGroupProps, } from './components/RadioGroup.js';
 export { AppHeader, type AppHeaderProps } from './components/AppHeader.js';
 export { Badge, type BadgeProps, type BadgeSize, type BadgeTone, badgeSizes, badgeTones, } from './components/Badge.js';
@@ -41,6 +42,8 @@ export type { Breakpoint, BreakpointDirection, VisibilityBreakpoint, } from './c
 export { breakpointQuery } from './css/breakpoints.js';
 export { Separator } from './components/Separator.js';
 export type { SeparatorOrientation, SeparatorProps, } from './components/Separator.js';
+export { DescriptionItem, DescriptionList, } from './components/DescriptionList.js';
+export type { DescriptionItemProps, DescriptionListProps, } from './components/DescriptionList.js';
 export { Grid } from './components/Grid.js';
 export type { GridColumns, GridProps } from './components/Grid.js';
 export type { GridColumnSpan } from './css/css-grid-span.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { Checkbox } from './components/Checkbox.js';
 export { Spinner, } from './components/Spinner.js';
 export { Progress, } from './components/Progress.js';
 export { Tooltip, } from './components/Tooltip.js';
+export { InfoTip } from './components/InfoTip.js';
 export { RadioGroup, } from './components/RadioGroup.js';
 export { AppHeader } from './components/AppHeader.js';
 export { Badge, badgeSizes, badgeTones, } from './components/Badge.js';
@@ -34,6 +35,7 @@ export { ThemeProvider, useTheme, } from './theme/ThemeProvider.js';
 export { utilityClassCatalog } from './css/stylesheet.js';
 export { breakpointQuery } from './css/breakpoints.js';
 export { Separator } from './components/Separator.js';
+export { DescriptionItem, DescriptionList, } from './components/DescriptionList.js';
 export { Grid } from './components/Grid.js';
 export { DenominationGrid } from './components/DenominationGrid.js';
 export { FilterChips } from './components/FilterChips.js';

package/dist/styles.css

@@ -1884,12 +1884,6 @@ body {
 .sw-button-sm.sw-calendar-button { min-width: var(--sw-control-sm-min-height); }
 .sw-button-md.sw-calendar-button { min-width: var(--sw-control-md-min-height); }
 
-.sw-calendar-button:not(.sw-button-md) .sw-date-field-glyph {
-  height: var(--sw-space-4);
-  width: var(--sw-space-4);
-}
-
-/* A coarse pointer gets the full touch target at the smaller sizes too. */
 @media (pointer: coarse) {
   .sw-button.sw-calendar-button {
     min-height: var(--sw-control-md-min-height);
@@ -1897,6 +1891,11 @@ body {
   }
 }
 
+.sw-calendar-button:not(.sw-button-md) .sw-date-field-glyph {
+  height: var(--sw-space-4);
+  width: var(--sw-space-4);
+}
+
 .sw-bar-chart {
   display: grid;
   gap: var(--sw-space-2);
@@ -2949,6 +2948,22 @@ body {
   .sw-tooltip { border-color: CanvasText; box-shadow: none; }
 }
 
+.sw-button.sw-info-tip {
+  flex: none;
+  padding-inline: 0;
+}
+
+.sw-button-xs.sw-info-tip { min-width: var(--sw-control-xs-min-height); }
+.sw-button-sm.sw-info-tip { min-width: var(--sw-control-sm-min-height); }
+.sw-button-md.sw-info-tip { min-width: var(--sw-control-md-min-height); }
+
+@media (pointer: coarse) {
+  .sw-button.sw-info-tip {
+    min-height: var(--sw-control-md-min-height);
+    min-width: var(--sw-control-md-min-height);
+  }
+}
+
 .sw-separator {
   background: var(--sw-color-border);
   border: 0;
@@ -3024,6 +3039,49 @@ body {
   .sw-stat-tile-primary { background: Highlight; }
 }
 
+.sw-description-list {
+  column-gap: var(--sw-space-4);
+  display: grid;
+  grid-template-columns: fit-content(40%) minmax(0, 1fr);
+  margin: 0;
+  min-width: 0;
+}
+
+.sw-description-item {
+  align-items: start;
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  padding-block: var(--sw-space-2);
+  row-gap: var(--sw-space-1);
+}
+
+.sw-description-item:first-child { padding-top: 0; }
+
+.sw-description-item:last-child { padding-bottom: 0; }
+
+.sw-description-item + .sw-description-item {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-description-term,
+.sw-description-detail {
+  align-items: flex-start;
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+@media not all and (min-width: 48rem) {
+  .sw-description-list { grid-template-columns: minmax(0, 1fr); }
+}
+
+@media (forced-colors: active) {
+  .sw-description-item + .sw-description-item { border-top-color: CanvasText; }
+}
+
 .sw-tabs {
   border-bottom: 1px solid var(--sw-color-border);
   display: flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",