@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.87 → 2.0.0-next.89

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

@@ -0,0 +1,355 @@
+import {LitElement, html, nothing, unsafeCSS, type TemplateResult} from 'lit';
+import {property, state} from 'lit/decorators.js';
+import {classMap} from 'lit/directives/class-map.js';
+import componentStyle from './readout-block.css?inline';
+import {customElement} from '../../decorator.js';
+import '../../components/textbox/textbox.js';
+import {
+  ObcTextboxSize,
+  ObcTextboxFontWeight,
+  ObcTextboxAlignment,
+} from '../../components/textbox/textbox.js';
+import '../../icons/icon-input-right.js';
+import '../../icons/icon-notification-advice.js';
+import {
+  formatNumericValue,
+  readoutFormattedInteger,
+  type ReadoutNumericFormatOptions,
+} from '../../navigation-instruments/readout/readout-formatters.js';
+import {
+  type AlertFrameConfig,
+  wrapWithAlertFrame,
+} from '../../components/alert-frame/alert-frame.js';
+
+// Re-exported so consumers can configure typography without a second import path.
+export {
+  ObcTextboxSize,
+  ObcTextboxFontWeight,
+  ObcTextboxAlignment,
+} from '../../components/textbox/textbox.js';
+
+/**
+ * Semantic variant of the block. Drives the default marker icon and the
+ * colour token; the layout is identical across variants.
+ * - `value`: the primary reading (no default marker icon).
+ * - `setpoint`: a setpoint reference (default `input-right` marker).
+ * - `advice`: an advisory reference (default `notification-advice` marker).
+ */
+export enum ReadoutBlockVariant {
+  value = 'value',
+  setpoint = 'setpoint',
+  advice = 'advice',
+}
+
+/**
+ * Density tier of the block — drives icon size, the icon↔number gap, and the
+ * degree-column width tier. The number typography size is controlled
+ * independently via {@link ObcReadoutBlock.valueSize} so a parent can de-emphasise
+ * one block relative to another within the same tier.
+ */
+export enum ReadoutBlockSize {
+  small = 'small',
+  medium = 'medium',
+  large = 'large',
+}
+
+/**
+ * Per-block measurement quality, rendered as a non-shifting outline chip.
+ * - `low-integrity`: the value is suspect.
+ * - `invalid`: the value is invalid.
+ */
+export enum ReadoutBlockDataQuality {
+  lowIntegrity = 'low-integrity',
+  invalid = 'invalid',
+}
+
+/**
+ * Pop-up fade phase for a setpoint block. Driven by the parent's setpoint
+ * interaction state machine; only meaningful for `role="setpoint"`.
+ */
+export enum ReadoutBlockHidePhase {
+  none = 'none',
+  hiding = 'hiding',
+  hidden = 'hidden',
+}
+
+/**
+ * `<obc-readout-block>` – the most atomic readout primitive: a single
+ * cap-height-aligned, width-reservable numeric segment (value / setpoint /
+ * advice).
+ *
+ * It renders one `obc-textbox` number with optional hinted leading zeros, a
+ * reservable width, an optional leading marker icon (via the `icon` slot or the
+ * role default), an optional trailing degree glyph, an `off`/unavailable text
+ * state, per-block data-quality and an optional per-block alert frame.
+ *
+ * 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
+ * block stays neutral until placed.
+ *
+ * @experimental Pilot for the new primitives + per-block options Readout API; the
+ * API may change in a future release.
+ *
+ * @slot icon - Replaces the role's default marker icon.
+ *
+ * @csspart block - The block container (carries role / tone / data-quality).
+ * @csspart block-content - The number + degree group.
+ * @csspart block-text - The `obc-textbox` rendering the number.
+ * @csspart block-icon - The leading marker-icon container.
+ * @csspart degree - The trailing degree-glyph column.
+ */
+@customElement('obc-readout-block')
+export class ObcReadoutBlock extends LitElement {
+  /** Semantic variant (value / setpoint / advice). */
+  @property({type: String}) variant: ReadoutBlockVariant =
+    ReadoutBlockVariant.value;
+
+  /** The numeric value; `null`/`undefined` renders a dash. */
+  @property({type: Number}) value: number | null = null;
+
+  /** Density tier — icon size, gap, degree tier. */
+  @property({type: String}) size: ReadoutBlockSize = ReadoutBlockSize.small;
+
+  /**
+   * Resolved number-typography size. When unset it is derived from `size`
+   * (small→s, medium→m, large→l), so a parent that de-emphasises a block (e.g.
+   * a secondary setpoint) can pass a smaller size without changing the tier.
+   */
+  @property({type: String}) valueSize?: ObcTextboxSize;
+
+  /** Accent (in-command) colour tone. */
+  @property({type: Boolean}) enhanced = false;
+
+  /** Number font weight (regular / semibold / bold); colour is independent. */
+  @property({type: String}) weight: ObcTextboxFontWeight =
+    ObcTextboxFontWeight.regular;
+
+  /** Render the trailing cap-height degree glyph (`°`). */
+  @property({type: Boolean}) hasDegree = false;
+
+  /** Show the leading marker-icon container (always on for setpoint/advice). */
+  @property({type: Boolean}) hasIcon = false;
+
+  /** Number of fraction digits. */
+  @property({type: Number}) fractionDigits = 0;
+
+  /** Integer digits to reserve / hint (independent of `fractionDigits`). */
+  @property({type: Number}) maxDigits = 0;
+
+  /** Render muted leading zeros filling the integer part to `maxDigits`. */
+  @property({type: Boolean}) hintedZeros = false;
+
+  /** Explicit longest string to reserve width for (e.g. `"0000.0"`). */
+  @property({type: String}) spaceReserver?: string;
+
+  /** Render `offText` instead of a number (e.g. equipment powered down). */
+  @property({type: Boolean}) off = false;
+
+  /** Text shown when `off` is true. */
+  @property({type: String}) offText = 'OFF';
+
+  /** Text alignment of the number within its reserved width. */
+  @property({type: String}) alignment: ObcTextboxAlignment =
+    ObcTextboxAlignment.Right;
+
+  /** Per-block measurement quality (outline chip). */
+  @property({type: String}) dataQuality?: ReadoutBlockDataQuality;
+
+  // `boolean | …` (not `false | …`): the generated Angular wrapper widens a
+  // literal-`false` union to `boolean`. `wrapWithAlertFrame` treats any
+  // non-object as "no frame", so accepting `boolean` is harmless.
+  /** Per-block alert frame; nests inside any parent alert frame. */
+  @property({type: Object}) alert: boolean | AlertFrameConfig = false;
+
+  /** Setpoint focus (touch) state — only meaningful for `role="setpoint"`. */
+  @property({type: Boolean}) touching = false;
+
+  /** Setpoint pop-up fade phase — only meaningful for `role="setpoint"`. */
+  @property({type: String}) hidePhase: ReadoutBlockHidePhase =
+    ReadoutBlockHidePhase.none;
+
+  @state() private hasAssignedIcon = false;
+
+  private get resolvedValueSize(): ObcTextboxSize {
+    if (this.valueSize) {
+      return this.valueSize;
+    }
+    switch (this.size) {
+      case ReadoutBlockSize.large:
+        return ObcTextboxSize.l;
+      case ReadoutBlockSize.medium:
+        return ObcTextboxSize.m;
+      default:
+        return ObcTextboxSize.s;
+    }
+  }
+
+  private get numericFormatOptions(): ReadoutNumericFormatOptions {
+    return {
+      showZeroPadding: false,
+      minValueLength: this.maxDigits,
+      fractionDigits: this.fractionDigits,
+    };
+  }
+
+  /** Widest possible value string for width reservation (e.g. `"000.0"`). */
+  private get reserverText(): string {
+    const maxDigits = this.maxDigits;
+    if (maxDigits <= 0) {
+      return '';
+    }
+    const integer = '0'.repeat(Math.max(maxDigits, 1));
+    return this.fractionDigits > 0
+      ? `${integer}.${'0'.repeat(this.fractionDigits)}`
+      : integer;
+  }
+
+  /**
+   * Effective width reserver: the wider of the explicit `spaceReserver` and the
+   * `maxDigits`/`fractionDigits`-derived reserve, so an explicit reserver can
+   * never reserve *less* than the formatted value needs. Under tabular-nums the
+   * rendered width is proportional to character count, so "wider" compares length.
+   */
+  private widerReserver(explicit: string | undefined, derived: string): string {
+    if (!explicit) {
+      return derived;
+    }
+    if (!derived) {
+      return explicit;
+    }
+    return explicit.length >= derived.length ? explicit : derived;
+  }
+
+  private dataQualityClasses(): Record<string, boolean> {
+    return {
+      'data-low-integrity':
+        this.dataQuality === ReadoutBlockDataQuality.lowIntegrity,
+      'data-invalid': this.dataQuality === ReadoutBlockDataQuality.invalid,
+    };
+  }
+
+  private onIconSlotChange = (event: Event): void => {
+    // `slotchange` fires after the first render once content is (re)assigned,
+    // so it covers the initial state without a firstUpdated re-render.
+    this.hasAssignedIcon =
+      (event.target as HTMLSlotElement).assignedElements({flatten: true})
+        .length > 0;
+  };
+
+  private renderIcon(): TemplateResult | typeof nothing {
+    // Value blocks only show an icon when asked; setpoint/advice always reserve
+    // their marker. The role default is rendered as a direct child (so it sizes
+    // via `.block-icon obi-*`) and hidden once an icon is assigned to the slot —
+    // `{flatten: true}` sees through a forwarded-but-empty parent slot, so the
+    // default still shows when the consumer overrides nothing.
+    const showIcon = this.variant !== ReadoutBlockVariant.value || this.hasIcon;
+    if (!showIcon) {
+      return nothing;
+    }
+    let fallback: TemplateResult | typeof nothing = nothing;
+    if (this.variant === ReadoutBlockVariant.setpoint) {
+      fallback = html`<obi-input-right></obi-input-right>`;
+    } else if (this.variant === ReadoutBlockVariant.advice) {
+      fallback = html`<obi-notification-advice></obi-notification-advice>`;
+    }
+    return html`<span class="block-icon" part="block-icon" aria-hidden="true">
+      <slot name="icon" @slotchange=${this.onIconSlotChange}></slot>
+      ${this.hasAssignedIcon ? nothing : fallback}
+    </span>`;
+  }
+
+  /**
+   * A cap-height `°` column whose width scales with the number size. Inherits the
+   * block's colour.
+   */
+  private renderDegreeGlyph(size: ObcTextboxSize): TemplateResult {
+    return html`
+      <span
+        class=${classMap({
+          'degree-column': true,
+          [`degree-${size}`]: true,
+          'degree-inherit': true,
+        })}
+        part="degree"
+      >
+        <obc-textbox class="degree-glyph" .size=${size} alignment="center"
+          >°</obc-textbox
+        >
+      </span>
+    `;
+  }
+
+  override render() {
+    const valueSize = this.resolvedValueSize;
+    const formatOptions = this.numericFormatOptions;
+    const valueForFormat = this.value ?? undefined;
+    const text = this.off
+      ? this.offText
+      : 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 ||
+      !this.hintedZeros ||
+      valueForFormat === undefined ||
+      valueForFormat < 0
+        ? 0
+        : Math.max(this.maxDigits - 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
+    // 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);
+
+    const block = html`
+      <div
+        class=${classMap({
+          block: true,
+          [`block-${this.variant}`]: true,
+          [`size-${this.size}`]: true,
+          'tone-enhanced': this.enhanced,
+          touching: this.touching,
+          'is-hiding': this.hidePhase === ReadoutBlockHidePhase.hiding,
+          'is-hidden': this.hidePhase === ReadoutBlockHidePhase.hidden,
+          ...this.dataQualityClasses(),
+        })}
+        part="block block-${this.variant}"
+      >
+        ${this.renderIcon()}
+        <span class="block-content" part="block-content">
+          <obc-textbox
+            class="block-text"
+            part="block-text"
+            .size=${valueSize}
+            .fontWeight=${this.weight}
+            .alignment=${this.alignment}
+            .tabularNums=${true}
+          >
+            ${hinted
+              ? html`<span class="hinted-zero" aria-hidden="true"
+                  >${hinted}</span
+                >`
+              : nothing}${text}
+            ${reserver ? html`<span slot="length">${reserver}</span>` : nothing}
+          </obc-textbox>
+          ${this.hasDegree ? this.renderDegreeGlyph(valueSize) : nothing}
+        </span>
+      </div>
+    `;
+    return wrapWithAlertFrame(this.alert ?? false, block);
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-readout-block': ObcReadoutBlock;
+  }
+}

package/src/navigation-instruments/gauge-radial/gauge-radial.css

@@ -4,45 +4,68 @@
   height: 100%;
 }
 
-/* Host takes each sector's crop aspect (see `sectorClips`): 270/90 square, 180
-   wide — so the dial is the same size at any width.
+.gauge-radial-root {
+  /* Readout vertical placement per layout (% of the cropped box), tuned to the
+     watch geometry — re-check if the ring radii or the 448 box change. Which
+     layout uses which is in renderReadouts(). */
+  --readout-meta-top: 72%;
+  --readout-meta-top-needle: 63%;
+  --readout-meta-top-180: 60%;
+
+  position: relative;
 
-   `width`/`height: auto` + `max-width`/`max-height: 100%` makes the host the
-   largest box of the sector's aspect ratio that fits inside *both* the
-   available width and height. Using `height: auto` alone only honours the
-   width, so in a short, wide (e.g. flex) container the square would grow as
-   tall as it is wide and overflow — see issue #992. */
-:host([sector="270"]),
-:host([sector="90-left"]),
-:host([sector="90-right"]) {
+  /* The dial is the largest box of its sector's aspect ratio that fits inside
+     *both* the available width and height of the (full-size) host. `width: auto`
+     stretches the block to the host width, then `aspect-ratio` + `max-height`
+     transfer the constraint back, shrinking it to fit a short host too — see
+     issue #992. The host always fills its container, so the gauge can be
+     positioned within the leftover space via the alignment classes below. */
   width: auto;
   height: auto;
   max-width: 100%;
   max-height: 100%;
   aspect-ratio: 1;
-}
 
-/* 448 / 251 = the 180° crop's aspect (448 wide × 448·(1 − 44%) tall); keep in
-   sync with `sectorClips` bottom=44 in gauge-radial.ts. */
-:host([sector="180"]) {
-  width: auto;
-  height: auto;
-  max-width: 100%;
-  max-height: 100%;
-  aspect-ratio: 448 / 251;
-}
+  /* Defaults (centered both ways); overridden by the halign-* / valign-*
+     classes. Horizontal alignment uses auto margins (which reference the host
+     width); vertical alignment uses a relative `top` offset (which references
+     the definite host height) plus a self-sized `translateY`. */
+  margin-left: auto;
+  margin-right: auto;
+  top: 50%;
+  transform: translateY(-50%);
 
-.gauge-radial-root {
-  /* Readout vertical placement per layout (% of the cropped host), tuned to the
-     watch geometry — re-check if the ring radii or the 448 box change. Which
-     layout uses which is in renderReadouts(). */
-  --readout-meta-top: 72%;
-  --readout-meta-top-needle: 63%;
-  --readout-meta-top-180: 60%;
+  /* 448 / 251 = the 180° crop's aspect (448 wide × 448·(1 − 44%) tall); keep in
+     sync with `sectorClips` bottom=44 in gauge-radial.ts. */
+  &.sector-180 {
+    aspect-ratio: 448 / 251;
+  }
 
-  position: relative;
-  width: 100%;
-  height: 100%;
+  &.halign-left {
+    margin-left: 0;
+    margin-right: auto;
+  }
+  &.halign-center {
+    margin-left: auto;
+    margin-right: auto;
+  }
+  &.halign-right {
+    margin-left: auto;
+    margin-right: 0;
+  }
+
+  &.valign-top {
+    top: 0;
+    transform: translateY(0);
+  }
+  &.valign-center {
+    top: 50%;
+    transform: translateY(-50%);
+  }
+  &.valign-bottom {
+    top: 100%;
+    transform: translateY(-100%);
+  }
 
   .gauge-readout-value {
     position: absolute;

package/src/navigation-instruments/gauge-radial/gauge-radial.stories.ts

@@ -1,6 +1,8 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import {
+  GaugeRadialHorizontalAlignment,
   GaugeRadialSector,
+  GaugeRadialVerticalAlignment,
   ObcGaugeRadial,
   ObcGaugeRadialType,
 } from './gauge-radial.js';
@@ -28,6 +30,14 @@ const meta = {
     height: {control: {type: 'range', min: 100, max: 1000, step: 1}},
     type: {control: 'select', options: Object.values(ObcGaugeRadialType)},
     sector: {control: 'select', options: Object.values(GaugeRadialSector)},
+    horizontalAlignment: {
+      control: 'select',
+      options: Object.values(GaugeRadialHorizontalAlignment),
+    },
+    verticalAlignment: {
+      control: 'select',
+      options: Object.values(GaugeRadialVerticalAlignment),
+    },
     priority: {control: 'select', options: Object.values(Priority)},
     state: {control: 'select', options: Object.values(InstrumentState)},
     tickmarkStyle: {
@@ -259,6 +269,46 @@ export const ShortWideContainer180: Story = {
   },
 };
 
+export const ShortWideAlignedLeft: Story = {
+  args: {
+    ...sectorStoryArgs,
+    sector: GaugeRadialSector.deg270,
+    width: 600,
+    height: 160,
+    horizontalAlignment: GaugeRadialHorizontalAlignment.left,
+  },
+};
+
+export const ShortWideAlignedRight: Story = {
+  args: {
+    ...sectorStoryArgs,
+    sector: GaugeRadialSector.deg270,
+    width: 600,
+    height: 160,
+    horizontalAlignment: GaugeRadialHorizontalAlignment.right,
+  },
+};
+
+export const TallNarrowAlignedTop: Story = {
+  args: {
+    ...sectorStoryArgs,
+    sector: GaugeRadialSector.deg270,
+    width: 200,
+    height: 500,
+    verticalAlignment: GaugeRadialVerticalAlignment.top,
+  },
+};
+
+export const TallNarrowAlignedBottom: Story = {
+  args: {
+    ...sectorStoryArgs,
+    sector: GaugeRadialSector.deg270,
+    width: 200,
+    height: 500,
+    verticalAlignment: GaugeRadialVerticalAlignment.bottom,
+  },
+};
+
 const readoutStoryArgs = {
   value: 123,
   minValue: 0,

package/src/navigation-instruments/gauge-radial/gauge-radial.ts

@@ -27,6 +27,18 @@ export enum GaugeRadialSector {
   deg90Right = '90-right',
 }
 
+export enum GaugeRadialHorizontalAlignment {
+  left = 'left',
+  center = 'center',
+  right = 'right',
+}
+
+export enum GaugeRadialVerticalAlignment {
+  top = 'top',
+  center = 'center',
+  bottom = 'bottom',
+}
+
 export interface GaugeRadialAdvice {
   minValue: number;
   maxValue: number;
@@ -59,6 +71,12 @@ export interface GaugeRadialAdvice {
  * - **Advice zones**: Pass an array of {@link GaugeRadialAdvice} objects to
  *   render caution/alert arcs on the gauge. Not shown on the `90-left` /
  *   `90-right` sectors.
+ * - **Alignment**: The host always fills its container and the dial shrinks to
+ *   fit the smaller of the available width/height, so a short, wide (or tall,
+ *   narrow) container leaves slack on one axis. `horizontalAlignment`
+ *   (`left` | `center` | `right`) and `verticalAlignment`
+ *   (`top` | `center` | `bottom`) position the dial within that slack; both
+ *   default to `center`.
  *
  * ## Usage Guidelines
  *
@@ -125,6 +143,21 @@ export class ObcGaugeRadial extends SetpointMixin(LitElement) {
   @property({type: Array, attribute: false}) advices: GaugeRadialAdvice[] = [];
   @property({type: String, reflect: true}) sector: GaugeRadialSector =
     GaugeRadialSector.deg270;
+  /**
+   * Horizontal placement of the dial when the host is wider than the dial
+   * (e.g. a short, wide container shrinks the dial to fit the height, leaving
+   * horizontal slack). Default `center`.
+   */
+  @property({type: String})
+  horizontalAlignment: GaugeRadialHorizontalAlignment =
+    GaugeRadialHorizontalAlignment.center;
+  /**
+   * Vertical placement of the dial when the host is taller than the dial
+   * (e.g. a tall, narrow container shrinks the dial to fit the width, leaving
+   * vertical slack). Default `center`.
+   */
+  @property({type: String}) verticalAlignment: GaugeRadialVerticalAlignment =
+    GaugeRadialVerticalAlignment.center;
   /**
    * When `true`, shows the centre `<obc-readout>`(s) with the current value
    * (and optional `label`/`unit`). Layout depends on `sector` and `type`.
@@ -281,6 +314,8 @@ export class ObcGaugeRadial extends SetpointMixin(LitElement) {
           'sector-180': this.sector === GaugeRadialSector.deg180,
           'sector-90-left': this.sector === GaugeRadialSector.deg90Left,
           'sector-90-right': this.sector === GaugeRadialSector.deg90Right,
+          [`halign-${this.horizontalAlignment}`]: true,
+          [`valign-${this.verticalAlignment}`]: true,
         })}
       >
         <obc-instrument-radial

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

@@ -0,0 +1,13 @@
+:host {
+  display: block;
+  width: 100%;
+}
+
+/* Vertical stack of rows. The 4px row gap matches the rich detail rows in
+   `obc-automation-tank`; override via `--obc-readout-list-row-gap`. */
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--obc-readout-list-row-gap, 4px);
+  width: 100%;
+}