@ahrowe/ui 0.50.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/chatMessageList/chatMessageList.types.d.ts

@@ -15,7 +15,7 @@ export interface ChatMessageListHandle {
 export interface ChatMessageListProps extends HtmlProps<HTMLDivElement> {
     /** `ChatMessage`s, and anything between them: a `Divider` with a date, a typing indicator. Oldest first. */
     children?: ReactNode;
-    /** Loads older messages when the user scrolls to the top. Prepend them; the view stays where it was. Leave it out once there are no more. */
+    /** Loads older messages as the user nears the top. Prepend them; the view stays where it was. Leave it out once there are no more. */
     onLoadMore?: () => Promise<void>;
     ref?: Ref<ChatMessageListHandle>;
     /** Overrides the text ChatMessageList renders of its own. Merged per key. */

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/dropdown/dropdown.types.d.ts

@@ -8,7 +8,7 @@ export interface DropdownItem {
     disabled?: boolean;
 }
 export type DropdownSlots = 'root' | 'label' | 'field' | 'control' | 'icon' | 'placeholder' | 'list' | 'option';
-export interface DropdownProps extends Omit<HtmlProps, 'onFocus' | 'onBlur' | 'onMouseEnter' | 'onMouseLeave'> {
+export interface DropdownProps extends Omit<HtmlProps, 'onFocus' | 'onBlur' | 'onMouseEnter' | 'onMouseLeave' | 'onScroll'> {
     formValidator?: FormValidator | null;
     onMouseEnter?: ((event: React.MouseEvent) => void) | null;
     onMouseLeave?: ((event: React.MouseEvent) => void) | null;
@@ -27,7 +27,8 @@ export interface DropdownProps extends Omit<HtmlProps, 'onFocus' | 'onBlur' | 'o
     isRow?: boolean;
     disabled?: boolean;
     readOnly?: boolean;
-    onScroll?: () => Promise<void>;
+    /** Loads more items as the end of the open list comes near. Pass `undefined` once there are no more. */
+    onLoadMore?: () => Promise<void>;
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
     dropdownLabel?: string;
     isDropdownListWider?: boolean;

package/dist/types/common/infiniteBlock/useInfiniteScroll.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-export declare function useInfiniteScroll(containerRef: React.RefObject<HTMLDivElement | null>, onScroll: () => Promise<void>, disabled: boolean): {
+export declare function useInfiniteScroll(containerRef: React.RefObject<HTMLDivElement | null>, onLoadMore: (() => Promise<void>) | undefined): {
     isLoading: boolean;
     sentinelRef: React.RefObject<HTMLDivElement | null>;
 };

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/ChatMessageList.md

@@ -83,12 +83,12 @@ button while it does:
   bottom by hand does the same.
 - **After sending**, call `scrollToBottom()` on the handle, or a user who sent from further up
   never sees their own message arrive.
-- **Older messages.** With `onLoadMore`, reaching the top calls it and shows a loader there.
+- **Older messages.** With `onLoadMore`, nearing the top calls it and shows a loader there.
   Prepend what it loads; the message that was at the top stays exactly where it was, at the very
   top too, where the browser's own scroll anchoring does nothing and Safari has none at all. It is
-  called again while the loaded page still leaves the top in view. If it rejects, it is called
-  again after three seconds if the top is still in view, or whenever the user next scrolls there.
-  Pass `undefined` once there is nothing older.
+  called again while the loaded page still leaves the top near, but not after one that added
+  nothing. If it rejects, it is called again after three seconds if the top is still near, or
+  whenever the user next scrolls there. Pass `undefined` once there is nothing older.
 
 **Sizing.** The list scrolls itself and fills the height it is given: `flex: 1` in a column, as
 above, or a `height`. A conversation shorter than the list sits at the bottom, by the composer. To
@@ -99,7 +99,7 @@ start at the top instead, as an AI chat often does: `styles={{ content: { margin
 | Prop | Type | Description |
 |------|------|-------------|
 | `children` | `ReactNode` | Messages, oldest first, and anything between them: a `Divider` with a date, a typing indicator |
-| `onLoadMore` | `() => Promise<void>` | Loads older messages when the top comes into view, see above |
+| `onLoadMore` | `() => Promise<void>` | Loads older messages as the top comes near, see above |
 | `ref` | `Ref<ChatMessageListHandle>` | `scrollToBottom()`: back to the newest message, smoothly unless the user prefers reduced motion, and following again |
 
 **Accessibility:** the scrolling element is a `role="log"`, which screen readers announce

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/Dropdown.md

@@ -36,13 +36,16 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 // Bottom sheet on small touch screens, anchored to the input everywhere else
 <Dropdown label="Status" items={items} value={status} onChange={onChange} presentation={Presentation.Auto} />
 
-// Infinite scroll support
+// Infinite scroll: more items as the end of the open list comes near
 <Dropdown
   items={items}
-  onScroll={async () => { await loadMoreItems(); }}
+  onLoadMore={hasMore ? loadMoreItems : undefined}
 />
 ```
 
+Loading on scroll suits a list people browse. To find one entry among hundreds, typing beats
+scrolling: InputDropdown filters as the user types.
+
 **Key props:**
 
 | Prop | Type | Description |
@@ -57,7 +60,7 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 | `disabled` | `boolean` | Greys the field out and prevents interaction |
 | `readOnly` | `boolean` | Locks the selection without the disabled styling — the field keeps its normal appearance and stays focusable, but the menu won't open and the value can't change (the chevron is hidden). Default `false` |
 | `placeholder` | `string` | Placeholder when no selection |
-| `onScroll` | `() => Promise<void>` | Load more on list scroll |
+| `onLoadMore` | `() => Promise<void>` | Loads more items as the end of the open list comes near, with a spinner meanwhile. Append what it loads. Called again while the end stays near, until a load appends nothing; pass `undefined` once there are no more to save that last call. A rejected load is tried again after three seconds |
 | `useMatLabelStyle` | `boolean` | Material-style floating label |
 | `presentation` | `Presentation` | Where the list opens: anchored to the input (`Default`), always a bottom sheet, or a sheet only on a small touch screen. Imported from the same package: `import { Presentation } from '@ahrowe/ui'` |
 | `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when nothing is selected, so an empty dropdown reads as blank instead of showing the label as if it were the selected value. Only applies with `useMatLabelStyle` (default) |
@@ -87,3 +90,14 @@ outside (a wrapper, a grid column, `style={{ maxWidth: 240 }}`) rather than expe
 to the label: everything inside is absolutely positioned, so it has no width of its own to fall back on.
 
 **Slots:** `root` `label` `field` `control` `icon` `placeholder` `list` `option`
+
+## Migration from `onScroll`
+
+Before 0.51 the load-more callback was `onScroll`, and it was never called. TypeScript points at
+every use:
+
+| Before | After |
+|--------|-------|
+| `onScroll={…}` | `onLoadMore={…}` |
+
+Loading now actually happens, so pass `undefined` once there is nothing more to load.