@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.88 → 2.0.0-next.90

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

@@ -0,0 +1,358 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {html} from 'lit';
+import {expect} from 'storybook/test';
+import './readout-list.js';
+import {
+  ReadoutListItemSize,
+  ReadoutListItemPriority,
+  ReadoutListItemDataQuality,
+  type ReadoutValueOptions,
+} 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';
+import {
+  ObcAlertFrameMode,
+  ObcAlertFrameType,
+} from '../../components/alert-frame/alert-frame.js';
+import {AlertType} from '../../types.js';
+
+type ListArgs = {
+  showDebugOverlay: boolean;
+};
+
+type Row = {
+  label: string;
+  value: number | null;
+  unit: string;
+  size?: ReadoutListItemSize;
+  hasDegree?: boolean;
+  fractionDigits?: number;
+  priority?: ReadoutListItemPriority;
+  hasSetpoint?: boolean;
+  setpoint?: number;
+  hasAdvice?: boolean;
+  advice?: number;
+  off?: boolean;
+  // Row-level and per-block state, so the list stories can smoke-test data
+  // quality + alert frames alongside the auto-alignment.
+  dataQuality?: ReadoutListItemDataQuality;
+  alert?: AlertFrameConfig;
+  valueDataQuality?: ReadoutListItemDataQuality;
+  valueAlert?: AlertFrameConfig;
+  setpointDataQuality?: ReadoutListItemDataQuality;
+};
+
+function renderRow(row: Row) {
+  const valueOptions =
+    row.valueDataQuality || row.valueAlert
+      ? {dataQuality: row.valueDataQuality, alert: row.valueAlert}
+      : undefined;
+  const setpointOptions = row.setpointDataQuality
+    ? {dataQuality: row.setpointDataQuality}
+    : undefined;
+  return html`
+    <obc-readout-list-item
+      .label=${row.label}
+      .unit=${row.unit}
+      .value=${row.value}
+      .size=${row.size ?? ReadoutListItemSize.small}
+      .hasDegree=${row.hasDegree ?? false}
+      .fractionDigits=${row.fractionDigits ?? 0}
+      .priority=${row.priority}
+      .off=${row.off ?? false}
+      .hasSetpoint=${row.hasSetpoint ?? false}
+      .setpoint=${row.setpoint}
+      .hasAdvice=${row.hasAdvice ?? false}
+      .advice=${row.advice}
+      .dataQuality=${row.dataQuality}
+      .alert=${row.alert ?? false}
+      .valueOptions=${valueOptions}
+      .setpointOptions=${setpointOptions}
+    ></obc-readout-list-item>
+  `;
+}
+
+function renderList(rows: Row[], showDebugOverlay: boolean) {
+  return html`
+    <div
+      data-obc-theme="day"
+      style="background: var(--container-background-color); padding: 16px; width: 360px; box-sizing: border-box;"
+    >
+      <obc-readout-list .showDebugOverlay=${showDebugOverlay}>
+        ${rows.map(renderRow)}
+      </obc-readout-list>
+    </div>
+  `;
+}
+
+const meta = {
+  title: 'Instruments/Readout List',
+  tags: ['autodocs', '6.0', 'wip'],
+  component: 'obc-readout-list',
+  args: {
+    showDebugOverlay: true,
+  },
+  argTypes: {
+    showDebugOverlay: {control: {type: 'boolean'}},
+  },
+} satisfies Meta<ListArgs>;
+
+export default meta;
+type Story = StoryObj<ListArgs>;
+
+const MIXED_ROWS: Row[] = [
+  {label: 'Temperature', value: 45, unit: 'C', hasDegree: true},
+  {label: 'Heading', value: 287, unit: 'T', hasDegree: true},
+  {label: 'Pressure', value: 1013, unit: 'Pa', fractionDigits: 1},
+  {label: 'Distance', value: 4.2, unit: 'miles', fractionDigits: 1},
+  {label: 'Speed', value: 18, unit: 'kn', fractionDigits: 1},
+];
+
+export const Default: Story = {
+  render: (args) => renderList(MIXED_ROWS, args.showDebugOverlay),
+};
+
+const DEGREE_ROWS: Row[] = [
+  {label: 'Heading', value: 287, unit: 'T', hasDegree: true},
+  {label: 'COG', value: 92, unit: 'T', hasDegree: true},
+  {label: 'Speed', value: 18, unit: 'kn'},
+  {label: 'Depth', value: 124, unit: 'm'},
+];
+
+export const Degrees: Story = {
+  render: (args) => renderList(DEGREE_ROWS, args.showDebugOverlay),
+};
+
+const WARNING_FRAME: AlertFrameConfig = {
+  status: AlertType.Warning,
+  mode: ObcAlertFrameMode.ackedActive,
+  type: ObcAlertFrameType.Regular,
+};
+const ALARM_FRAME_ICON: AlertFrameConfig = {
+  status: AlertType.Alarm,
+  mode: ObcAlertFrameMode.ackedActive,
+  type: ObcAlertFrameType.SmallSideFlip,
+  showAlertCategoryIcon: true,
+};
+
+export const WithSetpoints: Story = {
+  render: (args) =>
+    renderList(
+      [
+        {
+          label: 'Heading',
+          value: 287,
+          unit: 'T',
+          hasDegree: true,
+          hasSetpoint: true,
+          setpoint: 290,
+        },
+        // invalid setpoint chip — auto-aligned alongside the others
+        {
+          label: 'Speed',
+          value: 8,
+          unit: 'kn',
+          fractionDigits: 1,
+          hasSetpoint: true,
+          setpoint: 12,
+          setpointDataQuality: ReadoutListItemDataQuality.invalid,
+        },
+        // advice reference
+        {label: 'Depth', value: 1013, unit: 'm', hasAdvice: true, advice: 1010},
+        // per-value alert frame — wraps value + unit
+        {label: 'Fuel', value: 42, unit: '%', valueAlert: WARNING_FRAME},
+        // whole row invalid + null value (dash)
+        {
+          label: 'Wind',
+          value: null,
+          unit: 'kn',
+          dataQuality: ReadoutListItemDataQuality.invalid,
+        },
+        // whole row low-integrity + row-level alert frame with a badge-icon flap
+        {
+          label: 'Course',
+          value: 120,
+          unit: 'T',
+          hasDegree: true,
+          dataQuality: ReadoutListItemDataQuality.lowIntegrity,
+          alert: ALARM_FRAME_ICON,
+        },
+      ],
+      args.showDebugOverlay
+    ),
+};
+
+export const TestDynamicRow: Story = {
+  render: (args) => renderList(MIXED_ROWS, args.showDebugOverlay),
+  play: async ({canvasElement}) => {
+    const list = canvasElement.querySelector('obc-readout-list');
+    const row = document.createElement(
+      'obc-readout-list-item'
+    ) as HTMLElement & {
+      label: string;
+      value: number;
+      unit: string;
+      valueOptions?: ReadoutValueOptions;
+    };
+    row.label = 'Added';
+    row.value = 9;
+    row.unit = 'kn';
+    list?.appendChild(row);
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await expect(row.valueOptions?.spaceReserver).toBe('0000.0');
+  },
+};
+
+// Richer starting set for the interactive demo: a plain degree row, an invalid
+// setpoint, an advice reference, a per-value alert frame, a null/invalid row and
+// a low-integrity row with a row-level alert frame — so the manual add/remove /
+// re-align flow is exercised against the full range of state.
+const MANUAL_ROWS: Row[] = [
+  {label: 'Heading', value: 287, unit: 'T', hasDegree: true},
+  {
+    label: 'Speed',
+    value: 8,
+    unit: 'kn',
+    fractionDigits: 1,
+    hasSetpoint: true,
+    setpoint: 12,
+    setpointDataQuality: ReadoutListItemDataQuality.invalid,
+  },
+  {label: 'Depth', value: 1013, unit: 'm', hasAdvice: true, advice: 1010},
+  {label: 'Fuel', value: 42, unit: '%', valueAlert: WARNING_FRAME},
+  {
+    label: 'Wind',
+    value: null,
+    unit: 'kn',
+    dataQuality: ReadoutListItemDataQuality.invalid,
+  },
+  {
+    label: 'Course',
+    value: 120,
+    unit: 'T',
+    hasDegree: true,
+    dataQuality: ReadoutListItemDataQuality.lowIntegrity,
+    alert: ALARM_FRAME_ICON,
+  },
+];
+
+/**
+ * **Manual (Interactive)** — the rows are slotted children, so they cannot be
+ * driven by Storybook controls. Use the buttons to add / remove rows (a
+ * structural change the list re-aligns automatically) and to change the first
+ * row's value / unit (a property-only change, so it calls the public
+ * {@link ObcReadoutList.align} method). The debug overlay shows the reserved
+ * column widths reacting to each change. The starting rows include data-quality
+ * and alert-frame variations for a quick visual smoke test.
+ */
+export const Manual: Story = {
+  name: 'Manual (Interactive)',
+  tags: ['skip-test'],
+  render: (args) => html`
+    <div
+      data-obc-theme="day"
+      style="background: var(--container-background-color); padding: 16px; width: 380px; box-sizing: border-box; display: flex; flex-direction: column; gap: 16px;"
+    >
+      <div style="font-size: 14px; color: var(--element-neutral-color, #888);">
+        Rows are slotted children, so Storybook controls can't drive them. Use
+        the buttons to add / remove rows (the list re-aligns automatically) and
+        to change the first row's value / unit (a property-only change, so it
+        calls
+        <code>align()</code>). The debug overlay shows the reserved column
+        widths.
+      </div>
+      <obc-readout-list
+        id="manual-list"
+        .showDebugOverlay=${args.showDebugOverlay}
+      >
+        ${MANUAL_ROWS.map(renderRow)}
+      </obc-readout-list>
+      <div style="display: flex; gap: 8px; flex-wrap: wrap;">
+        <button id="m-add" style="padding: 6px 12px; cursor: pointer;">
+          Add row
+        </button>
+        <button id="m-remove" style="padding: 6px 12px; cursor: pointer;">
+          Remove row
+        </button>
+        <button id="m-bump" style="padding: 6px 12px; cursor: pointer;">
+          Bump first value ×10
+        </button>
+        <button id="m-unit" style="padding: 6px 12px; cursor: pointer;">
+          Toggle first unit
+        </button>
+      </div>
+      <div
+        id="m-status"
+        style="font: 12px/1.4 monospace; color: var(--element-neutral-color, #666);"
+      >
+        ${MANUAL_ROWS.length} rows
+      </div>
+    </div>
+  `,
+  play: async ({canvasElement}) => {
+    const list = canvasElement.querySelector('#manual-list') as
+      | (HTMLElement & {align: () => void})
+      | null;
+    const status = canvasElement.querySelector(
+      '#m-status'
+    ) as HTMLElement | null;
+    const addBtn = canvasElement.querySelector(
+      '#m-add'
+    ) as HTMLButtonElement | null;
+    const removeBtn = canvasElement.querySelector(
+      '#m-remove'
+    ) as HTMLButtonElement | null;
+    const bumpBtn = canvasElement.querySelector(
+      '#m-bump'
+    ) as HTMLButtonElement | null;
+    const unitBtn = canvasElement.querySelector(
+      '#m-unit'
+    ) as HTMLButtonElement | null;
+    if (!list || !status || !addBtn || !removeBtn || !bumpBtn || !unitBtn) {
+      return;
+    }
+
+    const UNITS = ['kn', 'm', 'C', 'miles'];
+    let added = 0;
+    const rows = () =>
+      Array.from(
+        list.querySelectorAll('obc-readout-list-item')
+      ) as (HTMLElement & {
+        value: number | null;
+        unit: string;
+      })[];
+    const refresh = () => {
+      status.textContent = `${rows().length} rows`;
+    };
+
+    addBtn.onclick = () => {
+      added += 1;
+      const row = document.createElement(
+        'obc-readout-list-item'
+      ) as HTMLElement & {label: string; value: number; unit: string};
+      row.label = `Row ${added}`;
+      row.value = added * 7;
+      row.unit = UNITS[added % UNITS.length];
+      list.appendChild(row);
+      refresh();
+    };
+    removeBtn.onclick = () => {
+      const all = rows();
+      all[all.length - 1]?.remove();
+      refresh();
+    };
+    bumpBtn.onclick = () => {
+      const first = rows()[0];
+      if (!first) return;
+      first.value = Math.round((first.value ?? 1) * 10);
+      list.align();
+    };
+    unitBtn.onclick = () => {
+      const first = rows()[0];
+      if (!first) return;
+      first.unit = first.unit === 'miles' ? 'T' : 'miles';
+      list.align();
+    };
+  },
+};

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

@@ -0,0 +1,216 @@
+import {LitElement, html, unsafeCSS, type PropertyValues} from 'lit';
+import {property} from 'lit/decorators.js';
+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';
+
+const ITEM_TAG = 'obc-readout-list-item';
+
+/** Child attributes whose change should re-trigger alignment (HTML-attribute usage). */
+const OBSERVED_ATTRIBUTES = [
+  'unit',
+  'src',
+  'value',
+  'setpoint',
+  'advice',
+  'max-digits',
+  'fraction-digits',
+  'has-degree',
+  'has-setpoint',
+  'has-advice',
+];
+
+/** 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)) {
+    return 0;
+  }
+  return String(Math.trunc(Math.abs(value))).length;
+}
+
+/**
+ * `<obc-readout-list>` – A container that groups `<obc-readout-list-item>` rows
+ * and **auto-aligns their columns**.
+ *
+ * Because each row is its own custom element, cross-row column alignment is not
+ * automatic. This container inspects its rows and pushes shared width reservers
+ * down so the unit column, the value / setpoint / advice columns and the source
+ * column all line up — the same effect the `Readout List Item → ColumnAlignment`
+ * story achieves by hand, done for you. Alignment is always on.
+ *
+ * What it equalizes — derived from each row's data and broadcast to every row, so
+ * the widest value / unit / source is never clipped:
+ * - **Unit:** the longest `unit` becomes every row's unit space-reserver.
+ * - **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.
+ * - **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
+ *   cleared once no degree rows remain.
+ *
+ * The list **owns** these reservers: it recomputes them from the rows' data on
+ * every pass (and clears stale reservers / spacers when rows change), so a
+ * `spaceReserver` set directly on a row inside the list is overwritten. Drive the
+ * data (`maxDigits` / `fractionDigits` / `unit` / `src`) rather than setting a
+ * manual reserver when a row lives in a list.
+ *
+ * Alignment runs on `slotchange` and on child mutations (added/removed rows and
+ * HTML-attribute changes). When rows are updated via JS **properties** only (no
+ * attribute/DOM mutation), call {@link align} to recompute.
+ *
+ * @experimental Pilot for the new primitives + per-block options Readout API; the
+ * API may change in a future release.
+ *
+ * @slot - The `<obc-readout-list-item>` rows.
+ *
+ * @csspart list - The vertical stack container.
+ */
+@customElement('obc-readout-list')
+export class ObcReadoutList extends LitElement {
+  /**
+   * Development aid: outline each row's readout building blocks (red), degree
+   * columns (blue) and degree spacer (green) so the reserved column widths are
+   * visible. Propagated to every row. Off by default.
+   */
+  @property({type: Boolean, reflect: true}) showDebugOverlay = false;
+
+  private mutationObserver?: MutationObserver;
+
+  protected override updated(changed: PropertyValues): void {
+    super.updated(changed);
+    // A host-property change is not seen by the child MutationObserver, so
+    // re-propagate `showDebugOverlay` (and re-align) when it toggles.
+    if (changed.has('showDebugOverlay')) {
+      this.align();
+    }
+  }
+
+  override disconnectedCallback(): void {
+    this.mutationObserver?.disconnect();
+    this.mutationObserver = undefined;
+    super.disconnectedCallback();
+  }
+
+  /** The `obc-readout-list-item` rows, including those nested in wrapper elements. */
+  private get items(): ObcReadoutListItem[] {
+    const slot = this.shadowRoot?.querySelector('slot');
+    const assigned = slot?.assignedElements({flatten: true}) ?? [];
+    return assigned.flatMap((el) =>
+      el.tagName.toLowerCase() === ITEM_TAG
+        ? [el as ObcReadoutListItem]
+        : Array.from(el.querySelectorAll<ObcReadoutListItem>(ITEM_TAG))
+    );
+  }
+
+  /**
+   * Recompute and apply the shared column reservers across all rows. Call this
+   * after updating rows via JS properties only (attribute/DOM changes are picked
+   * up automatically).
+   */
+  align(): void {
+    const items = this.items;
+    if (items.length === 0) {
+      return;
+    }
+
+    let maxIntegerDigits = 0;
+    let maxFractionDigits = 0;
+    let longestUnit = '';
+    let longestSrc = '';
+    let anyDegree = false;
+
+    for (const item of items) {
+      maxFractionDigits = Math.max(maxFractionDigits, item.fractionDigits ?? 0);
+      maxIntegerDigits = Math.max(
+        maxIntegerDigits,
+        item.maxDigits ?? 0,
+        integerDigitCount(item.value),
+        item.hasSetpoint ? integerDigitCount(item.setpoint) : 0,
+        item.hasAdvice ? integerDigitCount(item.advice) : 0
+      );
+      if (item.unit && item.unit.length > longestUnit.length) {
+        longestUnit = item.unit;
+      }
+      if (item.src && item.src.length > longestSrc.length) {
+        longestSrc = item.src;
+      }
+      if (item.hasDegree) {
+        anyDegree = true;
+      }
+    }
+
+    const numericReserver =
+      maxIntegerDigits > 0
+        ? '0'.repeat(maxIntegerDigits) +
+          (maxFractionDigits > 0 ? `.${'0'.repeat(maxFractionDigits)}` : '')
+        : undefined;
+
+    // Our writes are properties (no reflected attributes), so they do not trigger
+    // the MutationObserver; disconnecting around them is belt-and-suspenders.
+    this.mutationObserver?.disconnect();
+    for (const item of items) {
+      // 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.
+      item.valueOptions = {
+        ...item.valueOptions,
+        spaceReserver: numericReserver,
+      };
+      item.setpointOptions = {
+        ...item.setpointOptions,
+        spaceReserver: numericReserver,
+      };
+      item.adviceOptions = {
+        ...item.adviceOptions,
+        spaceReserver: numericReserver,
+      };
+      item.unitOptions = {
+        ...item.unitOptions,
+        spaceReserver: longestUnit || undefined,
+      };
+      item.srcOptions = {
+        ...item.srcOptions,
+        spaceReserver: longestSrc || undefined,
+      };
+      item.hasDegreeSpacer = anyDegree && !item.hasDegree;
+      item.showDebugOverlay = this.showDebugOverlay;
+    }
+    this.observeChildren();
+  }
+
+  private observeChildren(): void {
+    if (!this.mutationObserver) {
+      this.mutationObserver = new MutationObserver(() => this.align());
+    }
+    this.mutationObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES,
+    });
+  }
+
+  private handleSlotChange = (): void => {
+    this.align();
+    this.observeChildren();
+  };
+
+  override render() {
+    return html`
+      <div class="list" part="list">
+        <slot @slotchange=${this.handleSlotChange}></slot>
+      </div>
+    `;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-readout-list': ObcReadoutList;
+  }
+}