@ahrowe/ui 0.50.0 → 0.52.0

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`

package/docs/ScrollbarProvider.md

@@ -10,7 +10,7 @@
 import { ScrollbarProvider } from '@ahrowe/ui';
 
 <ScrollbarProvider className="my-list">
-  {items.map(item => <ListItem key={item.id} item={item} />)}
+  {items.map(item => <Row key={item.id} item={item} />)}
 </ScrollbarProvider>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",