@ahrowe/ui 0.37.0 → 0.39.0

package/docs/CommandPalette.md

@@ -0,0 +1,84 @@
+# CommandPalette
+
+**When to use:** A search-first dialog for running any command or jumping anywhere in the app from the keyboard, usually opened with ⌘K / Ctrl+K. It takes the same `MenuEntry[]` as [Menu](Menu.md), so one list can feed the menus, the palette and the shortcuts. For picking a value in a form, use [InputDropdown](InputDropdown.md).
+
+**Keywords:** cmd+k, ctrl+k, command menu, quick open, launcher, spotlight, go to anything, jump to, omnibox
+
+**Import:** `import { CommandPalette } from '@ahrowe/ui'`  
+**Types:** `import type { CommandPaletteProps, CommandPaletteLabels } from '@ahrowe/ui'`
+
+**Requires:** `<div id="bodyEnd"></div>` in your app: the palette is a [Modal](Modal.md) and portals there.
+
+```tsx
+import { CommandPalette, menuHotkeys, useHotkeys } from '@ahrowe/ui';
+import type { MenuEntry } from '@ahrowe/ui';
+
+const commands: MenuEntry[] = [
+  { heading: 'Invoice' },
+  { id: 'new-invoice', label: 'New invoice', icon: faPlus, shortcut: 'mod+n', onClick: createInvoice },
+  { id: 'export', label: 'Export as PDF', icon: faFilePdf, keywords: ['download', 'print'], onClick: exportPdf },
+  { heading: 'Go to' },
+  { id: 'customers', label: 'Customers', onClick: () => navigate('/customers') },
+];
+
+function App() {
+  const [isOpen, setOpen] = useState(false);
+  useHotkeys({ ...menuHotkeys(commands), 'mod+k': () => setOpen(true) });
+
+  return <CommandPalette items={commands} isOpen={isOpen} onClose={() => setOpen(false)} />;
+}
+```
+
+**Opening it is yours.** The palette binds no shortcut of its own, for the same reason `Menu` does not: if it listened for ⌘K and your app did too, it would open twice. `menuHotkeys` binds each command's `shortcut`, so the hint the palette draws and the key that fires stay one spelling.
+
+**Filtering** matches every typed word, in any order, against a string `label` and the command's `keywords`, ignoring case and accents: `uber` finds `Übersicht`. Within each group, a label starting with the query comes first, then a label word or a keyword starting with it, then any other match, and the group holding the best match moves to the top. A heading moves with its group and stays above it while any of it matches; separators are dropped while a query is typed. Typing highlights the best match, so Enter runs it. A `label` that is not a string cannot be read, so give such a command `keywords`.
+
+**Server results.** Set `filter={false}` and the palette shows `items` exactly as given, so they can be the results of your own search:
+
+```tsx
+const [results, setResults] = useState<MenuEntry[]>(commands);
+const [isLoading, setLoading] = useState(false);
+
+<CommandPalette
+  items={results}
+  filter={false}
+  isLoading={isLoading}
+  onQueryChange={(query) => {
+    if (!query) return setResults(commands);
+    setLoading(true);
+    searchCustomers(query).then((hits) => {
+      setResults(hits.map((c) => ({ id: c.id, label: c.name, onClick: () => navigate(`/customers/${c.id}`) })));
+      setLoading(false);
+    });
+  }}
+  isOpen={isOpen}
+  onClose={() => setOpen(false)}
+/>;
+```
+
+`onQueryChange` fires on every keystroke and with `''` each time the palette opens, so debounce the request and drop a response that arrives after a newer query. Between keystrokes the highlight follows the command's `id`, so it stays put while results arrive and are replaced around it.
+
+**Keyboard:** the focus stays in the search field. ↑ and ↓ move the highlight, wrapping and skipping disabled commands, Enter runs it, and Escape closes. Running a command calls its own `onClick`, then `onAction`, then `onClose`, the same order `Menu` uses. The number of matches is announced to screen readers as it changes.
+
+On a small touch screen it can present as a bottom sheet like every `Modal`: pass `presentation={Presentation.Auto}`, or set it app-wide through `ConfigProvider`.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `MenuEntry[]` | The commands. Headings group them; separators split groups (required) |
+| `isOpen` | `boolean` | Whether the palette is open (required) |
+| `onClose` | `() => void` | Called on Escape, a backdrop click, and after a command runs (required) |
+| `onAction` | `(id: string) => void` | Called with the id of the command that ran, after its own `onClick` |
+| `onQueryChange` | `(query: string) => void` | Called on every keystroke, and with `''` on open |
+| `filter` | `boolean` | Filter `items` by the query (default `true`). `false` shows them as given |
+| `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` and `onClick`. See [Menu.md](Menu.md).
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CommandPalette: { presentation: Presentation.Auto } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `search` `input` `list` `item` `itemIcon` `itemLabel` `itemShortcut` `heading` `separator` `empty`
+
+**Labels:** `label` `placeholder` `empty` `loading` `results(count)`: the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `CommandPaletteLabels`.

package/docs/ConfigProvider.md

@@ -92,8 +92,8 @@ A nested provider inherits it unless it sets its own, the same way `defaultProps
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
-- **Display:** `Button` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer`
-- **Overlays:** `ConfirmModal` · `Modal` · `Popover` · `Popover`
+- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
+- **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 
 ```tsx

package/docs/CopyButton.md

@@ -0,0 +1,45 @@
+# CopyButton
+
+**When to use:** Icon-only button that copies a value to the clipboard: an invoice number, an ID in a table row, an API key or share link inside an `Input`. For a labelled "Copy link" button, use `Button` with the `useClipboard` hook instead (see [Hooks.md](Hooks.md)).
+
+**Keywords:** token, secret, reference number, snippet
+
+**Import:** `import { CopyButton } from '@ahrowe/ui'`  
+**Types:** `import type { CopyButtonProps, CopyButtonLabels } from '@ahrowe/ui'`
+
+```tsx
+import { CopyButton, Input } from '@ahrowe/ui';
+
+<span>
+  {invoice.number} <CopyButton value={invoice.number} />
+</span>
+
+// inside a field
+<Input label='API key' value={apiKey} readOnly suffix={<CopyButton value={apiKey} />} />
+
+// a toast on success, where the button is not where the user is looking
+<CopyButton value={url} onCopy={() => showToast('Link copied', { type: 'success' })} />
+```
+
+After a click the icon rotates into a check (through `AnimatedIcon`, held still under `prefers-reduced-motion`) for `timeout` ms, the accessible name and tooltip read "Copied", and a polite live region announces it, because a swapped icon or a changed `aria-label` alone is not read out. A refused write (an insecure context, a blocked iframe) announces "Could not copy" and calls `onError`; the icon stays as it was. `CopyButton` shows no toast of its own: pass one through `onCopy` / `onError` if you want it.
+
+The live region is rendered as a sibling of the button, so `CopyButton` returns two elements. It is visually hidden and takes no space.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Text written to the clipboard on click (required) |
+| `timeout` | `number` | How long the copied state shows, in ms (default `2000`) |
+| `icon` | `IconDefinition \| ReactElement` | Icon before copying (default `faCopy`). The swap animates only when both icons are FontAwesome definitions |
+| `copiedIcon` | `IconDefinition \| ReactElement` | Icon while copied (default `faCheck`) |
+| `onCopy` | `(value: string) => void` | Called after a successful copy |
+| `onError` | `() => void` | Called when the clipboard refuses the write. `useClipboard` returns the reason |
+| `onClick` | `(event: MouseEvent) => void` | Called on every click, before the copy |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the button |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CopyButton: { timeout: 1500 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `icon`
+
+**Labels:** `copy` `copied` `failed`: the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `CopyButtonLabels`.

package/docs/DatePicker.md

@@ -2,72 +2,58 @@
 
 **When to use:** Date selection input — booking forms, birth date fields, date range pickers, deadline selectors. Renders as a text input with a floating label by default; can also be inline or modal.
 
-**Keywords:** calendar picker
+**Keywords:** calendar picker, timezone, ISO date, date string, day picker
 
 **Keyboard:** the day grid uses a roving tab stop (the selected day, or today, or the 1st — one Tab reaches it, not every day individually); arrow keys move by day (`←`/`→`) or by week (`↑`/`↓`), crossing into the adjacent month automatically when they run past the edge, and Enter/Space selects the focused day.
 
-**Import:** `import { DatePicker } from '@ahrowe/ui'`  
+**Import:** `import { DatePicker, dateToDay, dayToDate } from '@ahrowe/ui'`  
 **Types:** `import type { DatePickerProps } from '@ahrowe/ui'`
 
 ```tsx
-import { DatePicker, FormValidator } from '@ahrowe/ui';
+import { DatePicker, FormValidator, dateToDay } from '@ahrowe/ui';
 
-// Controlled input with floating label
-<DatePicker
-  label="Date of birth"
-  selected={date}
-  onSelect={(date) => setDate(date)}
-/>
+// Controlled input with floating label. The value is a day: '2026-09-15'
+const [day, setDay] = useState<string | null>(null);
+<DatePicker label="Date of birth" selected={day} onSelect={setDay} />
 
 // With FormValidator
-const dateValidator = new FormValidator<Date | null>(null);
-<DatePicker label="Start date" formValidator={dateValidator} />
+const dayValidator = new FormValidator<string | null>(null);
+<DatePicker label="Start date" formValidator={dayValidator} />
 
 // Inline calendar (no input field)
-<DatePicker
-  selected={date}
-  onSelect={setDate}
-  isInline
-  noInput
-/>
+<DatePicker selected={day} onSelect={setDay} isInline noInput />
 
 // Inside a modal (calendar opens in a Modal overlay)
-<DatePicker
-  label="Schedule date"
-  selected={date}
-  onSelect={setDate}
-  isModal
-/>
+<DatePicker label="Schedule date" selected={day} onSelect={setDay} isModal />
 
-// With min/max constraints and a clear button
+// From today to the end of the year, with a clear button
 <DatePicker
   label="Appointment"
-  selected={date}
-  onSelect={setDate}
-  minDate={new Date()}
-  maxDate={endOfYear}
+  selected={day}
+  onSelect={setDay}
+  minDate={dateToDay(new Date())}
+  maxDate="2026-12-31"
   showClearButton
 />
 
-// Date range (highlight start–end)
-<DatePicker
-  label="From"
-  selected={startDate}
-  onSelect={setStartDate}
-  startDate={startDate}
-  endDate={endDate}
-/>
+// Range: two pickers sharing a highlighted start and end
+<DatePicker label="From" selected={from} onSelect={setFrom} startDate={from} endDate={to} />
+<DatePicker label="To" selected={to} onSelect={setTo} startDate={from} endDate={to} minDate={from} />
 ```
 
+**A day, not a moment:** every day DatePicker takes or hands out is a `'YYYY-MM-DD'` string, the value an `<input type="date">` has. It has no time and no time zone, so it is the same day for everyone who sees it. The strings sort as the days do, so `from < to` compares two of them. `null`, `''` and anything that is not a real day, such as `'2026-02-30'`, mean no value; anything but the first two also logs a warning naming the prop, once.
+
+`dateToDay(date)` and `dayToDate(day)` convert to and from a `Date` in the browser's time zone: `dateToDay(new Date())` is today, `dayToDate(day)` the first moment of that day. Do not use `date.toISOString().slice(0, 10)`: that is the day in UTC, which in Vienna shortly after midnight is still yesterday.
+
 **Key props:**
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `label` | `string` | Floating label on the input |
-| `selected` | `Date` | Currently selected date |
-| `onSelect` | `(date: Date \| null) => void` | Called when a date is picked |
-| `onChange` | `(date: Date \| null) => void` | Alternative change callback |
-| `formValidator` | `FormValidator` | Connects to validation |
+| `selected` | `string \| null` | Selected day, `'YYYY-MM-DD'` |
+| `onSelect` | `(day: string \| null) => void` | Called when a day is picked in the calendar |
+| `onChange` | `(day: string \| null) => void` | Called on every change, picked or typed |
+| `formValidator` | `FormValidator<string \| null>` | Connects to validation, and then owns the value. `new FormValidator(null)` and `new FormValidator('')` fit too |
 | `isRequired` | `boolean` | |
 | `isValid` | `boolean` | Manual valid state |
 | `errorMessage` | `string` | Manual error message |
@@ -75,12 +61,53 @@ const dateValidator = new FormValidator<Date | null>(null);
 | `noHeader` | `boolean` | Hide the month/year navigation header |
 | `isModal` | `boolean` | Open calendar in a Modal overlay |
 | `isInline` | `boolean` | Render calendar always-visible inline |
-| `minDate` | `Date \| null` | Earliest selectable date |
-| `maxDate` | `Date \| null` | Latest selectable date |
+| `minDate` | `string \| null` | Earliest selectable day |
+| `maxDate` | `string \| null` | Latest selectable day |
 | `showClearButton` | `boolean` | Show a clear/reset button |
-| `startDate` | `Date` | Range highlight start |
-| `endDate` | `Date` | Range highlight end |
+| `startDate` | `string \| null` | Range highlight start |
+| `endDate` | `string \| null` | Range highlight end |
 
 **Slots:** `root` `input` `header` `monthDropdown` `yearDropdown` `calendar` `clearButton`
 
-The root also takes the full native attribute set (`id`, `data-*`, `aria-*`, `title`, event handlers). `onChange` and `onSelect` report a `Date`, so the native handlers of those names are not available.
+The root also takes the full native attribute set (`id`, `data-*`, `aria-*`, `title`, event handlers). `onChange` and `onSelect` report a day, so the native handlers of those names are not available.
+
+## When a day stands for a moment
+
+A poll that closes on a day, a booking that starts on one, a deadline: here the day has to become a moment, and only your app knows in which time zone and at which point of the day. Store the moment itself (a UTC timestamp), and show it in the time zone of whoever reads it.
+
+In the user's own time zone the platform is enough:
+
+```ts
+const start = dayToDate(day); // the first moment of the day, where the user is
+```
+
+In a given zone, a company's, a household's, a venue's, use a library that knows time zones, such as Luxon. Name the zone (`'Europe/Vienna'`), not its offset (`+02:00`): the offset changes with daylight saving.
+
+```ts
+import { DateTime } from 'luxon';
+
+// Closes at the end of the day in Vienna, wherever the reader is.
+const closesAt = DateTime.fromISO(day, { zone: 'Europe/Vienna' }).endOf('day').toJSDate();
+
+// And back, for the picker: the day that moment falls on in Vienna.
+const shown = DateTime.fromJSDate(closesAt, { zone: 'Europe/Vienna' }).toISODate();
+```
+
+With a [TimeInput](TimeInput.md) next to it, which holds `'HH:MM'`, the two make a moment the same way: ``DateTime.fromISO(`${day}T${time}`, { zone })``, or, in the user's own zone, `dayToDate(day)` followed by `setHours(hours, minutes)`.
+
+## Migration from Date values
+
+Before 0.39 every day was a `Date` at midnight UTC. Now it is a `'YYYY-MM-DD'` string, and TypeScript points at each place to change, because a `Date` no longer fits any of the props. Two things still get through: a `Date` in plain JavaScript or through a validator typed as `FormValidator<any>`, and a stored value read back as its JSON, `'2026-09-15T00:00:00.000Z'`, which is a string to TypeScript. DatePicker shows either as an empty field, logs a warning naming the prop, and leaves the value alone until the user actually edits the field.
+
+| Before | After |
+|--------|-------|
+| `useState<Date \| null>(null)` | `useState<string \| null>(null)` |
+| `new FormValidator<Date \| null>(null)` | `new FormValidator<string \| null>(null)` |
+| `selected={new Date()}`, `minDate={new Date()}` | `selected={dateToDay(new Date())}` |
+| `a.getTime() < b.getTime()` | `a < b` |
+| `date.toLocaleDateString(locale)` | `dayToDate(day).toLocaleDateString(locale)` |
+| `JSON.stringify(date)`, `date.toISOString()` | the string itself |
+
+Data you already stored from DatePicker was midnight UTC of the picked day. `stored.toISOString().slice(0, 10)` turns exactly that back into the day, since the value was built in UTC; do this only for values DatePicker produced.
+
+Where the value was really a moment (the poll and deadline cases above), decide the time zone once, in your own code, as shown in the section before this one, rather than relying on what DatePicker happened to hand out.

package/docs/ErrorBoundary.md

@@ -65,7 +65,7 @@ import { ErrorBoundary } from '@ahrowe/ui';
 </ErrorBoundary>
 ```
 
-The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a labeled copy `Button` that fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
+The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a `CopyButton` that also fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
 
 **Key props:**
 
@@ -74,7 +74,7 @@ The default fallback is a centered card with a tinted icon badge, an `Accordion`
 | `children` | `ReactNode` | The subtree to protect |
 | `title` | `ReactNode` | Heading in the default fallback (default `"Something went wrong"`) |
 | `description` | `ReactNode` | Overrides the message shown under the title. Defaults to `error.message` |
-| `labels` | `ErrorBoundaryLabels` | Overrides for every other built-in string (stack trace label, copy/reset button text, copy toasts) — pass a translated set for non-English apps. See below |
+| `labels` | `ErrorBoundaryLabels` | Overrides for every other built-in string (stack trace label, copy button tooltip, reset button text, copy toasts) — pass a translated set for non-English apps. See below |
 | `fallback` | `ReactNode \| (props: ErrorBoundaryFallbackProps) => ReactNode` | Replaces the built-in fallback entirely. The render-function form receives `{ error, errorInfo, resetErrorBoundary }` |
 | `onError` | `(error: Error, errorInfo: ErrorInfo) => void` | Called once per catch — the place to report to Sentry/Datadog/etc. |
 | `onReset` | `() => void` | Called after the boundary is reset, whether via the built-in "Try again" button, a custom fallback calling `resetErrorBoundary`, or a `resetKeys` change. Use it to re-arm whatever state caused the crash |
@@ -86,8 +86,8 @@ The default fallback is a centered card with a tinted icon badge, an `Accordion`
 | Field | Default | Description |
 |-------|---------|--------------|
 | `stackTrace` | `"Stack trace"` | Accordion header for the stack trace section |
-| `copy` | `"Copy"` | Copy button label before copying |
-| `copied` | `"Copied"` | Copy button label right after a successful copy |
+| `copy` | `"Copy"` | Copy button tooltip and accessible name before copying |
+| `copied` | `"Copied"` | Copy button tooltip and accessible name right after a successful copy |
 | `reset` | `"Try again"` | Reset button label |
 | `copySuccessToast` | `"Stack trace copied to clipboard"` | Toast shown after a successful copy (only visible if `ToastProvider` is mounted) |
 | `copyErrorToast` | `"Could not copy stack trace"` | Toast shown if the copy fails |

package/docs/Fab.md

@@ -22,7 +22,6 @@ import { faPlus, faPen, faCamera } from '@fortawesome/free-solid-svg-icons';
     { id: 'photo', icon: faCamera, label: 'Photo' },
   ]}
   onMenuEntryClicked={(id) => handleAction(id)}
-  closeMenuOnEntryClicked
 />
 
 // Mini size
@@ -38,7 +37,7 @@ import { faPlus, faPen, faCamera } from '@fortawesome/free-solid-svg-icons';
 | `size` | `'default' \| 'mini'` | Button size |
 | `menuEntries` | `FabMenuEntry[]` | `{ id, icon, label? }` — enables speed dial |
 | `onMenuEntryClicked` | `(id: string) => void` | Sub-menu entry handler |
-| `closeMenuOnEntryClicked` | `boolean` | Auto-close menu after selection |
+| `closeMenuOnEntryClicked` | `boolean` | Close the menu after an entry is picked (default `true`) |
 | `onClick` | `() => void` | Simple click handler (no speed dial) |
 | `children` | `ReactNode` | FAB icon content |
 

package/docs/FormValidator.md

@@ -32,7 +32,7 @@ nameValidator.dirty                    // value has changed since creation
 > | Field | Default value |
 > |-------|---------------|
 > | string (text, email, …) | `''` |
-> | `Date` | `null` |
+> | day (`DatePicker`, `'YYYY-MM-DD'`) | `null` |
 > | number | `undefined` (or `0`) |
 > | checkbox / boolean | `false` |
 > | single-select id | `null` |
@@ -69,7 +69,7 @@ function NameField() {
 
 ```tsx
 const ageValidator    = new FormValidator<number | undefined>(undefined, [Validators.required()]);
-const dateValidator   = new FormValidator<Date | null>(null);
+const dayValidator    = new FormValidator<string | null>(null); // DatePicker: '2026-09-15'
 const agreedValidator = new FormValidator<boolean>(false, [Validators.required()]);
 ```
 
@@ -108,7 +108,7 @@ Validators.multiEmail(errorMsg?)           // comma/semicolon-separated list of
 Validators.mustBeNumber(errorMsg?)         // parses as a number
 Validators.oneOf(allowedValues, errorMsg?) // value is in the allowed array
 Validators.typeOf(allowedTypes, errorMsg?) // typeof value matches (string or string[])
-Validators.date(errorMsg?)                 // valid date string (DD.MM.YYYY or ISO)
+Validators.date(errorMsg?)                 // a real date: a 'YYYY-MM-DD' day (DatePicker), DD.MM.YYYY, a toISOString() timestamp, or a valid Date
 Validators.dateObject(errorMsg?)           // an object with an `isValid` flag (e.g. a date wrapper)
 Validators.website(errorMsg?)              // valid URL
 Validators.bic(errorMsg?)                  // valid BIC/SWIFT code

package/docs/Hooks.md

@@ -1,11 +1,11 @@
 # Hooks
 
-**When to use:** Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay.
+**When to use:** Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, copying to the clipboard, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay.
 
 **Keywords:** hotkey, keybinding, keyboard shortcut, cmd+k, command palette, breakpoint, responsive, touch device, on-screen keyboard, focus trap, scroll lock, swipe
 
-**Import:** `import { useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, tabbablesIn } from '@ahrowe/ui'`
-**Types:** `import type { HotkeyMap, HotkeyHandler, UseHotkeysOptions, VisualViewportSize, ScrollEdges, ScrollEdgesOptions, UseSwipeDismissOptions, UseSwipeDismissResult, UseOverlayArgs } from '@ahrowe/ui'`
+**Import:** `import { useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, useClipboard, tabbablesIn } from '@ahrowe/ui'`
+**Types:** `import type { HotkeyMap, HotkeyHandler, UseHotkeysOptions, VisualViewportSize, ScrollEdges, ScrollEdgesOptions, UseSwipeDismissOptions, UseSwipeDismissResult, UseOverlayArgs, UseClipboardOptions, UseClipboardResult } from '@ahrowe/ui'`
 
 ---
 
@@ -211,6 +211,42 @@ function CustomOverlay({ isOpen, onClose, children }) {
 
 Reach for [Modal.md](Modal.md) or [Drawer.md](Drawer.md) first; this is for an overlay they do not cover.
 
+## useClipboard
+
+Writes text to the clipboard and reports how it went. For the usual icon-only copy control, use
+[CopyButton.md](CopyButton.md), which is this hook plus the feedback and the screen-reader
+announcement. Reach for the hook when the trigger is something else, such as a labelled `Button`:
+
+```tsx
+const { copy, copied } = useClipboard();
+
+<Button icon={copied ? faCheck : faCopy} onClick={() => void copy(shareUrl)}>
+  {copied ? 'Copied' : 'Copy link'}
+</Button>;
+```
+
+`copy(text)` resolves `true` on success and `false` on failure, so it never needs a `try`:
+
+```tsx
+const ok = await copy(invoice.number);
+showToast(ok ? 'Copied' : 'Could not copy', { type: ok ? 'success' : 'error' });
+```
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `timeout` | `number` | `2000` | How long `copied` stays `true` after a copy, in ms |
+
+| Returns | Type | Description |
+| ------- | ---- | ----------- |
+| `copy` | `(text: string) => Promise<boolean>` | Writes `text`; a second copy restarts the timeout |
+| `copied` | `boolean` | `true` for `timeout` ms after a successful copy |
+| `error` | `Error \| null` | Why the last copy failed, until the next attempt |
+| `reset` | `() => void` | Clears `copied` and `error` early |
+
+It uses `navigator.clipboard.writeText` only. That API needs a secure context (`https://` or
+`localhost`) and may be blocked inside an iframe; there it fails through `error` rather than falling
+back to the deprecated `document.execCommand('copy')`.
+
 ## tabbablesIn
 
 The tabbable descendants of an element, in DOM order. An element taken out of the tab order with

package/docs/InputDropdown.md

@@ -5,7 +5,7 @@
 **Keywords:** autocomplete, typeahead
 
 **Import:** `import { InputDropdown } from '@ahrowe/ui'`  
-**Types:** `import type { InputDropdownItem, InputDropdownProps } from '@ahrowe/ui'`
+**Types:** `import type { InputDropdownItem, InputDropdownLabels, InputDropdownProps } from '@ahrowe/ui'`
 
 ```tsx
 import { InputDropdown } from '@ahrowe/ui';
@@ -63,6 +63,7 @@ interface InputDropdownItem {
 | `onChange` | `(value: unknown) => void` | Called on every text change |
 | `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 |
 | `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` |
@@ -78,8 +79,12 @@ Inside a `<form>`, `Enter` on a highlighted suggestion picks it without submitti
 with nothing highlighted submits as any text field would. So cycling to your own text and pressing
 `Enter` twice is the way to submit exactly what you typed. `Home` and `End` are left to the text field, so they move the caret.
 
-**Slots:** `root` `dropdown` `item`
+**Nothing to show:** the list only opens when it has something in it. With `allowCustomValue` a search that matches nothing closes it, since the typed text is kept anyway, and it reopens as soon as something matches again. Without `allowCustomValue` the typed text is thrown away on blur, so a `No matches` row says so while the user is still typing, and a screen reader announces it. Nothing typed yet opens nothing in either mode, including a preset value that `items` does not contain.
 
-Long lists are handled by capping how many matches are rendered (`maxItems`, default `100`) rather than by virtualizing: only about six rows fit in the scroll box, so anything past the cap is DOM the user never sees. Raise `maxItems` (or set it to `0`) if a list is genuinely meant to be scrolled end to end. For lists too large to pass as `items` at all, fetch on the server, keep the results in your own state and feed them in as `items`.
+**Labels:** `empty` (shown when nothing matches and `allowCustomValue` is off, default `No matches`): the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `InputDropdownLabels`.
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). The panel itself is a [Popover](Popover.md), so it flips, clamps and presents as a bottom sheet the same way every other anchored surface in the library does. It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.
+**Slots:** `root` `dropdown` `item` `empty`
+
+Long lists are handled by capping how many matches are rendered (`maxItems`, default `100`) rather than by virtualizing: only about six rows fit in the scroll box, so anything past the cap is DOM the user never sees. Raise `maxItems` (or set it to `0`) if a list is genuinely meant to be scrolled end to end. For lists too large to pass as `items` at all, fetch on the server, keep the results in your own state and feed them in as `items`. Without `allowCustomValue`, say so while a fetch runs, or the field reports `No matches` for results that have not arrived yet: `labels={{ empty: isFetching ? 'Loading…' : 'No matches' }}`.
+
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). The panel itself is a [Popover](Popover.md), so it flips and clamps the same way every other anchored surface in the library does. It is never a bottom sheet, whatever `presentation` a `ConfigProvider` sets: the field being typed into is the trigger, and a sheet would cover it with its backdrop and open the list away from it, below an on-screen keyboard. It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/Menu.md

@@ -29,11 +29,13 @@ const items: MenuEntry[] = [
 **Entries** are one of three shapes, and the list is read in the order you give it:
 
 ```ts
-{ id: 'edit', label: 'Edit', icon, shortcut, disabled, danger, onClick }  // an action
-{ separator: true }                                                       // a line
-{ heading: 'This document' }                                              // a label over what follows
+{ id: 'edit', label: 'Edit', icon, shortcut, keywords, disabled, danger, onClick }  // an action
+{ separator: true }                                                                 // a line
+{ heading: 'This document' }                                                        // a label over what follows
 ```
 
+`keywords` are extra search terms for [CommandPalette](CommandPalette.md), which takes the same entries. The menu ignores them.
+
 **Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows.
 
 Listening for it is yours, because only your app knows what else is listening: if it already binds `⌘S` and the menu bound it too, both would fire and the action would run twice. `menuHotkeys` turns the same entries into a map for `useHotkeys`, so the one spelling covers the hint and the binding:

package/docs/Popover.md

@@ -28,6 +28,18 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 <Popover isOpen={open} onOpenChange={setOpen} content={<Form onDone={() => setOpen(false)} />}>
   <button>Edit</button>
 </Popover>
+
+// One popover for many elements it does not wrap: a calendar's events, a table's cells
+const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+{events.map((event) => (
+  <button key={event.id} onClick={(e) => setAnchor(e.currentTarget)}>{event.title}</button>
+))}
+<Popover
+  anchor={anchor}
+  isOpen={anchor !== null}
+  onOpenChange={(open) => !open && setAnchor(null)}
+  content={<EventDetails />}
+/>
 ```
 
 **PopoverPlacement enum:** `PopoverPlacement.Top` | `Bottom` | `Left` | `Right` — the preferred side; auto-flips to the opposite side when there's no room.
@@ -44,6 +56,7 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 |------|------|---------|-------------|
 | `content` | `ReactNode` | — | Panel body |
 | `children` | `ReactNode` | — | Trigger element |
+| `anchor` | `HTMLElement \| null` |  | Place the panel against this element instead of `children`. Open it with `isOpen`; `children` can be left out. A click on it is not an outside click, Escape returns the focus to it, and changing it while open moves the panel. `null` falls back to `children` |
 | `placement` | `PopoverPlacement` | `Bottom` | Preferred side |
 | `align` | `PopoverAlign` | `Center` | Cross-axis alignment |
 | `trigger` | `PopoverTrigger` | `Click` | What opens the popover |
@@ -80,3 +93,5 @@ Requires a `<div id="bodyEnd"></div>` at the app root — the panel is portaled
 **Scrolling:** where the browser supports CSS anchor positioning, including the trigger's transforms, the panel is anchored to the trigger in CSS, so it moves with a scrolling trigger in the same frame instead of catching up a frame later. Firefox resolves anchors without transforms, so it keeps the pixel positioning. While it is open the trigger carries an inline `anchor-name`, added to any inline one it already has; an `anchor-name` your stylesheet gives the trigger is overridden for that time.
 
 **Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content and the keyboard opened it (Enter or Space on the trigger, or ArrowDown/ArrowUp), focus moves to the first focusable element and the panel gets `role="dialog"`; a pointer click leaves the focus where it already is. `focusOnOpen` forces either. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. This is non-modal: focus is not trapped, and hover/focus triggers don't steal focus. Escape closes only the innermost open layer, so a popover inside a `Modal` closes on the first press and leaves the modal open. Popovers with only static content don't manage focus or claim the dialog role.
+
+**Anchored (`anchor`):** your code opens the panel, not a key event Popover sees, so the default `focusOnOpen` looks at the click that opened it: Enter or Space on the anchor or on something inside it (a click with `detail === 0`) moves the focus into the panel, a pointer click leaves it where it is, and an open with no click at all, such as suggestions appearing while the user types into an anchored field, never takes it. Escape, Tab and Shift+Tab out of the panel continue from the anchor as they would from a trigger: from the anchor itself when it takes focus, otherwise from the first focusable element inside it.

package/docs/WeatherIcon.md

@@ -0,0 +1,49 @@
+# WeatherIcon
+
+**When to use:** An animated weather symbol for a forecast, a dashboard widget or a day selector, one per condition a forecast reports. For a static pictogram of anything else, use a FontAwesome icon.
+
+**Keywords:** forecast, rain, snow, sun, cloud, storm, climate, meteo
+
+**Import:** `import { WeatherIcon, WeatherType } from '@ahrowe/ui'`  
+**Types:** `import type { WeatherIconProps, WeatherIconLabels } from '@ahrowe/ui'`
+
+```tsx
+import { WeatherIcon, WeatherType } from '@ahrowe/ui';
+
+<WeatherIcon type={WeatherType.Rainy} />
+
+// Any CSS size; a number is pixels
+<WeatherIcon type={WeatherType.Snowy} size='3em' />
+
+// A still frame, for small or repeated icons such as a row of days
+<WeatherIcon type={WeatherType.PartlyCloudy} size={32} animated={false} />
+```
+
+**Enums:** `WeatherType`: `Sunny` · `ClearNight` · `Cloudy` · `PartlyCloudy` · `PartlyCloudyNight` · `RainyLight` · `Rainy` · `RainyHeavy` · `Snowy` · `Hail` · `Foggy` · `Thunderstorm`
+
+**Your API's own enum works as it is.** `type` takes the enum or its string value (`'rainy'`, `'partlyCloudy'`), so a backend enum with the same values passes without a mapping, even though TypeScript treats two enums as different types.
+
+**Colour** is the text colour it sits in (`currentColor`), like any icon. Set `color` on it or on a parent:
+
+```tsx
+<WeatherIcon type={WeatherType.Sunny} style={{ color: 'var(--warn-color)' }} />
+```
+
+**Motion.** Clouds drift, rain and snow fall, hail bounces, lightning flashes twice every four seconds. Under `prefers-reduced-motion` it draws the same still frame as `animated={false}`: each drop, flake and stone frozen at a different point of its fall rather than all bunched under the cloud. `animated={false}` is also worth setting on a long row of small icons, where the motion is too small to see but costs the same. Set it app-wide through `ConfigProvider`.
+
+**Accessibility.** The svg is `role="img"` and named after the weather ("Heavy rain"). Where the text next to it already says the same, pass `aria-hidden`.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `type` | `WeatherType \| string value` | The weather to draw (required) |
+| `size` | `number \| string` | Width and height. A number is pixels (default `64`) |
+| `animated` | `boolean` | `false` draws a still frame (default `true`). Always still under reduced motion |
+| `labels` | `WeatherIconLabels` | The accessible name of each weather |
+
+The native svg attributes (`className`, `style`, `aria-*`, `data-*`, handlers) reach the `<svg>`.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ WeatherIcon: { animated: false } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Labels:** one key per `WeatherType` value, `sunny` to `thunderstorm`: the accessible name of each weather. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `WeatherIconLabels`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",
@@ -88,7 +88,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@ahrowe/form-validation": "^0.2.0",
+    "@ahrowe/form-validation": "^0.3.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -128,7 +128,6 @@
     "publint": "^0.3.24",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "react-element-to-jsx-string": "^17.0.1",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.1",
     "remark-gfm": "^4.0.1",