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

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/building-blocks/alert-list/alert-list.ts

@@ -7,6 +7,10 @@ import {ObcScrollbar} from '../../components/scrollbar/scrollbar.js';
 import {ObcAlertMenuItem} from '../../components/alert-menu-item/alert-menu-item.js';
 
 /**
+ * @slot - Default slot for the alert list items.
+ * @slot empty-icon - Icon shown when the list is empty.
+ * @slot empty-title - Title shown when the list is empty.
+ * @slot empty-description - Description shown when the list is empty.
  * @stable
  */
 @customElement('obc-alert-list')

package/src/building-blocks/bar-horizontal/bar-horizontal.ts

@@ -63,6 +63,8 @@ export {
  * Set `priority` to `Priority.enhanced` to use the blue/enhanced color palette
  * for bar fill and setpoint instead of the default gray/regular palette
  * (default: `Priority.regular`).
+ *
+ * @fires scale-dimensions-changed {CustomEvent} Fired when the scale's computed layout thickness changes; a parent chart listens for this to reserve space for the scale. Bubbles and is composed.
  * @beta
  */
 @customElement('obc-bar-horizontal')

package/src/building-blocks/bar-vertical/bar-vertical.ts

@@ -61,6 +61,8 @@ export {
  * Set `priority` to `Priority.enhanced` to use the blue/enhanced color palette
  * for bar fill and setpoint instead of the default gray/regular palette
  * (default: `Priority.regular`).
+ *
+ * @fires scale-dimensions-changed {CustomEvent} Fired when the scale's computed layout thickness changes; a parent chart listens for this to reserve space for the scale. Bubbles and is composed.
  * @beta
  */
 @customElement('obc-bar-vertical')

package/src/components/advice-floating-item/advice-floating-item.ts

@@ -43,8 +43,7 @@ import {
  * ## Slots
  * | Slot Name      | Renders When...                      | Purpose                                                      |
  * | -------------- | ------------------------------------ | ------------------------------------------------------------ |
- * | primary-icon   | Always (unless overridden)           | Main advice icon (default: `<obi-notification-advice-active>`) or custom icon. |
- * | secondary-icon | Only when `type="application"`       | Additional icon for application-type advice messages.         |
+ * | primary-icon   | Only when `type="application"`       | Custom main icon (the built-in advice icon is used otherwise). |
  * | title          | Always                               | Title or heading of the advice message.                      |
  * | description    | Always                               | Detailed advice or message text.                             |
  * | time           | If `hasTimestamp` is true            | Timestamp label (e.g., "09:12:46").                          |
@@ -75,8 +74,7 @@ import {
  * </obc-advice-floating-item>
  * ```
  *
- * @slot primary-icon - Main advice icon (default: `<obi-notification-advice-active>`), or custom icon.
- * @slot secondary-icon - Additional icon for application-type advice messages.
+ * @slot primary-icon - Custom main icon, projected into the child only when `type="application"` (the built-in advice icon is used otherwise).
  * @slot title - Title or heading of the advice message.
  * @slot description - Detailed advice or message text.
  * @slot time - Timestamp label (e.g., "09:12:46").

package/src/components/advice-message-item/advice-message-item.ts

@@ -62,17 +62,12 @@ export enum ObcAdviceMessageItemSize {
  * ---
  *
  * ### Slots
- * | Slot Name         | Renders When...                                 | Purpose                                                      |
- * |-------------------|------------------------------------------------|--------------------------------------------------------------|
- * | `primary-icon`    | Always                                          | Main icon representing the advice (default: advice icon).    |
- * | `secondary-icon`  | `hasSecondaryIcon` is true                     | Optional overlay icon for additional status or category.      |
- * | `title`           | `hasTitle` is true and `title` is set          | Title or heading of the advice message.                      |
- * | `description`     | `hasDescription` is true and `description` set | Detailed message text.                                       |
- * | `time`            | `hasTimestamp` is true and `time` is set       | Primary timestamp (e.g., time of advice).                    |
- * | `time-secondary`  | `hasTimestamp2` is true and `timeSecondary` set| Secondary timestamp (e.g., duration, relative time).         |
- * | `action-text`     | `type="with-button"`                           | Label for the primary action button.                         |
- * | `action-icon`     | `type="with-icon-button"`                      | Icon for the action button (default: close icon).            |
- * | `empty`           | `type="inactive"` or `empty` is true           | Text to display in the empty/inactive state.                 |
+ * | Slot Name         | Renders When...            | Purpose                                                  |
+ * |-------------------|----------------------------|----------------------------------------------------------|
+ * | `secondary-icon`  | `hasSecondaryIcon` is true | Optional overlay icon for additional status or category. |
+ *
+ * All other content (title, description, timestamps, action label/icon, empty-state
+ * text) is driven by properties and rendered internally; it is not exposed as slots.
  *
  * ---
  *
@@ -104,15 +99,7 @@ export enum ObcAdviceMessageItemSize {
  *
  * In this example, the advice message displays a title, description, timestamp, and a "View" action button.
  *
- * @slot primary-icon - Main icon representing the advice (always present)
  * @slot secondary-icon - Optional overlay icon for additional status/category (shown when `hasSecondaryIcon` is true)
- * @slot title - Title or heading of the advice (shown when `hasTitle` is true)
- * @slot description - Detailed message text (shown when `hasDescription` is true)
- * @slot time - Primary timestamp (shown when `hasTimestamp` is true)
- * @slot time-secondary - Secondary timestamp (shown when `hasTimestamp2` is true)
- * @slot action-text - Label for the action button (when `type="with-button"`)
- * @slot action-icon - Icon for the action button (when `type="with-icon-button"`)
- * @slot empty - Text to display in the empty/inactive state (when `type="inactive"` or `empty` is true)
  * @fires message-click {CustomEvent<void>} When the main message area is clicked
  * @fires action-click {CustomEvent<void>} When the action button (text or icon) is clicked
  * @beta

package/src/components/alert-floating-item/alert-floating-item.ts

@@ -12,6 +12,18 @@ import {
 } from '../floating-item/floating-item.js';
 
 /**
+ * `<obc-alert-floating-item>` – A floating alert message that overlays the interface with a built-in alert icon.
+ *
+ * @slot primary-icon - Custom main icon, projected into the child only when `type="application"` (the built-in alert icon is used otherwise).
+ * @slot title - Title or heading of the alert message.
+ * @slot description - Detailed message text.
+ * @slot time - Timestamp label (e.g., "09:12:46").
+ * @slot day - Day label (e.g., "Yesterday").
+ * @slot action - Primary action button label/content.
+ * @slot action2 - Secondary action button label/content.
+ * @fires action-click {CustomEvent} When the primary action button is clicked.
+ * @fires action2-click {CustomEvent} When the secondary action button is clicked.
+ * @fires dismiss-click {CustomEvent} When the alert message is dismissed.
  * @stable
  */
 @customElement('obc-alert-floating-item')

package/src/components/alert-menu/alert-menu.ts

@@ -50,15 +50,9 @@ export type ObcAckAllVisibleClickEvent = CustomEvent<{
  * | Slot Name                        | Renders When...                  | Purpose                                                        |
  * |----------------------------------|----------------------------------|----------------------------------------------------------------|
  * | (default)                        | Always                           | Place one or more `<obc-alert-menu-item>` elements as alert rows. |
- * | empty-unacked-title              | Unacked tab, when empty          | Custom title for empty unacknowledged alerts.                  |
- * | empty-unacked-description        | Unacked tab, when empty          | Custom description for empty unacknowledged alerts.            |
- * | empty-unacked-icon               | Unacked tab, when empty          | Custom icon for empty unacknowledged alerts.                   |
- * | empty-all-title                  | Active tab, when empty    | Custom title for empty active alerts.                          |
- * | empty-all-description            | Active tab, when empty    | Custom description for empty active alerts.                    |
- * | empty-all-icon                   | Active tab, when empty    | Custom icon for empty active alerts.                           |
- * | empty-shelved-title              | Shelved tab, when empty          | Custom title for empty shelved alerts.                         |
- * | empty-shelved-description        | Shelved tab, when empty          | Custom description for empty shelved alerts.                   |
- * | empty-shelved-icon               | Shelved tab, when empty          | Custom icon for empty shelved alerts.                          |
+ * | empty-<tab>-title                | Selected tab is empty            | Custom title for the empty state (`<tab>` is one of `unacked`, `all`, `shelved`). |
+ * | empty-<tab>-description          | Selected tab is empty            | Custom description for the empty state (`<tab>` is one of `unacked`, `all`, `shelved`). |
+ * | empty-<tab>-icon                 | Selected tab is empty            | Custom icon for the empty state (`<tab>` is one of `unacked`, `all`, `shelved`). |
  *
  * ### Properties
  * - `hasShelved` (boolean): If true, displays the "Shelved" tab and enables shelving support. Default: false.
@@ -68,7 +62,6 @@ export type ObcAckAllVisibleClickEvent = CustomEvent<{
  *
  * ### Events
  * - **ack-all-visible-click** – Fired when the "ACK visible" button is clicked. The event detail includes the list of visible alert elements and the current tab name.
- * - **alert-list-click** – Fired when the "Alerts" navigation button is clicked.
  * - **silence-click** – Fired when the "Silence" button is clicked.
  * - **go-to-alert-list-click** – Fired when the "Alerts" navigation button is clicked.
  *
@@ -92,17 +85,10 @@ export type ObcAckAllVisibleClickEvent = CustomEvent<{
  * ```
  *
  * @slot - The alerts items as ObcAlertMenuItem
- * @slot empty-unacked-title - Custom title for empty unacknowledged alerts (Unacked tab)
- * @slot empty-unacked-description - Custom description for empty unacknowledged alerts (Unacked tab)
- * @slot empty-unacked-icon - Custom icon for empty unacknowledged alerts (Unacked tab)
- * @slot empty-all-title - Custom title for empty active alerts (Active tab)
- * @slot empty-all-description - Custom description for empty active alerts (Active tab)
- * @slot empty-all-icon - Custom icon for empty active alerts (Active tab)
- * @slot empty-shelved-title - Custom title for empty shelved alerts (Shelved tab)
- * @slot empty-shelved-description - Custom description for empty shelved alerts (Shelved tab)
- * @slot empty-shelved-icon - Custom icon for empty shelved alerts (Shelved tab)
+ * @slot empty-<tab>-title - Custom empty-state title for the selected tab (`<tab>` is one of `unacked`, `all`, `shelved`)
+ * @slot empty-<tab>-description - Custom empty-state description for the selected tab (`<tab>` is one of `unacked`, `all`, `shelved`)
+ * @slot empty-<tab>-icon - Custom empty-state icon for the selected tab (`<tab>` is one of `unacked`, `all`, `shelved`)
  * @fires ack-all-visible-click {ObcAckAllVisibleClickEvent} - Fired when the ack all visible button is clicked
- * @fires alert-list-click {CustomEvent} - Fired when the alert list button is clicked
  * @fires silence-click {CustomEvent} - Fired when the silence button is clicked
  * @fires go-to-alert-list-click {CustomEvent} - Fired when the go to alert list button is clicked
  */

package/src/components/alert-menu-item/alert-menu-item.ts

@@ -65,6 +65,8 @@ export enum ObcAlertMenuItemActionState {
  * | Slot Name     | Renders When...                | Purpose                                              |
  * |---------------|-------------------------------|------------------------------------------------------|
  * | alert-icon    | Always                        | Main alert icon representing the alert type.         |
+ * | title         | Always                        | Title content; falls back to the `title` property.   |
+ * | description   | Always                        | Description content; falls back to the `description` property. |
  * | icon          | If `hasIcon` is true          | Secondary icon (e.g., system/source of alert).       |
  *
  * ### Events
@@ -94,6 +96,8 @@ export enum ObcAlertMenuItemActionState {
  * ```
  *
  * @slot alert-icon - The main alert icon representing the alert type.
+ * @slot title - Title content; falls back to the `title` property when empty.
+ * @slot description - Description content; falls back to the `description` property when empty.
  * @slot icon - Optional secondary icon (e.g., source/system).
  *
  * @fires ack-click {CustomEvent<void>} Fired when the ACK action button is clicked.

package/src/components/chat-message/chat-message.ts

@@ -12,6 +12,9 @@ export enum ObcChatMessagePosition {
 }
 
 /**
+ * `<obc-chat-message>` – A single chat message bubble with optional name and date header.
+ *
+ * @slot - The message content (body of the chat bubble).
  * @stable
  */
 @customElement('obc-chat-message')

package/src/components/elevated-card-radio/elevated-card-radio.ts

@@ -38,10 +38,8 @@ import {ObcRadio} from '../radio/radio.js';
  * ---
  *
  * ### Slots
- * | Slot Name     | Renders When... | Purpose                                 |
- * |-------------- |-----------------|-----------------------------------------|
- * | leading-icon  | Always          | Contains the radio button itself.       |
- * | label         | Always          | Displays the label text for the option. |
+ * This component exposes no slots. The radio input and its label are rendered
+ * internally from the `label`, `value`, `checked`, and related properties.
  *
  * ---
  *
@@ -82,8 +80,6 @@ import {ObcRadio} from '../radio/radio.js';
  * ```
  * In this example, two card radios form a group; only one can be selected at a time.
  *
- * @slot leading-icon - Contains the radio button input.
- * @slot label - Displays the label text for the radio option.
  * @fires change - Fired when the radio is changed.
  * @stable
  */