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

package/src/automation/automation-tank/automation-tank.ts

@@ -82,6 +82,22 @@ export enum TankOrientation {
  *   slot — the parent controls the footprint and the tank renders
  *   responsively inside it, just like a regular button. Compact / static
  *   inner layout still applies; only the host box is changed.
+ *
+ *   If the parent leaves *one* axis indefinite — a flex/grid slot sized with
+ *   `min-height`/`max-height` rather than `height`, or a cross axis freed by
+ *   `align-self: center` — the corresponding `100%` computes to `auto` and the
+ *   tank derives that axis from the other one through the design aspect ratio
+ *   of the matching `point` footprint (256×376 vertical, 420×256 horizontal,
+ *   170×282 compact/static, 244×208 horizontal compact/static). The size then
+ *   does not depend on the chart cell, which takes its own size from the cell
+ *   it was measured in and would otherwise make the constraint circular
+ *   (issue #1121).
+ *
+ *   If *both* axes are indefinite (a shrink-to-fit parent, e.g. an unsized
+ *   `inline-block`) there is no axis left to derive from, so the host falls
+ *   back to its text content. That is stable and non-circular, but much
+ *   smaller than the design footprint — give the parent a definite size on at
+ *   least one axis, and on both whenever the exact footprint matters.
  */
 export enum TankPositioning {
   point = 'point',
@@ -122,7 +138,7 @@ export enum TankChartMode {
  * @slot alert-icon - Custom icon for the alert frame.
  * @slot alert-label - Label for the alert frame.
  * @slot alert-timer - Timer for the alert frame.
- * @fires click - Fired when the tank is clicked. In `static` mode the tank renders a `<div role="img">` instead of a `<button>`, so it is not focusable or keyboard-activatable; pointer clicks still reach the host.
+ * @fires click - Fired when the tank is clicked. When `clickable` is `false` the tank renders a plain `<div>`, and in `static` mode a `<div role="img">`, instead of a `<button>` — in both cases it is not focusable or keyboard-activatable; pointer clicks still reach the host.
  * @beta
  */
 @customElement('obc-automation-tank')
@@ -137,9 +153,10 @@ export class ObcAutomationTank extends SetpointMixin(LitElement) {
   @property({type: Boolean, reflect: true}) compact: boolean = false;
   /**
    * Host positioning model — see `TankPositioning` for details. Defaults to
-   * `button` (host fills parent container, 100% × 100%, no anchor offset).
-   * Set to `point` for the legacy P&ID canvas mode (fixed default dimensions
-   * + top-center anchor offset).
+   * `button` (host fills parent container, 100% × 100%, falling back to the
+   * design aspect ratio on any axis the parent leaves indefinite, no anchor
+   * offset). Set to `point` for the legacy P&ID canvas mode (fixed default
+   * dimensions + top-center anchor offset).
    */
   @property({type: String, reflect: true}) positioning: TankPositioning =
     TankPositioning.button;
@@ -156,7 +173,38 @@ export class ObcAutomationTank extends SetpointMixin(LitElement) {
    * activatable controls.
    */
   @property({type: Boolean, reflect: true}) static: boolean = false;
-  /** Enables the activated background color, used to indicate that the tank is activated/selected. */
+  /**
+   * Whether the tank is interactive. `true` (default) renders the root as a
+   * `<button>` with the full flat-mixin interaction surface. `false` renders a
+   * non-interactive `<div>` — the resting appearance is unchanged (same
+   * enabled-state colors and the same 1px border box, via the mixin's
+   * `noClick` variant), but the hover / pressed / focus-visible states are
+   * gone and the tank leaves the tab order.
+   *
+   * Everything else keeps rendering: the chart / bar, badges, readout, tag and
+   * the `alert` frame all behave exactly as they do on a clickable tank. Use
+   * this for a display-only tank that still shows live data — e.g. a row total
+   * aggregating the tanks beside it. For "device present, current state
+   * unknown" use `static` instead, which also hides the chart and shrinks to
+   * the compact footprint.
+   *
+   * `static` is already non-interactive, so this has no effect there.
+   *
+   * Property-only (`attribute: false`, per the repo's positive-default-true
+   * boolean convention — a `true` default cannot round-trip through an HTML
+   * boolean attribute). Set it as a property: `el.clickable = false`,
+   * `.clickable=${false}` in a Lit template, or the equivalent binding in the
+   * React / Vue / Angular / Svelte wrappers. A `clickable="false"` attribute in
+   * plain HTML is **not** observed and leaves the tank interactive.
+   */
+  @property({type: Boolean, attribute: false}) clickable: boolean = true;
+  /**
+   * Enables the activated background color, used to indicate that the tank is
+   * activated/selected. Requires an interactive tank — the `noClick` mixin
+   * variant used when `clickable` is `false` only paints the enabled state, so
+   * a non-clickable tank ignores this (matching `obc-elevated-card`).
+   * @availableWhen clickable==true
+   */
   @property({type: Boolean}) activated: boolean = false;
   @property({type: String}) tag: string = '';
 
@@ -1001,7 +1049,18 @@ export class ObcAutomationTank extends SetpointMixin(LitElement) {
     // The `activated` class goes on the interactive `.root` so the shared
     // `flat` style mixin paints the activated background/border on `.halo`
     // (its `visibleWrapperClass`), same as the mixin's hover/pressed states.
-    const rootClasses = classMap({root: true, activated: this.activated});
+    //
+    // `.clickable` selects between the two flat-mixin variants in CSS: the
+    // full six-state one, or the `noClick` one that paints only the resting
+    // enabled state. `static` is already display-only, so it never counts as
+    // clickable. Same shape as `obc-elevated-card`'s `.not-clickable` split
+    // and `obc-readout-list-item`'s `.root.clickable`.
+    const isClickable = this.clickable && !this.static;
+    const rootClasses = classMap({
+      root: true,
+      activated: this.activated,
+      clickable: isClickable,
+    });
 
     // `aria-live="polite"` + `aria-atomic="true"` on the root so the
     // slotted alert label (and any state change of the alert frame) is
@@ -1010,27 +1069,47 @@ export class ObcAutomationTank extends SetpointMixin(LitElement) {
     // TODO(a11y): the rest of the automation component family still lacks
     // this live-region announcement; consolidate when alert support is
     // factored into a shared mixin.
-    return html`
-      ${this.static
-        ? html`<div
-            class=${rootClasses}
-            role="img"
-            aria-label=${this.tag || 'Tank'}
-            aria-live="polite"
-            aria-atomic="true"
-          >
-            ${halo}
-          </div>`
-        : html`<button
-            class=${rootClasses}
-            type="button"
-            aria-label=${this.tag || 'Tank'}
-            aria-live="polite"
-            aria-atomic="true"
-          >
-            ${halo}
-          </button>`}
-    `;
+    // Three root shapes:
+    //   - static:            <div role="img"> — an opaque graphic standing in
+    //     for a device whose state is unknown, named by its tag.
+    //   - clickable false:  a plain <div>. Deliberately no `role="img"` and no
+    //     `aria-label` here: unlike a static tank this one still shows live
+    //     data, and both would collapse the readout into a single opaque name
+    //     and hide the percent / value / tag from screen readers. The visible
+    //     content is the accessible content. (Same reasoning as the non-
+    //     clickable branch of `obc-readout-list-item`.)
+    //   - default:           <button>.
+    // The live region stays on all three so an `alert` label is announced
+    // regardless of interactivity.
+    if (this.static) {
+      return html`<div
+        class=${rootClasses}
+        role="img"
+        aria-label=${this.tag || 'Tank'}
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        ${halo}
+      </div>`;
+    }
+    if (!isClickable) {
+      return html`<div
+        class=${rootClasses}
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        ${halo}
+      </div>`;
+    }
+    return html`<button
+      class=${rootClasses}
+      type="button"
+      aria-label=${this.tag || 'Tank'}
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      ${halo}
+    </button>`;
   }
 
   static override styles = unsafeCSS(compentStyle);

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

@@ -481,6 +481,19 @@ const UNAVAILABLE_CASES: {
     label: 'null · no fraction digits',
     args: {value: null, maxDigits: 3},
   },
+  // The knobs, not the value: a `fractionDigits` written by a failed runtime
+  // (`NaN`) must not silently format with zero decimals — a critical 0.4
+  // printed as a plausible-looking "0" reads as healthy. The reading dashes
+  // instead. A missing `maxDigits` dashes too, for consistency; with the
+  // precision still known, the placeholder keeps its fraction shape.
+  {
+    label: 'value 0.4 · fractionDigits NaN — precision failed to arrive',
+    args: {value: 0.4, maxDigits: 3, fractionDigits: Number.NaN},
+  },
+  {
+    label: 'value 0.4 · maxDigits NaN — same, for consistency',
+    args: {value: 0.4, maxDigits: Number.NaN, fractionDigits: 1},
+  },
 ];
 
 // Stacked in one column under identical settings so the decimal points and the
@@ -509,6 +522,13 @@ const ALIGNMENT_CASES: Partial<BlockArgs>[] = [
  *    runtime data condition (sensor dropout, `0/0`, a bad parse) rather than a
  *    programmer error, so they resolve to the dash rather than throwing.
  *
+ * 4. **A digit knob that never arrived dashes the reading too.** `NaN`,
+ *    `null` or `undefined` in `fractionDigits` / `maxDigits` is a runtime
+ *    failure of the writing system, and formatting with a default the author
+ *    never chose would let a critical `0.4` pass for a healthy `0`. Finite
+ *    out-of-range values are different: `fractionDigits` throws (programmer
+ *    error), `maxDigits` clamps (width-only).
+ *
  * Hinted zeros are suppressed for an unavailable value, so the two "not
  * available" rows are identical and nothing reads `----Na.N`.
  *

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

@@ -15,6 +15,9 @@ import {
   formatNumericValue,
   readoutFormattedInteger,
   assertReadoutValueType,
+  assertReadoutFractionDigits,
+  isReadoutDigitCountMissing,
+  resolveReadoutDigitCount,
   resolveReadoutNumericValue,
   resolveReadoutTextValue,
   READOUT_UNAVAILABLE_DASH,
@@ -152,13 +155,23 @@ export class ObcReadoutBlock extends LitElement {
   @property({type: Boolean}) hasIcon = false;
 
   /**
-   * Number of fraction digits.
+   * Number of fraction digits. 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
    */
   @property({type: Number}) fractionDigits = 0;
 
   /**
    * Integer digits to reserve / hint (independent of `fractionDigits`).
+   * 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
    */
   @property({type: Number}) maxDigits = 0;
@@ -214,24 +227,54 @@ export class ObcReadoutBlock extends LitElement {
     }
   }
 
+  /**
+   * `maxDigits` bounded to a usable count. Every width calculation below goes
+   * through this rather than the raw property, so an `Infinity` (or absurdly
+   * large) value cannot reach `String.prototype.repeat`.
+   */
+  private get resolvedMaxDigits(): number {
+    return resolveReadoutDigitCount(this.maxDigits);
+  }
+
+  /**
+   * Whether a digit knob failed to arrive (`NaN` / `null` / `undefined`).
+   * The reading then renders as the unavailable dash rather than silently
+   * formatting with a default the author never chose — a critical `0.4`
+   * formatted with a failed `fractionDigits` would otherwise print as a
+   * plausible-looking `0`. A missing `maxDigits` dashes too, for consistency:
+   * either knob arriving broken means the row's configuration cannot be
+   * trusted.
+   */
+  private get digitCountsMissing(): boolean {
+    return (
+      isReadoutDigitCountMissing(this.fractionDigits) ||
+      isReadoutDigitCountMissing(this.maxDigits)
+    );
+  }
+
   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,
+      minValueLength: this.resolvedMaxDigits,
+      // A missing precision shapes the placeholder as zero fraction digits (a
+      // single dash) — and keeps a runtime `undefined`/`null` out of the
+      // options object, which is typed `number` throughout the formatters.
+      fractionDigits: isReadoutDigitCountMissing(this.fractionDigits)
+        ? 0
+        : this.fractionDigits,
     };
   }
 
   /** Widest possible value string for width reservation (e.g. `"000.0"`). */
   private get reserverText(): string {
-    const maxDigits = this.maxDigits;
+    const maxDigits = this.resolvedMaxDigits;
     if (maxDigits <= 0) {
       return '';
     }
-    const integer = '0'.repeat(Math.max(maxDigits, 1));
+    const integer = '0'.repeat(maxDigits);
     return this.fractionDigits > 0
       ? `${integer}.${'0'.repeat(this.fractionDigits)}`
       : integer;
@@ -322,16 +365,19 @@ export class ObcReadoutBlock 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-block', this.value, this.valueType);
+    assertReadoutFractionDigits('obc-readout-block', this.fractionDigits);
   }
 
   override render() {
     const valueSize = this.resolvedValueSize;
     const formatOptions = this.numericFormatOptions;
     const isTextMode = this.valueType === ReadoutValueType.text;
-    const valueForFormat = resolveReadoutNumericValue(
-      this.value,
-      this.valueType
-    );
+    // A missing digit knob makes the reading untrustworthy, so it resolves to
+    // "no reading" and renders the dash (see `digitCountsMissing`). Text mode
+    // is unaffected — it ignores the numeric knobs entirely.
+    const valueForFormat = this.digitCountsMissing
+      ? undefined
+      : resolveReadoutNumericValue(this.value, this.valueType);
     const textValue = resolveReadoutTextValue(this.value, this.valueType);
     // Text mode renders verbatim and ignores the numeric format options; a
     // blank / missing text value still falls back to the unavailable dash.
@@ -351,7 +397,7 @@ export class ObcReadoutBlock extends LitElement {
       valueForFormat === undefined ||
       valueForFormat < 0
         ? 0
-        : Math.max(this.maxDigits - readoutFormattedInteger(text), 0);
+        : Math.max(this.resolvedMaxDigits - readoutFormattedInteger(text), 0);
     const hinted = hintCount > 0 ? '0'.repeat(hintCount) : '';
     // Hinted zeros own the width — they already fill to `maxDigits` — so when
     // `hintedZeros` is enabled an explicit `spaceReserver` is ignored (it has

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

@@ -1,6 +1,10 @@
 import {describe, it, expect} from 'vitest';
 import {
   assertReadoutValueType,
+  assertReadoutFractionDigits,
+  isReadoutDigitCountMissing,
+  resolveReadoutDigitCount,
+  READOUT_MAX_DIGITS,
   resolveReadoutNumericValue,
   resolveReadoutTextValue,
   formatNumericValue,
@@ -367,3 +371,204 @@ describe("designer's format specification (000.00)", () => {
     );
   });
 });
+
+describe('assertReadoutFractionDigits', () => {
+  // `fractionDigits` reaches `Number.prototype.toFixed` unchanged, which throws
+  // outside 0…100. These are the values that already crash today, now reported
+  // against the component instead of as a bare RangeError.
+  it('throws below 0 and above the maximum', () => {
+    expect(() => assertReadoutFractionDigits('obc-readout', -1)).toThrow(
+      RangeError
+    );
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', READOUT_MAX_DIGITS + 1)
+    ).toThrow(RangeError);
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', Number.POSITIVE_INFINITY)
+    ).toThrow(RangeError);
+  });
+
+  it('names the component and the offending value', () => {
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout-list-item', -1)
+    ).toThrow(/obc-readout-list-item.*between 0 and 100.*-1/s);
+  });
+
+  // `JSON.stringify` serialises these to `null`, which would hide the very
+  // value being rejected.
+  it('reports non-finite values verbatim in the message', () => {
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', Number.POSITIVE_INFINITY)
+    ).toThrow(/got Infinity/);
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', Number.NEGATIVE_INFINITY)
+    ).toThrow(/got -Infinity/);
+  });
+
+  // The components read `fractionDigits ?? 0` and `toFixed(undefined)` behaves
+  // as `toFixed(0)`, so clearing the property must not throw.
+  it('accepts an unset value', () => {
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', undefined as unknown as number)
+    ).not.toThrow();
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', null as unknown as number)
+    ).not.toThrow();
+  });
+
+  it('accepts the whole supported range', () => {
+    expect(() => assertReadoutFractionDigits('obc-readout', 0)).not.toThrow();
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', READOUT_MAX_DIGITS)
+    ).not.toThrow();
+  });
+
+  // Values `toFixed` itself tolerates are left alone rather than rejected.
+  it('tolerates what toFixed tolerates', () => {
+    expect(() => assertReadoutFractionDigits('obc-readout', 2.7)).not.toThrow();
+    expect(() =>
+      assertReadoutFractionDigits('obc-readout', Number.NaN)
+    ).not.toThrow();
+  });
+
+  // The assertion must agree with the runtime it is protecting.
+  it('accepts exactly the values toFixed accepts', () => {
+    // Covers both sides of the boundary, including the truncation cases the
+    // instruction file documents: 100.9 -> 100 and -0.5 -> -0 are accepted,
+    // while -1, 101 and the infinities are not.
+    for (const digits of [
+      0,
+      1,
+      2.7,
+      -0.5,
+      100.9,
+      Number.NaN,
+      undefined,
+      null,
+      READOUT_MAX_DIGITS,
+      -1,
+      READOUT_MAX_DIGITS + 1,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    ] as number[]) {
+      let assertionThrew = false;
+      let toFixedThrew = false;
+      try {
+        assertReadoutFractionDigits('obc-readout', digits);
+      } catch {
+        assertionThrew = true;
+      }
+      try {
+        (12.3).toFixed(digits);
+      } catch {
+        toFixedThrew = true;
+      }
+      expect(assertionThrew).toBe(toFixedThrew);
+    }
+  });
+});
+
+describe('resolveReadoutDigitCount', () => {
+  it('passes a usable count through', () => {
+    expect(resolveReadoutDigitCount(4)).toBe(4);
+    expect(resolveReadoutDigitCount(0)).toBe(0);
+  });
+
+  // `Infinity` is the value that throws out of `String.prototype.repeat`.
+  it('caps Infinity rather than throwing', () => {
+    expect(resolveReadoutDigitCount(Number.POSITIVE_INFINITY)).toBe(
+      READOUT_MAX_DIGITS
+    );
+    expect(() =>
+      '0'.repeat(resolveReadoutDigitCount(Number.POSITIVE_INFINITY))
+    ).not.toThrow();
+  });
+
+  it('caps a large finite count so the reserver stays bounded', () => {
+    expect(resolveReadoutDigitCount(1_000_000)).toBe(READOUT_MAX_DIGITS);
+  });
+
+  // Matches what the existing guards already did with these: reserve nothing.
+  it('is 0 for negative, NaN, null and undefined', () => {
+    expect(resolveReadoutDigitCount(-5)).toBe(0);
+    expect(resolveReadoutDigitCount(Number.NEGATIVE_INFINITY)).toBe(0);
+    expect(resolveReadoutDigitCount(Number.NaN)).toBe(0);
+    expect(resolveReadoutDigitCount(null)).toBe(0);
+    expect(resolveReadoutDigitCount(undefined)).toBe(0);
+  });
+
+  it('truncates a fractional count', () => {
+    expect(resolveReadoutDigitCount(2.7)).toBe(2);
+  });
+
+  // Whatever comes back must be safe to hand to `repeat`.
+  it('always returns a count repeat() accepts', () => {
+    for (const input of [
+      -5,
+      0,
+      2.7,
+      4,
+      1_000_000,
+      Number.NaN,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    ]) {
+      expect(() => '0'.repeat(resolveReadoutDigitCount(input))).not.toThrow();
+    }
+  });
+});
+
+describe('isReadoutDigitCountMissing', () => {
+  // The third contract besides throw and clamp: a knob that never arrived is
+  // a runtime data condition, and the reading renders as the dash rather than
+  // silently formatting with a default the author never chose.
+  it('is true for NaN, null and undefined', () => {
+    expect(isReadoutDigitCountMissing(Number.NaN)).toBe(true);
+    expect(isReadoutDigitCountMissing(null)).toBe(true);
+    expect(isReadoutDigitCountMissing(undefined)).toBe(true);
+  });
+
+  // A number that ARRIVED wrong is a different contract: out-of-range
+  // `fractionDigits` throws (`assertReadoutFractionDigits`), out-of-range
+  // `maxDigits` clamps (`resolveReadoutDigitCount`). Neither is "missing".
+  it('is false for any number that arrived, however wrong', () => {
+    expect(isReadoutDigitCountMissing(0)).toBe(false);
+    expect(isReadoutDigitCountMissing(2)).toBe(false);
+    expect(isReadoutDigitCountMissing(2.7)).toBe(false);
+    expect(isReadoutDigitCountMissing(-1)).toBe(false);
+    expect(isReadoutDigitCountMissing(101)).toBe(false);
+    expect(isReadoutDigitCountMissing(Number.POSITIVE_INFINITY)).toBe(false);
+    expect(isReadoutDigitCountMissing(Number.NEGATIVE_INFINITY)).toBe(false);
+  });
+});
+
+// The review that introduced this: a system writing `fractionDigits` at
+// runtime can fail and produce `NaN` — `toFixed(NaN)` then formats with zero
+// decimals, so a critical `0.4` prints as a plausible-looking `0` and an
+// operator cannot tell the readout is broken. The dash makes it visible.
+describe('formatNumericValue — missing precision', () => {
+  const opts = (fractionDigits: number) => ({
+    showZeroPadding: false,
+    minValueLength: 3,
+    fractionDigits,
+  });
+  const D = READOUT_UNAVAILABLE_DASH;
+
+  it('renders the dash, not a zero-decimal number', () => {
+    expect(formatNumericValue(0.4, opts(Number.NaN))).toBe(D);
+    expect(formatNumericValue(12.3, opts(Number.NaN))).toBe(D);
+  });
+
+  // Regression: `NaN < 1` is false, so the placeholder generator used to fall
+  // into its fraction branch where both `repeat(NaN)` calls produce '', and
+  // an unavailable value with a missing precision degenerated to a lone ".".
+  it('shapes the placeholder as zero fraction digits, not a lone dot', () => {
+    expect(formatNumericValue(undefined, opts(Number.NaN))).toBe(D);
+    expect(formatNumericValue(undefined, opts(Number.NaN))).not.toBe('.');
+  });
+
+  it('still formats normally with a precision that arrived', () => {
+    expect(formatNumericValue(0.4, opts(1))).toBe('0.4');
+    expect(formatNumericValue(12.3, opts(2))).toBe('12.30');
+  });
+});