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

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

@@ -20,6 +20,7 @@ import {
   type ReadoutAdviceOptions,
   type ReadoutReserverOptions,
   type ReadoutSourceOptions,
+  ReadoutValueType,
 } from './readout.js';
 import {
   type AlertFrameConfig,
@@ -36,7 +37,8 @@ type ReadoutStoryArgs = {
   unit: string;
   src: string;
   hasValue: boolean;
-  value: number;
+  value: number | string;
+  valueType: ReadoutValueType;
   off: boolean;
   hasSetpoint: boolean;
   setpoint: number;
@@ -90,7 +92,8 @@ type ReadoutConfig = {
   unit?: string;
   src?: string;
   hasValue?: boolean;
-  value?: number | null;
+  value?: number | string | null;
+  valueType?: ReadoutValueType;
   off?: boolean;
   hasSetpoint?: boolean;
   setpoint?: number;
@@ -159,6 +162,7 @@ function renderReadout(config: ReadoutConfig) {
       .src=${config.src}
       .hasValue=${config.hasValue ?? true}
       .value=${config.value ?? null}
+      .valueType=${config.valueType ?? ReadoutValueType.number}
       .off=${config.off ?? false}
       .hasSetpoint=${config.hasSetpoint ?? false}
       .setpoint=${config.setpoint}
@@ -241,6 +245,7 @@ const defaultArgs: ReadoutStoryArgs = {
   src: '',
   hasValue: true,
   value: 123,
+  valueType: ReadoutValueType.number,
   off: false,
   hasSetpoint: false,
   setpoint: 120,
@@ -306,6 +311,7 @@ const meta = {
       src: args.src,
       hasValue: args.hasValue,
       value: args.value,
+      valueType: args.valueType,
       off: args.off,
       hasSetpoint: args.hasSetpoint,
       setpoint: args.setpoint,
@@ -322,7 +328,16 @@ const meta = {
     hasValue: {name: 'Has Value', table: {category: 'Data'}},
     value: {
       name: '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.
+      control: {type: 'text'},
+      table: {category: 'Data'},
+    },
+    valueType: {
+      name: 'Value Type',
+      control: {type: 'inline-radio'},
+      options: Object.values(ReadoutValueType),
       table: {category: 'Data'},
     },
     off: {name: 'Off', table: {category: 'Data'}},
@@ -1153,6 +1168,141 @@ export const DebugOverlay: StoryObj<
   `,
 };
 
+/**
+ * **Text values** — `valueType="text"` renders `value` verbatim instead of
+ * formatting it as a number, for readings that are states rather than
+ * quantities ("Auto", "Thermo On", "Standby").
+ *
+ * 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` — a numeric-looking string such as `"12.4"` is still accepted and
+ * parsed, so plain-HTML `value="12.4"` keeps working.
+ */
+export const TextValue: Story = {
+  render: () =>
+    renderShowcase([
+      {
+        title: 'Text Value — Vertical',
+        columns: 3,
+        cases: [
+          {
+            label: 'text',
+            config: {
+              label: 'Mode',
+              unit: '',
+              value: 'Auto',
+              valueType: ReadoutValueType.text,
+            },
+          },
+          {
+            label: 'text + source',
+            config: {
+              label: 'Thruster',
+              unit: '',
+              value: 'Standby',
+              valueType: ReadoutValueType.text,
+              src: 'CTRL',
+            },
+          },
+          {
+            label: 'text + stacked meta',
+            config: {
+              label: 'Status',
+              unit: '',
+              value: 'Normal',
+              valueType: ReadoutValueType.text,
+              options: {stacking: ReadoutStacking.stacked},
+            },
+          },
+        ],
+      },
+      {
+        title: 'Text Value — Horizontal',
+        columns: 3,
+        cases: [
+          {
+            label: 'text',
+            config: {
+              label: 'Mode',
+              unit: '',
+              value: 'Auto',
+              valueType: ReadoutValueType.text,
+              options: {direction: ReadoutDirection.horizontal},
+            },
+          },
+          {
+            label: 'text + source',
+            config: {
+              label: 'Thruster',
+              unit: '',
+              value: 'Standby',
+              valueType: ReadoutValueType.text,
+              src: 'CTRL',
+              options: {direction: ReadoutDirection.horizontal},
+            },
+          },
+          {
+            label: 'numeric (contrast)',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: 12.4,
+              options: {
+                direction: ReadoutDirection.horizontal,
+                fractionDigits: 1,
+              },
+            },
+          },
+        ],
+      },
+      {
+        title: 'Value Resolution — Sizes and Edge Cases',
+        columns: 4,
+        cases: [
+          {
+            label: 'verbatim "1.50" (trailing zero kept)',
+            config: {
+              label: 'Bearing',
+              unit: '',
+              value: '1.50',
+              valueType: ReadoutValueType.text,
+              options: {fractionDigits: 1},
+            },
+          },
+          {
+            label: 'null in text mode (dash)',
+            config: {
+              label: 'Mode',
+              unit: '',
+              value: null,
+              valueType: ReadoutValueType.text,
+            },
+          },
+          {
+            label: 'numeric string in number mode → 12.4',
+            config: {
+              label: 'SOG',
+              unit: 'kn',
+              value: '12.4',
+              options: {fractionDigits: 1},
+            },
+          },
+          {
+            label: 'text + degree (hasDegree honoured)',
+            config: {
+              label: 'Mode',
+              unit: '',
+              value: 'Auto',
+              valueType: ReadoutValueType.text,
+              options: {hasDegree: true},
+            },
+          },
+        ],
+      },
+    ]),
+};
+
 export const TestCases: Story = {
   render: () => {
     return html` <style>
@@ -1174,6 +1324,20 @@ export const TestCases: Story = {
           .value=${123}
           .unit=${'kn'}
         ></obc-readout>
+        <obc-readout
+          .size=${ReadoutSize.small}
+          .direction=${ReadoutDirection.horizontal}
+          .value=${'Thermo On'}
+          .valueType=${ReadoutValueType.text}
+          .label=${'Operating mode'}
+        ></obc-readout>
+        <obc-readout
+          .size=${ReadoutSize.small}
+          .direction=${ReadoutDirection.horizontal}
+          .value=${'Normal'}
+          .valueType=${ReadoutValueType.text}
+          .label=${'Status'}
+        ></obc-readout>
       </div>`;
   },
 };

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

@@ -25,7 +25,12 @@ import {
   type ReadoutSrcOptions,
 } from '../readout-list-item/readout-list-item.js';
 import {Priority} from '../types.js';
-import {type ReadoutNumericFormatOptions} from './readout-formatters.js';
+import {
+  assertReadoutValueType,
+  resolveReadoutNumericValue,
+  ReadoutValueType,
+  type ReadoutNumericFormatOptions,
+} from './readout-formatters.js';
 import {
   isDisplayedAtSetpoint,
   readoutNumericFormatOptions,
@@ -58,6 +63,7 @@ import '../../icons/icon-drop-down-google.js';
 // purpose: the two components are layout variants of the same primitives +
 // per-block options API and may merge in a future release.
 export {ObcTextboxFontWeight} from '../../components/textbox/textbox.js';
+export {ReadoutValueType} from './readout-formatters.js';
 export type {
   ReadoutBlockState,
   ReadoutValueOptions,
@@ -202,6 +208,8 @@ export interface ReadoutSourceOptions extends ReadoutSrcOptions {
  *   `flyout` interactivity via `srcOptions.interaction`.
  * - **Formatting:** shared `fractionDigits`, width reservation via
  *   `maxDigits` and per-segment `hintedZeros`; a `null` value renders a dash.
+ * - **Text values:** `valueType="text"` renders `value` verbatim (e.g.
+ *   `"Auto"`) instead of formatting it as a number.
  *
  * ### Usage Guidelines
  * Use for stand-alone instrument readouts and readouts embedded in
@@ -242,7 +250,18 @@ export class ObcReadout extends LitElement {
    * value block at full size, so the layout does not shift when data arrives.
    */
   @property({type: Boolean, attribute: false}) hasValue = true;
-  @property({type: Number}) value: number | null = null;
+  /**
+   * The value; `null` 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;
   /** Render the value as `offText` (e.g. equipment powered down). Affects the value only. */
   @property({type: Boolean}) off = false;
   /** Text shown in place of the value when `off` is true. @availableWhen off==true */
@@ -267,7 +286,17 @@ export class ObcReadout extends LitElement {
   @property({type: Boolean}) hasDegree = false;
   /** @availableWhen hasDegree==false */
   @property({type: Boolean}) hasDegreeSpacer = false;
+  /**
+   * Also formats the numeric setpoint / advice blocks, which stay numeric
+   * even when the value is text.
+   * @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.
+   * @availableWhen valueType==number || hasSetpoint==true || hasAdvice==true
+   */
   @property({type: Number}) maxDigits = 0;
   @property({type: String}) dataQuality?: ReadoutDataQuality;
   // `boolean | …` (not `false | …`): the generated Angular wrapper widens a
@@ -361,8 +390,10 @@ export class ObcReadout extends LitElement {
     if (!this.hasSetpoint) {
       return false;
     }
+    // A text value never compares equal to a setpoint, so flip-flop / pop-up
+    // stay dormant for `valueType="text"`.
     return isDisplayedAtSetpoint(
-      this.value,
+      resolveReadoutNumericValue(this.value, this.valueType) ?? null,
       this.setpoint,
       this.numericFormatOptions(this.resolvedMaxDigits)
     );
@@ -489,7 +520,9 @@ export class ObcReadout extends LitElement {
 
   private renderBlock(config: {
     variant: ReadoutBlockVariant;
-    value: number | null | undefined;
+    value: number | string | null | undefined;
+    /** Only the value block is ever text; setpoint / advice stay numeric. */
+    valueType?: ReadoutValueType;
     valueSize: ObcTextboxSize;
     enhanced: boolean;
     weight: ObcTextboxFontWeight;
@@ -518,6 +551,7 @@ export class ObcReadout extends LitElement {
         exportparts="block, block-content, block-text, block-icon, degree"
         .variant=${config.variant}
         .value=${config.value ?? null}
+        .valueType=${config.valueType ?? ReadoutValueType.number}
         .size=${this.resolvedSize}
         .valueSize=${config.valueSize}
         .enhanced=${config.enhanced}
@@ -676,6 +710,7 @@ export class ObcReadout extends LitElement {
         ${this.renderBlock({
           variant: ReadoutBlockVariant.value,
           value: this.value,
+          valueType: this.valueType,
           valueSize: this.valueSize,
           enhanced: this.rowEnhanced,
           weight: this.valueWeight,
@@ -1017,6 +1052,7 @@ export class ObcReadout extends LitElement {
         : html`${this.renderBlock({
             variant: ReadoutBlockVariant.value,
             value: this.value,
+            valueType: this.valueType,
             valueSize: this.primarySize,
             enhanced: false,
             weight: this.valueWeight,
@@ -1089,6 +1125,18 @@ export class ObcReadout 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', this.value, this.valueType);
+  }
+
   override updated(changed: Map<string, unknown>): void {
     super.updated(changed);
 

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

@@ -7,6 +7,7 @@ import {
   ReadoutListItemPriority,
   ReadoutListItemDataQuality,
   type ReadoutValueOptions,
+  ReadoutValueType,
 } from '../readout-list-item/readout-list-item.js';
 import '../readout-list-item/readout-list-item.js';
 import type {AlertFrameConfig} from '../../components/alert-frame/alert-frame.js';
@@ -22,7 +23,8 @@ type ListArgs = {
 
 type Row = {
   label: string;
-  value: number | null;
+  value: number | string | null;
+  valueType?: ReadoutValueType;
   unit: string;
   size?: ReadoutListItemSize;
   hasDegree?: boolean;
@@ -55,6 +57,7 @@ function renderRow(row: Row) {
       .label=${row.label}
       .unit=${row.unit}
       .value=${row.value}
+      .valueType=${row.valueType ?? ReadoutValueType.number}
       .size=${row.size ?? ReadoutListItemSize.small}
       .hasDegree=${row.hasDegree ?? false}
       .fractionDigits=${row.fractionDigits ?? 0}
@@ -112,6 +115,49 @@ export const Default: Story = {
   render: (args) => renderList(MIXED_ROWS, args.showDebugOverlay),
 };
 
+/**
+ * **Mixed text and numeric rows.** Rows with `valueType="text"` render their
+ * value verbatim and are **excluded from the auto-computed numeric reserver in
+ * both directions**:
+ *
+ * - they do not *contribute* to it, so a long string like "Thermo On" cannot
+ *   inflate the shared value column for every numeric row;
+ * - they do not *receive* it either, so a short string like "Auto" is not padded
+ *   out to a digit width. Each text row's value block sizes to its own content.
+ *
+ * A text row's setpoint / advice blocks stay numeric and are reserved normally.
+ */
+const TEXT_ROWS: Row[] = [
+  {
+    label: 'Operating mode',
+    value: 'Thermo On',
+    valueType: ReadoutValueType.text,
+    unit: '',
+  },
+  {
+    label: 'Status',
+    value: 'Normal',
+    valueType: ReadoutValueType.text,
+    unit: '',
+  },
+  // Deliberately shorter than the numeric reserve ("0000.0"), so this row
+  // demonstrates that a text value hugs its content instead of being padded
+  // out to the digit column's width.
+  {
+    label: 'Mode',
+    value: 'Auto',
+    valueType: ReadoutValueType.text,
+    unit: '',
+  },
+  {label: 'Temperature', value: 45, unit: 'C', hasDegree: true},
+  {label: 'Pressure', value: 1013, unit: 'Pa', fractionDigits: 1},
+  {label: 'Speed', value: 18.4, unit: 'kn', fractionDigits: 1},
+];
+
+export const TextValues: Story = {
+  render: (args) => renderList(TEXT_ROWS, args.showDebugOverlay),
+};
+
 const DEGREE_ROWS: Row[] = [
   {label: 'Heading', value: 287, unit: 'T', hasDegree: true},
   {label: 'COG', value: 92, unit: 'T', hasDegree: true},
@@ -182,6 +228,81 @@ export const WithSetpoints: Story = {
     ),
 };
 
+/**
+ * Attribute-driven regression test for text rows. Uses plain HTML attributes
+ * (not property bindings) so it covers the path where `value` arrives as a raw
+ * string: `valuetype="text"` must render verbatim and stay out of the shared
+ * numeric reserver, while a numeric `value="1013"` under the default value type
+ * must still resolve to a number and drive the reserver.
+ *
+ * Note the attribute is `valuetype`, all lowercase — Lit lowercases a property
+ * name to derive its attribute rather than kebab-casing it.
+ */
+export const TestTextRowAttributes: Story = {
+  render: () => html`
+    <div
+      data-obc-theme="day"
+      style="background: var(--container-background-color); padding: 16px; width: 360px; box-sizing: border-box;"
+    >
+      <obc-readout-list>
+        <obc-readout-list-item
+          id="text-row"
+          label="Operating mode"
+          value="Thermo On"
+          valuetype="text"
+        ></obc-readout-list-item>
+        <obc-readout-list-item
+          id="short-text-row"
+          label="Mode"
+          value="Auto"
+          valuetype="text"
+          maxdigits="8"
+          fractiondigits="3"
+        ></obc-readout-list-item>
+        <obc-readout-list-item
+          id="numeric-row"
+          label="Pressure"
+          unit="Pa"
+          value="1013"
+        ></obc-readout-list-item>
+      </obc-readout-list>
+    </div>
+  `,
+  play: async ({canvasElement}) => {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+
+    const textRow = canvasElement.querySelector('#text-row') as HTMLElement & {
+      valueType: ReadoutValueType;
+      valueOptions?: ReadoutValueOptions;
+    };
+    const shortTextRow = canvasElement.querySelector(
+      '#short-text-row'
+    ) as HTMLElement & {valueOptions?: ReadoutValueOptions};
+    const numericRow = canvasElement.querySelector(
+      '#numeric-row'
+    ) as HTMLElement & {valueOptions?: ReadoutValueOptions};
+
+    // The attribute reached the property as the enum value.
+    await expect(textRow.valueType).toBe(ReadoutValueType.text);
+    // Text renders verbatim. The value lives in the nested obc-readout-block's
+    // shadow root, so reach through it rather than the row's own.
+    const block = textRow.shadowRoot?.querySelector('obc-readout-block');
+    await expect(block?.shadowRoot?.textContent).toContain('Thermo On');
+
+    // The reserve is driven by the 4-digit numeric row only. Neither the long
+    // text ("Thermo On") nor the text row's own maxdigits=8 / fractiondigits=3
+    // inflate it — a text block ignores those, so counting them would pad every
+    // numeric row for nothing.
+    await expect(numericRow.valueOptions?.spaceReserver).toBe('0000');
+
+    // Text rows do not RECEIVE the numeric reserve either: it is a width in
+    // digits, so it would pad "Auto" out to the numeric column's width.
+    await expect(textRow.valueOptions?.spaceReserver).toBeUndefined();
+    await expect(shortTextRow.valueOptions?.spaceReserver).toBeUndefined();
+  },
+};
+
 export const TestDynamicRow: Story = {
   render: (args) => renderList(MIXED_ROWS, args.showDebugOverlay),
   play: async ({canvasElement}) => {

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

@@ -4,16 +4,31 @@ 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 {
+  resolveReadoutNumericValue,
+  ReadoutValueType,
+} from '../readout/readout-formatters.js';
 
 const ITEM_TAG = 'obc-readout-list-item';
 
+// Lit lowercases a property name to derive its attribute (it does not
+// kebab-case), so multi-word properties are observed as one lowercase word —
+// `valueType` becomes `valuetype`.
+//
+// The kebab-cased entries below are therefore INERT: the real attributes are
+// `maxdigits`, `fractiondigits`, `hasdegree`, `hassetpoint` and `hasadvice`, so
+// changing any of them does not currently re-trigger alignment. They predate
+// this list and are left as-is rather than silently activating five code paths
+// that have never run; see the follow-up issue before adding more entries.
 /** Child attributes whose change should re-trigger alignment (HTML-attribute usage). */
 const OBSERVED_ATTRIBUTES = [
   'unit',
   'src',
   'value',
+  'valuetype',
   'setpoint',
   'advice',
+  // ⚠ inert — see the note above; the real names have no hyphens.
   'max-digits',
   'fraction-digits',
   'has-degree',
@@ -21,6 +36,11 @@ const OBSERVED_ATTRIBUTES = [
   'has-advice',
 ];
 
+/** Whether a row renders its value as verbatim text rather than a number. */
+function isTextValueRow(item: ObcReadoutListItem): boolean {
+  return item.valueType === ReadoutValueType.text;
+}
+
 /** Integer-digit count of a numeric value (sign and fraction excluded). */
 function integerDigitCount(value: number | null | undefined): number {
   if (value === null || value === undefined || Number.isNaN(value)) {
@@ -45,7 +65,12 @@ function integerDigitCount(value: number | null | undefined): number {
  * - **Value / setpoint / advice:** the widest numeric width (max integer digits +
  *   max fraction digits across rows, derived from each row's `maxDigits` /
  *   `fractionDigits` / current values) is reserved on every row's numeric blocks.
- *   Reserving off digit counts keeps it stable as live values update.
+ *   Reserving off digit counts keeps it stable as live values update. A row with
+ *   `valueType="text"` is excluded in both directions — it neither contributes
+ *   to the reserve (so a long text value cannot inflate the numeric column) nor
+ *   receives it (so short text is not padded to a digit width); its value block
+ *   sizes to its own content. Its setpoint / advice blocks stay numeric and are
+ *   reserved normally.
  * - **Source:** the longest `src` becomes every row's source space-reserver.
  * - **Degree:** if any row has a degree, non-degree rows reserve the degree column
  *   (`hasDegreeSpacer`) so their digits line up with the degree rows; the spacer is
@@ -123,11 +148,31 @@ export class ObcReadoutList extends LitElement {
     let anyDegree = false;
 
     for (const item of items) {
-      maxFractionDigits = Math.max(maxFractionDigits, item.fractionDigits ?? 0);
+      // A text value renders verbatim, so it contributes nothing to the numeric
+      // reserve: resolving it yields `undefined` and `integerDigitCount` returns
+      // 0. Its row's `maxDigits` / `fractionDigits` are skipped too — they are
+      // ignored by a text block, so counting them would let a text row inflate
+      // every other row's numeric column. They DO still count when the row also
+      // has a setpoint or advice block, which stay numeric and are formatted by
+      // them. Numeric rows driven by HTML attributes resolve back to numbers
+      // here, so they take part as usual.
+      const hasNumericBlock =
+        !isTextValueRow(item) || item.hasSetpoint || item.hasAdvice;
+      if (hasNumericBlock) {
+        maxFractionDigits = Math.max(
+          maxFractionDigits,
+          item.fractionDigits ?? 0
+        );
+        maxIntegerDigits = Math.max(maxIntegerDigits, item.maxDigits ?? 0);
+      }
       maxIntegerDigits = Math.max(
         maxIntegerDigits,
-        item.maxDigits ?? 0,
-        integerDigitCount(item.value),
+        integerDigitCount(
+          resolveReadoutNumericValue(
+            item.value,
+            item.valueType ?? ReadoutValueType.number
+          )
+        ),
         item.hasSetpoint ? integerDigitCount(item.setpoint) : 0,
         item.hasAdvice ? integerDigitCount(item.advice) : 0
       );
@@ -155,9 +200,13 @@ export class ObcReadoutList extends LitElement {
       // Recompute every reserver / spacer on every pass (do not gate on a value
       // being present), so stale state clears when rows change — e.g. when the
       // last degree row, the last unit, or the last source is removed.
+      // The numeric reserve is a width in DIGITS, so applying it to a text
+      // block would pad short text ("Auto" padded out to "0000.0"'s width).
+      // Text rows hug their own content instead. Setpoint / advice stay
+      // numeric and keep the shared reserve even on a text row.
       item.valueOptions = {
         ...item.valueOptions,
-        spaceReserver: numericReserver,
+        spaceReserver: isTextValueRow(item) ? undefined : numericReserver,
       };
       item.setpointOptions = {
         ...item.setpointOptions,