@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.121 → 2.0.0-next.122

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

@@ -21,6 +21,115 @@ export function isReadoutValueType(value: unknown): value is ReadoutValueType {
   return typeof value === 'string' && READOUT_VALUE_TYPES.includes(value);
 }
 
+/**
+ * The largest `fractionDigits` `Number.prototype.toFixed` accepts. Reused as the
+ * `maxDigits` ceiling so the two bounds stay symmetric — a wider reserve than
+ * this is meaningless anyway, and an unbounded one builds a huge string.
+ */
+export const READOUT_MAX_DIGITS = 100;
+
+/**
+ * `fractionDigits` as `toFixed` will actually read it: `NaN` and an unset value
+ * count as 0, and a fractional count truncates.
+ */
+function effectiveFractionDigits(
+  fractionDigits: number | null | undefined
+): number {
+  // `toFixed(undefined)` behaves as `toFixed(0)`, and the components read
+  // `fractionDigits ?? 0`, so an unset value must not be rejected here — the
+  // assertion has to accept exactly what the runtime accepts.
+  if (fractionDigits === null || fractionDigits === undefined) {
+    return 0;
+  }
+  return Number.isNaN(fractionDigits) ? 0 : Math.trunc(fractionDigits);
+}
+
+/**
+ * Throws when `fractionDigits` is outside the range `toFixed` accepts.
+ *
+ * It is a public property that reaches `Number.prototype.toFixed` unchanged, so
+ * `-1`, `101` or `Infinity` already throw a bare
+ * `RangeError: toFixed() digits argument must be between 0 and 100` from inside
+ * the update cycle. This replaces that with an error naming the component and
+ * the offending value.
+ *
+ * Deliberately not clamped: `fractionDigits` sets the PRECISION of a reading, so
+ * quietly turning `-1` into `0` would drop decimals from a displayed value
+ * without telling anyone. It is a configuration mistake, fixable only in code —
+ * the same class as a bad `valueType`, and treated the same way.
+ *
+ * Values `toFixed` itself tolerates are left alone: `NaN` reads as `0`, and a
+ * fractional count truncates (`2.7` → `2`).
+ */
+export function assertReadoutFractionDigits(
+  tagName: string,
+  fractionDigits: number | null | undefined
+): void {
+  const digits = effectiveFractionDigits(fractionDigits);
+  if (Number.isFinite(digits) && digits >= 0 && digits <= READOUT_MAX_DIGITS) {
+    return;
+  }
+  throw new RangeError(
+    // `String`, not `JSON.stringify`: the latter serialises `Infinity` and
+    // `NaN` to `null`, hiding the very value being rejected.
+    `<${tagName}>: fractionDigits must be between 0 and ${READOUT_MAX_DIGITS} ` +
+      `(got ${String(fractionDigits)}).`
+  );
+}
+
+/**
+ * A digit count used for WIDTH RESERVATION, normalised to a non-negative integer
+ * no greater than {@link READOUT_MAX_DIGITS}.
+ *
+ * Deliberately named for the role rather than for `maxDigits`: both `maxDigits`
+ * and the fraction count `obc-readout-list` reserves with are the same kind of
+ * input — a count handed to `String.prototype.repeat` — and must be bounded the
+ * same way. `fractionDigits` as a FORMAT input is a different contract and is
+ * rejected instead; see {@link assertReadoutFractionDigits}.
+ *
+ * Clamped rather than rejected because it only reserves width, so bounding it
+ * changes no reading's meaning, and the surrounding code already absorbs bad
+ * values silently (`Math.max(count, 1)`, `NaN` repeating to `''`). What is not
+ * absorbed is `Infinity`, which throws out of `String.prototype.repeat`, and a
+ * large finite count, which builds a reserver string long enough to matter —
+ * both are capped here.
+ */
+export function resolveReadoutDigitCount(
+  count: number | null | undefined
+): number {
+  const digits = Math.trunc(count ?? 0);
+  if (Number.isNaN(digits) || digits <= 0) {
+    // Matches what the existing guards already do with these: reserve nothing.
+    return 0;
+  }
+  // `Infinity` lands on the cap — "as wide as possible" — rather than throwing.
+  return Math.min(digits, READOUT_MAX_DIGITS);
+}
+
+/**
+ * Whether a digit-count knob failed to arrive as a number: `null`, `undefined`
+ * or `NaN`.
+ *
+ * A missing knob renders the READING unavailable (the dash) rather than
+ * silently formatting with a default the author never chose. `fractionDigits`
+ * is typically written by the consuming system, and a runtime failure there
+ * produces exactly these values — formatting with `0` instead would print a
+ * critical `0.4` as a plausible-looking `0`, which an operator cannot tell
+ * apart from a healthy reading. The dash makes the failure visible.
+ *
+ * This is a third contract besides throw and clamp: a finite out-of-range
+ * `fractionDigits` is a programmer error and throws
+ * ({@link assertReadoutFractionDigits}); a finite out-of-range `maxDigits` is
+ * width-only and clamps ({@link resolveReadoutDigitCount}); a knob that never
+ * arrived is a runtime data condition and dashes the reading, the same class
+ * as a `NaN` value.
+ */
+export function isReadoutDigitCountMissing(
+  count: number | null | undefined
+): boolean {
+  return count === null || count === undefined || Number.isNaN(count);
+}
+
 function isBlank(value: string): boolean {
   return value.trim() === '';
 }
@@ -144,10 +253,18 @@ export const READOUT_UNAVAILABLE_DASH = '\u2012';
 function dashedGenerator({
   showZeroPadding,
   minValueLength,
-  fractionDigits,
+  fractionDigits: rawFractionDigits,
 }: ReadoutNumericFormatOptions): string {
   const visibleDigits = showZeroPadding ? Math.max(minValueLength, 1) : 1;
 
+  // A missing precision shapes the placeholder as zero fraction digits — a
+  // single dash. Without this, `NaN < 1` is false, both `repeat(NaN)` calls
+  // below produce the empty string, and the placeholder degenerates to a
+  // lone `"."`.
+  const fractionDigits = Number.isNaN(rawFractionDigits)
+    ? 0
+    : rawFractionDigits;
+
   if (fractionDigits < 1) {
     return READOUT_UNAVAILABLE_DASH.repeat(visibleDigits);
   }
@@ -169,7 +286,16 @@ export function formatNumericValue(
   // `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)) {
+  //
+  // A missing precision (`NaN` fractionDigits) is the same class of failure
+  // from the other operand: `value.toFixed(NaN)` silently formats with zero
+  // decimals, printing a critical `0.4` as a plausible-looking `0`. The
+  // reading is untrustworthy without its precision, so it dashes too.
+  if (
+    value === undefined ||
+    !Number.isFinite(value) ||
+    Number.isNaN(options.fractionDigits)
+  ) {
     return dashedGenerator(options);
   }
 

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

@@ -27,6 +27,9 @@ import {
 import {Priority} from '../types.js';
 import {
   assertReadoutValueType,
+  assertReadoutFractionDigits,
+  isReadoutDigitCountMissing,
+  resolveReadoutDigitCount,
   resolveReadoutNumericValue,
   ReadoutValueType,
   type ReadoutNumericFormatOptions,
@@ -288,13 +291,22 @@ export class ObcReadout extends LitElement {
   @property({type: Boolean}) hasDegreeSpacer = false;
   /**
    * Also formats the numeric setpoint / advice blocks, which stay numeric
-   * even when the value is text.
+   * even when the value is text. Must be between 0 and 100 — the range
+   * `Number.prototype.toFixed` accepts; outside it throws a `RangeError`.
+   * A fractional count truncates (`2.7` → `2`). A count that never arrived
+   * (`NaN`, `null` or unset) renders the reading as the unavailable dash —
+   * formatting with a precision the author never chose would let a critical
+   * `0.4` pass for a healthy `0`.
    * @availableWhen valueType==number || hasSetpoint==true || hasAdvice==true
    */
   @property({type: Number}) fractionDigits = 0;
   /**
    * Also formats the numeric setpoint / advice blocks, which stay numeric
-   * even when the value is text.
+   * even when the value is text. Bounded before use: a fractional count
+   * truncates (`2.7` → `2`), anything above 100 — including `Infinity` —
+   * caps at 100, and a negative count reserves nothing. A count that never
+   * arrived (`NaN`, `null` or unset) renders the reading as the unavailable
+   * dash, consistent with `fractionDigits`.
    * @availableWhen valueType==number || hasSetpoint==true || hasAdvice==true
    */
   @property({type: Number}) maxDigits = 0;
@@ -375,7 +387,21 @@ export class ObcReadout extends LitElement {
   }
 
   private get resolvedMaxDigits(): number {
-    return this.maxDigits ?? 0;
+    return resolveReadoutDigitCount(this.maxDigits);
+  }
+
+  /**
+   * Whether a digit knob failed to arrive (`NaN` / `null` / `undefined`).
+   * The raw knobs are forwarded to the blocks, which render the reading as
+   * the unavailable dash (see `obc-readout-block.digitCountsMissing`); this
+   * getter only keeps the setpoint comparison in agreement with what is
+   * displayed.
+   */
+  private get digitCountsMissing(): boolean {
+    return (
+      isReadoutDigitCountMissing(this.fractionDigits) ||
+      isReadoutDigitCountMissing(this.maxDigits)
+    );
   }
 
   private get hasSrc(): boolean {
@@ -390,6 +416,12 @@ export class ObcReadout extends LitElement {
     if (!this.hasSetpoint) {
       return false;
     }
+    // A missing digit knob renders every numeric block as the dash; two
+    // dashes must not read as "at the setpoint", so the comparison stays off
+    // entirely while the configuration is untrustworthy.
+    if (this.digitCountsMissing) {
+      return false;
+    }
     // A text value never compares equal to a setpoint, so flip-flop / pop-up
     // stay dormant for `valueType="text"`.
     return isDisplayedAtSetpoint(
@@ -558,8 +590,8 @@ export class ObcReadout extends LitElement {
         .weight=${config.weight}
         .hasDegree=${config.hasDegree ?? false}
         .hasIcon=${config.hasIcon ?? false}
-        .fractionDigits=${this.resolvedFractionDigits}
-        .maxDigits=${this.resolvedMaxDigits}
+        .fractionDigits=${this.fractionDigits}
+        .maxDigits=${this.maxDigits}
         .hintedZeros=${config.hintedZeros}
         .spaceReserver=${config.spaceReserver}
         .off=${config.off ?? false}
@@ -1135,6 +1167,7 @@ export class ObcReadout extends LitElement {
     // `changed`, skip the check, and render the invalid value as a plain dash:
     // exactly the silent failure this assertion exists to prevent.
     assertReadoutValueType('obc-readout', this.value, this.valueType);
+    assertReadoutFractionDigits('obc-readout', this.fractionDigits);
   }
 
   override updated(changed: Map<string, unknown>): void {

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

@@ -4,6 +4,7 @@ import componentStyle from './readout-list.css?inline';
 import {customElement} from '../../decorator.js';
 import '../readout-list-item/readout-list-item.js';
 import {ObcReadoutListItem} from '../readout-list-item/readout-list-item.js';
+import {resolveReadoutDigitCount} from '../readout/readout-formatters.js';
 import {
   resolveReadoutNumericValue,
   ReadoutValueType,
@@ -158,12 +159,19 @@ export class ObcReadoutList extends LitElement {
       // here, so they take part as usual.
       const hasNumericBlock =
         !isTextValueRow(item) || item.hasSetpoint || item.hasAdvice;
+      // Bounded per row: the list builds its own reserver string from these
+      // counts, so an `Infinity` or absurdly large value on any single row
+      // would otherwise throw out of `String.prototype.repeat` below — inside a
+      // MutationObserver callback, where the stack says nothing useful.
       if (hasNumericBlock) {
         maxFractionDigits = Math.max(
           maxFractionDigits,
-          item.fractionDigits ?? 0
+          resolveReadoutDigitCount(item.fractionDigits)
+        );
+        maxIntegerDigits = Math.max(
+          maxIntegerDigits,
+          resolveReadoutDigitCount(item.maxDigits)
         );
-        maxIntegerDigits = Math.max(maxIntegerDigits, item.maxDigits ?? 0);
       }
       maxIntegerDigits = Math.max(
         maxIntegerDigits,

package/src/navigation-instruments/readout-list-item/readout-list-item.ts

@@ -17,6 +17,9 @@ import {
 } from '../../building-blocks/readout-block/readout-block.js';
 import {
   assertReadoutValueType,
+  assertReadoutFractionDigits,
+  isReadoutDigitCountMissing,
+  resolveReadoutDigitCount,
   resolveReadoutNumericValue,
   ReadoutValueType,
   type ReadoutNumericFormatOptions,
@@ -289,13 +292,22 @@ export class ObcReadoutListItem extends LitElement {
   @property({type: Boolean}) hasDegreeSpacer = false;
   /**
    * Also formats the numeric setpoint / advice blocks, which stay numeric
-   * even when the value is text.
+   * even when the value is text. Must be between 0 and 100 — the range
+   * `Number.prototype.toFixed` accepts; outside it throws a `RangeError`.
+   * A fractional count truncates (`2.7` → `2`). A count that never arrived
+   * (`NaN`, `null` or unset) renders the reading as the unavailable dash —
+   * formatting with a precision the author never chose would let a critical
+   * `0.4` pass for a healthy `0`.
    * @availableWhen valueType==number || hasSetpoint==true || hasAdvice==true
    */
   @property({type: Number}) fractionDigits = 0;
   /**
    * Also formats the numeric setpoint / advice blocks, which stay numeric
-   * even when the value is text.
+   * even when the value is text. Bounded before use: a fractional count
+   * truncates (`2.7` → `2`), anything above 100 — including `Infinity` —
+   * caps at 100, and a negative count reserves nothing. A count that never
+   * arrived (`NaN`, `null` or unset) renders the reading as the unavailable
+   * dash, consistent with `fractionDigits`.
    * @availableWhen valueType==number || hasSetpoint==true || hasAdvice==true
    */
   @property({type: Number}) maxDigits = 0;
@@ -343,7 +355,21 @@ export class ObcReadoutListItem extends LitElement {
   }
 
   private get resolvedMaxDigits(): number {
-    return this.maxDigits ?? 0;
+    return resolveReadoutDigitCount(this.maxDigits);
+  }
+
+  /**
+   * Whether a digit knob failed to arrive (`NaN` / `null` / `undefined`).
+   * The raw knobs are forwarded to the blocks, which render the reading as
+   * the unavailable dash (see `obc-readout-block.digitCountsMissing`); this
+   * getter only keeps the setpoint comparison in agreement with what is
+   * displayed.
+   */
+  private get digitCountsMissing(): boolean {
+    return (
+      isReadoutDigitCountMissing(this.fractionDigits) ||
+      isReadoutDigitCountMissing(this.maxDigits)
+    );
   }
 
   private get resolvedClickable(): false | Required<ReadoutListItemClickable> {
@@ -361,6 +387,12 @@ export class ObcReadoutListItem extends LitElement {
     if (!this.hasSetpoint) {
       return false;
     }
+    // A missing digit knob renders every numeric block as the dash; two
+    // dashes must not read as "at the setpoint", so the comparison stays off
+    // entirely while the configuration is untrustworthy.
+    if (this.digitCountsMissing) {
+      return false;
+    }
     // A text value never compares equal to a setpoint, so flip-flop / pop-up
     // stay dormant for `valueType="text"`.
     return isDisplayedAtSetpoint(
@@ -516,8 +548,8 @@ export class ObcReadoutListItem extends LitElement {
         .weight=${config.weight}
         .hasDegree=${config.hasDegree ?? false}
         .hasIcon=${config.hasIcon ?? false}
-        .fractionDigits=${this.resolvedFractionDigits}
-        .maxDigits=${this.resolvedMaxDigits}
+        .fractionDigits=${this.fractionDigits}
+        .maxDigits=${this.maxDigits}
         .hintedZeros=${config.hintedZeros}
         .spaceReserver=${config.spaceReserver}
         .off=${config.off ?? false}
@@ -869,6 +901,7 @@ export class ObcReadoutListItem extends LitElement {
     // `changed`, skip the check, and render the invalid value as a plain dash:
     // exactly the silent failure this assertion exists to prevent.
     assertReadoutValueType('obc-readout-list-item', this.value, this.valueType);
+    assertReadoutFractionDigits('obc-readout-list-item', this.fractionDigits);
   }
 
   override updated(changed: Map<string, unknown>): void {