@ahrowe/ui 0.37.0 → 0.38.0

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/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.38.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",
@@ -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",