@ixfx/components 0.4.4 → 0.5.0

package/docs-user/notifier.md

@@ -0,0 +1,131 @@
+# Notifier
+
+A "lookless" app-wide notification system. `NotificationManager` is a singleton that owns notification state, queueing, and timing — it doesn't know how to draw anything. A `NotificationRenderer` (the built-in "pill" renderer, or your own) is responsible for showing/hiding notifications on screen.
+
+```typescript
+import { NotificationManager } from '../src/index.js';
+
+NotificationManager.notify({ type: 'info', message: 'Saved.' });
+```
+
+No setup required — the first `notify()` call lazily creates a default pill renderer (`top-right`, list display).
+
+---
+
+## `NotificationManager`
+
+### `notify(content): string`
+
+```typescript
+const id = NotificationManager.notify({
+  type: 'error',              // 'info' | 'warning' | 'error'
+  message: 'Upload failed',
+  icon: 'error',               // optional; errors default to 'error' if omitted
+  onTap: (id) => { /* per-notification tap handler */ },
+});
+```
+
+Returns the notification's `id`, which can be used to `update()` or `dismiss()` it later.
+
+### `update(id, content): void`
+
+```typescript
+NotificationManager.update(id, { message: 'Still uploading…' });
+```
+
+Merges the given fields into the existing notification and, if it's currently the front (displayed) message, resets its dismissal timer.
+
+### `dismiss(id): void` / `dismissAll(): void`
+
+Programmatically hide one notification, or clear everything.
+
+### `configure(options): void`
+
+Merges into the current configuration. Can be called any time, including after notifications are already showing.
+
+```typescript
+NotificationManager.configure({
+  timeout: 4000,
+  timeoutError: 8000,
+  queue: true,
+  queueSize: 3,
+  tapBehaviour: 'dismiss',
+  tapHandlerDefault: (notification) => console.log(notification.message),
+  renderer: createPillRenderer({ position: 'bottom-right' }),
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `renderer` | `NotificationRenderer` | built-in pill renderer | Swap the display implementation. See [Custom renderers](#custom-renderers). |
+| `timeout` | `number` (ms) | `4000` | Default display time for `info`/`warning` messages. |
+| `timeoutError` | `number` (ms) | `8000` | Display time for `error` messages. |
+| `queue` | `boolean` | `true` | `true`: up to `queueSize` messages can be waiting at once (see below). `false`: each new message immediately replaces whatever is showing. |
+| `queueSize` | `number` | `3` | Max number of messages held at once when `queue` is `true`. Shrinking it evicts overflow immediately. |
+| `tapBehaviour` | `'none' \| 'dismiss'` | `'dismiss'` | Whether tapping a notification also dismisses it (after any tap handler runs). |
+| `tapHandlerDefault` | `(notification) => void` | — | Called on tap when the notification has no `onTap` of its own. |
+
+---
+
+## Queueing model
+
+- **`queue: false`** — a message is always shown alone, for the full `timeout`/`timeoutError`. A new `notify()` call immediately replaces whatever is showing.
+- **`queue: true`** — up to `queueSize` messages are visible at once. When a new message arrives and the queue is already full, **the oldest message is evicted immediately** to make room — nothing waits in an unbounded backlog.
+- Only the **front** message (the oldest, next to be dismissed) has a running timer. A message that arrived while others were already queued gets `1/queueSize` of the normal timeout once it becomes front; a message that was alone in the queue when it arrived gets the full timeout. This means a burst of messages cycles through quickly, while a single message gets the full, unhurried display time.
+- `update()` only resets the timer if the updated notification is currently front (i.e. actually has a timer running).
+
+---
+
+## Pill renderer
+
+The built-in renderer, `createPillRenderer(options)`, renders notifications as rounded pills fixed to a corner or edge of the viewport, using theme CSS variables for styling.
+
+```typescript
+import { createPillRenderer, NotificationManager } from '../src/index.js';
+
+NotificationManager.configure({
+  renderer: createPillRenderer({
+    position: 'top-right',
+    queueDisplay: 'list',
+    safeArea: { top: 60 }, // e.g. clear a fixed header
+  }),
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `position` | `'top-left' \| 'top-middle' \| 'top-right' \| 'bottom-left' \| 'bottom-middle' \| 'bottom-right'` | `'top-right'` | Which corner/edge pills anchor to, and the direction they slide in/out from. |
+| `queueDisplay` | `'list' \| 'stack'` | `'list'` | How queued (non-front) messages are shown — see below. |
+| `safeArea` | `{ top?, right?, bottom?, left? }` (px) | `{}` | Extra margin added on top of the default spacing, e.g. to avoid a fixed header/footer/notch. |
+
+### `queueDisplay: 'list'`
+
+Each message gets its own row. The oldest message sits nearest the anchor edge; newer messages extend away from it (for `top-*` positions, newest is lowest on screen; for `bottom-*`, newest is highest). When the front message is dismissed, the rest animate into the vacated slot.
+
+### `queueDisplay: 'stack'`
+
+Only the front message is fully shown. Queued messages peek out from behind it, offset by a few pixels and increasingly faded/desaturated, giving a visual hint that more are waiting. They aren't interactive (no tap, no pointer events) until promoted to front.
+
+The offset direction follows the anchor position: corner positions (e.g. `top-left`) offset diagonally, away from both edges (`top-left` → down-right); `-middle` positions offset only vertically, away from the anchor edge (`bottom-middle` → straight up).
+
+When the front message is dismissed, the next one animates into the front slot at full opacity.
+
+---
+
+## Custom renderers
+
+Anything implementing `NotificationRenderer` can be passed to `configure({ renderer })`:
+
+```typescript
+export interface NotificationRenderer {
+  attach: (hooks: NotificationRendererHooks) => void;
+  detach?: () => void;
+  setNotifications: (notifications: Notification[], queueSize: number) => void;
+}
+```
+
+- `attach(hooks)` is called once when the renderer becomes active. Call `hooks.onTap(id)` whenever the user interacts with a shown notification — the manager decides what tapping means (per-notification `onTap`, `tapHandlerDefault`, `tapBehaviour`).
+- `detach?()` is called if the renderer is swapped out at runtime, so it can tear down its DOM.
+- `setNotifications(notifications, queueSize)` is called any time the visible set changes (new message, dismissal, eviction, reorder, content update). `notifications` is the manager's full, rank-ordered view — index `0` is the front/oldest message — and is never longer than `queueSize`, since the manager itself evicts overflow. A renderer just needs to reconcile this list against whatever it's currently showing (create new, update existing, remove missing) — see `pill-renderer.ts` for a full example.
+
+`NotificationContent.onTap` is per-notification and takes the notification's `id`; `tapHandlerDefault` (manager-wide) takes the full `Notification`.

package/docs-user/plots.md

@@ -99,6 +99,8 @@ Renders a 1D data series as a time-series / ordered-sequence plot.
 | `tooltips` | `boolean` | `true` | Show tooltip on hover |
 | `precise` | `boolean` | `false` | Show latest value in corner |
 | `persistentScale` | `boolean` | `true` | Keep same scale; if `false`, scale adjusts to visible data |
+| `rangeMin` | `number` | `NaN` | Fixed minimum value for Y-axis (when set, disables auto-scaling) |
+| `rangeMax` | `number` | `NaN` | Fixed maximum value for Y-axis (when set, disables auto-scaling) |
 | `clickPauses` | `boolean` | `false` | Toggle pause on click |
 | `shaded` | `boolean` | `false` | Shaded area under line |
 | `areaColor` | `string` | `""` | Custom shade colour |
@@ -106,6 +108,16 @@ Renders a 1D data series as a time-series / ordered-sequence plot.
 | `colorEasing` | `string` | `""` | Easing for colour mapping |
 | `colorScale` | `string` | `""` | Colour palette for `scale` mode |
 
+### Fixed Range
+
+Set `range-min` and `range-max` attributes to fix the Y-axis scale:
+
+```html
+<ixfx-plot-single-axis range-min="0" range-max="100"></ixfx-plot-single-axis>
+```
+
+When both are set, the plot uses a fixed range instead of auto-scaling to the data.
+
 ### Draw Styles
 
 | Style | Description |
@@ -151,6 +163,24 @@ Use `color-easing` for easing functions or `color-scale` for custom palettes:
 ### Events
 
 - **`plot-datapoint-click`** — `{ value: number, index: number }`
+- **`plot-pointer-move`** — `{ clientX: number, clientY: number, index: number }`
+- **`plot-pointer-leave`** — Fired when pointer leaves the plot
+
+### Value Formatting
+
+Override `valueFormat` to customize the tooltip and precise value display:
+
+```typescript
+plot.valueFormat = v => v ? `${v.toFixed(1)}°C` : '';
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `values` | `readonly number[]` | Get all values in the series |
+| `dataLength` | `number` | Number of data points |
+| `series` | `PlotDataSeries` | Internal data series instance |
 
 ### Example
 
@@ -228,8 +258,13 @@ Unlike the other plot components, multi-axis manages multiple independent data s
 
 ```typescript
 plot.addData({ temperature: 22, humidity: 60, pressure: 1013 });
+plot.addObject({ temperature: 22, humidity: 60 });        // Add to existing series
+plot.setData('temperature', [1, 2, 3]);                  // Replace series data
+plot.setObjects({ a: [1,2,3], b: [4,5,6] });            // Replace multiple series
 plot.styleSeries('temperature', { 'plot-color': '#ff6b6b' });
-plot.clear();
+plot.clear();                                            // Clear all series
+plot.clearSeries('temperature');                          // Clear single series
+plot.series;                                             // Get series names array
 ```
 
 ### Layouts
@@ -282,6 +317,19 @@ Renders a histogram of value distributions. Unlike `ixfx-plot-single-axis` (wher
 
 **Tag:** `<ixfx-plot-histogram>`
 
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `orientation` | `PlotHistogramOrientation` | `horizontal` | `horizontal` or `vertical` |
+| `resolution` | `number` | `0.10` | Fraction of range per bucket |
+| `min` / `max` | `number` | auto | Fixed value range (disables auto-scaling) |
+| `capacity` | `number` | `100` | Max values retained |
+| `valueTooltips` | `PlotHistogramValueTooltips` | `hover` | `hover` (bubble), `inline` (overlay-text), or `none` |
+| `tooltipDelay` | `number` | `400` | Hover delay (ms) before the `hover` bubble appears/disappears |
+| `valueUpdateInterval` | `number` | `500` | Max rate (ms) at which a shown value refreshes against live-changing data |
+| `paused` | `boolean` | `false` | Pause rendering updates |
+
 ### Orientation
 
 | Value | Description |
@@ -338,6 +386,18 @@ rect.bar {
 
 - **`plot-bucket-click`** — `{ bucketIndex: number, valueMin: number, valueMax: number, relativeValue: number }`
 
+### Tooltips
+
+`valueTooltips` selects how hovering a bucket is shown, sharing the same overridable `valueFormat(valueMin, valueMax, frequency)` (default: `"<min> - <max>: <frequency>"`):
+
+- `"hover"` (default) — a floating `ixfx-tooltip` bubble, positioned by the component itself: centred on the hovered bar along the bucket axis, offset from the cursor on the other axis. Debounced by `tooltipDelay` ms (default `400`) on first appearance and on hide; switching directly between bars while already visible updates instantly.
+- `"inline"` — swaps the title overlay-text (top-left) for the hovered bucket's value/frequency instantly (no debounce), reverting to `title` when the pointer leaves.
+- `"none"` — no hover feedback.
+
+While hovering, both `hover` and `inline` refresh their displayed value at most every `valueUpdateInterval` ms (default `500`) as the underlying bucket's data changes, rather than on every `add()`.
+
+Note: `title` is not reflected to the native `title` attribute, so hovering the plot doesn't also trigger the browser's own tooltip.
+
 ### Example
 
 ```html