@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.111 → 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/compass/compass.ts

@@ -262,7 +262,7 @@ export class ObcCompass extends LitElement {
   /** @availableWhen priority==enhanced */
   @property({type: Array, attribute: false})
   priorityElements: CompassPriorityElement[] = [CompassPriorityElement.hdg];
-  /** Show compass NSEW labels and north arrow. */
+  /** Show compass NSEW labels. The north arrow is always shown, independent of this flag. */
   @property({type: Boolean}) showLabels: boolean = false;
   /** When true, labels and north arrow are placed inside the outer ring. */
   @property({type: Boolean}) tickmarksInside: boolean = false;
@@ -424,7 +424,7 @@ export class ObcCompass extends LitElement {
           .tickmarksInside=${this.tickmarksInside}
           .crosshairEnabled=${true}
           .crosshairCenterCutout=${this.hasCenterReadouts}
-          .northArrow=${!frame.labelsHidden}
+          .northArrow=${true}
           .angleSetpoint=${this.headingSetpoint ?? undefined}
           .newAngleSetpoint=${this.newHeadingSetpoint}
           .atAngleSetpoint=${this._headingSp.computeAtSetpoint(this.heading)}

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

@@ -38,6 +38,21 @@ const meta: Meta<typeof ObcCurrent> = {
       control: 'select',
       options: topVessels,
     },
+    hasPattern: {control: 'boolean'},
+    waveLength: {
+      control: {type: 'range', min: 0.25, max: 3, step: 0.05},
+      description:
+        'Wavelength multiplier on the design band spacing (1 = design).',
+    },
+    waveHeight: {
+      control: {type: 'range', min: 0, max: 1, step: 0.05},
+      description: 'Peak opacity the pattern bands fade up to.',
+    },
+    waveSpeed: {
+      control: {type: 'range', min: -2, max: 2, step: 0.1},
+      description:
+        'Pattern drift in wavelengths per second, with the flow (0 = static).',
+    },
   },
 } satisfies Meta<ObcCurrent>;
 
@@ -59,3 +74,21 @@ export const VesselEnhanced: Story = {
 export const DirectionEnhanced: Story = {
   args: {type: CurrentType.direction, priority: Priority.enhanced},
 };
+
+export const WithoutPattern: Story = {
+  args: {hasPattern: false},
+};
+
+/** Denser, softer waves: half the design wavelength at reduced intensity. */
+export const WaveTuned: Story = {
+  args: {waveLength: 0.5, waveHeight: 0.6},
+};
+
+/**
+ * The pattern drifts with the flow at `waveSpeed` wavelengths per second
+ * (excluded from visual tests because it animates continuously).
+ */
+export const AnimatedWaves: Story = {
+  tags: ['skip-test'],
+  args: {waveSpeed: 0.4},
+};

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

@@ -18,8 +18,14 @@ export enum CurrentType {
 
 const CURRENT_PATTERN_SCALE_VESSEL = 1.39;
 const CURRENT_PATTERN_SCALE_DIRECTION = 2.0;
-/** Chevron-tip anchor radius for the peripheral icon (vessel type), from Figma. */
-const CURRENT_ICON_PERIPHERY_RADIUS = 116;
+/**
+ * Chevron-tip anchor radius for the peripheral icon (vessel type): the tip
+ * sits on the track band's inner edge (112), so the 48-unit glyph box fills
+ * the band (112–160) exactly, per the OpenBridge 6.1 design.
+ */
+const CURRENT_ICON_PERIPHERY_RADIUS = innerRingRadiusFor(
+  WatchCircleType.double
+);
 /** Scale of the centered 24-unit chevron glyph (direction type), from Figma (168/24). */
 const CURRENT_DIRECTION_ICON_SCALE = 7;
 
@@ -56,6 +62,9 @@ export function clampCurrentSpeed(value: number | null): number | null {
  *   the enhanced (blue) palette.
  * - **Vessel image**: configurable silhouette rotating with
  *   `vesselHeadingDeg` (vessel type).
+ * - **Pattern toggle & wave tuning**: `hasPattern` switches the band pattern
+ *   off; `waveLength`, `waveHeight` and `waveSpeed` tune the band spacing,
+ *   intensity and drift motion.
  *
  * ## Usage Guidelines
  *
@@ -89,6 +98,28 @@ export class ObcCurrent extends LitElement {
   @property({type: Number}) currentFromDirection: number | null = null;
   /** Color priority: `Priority.enhanced` uses the blue/enhanced palette (default: `Priority.regular`). */
   @property({type: String}) priority: Priority = Priority.regular;
+  /**
+   * Show the force-graphics band pattern behind the watch face.
+   * @availableWhen currentFromDirection!=null
+   */
+  @property({type: Boolean, attribute: false}) hasPattern = true;
+  /**
+   * Wavelength of the pattern bands as a multiplier on the design spacing
+   * (1 = design, 0.5 = twice as dense).
+   * @availableWhen hasPattern==true && currentFromDirection!=null
+   */
+  @property({type: Number}) waveLength = 1;
+  /**
+   * Wave intensity: the peak opacity the pattern bands fade up to (0–1).
+   * @availableWhen hasPattern==true && currentFromDirection!=null
+   */
+  @property({type: Number}) waveHeight = 1;
+  /**
+   * Drift speed of the pattern in wavelengths per second, moving with the
+   * flow (negative drifts against it); 0 keeps the pattern static.
+   * @availableWhen hasPattern==true && currentFromDirection!=null
+   */
+  @property({type: Number}) waveSpeed = 0;
   /**
    * The image of the vessel.
    * @availableWhen type==vessel
@@ -148,7 +179,7 @@ export class ObcCurrent extends LitElement {
   }
 
   private renderForcePattern(watchCircleType: WatchCircleType) {
-    if (this.currentFromDirection == null) {
+    if (!this.hasPattern || this.currentFromDirection == null) {
       return nothing;
     }
     return html`
@@ -162,6 +193,9 @@ export class ObcCurrent extends LitElement {
           color: this.enhanced
             ? 'var(--instrument-enhanced-tertiary-color)'
             : undefined,
+          waveLength: this.waveLength,
+          waveHeight: this.waveHeight,
+          waveSpeed: this.waveSpeed,
         })}
       </svg>
     `;

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

@@ -128,12 +128,14 @@ export const WithVectorArrows: Story = {
 
 /**
  * Below the label-reserve cap (~200px for the NSWE + north-arrow decor) the
- * frame reports `labelsHidden` and the instrument drops the labels and the
- * north arrow instead of letting them clip — the same graceful degradation
- * the tick-label instruments use (issue #1021).
+ * frame reports `labelsHidden` and the instrument drops the labels instead
+ * of letting them clip — the same graceful degradation the tick-label
+ * instruments use (issue #1021). The north arrow stays visible on even the
+ * smallest face: below the small-scale threshold it renders as a compact
+ * triangle at the ring that scales with the face, so it never clips.
  */
 export const SmallContainerDegraded: Story = {
-  name: 'Small Container (160px, Labels + Arrow Hidden Past Cap)',
+  name: 'Small Container (160px, Labels Hidden Past Cap)',
   args: {
     width: 160,
   },

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

@@ -309,7 +309,7 @@ export class ObcHeading extends LitElement {
           .tickmarksInside=${this.tickmarksInside}
           .crosshairEnabled=${true}
           .crosshairCenterCutout=${this.hasCenterReadouts}
-          .northArrow=${!frame.labelsHidden}
+          .northArrow=${true}
           .angleSetpoint=${this.headingSetpoint ?? undefined}
           .newAngleSetpoint=${this.newHeadingSetpoint}
           .atAngleSetpoint=${this._headingSp.computeAtSetpoint(this.heading)}

package/src/navigation-instruments/pitch-roll-heave/pitch-roll-heave.ts

@@ -351,9 +351,16 @@ export class ObcPitchRollHeave extends LitElement {
    * `obc-watch` renders its crosshair after the bands, i.e. on top of them.
    * Drawing it here puts it under the watch layer, so the bands and the heave
    * column mask it naturally.
+   *
+   * In `single-scale` nothing frames the segment above the vessel (the other
+   * three arms end under the pitch band, roll band and heave column), so the
+   * vertical arm stops at the centre instead of continuing upward. In
+   * `dual-scale` the top roll band gives it a natural endpoint, so the full
+   * arm is kept.
    */
   private renderCrosshair(): SVGTemplateResult {
     const r = OUTER_RING_RADIUS;
+    const yTop = this.isDualScale ? -r : 0;
     return svg`
       <line
         x1=${-r} y1="0" x2=${r} y2="0"
@@ -361,7 +368,7 @@ export class ObcPitchRollHeave extends LitElement {
         vector-effect="non-scaling-stroke"
       />
       <line
-        x1="0" y1=${-r} x2="0" y2=${r}
+        x1="0" y1=${yTop} x2="0" y2=${r}
         stroke="var(--instrument-frame-tertiary-color)"
         vector-effect="non-scaling-stroke"
       />

package/src/navigation-instruments/rate-of-turn/rate-of-turn.stories.ts

@@ -131,7 +131,7 @@ export const WithTrackBar: Story = {
     hasReadout: true,
     rateOfTurnDegreesPerMinute: 45,
     rotPosition: RotPosition.innerCircle,
-    watchCircleType: WatchCircleType.double,
+    watchCircleType: WatchCircleType.triple,
   },
 };
 
@@ -142,7 +142,7 @@ export const WithTrackBarEnhanced: Story = {
     hasReadout: true,
     rateOfTurnDegreesPerMinute: 45,
     rotPosition: RotPosition.innerCircle,
-    watchCircleType: WatchCircleType.double,
+    watchCircleType: WatchCircleType.triple,
     priority: Priority.enhanced,
   },
 };
@@ -154,7 +154,7 @@ export const WithTrackBarPortStarboard: Story = {
     hasReadout: true,
     rateOfTurnDegreesPerMinute: 45,
     rotPosition: RotPosition.innerCircle,
-    watchCircleType: WatchCircleType.double,
+    watchCircleType: WatchCircleType.triple,
     rotPortStarboard: true,
   },
 };

package/src/navigation-instruments/rate-of-turn/rate-of-turn.ts

@@ -35,7 +35,8 @@ export {RotType, RotPosition};
  * - **Track bar** (`hasTrackBar`): A bar in the ring band growing from the
  *   twelve o'clock position to the measured rate of turn, with a needle
  *   marker at its end and sector tickmarks (pairs with
- *   `watchCircleType="double"` for the banded face).
+ *   `watchCircleType="double"` for the banded face, or `"triple"` when the
+ *   ROT dots sit on the inner circle).
  * - **Center readout** (`hasReadout`): A centered readout showing the
  *   measured rate of turn (label `ROT`, unit `DEG/min` by default).
  * - **Color priority**: Uses `priority` to select regular or enhanced color
@@ -91,7 +92,9 @@ export class ObcRateOfTurn extends LitElement {
    * When `true`, shows a bar in the ring band from the twelve o'clock
    * position to the measured rate of turn, with a needle marker at its end
    * and sector tickmarks. Pairs with `watchCircleType="double"` for the
-   * banded face. Driven by `rateOfTurnDegreesPerMinute` only.
+   * banded face — or `"triple"` when `rotPosition` is `innerCircle`, so the
+   * dots get their inner track too. Driven by `rateOfTurnDegreesPerMinute`
+   * only.
    */
   @property({type: Boolean}) hasTrackBar: boolean = false;
   /**