@kteneyck/cesium-timeline-angular 0.9.0 → 0.11.0

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.
Files changed (5) hide show
  1. package/README.md +79 -41
  2. package/fesm2022/kteneyck-cesium-timeline-angular.mjs +427 -184
  3. package/fesm2022/kteneyck-cesium-timeline-angular.mjs.map +1 -1
  4. package/package.json +4 -4
  5. package/types/kteneyck-cesium-timeline-angular.d.ts +39 -3
package/README.md CHANGED
@@ -17,7 +17,7 @@ A canvas-based timeline component for **React** and **Angular** with Cesium Cloc
17
17
  ### React
18
18
 
19
19
  ```bash
20
- npm install @kteneyck/cesium-timeline-react @kteneyck/cesium-timeline-core
20
+ npm install @kteneyck/cesium-timeline-react
21
21
  ```
22
22
 
23
23
  Peer dependencies: `react` ≥ 19, `cesium` ≥ 1.100
@@ -25,7 +25,7 @@ Peer dependencies: `react` ≥ 19, `cesium` ≥ 1.100
25
25
  ### Angular
26
26
 
27
27
  ```bash
28
- npm install @kteneyck/cesium-timeline-angular @kteneyck/cesium-timeline-core
28
+ npm install @kteneyck/cesium-timeline-angular
29
29
  ```
30
30
 
31
31
  Peer dependencies: `@angular/core` ≥ 17, `cesium` ≥ 1.100
@@ -127,12 +127,13 @@ Angular components use standalone imports — no NgModule required. Selectors: `
127
127
  - **Netflix/Hulu-style controls** — transport buttons (⏮ ◀◀ ▶/⏸ ▶▶ ⏭) always stay centered; speed badge and LIVE button in the left column never cause layout shift.
128
128
  - **Conditional start/end buttons** — ⏮ and ⏭ are only rendered when `startTime` and `endTime` props are explicitly provided.
129
129
  - **Speed cycling** — FF cycles through `ffSpeeds` (default `2×→4×→8×→16×→32×→1×`); RW cycles through `rwSpeeds` (default `−1×→−2×→−4×→−8×→−16×→−32×`). Both arrays are fully configurable.
130
- - **LIVE button** — filled `● LIVE` when within 10 s of wall clock; dim outline `LIVE` otherwise; clicking jumps to `Date.now()` and resets speed to 1×.
130
+ - **LIVE button** — shows a red dot + filled background when within 10 s of wall clock; dim outline otherwise. Clicking jumps to `Date.now()` and resets speed to 1×. Configurable size (`sm`/`md`/`lg`) and position (`left`/`right`). Dot color is themeable via `liveDotColor`.
131
131
  - **Speed badge** — shown in the left column when multiplier ≠ 1×; click to reset to 1×.
132
132
  - **Two-line datetime display** — time displayed large/bold; date displayed smaller in the theme's active color.
133
133
  - **Clickable datetime** — pass `onDateTimeClick` to open your own date picker; pass the result back via `jumpToTime` to pan the canvas and set the time.
134
134
  - **Token-based datetime format** — built-in presets plus custom format strings with 17 supported tokens.
135
135
  - **Max tick limit** — `maxTicks` prop prevents the canvas from becoming overloaded at wide zoom levels by coarsening the tick scale automatically.
136
+ - **Ghost / preview needle** — while hovering over the timeline a semi-transparent (15% opacity) preview needle tracks the cursor so you can see exactly where a click or zoom-to-selection drag would land before committing. The ghost disappears when the cursor leaves the canvas or an interaction begins.
136
137
  - **Zoom to selection** — drag in the tick area (away from the needle) to draw a time-range highlight with a crosshair cursor; on release the visible window zooms to exactly the selected span and fires `onRangeSelect` (React) / `rangeSelect` (Angular) with the resulting start and end times.
137
138
  - **Swim lanes** — display time intervals and instants as horizontal rows inside the canvas. Supports customizable styling, click/hover/double-click event hooks, drag-to-reorder, and vertical scrolling when lanes overflow.
138
139
  - **Fully themeable** — 16 theme properties cover every color, size, and font setting, including swim lane item border defaults.
@@ -145,38 +146,41 @@ Angular components use standalone imports — no NgModule required. Selectors: `
145
146
 
146
147
  ### `TimelineProps`
147
148
 
148
- | Prop | Type | Default | Description |
149
- |------|------|---------|-------------|
150
- | `clock` | `Cesium.Clock` | — | Cesium clock to sync with. Falls back to `setInterval` if omitted. |
151
- | `startTime` | `JulianDate \| Date` | now − 12 h | Left bound of initial visible window. Also shows the ⏮ button when provided. |
152
- | `endTime` | `JulianDate \| Date` | now + 12 h | Right bound of initial visible window. Also shows the ⏭ button when provided. |
153
- | `currentTime` | `JulianDate \| Date` | `startTime` | Initial needle position |
154
- | `height` | `number` | `120` | Canvas height in pixels |
155
- | `showControls` | `boolean` | `true` | Show/hide the control bar |
156
- | `enableDrag` | `boolean` | `true` | Show/hide the canvas (drag/seek area) |
157
- | `showLabels` | `boolean` | — | Show/hide tick labels on the canvas |
158
- | `snapToTicks` | `boolean` | — | Snap needle to nearest tick on drag |
159
- | `tickInterval` | `TickInterval \| number` | auto | Override automatic tick interval |
160
- | `maxTicks` | `number` | unlimited | Maximum number of major ticks on the canvas at once. When exceeded the tick scale is automatically coarsened. |
161
- | `ffSpeeds` | `number[]` | `[2,4,8,16,32,1]` | Speed steps cycled by the ▶▶ button. Last entry wraps back to first. |
162
- | `rwSpeeds` | `number[]` | `[1,2,4,8,16,32]` | Absolute-value speed steps cycled by the ◀◀ button (negated internally). |
163
- | `dateTimeFormat` | `string` | `'MMM DD YYYY HH:mm:ss'` | Token-based format string for the controls datetime display |
149
+ | Prop | Type | Default | Description |
150
+ |------|------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
151
+ | `clock` | `Cesium.Clock` | — | Cesium clock to sync with. Falls back to `setInterval` if omitted. |
152
+ | `startTime` | `JulianDate \| Date` | now − 12 h | Left bound of initial visible window. Also shows the ⏮ button when provided. |
153
+ | `endTime` | `JulianDate \| Date` | now + 12 h | Right bound of initial visible window. Also shows the ⏭ button when provided. |
154
+ | `currentTime` | `JulianDate \| Date` | `startTime` | Initial needle position |
155
+ | `height` | `number` | `120` | Canvas height in pixels |
156
+ | `showControls` | `boolean` | `true` | Show/hide the control bar |
157
+ | `enableDrag` | `boolean` | `true` | Show/hide the canvas (drag/seek area) |
158
+ | `showLabels` | `boolean` | — | Show/hide tick labels on the canvas |
159
+ | `snapToTicks` | `boolean` | — | Snap needle to nearest tick on drag |
160
+ | `tickInterval` | `TickInterval \| number` | auto | Override automatic tick interval |
161
+ | `maxTicks` | `number` | unlimited | Maximum number of major ticks on the canvas at once. When exceeded the tick scale is automatically coarsened. |
162
+ | `ffSpeeds` | `number[]` | `[2,4,8,16,32,1]` | Speed steps cycled by the ▶▶ button. Last entry wraps back to first. |
163
+ | `rwSpeeds` | `number[]` | `[1,2,4,8,16,32]` | Absolute-value speed steps cycled by the ◀◀ button (negated internally). |
164
+ | `dateTimeFormat` | `string` | `'MMM DD YYYY HH:mm:ss'` | Token-based format string for the controls datetime display |
164
165
  | `timezone` | `string` | browser local | IANA timezone name (e.g. `'UTC'`, `'America/New_York'`) or `'local'` for the browser's timezone. Controls both tick labels and the datetime display. When set, a short abbreviation (e.g. `UTC`, `EST`) appears to the right of the date. |
165
- | `onDateTimeClick` | `() => void` | — | Called when the user clicks the datetime display. Use to open your own date picker. |
166
- | `jumpToTime` | `JulianDate \| Date` | — | Set to programmatically jump the timeline to a moment (pans canvas + sets time). |
167
- | `theme` | `Partial<TimelineTheme>` | `defaultTheme` | Theme overrides (merged with defaults) |
168
- | `className` | `string` | — | CSS class applied to the root div |
169
- | `onTimeChange` | `(t: JulianDate) => void` | — | Fires when needle moves (drag, click, or clock tick) |
170
- | `onPlayPause` | `(playing: boolean) => void` | — | Fires on play/pause toggle |
171
- | `onMultiplierChange` | `(m: number) => void` | — | Fires when speed changes |
172
- | `swimLanes` | `SwimLane[]` | — | Array of swim lane definitions to render on the canvas |
173
- | `showSwimLanes` | `boolean` | `true` | Show or hide the swim lanes |
174
- | `onSwimLaneItemClick` | `(info: SwimLaneEventInfo) => void` | — | Fires when a swim lane item is clicked |
175
- | `onSwimLaneItemHover` | `(info: SwimLaneEventInfo \| null) => void` | — | Fires when mouse enters/leaves a swim lane item |
176
- | `onSwimLaneItemDoubleClick` | `(info: SwimLaneEventInfo) => void` | — | Fires when a swim lane item is double-clicked |
177
- | `onSwimLaneReorder` | `(orderedIds: string[]) => void` | — | Fires when swim lanes are reordered via drag. Receives the new lane id order. |
178
- | `onRangeSelect` | `(start: JulianDate, end: JulianDate) => void` | — | Fires when the user completes a click-and-drag in the tick area. The visible window zooms to the selected span; receives the resulting start and end times. |
179
- | `labels` | `Partial<TimelineLabels>` | English defaults | Override any control-bar label or tooltip string. See [Labels & i18n](#labels--i18n). |
166
+ | `onDateTimeClick` | `() => void` | — | Called when the user clicks the datetime display. Use to open your own date picker. |
167
+ | `jumpToTime` | `JulianDate \| Date` | — | Set to programmatically jump the timeline to a moment (pans canvas + sets time). |
168
+ | `theme` | `Partial<TimelineTheme>` | `defaultTheme` | Theme overrides (merged with defaults) |
169
+ | `className` | `string` | — | CSS class applied to the root div |
170
+ | `onTimeChange` | `(t: JulianDate) => void` | — | Fires when needle moves (drag, click, or clock tick) |
171
+ | `onPlayPause` | `(playing: boolean) => void` | — | Fires on play/pause toggle |
172
+ | `onMultiplierChange` | `(m: number) => void` | — | Fires when speed changes |
173
+ | `swimLanes` | `SwimLane[]` | — | Array of swim lane definitions to render on the canvas |
174
+ | `showSwimLanes` | `boolean` | `true` | Show or hide the swim lanes |
175
+ | `onSwimLaneItemClick` | `(info: SwimLaneEventInfo) => void` | — | Fires when a swim lane item is clicked |
176
+ | `onSwimLaneItemHover` | `(info: SwimLaneEventInfo \| null) => void` | — | Fires when mouse enters/leaves a swim lane item |
177
+ | `onSwimLaneItemDoubleClick` | `(info: SwimLaneEventInfo) => void` | — | Fires when a swim lane item is double-clicked |
178
+ | `onSwimLaneReorder` | `(orderedIds: string[]) => void` | — | Fires when swim lanes are reordered via drag. Receives the new lane id order. |
179
+ | `onRangeSelect` | `(start: JulianDate, end: JulianDate) => void` | — | Fires when the user completes a click-and-drag in the tick area. The visible window zooms to the selected span; receives the resulting start and end times. |
180
+ | `labels` | `Partial<TimelineLabels>` | English defaults | Override any control-bar label or tooltip string. See [Labels & i18n](#labels--i18n). |
181
+ | `liveButtonSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the LIVE button in the control bar. |
182
+ | `liveButtonPosition` | `'left' \| 'right'` | `'left'` | Position of the LIVE button — beside the datetime display (`'left'`) or the opposite side of the control bar (`'right'`). |
183
+ | `invertScrollZoom` | `boolean` | `false` | Reverses the scroll-wheel zoom direction. By default scroll up zooms in and scroll down zooms out. Set to `true` for scroll down zooms in, scroll up zooms out. |
180
184
 
181
185
  ---
182
186
 
@@ -215,6 +219,7 @@ Pass a partial `TimelineTheme` object to the `theme` prop. Any omitted propertie
215
219
  | `buttonActiveColor` | `#d69826` | Active buttons, LIVE, speed badge, and date line colour |
216
220
  | `swimLaneItemBorderColor` | `#666666` | Default border colour for swim lane interval bars. Can be overridden per-lane or per-item. |
217
221
  | `swimLaneItemBorderWidth` | `0` | Default border width (px) for swim lane interval bars. Set to `0` to remove borders globally. Can be overridden per-lane or per-item. |
222
+ | `liveDotColor` | `#e53e3e` | Colour of the dot shown on the LIVE button when playback is live. |
218
223
 
219
224
  > **Note:** Theme colours must be resolved hex/rgb values. CSS variables like `var(--primary-color)` do **not** work in canvas `ctx.fillStyle`. Use `getComputedStyle(document.documentElement).getPropertyValue('--primary-color').trim()` to resolve them first.
220
225
 
@@ -364,13 +369,16 @@ The control bar uses a 3-column CSS grid so the transport buttons are always cen
364
369
 
365
370
  ### LIVE Button
366
371
 
367
- - Shows `● LIVE` (filled background) when the current time is within 10 seconds of `Date.now()`.
368
- - Shows `LIVE` (dim outline) otherwise.
369
- - Clicking jumps to `Date.now()`, centers the visible window ±12 h, and resets speed to 1×.
372
+ - Shows a red dot and filled background when the current time is within 2 seconds of `Date.now()`.
373
+ - Shows `LIVE` (dim outline, no dot) otherwise.
374
+ - Clicking jumps to `Date.now()`, centers the visible window, and resets speed to 1×.
375
+ - **Size** — controlled by the `liveButtonSize` prop: `'sm'` | `'md'` (default) | `'lg'`.
376
+ - **Position** — controlled by the `liveButtonPosition` prop: `'left'` (default, beside the datetime display) | `'right'` (right side of the control bar).
377
+ - **Dot color** — controlled by `theme.liveDotColor` (default `#e53e3e`).
370
378
 
371
379
  ### Speed Badge
372
380
 
373
- - Appears to the right of LIVE when multiplier ≠ 1×.
381
+ - Appears inline beside the LIVE button when multiplier ≠ 1×.
374
382
  - Shows `◀ N×` for reverse, `N× ▶` for fast-forward.
375
383
  - Clicking resets to 1× speed.
376
384
 
@@ -426,7 +434,7 @@ Every label and tooltip in the control bar is overridable via the `labels` prop.
426
434
  |-----|-------------------|-------|
427
435
  | `dateTimeClickTooltip` | `"Click to jump to a date/time"` | Tooltip on the datetime display when `onDateTimeClick` is wired up |
428
436
  | `liveLabel` | `"LIVE"` | LIVE button text when not at live time |
429
- | `liveActiveLabel` | `"● LIVE"` | LIVE button text when at live time |
437
+ | `liveActiveLabel` | `"LIVE"` | LIVE button text when at live time (red dot is rendered separately) |
430
438
  | `liveTooltip` | `"Jump to live (now)"` | LIVE button tooltip when not at live time |
431
439
  | `liveActiveTooltip` | `"Currently live"` | LIVE button tooltip when at live time |
432
440
  | `resetSpeedTooltip` | `"Reset to 1× speed"` | Tooltip on the speed-reset badge |
@@ -456,7 +464,7 @@ const frLabels: Partial<TimelineLabels> = {
456
464
  playTooltip: 'Lecture',
457
465
  pauseTooltip: 'Pause',
458
466
  liveLabel: 'EN DIRECT',
459
- liveActiveLabel: '● EN DIRECT',
467
+ liveActiveLabel: 'EN DIRECT',
460
468
  liveTooltip: 'Aller en direct',
461
469
  liveActiveTooltip: 'Vous êtes en direct',
462
470
  rewindTooltip: 'Retour rapide',
@@ -482,7 +490,7 @@ export class AppComponent {
482
490
  playTooltip: 'Lecture',
483
491
  pauseTooltip: 'Pause',
484
492
  liveLabel: 'EN DIRECT',
485
- liveActiveLabel: '● EN DIRECT',
493
+ liveActiveLabel: 'EN DIRECT',
486
494
  liveTooltip: 'Aller en direct',
487
495
  liveActiveTooltip: 'Vous êtes en direct',
488
496
  rewindActiveTooltip: (n) => `Retour ${n}× — cliquer pour accélérer`,
@@ -759,6 +767,36 @@ onRangeSelect(range: { start: Cesium.JulianDate; end: Cesium.JulianDate }) {
759
767
 
760
768
  ---
761
769
 
770
+ ## Ghost / Preview Needle
771
+
772
+ When the user hovers over the timeline canvas a **ghost needle** (a semi-transparent version of the current-time indicator) tracks the cursor position in real time. It renders at **15% opacity** using the same `indicatorColor` and `indicatorLineWidth` as the real needle, giving a clear preview of where a click-to-seek or zoom-to-selection drag would begin — without moving the actual current time.
773
+
774
+ ### Behaviour summary
775
+
776
+ | State | Ghost visible? |
777
+ |---|---|
778
+ | Mouse idle over canvas | ✅ Follows cursor |
779
+ | Dragging (scrub / range-select / slide / zoom) | ❌ Hidden |
780
+ | Mouse leaves canvas | ❌ Hidden |
781
+
782
+ ### Theming the ghost needle
783
+
784
+ The ghost needle inherits `indicatorColor` and `indicatorLineWidth` from your theme — no additional configuration is needed. To change its appearance, update those two theme properties:
785
+
786
+ ```tsx
787
+ <Timeline
788
+ clock={viewer.clock}
789
+ theme={{
790
+ indicatorColor: '#ffd54f',
791
+ indicatorLineWidth: 3,
792
+ }}
793
+ />
794
+ ```
795
+
796
+ The ghost will render as the same colour at 15% opacity, and the real needle will render at full opacity.
797
+
798
+ ---
799
+
762
800
  ## Swim Lanes
763
801
 
764
802
  Swim lanes render time intervals (bars) and instants (markers) as horizontal rows directly on the timeline canvas, aligned with the ticks and needle. They are ideal for visualizing satellite passes, ground contacts, scheduled events, or any temporal data.