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

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

@@ -16,6 +16,7 @@ import {
   type ReadoutAdviceOptions,
   type ReadoutReserverOptions,
   type ReadoutSrcOptions,
+  ReadoutValueType,
 } from './readout-list-item.js';
 import type {AlertFrameConfig} from '../../components/alert-frame/alert-frame.js';
 import {
@@ -36,7 +37,8 @@ type ReadoutListItemStoryArgs = {
   unit: string;
   src: string;
   hasValue: boolean;
-  value: number;
+  value: number | string;
+  valueType: ReadoutValueType;
   off: boolean;
   hasSetpoint: boolean;
   setpoint: number;
@@ -90,7 +92,8 @@ type ReadoutItemConfig = {
   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 renderItem(config: ReadoutItemConfig) {
       .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}
@@ -245,6 +249,7 @@ const defaultArgs: ReadoutListItemStoryArgs = {
   src: 'SRC',
   hasValue: true,
   value: 123,
+  valueType: ReadoutValueType.number,
   off: false,
   hasSetpoint: false,
   setpoint: 120,
@@ -313,6 +318,7 @@ const meta = {
         src: args.src,
         hasValue: args.hasValue,
         value: args.value,
+        valueType: args.valueType,
         off: args.off,
         hasSetpoint: args.hasSetpoint,
         setpoint: args.setpoint,
@@ -331,7 +337,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'}},
@@ -461,6 +476,96 @@ export const Off: Story = {
     ]),
 };
 
+/**
+ * **Text values** — `valueType="text"` renders `value` verbatim instead of
+ * formatting it as a number, for readings that are states rather than
+ * quantities ("Thermo On", "Auto", "Normal").
+ *
+ * The first section reproduces the reference design: two status rows sharing a
+ * bar, each a label with a bold text value, separated by a vertical divider.
+ *
+ * Under `valueType="text"` the numeric format options (`fractionDigits`,
+ * `maxDigits`, `hintedZeros`) are ignored; an explicit `spaceReserver` still
+ * applies. Passing text while `valueType` is `number` throws a `TypeError`
+ * rather than rendering `NaN`.
+ */
+const STATUS_BAR_ROWS: {label: string; value: string}[] = [
+  {label: 'Operating mode', value: 'Thermo On'},
+  {label: 'Status', value: 'Normal'},
+];
+
+export const TextValue: Story = {
+  render: () => html`
+    <style>
+      .rli-status-bar {
+        display: flex;
+        align-items: stretch;
+        width: 100%;
+        background: var(--container-background-color);
+      }
+      .rli-status-cell {
+        flex: 1;
+        display: flex;
+        align-items: center;
+        padding: 0 16px;
+      }
+      .rli-status-cell + .rli-status-cell {
+        border-left: 1px solid var(--border-divider-color, #ccc);
+      }
+      .rli-status-cell > obc-readout-list-item {
+        width: 100%;
+      }
+      .rli-text-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(240px, max-content));
+        gap: 12px 24px;
+        margin-top: 32px;
+      }
+    </style>
+    <div class="rli-status-bar">
+      ${STATUS_BAR_ROWS.map(
+        (row) => html`
+          <div class="rli-status-cell">
+            ${renderItem({
+              label: row.label,
+              value: row.value,
+              valueType: ReadoutValueType.text,
+              options: {
+                size: ReadoutListItemSize.medium,
+                value: {weight: ObcTextboxFontWeight.bold},
+              },
+            })}
+          </div>
+        `
+      )}
+    </div>
+    <div class="rli-text-grid">
+      ${[
+        {label: 'Mode', value: 'Auto', valueType: ReadoutValueType.text},
+        {
+          label: 'Thruster',
+          value: 'Standby',
+          valueType: ReadoutValueType.text,
+        },
+        // Numeric rows for contrast — the same component, unchanged.
+        {label: 'Speed', value: 12.4, valueType: ReadoutValueType.number},
+        // Verbatim text preserves formatting a number could not round-trip.
+        {label: 'Bearing', value: '1.50', valueType: ReadoutValueType.text},
+      ].map((row) =>
+        renderItem({
+          label: row.label,
+          value: row.value,
+          valueType: row.valueType,
+          options: {
+            size: ReadoutListItemSize.medium,
+            fractionDigits: 1,
+          },
+        })
+      )}
+    </div>
+  `,
+};
+
 const SIZES = [
   ReadoutListItemSize.small,
   ReadoutListItemSize.medium,
@@ -1596,7 +1701,8 @@ export const MissingParts: Story = {
  */
 type AlignmentRow = {
   label: string;
-  value: number | null;
+  value: number | string | null;
+  valueType?: ReadoutValueType;
   unit: string;
   size?: ReadoutListItemSize;
   hasDegree?: boolean;
@@ -1722,6 +1828,19 @@ const ALIGNMENT_ROWS: AlignmentRow[] = [
       type: ObcAlertFrameType.Regular,
     },
   },
+  // text value — `valueType="text"` renders verbatim and ignores maxDigits /
+  // fractionDigits, but still honours an explicit `spaceReserver`. So these
+  // rows hug their text in the left column and join the shared value column in
+  // the right one, confirming text does not disturb the numeric alignment.
+  // (Inside `obc-readout-list`, which owns the reservers, text rows are instead
+  // excluded from the computed numeric width — see that component's stories.)
+  {label: 'Mode', value: 'Auto', valueType: ReadoutValueType.text, unit: ''},
+  {
+    label: 'Thruster',
+    value: 'Standby',
+    valueType: ReadoutValueType.text,
+    unit: '',
+  },
   // size variants — value digit edges do NOT fully align cross-size (the degree
   // column scales 6/8/12px with the value size); see the ColumnAlignment doc.
 
@@ -1771,6 +1890,7 @@ function renderAlignmentColumn(aligned: boolean, showDebugOverlay: boolean) {
           unit: row.unit,
           src: '',
           value: row.value,
+          valueType: row.valueType,
           hasSetpoint: row.hasSetpoint,
           setpoint: row.setpoint,
           hasAdvice: row.hasAdvice,

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

@@ -15,7 +15,12 @@ import {
   ReadoutBlockDataQuality,
   ReadoutBlockHidePhase,
 } from '../../building-blocks/readout-block/readout-block.js';
-import {type ReadoutNumericFormatOptions} from '../readout/readout-formatters.js';
+import {
+  assertReadoutValueType,
+  resolveReadoutNumericValue,
+  ReadoutValueType,
+  type ReadoutNumericFormatOptions,
+} from '../readout/readout-formatters.js';
 import {
   isDisplayedAtSetpoint,
   readoutNumericFormatOptions,
@@ -39,6 +44,9 @@ import {AlertType} from '../../types.js';
 // without a second import path.
 export {ObcTextboxFontWeight} from '../../components/textbox/textbox.js';
 
+// Re-exported so consumers can type `valueType` without a second import path.
+export {ReadoutValueType} from '../readout/readout-formatters.js';
+
 /**
  * Density/size scale of the readout row (an alias of `ReadoutBlockSize`).
  * - `small`: regular value typography (smallest, densest).
@@ -207,6 +215,8 @@ export interface ReadoutSrcOptions extends ReadoutBlockState {
  *   `round-corners`, or `round` corners.
  * - **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.
+ *   `"Thermo On"`) instead of formatting it as a number.
  *
  * ### Usage Guidelines
  * Use for dense readout rows in lists/tables. Prefer `<obc-readout>` for rich
@@ -242,7 +252,18 @@ export class ObcReadoutListItem extends LitElement {
    * block at full size, so the row 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 */
@@ -265,7 +286,17 @@ export class ObcReadoutListItem extends LitElement {
   @property({type: Boolean}) hasLeadingIcon = false;
   @property({type: Boolean}) 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?: ReadoutListItemDataQuality;
   // `boolean | …` (not `false | …`): the generated Angular wrapper widens a
@@ -329,8 +360,10 @@ export class ObcReadoutListItem 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)
     );
@@ -451,7 +484,9 @@ export class ObcReadoutListItem 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;
@@ -473,6 +508,7 @@ export class ObcReadoutListItem 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}
@@ -684,6 +720,7 @@ export class ObcReadoutListItem extends LitElement {
           ? this.renderBlock({
               variant: ReadoutBlockVariant.value,
               value: this.value,
+              valueType: this.valueType,
               valueSize: this.valueSize,
               enhanced: this.rowEnhanced,
               weight: this.valueWeight,
@@ -821,6 +858,18 @@ export class ObcReadoutListItem 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-list-item', this.value, this.valueType);
+  }
+
   override updated(changed: Map<string, unknown>): void {
     super.updated(changed);