@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.94 → 2.0.0-next.95

package/src/charthelpers/x-value.spec.ts

@@ -0,0 +1,102 @@
+import {describe, expect, it} from 'vitest';
+import {formatXValue, normalizeXValue, XValueMode} from './x-value.js';
+
+describe('normalizeXValue', () => {
+  it('passes finite numbers through in both modes', () => {
+    expect(normalizeXValue(1751790000000, XValueMode.time)).toBe(1751790000000);
+    expect(normalizeXValue(42.5, XValueMode.number)).toBe(42.5);
+  });
+
+  it('returns NaN for non-finite numbers', () => {
+    expect(normalizeXValue(Infinity, XValueMode.time)).toBeNaN();
+    expect(normalizeXValue(NaN, XValueMode.number)).toBeNaN();
+  });
+
+  it('converts Date via getTime()', () => {
+    const d = new Date('2026-07-06T10:00:00Z');
+    expect(normalizeXValue(d, XValueMode.time)).toBe(d.getTime());
+  });
+
+  it('uses epochMilliseconds for Temporal Instant/ZonedDateTime shapes', () => {
+    expect(
+      normalizeXValue({epochMilliseconds: 1751790000000}, XValueMode.time)
+    ).toBe(1751790000000);
+  });
+
+  it('prefers epochMilliseconds when a ZonedDateTime-like also has year/month/day', () => {
+    expect(
+      normalizeXValue(
+        {epochMilliseconds: 123, year: 2026, month: 7, day: 6},
+        XValueMode.time
+      )
+    ).toBe(123);
+  });
+
+  it('interprets PlainDateTime-like shapes in the system time zone', () => {
+    const v = {year: 2026, month: 7, day: 6, hour: 10, minute: 30};
+    expect(normalizeXValue(v, XValueMode.time)).toBe(
+      new Date(2026, 6, 6, 10, 30, 0, 0).getTime()
+    );
+  });
+
+  it('interprets PlainDate-like shapes as local midnight', () => {
+    expect(
+      normalizeXValue({year: 2026, month: 7, day: 6}, XValueMode.time)
+    ).toBe(new Date(2026, 6, 6).getTime());
+  });
+
+  it('parses ISO strings in time mode', () => {
+    expect(normalizeXValue('2026-07-06T10:00:00Z', XValueMode.time)).toBe(
+      Date.parse('2026-07-06T10:00:00Z')
+    );
+  });
+
+  it('falls back to Number() for numeric strings in time mode', () => {
+    expect(normalizeXValue('1751790000000', XValueMode.time)).toBe(
+      1751790000000
+    );
+  });
+
+  it('only accepts numeric strings in number mode', () => {
+    expect(normalizeXValue('42.5', XValueMode.number)).toBe(42.5);
+    expect(normalizeXValue('2026-07-06', XValueMode.number)).toBeNaN();
+  });
+
+  it('returns NaN for garbage input', () => {
+    expect(normalizeXValue('not a date', XValueMode.time)).toBeNaN();
+    expect(normalizeXValue('', XValueMode.time)).toBeNaN();
+    expect(normalizeXValue({} as never, XValueMode.time)).toBeNaN();
+    expect(normalizeXValue(null as never, XValueMode.time)).toBeNaN();
+    expect(normalizeXValue(undefined as never, XValueMode.time)).toBeNaN();
+  });
+});
+
+describe('formatXValue', () => {
+  it('formats relative minutes when a reference is given', () => {
+    const ref = 1751790000000;
+    expect(formatXValue(ref + 5 * 60000, XValueMode.time, ref)).toBe('5min');
+    expect(formatXValue(ref - 3 * 60000, XValueMode.time, ref)).toBe('-3min');
+  });
+
+  it('renders a locale date when no reference is given', () => {
+    const ts = Date.parse('2026-07-06T10:00:00Z');
+    expect(formatXValue(ts, XValueMode.time)).toBe(
+      new Date(ts).toLocaleDateString()
+    );
+  });
+
+  it('ignores a non-finite reference', () => {
+    const ts = Date.parse('2026-07-06T10:00:00Z');
+    expect(formatXValue(ts, XValueMode.time, NaN)).toBe(
+      new Date(ts).toLocaleDateString()
+    );
+  });
+
+  it('formats number mode as plain string, even with a reference', () => {
+    expect(formatXValue(42.5, XValueMode.number, 1000)).toBe('42.5');
+  });
+
+  it('returns empty string for non-finite values', () => {
+    expect(formatXValue(NaN, XValueMode.time)).toBe('');
+  });
+});

package/src/charthelpers/x-value.ts

@@ -0,0 +1,134 @@
+/**
+ * X-value normalization and formatting for line/area charts.
+ *
+ * Charts accept x-values as epoch milliseconds, ISO-8601 strings, `Date`
+ * instances, or Temporal objects (`Instant`, `ZonedDateTime`,
+ * `PlainDateTime`, `PlainDate`). All are normalized to a single number
+ * (epoch milliseconds in `'time'` mode, the plain value in `'number'` mode)
+ * so the Chart.js linear scale positions points proportionally.
+ *
+ * Temporal support is structural (duck-typed): there is no dependency on the
+ * Temporal API or a polyfill, and cross-realm/polyfilled objects work.
+ * Plain* types (which carry no time zone) are interpreted in the system
+ * time zone.
+ *
+ * @example
+ * ```ts
+ * normalizeXValue('2026-07-06T10:00:00Z', XValueMode.time); // epoch ms
+ * normalizeXValue(new Date(0), XValueMode.time); // 0
+ * normalizeXValue({epochMilliseconds: 42}, XValueMode.time); // 42 (Temporal)
+ * normalizeXValue('2.5', XValueMode.number); // 2.5
+ *
+ * formatXValue(ms, XValueMode.time, referenceMs); // '5min' (relative)
+ * formatXValue(ms, XValueMode.time); // locale date string
+ * formatXValue(2.5, XValueMode.number); // '2.5'
+ * ```
+ */
+
+type TemporalEpochLike = {
+  epochMilliseconds: number;
+};
+
+type TemporalPlainLike = {
+  year: number;
+  month: number;
+  day: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+};
+
+/** Structural type covering the supported Temporal object shapes. */
+export type TemporalLike = TemporalEpochLike | TemporalPlainLike;
+
+/** Every value accepted as a chart x-coordinate. */
+export type ChartXValue = number | string | Date | TemporalLike;
+
+/** X-axis interpretation used for normalization and formatting. */
+export enum XValueMode {
+  time = 'time',
+  number = 'number',
+}
+
+function isTemporalEpochLike(v: object): v is TemporalEpochLike {
+  return typeof (v as TemporalEpochLike).epochMilliseconds === 'number';
+}
+
+function isTemporalPlainLike(v: object): v is TemporalPlainLike {
+  const t = v as TemporalPlainLike;
+  return (
+    typeof t.year === 'number' &&
+    typeof t.month === 'number' &&
+    typeof t.day === 'number'
+  );
+}
+
+/**
+ * Normalize an x-value to a finite number, or NaN when unusable.
+ *
+ * Rules, in order:
+ * 1. `number` → as-is (epoch ms in time mode, plain value in number mode)
+ * 2. `Date` → `getTime()`
+ * 3. `{epochMilliseconds}` (Temporal Instant / ZonedDateTime) → epoch ms
+ * 4. `{year, month, day, …}` (Temporal PlainDateTime / PlainDate) →
+ *    epoch ms in the system time zone
+ * 5. `string` → time mode: `Date.parse()` first, `Number()` fallback;
+ *    number mode: `Number()` only
+ */
+export function normalizeXValue(v: ChartXValue, mode: XValueMode): number {
+  if (typeof v === 'number') {
+    return Number.isFinite(v) ? v : NaN;
+  }
+  if (v instanceof Date) {
+    return v.getTime();
+  }
+  if (typeof v === 'object' && v !== null) {
+    if (isTemporalEpochLike(v)) return v.epochMilliseconds;
+    if (isTemporalPlainLike(v)) {
+      return new Date(
+        v.year,
+        v.month - 1,
+        v.day,
+        v.hour ?? 0,
+        v.minute ?? 0,
+        v.second ?? 0,
+        v.millisecond ?? 0
+      ).getTime();
+    }
+    return NaN;
+  }
+  if (typeof v === 'string') {
+    if (v.trim() === '') return NaN;
+    if (mode === XValueMode.time) {
+      const parsed = Date.parse(v);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+    const numeric = Number(v);
+    return Number.isFinite(numeric) ? numeric : NaN;
+  }
+  return NaN;
+}
+
+/**
+ * Format a normalized x-value for axis tick labels and tooltips.
+ *
+ * Mirrors the historical chart-line tick formatting exactly: with a finite
+ * `relativeToMs` (time mode) renders `<n>min` relative to it; without one
+ * renders `toLocaleDateString()`. Number mode renders the plain value.
+ * Callers express the `TimeDisplay` choice by passing or omitting
+ * `relativeToMs`.
+ */
+export function formatXValue(
+  value: number,
+  mode: XValueMode,
+  relativeToMs?: number
+): string {
+  if (!Number.isFinite(value)) return '';
+  if (mode === XValueMode.number) return String(value);
+  if (relativeToMs !== undefined && Number.isFinite(relativeToMs)) {
+    const minutes = Math.round((value - relativeToMs) / 60000);
+    return `${minutes}min`;
+  }
+  return new Date(value).toLocaleDateString();
+}

package/src/navigation-instruments/gauge-trend/gauge-trend.stories.ts

@@ -43,6 +43,19 @@ const SAMPLE_DATA = [
   {label: '30', value: 50},
 ];
 
+const UNEVEN_TIME_DATA = [
+  {x: '2026-07-06T10:00:00Z', value: 45},
+  {x: '2026-07-06T10:02:00Z', value: 52},
+  {x: '2026-07-06T10:03:00Z', value: 48},
+  {x: '2026-07-06T10:10:00Z', value: 55},
+  {x: '2026-07-06T10:11:00Z', value: 62},
+  {x: '2026-07-06T10:25:00Z', value: 58},
+  {x: '2026-07-06T10:26:00Z', value: 52},
+  {x: '2026-07-06T10:40:00Z', value: 40},
+  {x: '2026-07-06T11:20:00Z', value: 35},
+  {x: '2026-07-06T11:21:00Z', value: 50},
+];
+
 const meta: Meta = {
   title: 'Instruments/Gauge Trend',
   tags: ['autodocs', '6.0'],
@@ -253,6 +266,35 @@ export const GaugeTrend: Story = {
   `,
 };
 
+export const UnevenTimeIntervals: Story = {
+  name: 'Uneven Time Intervals (Auto Time Axis)',
+  play: async () => {
+    // Wait for rendering to complete before snapshot
+    await new Promise((resolve) => setTimeout(resolve, 300));
+  },
+  render: (_args) => html`
+    <obc-gauge-trend
+      .data=${UNEVEN_TIME_DATA}
+      .width=${_args.width}
+      .height=${_args.height}
+      .priority=${_args.priority}
+      .chartFill=${_args.chartFill}
+      .minValue=${_args.minValue ?? 0}
+      .maxValue=${_args.maxValue ?? 100}
+      .value=${_args.value}
+      .setpoint=${_args.setpoint}
+      .touching=${_args.touching}
+      .hasBar=${_args.hasBar}
+      .hasScale=${_args.hasScale}
+      .fillMode=${_args.fillMode}
+      .fillMin=${_args.fillMin}
+      .primaryTickmarkInterval=${10}
+      .secondaryTickmarkInterval=${5}
+    >
+    </obc-gauge-trend>
+  `,
+};
+
 export const GaugeTrendScaleReferenceSize: Story = {
   name: 'Using ScaleReferenceSize=240',
   play: async () => {

package/src/navigation-instruments/gauge-trend/gauge-trend.ts

@@ -40,7 +40,9 @@ export {FillMode, ScaleType};
  * ## Locked Configuration (not user-configurable)
  * - Fixed aspect ratio scaling: always enabled
  * - Instrument mode: always enabled (8px border radius)
- * - X-axis type: always 'category'
+ * - X-axis type: auto-detected — 'category' for `{label, value}` data,
+ *   'time' for `{x, value}` data (uneven intervals position proportionally).
+ *   Assigning `xAxisType` explicitly disables auto-detection.
  * - Line mode: always 'smooth'
  * - Grid, tick marks, points, legend: always hidden
  * - Scale advice position: always 'inner'
@@ -102,6 +104,17 @@ export {FillMode, ScaleType};
  * ></obc-gauge-trend>
  * ```
  *
+ * ### Time-based data with uneven intervals
+ * ```html
+ * <obc-gauge-trend
+ *   .data=${[
+ *     {x: '2026-07-06T10:00:00Z', value: 3.5},
+ *     {x: '2026-07-06T10:03:00Z', value: 4.2},
+ *     {x: '2026-07-06T10:15:00Z', value: 5.0}
+ *   ]}
+ * ></obc-gauge-trend>
+ * ```
+ *
  * @property {number} width - Chart width in pixels (defines aspect ratio)
  * @property {number} height - Chart height in pixels (defines aspect ratio)
  * @property {boolean} enhanced - Use enhanced color palette for chart and scales
@@ -119,6 +132,8 @@ export {FillMode, ScaleType};
 export class ObcGaugeTrend extends SetpointMixin(ObcChartLineBase) {
   private _barVerticalElement?: HTMLElement;
   private _isFirstUpdate = false;
+  private _explicitXAxisType = false;
+  private _autoAppliedXAxisType?: XAxisType;
 
   constructor() {
     super();
@@ -456,6 +471,28 @@ export class ObcGaugeTrend extends SetpointMixin(ObcChartLineBase) {
   }
 
   override willUpdate(changed: Map<PropertyKey, unknown>) {
+    // Auto axis detection: {x, value} data switches to time spacing, {label,
+    // value} stays category. An explicit xAxisType assignment (anything we
+    // did not auto-apply) permanently disables auto-detection. The
+    // constructor's 'category' default lands in the first changed-map but is
+    // not treated as explicit (hasUpdated is false and it equals the default).
+    if (
+      changed.has('xAxisType') &&
+      this.xAxisType !== this._autoAppliedXAxisType &&
+      (this.hasUpdated || this.xAxisType !== XAxisType.category)
+    ) {
+      this._explicitXAxisType = true;
+    }
+    if (!this._explicitXAxisType && changed.has('data')) {
+      const allHaveX =
+        (this.data?.length ?? 0) > 0 && this.data.every((d) => d.x != null);
+      const target = allHaveX ? XAxisType.time : XAxisType.category;
+      if (this.xAxisType !== target) {
+        this._autoAppliedXAxisType = target;
+        this.xAxisType = target;
+      }
+    }
+
     super.willUpdate(changed);
 
     // Update y-axis range when chart or scale min/max changes