@ahrowe/ui 0.19.4 → 0.21.0

package/docs/OtpInput.md

@@ -0,0 +1,92 @@
+# OtpInput
+
+**When to use:** A one-time-passcode / verification-code input, rendered as one box per character. Typing a character auto-advances to the next box, Backspace on an empty box steps back to the previous one, arrow keys move freely between boxes, and pasting a full code (or an SMS autofill suggestion) fills every box at once instead of just the focused one.
+
+**Keywords:** otp, 2fa, mfa, verification code, sms code, passcode, pin code, two-factor
+
+**Import:** `import { OtpInput, OtpInputCharset } from '@ahrowe/ui'`
+
+**Requires:** `<div id="bodyEnd"></div>` in your HTML (the error message renders via `Tooltip`, which portals).
+
+**Charset:** `OtpInputCharset.Numeric` (default) | `OtpInputCharset.Alphanumeric`
+
+```tsx
+import { useState } from 'react';
+import { OtpInput, OtpInputCharset } from '@ahrowe/ui';
+
+// Basic — 6 numeric boxes, controlled
+const [code, setCode] = useState('');
+<OtpInput value={code} onChange={setCode} />
+
+// React once the code is fully entered — e.g. auto-submit for verification
+<OtpInput
+  onComplete={(code) => verifyCode(code)}
+/>
+
+// Labeled and required
+<OtpInput label="Verification code" isRequired autoFocus />
+
+// Fewer/more boxes, and a non-numeric charset (e.g. a backup/recovery code)
+<OtpInput length={4} charset={OtpInputCharset.Alphanumeric} value={code} onChange={setCode} />
+
+// Masked, like a password field
+<OtpInput masked value={code} onChange={setCode} />
+
+// Visually split into groups, e.g. 3 + 3
+<OtpInput groupAfter={[3]} value={code} onChange={setCode} />
+
+// Manual error state (e.g. after a failed verification call)
+<OtpInput
+  value={code}
+  onChange={setCode}
+  isValid={!wasRejected}
+  errorMessage="That code didn't match. Try again."
+/>
+
+// Auto-clear on error — once isValid turns false, the wrong code and error message stay
+// visible briefly, then every box clears and refocuses the first one for a clean retry
+<OtpInput
+  value={code}
+  onChange={setCode}
+  onComplete={verifyCode}
+  isValid={!wasRejected}
+  errorMessage="That code didn't match. Try again."
+  clearOnError
+/>
+
+// With FormValidator
+import { FormValidator, Validators } from '@ahrowe/ui';
+const codeValidator = new FormValidator('', [Validators.required(), Validators.minLength(6)]);
+<OtpInput formValidator={codeValidator} />
+```
+
+**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.
+
+**`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.
+
+**Handling a failed verification (`clearOnError`):** when the code the user entered turns out to be wrong, don't leave it sitting there for them to correct digit-by-digit — set `clearOnError` so that once `isValid`/`formValidator` newly reports invalid, the boxes shake briefly (respecting `prefers-reduced-motion`) and, after `clearErrorDelay` (default `900`ms — long enough to read the error message first), every box clears and focus returns to the first one, ready for a clean retry. This is the standard pattern used by most OTP UIs (a wrong SMS/authenticator code almost always means the user misread the whole code, not mistyped one digit). Off by default, since the consumer's own error handling (e.g. a form-level retry flow) may prefer to leave the value in place instead.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `length` | `number` | Number of boxes (default `6`) |
+| `value` | `string` | Controlled code, e.g. `"123456"` |
+| `onChange` | `(value: string) => void` | Fires on every change with the current (possibly partial) code |
+| `onComplete` | `(value: string) => void` | Fires once the code reaches `length` characters |
+| `formValidator` | `FormValidator` | Connects to form validation |
+| `charset` | `OtpInputCharset` | Restricts allowed characters and picks the mobile keyboard (default `Numeric`) |
+| `masked` | `boolean` | Renders each box's value as a dot, like a password field |
+| `groupAfter` | `number[]` | 1-based box indices after which a small visual gap is drawn, e.g. `[3]` for 3 + 3 |
+| `label` | `string` | Label above the boxes |
+| `isRequired` | `boolean` | Shows a required mark (`*`) next to the label |
+| `isValid` | `boolean` | Manual valid state (default `true`) |
+| `errorMessage` | `string` | Manual error message, shown in an error `Tooltip` on focus/hover (falls back to `formValidator`'s current error) |
+| `clearOnError` | `boolean` | Once an error newly appears, shake the boxes and, after `clearErrorDelay`, clear them and refocus the first one (default `false`) |
+| `clearErrorDelay` | `number` | Delay in ms before `clearOnError` clears the boxes (default `900`) |
+| `disabled` | `boolean` | |
+| `autoFocus` | `boolean` | Focuses the first empty box (or the first box) on mount |
+
+**Slots:** `root` `label` `inputs` `input` `separator`

package/docs/Rating.md

@@ -55,7 +55,7 @@ import { faHeart } from '@fortawesome/free-solid-svg-icons';
 | `allowClear` | `boolean` | Clicking the currently-selected star resets the value to `0` (default `true`) |
 | `readOnly` | `boolean` | Display only, not focusable or interactive |
 | `disabled` | `boolean` | Dims the control and disables interaction |
-| `icon` | `IconDefinition` | Overrides the default star icon |
+| `icon` | `IconDefinition \| ReactElement` | Overrides the default star icon — FontAwesome icon or any React element |
 | `aria-label` | `string` | Accessible label (default `'Rating'`) |
 
 **Accessibility:** renders `role="slider"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext`, matching `Slider`'s pattern.

package/docs/SectionHeader.md

@@ -62,7 +62,7 @@ import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
 |------|------|-------------|
 | `title` | `ReactNode` | Main heading |
 | `subtitle` | `ReactNode` | Secondary text below the title |
-| `icon` | `IconDefinition` | FontAwesome icon shown on the left; ignored when `thumbnail` is set |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown on the left (FontAwesome icon or any React element); ignored when `thumbnail` is set |
 | `thumbnail` | `string \| ReactNode` | URL → background image; any other ReactNode → rendered inside the leading circle |
 | `left` | `ReactNode` | Leftmost content of the trailing block (title stays fixed to the left of it) |
 | `center` | `ReactNode` | Center content of the trailing block, e.g. a search box or tabs |
@@ -76,7 +76,7 @@ import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
 ```ts
 interface SectionHeaderAction {
   title?: string;
-  icon: IconDefinition;
+  icon: IconDefinition | ReactElement;
   onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
 }
 ```

package/docs/Stepper.md

@@ -69,7 +69,7 @@ const steps = [
 | `label` | `ReactNode` | Primary step label |
 | `description` | `ReactNode` | Secondary line under the label |
 | `content` | `ReactNode` | Collapsible body under the label (vertical only) |
-| `icon` | `IconDefinition` | FontAwesome icon in the marker, replacing the number |
+| `icon` | `IconDefinition \| ReactElement` | Icon in the marker, replacing the number — FontAwesome icon or any React element |
 | `error` | `boolean` | Recolours the marker with `--stepper-error-color`; suppresses the checkmark |
 | `optional` | `boolean \| ReactNode` | `true` → an "Optional" hint; a node → custom hint text |
 | `disabled` | `boolean` | Never clickable, dimmed |

package/docs/TabHeader.md

@@ -56,7 +56,7 @@ function Example() {
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `string` | Unique identifier, matched against `currentTab` |
-| `icon` | `IconDefinition` | FontAwesome icon (always visible, incl. mobile) |
+| `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element (always visible, incl. mobile) |
 | `title` | `string` | Optional title next to the icon |
 | `subtitle` | `string` | Optional subtitle beneath the title |
 | `disabled` | `boolean` | Dim the tab and prevent selection |

package/docs/Timeline.md

@@ -87,7 +87,7 @@ function AuditLog() {
 | `title` | `ReactNode` | Primary label for the entry |
 | `description` | `ReactNode` | Secondary line under the title |
 | `timestamp` | `ReactNode` | Rendered next to the title, e.g. a date or relative time ("2 hours ago") |
-| `icon` | `IconDefinition` | FontAwesome icon shown in the marker instead of a plain dot |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown in the marker instead of a plain dot — FontAwesome icon or any React element |
 | `status` | `TimelineItemStatus` | Semantic marker colour (default `Default`) |
 | `content` | `ReactNode` | Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar |
 | `onClick` | `(event: MouseEvent<HTMLDivElement>) => void` | Makes the whole entry clickable, rendering it as an accessible button (`role="button"`, focusable, click and Enter both fire it). Omit to render a plain, non-interactive row |

package/docs/Timer.md

@@ -0,0 +1,141 @@
+# Timer
+
+**When to use:** A countdown timer with a depleting ring, add/remove-time and pause/cancel controls, and an imperative ref API. Built for step-by-step flows where a wait needs its own clock — a recipe step ("simmer for 9 minutes"), a rest interval, a checkout hold, a break timer. Each instance owns its own state, so several can run independently at once (e.g. one per recipe step).
+
+**Keywords:** countdown, cooking timer, stopwatch, recipe, kitchen timer, ring progress
+
+**Import:** `import { Timer } from '@ahrowe/ui'`
+**Types:** `import type { TimerProps, TimerHandle, TimerStatus } from '@ahrowe/ui'`
+
+```tsx
+import { Timer } from '@ahrowe/ui';
+
+// Basic countdown — starts automatically, built-in controls shown
+<Timer durationSeconds={9 * 60} />
+
+// With a label inside the ring
+<Timer durationSeconds={9 * 60} label="Simmer the sauce" />
+
+// Doesn't start until start() is called (see ref example below)
+<Timer durationSeconds={60} autoStart={false} />
+
+// Display only — no built-in controls
+<Timer durationSeconds={45} showControls={false} />
+
+// Only some controls — keep add/remove, hide pause and cancel
+<Timer durationSeconds={45} hidePauseButton hideCancelButton adjustSeconds={15} />
+
+// Smaller ring, thinner stroke
+<Timer durationSeconds={30} size="100px" strokeWidth={6} />
+
+// Depletes counter-clockwise instead of the default clockwise sweep
+<Timer durationSeconds={30} counterClockwise />
+
+// Urgent colour + heartbeat pulse kicks in earlier (last 25% instead of the default 10%)
+<Timer durationSeconds={60} urgentThreshold={0.25} />
+
+// Ambient sonar-style ripples expanding from the center while running
+<Timer durationSeconds={10 * 60} showRunningRipples label="Meditating" />
+
+// Completion sound and a browser Notification (both opt-in, both default off)
+<Timer
+  durationSeconds={5 * 60}
+  playSoundOnComplete
+  notifyOnComplete
+  notificationTitle="Timer done"
+  notificationBody="The pasta is ready"
+/>
+
+// Imperative control via ref — for a fully custom UI, or driving start()/pause() from
+// elsewhere on the page
+import { useRef } from 'react';
+import type { TimerHandle } from '@ahrowe/ui';
+
+function Example() {
+  const ref = useRef<TimerHandle>(null);
+  return (
+    <>
+      <Timer ref={ref} durationSeconds={60} showControls={false} autoStart={false} />
+      <button onClick={() => ref.current?.start()}>Start</button>
+      <button onClick={() => ref.current?.addTime(30)}>+30s</button>
+    </>
+  );
+}
+```
+
+**Not a controlled value:** `Timer` isn't a controlled numeric input like `Slider` — there's no `remainingSeconds` prop to drive from outside. `durationSeconds` seeds the countdown; from there it owns the ticking internally, exposing state via callbacks (`onTick`, `onComplete`, …) and the `TimerHandle` ref rather than a value a consumer sets on every tick. Changing `durationSeconds` after mount resets the timer to the new duration (see `resetOnDurationChange` below).
+
+**Direction:** the ring depletes clockwise by default, starting from 12 o'clock. Set `counterClockwise` to sweep the other way instead.
+
+**Controls:** the built-in row has remove-time / pause-resume / add-time, plus a cancel button underneath. `showControls={false}` hides the whole block; the individual `hide*Button` props hide one control while keeping the rest (e.g. a fixed-duration display-only step keeps pause/cancel but drops add/remove). The pause button doubles as a play/restart button whenever there's nothing to pause — titled "Start" for an idle timer that hasn't run yet, or "Restart" once completed or cancelled — so there's always a way to (re)start the countdown from the built-in controls alone, without wiring up a separate button via the ref. Add-time also stays available after completion and, if clicked, un-completes and resumes the countdown (the "oops, give it 2 more minutes" case).
+
+**Urgency and the heartbeat pulse:** once remaining time drops to `urgentThreshold` (default the last 10% of the original duration) the ring switches to `--timer-urgent-color` and, if `pulseOnUrgent` is set (default `true`), the ring gently scales in a breathing "heartbeat" — accelerating from a 1s to a 0.6s cycle in the final 5 seconds. Disable it with `pulseOnUrgent={false}` if the motion isn't wanted.
+
+`urgentThreshold`'s 10%-of-duration fraction gets vanishingly small on a short timer (10% of 5 seconds is half a second — barely long enough to register). `urgentMinSeconds` (default `3`) sets a floor in absolute seconds: the urgent state uses whichever of the two — the fraction or the floor — produces the larger window. It has no effect on longer timers, where the fraction alone already exceeds it.
+
+**Running ripples:** `showRunningRipples` (default `false`) shows a thin ring pulsing outward from the dial's own edge and fading out — a beacon/live-indicator-style halo, similar to a map's live-location dot. It starts right at the ring's boundary and only grows slightly beyond it, so it never overlaps the time readout or the progress ring itself. A new one spawns about once a second while `status === 'running'`, each animating through its own 3-second cycle independently, so several are visible overlapping at once. Pausing (or completing/cancelling) only stops *new* ones from spawning — whichever are already mid-flight keep animating through to a normal, faded finish rather than disappearing mid-cycle. Purely decorative: colour comes from `--timer-ripple-color` (falls back to `--timer-progress-color`/`--primary-color`), and it's disabled entirely under `prefers-reduced-motion: reduce`.
+
+**Sound and notifications (both opt-in, both default `false`):** `playSoundOnComplete` plays a short built-in chime on completion (override with your own clip via `soundUrl`); playback failures (autoplay policy, unsupported browser) are swallowed silently, never thrown. `notifyOnComplete` shows a browser `Notification` on completion — permission is requested lazily on the first `start()` (a user gesture, as browsers require), and a denied or unsupported Notification API fails completely silently, with no console warning. Note: `autoStart` firing on page load with no prior user interaction may itself have its permission prompt silently blocked by the browser — that's a platform limitation, not something `Timer` can work around.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `durationSeconds` | `number` | Starting duration in seconds (required) |
+| `autoStart` | `boolean` | Start ticking automatically on mount and on `durationSeconds` change (default `true`) |
+| `resetOnDurationChange` | `boolean` | A `durationSeconds` change restarts the countdown (`true`, default) or only updates the idle baseline (`false`) |
+| `onTick` | `(remainingMs: number) => void` | Fires roughly every 200ms while running |
+| `onComplete` | `() => void` | Fires exactly once when it reaches zero |
+| `onStart` / `onPause` / `onResume` / `onCancel` | `() => void` | Lifecycle callbacks |
+| `onAddTime` / `onRemoveTime` | `(seconds, newRemainingSeconds) => void` | Fires when time is adjusted, by button or ref |
+| `showControls` | `boolean` | Show the built-in control row (default `true`) |
+| `hideAddButton` / `hideRemoveButton` / `hidePauseButton` / `hideCancelButton` | `boolean` | Hide one control while keeping the rest |
+| `adjustSeconds` | `number` | Seconds added/removed per click (default `30`) |
+| `maxSeconds` | `number` | Optional cap on remaining time when adding |
+| `label` | `ReactNode` | Text under the time readout, inside the ring |
+| `formatTime` | `(remainingMs: number) => ReactNode` | Overrides the default `MM:SS` / `H:MM:SS` formatter |
+| `size` | `string` | Ring diameter, any CSS length (default `'160px'`) |
+| `strokeWidth` | `number` | Ring stroke width in px (default `10`) |
+| `counterClockwise` | `boolean` | Depletes counter-clockwise instead of the default clockwise sweep (default `false`) |
+| `urgentThreshold` | `number` | Fraction (0–1) of the original duration at which the urgent colour/pulse kicks in (default `0.1`) |
+| `urgentMinSeconds` | `number` | Floor, in seconds, for the urgent window — whichever of this or `urgentThreshold`'s fraction is larger wins (default `3`) |
+| `pulseOnUrgent` | `boolean` | Enables the heartbeat pulse once urgent (default `true`) |
+| `showRunningRipples` | `boolean` | Shows a beacon-style halo pulsing outward from the dial's edge while running (default `false`) |
+| `playSoundOnComplete` | `boolean` | Play the built-in (or `soundUrl`) chime on completion (default `false`) |
+| `soundUrl` | `string` | Overrides the built-in completion sound |
+| `soundVolume` | `number` | Completion sound volume, 0–1 (default `0.5`) |
+| `notifyOnComplete` | `boolean` | Show a browser Notification on completion (default `false`) |
+| `notificationTitle` / `notificationBody` | `string` | Notification text (body falls back to `label` when it's a string) |
+
+**`TimerHandle`** (via `ref`):
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Starts (or restarts, if idle/completed/cancelled) from the current duration |
+| `pause()` | Pauses a running timer |
+| `resume()` | Resumes a paused timer from where it left off |
+| `addTime(seconds)` | Adds seconds to the remaining time, clamped to `maxSeconds` if set |
+| `removeTime(seconds)` | Removes seconds, clamped to 0 (which completes the timer) |
+| `cancel()` | Stops and resets to idle at the original duration; does not fire `onComplete` |
+| `reset()` | Resets to idle at `durationSeconds` |
+| `getStatus()` | Returns the current `TimerStatus` synchronously |
+| `getRemainingMs()` | Returns the current remaining ms synchronously |
+
+**`TimerStatus`:** `'idle'` \| `'running'` \| `'paused'` \| `'completed'` \| `'cancelled'`
+
+**Theming:** override these CSS variables theme-wide via `ThemeProvider` or per instance via `style`; each falls back to a built-in default:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--timer-track-color` | `var(--background-accent-light)` |
+| `--timer-progress-color` | `var(--primary-color)` |
+| `--timer-urgent-color` | `var(--error-color)` |
+| `--timer-ripple-color` | `var(--timer-progress-color)` (which itself falls back to `var(--primary-color)`) |
+| `--timer-size` | `160px` (also settable per instance via `size`) |
+| `--timer-stroke-width` | `10px` (also settable per instance via `strokeWidth`) |
+| `--timer-text-color` | `var(--text-color)` |
+| `--timer-label-color` | `var(--text-dark)` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Timer: { adjustSeconds: 60, playSoundOnComplete: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `ringWrapper` `ringSvg` `ringTrack` `ringProgress` `ripples` `ripple` `display` `time` `label` `controls` `addButton` `removeButton` `pauseButton` `cancelButton`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.19.4",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public"
   },