@industream/timeline 1.0.1 → 1.2.0

package/README.md

@@ -33,25 +33,68 @@ Then drop it anywhere. Drive it with **attributes**, read it back through **even
 | `language` | `en` \| `fr` \| `de` | `en` | UI language. |
 | `instant` | boolean (presence) | — | Show the snapshot instant T (playhead + value bubble). |
 | `window` | boolean (presence) | — | Show the `[from,to]` window and its start/end fields. |
-| `modes` | space-separated `live` `timelapse` | all compatible | Animated modes on top of Historic (always on). `timelapse` needs `instant`+`window`. |
+| `modes` | space-separated `live` `timelapse` (absent = all; `""` = Historic only) | all compatible | Animated modes on top of Historic (always on). `timelapse` auto-adds `instant`+`window` while it runs. |
 | `theme` | `light` \| `dark` | `light` | Built-in colour theme. |
 | `step-loading` | boolean | off | Tells timelapse a snapshot is still loading, so playback waits for your data. |
+| `from`, `to` | epoch ms (digits only) or ISO 8601 | — | The window `[from, to]`. Give both, or neither. |
+| `timespan` | duration: `30m`, `1h`, `2d`, `1w`, `3M`, `1y` | `2d` | The window as the last *duration* (ends now). `from` / `to` win over it. |
+| `extent` | duration, same syntax | `7d` | How much time the band spans. |
+| `mode` | `live` \| `historic` | Live when offered, else Historic | The mode to start in. `live` needs Live in `modes`. |
+
+If **neither** `instant` nor `window` is present, both default on (bare `<industream-timeline>` = full timeline). Historic is always on; `modes` lists only `live` / `timelapse` (**omit** the attribute for the default, `""` for Historic only). Listing `historic` or an unknown mode throws; `timelapse` never throws — it auto-adds any missing content while it runs. See the [full guide](../docs/web-component.md#every-combination) for every combination.
+
+**Position** (`from` / `to` / `timespan`, `extent`, `mode`): the timeline starts on these attributes, and
+**changing one later moves it** — so a page can give its window back to a timeline it mounts again. Changing
+`modes`, `language` or `theme` keeps the window and mode (a mode no longer offered falls back to Historic). Durations
+use `m` for minutes and `M` for months. A window is always shown whole: the extent widens or moves to contain
+it, and a window ending in the future ends now. In Live, the window keeps its duration but ends now. Changing
+`from` / `to` leaves Live; changing `timespan` keeps the current mode. Setting `from` / `to` to the window the
+timeline has just emitted does nothing, so a page may store the window it receives and hand it back. An
+invalid value throws. See the [full guide](../docs/web-component.md#position).
 
-If **neither** `instant` nor `window` is present, both default on (bare `<industream-timeline>` = full timeline). Historic is always on; `modes` lists only `live` / `timelapse`. An invalid `modes` (listing `historic`, or `timelapse` without both `instant` and `window`) throws.
+```html
+<!-- Live on the last hour, Historic available -->
+<industream-timeline window modes="live" timespan="1h"></industream-timeline>
+<!-- Historic only, on a window the user chose -->
+<industream-timeline window modes="" from="2026-10-01T00:00:00Z" to="2026-10-03T00:00:00Z"></industream-timeline>
+```
 
 One **property** (an object, so set it in JS, not as an attribute): `el.preview = { points, min, max }` — an
 optional series drawn faintly across the band.
 
 ### Events
 
-All fire as `CustomEvent`s (they `bubble` and cross shadow boundaries). Times are **epoch milliseconds** in
-`event.detail`.
+All fire as `CustomEvent`s (they `bubble` and cross shadow boundaries), once on start and then on every
+change. Times are **epoch milliseconds** in `event.detail`.
 
 | Event | `detail` | Fires when |
 | --- | --- | --- |
 | `snapshotchange` | `{ snapshot }` | the "as of" instant changes (debounced). |
 | `windowchange` | `{ from, to }` | the window bounds change (debounced). |
 | `extentchange` | `{ from, to }` | the full navigable extent changes. |
+| `modechange` | `{ mode }` — `"historic"` \| `"live"` \| `"timelapse"` | the mode changes. |
+
+## TypeScript
+
+The package ships its type declarations: the element class, `IndustreamTimelineAttributes`, the event details
+(`TimelineWindowChangeDetail`…) and the `HTMLElementTagNameMap` entry. So
+`document.createElement("industream-timeline")` is typed, and so is `event.detail` in its listeners.
+
+React's JSX has no entry for custom tags. Add it once in your app, from the shipped attributes:
+
+```ts
+// industream-timeline-jsx.d.ts
+import type { DetailedHTMLProps, HTMLAttributes } from "react";
+import type { IndustreamTimelineAttributes, IndustreamTimelineElement } from "@industream/timeline";
+
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "industream-timeline": DetailedHTMLProps<HTMLAttributes<IndustreamTimelineElement>, IndustreamTimelineElement> & IndustreamTimelineAttributes;
+        }
+    }
+}
+```
 
 ## Angular