@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.112 → 2.0.0-next.113

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

@@ -1,11 +1,13 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import {html, nothing} from 'lit';
+import {expect} from 'storybook/test';
 import {
   ReadoutBlockVariant,
   ReadoutBlockSize,
   ReadoutBlockDataQuality,
   ObcTextboxFontWeight,
   ObcTextboxAlignment,
+  ReadoutValueType,
 } from './readout-block.js';
 import './readout-block.js';
 import '../../icons/icon-placeholder.js';
@@ -19,7 +21,8 @@ const NONE = 'none';
 
 type BlockArgs = {
   variant: ReadoutBlockVariant;
-  value: number;
+  value: number | string | null;
+  valueType: ReadoutValueType;
   size: ReadoutBlockSize;
   enhanced: boolean;
   weight: ObcTextboxFontWeight;
@@ -43,6 +46,7 @@ function renderBlock(args: Partial<BlockArgs>) {
     <obc-readout-block
       .variant=${args.variant ?? ReadoutBlockVariant.value}
       .value=${args.value ?? null}
+      .valueType=${args.valueType ?? ReadoutValueType.number}
       .size=${args.size ?? ReadoutBlockSize.small}
       .enhanced=${args.enhanced ?? false}
       .weight=${args.weight ?? ObcTextboxFontWeight.regular}
@@ -128,6 +132,7 @@ const meta = {
   args: {
     variant: ReadoutBlockVariant.value,
     value: 123,
+    valueType: ReadoutValueType.number,
     size: ReadoutBlockSize.small,
     enhanced: false,
     weight: ObcTextboxFontWeight.regular,
@@ -143,7 +148,14 @@ const meta = {
     dataQuality: NONE,
   },
   argTypes: {
-    value: {control: {type: 'number'}},
+    // Text control (not number) so both value types are exercisable. Under
+    // valueType=number a numeric string resolves back to a number; entering
+    // non-numeric text there throws, which is the intended contract.
+    value: {control: {type: 'text'}},
+    valueType: {
+      control: {type: 'inline-radio'},
+      options: Object.values(ReadoutValueType),
+    },
     variant: {
       control: {type: 'select'},
       options: Object.values(ReadoutBlockVariant),
@@ -243,6 +255,66 @@ export const OffText: Story = {
     ]),
 };
 
+/**
+ * `valueType="text"` renders `value` verbatim instead of formatting it as a
+ * number — for readings that are states rather than quantities.
+ *
+ * The numeric format options (`fractionDigits`, `maxDigits`, `hintedZeros`) are
+ * ignored in this mode; an explicit `spaceReserver` still applies. Passing text
+ * while `valueType` is `number` throws a `TypeError` rather than rendering
+ * `NaN`, while a numeric-looking string such as `"12.4"` is accepted and parsed
+ * so plain-HTML `value="12.4"` keeps working.
+ */
+export const TextValue: Story = {
+  render: () =>
+    renderShowcase([
+      {
+        title: 'text',
+        args: {value: 'Auto', valueType: ReadoutValueType.text},
+      },
+      {
+        title: 'longer text',
+        args: {value: 'Thermo On', valueType: ReadoutValueType.text},
+      },
+      {
+        title: 'verbatim "1.50"',
+        args: {
+          value: '1.50',
+          valueType: ReadoutValueType.text,
+          fractionDigits: 1,
+        },
+      },
+      {
+        title: 'maxDigits ignored',
+        args: {value: 'Auto', valueType: ReadoutValueType.text, maxDigits: 4},
+      },
+      {
+        title: 'spaceReserver honoured',
+        args: {
+          value: 'Auto',
+          valueType: ReadoutValueType.text,
+          spaceReserver: 'Thermo On',
+        },
+      },
+      {
+        title: 'null → dash',
+        args: {value: null, valueType: ReadoutValueType.text},
+      },
+      {
+        title: 'numeric string in number mode',
+        args: {value: '12.4', fractionDigits: 1},
+      },
+      {
+        title: 'text + degree',
+        args: {
+          value: 'Auto',
+          valueType: ReadoutValueType.text,
+          hasDegree: true,
+        },
+      },
+    ]),
+};
+
 /**
  * Hinted zeros pad the integer part up to `maxDigits` as muted leading zeros.
  * When enabled they take priority over `spaceReserver` (they already fill to
@@ -306,6 +378,43 @@ export const Alignment: Story = {
     ),
 };
 
+/**
+ * Regression test for a validation hole, not a visual case.
+ *
+ * When `willUpdate` throws, Lit's `performUpdate` catch calls `__markUpdated()`,
+ * which clears the changed-properties map. Validation used to be gated on
+ * `changed.has('value') || changed.has('valueType')`, so the NEXT update —
+ * driven by any other property, e.g. `obc-readout-list.align()` writing the
+ * shared reservers — saw an empty map, skipped the check, and rendered the
+ * invalid value as a plain dash. Loud once, then silent forever.
+ *
+ * An EMPTY changed map is exactly what Lit leaves behind after a throw, so
+ * `willUpdate` is invoked directly with one. The element is deliberately left
+ * detached: an unconnected `LitElement` never starts its update cycle, so this
+ * exercises the guard without the real throw escaping the scheduler as an
+ * unhandled rejection.
+ */
+export const TestValidationSurvivesUnrelatedUpdate: Story = {
+  render: () => html`<span>Regression test — see the play function.</span>`,
+  play: async () => {
+    type Probe = HTMLElement & {
+      value: number | string | null;
+      willUpdate: (changed: Map<string, unknown>) => void;
+    };
+    const el = document.createElement('obc-readout-block') as Probe;
+    const validateWithNoChanges = () => el.willUpdate(new Map());
+
+    el.value = 'Auto';
+    await expect(validateWithNoChanges).toThrow(/value must be a number/);
+
+    el.value = 12.4;
+    await expect(validateWithNoChanges).not.toThrow();
+
+    el.value = null;
+    await expect(validateWithNoChanges).not.toThrow();
+  },
+};
+
 export const DataQuality: Story = {
   render: () =>
     renderShowcase([
@@ -318,7 +427,7 @@ export const DataQuality: Story = {
         title: 'invalid',
         args: {value: 123, dataQuality: ReadoutBlockDataQuality.invalid},
       },
-      {title: 'null (dash)', args: {value: undefined}},
+      {title: 'null (dash)', args: {value: null}},
     ]),
 };
 

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

@@ -14,6 +14,10 @@ import '../../icons/icon-notification-advice.js';
 import {
   formatNumericValue,
   readoutFormattedInteger,
+  assertReadoutValueType,
+  resolveReadoutNumericValue,
+  resolveReadoutTextValue,
+  ReadoutValueType,
   type ReadoutNumericFormatOptions,
 } from '../../navigation-instruments/readout/readout-formatters.js';
 import {
@@ -27,6 +31,7 @@ export {
   ObcTextboxFontWeight,
   ObcTextboxAlignment,
 } from '../../components/textbox/textbox.js';
+export {ReadoutValueType} from '../../navigation-instruments/readout/readout-formatters.js';
 
 /**
  * Semantic variant of the block. Drives the default marker icon and the
@@ -83,6 +88,9 @@ export enum ReadoutBlockHidePhase {
  * role default), an optional trailing degree glyph, an `off`/unavailable text
  * state, per-block data-quality and an optional per-block alert frame.
  *
+ * Setting `valueType` to `text` renders `value` verbatim (e.g.
+ * `"Auto"`) instead of a formatted number.
+ *
  * This is a building block used inside `obc-readout-list-item` (and, in a future
  * refactor, inside `obc-readout`); it is not normally used on its own. Colour is
  * inherited from the host context (the parent sets the role colour), so the
@@ -105,8 +113,19 @@ export class ObcReadoutBlock extends LitElement {
   @property({type: String}) variant: ReadoutBlockVariant =
     ReadoutBlockVariant.value;
 
-  /** The numeric value; `null`/`undefined` renders a dash. */
-  @property({type: Number}) value: number | null = null;
+  /**
+   * The value; `null`/`undefined` renders a dash. A number by default, or text
+   * when {@link valueType} is `text`.
+   */
+  @property({type: String}) value: number | string | null = null;
+
+  /**
+   * How {@link value} is interpreted. `number` (default) formats it via
+   * `fractionDigits`; `text` renders it verbatim and ignores the numeric
+   * format options. Passing text while this is `number` throws.
+   */
+  @property({type: String}) valueType: ReadoutValueType =
+    ReadoutValueType.number;
 
   /** Density tier — icon size, gap, degree tier. */
   @property({type: String}) size: ReadoutBlockSize = ReadoutBlockSize.small;
@@ -131,13 +150,22 @@ export class ObcReadoutBlock extends LitElement {
   /** Show the leading marker-icon container (always on for setpoint/advice). */
   @property({type: Boolean}) hasIcon = false;
 
-  /** Number of fraction digits. */
+  /**
+   * Number of fraction digits.
+   * @availableWhen valueType==number
+   */
   @property({type: Number}) fractionDigits = 0;
 
-  /** Integer digits to reserve / hint (independent of `fractionDigits`). */
+  /**
+   * Integer digits to reserve / hint (independent of `fractionDigits`).
+   * @availableWhen valueType==number
+   */
   @property({type: Number}) maxDigits = 0;
 
-  /** Render muted leading zeros filling the integer part to `maxDigits`. */
+  /**
+   * Render muted leading zeros filling the integer part to `maxDigits`.
+   * @availableWhen valueType==number
+   */
   @property({type: Boolean}) hintedZeros = false;
 
   /** Explicit longest string to reserve width for (e.g. `"0000.0"`). */
@@ -280,19 +308,41 @@ export class ObcReadoutBlock extends LitElement {
     `;
   }
 
+  protected override willUpdate(changed: Map<string, unknown>): void {
+    super.willUpdate(changed);
+    // Validated on EVERY update, deliberately NOT gated on `value`/`valueType`
+    // appearing in `changed`. When this assertion throws, Lit's `performUpdate`
+    // catch calls `__markUpdated()`, which clears the changed-properties map. A
+    // later update driven by any OTHER property — inside `obc-readout-list`,
+    // `align()` writing the shared reservers — would then see no `value` in
+    // `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);
+  }
+
   override render() {
     const valueSize = this.resolvedValueSize;
     const formatOptions = this.numericFormatOptions;
-    const valueForFormat = this.value ?? undefined;
+    const isTextMode = this.valueType === ReadoutValueType.text;
+    const valueForFormat = 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.
     const text = this.off
       ? this.offText
-      : formatNumericValue(valueForFormat, formatOptions);
+      : isTextMode
+        ? (textValue ?? '-')
+        : formatNumericValue(valueForFormat, formatOptions);
     // Hinted zeros pad the INTEGER part up to `maxDigits`, independent of
     // `fractionDigits` (the decimal point and fraction digits never count toward
     // `maxDigits`). Negative / dashed values are not padded. Example: value 1.2,
     // maxDigits 3, fractionDigits 1 → "001.2".
     const hintCount =
       this.off ||
+      isTextMode ||
       !this.hintedZeros ||
       valueForFormat === undefined ||
       valueForFormat < 0
@@ -303,9 +353,13 @@ export class ObcReadoutBlock extends LitElement {
     // `hintedZeros` is enabled an explicit `spaceReserver` is ignored (it has
     // higher priority). Otherwise the wider of the explicit reserver and the
     // `maxDigits`-derived reserve wins.
-    const reserver = this.hintedZeros
-      ? this.reserverText
-      : this.widerReserver(this.spaceReserver, this.reserverText);
+    // Text mode ignores the `maxDigits`-derived numeric reserve — only an
+    // explicit `spaceReserver` still applies.
+    const reserver = isTextMode
+      ? (this.spaceReserver ?? '')
+      : this.hintedZeros
+        ? this.reserverText
+        : this.widerReserver(this.spaceReserver, this.reserverText);
 
     const block = html`
       <div

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

@@ -0,0 +1,229 @@
+import {describe, it, expect} from 'vitest';
+import {
+  assertReadoutValueType,
+  resolveReadoutNumericValue,
+  resolveReadoutTextValue,
+  isReadoutValueType,
+  ReadoutValueType,
+} from './readout-formatters.js';
+
+describe('assertReadoutValueType', () => {
+  it('accepts a number when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', 12.4, ReadoutValueType.number)
+    ).not.toThrow();
+  });
+
+  it('accepts null when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', null, ReadoutValueType.number)
+    ).not.toThrow();
+  });
+
+  // HTML attributes are always strings, so `<obc-readout value="12.4">` must
+  // keep working under the default valueType.
+  it('accepts a numeric-looking string when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', '12.4', ReadoutValueType.number)
+    ).not.toThrow();
+  });
+
+  it('accepts a negative numeric string when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', '-12.4', ReadoutValueType.number)
+    ).not.toThrow();
+  });
+
+  // `value="${maybeUndefined}"` is a common template shape, and Number('') is
+  // 0 — a silently wrong reading, which is worse than a dash.
+  it('accepts a blank string when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', '', ReadoutValueType.number)
+    ).not.toThrow();
+    expect(() =>
+      assertReadoutValueType('obc-readout', '   ', ReadoutValueType.number)
+    ).not.toThrow();
+  });
+
+  it('throws for text when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', 'Auto', ReadoutValueType.number)
+    ).toThrow(TypeError);
+  });
+
+  it('names the offending tag and value in the message', () => {
+    expect(() =>
+      assertReadoutValueType(
+        'obc-readout-list-item',
+        'Thermo On',
+        ReadoutValueType.number
+      )
+    ).toThrow(/obc-readout-list-item.*Thermo On.*valueType="text"/s);
+  });
+
+  it('throws for a partially numeric string when valueType is number', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', '12.4 kn', ReadoutValueType.number)
+    ).toThrow(TypeError);
+  });
+
+  it('never throws when valueType is text', () => {
+    expect(() =>
+      assertReadoutValueType('obc-readout', 'Auto', ReadoutValueType.text)
+    ).not.toThrow();
+    expect(() =>
+      assertReadoutValueType('obc-readout', 12.4, ReadoutValueType.text)
+    ).not.toThrow();
+  });
+
+  // An attribute carries an unchecked string, so a typo matches neither mode.
+  // Without this it falls through every check and silently renders a dash.
+  it('throws for an unrecognised valueType', () => {
+    expect(() =>
+      assertReadoutValueType(
+        'obc-readout',
+        'Auto',
+        'strng' as unknown as ReadoutValueType
+      )
+    ).toThrow(/valueType must be "number" or "text".*"strng"/s);
+  });
+
+  it('throws for an unrecognised valueType even with a numeric value', () => {
+    expect(() =>
+      assertReadoutValueType(
+        'obc-readout',
+        12.4,
+        'STRING' as unknown as ReadoutValueType
+      )
+    ).toThrow(TypeError);
+  });
+
+  // undefined/null mean "use the default", so they must still enforce the
+  // number contract rather than skipping validation entirely.
+  it('treats an unset valueType as number', () => {
+    expect(() =>
+      assertReadoutValueType(
+        'obc-readout',
+        'Auto',
+        undefined as unknown as ReadoutValueType
+      )
+    ).toThrow(TypeError);
+    expect(() =>
+      assertReadoutValueType(
+        'obc-readout',
+        12.4,
+        undefined as unknown as ReadoutValueType
+      )
+    ).not.toThrow();
+  });
+});
+
+describe('isReadoutValueType', () => {
+  it('accepts the supported values', () => {
+    expect(isReadoutValueType('number')).toBe(true);
+    expect(isReadoutValueType('text')).toBe(true);
+  });
+
+  it('rejects anything else', () => {
+    // `string` names the JS type rather than the mode, and is the likely
+    // mistake for anyone reaching for the TypeScript word.
+    expect(isReadoutValueType('string')).toBe(false);
+    expect(isReadoutValueType('strng')).toBe(false);
+    expect(isReadoutValueType('Number')).toBe(false);
+    expect(isReadoutValueType('')).toBe(false);
+    expect(isReadoutValueType(undefined)).toBe(false);
+    expect(isReadoutValueType(null)).toBe(false);
+    expect(isReadoutValueType(0)).toBe(false);
+  });
+});
+
+describe('resolveReadoutNumericValue', () => {
+  it('passes a number through unchanged', () => {
+    expect(resolveReadoutNumericValue(12.4, ReadoutValueType.number)).toBe(
+      12.4
+    );
+  });
+
+  it('parses a numeric string', () => {
+    expect(resolveReadoutNumericValue('12.4', ReadoutValueType.number)).toBe(
+      12.4
+    );
+  });
+
+  it('is undefined for null, undefined and blank strings', () => {
+    expect(
+      resolveReadoutNumericValue(null, ReadoutValueType.number)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue(undefined, ReadoutValueType.number)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue('', ReadoutValueType.number)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue('  ', ReadoutValueType.number)
+    ).toBeUndefined();
+  });
+
+  it('is undefined for non-numeric text', () => {
+    expect(
+      resolveReadoutNumericValue('Auto', ReadoutValueType.number)
+    ).toBeUndefined();
+  });
+
+  // Text rows must contribute nothing to obc-readout-list's shared reserver.
+  it('is undefined in text mode even for a numeric value', () => {
+    expect(
+      resolveReadoutNumericValue(12.4, ReadoutValueType.text)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutNumericValue('12.4', ReadoutValueType.text)
+    ).toBeUndefined();
+  });
+
+  // Pre-existing behaviour, deliberately preserved: NaN reaches the formatter.
+  it('passes NaN through in number mode', () => {
+    expect(
+      resolveReadoutNumericValue(Number.NaN, ReadoutValueType.number)
+    ).toBeNaN();
+  });
+});
+
+describe('resolveReadoutTextValue', () => {
+  it('returns the text verbatim in text mode', () => {
+    expect(resolveReadoutTextValue('Thermo On', ReadoutValueType.text)).toBe(
+      'Thermo On'
+    );
+  });
+
+  // The reason a converter was rejected: it would have parsed this to 1.5.
+  it('preserves trailing zeros in text mode', () => {
+    expect(resolveReadoutTextValue('1.50', ReadoutValueType.text)).toBe('1.50');
+  });
+
+  it('coerces a number to text in text mode', () => {
+    expect(resolveReadoutTextValue(12.4, ReadoutValueType.text)).toBe('12.4');
+  });
+
+  it('is undefined for null, undefined and blank strings', () => {
+    expect(
+      resolveReadoutTextValue(null, ReadoutValueType.text)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutTextValue(undefined, ReadoutValueType.text)
+    ).toBeUndefined();
+    expect(resolveReadoutTextValue('', ReadoutValueType.text)).toBeUndefined();
+    expect(
+      resolveReadoutTextValue('   ', ReadoutValueType.text)
+    ).toBeUndefined();
+  });
+
+  it('is undefined in number mode', () => {
+    expect(
+      resolveReadoutTextValue('12.4', ReadoutValueType.number)
+    ).toBeUndefined();
+    expect(
+      resolveReadoutTextValue(12.4, ReadoutValueType.number)
+    ).toBeUndefined();
+  });
+});

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

@@ -4,6 +4,111 @@ export type ReadoutNumericFormatOptions = {
   fractionDigits: number;
 };
 
+/**
+ * How a readout's `value` is interpreted.
+ * - `number`: formatted via `fractionDigits` / `maxDigits`.
+ * - `text`: rendered verbatim, with the numeric format options ignored.
+ */
+export enum ReadoutValueType {
+  number = 'number',
+  text = 'text',
+}
+
+const READOUT_VALUE_TYPES: readonly string[] = Object.values(ReadoutValueType);
+
+/** Whether `value` is one of the supported {@link ReadoutValueType} values. */
+export function isReadoutValueType(value: unknown): value is ReadoutValueType {
+  return typeof value === 'string' && READOUT_VALUE_TYPES.includes(value);
+}
+
+function isBlank(value: string): boolean {
+  return value.trim() === '';
+}
+
+/**
+ * Throws when `valueType` is not a supported value, or when `value` is text but
+ * `valueType` is `number`.
+ *
+ * `valueType` is validated first because an attribute carries an unchecked
+ * string: a typo such as `valuetype="strng"` matches neither mode, so every
+ * mode check falls through and the readout silently renders the unavailable
+ * dash — the opposite of the loud failure this contract exists to give.
+ * `undefined`/`null` are allowed and mean "use the default".
+ *
+ * Attributes are always strings, so a numeric-looking string (`value="10.12"`)
+ * is accepted and parsed. Blank strings resolve to the unavailable dash rather
+ * than throwing — `value="${maybeUndefined}"` is a common template shape, and
+ * `Number('')` is `0`, a silently wrong reading.
+ */
+export function assertReadoutValueType(
+  tagName: string,
+  value: number | string | null | undefined,
+  valueType: ReadoutValueType
+): void {
+  // `undefined`/`null` mean "use the default", matching how the components and
+  // the resolvers treat an unset `valueType`.
+  const resolved = valueType ?? ReadoutValueType.number;
+  if (!isReadoutValueType(resolved)) {
+    throw new TypeError(
+      `<${tagName}>: valueType must be ` +
+        `${READOUT_VALUE_TYPES.map((t) => `"${t}"`).join(' or ')} ` +
+        `(got ${JSON.stringify(valueType)}).`
+    );
+  }
+  if (
+    resolved !== ReadoutValueType.number ||
+    typeof value !== 'string' ||
+    isBlank(value)
+  ) {
+    return;
+  }
+  if (Number.isFinite(Number(value))) {
+    return;
+  }
+  throw new TypeError(
+    `<${tagName}>: value must be a number when valueType is "number" ` +
+      `(got ${JSON.stringify(value)}). Set valueType="text" to render text.`
+  );
+}
+
+/** The value as a number, or `undefined` when it is text / unavailable. */
+export function resolveReadoutNumericValue(
+  value: number | string | null | undefined,
+  valueType: ReadoutValueType
+): number | undefined {
+  if (
+    valueType === ReadoutValueType.text ||
+    value === null ||
+    value === undefined
+  ) {
+    return undefined;
+  }
+  if (typeof value === 'number') {
+    return value;
+  }
+  if (isBlank(value)) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/** The value as display text, or `undefined` when not in text mode / blank. */
+export function resolveReadoutTextValue(
+  value: number | string | null | undefined,
+  valueType: ReadoutValueType
+): string | undefined {
+  if (
+    valueType !== ReadoutValueType.text ||
+    value === null ||
+    value === undefined
+  ) {
+    return undefined;
+  }
+  const text = typeof value === 'number' ? String(value) : value;
+  return isBlank(text) ? undefined : text;
+}
+
 function dashedGenerator({
   showZeroPadding,
   minValueLength,