@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.115 → 2.0.0-next.116

package/src/building-blocks/readout-block/readout-block.ts

@@ -17,6 +17,7 @@ import {
   assertReadoutValueType,
   resolveReadoutNumericValue,
   resolveReadoutTextValue,
+  READOUT_UNAVAILABLE_DASH,
   ReadoutValueType,
   type ReadoutNumericFormatOptions,
 } from '../../navigation-instruments/readout/readout-formatters.js';
@@ -215,6 +216,9 @@ export class ObcReadoutBlock extends LitElement {
 
   private get numericFormatOptions(): ReadoutNumericFormatOptions {
     return {
+      // The unavailable placeholder stays short (`\u2012.\u2012\u2012`) rather than
+      // spelling out every reserved digit position — `maxDigits` already
+      // reserves the width, so it simply sits at the right edge of it.
       showZeroPadding: false,
       minValueLength: this.maxDigits,
       fractionDigits: this.fractionDigits,
@@ -334,7 +338,7 @@ export class ObcReadoutBlock extends LitElement {
     const text = this.off
       ? this.offText
       : isTextMode
-        ? (textValue ?? '-')
+        ? (textValue ?? READOUT_UNAVAILABLE_DASH)
         : formatNumericValue(valueForFormat, formatOptions);
     // Hinted zeros pad the INTEGER part up to `maxDigits`, independent of
     // `fractionDigits` (the decimal point and fraction digits never count toward

package/src/navigation-instruments/readout/readout-formatters.spec.ts

@@ -3,8 +3,10 @@ import {
   assertReadoutValueType,
   resolveReadoutNumericValue,
   resolveReadoutTextValue,
+  formatNumericValue,
   isReadoutValueType,
   ReadoutValueType,
+  READOUT_UNAVAILABLE_DASH,
 } from './readout-formatters.js';
 
 describe('assertReadoutValueType', () => {
@@ -181,11 +183,50 @@ describe('resolveReadoutNumericValue', () => {
     ).toBeUndefined();
   });
 
-  // Pre-existing behaviour, deliberately preserved: NaN reaches the formatter.
-  it('passes NaN through in number mode', () => {
+  // A non-finite number is unavailable, not a reading: `toFixed` would render
+  // the literal text "NaN" / "Infinity" in place of a value.
+  it('is undefined for a non-finite number', () => {
     expect(
       resolveReadoutNumericValue(Number.NaN, ReadoutValueType.number)
-    ).toBeNaN();
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue(
+        Number.POSITIVE_INFINITY,
+        ReadoutValueType.number
+      )
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue(
+        Number.NEGATIVE_INFINITY,
+        ReadoutValueType.number
+      )
+    ).toBeUndefined();
+  });
+
+  // `.value=${undefined}` reaches the property uncoerced, so an unset value must
+  // read exactly like an explicit `null` — both are "no reading".
+  it('treats undefined and null identically', () => {
+    expect(resolveReadoutNumericValue(undefined, ReadoutValueType.number)).toBe(
+      resolveReadoutNumericValue(null, ReadoutValueType.number)
+    );
+    expect(resolveReadoutTextValue(undefined, ReadoutValueType.text)).toBe(
+      resolveReadoutTextValue(null, ReadoutValueType.text)
+    );
+  });
+
+  // Before this, the same logical input resolved differently depending on how
+  // it was bound: `<obc-readout value="NaN">` (attribute → string) gave a dash,
+  // while `.value=${NaN}` (property → number) gave the literal text "NaN".
+  it('resolves a non-finite value identically as a number and as a string', () => {
+    expect(
+      resolveReadoutNumericValue(Number.NaN, ReadoutValueType.number)
+    ).toBe(resolveReadoutNumericValue('NaN', ReadoutValueType.number));
+    expect(
+      resolveReadoutNumericValue(
+        Number.POSITIVE_INFINITY,
+        ReadoutValueType.number
+      )
+    ).toBe(resolveReadoutNumericValue('Infinity', ReadoutValueType.number));
   });
 });
 
@@ -227,3 +268,102 @@ describe('resolveReadoutTextValue', () => {
     ).toBeUndefined();
   });
 });
+
+describe('formatNumericValue — unavailable value', () => {
+  const opts = (minValueLength: number, fractionDigits: number) => ({
+    showZeroPadding: false,
+    minValueLength,
+    fractionDigits,
+  });
+  const D = READOUT_UNAVAILABLE_DASH;
+
+  // U+2012 FIGURE DASH, not the ASCII hyphen. It is defined to be digit-width,
+  // so the placeholder's decimal point and fraction positions line up with the
+  // reading it replaces; measured in Noto Sans, a digit and U+2012 are both
+  // 13.02px while U+002D is 7.02px. `tabular-nums` does not fix this — it
+  // equalises figures with each other and leaves punctuation alone.
+  it('uses the digit-width figure dash, not a hyphen', () => {
+    expect(D).toBe('\u2012');
+    expect(formatNumericValue(undefined, opts(0, 0))).not.toContain('-');
+  });
+
+  // Deliberately short: `maxDigits` reserves the width, so the placeholder sits
+  // at the right edge of it rather than spelling out every reserved position.
+  it('is one integer dash plus one per fraction digit', () => {
+    expect(formatNumericValue(undefined, opts(0, 0))).toBe(D);
+    expect(formatNumericValue(undefined, opts(0, 2))).toBe(`${D}.${D}${D}`);
+    expect(formatNumericValue(undefined, opts(3, 2))).toBe(`${D}.${D}${D}`);
+  });
+
+  it('does not grow with maxDigits', () => {
+    expect(formatNumericValue(undefined, opts(4, 3))).toBe(
+      formatNumericValue(undefined, opts(0, 3))
+    );
+  });
+
+  // `formatNumericValue` is exported, so it must hold the line itself rather
+  // than trusting every caller to have normalised first — `NaN.toFixed()`
+  // would otherwise put the literal text "NaN" where a reading belongs.
+  it('treats a non-finite argument as unavailable without normalisation', () => {
+    expect(formatNumericValue(Number.NaN, opts(3, 2))).toBe(`${D}.${D}${D}`);
+    expect(formatNumericValue(Number.POSITIVE_INFINITY, opts(3, 2))).toBe(
+      `${D}.${D}${D}`
+    );
+    expect(formatNumericValue(Number.NEGATIVE_INFINITY, opts(3, 2))).toBe(
+      `${D}.${D}${D}`
+    );
+  });
+
+  it('still formats a finite value', () => {
+    expect(formatNumericValue(12.3, opts(3, 2))).toBe('12.30');
+    expect(formatNumericValue(0, opts(0, 0))).toBe('0');
+    expect(formatNumericValue(-4.5, opts(3, 1))).toBe('-4.5');
+  });
+
+  // The whole point of routing non-finite numbers through the same path.
+  it('renders a non-finite number as the unavailable dash', () => {
+    const resolved = resolveReadoutNumericValue(
+      Number.NaN,
+      ReadoutValueType.number
+    );
+    expect(formatNumericValue(resolved, opts(4, 1))).toBe(`${D}.${D}`);
+  });
+});
+
+// The designer's specification, verbatim:
+//   format: 000.00
+//   readout: 12.30
+//   readout with hinted: 012.30  (hinted colour on the first zero)
+//   Not available: -.--   (revised in review from ---.--)
+// `format: 000.00` is maxDigits 3 + fractionDigits 2.
+describe("designer's format specification (000.00)", () => {
+  const MAX_DIGITS = 3;
+  const FRACTION_DIGITS = 2;
+  const opts = {
+    showZeroPadding: false,
+    minValueLength: MAX_DIGITS,
+    fractionDigits: FRACTION_DIGITS,
+  };
+
+  it('renders a reading as 12.30', () => {
+    expect(formatNumericValue(12.3, opts)).toBe('12.30');
+  });
+
+  // The specification's hinted line (`012.30`) is covered by the hinted-zeros
+  // change, not here — this PR only owns the unavailable placeholder. The
+  // rendered hinted case is still shown in the story for the designer.
+
+  it('renders an unavailable value as -.-- (short form)', () => {
+    expect(formatNumericValue(undefined, opts)).toBe(
+      `${READOUT_UNAVAILABLE_DASH}.${READOUT_UNAVAILABLE_DASH}${READOUT_UNAVAILABLE_DASH}`
+    );
+  });
+
+  // The placeholder is deliberately shorter than the reading now; `maxDigits`
+  // reserves the width, so it right-aligns inside it instead of filling it.
+  it('is shorter than the reading, sitting at the right of the reserve', () => {
+    expect(formatNumericValue(undefined, opts).length).toBeLessThan(
+      '012.30'.length
+    );
+  });
+});

package/src/navigation-instruments/readout/readout-formatters.ts

@@ -71,7 +71,18 @@ export function assertReadoutValueType(
   );
 }
 
-/** The value as a number, or `undefined` when it is text / unavailable. */
+/**
+ * The value as a number, or `undefined` when it is text / unavailable.
+ *
+ * A non-finite number (`NaN`, `±Infinity`) counts as unavailable and renders the
+ * dash, the same as `null`. `NaN` is a runtime data condition — a sensor
+ * dropout, a `0/0`, a bad parse — not a programmer error, so it must not throw;
+ * and `value.toFixed()` would otherwise render the literal text `"NaN"` /
+ * `"Infinity"` in place of a reading. This also makes the number path agree with
+ * the string path below, which has always resolved a non-finite string to
+ * `undefined` — before this, `<obc-readout value="NaN">` rendered a dash while
+ * `.value=${NaN}` rendered `"NaN"`.
+ */
 export function resolveReadoutNumericValue(
   value: number | string | null | undefined,
   valueType: ReadoutValueType
@@ -84,7 +95,7 @@ export function resolveReadoutNumericValue(
     return undefined;
   }
   if (typeof value === 'number') {
-    return value;
+    return Number.isFinite(value) ? value : undefined;
   }
   if (isBlank(value)) {
     return undefined;
@@ -109,6 +120,27 @@ export function resolveReadoutTextValue(
   return isBlank(text) ? undefined : text;
 }
 
+/**
+ * The character used for an unavailable ("no reading") value.
+ *
+ * U+2012 FIGURE DASH, not the ASCII hyphen-minus: it is defined to be the same
+ * width as a digit, so the placeholder lines up with the reading it stands in
+ * for. Measured in Noto Sans with tabular figures at `size="m"` — digit 13.02px,
+ * U+2012 13.02px, U+002D 7.02px, en dash 11.02px, em dash 22.02px. With a
+ * hyphen, `-.--` sat 46% narrow per character and its decimal point missed the
+ * reading's; with U+2012 the point and every fraction position align exactly.
+ */
+export const READOUT_UNAVAILABLE_DASH = '\u2012';
+
+/**
+ * The unavailable ("no reading") text: a single integer dash plus one dash per
+ * fraction digit — `\u2012` at `fractionDigits` 0, `\u2012.\u2012\u2012` at 2.
+ *
+ * Deliberately NOT filled out to `maxDigits`: the placeholder stays short and
+ * sits at the right edge of the reserved width, rather than spelling out every
+ * reserved digit position. `maxDigits` still reserves the width, so nothing
+ * shifts when a reading arrives.
+ */
 function dashedGenerator({
   showZeroPadding,
   minValueLength,
@@ -117,13 +149,15 @@ function dashedGenerator({
   const visibleDigits = showZeroPadding ? Math.max(minValueLength, 1) : 1;
 
   if (fractionDigits < 1) {
-    return '-'.repeat(visibleDigits);
+    return READOUT_UNAVAILABLE_DASH.repeat(visibleDigits);
   }
 
   const integerDigits = visibleDigits - fractionDigits;
 
   return (
-    '-'.repeat(Math.max(integerDigits, 1)) + '.' + '-'.repeat(fractionDigits)
+    READOUT_UNAVAILABLE_DASH.repeat(Math.max(integerDigits, 1)) +
+    '.' +
+    READOUT_UNAVAILABLE_DASH.repeat(fractionDigits)
   );
 }
 
@@ -131,7 +165,11 @@ export function formatNumericValue(
   value: number | undefined,
   options: ReadoutNumericFormatOptions
 ): string {
-  if (value === undefined) {
+  // Non-finite counts as unavailable here too, not only in
+  // `resolveReadoutNumericValue`. Every caller normalises today, but this
+  // function is exported, and `NaN.toFixed()` would put the literal text
+  // "NaN" where a reading belongs — the exact failure this change removes.
+  if (value === undefined || !Number.isFinite(value)) {
     return dashedGenerator(options);
   }
 

package/src/navigation-instruments/readout/readout-shared.spec.ts

@@ -58,6 +58,19 @@ describe('isDisplayedAtSetpoint', () => {
       isDisplayedAtSetpoint(30, undefined, readoutNumericFormatOptions(0, 0))
     ).toBe(false);
   });
+
+  // Callers normalise `value` but pass `setpoint` raw, so a non-finite setpoint
+  // would otherwise be formatted as the literal "NaN" / "Infinity" and compared
+  // as a string. An unavailable reading is never "at" a setpoint.
+  it('is false when either side is non-finite', () => {
+    const format = readoutNumericFormatOptions(0, 0);
+    expect(isDisplayedAtSetpoint(30, Number.NaN, format)).toBe(false);
+    expect(isDisplayedAtSetpoint(30, Number.POSITIVE_INFINITY, format)).toBe(
+      false
+    );
+    expect(isDisplayedAtSetpoint(Number.NaN, 30, format)).toBe(false);
+    expect(isDisplayedAtSetpoint(Number.NaN, Number.NaN, format)).toBe(false);
+  });
 });
 
 describe('readoutPrimarySize / readoutSecondarySize', () => {

package/src/navigation-instruments/readout/readout-shared.ts

@@ -47,6 +47,12 @@ export function readoutNumericFormatOptions(
   fractionDigits: number
 ): ReadoutNumericFormatOptions {
   return {
+    // Comparison-only (see `isDisplayedAtSetpoint`), which returns early unless
+    // both operands are finite numbers — so `formatNumericValue` never reaches
+    // its unavailable-dash branch here and the padding would have no effect.
+    // `obc-readout-block` sets it to `false` for rendering as well, since the
+    // unavailable placeholder is deliberately short rather than filled out to
+    // `maxDigits`. Nothing enables it today.
     showZeroPadding: false,
     minValueLength: maxDigits,
     fractionDigits,
@@ -66,6 +72,16 @@ export function isDisplayedAtSetpoint(
   if (value === null || setpoint === undefined) {
     return false;
   }
+  // An unavailable reading is never "at" the setpoint. Callers normalise
+  // `value` (via `resolveReadoutNumericValue`) but pass `setpoint` raw, so a
+  // non-finite setpoint would otherwise be formatted as the literal "NaN" /
+  // "Infinity" and compared as a string. The comparison result happens to be
+  // correct either way — a normalised `value` can never also format to "NaN" —
+  // but guarding both keeps the two operands symmetric and the invariant below
+  // honest.
+  if (!Number.isFinite(value) || !Number.isFinite(setpoint)) {
+    return false;
+  }
   return (
     formatNumericValue(value, formatOptions) ===
     formatNumericValue(setpoint, formatOptions)

package/src/navigation-instruments/readout/readout.stories.ts

@@ -1303,6 +1303,116 @@ export const TextValue: Story = {
     ]),
 };
 
+/**
+ * **Unavailable values in a full readout — for design review.**
+ *
+ * The same change as `Building Blocks/Readout Block → Unavailable Values`, shown
+ * with a label and unit so the placeholder can be judged in the context an
+ * instrument actually renders.
+ *
+ * - The placeholder stays short (`-.-`) and sits at the right edge of the width
+ *   `maxDigits` reserves, rather than spelling out every reserved position.
+ * - The dash is U+2012 FIGURE DASH, which is digit-width, so its decimal point
+ *   and fraction positions line up with the reading it replaces. The ASCII
+ *   hyphen is 46% narrower and did not align.
+ * - `NaN` / `±Infinity` render the dash instead of the literal text `NaN` /
+ *   `Infinity`.
+ *
+ * Each section pairs the placeholder with a live reading under identical
+ * settings, so the two can be compared directly.
+ */
+export const UnavailableValues: Story = {
+  render: () =>
+    renderShowcase([
+      {
+        title: 'Unavailable vs. a Reading (maxDigits 4, Fraction 1)',
+        columns: 3,
+        cases: [
+          {
+            label: 'null → dash',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: null,
+              options: {maxDigits: 4, fractionDigits: 1},
+            },
+          },
+          {
+            label: 'NaN → dash (was "NaN")',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: Number.NaN,
+              options: {maxDigits: 4, fractionDigits: 1},
+            },
+          },
+          {
+            label: 'reading, identical settings',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: 12.4,
+              options: {maxDigits: 4, fractionDigits: 1},
+            },
+          },
+        ],
+      },
+      {
+        // Both cards enable hintedZeros, so the placeholder and the reading are
+        // compared under identical settings here too.
+        title: 'With Hinted Zeros (maxDigits 4, Fraction 1)',
+        columns: 2,
+        cases: [
+          {
+            label: 'null + hinted zeros',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: null,
+              options: {
+                maxDigits: 4,
+                fractionDigits: 1,
+                value: {hintedZeros: true},
+              },
+            },
+          },
+          {
+            label: 'reading + hinted zeros',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: 12.4,
+              options: {
+                maxDigits: 4,
+                fractionDigits: 1,
+                value: {hintedZeros: true},
+              },
+            },
+          },
+        ],
+      },
+      {
+        title: 'No maxDigits — Same Placeholder, Narrower Reserve',
+        columns: 2,
+        cases: [
+          {
+            label: 'null',
+            config: {label: 'SOG', unit: 'kn', value: null, options: {}},
+          },
+          {
+            label: 'null / fraction 1',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: null,
+              options: {fractionDigits: 1},
+            },
+          },
+        ],
+      },
+    ]),
+};
+
 export const TestCases: Story = {
   render: () => {
     return html` <style>