@industream/timeline 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -0
- package/dist/industream-timeline.js +21295 -0
- package/package.json +55 -0
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# @industream/timeline
|
|
2
|
+
|
|
3
|
+
The **@industream timeline** as a framework-agnostic **Web Component** — `<industream-timeline>`: a band with a
|
|
4
|
+
movable **snapshot** point, a resizable **`[from, to]`** window, zoom, and **Live** / **Timelapse** modes. It
|
|
5
|
+
only produces *times* — it fetches nothing and has no API coupling.
|
|
6
|
+
|
|
7
|
+
**Self-contained**: React, the widget, and its styles are bundled inside a **Shadow DOM**. The host provides
|
|
8
|
+
**nothing** — no React, no Tailwind, no CSS setup. Works in Angular, Vue, Svelte, vanilla… or a React app.
|
|
9
|
+
|
|
10
|
+
> Building a **React** app? If you can consume the source package, prefer **`@industream/timeline-react`**: you
|
|
11
|
+
> avoid a second React runtime and get typed hooks (`useSnapshot`, `useStartDate`…) instead of DOM events.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm i @industream/timeline
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
A single **side-effect import** registers the `<industream-timeline>` element globally:
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import "@industream/timeline";
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Then drop it anywhere. Drive it with **attributes**, read it back through **events**.
|
|
28
|
+
|
|
29
|
+
### Attributes
|
|
30
|
+
|
|
31
|
+
| Attribute | Values | Default | Meaning |
|
|
32
|
+
| --- | --- | --- | --- |
|
|
33
|
+
| `language` | `en` \| `fr` \| `de` | `en` | UI language. |
|
|
34
|
+
| `instant` | boolean (presence) | — | Show the snapshot instant T (playhead + value bubble). |
|
|
35
|
+
| `window` | boolean (presence) | — | Show the `[from,to]` window and its start/end fields. |
|
|
36
|
+
| `modes` | space-separated `live` `timelapse` | all compatible | Animated modes on top of Historic (always on). `timelapse` needs `instant`+`window`. |
|
|
37
|
+
| `theme` | `light` \| `dark` | `light` | Built-in colour theme. |
|
|
38
|
+
| `step-loading` | boolean | off | Tells timelapse a snapshot is still loading, so playback waits for your data. |
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
One **property** (an object, so set it in JS, not as an attribute): `el.preview = { points, min, max }` — an
|
|
43
|
+
optional series drawn faintly across the band.
|
|
44
|
+
|
|
45
|
+
### Events
|
|
46
|
+
|
|
47
|
+
All fire as `CustomEvent`s (they `bubble` and cross shadow boundaries). Times are **epoch milliseconds** in
|
|
48
|
+
`event.detail`.
|
|
49
|
+
|
|
50
|
+
| Event | `detail` | Fires when |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `snapshotchange` | `{ snapshot }` | the "as of" instant changes (debounced). |
|
|
53
|
+
| `windowchange` | `{ from, to }` | the window bounds change (debounced). |
|
|
54
|
+
| `extentchange` | `{ from, to }` | the full navigable extent changes. |
|
|
55
|
+
|
|
56
|
+
## Angular
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from "@angular/core";
|
|
60
|
+
import "@industream/timeline";
|
|
61
|
+
|
|
62
|
+
@Component({
|
|
63
|
+
selector: "app-root",
|
|
64
|
+
schemas: [CUSTOM_ELEMENTS_SCHEMA], // lets Angular accept the custom tag
|
|
65
|
+
template: `
|
|
66
|
+
<industream-timeline
|
|
67
|
+
[attr.language]="language()"
|
|
68
|
+
[attr.theme]="theme()"
|
|
69
|
+
(snapshotchange)="onSnapshot($event)"
|
|
70
|
+
(windowchange)="onWindow($event)">
|
|
71
|
+
</industream-timeline>`,
|
|
72
|
+
})
|
|
73
|
+
export class App {
|
|
74
|
+
readonly language = signal<"en" | "fr" | "de">("en");
|
|
75
|
+
readonly theme = signal<"light" | "dark">("light");
|
|
76
|
+
onSnapshot(e: Event) { const { snapshot } = (e as CustomEvent).detail; /* new Date(snapshot) */ }
|
|
77
|
+
onWindow(e: Event) { const { from, to } = (e as CustomEvent).detail; /* … */ }
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Vanilla
|
|
82
|
+
|
|
83
|
+
```html
|
|
84
|
+
<industream-timeline language="en" theme="dark"></industream-timeline>
|
|
85
|
+
<script type="module">
|
|
86
|
+
import "@industream/timeline";
|
|
87
|
+
const el = document.querySelector("industream-timeline");
|
|
88
|
+
el.addEventListener("snapshotchange", (e) => console.log(new Date(e.detail.snapshot)));
|
|
89
|
+
</script>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Theming
|
|
93
|
+
|
|
94
|
+
The widget ships a default theme. Flip it with `theme="dark"`, or override the CSS variables from the host —
|
|
95
|
+
they inherit through the shadow boundary:
|
|
96
|
+
|
|
97
|
+
```css
|
|
98
|
+
industream-timeline { --primary: oklch(0.55 0.2 250); --radius: 0.3rem; }
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
ISC
|