@kteneyck/cesium-timeline-react 0.4.0 → 0.6.0

package/README.md

@@ -123,7 +123,7 @@ Angular components use standalone imports — no NgModule required. Selectors: `
 - **Auto-scroll during playback** — visible window pans automatically when the needle reaches 10% from either edge.
 - **Infinite scrolling window** — timeline is not clamped to `startTime`/`endTime`; the window can pan anywhere.
 - **Adaptive tick labels** — label granularity adapts to zoom level: milliseconds → seconds → HH:MM:SS → HH:MM → Month Day → Month Year → Year. Tick dates are shown only when the visible window spans more than 24 hours.
-- **Local time labels** — ticks and dates reflect the user's local timezone, not UTC.
+- **Configurable timezone** — tick labels and the datetime display can show any IANA timezone (e.g. `"UTC"`, `"America/New_York"`) or the browser's local time. A short abbreviation (e.g. `UTC`, `EST`, `PDT`) is displayed to the right of the date line whenever a non-local timezone is active.
 - **Netflix/Hulu-style controls** — transport buttons (⏮ ◀◀ ▶/⏸ ▶▶ ⏭) always stay centered; speed badge and LIVE button in the left column never cause layout shift.
 - **Conditional start/end buttons** — ⏮ and ⏭ are only rendered when `startTime` and `endTime` props are explicitly provided.
 - **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.
@@ -135,6 +135,7 @@ Angular components use standalone imports — no NgModule required. Selectors: `
 - **Max tick limit** — `maxTicks` prop prevents the canvas from becoming overloaded at wide zoom levels by coarsening the tick scale automatically.
 - **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.
 - **Fully themeable** — 16 theme properties cover every color, size, and font setting, including swim lane item border defaults.
+- **Localizable labels** — every control-bar label and tooltip is overridable via the `labels` prop; dynamic tooltips accept a `(multiplier: number) => string` callback. See [Labels & i18n](#labels--i18n).
 - **Responsive** — fills container width; `ResizeObserver` redraws on resize.
 
 ---
@@ -159,6 +160,7 @@ Angular components use standalone imports — no NgModule required. Selectors: `
 | `ffSpeeds` | `number[]` | `[2,4,8,16,32,1]` | Speed steps cycled by the ▶▶ button. Last entry wraps back to first. |
 | `rwSpeeds` | `number[]` | `[1,2,4,8,16,32]` | Absolute-value speed steps cycled by the ◀◀ button (negated internally). |
 | `dateTimeFormat` | `string` | `'MMM DD YYYY HH:mm:ss'` | Token-based format string for the controls datetime display |
+| `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. |
 | `onDateTimeClick` | `() => void` | — | Called when the user clicks the datetime display. Use to open your own date picker. |
 | `jumpToTime` | `JulianDate \| Date` | — | Set to programmatically jump the timeline to a moment (pans canvas + sets time). |
 | `theme` | `Partial<TimelineTheme>` | `defaultTheme` | Theme overrides (merged with defaults) |
@@ -172,6 +174,7 @@ Angular components use standalone imports — no NgModule required. Selectors: `
 | `onSwimLaneItemHover` | `(info: SwimLaneEventInfo \| null) => void` | — | Fires when mouse enters/leaves a swim lane item |
 | `onSwimLaneItemDoubleClick` | `(info: SwimLaneEventInfo) => void` | — | Fires when a swim lane item is double-clicked |
 | `onSwimLaneReorder` | `(orderedIds: string[]) => void` | — | Fires when swim lanes are reordered via drag. Receives the new lane id order. |
+| `labels` | `Partial<TimelineLabels>` | English defaults | Override any control-bar label or tooltip string. See [Labels & i18n](#labels--i18n). |
 
 ---
 
@@ -229,6 +232,60 @@ const theme = useMemo(() => {
 
 ---
 
+## Timezone
+
+By default the timeline displays all times in the **browser's local timezone**. Pass the `timezone` prop to use UTC or any [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) instead.
+
+```tsx
+// UTC
+<Timeline clock={viewer.clock} timezone="UTC" ... />
+
+// A named IANA zone
+<Timeline clock={viewer.clock} timezone="America/New_York" ... />
+
+// Back to local (or simply omit the prop)
+<Timeline clock={viewer.clock} timezone="local" ... />
+```
+
+Both the **canvas tick labels** and the **control bar datetime display** update to reflect the chosen timezone. When a non-local timezone is active a short abbreviation (e.g. `UTC`, `EST`, `PDT`) is shown to the right of the date line. The abbreviation is DST-aware — it automatically switches between `EST` and `EDT`, `PST` and `PDT`, etc.
+
+### `Timezones` constants
+
+```tsx
+import { Timezones } from '@kteneyck/cesium-timeline-react';
+
+<Timeline timezone={Timezones.UTC} ... />   // "UTC"
+<Timeline timezone={Timezones.LOCAL} ... /> // "local" (default behavior)
+```
+
+### `getTimezoneAbbr` utility
+
+Returns the short abbreviation for a given date and timezone, or `null` for local.
+
+```tsx
+import { getTimezoneAbbr } from '@kteneyck/cesium-timeline-react';
+
+getTimezoneAbbr(new Date(), 'UTC');               // → "UTC"
+getTimezoneAbbr(new Date(), 'America/Chicago');   // → "CDT" or "CST"
+getTimezoneAbbr(new Date());                      // → null  (local)
+```
+
+### `formatDateTime` with timezone
+
+The `formatDateTime` utility accepts an optional third argument:
+
+```tsx
+import { formatDateTime, DateTimeFormats } from '@kteneyck/cesium-timeline-react';
+
+formatDateTime(new Date(), DateTimeFormats.ISO, 'UTC');
+// → "2026-02-24 14:04:07"  (always in UTC regardless of local browser timezone)
+
+formatDateTime(new Date(), DateTimeFormats.DEFAULT, 'America/Los_Angeles');
+// → "Feb 24 2026 06:04:07"
+```
+
+---
+
 ## DateTime Format
 
 The `dateTimeFormat` prop controls the two-line datetime display in the control bar. It accepts a token-based format string.
@@ -357,6 +414,88 @@ const [pickerOpen, setPickerOpen] = useState(false);
 
 ---
 
+## Labels & i18n
+
+Every label and tooltip in the control bar is overridable via the `labels` prop. Pass a `Partial<TimelineLabels>` object — only the keys you provide are changed; everything else falls back to the English defaults.
+
+### `TimelineLabels` reference
+
+| Key | Default (English) | Notes |
+|-----|-------------------|-------|
+| `dateTimeClickTooltip` | `"Click to jump to a date/time"` | Tooltip on the datetime display when `onDateTimeClick` is wired up |
+| `liveLabel` | `"LIVE"` | LIVE button text when not at live time |
+| `liveActiveLabel` | `"● LIVE"` | LIVE button text when at live time |
+| `liveTooltip` | `"Jump to live (now)"` | LIVE button tooltip when not at live time |
+| `liveActiveTooltip` | `"Currently live"` | LIVE button tooltip when at live time |
+| `resetSpeedTooltip` | `"Reset to 1× speed"` | Tooltip on the speed-reset badge |
+| `jumpToStartTooltip` | `"Jump to start"` | ⏮ button tooltip when a start time is set |
+| `noStartTimeTooltip` | `"No start time set"` | ⏮ button tooltip when no start time is set |
+| `jumpToEndTooltip` | `"Jump to end"` | ⏭ button tooltip when an end time is set |
+| `noEndTimeTooltip` | `"No end time set"` | ⏭ button tooltip when no end time is set |
+| `rewindTooltip` | `"Rewind"` | ◀◀ button tooltip at normal speed |
+| `rewindActiveTooltip` | `(n) => "Reverse N× — click to speed up…"` | ◀◀ button tooltip while rewinding — receives the current multiplier |
+| `playTooltip` | `"Play"` | ▶ button tooltip when stopped |
+| `playFromRewindTooltip` | `"Play (reset to 1×)"` | ▶ button tooltip when coming out of rewind |
+| `pauseTooltip` | `"Pause"` | ▶ button tooltip when playing |
+| `fastForwardTooltip` | `"Fast forward"` | ▶▶ button tooltip at normal speed |
+| `fastForwardActiveTooltip` | `(n) => "N× speed — click to increase…"` | ▶▶ button tooltip while fast-forwarding — receives the current multiplier |
+| `collapseSwimLanesTooltip` | `"Collapse swim lanes"` | Chevron button tooltip when lanes are visible |
+| `expandSwimLanesTooltip` | `"Expand swim lanes"` | Chevron button tooltip when lanes are hidden |
+
+Dynamic fields (`rewindActiveTooltip`, `fastForwardActiveTooltip`) accept either a **static string** or a **function** `(multiplier: number) => string`. Use a function when you want to embed the speed value in your translated string.
+
+### React example
+
+```tsx
+import { Timeline } from '@kteneyck/cesium-timeline-react';
+import type { TimelineLabels } from '@kteneyck/cesium-timeline-core';
+
+const frLabels: Partial<TimelineLabels> = {
+  playTooltip: 'Lecture',
+  pauseTooltip: 'Pause',
+  liveLabel: 'EN DIRECT',
+  liveActiveLabel: '● EN DIRECT',
+  liveTooltip: 'Aller en direct',
+  liveActiveTooltip: 'Vous êtes en direct',
+  rewindTooltip: 'Retour rapide',
+  rewindActiveTooltip: (n) => `Retour ${n}× — cliquer pour accélérer`,
+  fastForwardTooltip: 'Avance rapide',
+  fastForwardActiveTooltip: (n) => `${n}× — cliquer pour augmenter la vitesse`,
+  collapseSwimLanesTooltip: 'Réduire les pistes',
+  expandSwimLanesTooltip: 'Développer les pistes',
+};
+
+<Timeline clock={viewer.clock} labels={frLabels} height={120} />
+```
+
+### Angular example
+
+```typescript
+// component.ts
+import type { TimelineLabels } from '@kteneyck/cesium-timeline-core';
+
+@Component({ ... })
+export class AppComponent {
+  frLabels: Partial<TimelineLabels> = {
+    playTooltip: 'Lecture',
+    pauseTooltip: 'Pause',
+    liveLabel: 'EN DIRECT',
+    liveActiveLabel: '● EN DIRECT',
+    liveTooltip: 'Aller en direct',
+    liveActiveTooltip: 'Vous êtes en direct',
+    rewindActiveTooltip: (n) => `Retour ${n}× — cliquer pour accélérer`,
+    fastForwardActiveTooltip: (n) => `${n}× — cliquer pour augmenter la vitesse`,
+  };
+}
+```
+
+```html
+<!-- component.html -->
+<ct-timeline [clock]="clock" [labels]="frLabels" [height]="120" />
+```
+
+---
+
 ## Exports
 
 ### React
@@ -385,7 +524,10 @@ import {
 ```tsx
 import {
   DateTimeFormats,   // Format string presets
-  formatDateTime,    // Token-based date formatter
+  Timezones,         // { LOCAL: 'local', UTC: 'UTC' } convenience constants
+  DEFAULT_LABELS,    // Default English label/tooltip strings
+  formatDateTime,    // Token-based date formatter (date, format, timezone?)
+  getTimezoneAbbr,   // Short timezone abbreviation for a date (date, timezone?)
   splitForDisplay,   // Split format string into time/date parts
   toJulianDate,      // Convert Date | JulianDate → JulianDate
   toDate,            // Convert Date | JulianDate → Date
@@ -401,6 +543,7 @@ import {
 // TypeScript types
 import type {
   TimelineTheme,
+  TimelineLabels,
   SwimLane,
   SwimLaneItem,
   SwimLaneItemStyle,