@ahrowe/ui 0.51.0 → 0.52.0

package/dist/types/common/actionIcon/actionIcon.types.d.ts

@@ -1,13 +1,17 @@
 import { IconContent } from '../types/icon.types.js';
 import { SlotClassNames, SlotStyles } from '../types/slots.types.js';
-import { ButtonProps } from '../button/button.types.js';
+import { ButtonElementProps, ButtonLinkProps } from '../button/button.types.js';
 export type ActionIconSlots = 'root' | 'icon';
-/**
- * A Button with only an icon, sized by that icon, so every Button prop applies except the ones
- * that describe a label or a size.
- */
-export interface ActionIconProps extends Omit<ButtonProps, 'icon' | 'size' | 'children' | 'isLoading' | 'shortcut' | 'classNames' | 'styles'> {
+type LabelAndSizeProps = 'icon' | 'size' | 'children' | 'isLoading' | 'shortcut' | 'classNames' | 'styles';
+interface ActionIconOwnProps {
     icon: IconContent;
     classNames?: SlotClassNames<ActionIconSlots>;
     styles?: SlotStyles<ActionIconSlots>;
 }
+/**
+ * A Button with only an icon, sized by that icon, so every Button prop applies except the ones
+ * that describe a label or a size. With `href` it is a link, as a Button is. Two branches rather
+ * than one `Omit<ButtonProps>`, which would merge them and lose `target` and the typed `onClick`.
+ */
+export type ActionIconProps = (Omit<ButtonElementProps, LabelAndSizeProps> & ActionIconOwnProps) | (Omit<ButtonLinkProps, LabelAndSizeProps> & ActionIconOwnProps);
+export {};

package/dist/types/common/ahroweProvider/ahroweProvider.d.ts

@@ -1,4 +1,4 @@
 import { ReactElement } from 'react';
 import { AhroweProviderProps } from './ahroweProvider.types.js';
-declare function AhroweProvider({ children, themes, currentThemeId, defaultProps, presentation, toast, scrollbars, }: AhroweProviderProps): ReactElement;
+declare function AhroweProvider({ children, themes, currentThemeId, defaultProps, presentation, navigate, toast, scrollbars, }: AhroweProviderProps): ReactElement;
 export default AhroweProvider;

package/dist/types/common/button/button.types.d.ts

@@ -27,20 +27,14 @@ export declare enum ButtonType {
     Submit = "submit"
 }
 export type ButtonSlots = 'background' | 'content' | 'loadingContainer' | 'label' | 'shortcut';
-/**
- * `DataProps` supplies the `data-*` index signature, which `ButtonHTMLAttributes` doesn't cover.
- * `type`, `color` and `onClick` below deliberately narrow their inherited counterparts.
- */
-export interface ButtonProps extends DataProps, React.ButtonHTMLAttributes<HTMLButtonElement> {
+interface ButtonOwnProps extends DataProps {
     className?: string;
     style?: CSSProperties;
-    type?: ButtonType;
     /** Emphasis: `Filled`, `Light`, `Outlined` (default) or `Plain`. */
     styleType?: ButtonStyleType;
     /** A `ThemeColor` (default `Primary`) or any CSS colour, such as `'var(--brand)'`. */
     color?: ColorValue;
     size?: ButtonSize;
-    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
     children?: React.ReactNode;
     icon?: IconContent;
     /**
@@ -51,7 +45,30 @@ export interface ButtonProps extends DataProps, React.ButtonHTMLAttributes<HTMLB
     isLoading?: boolean;
     disabled?: boolean;
     title?: string;
-    ref?: React.Ref<HTMLButtonElement>;
     classNames?: SlotClassNames<ButtonSlots>;
     styles?: SlotStyles<ButtonSlots>;
 }
+/**
+ * A Button without `href`, a `<button>`. `DataProps` supplies the `data-*` index signature, which
+ * `ButtonHTMLAttributes` doesn't cover. `type` and `onClick` narrow their native counterparts.
+ */
+export interface ButtonElementProps extends ButtonOwnProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps | 'type' | 'onClick'> {
+    href?: undefined;
+    type?: ButtonType;
+    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
+    ref?: React.Ref<HTMLButtonElement>;
+}
+/** A Button with `href`, an `<a>`: `target`, `rel` and `download` are the native ones. */
+export interface ButtonLinkProps extends ButtonOwnProps, Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof ButtonOwnProps | 'type' | 'onClick' | 'href'> {
+    /**
+     * Renders the button as a link, so a long press, Ctrl/⌘-click and a middle click work as on any
+     * other: `tel:`, `mailto:`, a maps URL, a page of the app. A plain click on a page of the app goes
+     * through `ConfigProvider`'s `navigate` when it is set.
+     */
+    href: string;
+    type?: undefined;
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => Promise<void> | void;
+    ref?: React.Ref<HTMLAnchorElement>;
+}
+export type ButtonProps = ButtonElementProps | ButtonLinkProps;
+export {};

package/dist/types/common/configProvider/configProvider.d.ts

@@ -9,5 +9,6 @@ export declare const ConfigContext: React.Context<ComponentDefaults | null>;
  * consumer who missed one would get sheets in half their app.
  */
 export declare const PresentationContext: React.Context<Presentation | undefined>;
-declare function ConfigProvider({ children, defaultProps, presentation }: ConfigProviderProps): React.JSX.Element;
+export declare const NavigateContext: React.Context<((path: string) => void) | undefined>;
+declare function ConfigProvider({ children, defaultProps, presentation, navigate }: ConfigProviderProps): React.JSX.Element;
 export default ConfigProvider;

package/dist/types/common/configProvider/configProvider.types.d.ts

@@ -151,4 +151,12 @@ export interface ConfigProviderProps {
      * component-keyed entry in `defaultProps` overrides it, and an explicit prop overrides both.
      */
     presentation?: Presentation;
+    /**
+     * The app's router, for the links components render: Button and ListItem with an `href`, and
+     * Breadcrumb, Menu and CommandPalette entries. A plain click on a link within the app calls it
+     * with the path (`/clients/7?tab=projects`) instead of loading the page. Ctrl/⌘-click, a middle
+     * click, `target`, `download` and links to anywhere else stay with the browser. Unset, every
+     * link loads its page. A nested provider that does not set it keeps the outer one's.
+     */
+    navigate?: (path: string) => void;
 }

package/dist/types/common/copyButton/copyButton.types.d.ts

@@ -11,7 +11,10 @@ export interface CopyButtonLabels {
     /** Announced when the copy fails. Default: "Could not copy". */
     failed?: string;
 }
-export interface CopyButtonProps extends Omit<ActionIconProps, 'icon' | 'onCopy' | 'onError' | 'onClick' | 'ref' | 'classNames' | 'styles'> {
+/** The `<button>` branch of ActionIcon: a copy button is never a link. */
+export interface CopyButtonProps extends Omit<Extract<ActionIconProps, {
+    href?: undefined;
+}>, 'href' | 'icon' | 'onCopy' | 'onError' | 'onClick' | 'ref' | 'classNames' | 'styles'> {
     /** Text written to the clipboard on click. */
     value: string;
     /** How long the copied state shows, in ms. Default: 2000. */

package/dist/types/common/listItem/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './listItem.js';
+export * from './listItem.types.js';

package/dist/types/common/listItem/listItem.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { ListItemProps } from './listItem.types.js';
+declare function ListItem({ icon, title, subtitle, endContent, href, target, rel, download, onClick, selected, chevron, className, style, classNames, styles: slotStyles, ...rest }: ListItemProps): ReactElement;
+export default ListItem;

package/dist/types/common/listItem/listItem.types.d.ts

@@ -0,0 +1,33 @@
+import { AnchorHTMLAttributes, CSSProperties, MouseEventHandler, ReactNode } from 'react';
+import { IconContent } from '../types/icon.types.js';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type ListItemSlots = 'root' | 'icon' | 'labels' | 'trigger' | 'title' | 'subtitle' | 'endContent' | 'chevron';
+export interface ListItemProps extends Omit<HtmlProps<HTMLDivElement>, 'title' | 'onClick'>, Pick<AnchorHTMLAttributes<HTMLAnchorElement>, 'target' | 'rel' | 'download'> {
+    /** Before the title: a FontAwesome icon or any element, such as an `Avatar`. */
+    icon?: IconContent;
+    /** The main line. Cut off with an ellipsis where it does not fit. */
+    title: ReactNode;
+    /** A smaller line under the title, cut off after two lines. */
+    subtitle?: ReactNode;
+    /**
+     * The trailing edge: a status `Chip`, a date, an amount, and controls of its own such as an
+     * edit button or a `Switch`, which keep working in a row that opens something.
+     */
+    endContent?: ReactNode;
+    /**
+     * Opens something from the whole row, as a link: Ctrl/⌘-click and a middle click open a new tab.
+     * A plain click on a page of the app goes through `ConfigProvider`'s `navigate` when it is set.
+     * `target`, `rel` and `download` apply to it.
+     */
+    href?: string;
+    /** Opens something from the whole row, as a button. With `href` as well, runs before the link is followed. */
+    onClick?: MouseEventHandler<HTMLElement>;
+    /** The row whose record is open: tinted, and the current page to a screen reader. */
+    selected?: boolean;
+    /** The chevron at the end. Shown for a row with an `href`, which takes the user somewhere. */
+    chevron?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<ListItemSlots>;
+    styles?: SlotStyles<ListItemSlots>;
+}

package/dist/types/common/menu/menu.types.d.ts

@@ -26,8 +26,8 @@ export interface MenuAction {
     /** Renders in the destructive colour. For deleting, discarding, revoking. */
     danger?: boolean;
     /**
-     * Followed after `onClick` and `onAction`. In `Menu` a real `<a>`, so Ctrl/⌘-click opens a new tab.
-     * Loads the whole page: with a client-side router, navigate in `onClick` instead.
+     * Followed after `onClick` and `onAction`, through `ConfigProvider`'s `navigate` when it is set.
+     * In `Menu` a real `<a>`, so Ctrl/⌘-click opens a new tab.
      */
     href?: string;
     onClick?: () => void;

package/dist/types/common/menu/menuItem.d.ts

@@ -6,5 +6,8 @@ export declare function renderItemIcon(icon: MenuAction['icon'], reserveCell: bo
     className: string;
     style?: CSSProperties;
 }): ReactNode;
-/** Runs an action the way clicking it does: its own `onClick`, then `onAction`, then its `href`. */
-export declare function runMenuAction(action: MenuAction, onAction?: (id: string) => void): void;
+/**
+ * Runs an action the way clicking it does: its own `onClick`, then `onAction`, then its `href`.
+ * `follow` is `useFollowHref()` where the caller can reach the router; `menuHotkeys` cannot.
+ */
+export declare function runMenuAction(action: MenuAction, onAction?: (id: string) => void, follow?: (href: string) => void): void;

package/dist/types/common/themeProvider/theme.types.d.ts

@@ -217,6 +217,10 @@ export interface ThemeVariables {
     '--multi-select-min-height'?: string;
     /** Maximum height of the open option panel. Falls back to 260px. */
     '--multi-select-panel-height'?: string;
+    /** Minimum height of a row. Falls back to 48px, the smallest comfortable touch target. */
+    '--list-item-min-height'?: string;
+    /** Background of a `selected` row. Falls back to a 12% tint of --primary-color. */
+    '--list-item-selected-background'?: string;
     /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
     '--kanban-empty-column-width'?: string;
     '--option-picker-padding'?: string;

package/dist/types/common/utils/navigation.d.ts

@@ -0,0 +1,12 @@
+import { MouseEvent } from 'react';
+type Navigate = (path: string) => void;
+/**
+ * The click handler for an `<a>` a component renders: a plain click on a link within the app goes
+ * to `ConfigProvider`'s `navigate`, everything else to the browser. Call it after the consumer's own
+ * `onClick`, so a `preventDefault()` there still wins.
+ */
+export declare function useLinkClick(): (event: MouseEvent<HTMLAnchorElement>) => void;
+/** Follows a link from code, where no anchor was clicked: through the router where it can. */
+export declare function followHref(href: string, navigate?: Navigate): void;
+export declare function useFollowHref(): (href: string) => void;
+export {};

package/dist/types/index.d.ts

@@ -82,6 +82,8 @@ export { default as KanbanBoard } from './common/kanbanBoard/index.js';
 export * from './common/kanbanBoard/index.js';
 export { default as KlipyPicker } from './common/klipyPicker/index.js';
 export * from './common/klipyPicker/index.js';
+export { default as ListItem } from './common/listItem/index.js';
+export * from './common/listItem/index.js';
 export { default as Loader } from './common/loader/index.js';
 export * from './common/loader/index.js';
 export { default as LoadingOverlay } from './common/loadingOverlay/index.js';

package/docs/ActionIcon.md

@@ -9,18 +9,21 @@
 **Requires:** `@fortawesome/free-solid-svg-icons` peer dependency.
 
 An ActionIcon is a [Button](Button.md) holding only an icon and sized by it: a real `<button>`
-with Button's hover, focus ring and ripple. It takes Button's `styleType` and `color`, plain and
+with Button's hover, focus ring and ripple, or with an `href` a link, as a Button is. It takes Button's `styleType` and `color`, plain and
 in the surrounding text colour by default, so it fits whatever it sits on.
 
 ```tsx
 import { ActionIcon, ButtonStyleType, ThemeColor } from '@ahrowe/ui';
-import { faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
+import { faPhone, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
 <ActionIcon icon={faXmark} aria-label="Close" onClick={onClose} />
 
 // A destructive row action
 <ActionIcon icon={faTrash} color={ThemeColor.Error} title="Delete item" onClick={handleDelete} />
 
+// A link: a long press copies the number
+<ActionIcon icon={faPhone} href="tel:+431234567" aria-label="Call" />
+
 // Filled, for an action that should stand out
 <ActionIcon icon={faTrash} styleType={ButtonStyleType.Filled} color={ThemeColor.Error} aria-label="Delete" />
 ```
@@ -35,7 +38,8 @@ import { faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 | `title` | `string` | Tooltip. Give an icon-only button an `aria-label` as well |
 | `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void \| Promise<void>` | Click handler |
 | `disabled` | `boolean` | Fades it and blocks clicks |
-| `ref` | `Ref<HTMLButtonElement>` | Ref to the button |
+| `href` | `string` | Renders it as an `<a>`, with `target`, `rel` and `download`. See [Button.md](Button.md) |
+| `ref` | `Ref<HTMLButtonElement>` | Ref to the button, or `Ref<HTMLAnchorElement>` with an `href` |
 
 Every other Button prop and native `<button>` attribute passes through, except `size`,
 `children`, `isLoading` and `shortcut`. The box is the icon plus `4px` on each side; set `width`

package/docs/AhroweProvider.md

@@ -40,6 +40,7 @@ Every prop is optional. `<AhroweProvider><App /></AhroweProvider>` applies `defa
 | `currentThemeId` | `string` | the first theme without a `baseThemeId` | The `id` of the theme to apply |
 | `defaultProps` | `ComponentDefaults` | | Default props per component. See [ConfigProvider.md](ConfigProvider.md) |
 | `presentation` | `Presentation` | | How every sheet-capable component presents. See [ConfigProvider.md](ConfigProvider.md) |
+| `navigate` | `(path: string) => void` | | The app's router, for the links components render. Usually set on a `ConfigProvider` inside the router instead, see [ConfigProvider.md](ConfigProvider.md) |
 | `toast` | `ToastContextConfig` | | Settings for every toast `showToast` shows. See [Toast.md](Toast.md) |
 | `scrollbars` | `boolean` | `true` | Styles every scrollbar inside the app in the theme's colours. See **Scrollbars** |
 
@@ -51,7 +52,7 @@ On the server, and while hydrating, nothing is portalled: the server has nowhere
 
 ## Nesting
 
-A nested `AhroweProvider` applies its `themes`, `currentThemeId`, `defaultProps` and `presentation` to its section. Its `defaultProps` merge with the outer ones per component, the same as nested `ConfigProvider`s. Toasts, scrollbars and the portal element stay with the outermost provider, so a nested `toast` or `scrollbars` is ignored, with a warning.
+A nested `AhroweProvider` applies its `themes`, `currentThemeId`, `defaultProps`, `presentation` and `navigate` to its section. Its `defaultProps` merge with the outer ones per component, the same as nested `ConfigProvider`s. Toasts, scrollbars and the portal element stay with the outermost provider, so a nested `toast` or `scrollbars` is ignored, with a warning.
 
 Only a provider inside another `AhroweProvider` counts as nested. Put the outer one at the root first: one placed around a section of an app that has none renders the portal element inside that section, where an `overflow: hidden` or a `transform` around it clips every panel.
 

package/docs/Breadcrumb.md

@@ -30,28 +30,8 @@ import { faHouse, faFolder } from '@fortawesome/free-solid-svg-icons';
   ]}
 />
 
-// Client-side routing (e.g. react-router): keep href for a real, right-clickable link,
-// and use onClick to intercept the native navigation with the router's own navigate()
-import { useNavigate } from 'react-router-dom';
-
-function Example() {
-  const navigate = useNavigate();
-  return (
-    <Breadcrumb
-      items={[
-        {
-          label: 'Home',
-          href: '/',
-          onClick: (event) => {
-            event.preventDefault();
-            navigate('/');
-          },
-        },
-        { label: 'Current page' },
-      ]}
-    />
-  );
-}
+// With a client-side router, set `navigate` once on ConfigProvider (ConfigProvider.md):
+// a plain click on a crumb then goes through the router, a middle click still opens a new tab.
 
 // A disabled crumb: dimmed, not clickable, regardless of href/onClick
 <Breadcrumb
@@ -86,9 +66,9 @@ function Example() {
 |-------|------|-------------|
 | `id` | `string` | Optional stable key; falls back to the item's index |
 | `label` | `ReactNode` | The crumb's text |
-| `href` | `string` | Renders the crumb as a real `<a>`. Omit to render a plain clickable element (with `onClick`) or static text |
+| `href` | `string` | Renders the crumb as a real `<a>`, followed through `ConfigProvider`'s `navigate` when it is set. Omit to render a plain clickable element (with `onClick`) or static text |
 | `icon` | `IconDefinition \| ReactElement` | Optional leading icon — FontAwesome icon or any React element |
-| `onClick` | `(event: MouseEvent) => void` | Click handler. Works alongside `href`: call `event.preventDefault()` to stop the native navigation and hand off to a client-side router's own navigate function (see the react-router example above). Also works on its own, with no `href` |
+| `onClick` | `(event: MouseEvent) => void` | Click handler. Alongside `href` it runs first, and `event.preventDefault()` stops the link from being followed. Also works on its own, with no `href` |
 | `disabled` | `boolean` | Dims the crumb and makes it non-interactive, regardless of `href`/`onClick` |
 
 **Key props:**

package/docs/Button.md

@@ -12,7 +12,7 @@ works with any colour. The colours are the library-wide `ThemeColor`s or any CSS
 
 ```tsx
 import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor, useHotkeys } from '@ahrowe/ui';
-import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
+import { faLocationArrow, faPhone, faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
 // The main action
 <Button styleType={ButtonStyleType.Filled} onClick={handleSave}>Save</Button>
@@ -67,6 +67,10 @@ useHotkeys({ 'mod+s': handleSave });
 
 // Submit button in a form
 <Button type={ButtonType.Submit} styleType={ButtonStyleType.Filled}>Submit</Button>
+
+// A link: a long press copies the number, a middle click opens a new tab
+<Button href="tel:+431234567" icon={faPhone}>Call</Button>
+<Button href={mapsUrl} target="_blank" icon={faLocationArrow}>Directions</Button>
 ```
 
 **Enums:**
@@ -83,19 +87,37 @@ useHotkeys({ 'mod+s': handleSave });
 | `styleType` | `ButtonStyleType` | `Filled`: solid fill, for the one main action. `Light`: a tint of the colour behind text in the colour. `Outlined` (default): border and text in the colour. `Plain`: text in the colour, no fill or border, for toolbar, icon and close buttons |
 | `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour. `Neutral` takes the surrounding text colour, with a `--border-color` outline; `Error` is for destructive actions. See [ThemeColor.md](ThemeColor.md) |
 | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
-| `type` | `ButtonType` | HTML button type |
+| `type` | `ButtonType` | HTML button type. Not on a link |
+| `href` | `string` | Renders an `<a>` instead of a `<button>`, see **As a link** |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
 | `shortcut` | `string` | A combo in [useHotkeys](Hooks.md) spelling, e.g. `'mod+s'`. Shown after the label, written for the platform. Binding it is yours, see below |
-| `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
+| `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks and a form submit like `disabled`, but keeps full colour and the keyboard focus. |
 | `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
 
-`ButtonProps` extends `React.ButtonHTMLAttributes<HTMLButtonElement>`, so every native `<button>`
-attribute is accepted and forwarded — pointer handlers (`onPointerDown` and friends, for
-press-and-hold controls that act on press rather than release), `onContextMenu`, `tabIndex`,
-`name`, `value`, `form`, `autoFocus`, and the rest. `type` and `onClick` are narrowed: `type`
-takes the `ButtonType` enum, and `onClick` may return a promise. `color` is Button's own prop, not
-the obsolete HTML attribute.
+Without an `href`, every native `<button>` attribute is accepted and forwarded — pointer handlers
+(`onPointerDown` and friends, for press-and-hold controls that act on press rather than release),
+`onContextMenu`, `tabIndex`, `name`, `value`, `form`, `autoFocus`, and the rest. `type` and
+`onClick` are narrowed: `type` takes the `ButtonType` enum, and `onClick` may return a promise.
+`color` is Button's own prop, not the obsolete HTML attribute. With an `href`, the native `<a>`
+attributes take their place, see below.
+
+## As a link
+
+With an `href` a Button is an `<a>` that looks like a button, so it behaves like a link: a long
+press offers to copy the address, and Ctrl/⌘-click and a middle click open a new tab. Use it for
+anything that goes somewhere: `tel:`, `mailto:`, a maps URL, a page of your app. A button whose
+`onClick` sets `window.location` gets none of that.
+
+- **Types.** `ButtonProps` is two shapes, told apart by `href`. The link takes the native `<a>`
+  attributes, `target`, `rel` and `download` among them, types `onClick` and `ref` for the `<a>`,
+  and has no `type`. An `href` that may be `undefined` renders a `<button>` while it is, and an
+  `onClick` beside it needs its event typed as `MouseEvent<HTMLElement>`.
+- **Pages of your app** load the whole page unless `ConfigProvider` has a `navigate`, which then
+  takes a plain click, see [ConfigProvider.md](ConfigProvider.md).
+- **`disabled`** drops the `href`: an `<a>` cannot be disabled, so it leaves the tab order and is
+  announced as a dimmed link. **`isLoading`** keeps it, and with it the focus, but is not followed.
+- **`target="_blank"`** needs no `rel="noopener"`: every browser the library supports implies it.
 
 **Shortcuts are drawn, not bound.** `shortcut` writes the combo in a pill after the label,
 `⌘S` on an Apple platform and `Ctrl+S` elsewhere. It also sets `aria-keyshortcuts`, so a screen
@@ -139,6 +161,19 @@ A Button is sized by its font. `--default-font-size` is the base, `Medium` is th
 
 `ButtonSize.Icon` is the exception: it inherits the surrounding text size and has no padding at all, because the caller sets the box.
 
+## Migration from the `ButtonProps` interface
+
+Before 0.51, `ButtonProps` and `ActionIconProps` were interfaces for a `<button>`. Each is now a
+union of a button and a link shape, told apart by `href`. Code that renders a Button compiles
+unchanged; a type built on one may not, because an interface cannot extend a union and `Omit` on
+one keeps only what both shapes share:
+
+| Before | After |
+|--------|-------|
+| `interface SaveButtonProps extends ButtonProps { … }` | `type SaveButtonProps = ButtonProps & { … }`, which keeps both shapes, so the wrapper takes an `href` too |
+| `interface MyIconProps extends ActionIconProps { … }` | `type MyIconProps = ActionIconProps & { … }` |
+| `Omit<ButtonProps, 'styleType'>` | `Omit<ButtonElementProps, 'styleType'>` for a wrapper that is only ever a `<button>` |
+
 ## Migration from `ButtonSize.Default`
 
 Before 0.45, `ButtonSize.Default` was a second name for `Medium`, which is now the default. Replace

package/docs/CLAUDE.md

@@ -40,6 +40,9 @@ enums and slot names. Do not infer props from a component's name.
   emphasis, the same way everywhere: `Filled` for the one main action of a region (at most one),
   `Light` for status and selection, `Outlined` for secondary actions, `Plain` for tertiary ones.
 - **`icon` props** take a FontAwesome `IconDefinition` or any React element.
+- **Links.** An `href` (Button, ActionIcon, ListItem, Breadcrumb, Menu, CommandPalette) renders a
+  real `<a>`. With a client-side router, set `navigate` on a `ConfigProvider` inside the router
+  once, or every plain click loads the page (ConfigProvider.md).
 - **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
   Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`, ChatComposer its
   `<textarea>`. Timer, Flip, Tilt, Ripple, VirtualList, ChatMessageList, RoomDrawer and RoomViewer
@@ -106,6 +109,7 @@ enums and slot names. Do not infer props from a component's name.
 | InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
 | KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
 | KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
+| ListItem.md | ListItem | One row of a list that stands for a record: a customer, an invoice, a delivery note |
 | Loader.md | Loader, LoaderType, ThemeColor | A loading indicator for something in progress with no known end: a fetch, a save, a connection |
 | LoadingOverlay.md | LoadingOverlay, Loader, LoaderType | Covering content while it reloads: a table refreshing, a form saving, a panel fetching its next page |
 | Menu.md | Menu, menuHotkeys | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |

package/docs/CommandPalette.md

@@ -73,7 +73,7 @@ On a small touch screen it can present as a bottom sheet like every `Modal`: pas
 | `isLoading` | `boolean` | Shows the `loading` label instead of `empty` while nothing matches |
 | `presentation` | `Presentation` | Centred dialog (default), bottom sheet, or a sheet only on a small touch screen |
 
-A command is a `MenuAction`: `id`, `label`, `icon`, `shortcut`, `keywords`, `disabled`, `danger`, `href` and `onClick`. A command with an `href` goes there after running. See [Menu.md](Menu.md).
+A command is a `MenuAction`: `id`, `label`, `icon`, `shortcut`, `keywords`, `disabled`, `danger`, `href` and `onClick`. A command with an `href` goes there after running, through `ConfigProvider`'s `navigate` when it is set. See [Menu.md](Menu.md).
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CommandPalette: { presentation: Presentation.Auto } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

package/docs/ConfigProvider.md

@@ -7,7 +7,7 @@
 **Import:** `import { ConfigProvider } from '@ahrowe/ui'`
 **Types:** `import type { ComponentDefaults, ConfigProviderProps } from '@ahrowe/ui'`
 
-At the app root, pass `defaultProps` and `presentation` to [AhroweProvider](AhroweProvider.md), which includes a ConfigProvider. Use ConfigProvider on its own for a section with defaults of its own:
+At the app root, pass `defaultProps`, `presentation` and `navigate` to [AhroweProvider](AhroweProvider.md), which includes a ConfigProvider. Use ConfigProvider on its own for a section with defaults of its own:
 
 ```tsx
 import { AhroweProvider, ConfigProvider } from '@ahrowe/ui';
@@ -58,6 +58,7 @@ So a global default only fills in props a given instance left out — any instan
 |------|------|-------------|
 | `defaultProps` | `ComponentDefaults` | Default props keyed by component name, e.g. `{ Input: { alwaysFloatLabel: true } }` |
 | `presentation` | `Presentation` | How every sheet-capable component presents by default — one switch for all of them (see below) |
+| `navigate` | `(path: string) => void` | The app's router, for every link a component renders (see below) |
 | `children` | `ReactNode` | Your app content |
 
 ## App-wide `presentation`
@@ -90,6 +91,38 @@ It resolves *under* the component-keyed defaults, so the full order for a `prese
 
 A nested provider inherits it unless it sets its own, the same way `defaultProps` compose. Everything built on those four components follows along: `SplitButton`, `ColorPicker`, `Breadcrumb`, `VirtualList`, and `DatePicker`/`TimeInput`/`KlipyPicker` in either their menu or their `isModal` mode. `InputDropdown` and `Tooltip` are deliberately never sheets and ignore it.
 
+## Client-side routing (`navigate`)
+
+Button, ActionIcon and ListItem with an `href`, and Breadcrumb, Menu and CommandPalette entries with one, are real links: a long press, Ctrl/⌘-click and a middle click work on them as on any `<a>`. Without `navigate` a plain click loads the page. With it, a plain click on a page of the app calls `navigate` with the path instead:
+
+```tsx
+import { Outlet, useNavigate } from 'react-router-dom';
+import { ConfigProvider } from '@ahrowe/ui';
+
+// The root route's element. useNavigate needs the router, and AhroweProvider is usually outside it.
+function Root() {
+  const navigate = useNavigate();
+  return (
+    <ConfigProvider navigate={navigate}>
+      <Outlet />
+    </ConfigProvider>
+  );
+}
+```
+
+It is called with the path, search and hash (`/clients/7?tab=projects`) for a plain left click on an `http:` or `https:` link to the page's own origin. The browser keeps everything else: a click with Ctrl, ⌘, Shift or Alt, a middle click, a link with a `target` or `download`, another site, `mailto:`, `tel:`, a `blob:` URL, and a jump to an anchor on the current page. An `onClick` of your own runs first, and a `preventDefault()` in it keeps `navigate` out.
+
+- **Write absolute paths.** An `href` is resolved against the page's URL, like any link, because that is what a middle click does; `navigate` gets the resolved path. A router resolves a relative path against the route instead, so `href="projects/1"` on `/clients/7` is `/clients/projects/1`, not where `navigate('projects/1')` would go.
+- **`navigate` decides.** It gets every path of the page's own origin, also one the router does not own: a server route such as `/logout`, a file under `/api`, a page outside a `basename`. Hand those back to the browser with `window.location.assign(path)`. A `basename` is part of the `href` but not of the path the router's `navigate` takes, so strip it:
+
+  ```tsx
+  navigate={(path) => {
+    if (path === BASENAME || path.startsWith(`${BASENAME}/`)) navigate(path.slice(BASENAME.length) || '/');
+    else window.location.assign(path);
+  }}
+  ```
+- **Two places it cannot reach.** Toasts render in `AhroweProvider`'s own host, outside a `ConfigProvider` placed inside the router. `menuHotkeys` runs outside React, so an entry with an `href` run from its shortcut loads the page.
+
 ## Supported components
 
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:

package/docs/ListItem.md

@@ -0,0 +1,97 @@
+# ListItem
+
+**When to use:** One row of a list that stands for a record: a customer, an invoice, a delivery note. It shows a title, a second line and a status, can hold actions of its own, and can open the record from the whole row. For hundreds of rows use [VirtualList](VirtualList.md); for actions hanging off a trigger, [Menu](Menu.md).
+
+**Keywords:** row, list row, cell, entry, record, item, drill-down, detail link, settings row
+
+**Import:** `import { ListItem } from '@ahrowe/ui'`
+**Types:** `import type { ListItemProps } from '@ahrowe/ui'`
+
+```tsx
+import { ActionIcon, Chip, ListItem, ThemeColor } from '@ahrowe/ui';
+import { faFileInvoice, faPen } from '@fortawesome/free-solid-svg-icons';
+
+// Shows a record
+<ListItem title="Created" endContent="12 Oct 2026" />
+
+// Opens it: the whole row is the link, with a chevron
+<ListItem
+  icon={faFileInvoice}
+  title="Invoice 2026-0042"
+  subtitle="Müller GmbH, due 1 Nov"
+  endContent={<Chip text="Open" color={ThemeColor.Warn} />}
+  href="/invoices/42"
+/>
+
+// Opens it and has an action: the edit button stays its own
+<ListItem
+  title="Müller GmbH"
+  subtitle="3 projects"
+  href="/clients/7"
+  endContent={<ActionIcon icon={faPen} aria-label="Edit" onClick={editClient} />}
+/>
+
+// Opens it from a button instead of a link: no chevron, which promises a page
+<ListItem title="Add a contact" onClick={openContactModal} />
+
+// The one that is open, beside its detail view
+<ListItem title="Müller GmbH" href="/clients/7" selected={clientId === 7} />
+```
+
+## Opening a record
+
+With `href` the title is a link, and with `onClick` a button. Either one stretches over the whole
+row, so a click anywhere on it opens the record, and with a link a middle click and a long press
+too. Controls in the row stay their own: a button, a link, an input or anything with a `tabindex`
+sits above the stretched area. Text around them still opens the row, so a click on a status `Chip`
+opens the record.
+
+A plain click on a page of the app goes through `ConfigProvider`'s `navigate` when it is set, see
+[ConfigProvider.md](ConfigProvider.md). A screen reader hears the title as the link's name and the
+subtitle, and a text `endContent`, as its description, rather than the whole row run together.
+
+Because the link covers the row, its text cannot be selected with the mouse. A row that is only
+read, with neither `href` nor `onClick`, selects as usual.
+
+The rows sit in whatever holds them, a `Card` or a `<ul>` of your own. ListItem draws no dividers
+and no list semantics of its own: it is a `<div>`, so in a `<ul>` give each one an `<li>`.
+
+**Dividers.** Between groups of rows, a [Divider](Divider.md): it has no margin, so it adds the line
+and nothing else. Between every row, a border from the container instead, because a screen reader
+announces each `Divider` as a separator. The same rule works on `<div>`s and on `<li>`s:
+
+```css
+.clients > * + * {
+  border-top: 1px solid var(--border-color);
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | The main line, cut off with an ellipsis where it does not fit (required) |
+| `subtitle` | `ReactNode` | A smaller line under it, cut off after two lines |
+| `icon` | `IconDefinition \| ReactElement` | Before the title: a FontAwesome icon or any element, such as an `Avatar` |
+| `endContent` | `ReactNode` | The trailing edge: a status, a date, an amount, and controls of its own |
+| `href` | `string` | Opens the record from the whole row, as a link. `target`, `rel` and `download` apply to it |
+| `onClick` | `MouseEventHandler<HTMLElement>` | Opens the record from the whole row, as a button. With `href` too, runs first, and `preventDefault()` keeps the link from being followed |
+| `selected` | `boolean` | The row whose record is open: tinted in `--list-item-selected-background`, and `aria-current="page"` on its link |
+| `chevron` | `boolean` | The chevron at the end. On by default for a row with an `href`, off for one with only `onClick`, which opens a dialog or runs an action rather than going somewhere |
+
+Every native attribute passes through to the root `<div>`. A long title shrinks before
+`endContent` and the chevron do, so they never leave the row. `endContent` itself never shrinks:
+a value longer than a date or an amount belongs in the `subtitle`.
+
+**Theming:**
+
+| Variable | Default |
+|----------|---------|
+| `--list-item-min-height` | `48px`, the smallest comfortable touch target |
+| `--list-item-selected-background` | a 12% tint of `--primary-color` |
+
+Set it once in the theme rather than on each row: `'--list-item-min-height': '64px'`. Hover and
+press tint the row in its own text colour, so they show on any surface; the keyboard focus ring
+goes around the whole row, inside its edge, in `--focus-border-color`.
+
+**Slots:** `root` `icon` `labels` `trigger` (the link or button, which draws the hover and focus ring in its `::after`) `title` `subtitle` `endContent` `chevron`

package/docs/Menu.md

@@ -54,7 +54,7 @@ useHotkeys(menuHotkeys(items, run));
 useHotkeys(menuHotkeys(items, run), { enabled: isOpen });
 ```
 
-It runs each entry the way clicking it does, its own `onClick` then `onAction` then its `href`, and leaves out a `disabled` entry and any entry with no `shortcut`. Bind them yourself instead if the actions already live in a keymap of your own; the menu does not mind either way.
+It runs each entry the way clicking it does, its own `onClick` then `onAction` then its `href`, and leaves out a `disabled` entry and any entry with no `shortcut`. It runs outside React, so it cannot reach `ConfigProvider`'s `navigate`: an `href` run from a shortcut loads the page. Bind them yourself instead if the actions already live in a keymap of your own; the menu does not mind either way.
 
 An action runs its own `onClick` first, then `onAction` on the menu, then the menu closes. Use whichever of the two fits: a handler per entry when they are unrelated, `onAction` when they funnel into one place.
 
@@ -120,7 +120,7 @@ Separators and headings are never focused. The trigger is given `aria-haspopup`,
 | `shortcut` | `string` | A combo in `useHotkeys` spelling, e.g. `'mod+k'`. Shown on the trailing edge, written for the platform. Binding it is yours, see `menuHotkeys` |
 | `disabled` | `boolean` | Not clickable, and skipped by the arrow keys |
 | `danger` | `boolean` | Renders in the destructive colour |
-| `href` | `string` | Makes the entry a real `<a>`, so Ctrl/⌘-click and a middle click open it in a new tab. A click runs `onClick` and `onAction` first, a middle click neither. The browser loads the page, so with a client-side router navigate in `onClick` instead. A `disabled` entry stays a button |
+| `href` | `string` | Makes the entry a real `<a>`, so Ctrl/⌘-click and a middle click open it in a new tab. A click runs `onClick` and `onAction` first, a middle click neither, then follows the link through `ConfigProvider`'s `navigate` when it is set, see [ConfigProvider.md](ConfigProvider.md). A `disabled` entry stays a button |
 | `onClick` | `() => void` | Runs before `onAction` |
 
 **Slots:** `root` `trigger` `menu` `item` `itemIcon` `itemLabel` `itemShortcut` `separator` `heading`