@ahrowe/ui 0.51.0 → 0.53.0

package/docs/InputDropdown.md

@@ -64,7 +64,7 @@ interface InputDropdownItem {
 | `placeholder` | `string` | |
 | `readOnly` | `boolean` | Make the field read-only — typing is blocked, the list won't open, and keyboard navigation/selection is disabled. Default `false` |
 | `labels` | `InputDropdownLabels` | Text the component renders of its own, see **Labels** below |
-| `formValidator` | `FormValidator` | Connects to validation — shows the error state/message once the field has been touched (blurred), and the required mark (`*`) when the validator has a `required` validator |
+| `formValidator` | `FormValidator` | Connects to validation — shows the error state/message once the validator's `shouldShowError` is true (by default once the field has been blurred, see FormValidator.md), and the required mark (`*`) when the validator has a `required` validator |
 | `error` | `string` | Manual error message (used when no `formValidator` is given) |
 | `isRequired` | `boolean` | Shows the required mark (`*`) next to the label. Also inferred automatically when `formValidator` has a `required` validator. Default `false` |
 

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

@@ -49,7 +49,7 @@ import { Presentation } from '@ahrowe/ui';
 
 **The label floats like `Input`'s.** It rests vertically centred over the control and rises into a notch cut out of the border once the field is focused, open, or has a selection, using the same `fieldset`/`legend` construction and the same `--input-notch-height` geometry as `Input`. A `MultiSelect` sitting next to an `Input` in a form animates with it rather than against it. Set `alwaysFloatLabel` to pin it up, which is what you want when a `placeholder` should always be readable: with a label present the placeholder is otherwise faded in on a delay matching the label's animation, so the two never sit on top of each other. Without a label there is nothing to wait for and it fades in at once.
 
-**Errors:** with a `formValidator` the field stays quiet until it has been touched (the first time the panel closes), then shows the validator's message while the field is hovered or focused, and drops it as soon as the validator is happy again. Without a validator, `isValid` and `errorMessage` are plain props and nothing clears them for you: derive them from your own state, as in `isValid={picked.length > 0}`.
+**Errors:** with a `formValidator` the field stays quiet until the validator's `showErrors` lets the error through (by default once touched: the first time the panel closes, see FormValidator.md), then shows the validator's message while the field is hovered or focused, and drops it as soon as the validator is happy again. Without a validator, `isValid` and `errorMessage` are plain props and nothing clears them for you: derive them from your own state, as in `isValid={picked.length > 0}`.
 
 **Height:** a MultiSelect with one row of chips is exactly as tall as an `Input` or `Dropdown` beside it, so a form row lines up. It grows only when the chips wrap onto a second row. The chips render at `0.8em` to fit: a standalone `Chip` is nearly as tall as the whole field, because its remove button carries `ActionIcon`'s padding around a `1em` icon.
 

package/docs/OtpInput.md

@@ -60,7 +60,7 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 
 **Interaction:** typing a character fills the focused box and jumps to the next one; on the last box, it blurs instead. Backspace on a filled box just clears it; on an already-empty box it clears and focuses the previous one. Left/Right arrow keys move focus without changing values. Pasting (or an SMS autofill suggestion landing in one box) distributes the pasted text across boxes starting from wherever it lands. Focusing a box selects its content, so typing immediately overwrites it rather than requiring a manual clear first.
 
-**Error display:** like `Input`/`RadioGroup`, the boxes get a red border once errored, and the message itself appears in an error `Tooltip` on focus or hover rather than sitting inline under the boxes all the time. With a `formValidator`, this only shows once the field has been *touched* (focus has left the group) **and** has an error — so a required-field error doesn't flash before the user has even had a chance to type. With manual `isValid`/`errorMessage`, there's no touched-gating (the consumer already controls when to set `isValid={false}`, e.g. only after a failed verification call). Either way, the error persists across renders until whatever's driving it — `isValid`, or the `formValidator`'s own error state — actually changes; `OtpInput` never silently clears it on its own. See `clearOnError` below for the one built-in exception.
+**Error display:** like `Input`/`RadioGroup`, the boxes get a red border once errored, and the message itself appears in an error `Tooltip` on focus or hover rather than sitting inline under the boxes all the time. With a `formValidator`, this shows once the validator's `shouldShowError` is true: by default once the field has been *touched* (focus has left the group) **and** has an error, so a required-field error doesn't flash before the user has even had a chance to type (`showErrors`, see FormValidator.md). With manual `isValid`/`errorMessage`, there's no touched-gating (the consumer already controls when to set `isValid={false}`, e.g. only after a failed verification call). Either way, the error persists across renders until whatever's driving it — `isValid`, or the `formValidator`'s own error state — actually changes; `OtpInput` never silently clears it on its own. See `clearOnError` below for the one built-in exception.
 
 **`onComplete`:** fires once per genuinely new completion — i.e. the code going from fewer than `length` characters to exactly `length`. Editing individual boxes of an already-complete code (retyping a digit that was wrong) does **not** refire it on every keystroke, since the code never drops below `length` in between; it fires again only after the code is cleared (manually, or via `clearOnError` below) and refilled.
 

package/docs/RadioGroup.md

@@ -71,7 +71,7 @@ interface RadioOption {
 | `errorMessage` | `string` | Manual error message (when not using a `formValidator`) |
 | `isValid` | `boolean` | Manual valid state (default `true`) |
 
-**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces only after the field is *touched* (focus leaves the group), then on focus or hover.
+**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces once the validator's `showErrors` allows it (by default after the field is *touched*: focus leaves the group, see FormValidator.md), then on focus or hover.
 
 **Global defaults:** adopts `ConfigProvider` — e.g. `defaultProps={{ RadioGroup: { orientation: RadioGroupOrientation.Horizontal } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

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.51.0",
+  "version": "0.53.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",
@@ -106,7 +106,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@ahrowe/form-validation": "^0.3.0",
+    "@ahrowe/form-validation": "^0.4.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",