@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.96 → 2.0.0-next.98

package/script/check-slot-event-docs.ts

@@ -0,0 +1,353 @@
+/**
+ * @module SlotEventDocAudit
+ * @description
+ * Audits every registered web component (`@customElement`) so that its rendered
+ * `<slot>` elements and dispatched custom events are declared with matching
+ * `@slot` / `@fires` JSDoc tags on the class.
+ *
+ * Why this matters: `custom-elements.json` is generated by `cem analyze`, which
+ * discovers slots and events **only** from `@slot` / `@fires` JSDoc tags — never
+ * from the template or from `dispatchEvent(...)` calls. If a component renders a
+ * `<slot name="leading-icon">` but forgets the `@slot leading-icon` tag, the slot
+ * is invisible to the manifest and therefore to every downstream consumer (the
+ * framework wrappers, IDE autocomplete, Storybook autodocs, code playgrounds).
+ * A `@slot`/`@fires` tag that has no counterpart in the template/code produces the
+ * opposite problem: a phantom control that does nothing. See issue #1033.
+ *
+ * The checks are intentionally conservative to stay false-positive-free in CI:
+ *
+ * - **Missing slot (error):** a *static* `<slot name="literal">` or a *bare*
+ *   default `<slot>` with no matching `@slot` tag. Slots rendered by an inherited
+ *   base class live in the base file, so subclasses are never falsely flagged.
+ * - **Missing event (error):** a literal `new CustomEvent('name')` /
+ *   `new Event('name')` with no matching `@fires`/`@event name` tag.
+ * - **Phantom slot (error):** a `@slot name` tag with no matching static
+ *   `<slot name="name">` element — only evaluated for files that `extends
+ *   LitElement` directly and contain no dynamic `<slot name="${…}">`, so
+ *   inheritance- and dynamic-name-based false positives are skipped. A
+ *   `slot="name"` *projection attribute* in the template does NOT suppress this
+ *   (it exposes nothing); only a genuine imperative read of the consumer's
+ *   children (e.g. `getAttribute('slot') === 'name'`) counts as a real slot.
+ * - **Empty description (warning):** a `@slot`/`@fires` tag with only a name and
+ *   no descriptive text. These become blank cells in the manifest / Storybook
+ *   controls; warnings do not fail CI.
+ *
+ * There is deliberately no phantom-`@fires` *error*: unlike slots (which must be
+ * a `<slot>` element in the component's own shadow DOM), a documented event may
+ * legitimately originate elsewhere — a native event bubbling from an inner
+ * element (`click`, `blur`), or an event re-fired by a child — so "documented
+ * but not locally dispatched" is not, on its own, a defect.
+ *
+ * Dynamic slot names (`<slot name="${expr}">` or `<slot name="pre-${id}-post">`)
+ * are skipped for the missing-slot check because their concrete names cannot be
+ * known statically; document them with a placeholder tag such as
+ * `@slot tab-<id>-icon` (see .cursor/rules/comments.mdc § Structured-tag rules).
+ *
+ * Usage:
+ * ```bash
+ * npm run lint:slots
+ * tsx script/check-slot-event-docs.ts
+ * ```
+ *
+ * Exits with code 1 when any error-level finding is present, suitable for CI.
+ *
+ * Note: standalone script; exports nothing. Regex-based like the sibling
+ * `check-css-*` audits — it does not build a full AST.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {globby} from 'globby';
+
+interface Finding {
+  file: string;
+  message: string;
+}
+
+/** Remove block and line comments so template scans ignore commented-out code. */
+function stripComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+/** Static exposed slot names (`<slot name="literal">`, no interpolation). */
+function findStaticSlots(code: string): Set<string> {
+  const slots = new Set<string>();
+  const re = /<slot\b([^>]*)>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(code)) !== null) {
+    const attrs = m[1];
+    const nameMatch = /\bname\s*=\s*["']([^"']*)["']/.exec(attrs);
+    if (!nameMatch) continue; // bare/default slot handled separately
+    const name = nameMatch[1];
+    if (name.includes('${')) continue; // dynamic — cannot resolve statically
+    slots.add(name);
+  }
+  return slots;
+}
+
+/** True when the template renders a bare default `<slot>` (no `name` attribute). */
+function hasDefaultSlot(code: string): boolean {
+  const re = /<slot\b([^>]*)>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(code)) !== null) {
+    if (!/\bname\s*=/.test(m[1])) return true;
+  }
+  return false;
+}
+
+/** True when any `<slot name="${…}">` uses an interpolated (dynamic) name. */
+function hasDynamicSlot(code: string): boolean {
+  const re = /<slot\b([^>]*)>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(code)) !== null) {
+    const nameMatch = /\bname\s*=\s*(?:["'][^"']*["']|`[^`]*`|[^\s>]+)/.exec(
+      m[1]
+    );
+    if (nameMatch && nameMatch[0].includes('${')) return true;
+  }
+  return false;
+}
+
+/**
+ * Literal event names the host itself dispatches:
+ * `this.dispatchEvent(new CustomEvent('name'…))`. Restricted to `this.` so
+ * events re-dispatched on inner child elements (e.g. a native `<input>`) are
+ * not mistaken for the component's own public API.
+ */
+function findDispatchedEvents(code: string): Set<string> {
+  const events = new Set<string>();
+  const re =
+    /this\.dispatchEvent\(\s*new\s+(?:Custom)?Event\s*\(\s*['"]([^'"]+)['"]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(code)) !== null) events.add(m[1]);
+  return events;
+}
+
+/** Documented slot names from `@slot name` tags (`-` denotes the default slot). */
+function findDocumentedSlots(source: string): {
+  names: Set<string>;
+  hasDefault: boolean;
+} {
+  const names = new Set<string>();
+  let hasDefault = false;
+  const re = /@slot\s+(\S+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    if (m[1] === '-') hasDefault = true;
+    else names.add(m[1]);
+  }
+  return {names, hasDefault};
+}
+
+/** Documented event names from `@fires name` / `@event name` tags. */
+function findDocumentedEvents(source: string): Set<string> {
+  const names = new Set<string>();
+  // Accept both tag orders: `@fires name {Type}` and `@fires {Type} name`.
+  // The optional leading `{Type}` may contain one level of nested braces,
+  // e.g. `{CustomEvent<{date: Date}>}`.
+  const re = /@(?:fires|event)\s+(?:\{(?:[^{}]|\{[^{}]*\})*\}\s+)?(\S+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) names.add(m[1]);
+  return names;
+}
+
+interface TagDoc {
+  name: string;
+  hasDescription: boolean;
+}
+
+/** A plausible slot/event name (identifier or kebab-case), or `-` for default. */
+function isValidTagName(name: string): boolean {
+  return name === '-' || /^[A-Za-z][\w-]*$/.test(name);
+}
+
+/** Parse `@slot` tags into name + whether descriptive text follows. */
+function parseSlotTags(source: string): TagDoc[] {
+  const out: TagDoc[] = [];
+  const re = /@slot[ \t]+(\S+)([^\n]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    if (!isValidTagName(m[1])) continue;
+    const rest = m[2].replace(/^\s*-\s*/, '').trim();
+    out.push({name: m[1], hasDescription: rest.length > 0});
+  }
+  return out;
+}
+
+/**
+ * Parse `@fires` / `@event` tags into name + whether descriptive text follows,
+ * tolerating a leading or trailing `{Type}` (with one level of nested braces).
+ */
+function parseEventTags(source: string): TagDoc[] {
+  const out: TagDoc[] = [];
+  const type = '\\{(?:[^{}]|\\{[^{}]*\\})*\\}';
+  const re = new RegExp(
+    `@(?:fires|event)[ \\t]+(?:${type}[ \\t]+)?(\\S+)([^\\n]*)`,
+    'g'
+  );
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    if (!isValidTagName(m[1])) continue;
+    const rest = m[2]
+      .replace(new RegExp(`^\\s*${type}\\s*`), '')
+      .replace(/^\s*-\s*/, '')
+      .trim();
+    out.push({name: m[1], hasDescription: rest.length > 0});
+  }
+  return out;
+}
+
+/** Whether the class extends `LitElement` directly (not a base class or mixin). */
+function extendsLitElementDirectly(source: string): boolean {
+  return /class\s+\w+\s+extends\s+LitElement\b/.test(source);
+}
+
+/** Whether the (comment-stripped) code references `name` as a string literal. */
+function referencesNameAsString(code: string, name: string): boolean {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`['"\`]${escaped}['"\`]`).test(code);
+}
+
+async function run(): Promise<void> {
+  const cwd = process.cwd();
+  const files = await globby(['src/**/*.ts'], {
+    cwd,
+    ignore: ['src/**/*.stories.ts', 'src/icons/**'],
+  });
+
+  const errors: Finding[] = [];
+  const warnings: Finding[] = [];
+  let componentCount = 0;
+
+  for (const rel of files.sort()) {
+    const source = fs.readFileSync(path.join(cwd, rel), 'utf8');
+    if (!/@customElement\(/.test(source)) continue;
+    componentCount++;
+
+    const code = stripComments(source);
+    const staticSlots = findStaticSlots(code);
+    const defaultSlot = hasDefaultSlot(code);
+    const dynamicSlot = hasDynamicSlot(code);
+    const events = findDispatchedEvents(code);
+
+    const docSlots = findDocumentedSlots(source);
+    const docEvents = findDocumentedEvents(source);
+
+    // Missing @slot for static exposed slots.
+    for (const name of staticSlots) {
+      if (!docSlots.names.has(name)) {
+        errors.push({
+          file: rel,
+          message: `renders <slot name="${name}"> but has no matching @slot ${name} tag`,
+        });
+      }
+    }
+
+    // Missing @slot - for a bare default slot.
+    if (defaultSlot && !docSlots.hasDefault) {
+      errors.push({
+        file: rel,
+        message: `renders a default <slot> but has no matching "@slot -" tag`,
+      });
+    }
+
+    // Missing @fires for dispatched custom events.
+    for (const name of events) {
+      if (!docEvents.has(name)) {
+        errors.push({
+          file: rel,
+          message: `dispatches CustomEvent('${name}') but has no matching @fires ${name} tag`,
+        });
+      }
+    }
+
+    // Phantom @slot — only for direct LitElement subclasses without dynamic
+    // slot names, so inherited/dynamic slots never produce false positives.
+    if (extendsLitElementDirectly(source) && !dynamicSlot) {
+      // A `slot="name"` attribute in the template is a *projection into a child*
+      // — it exposes nothing and must NOT suppress the phantom warning. Strip
+      // those before the string-literal check so only genuine imperative reads
+      // (e.g. `getAttribute('slot') === 'header'`, which relocate the consumer's
+      // `slot="name"` children) count as a real, if non-declarative, slot.
+      const codeNoProjections = code.replace(
+        /\bslot\s*=\s*["'][^"']*["']/g,
+        ' '
+      );
+      for (const name of docSlots.names) {
+        if (name.includes('<') || name.includes('${')) continue; // placeholder
+        if (staticSlots.has(name)) continue; // rendered as a real <slot>
+        if (referencesNameAsString(codeNoProjections, name)) continue;
+        errors.push({
+          file: rel,
+          message: `documents @slot ${name} but renders no <slot name="${name}"> (phantom — likely a slot="${name}" projection into a child)`,
+        });
+      }
+    }
+
+    // Empty description (warning) — a @slot/@fires tag with only a name produces
+    // a blank cell in the manifest / Storybook controls.
+    for (const tag of parseSlotTags(source)) {
+      if (!tag.hasDescription) {
+        const label = tag.name === '-' ? 'default slot' : `@slot ${tag.name}`;
+        warnings.push({file: rel, message: `${label} has no description`});
+      }
+    }
+    for (const tag of parseEventTags(source)) {
+      if (!tag.hasDescription) {
+        warnings.push({
+          file: rel,
+          message: `@fires ${tag.name} has no description`,
+        });
+      }
+    }
+  }
+
+  console.log('Slot & event documentation audit');
+  console.log(`Scanned ${componentCount} registered components under src/`);
+
+  const printByFile = (
+    findings: Finding[],
+    log: (msg: string) => void,
+    indent = '    '
+  ) => {
+    const byFile = new Map<string, string[]>();
+    for (const f of findings) {
+      if (!byFile.has(f.file)) byFile.set(f.file, []);
+      byFile.get(f.file)!.push(f.message);
+    }
+    for (const [file, messages] of [...byFile.entries()].sort()) {
+      log(`\n  ${file}`);
+      for (const msg of messages) log(`${indent}- ${msg}`);
+    }
+  };
+
+  if (warnings.length > 0) {
+    console.warn(
+      `\n⚠️  ${warnings.length} empty-description warning(s) (non-blocking):`
+    );
+    printByFile(warnings, (m) => console.warn(m));
+  }
+
+  if (errors.length > 0) {
+    console.error(`\nFound ${errors.length} issue(s):`);
+    printByFile(errors, (m) => console.error(m));
+    console.error(
+      `\n❌ Slot & event documentation audit failed. Add the missing @slot/@fires ` +
+        `tags (or remove the phantom ones). See .cursor/rules/comments.mdc.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const suffix =
+    warnings.length > 0 ? ` (${warnings.length} non-blocking warning(s))` : '';
+  console.log(`\n✅ Slot & event documentation audit passed.${suffix}`);
+}
+
+run().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`❌ Slot & event documentation audit failed: ${message}`);
+  process.exitCode = 1;
+});

package/src/ar/poi/poi.ts

@@ -164,7 +164,8 @@ const POINT_POINTER_OFFSET_PX = 12;
  * ## Slots/Content
  *
  * - Default slot: Main icon/content rendered inside `obc-poi-button`.
- * - `header`: Optional custom header content rendered above the POI object.
+ * - `button`: Optional custom button element replacing the default `obc-poi-button`.
+ * - `header`: Optional header content. Relocated into the inner `obc-poi-button` at runtime by a `MutationObserver` (there is no `<slot name="header">` element).
  *
  * ## Events
  *
@@ -185,7 +186,8 @@ const POINT_POINTER_OFFSET_PX = 12;
  * ```
  *
  * @slot - Default POI button content.
- * @slot header - Optional custom header content.
+ * @slot button - Optional custom button element replacing the default `obc-poi-button`.
+ * @slot header - Optional header content, relocated into the inner `obc-poi-button` at runtime.
  * @experimental
  */
 @customElement('obc-poi')

package/src/ar/poi-layer/poi-layer.ts

@@ -90,6 +90,7 @@ export enum OverlapMode {
  *
  * @slot - Default slot for POI targets and optional POI groups.
  * @fires layer-resize {CustomEvent<{height:number,label:string}>} Fired when the layer height changes.
+ * @fires layer-selection-changed {Event} Fired when the layer's `isSelected` state changes. Bubbles.
  * @experimental
  */
 @customElement('obc-poi-layer')

package/src/ar/poi-object/poi-object-aton.ts

@@ -29,6 +29,7 @@ export enum ObcPoiObjectAtonStyle {
 export {ObcPoiObjectState as ObcPoiObjectAtonState};
 
 /**
+ * @slot - Icon content rendered inside the POI object.
  * @experimental
  */
 @customElement('obc-poi-object-aton')

package/src/automation/automation-badge/automation-badge.ts

@@ -51,6 +51,8 @@ const ALERT_BADGE_TYPES: ObcAutomationBadgeType[] = [
 ];
 
 /**
+ * @slot icon-silhouette - Custom silhouette/outline icon, rendered behind the default slot content when no built-in badge type matches.
+ * @slot - Default slot for custom badge content, rendered when no built-in badge type matches.
  * @stable
  */
 @customElement('obc-automation-badge')

package/src/automation/automation-button/automation-button.ts

@@ -97,6 +97,15 @@ export enum AutomationButtonPositioning {
 }
 
 /**
+ * @slot badge-top-right - Content projected into the top-right badge position of the button.
+ * @slot badge-top-left - Content projected into the top-left badge position of the button.
+ * @slot badge-bottom-left - Content projected into the bottom-left badge position of the button.
+ * @slot badge-bottom-right - Content projected into the bottom-right badge position of the button.
+ * @slot icon - Primary icon shown inside the button (regular, double, flat and square variants).
+ * @slot icon-silhouette - Silhouette/outline icon shown behind the primary icon (flat variant only).
+ * @slot alert-icon - Custom icon for the alert frame, shown when alert==true and positioning=="point".
+ * @slot alert-label - Label for the alert frame, shown when alert==true and positioning=="point".
+ * @slot alert-timer - Timer for the alert frame, shown when alert==true and positioning=="point".
  * @stable
  */
 @customElement('obc-automation-button')

package/src/automation/automation-input-modal/automation-input-modal.ts

@@ -3,6 +3,10 @@ import {LitElement, html, unsafeCSS} from 'lit';
 import compentStyle from './automation-input-modal.css?inline';
 
 /**
+ * @slot header - Header content shown at the top of the modal.
+ * @slot preview - Preview content shown in the body of the modal.
+ * @slot action-primary - Primary action control shown in the actions row.
+ * @slot action-secondary - Secondary action control shown in the actions row.
  * @experimental
  */
 @customElement('obc-automation-input-modal')

package/src/automation/automation-tank/automation-tank.css

@@ -488,70 +488,14 @@
   margin-top: 8px;
 }
 
-.rich {
-  display: grid;
-  /* label takes remaining space; value (right-aligned) and suffix
-   * (left-aligned) form fixed content columns so digit right edges and
-   * suffix left edges align vertically across all rows. */
-  grid-template-columns: 1fr auto auto;
-  align-items: baseline;
-  row-gap: 4px;
-  padding-top: 8px;
-  white-space: nowrap;
-  @mixin font-instrument-unit;
-}
-
-.rich-row {
-  display: grid;
-  grid-template-columns: subgrid;
-  grid-column: 1 / -1;
-  align-items: baseline;
-  padding-left: var(
-    --instrument-components-readout-new-list-item-regular-container-padding-horizontal
-  );
-  padding-right: var(
-    --instrument-components-readout-new-list-item-regular-container-padding-horizontal
-  );
-}
-
-.rich-label {
-  @mixin font-instrument-label;
-  color: var(--element-inactive-color);
-  padding-right: 8px;
-  text-align: left;
-}
-
-.rich-value {
-  @mixin font-instrument-value-regular-neutral;
-  color: var(--element-neutral-color);
-  font-variant-numeric: tabular-nums;
-  text-align: right;
-}
-
-.rich-suffix {
-  display: inline-flex;
-  align-items: baseline;
-  /* Default 2px gap between value and unit when there is no degree/percent
-   * glyph. When a glyph is present it sits flush against the value and the
-   * unit follows flush after the glyph (see `.rich-glyph + .rich-unit`). */
-  padding-left: 2px;
-}
-
-.rich-suffix:has(.rich-glyph) {
-  padding-left: 0;
-}
-
-.rich-glyph {
-  @mixin font-instrument-value-regular-neutral;
-  color: var(--element-neutral-color);
-}
-
-.rich-unit {
-  color: var(--element-inactive-color);
-}
-
-.rich-glyph + .rich-unit {
-  padding-left: 0;
+/* Rich detail rows are consumer-slotted into `slot="rich"` — canonical usage is
+ * an `<obc-readout-list>` of `<obc-readout-list-item>` rows, which owns its own
+ * cap-height (textbox) typography and cross-row column alignment. The tank only
+ * spaces the slotted content below the divider; the divider itself is shown only
+ * when the slot is filled (`?hidden` bound to `_hasRichSlot`). */
+::slotted(obc-readout-list) {
+  display: block;
+  margin-top: 8px;
 }
 
 /* The chart cell is a plain sizing/clipping box. Both child renderers —

package/src/automation/automation-tank/automation-tank.stories.ts

@@ -6,10 +6,11 @@ import {
   TankPositioning,
   TankTrend,
   TankType,
-  type TankReadoutItem,
 } from './automation-tank.js';
 import './automation-tank.js';
-import {html} from 'lit';
+import '../../navigation-instruments/readout-list/readout-list.js';
+import '../../navigation-instruments/readout-list-item/readout-list-item.js';
+import {html, nothing} from 'lit';
 import {crossDecorator} from '../../storybook-util.js';
 import {AdviceType} from '../../navigation-instruments/watch/advice.js';
 import type {LinearAdvice} from '../../building-blocks/instrument-linear/advice.js';
@@ -57,13 +58,37 @@ const SAMPLE_ADVICE: LinearAdvice[] = [
   {min: 7500, max: 9000, type: AdviceType.advice, hinted: false},
 ];
 
-const SAMPLE_READOUT: TankReadoutItem[] = [
-  {label: 'Temperature', value: 45, hasDegree: true, unit: 'C'},
-  {label: 'Pressure', value: 45, unit: 'Pa'},
-  {label: 'Flow speed', value: 45, unit: 'm/s'},
-];
+// Canonical rich-detail content for the tank: an `<obc-readout-list>` of
+// `<obc-readout-list-item>` rows slotted into `slot="rich"`. The list owns the
+// cross-row column alignment and cap-height typography, replacing the tank's
+// former hand-rolled `.rich` grid.
+const renderRichReadout = () => html`
+  <obc-readout-list slot="rich">
+    <obc-readout-list-item
+      .label=${'Temperature'}
+      .value=${45}
+      .hasDegree=${true}
+      .unit=${'C'}
+    ></obc-readout-list-item>
+    <obc-readout-list-item
+      .label=${'Pressure'}
+      .value=${45}
+      .unit=${'Pa'}
+    ></obc-readout-list-item>
+    <obc-readout-list-item
+      .label=${'Flow speed'}
+      .value=${45}
+      .unit=${'m/s'}
+    ></obc-readout-list-item>
+  </obc-readout-list>
+`;
 
-const renderTank = (args: StoryArgs) => html`
+// `richReadout` is slotted into `slot="rich"`; defaults to `nothing` so most
+// stories render no detail rows. Kept as a separate helper (not the meta
+// `render`) because Storybook calls `render(args, context)` with a second
+// argument — `renderTank` below wraps it so that extra arg can't leak in as
+// slotted content.
+const renderTankEl = (args: StoryArgs, richReadout: unknown = nothing) => html`
   <obc-automation-tank
     .value=${args.value}
     .max=${args.max}
@@ -82,7 +107,6 @@ const renderTank = (args: StoryArgs) => html`
     .hasGraphIcon=${args.hasGraphIcon}
     .showTrendSymbol=${args.showTrendSymbol}
     .percentFractionDigits=${args.percentFractionDigits}
-    .readout=${args.readout}
     ?alert=${args.alert}
     .alertFrameType=${args.alertFrameType}
     .alertFrameThickness=${args.alertFrameThickness}
@@ -95,9 +119,12 @@ const renderTank = (args: StoryArgs) => html`
     .badgeCommandLocked=${args.badgeCommandLocked}
     .priority=${args.priority}
   >
+    ${richReadout}
   </obc-automation-tank>
 `;
 
+const renderTank = (args: StoryArgs) => renderTankEl(args);
+
 const meta: Meta<StoryArgs> = {
   title: 'Automation/Tanks/Tank',
   tags: ['autodocs', '6.0'],
@@ -120,7 +147,6 @@ const meta: Meta<StoryArgs> = {
     hasGraphIcon: false,
     showTrendSymbol: true,
     percentFractionDigits: 0,
-    readout: [],
     alert: false,
     alertFrameType: ObcAlertFrameType.SmallSideFlip,
     alertFrameThickness: ObcAlertFrameThickness.Small,
@@ -193,11 +219,6 @@ const meta: Meta<StoryArgs> = {
       description:
         'Advice overlay bands. `min`/`max` are in the same units as `max`. Toggle visibility with `hasAdvice`. Works in all three `chartMode` variants — `bar` overlays advice pills on the static bar, `graph` and `graph-and-bar` forward them to the embedded `obc-gauge-trend`.',
     },
-    readout: {
-      control: {type: 'object'},
-      description:
-        'Rich detail rows shown below the main percent/value block in the regular (non-compact, non-static) layout, separated by a divider. Each row: `{label, value, hasDegree?, hasPercentage?, unit}`. Empty array — nothing is rendered. Values use `percentFractionDigits` for formatting. Override the whole block via `slot="rich"`.',
-    },
     badgeControl: {
       options: Object.values(AutomationButtonBadgeControl),
       control: {type: 'select'},
@@ -405,8 +426,8 @@ export const Rich: Story = {
   args: {
     type: TankType.atmospheric,
     chartMode: TankChartMode.graphAndBar,
-    readout: SAMPLE_READOUT,
   },
+  render: (args) => renderTankEl(args, renderRichReadout()),
 };
 
 export const HorizontalRich: Story = {
@@ -414,8 +435,8 @@ export const HorizontalRich: Story = {
     type: TankType.atmospheric,
     orientation: TankOrientation.horizontal,
     chartMode: TankChartMode.graphAndBar,
-    readout: SAMPLE_READOUT,
   },
+  render: (args) => renderTankEl(args, renderRichReadout()),
 };
 
 /**
@@ -431,9 +452,9 @@ export const HorizontalRich: Story = {
  * and always render it as an integer to keep their fixed-width footprint
  * stable, so fraction-digit control only applies to the non-compact layout.
  *
- * `percentFractionDigits` is also applied uniformly to every row of the
- * `readout` rich list (see the `Rich` story) — all rows share one digit
- * count so the right-aligned numeric column stays visually consistent.
+ * The rich detail rows are now consumer-slotted (`slot="rich"`, canonically an
+ * `<obc-readout-list>`); each `<obc-readout-list-item>` owns its own
+ * `fractionDigits`, so `percentFractionDigits` no longer affects them.
  */
 export const WithFractionDigits: Story = {
   args: {
@@ -463,7 +484,6 @@ export const WithFractionDigits: Story = {
       .showTrendSymbol=${args.showTrendSymbol}
       .priority=${args.priority}
       .percentFractionDigits=${args.percentFractionDigits}
-      .readout=${args.readout}
     >
       <span slot="current-value">${args.value.toFixed(2)}</span>
       <span slot="max-value">${args.max.toFixed(2)}</span>
@@ -502,7 +522,6 @@ export const WithAlertAlarm: Story = {
       .hasGraphIcon=${args.hasGraphIcon}
       .showTrendSymbol=${args.showTrendSymbol}
       .percentFractionDigits=${args.percentFractionDigits}
-      .readout=${args.readout}
       ?alert=${args.alert}
       .alertFrameType=${args.alertFrameType}
       .alertFrameThickness=${args.alertFrameThickness}
@@ -625,7 +644,6 @@ export const Responsive: Story = {
           .hasGraphIcon=${args.hasGraphIcon}
           .showTrendSymbol=${args.showTrendSymbol}
           .percentFractionDigits=${args.percentFractionDigits}
-          .readout=${args.readout}
           ?alert=${args.alert}
           .alertFrameType=${args.alertFrameType}
           .alertFrameThickness=${args.alertFrameThickness}