@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.152 → 2.0.0-next.153

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

@@ -0,0 +1,289 @@
+import {LitElement, html, nothing, unsafeCSS} from 'lit';
+import {property} from 'lit/decorators.js';
+import {classMap} from 'lit/directives/class-map.js';
+import {localized, msg} from '@lit/localize';
+import componentStyle from './alert-button-item.css?inline';
+import {customElement} from '../../decorator.js';
+import '../../icons/icon-alerts.js';
+import '../../icons/icon-alerts-active.js';
+import '../../icons/icon-alerts-alarm-twotone.js';
+import '../../icons/icon-alerts-warning-twotone.js';
+import '../../icons/icon-alerts-caution-twotone.js';
+import '../../manual-icon/icon-alerts-critical-twotone.js';
+import '../../manual-icon/icon-alerts-diagnostic-twotone.js';
+import '../alert-counter-item/alert-counter-item.js';
+import {ObcAlertCounterItemType} from '../alert-counter-item/alert-counter-item.js';
+import {
+  AlertType,
+  FlashingSpeed,
+  type AlertCounts,
+  type ResolvedFlashingSpeed,
+} from '../../types.js';
+import {
+  AlertFlashPhase,
+  AlertTwotoneComponent,
+  alertCountsLabel,
+  alertTypeLabel,
+  getAlertTwotoneComponent,
+  rankAlertCounts,
+  resolveFlashingSpeed,
+} from '../../alert-severity.js';
+import {FlashingController} from '../../palettes/flashing-controller.js';
+
+/**
+ * `ObcAlertButtonType` – Enum for alert button visual and behavioral variants.
+ *
+ * - `flat`: Minimal, icon-only button for compact spaces.
+ * - `normal`: Standard button with icon and optional counter.
+ * - `enhanced`: Emphasized button with additional styling for high-priority alerts.
+ */
+export enum ObcAlertButtonType {
+  Flat = 'flat',
+  Normal = 'normal',
+  Enhanced = 'enhanced',
+}
+
+/**
+ * `<obc-alert-button-item>` – The bell button that shows the alert state and count.
+ *
+ * Shows the alert status as a bell in the style of the given alert type, with
+ * an optional counter, or as a global counter: one badge per severity, then
+ * the bell and the total. `obc-alert-button` renders the item next to its
+ * silence button; use the item on its own where no silence button is needed.
+ *
+ * ---
+ *
+ * ### Features
+ * - **Variants (`type`):** `flat` (icon only), `normal` (bordered, icon and
+ *   counter) and `enhanced` (filled in the severity colour).
+ * - **Alert types:** `alarm`, `warning`, `caution` and the `level-*` family;
+ *   `nAlerts` of 0 shows the idle bell.
+ * - **Counter:** `counter` shows `nAlerts` next to the bell, except in `flat`.
+ * - **Global counter:** `globalCounter` shows the per-severity `counts` as
+ *   badges, then the bell and `nAlerts`, always in the normal style.
+ * - **Flashing:** `blinking` flashes the bell at the tempo `flashingSpeed`
+ *   resolves (#1224).
+ * - **Fill height:** `fillHeight` stretches the visible button to the host
+ *   height, as the tall `obc-alert-button` does.
+ *
+ * ---
+ *
+ * ### Usage Guidelines
+ * - Keep `nAlerts` and `counts` consistent; the item shows both as given.
+ * - The generated label reads e.g. "Alerts, 12, 2 Alarm, 4 Warning,
+ *   6 Caution"; an `aria-label` on the host replaces it.
+ * - A native button, so Enter and Space activate it (APG button pattern).
+ * - A parent that joins another button to the item's end sets the
+ *   `data-group-item-not-last` attribute on the host.
+ * - **TODO(designer):** the Figma file draws the flat item's hover, active and
+ *   focused variants at 20 % opacity; the item uses the standard flat states.
+ * - **TODO(designer):** the Figma file defines no flashing for the global
+ *   counter, so it never flashes.
+ *
+ * ---
+ *
+ * ### Example
+ *
+ * ```html
+ * <obc-alert-button-item alertType="alarm" nAlerts="3" counter blinking></obc-alert-button-item>
+ * <obc-alert-button-item
+ *   globalCounter
+ *   nAlerts="12"
+ *   .counts=${{countAlarm: 2, countWarning: 4, countCaution: 6}}
+ * ></obc-alert-button-item>
+ * ```
+ *
+ * @property type - Visual variant: `flat` (icon only), `normal` (default, bordered with the counter) or `enhanced` (filled in the severity colour).
+ * @availableWhen type globalCounter==false
+ * @property alertType - Alert type that selects the icon and colours: `alarm`, `warning`, `caution` or a `level-*` severity.
+ * @availableWhen alertType globalCounter==false
+ * @property nAlerts - Number of active alerts; 0 shows the idle bell and hides the counter.
+ * @property counter - Shows `nAlerts` next to the bell (not in `flat`).
+ * @availableWhen counter globalCounter==false
+ * @property globalCounter - Shows the per-severity counts, the bell and the total instead of a single alert status.
+ * @property counts - Alert count per severity for the global counter badges.
+ * @availableWhen counts globalCounter==true
+ * @property shelvedCount - Number of shelved alerts, shown after the global counter badges.
+ * @availableWhen shelvedCount globalCounter==true
+ * @property blinking - Flashes the bell while there are active alerts of a flashing alert type.
+ * @availableWhen blinking globalCounter==false
+ * @property flashingSpeed - Flash tempo while `blinking` is on: `default` resolves from `alertType`, `fast`, `slow`, `very-slow` force a tempo, `fixed` never flashes.
+ * @availableWhen flashingSpeed blinking==true
+ * @property fillHeight - Stretches the visible button to the host height instead of the 32 px visual target.
+ * @property ariaLabel - Accessible name forwarded to the inner `<button>`, mapped to the `aria-label` attribute; replaces the generated label. `aria-labelledby` is not supported: ID references cannot cross the shadow boundary.
+ * @fires click - Fired when the button is clicked.
+ * @experimental
+ */
+@customElement('obc-alert-button-item')
+@localized()
+export class ObcAlertButtonItem extends LitElement {
+  @property({type: String}) type: ObcAlertButtonType =
+    ObcAlertButtonType.Normal;
+  @property({type: String}) alertType?: AlertType;
+  @property({type: Number}) nAlerts = 0;
+  @property({type: Boolean}) counter = false;
+  @property({type: Boolean}) globalCounter = false;
+  @property({type: Object, attribute: false}) counts: AlertCounts = {};
+  @property({type: Number}) shelvedCount = 0;
+  @property({type: Boolean}) blinking = false;
+  @property({type: String}) flashingSpeed: FlashingSpeed =
+    FlashingSpeed.Default;
+  @property({type: Boolean}) fillHeight = false;
+
+  // Reactive so a consumer changing the name re-renders the shadow button.
+  @property({type: String, attribute: 'aria-label'})
+  override ariaLabel: string | null = null;
+
+  protected readonly flashing = new FlashingController(
+    this,
+    () => this.resolvedFlashingSpeed
+  );
+
+  get resolvedFlashingSpeed(): ResolvedFlashingSpeed {
+    if (
+      this.globalCounter ||
+      !this.blinking ||
+      this.nAlerts <= 0 ||
+      this.alertType === undefined
+    ) {
+      return FlashingSpeed.Fixed;
+    }
+    return resolveFlashingSpeed(
+      this.flashingSpeed,
+      this.alertType,
+      AlertFlashPhase.Active
+    );
+  }
+
+  private get accessibleName(): string {
+    if (this.ariaLabel) {
+      return this.ariaLabel;
+    }
+    const parts = [msg('Alerts')];
+    if (this.nAlerts > 0) {
+      parts.push(String(this.nAlerts));
+    }
+    if (this.globalCounter) {
+      const breakdown = alertCountsLabel(this.counts, this.shelvedCount);
+      if (breakdown) {
+        parts.push(breakdown);
+      }
+    } else if (this.nAlerts > 0 && this.alertType) {
+      parts.push(alertTypeLabel(this.alertType));
+    }
+    return parts.join(', ');
+  }
+
+  private renderTwotoneIcon() {
+    const twotone = this.alertType
+      ? getAlertTwotoneComponent(this.alertType)
+      : AlertTwotoneComponent.Caution;
+    switch (twotone) {
+      case AlertTwotoneComponent.Critical:
+        return html`<obi-alerts-critical-twotone
+          useCssColor
+          class="icon"
+        ></obi-alerts-critical-twotone>`;
+      case AlertTwotoneComponent.Diagnostic:
+        return html`<obi-alerts-diagnostic-twotone
+          useCssColor
+          class="icon"
+        ></obi-alerts-diagnostic-twotone>`;
+      case AlertTwotoneComponent.Warning:
+        return html`<obi-alerts-warning-twotone
+          useCssColor
+          class="icon"
+        ></obi-alerts-warning-twotone>`;
+      case AlertTwotoneComponent.Caution:
+        return html`<obi-alerts-caution-twotone
+          useCssColor
+          class="icon"
+        ></obi-alerts-caution-twotone>`;
+      default:
+        return html`<obi-alerts-alarm-twotone
+          useCssColor
+          class="icon"
+        ></obi-alerts-alarm-twotone>`;
+    }
+  }
+
+  /** The blink layer shows the opposite of the steady layer in each flash. */
+  private renderIcon(styleType: ObcAlertButtonType, blinkLayer: boolean) {
+    if (this.nAlerts === 0) {
+      return html`<obi-alerts class="icon"></obi-alerts>`;
+    }
+    const enhanced = styleType === ObcAlertButtonType.Enhanced;
+    if (blinkLayer) {
+      return enhanced
+        ? this.renderTwotoneIcon()
+        : html`<obi-alerts class="icon"></obi-alerts>`;
+    }
+    return enhanced || this.globalCounter
+      ? html`<obi-alerts-active class="icon"></obi-alerts-active>`
+      : this.renderTwotoneIcon();
+  }
+
+  private renderCount() {
+    return html`<span class="count">${this.nAlerts}</span>`;
+  }
+
+  private renderCounts() {
+    if (rankAlertCounts(this.counts).length === 0 && this.shelvedCount <= 0) {
+      return nothing;
+    }
+    return html`<obc-alert-counter-item
+      .type=${ObcAlertCounterItemType.Badges}
+      .counts=${this.counts}
+      .shelvedCount=${this.shelvedCount}
+    ></obc-alert-counter-item>`;
+  }
+
+  override render() {
+    const styleType = this.globalCounter
+      ? ObcAlertButtonType.Normal
+      : this.type;
+    const showCount =
+      this.nAlerts > 0 &&
+      (this.globalCounter ||
+        (this.counter && styleType !== ObcAlertButtonType.Flat));
+    const tempo = this.resolvedFlashingSpeed;
+    return html`
+      <button
+        class=${classMap({
+          'alert-button': true,
+          [`type-${styleType}`]: true,
+          [`alert-type-${this.alertType ?? 'none'}`]: true,
+          counter: showCount && !this.globalCounter,
+          'global-counter': this.globalCounter,
+          'fill-height': this.fillHeight,
+          [`flash-${tempo}`]: true,
+        })}
+        aria-label=${this.accessibleName}
+      >
+        ${tempo === FlashingSpeed.Fixed
+          ? nothing
+          : html`<div class="blink" aria-hidden="true">
+              <div class="content">
+                ${this.renderIcon(styleType, true)}
+                ${showCount ? this.renderCount() : nothing}
+              </div>
+            </div>`}
+        <div class="visible-wrapper">
+          ${this.globalCounter ? this.renderCounts() : nothing}
+          <div class="content">
+            ${this.renderIcon(styleType, false)}
+            ${showCount ? this.renderCount() : nothing}
+          </div>
+        </div>
+      </button>
+    `;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-alert-button-item': ObcAlertButtonItem;
+  }
+}

package/src/components/alert-counter-item/alert-counter-item.css

@@ -0,0 +1,15 @@
+:host {
+  display: inline-block;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--app-components-alert-counter-item-badge-spacing);
+}
+
+obi-alerts-shelf {
+  display: block; /* fills the badge icon box that sizes the badge-icon slot */
+  width: 100%;
+  height: 100%;
+}

package/src/components/alert-counter-item/alert-counter-item.spec.ts

@@ -0,0 +1,91 @@
+import {describe, expect, it} from 'vitest';
+import {render} from 'vitest-browser-lit';
+import {html} from 'lit';
+import './alert-counter-item.js';
+import {
+  ObcAlertCounterItem,
+  ObcAlertCounterItemType,
+} from './alert-counter-item.js';
+import type {ObcBadge} from '../badge/badge.js';
+import type {AlertCounts} from '../../types.js';
+
+async function setup(
+  counts: AlertCounts,
+  options: {type?: ObcAlertCounterItemType; shelvedCount?: number} = {}
+) {
+  const screen = render(
+    html`<obc-alert-counter-item
+      .counts=${counts}
+      .type=${options.type ?? ObcAlertCounterItemType.Badges}
+      .shelvedCount=${options.shelvedCount ?? 0}
+    ></obc-alert-counter-item>`
+  );
+  const el = screen.container.querySelector(
+    'obc-alert-counter-item'
+  ) as ObcAlertCounterItem;
+  await el.updateComplete;
+  return el;
+}
+
+function badges(el: ObcAlertCounterItem): ObcBadge[] {
+  return [...el.shadowRoot!.querySelectorAll<ObcBadge>('obc-badge')];
+}
+
+function lastBadge(el: ObcAlertCounterItem): ObcBadge {
+  const all = badges(el);
+  return all[all.length - 1];
+}
+
+describe('obc-alert-counter-item', () => {
+  it('renders one filled badge per positive count, most severe first', async () => {
+    const el = await setup({countCaution: 6, countAlarm: 2, countWarning: 0});
+
+    expect(
+      badges(el).map((b) => [b.type, b.number, b.variant, b.showIcon])
+    ).toEqual([
+      ['alarm', 2, 'default', false],
+      ['caution', 6, 'default', false],
+    ]);
+  });
+
+  it('draws flat badges with glyphs in the alert-level type', async () => {
+    const el = await setup(
+      {countWarning: 4},
+      {type: ObcAlertCounterItemType.AlertLevel}
+    );
+
+    expect(badges(el).map((b) => [b.type, b.variant, b.showIcon])).toEqual([
+      ['warning', 'flat', true],
+    ]);
+  });
+
+  it('adds the shelved count last', async () => {
+    const filled = await setup({countAlarm: 2}, {shelvedCount: 9});
+    expect([lastBadge(filled).type, lastBadge(filled).number]).toEqual([
+      'regular',
+      9,
+    ]);
+
+    const level = await setup(
+      {countAlarm: 2},
+      {type: ObcAlertCounterItemType.AlertLevel, shelvedCount: 9}
+    );
+    expect(lastBadge(level).querySelector('obi-alerts-shelf')).not.toBeNull();
+  });
+
+  it('renders nothing when nothing is counted', async () => {
+    const el = await setup({countAlarm: 0});
+
+    expect(el.shadowRoot!.querySelector('.row')).toBeNull();
+  });
+
+  it('labels the row with the counts', async () => {
+    const el = await setup({countWarning: 4, countAlarm: 2}, {shelvedCount: 1});
+    const row = el.shadowRoot!.querySelector('.row')!;
+
+    expect(row.getAttribute('role')).toBe('img');
+    expect(row.getAttribute('aria-label')).toBe(
+      '2 Alarm, 4 Warning, 1 Shelved'
+    );
+  });
+});

package/src/components/alert-counter-item/alert-counter-item.stories.ts

@@ -0,0 +1,66 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {html} from 'lit';
+import {
+  ObcAlertCounterItem,
+  ObcAlertCounterItemType,
+} from './alert-counter-item.js';
+import './alert-counter-item.js';
+import type {AlertCounts} from '../../types.js';
+
+const LEVEL_COUNTS: AlertCounts = {
+  countLevelCritical: 1,
+  countLevelHigh: 9,
+  countLevelMedium: 4,
+  countLevelLow: 2,
+  countLevelDiagnostic: 7,
+};
+
+const meta: Meta<typeof ObcAlertCounterItem> = {
+  title: 'Application Components/Alerts/Alert Counter Item',
+  tags: ['autodocs', '6.1', 'experimental'],
+  component: 'obc-alert-counter-item',
+  args: {
+    type: ObcAlertCounterItemType.Badges,
+    counts: {countAlarm: 2, countWarning: 4, countCaution: 6},
+    shelvedCount: 0,
+  },
+  argTypes: {
+    type: {
+      control: {type: 'inline-radio'},
+      options: Object.values(ObcAlertCounterItemType),
+    },
+    counts: {control: {type: 'object'}},
+    shelvedCount: {control: {type: 'number', min: 0}},
+  },
+  render: (args) =>
+    html`<obc-alert-counter-item
+      .type=${args.type}
+      .counts=${args.counts}
+      .shelvedCount=${args.shelvedCount}
+    ></obc-alert-counter-item>`,
+} satisfies Meta<ObcAlertCounterItem>;
+
+export default meta;
+type Story = StoryObj<ObcAlertCounterItem>;
+
+export const Badges: Story = {};
+
+export const BadgesWithShelved: Story = {
+  args: {shelvedCount: 9},
+};
+
+export const AlertLevel: Story = {
+  args: {type: ObcAlertCounterItemType.AlertLevel},
+};
+
+export const AlertLevelWithShelved: Story = {
+  args: {type: ObcAlertCounterItemType.AlertLevel, shelvedCount: 9},
+};
+
+export const LevelSeverities: Story = {
+  args: {counts: LEVEL_COUNTS},
+};
+
+export const LevelSeveritiesAlertLevel: Story = {
+  args: {type: ObcAlertCounterItemType.AlertLevel, counts: LEVEL_COUNTS},
+};

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

@@ -0,0 +1,128 @@
+import {LitElement, html, nothing, unsafeCSS} from 'lit';
+import {property} from 'lit/decorators.js';
+import {repeat} from 'lit/directives/repeat.js';
+import {localized} from '@lit/localize';
+import componentStyle from './alert-counter-item.css?inline';
+import {customElement} from '../../decorator.js';
+import '../badge/badge.js';
+import {BadgeSize, BadgeType, BadgeVariant} from '../badge/badge.js';
+import '../../icons/icon-alerts-shelf.js';
+import type {AlertCounts} from '../../types.js';
+import {alertCountsLabel, rankAlertCounts} from '../../alert-severity.js';
+
+/**
+ * `ObcAlertCounterItemType` – How each count is drawn (Figma `Type`).
+ *
+ * - `badges`: filled badges in the severity colour (Figma Badges counter).
+ * - `alert-level`: flat badges with the severity glyph (Figma Alert level counter).
+ */
+export enum ObcAlertCounterItemType {
+  Badges = 'badges',
+  AlertLevel = 'alert-level',
+}
+
+/**
+ * `<obc-alert-counter-item>` – A row of alert counts, one badge per severity.
+ *
+ * Renders a large `obc-badge` for every severity with a count above zero, most
+ * severe first, followed by an optional shelved count. Nothing renders when
+ * nothing is counted.
+ *
+ * ---
+ *
+ * ### Features
+ * - **Two types:** `badges` draws filled badges in the severity colour;
+ *   `alert-level` draws flat badges with the severity glyph.
+ * - **Every severity:** `counts` takes the whole `AlertType` vocabulary,
+ *   including the `level-*` family, ordered by `ALERT_SEVERITY_PRIORITY`.
+ * - **Shelved count:** `shelvedCount` adds a neutral badge at the end, with
+ *   the shelf icon in `alert-level`.
+ * - **Accessible summary:** the row is announced as one image labelled with
+ *   the counts, e.g. "2 Alarm, 4 Warning, 6 Caution".
+ *
+ * ---
+ *
+ * ### Usage Guidelines
+ * - Show how many alerts are outstanding per severity in a compact space;
+ *   `obc-alert-button-item` nests the counter for its global counter.
+ * - Pass the counts as one object: `.counts=${{countAlarm: 2, countWarning: 4}}`.
+ * - The counter is display-only: it renders no button and fires no events.
+ * - For a framed per-subsystem summary with a label, see
+ *   `obc-alert-subsystem-counter`.
+ * - **TODO(designer):** the Figma component also has an Unacked counter type;
+ *   how its icons map to counts is not defined yet.
+ *
+ * ---
+ *
+ * ### Example
+ *
+ * ```html
+ * <obc-alert-counter-item
+ *   .counts=${{countAlarm: 2, countWarning: 4, countCaution: 6}}
+ *   shelvedCount="9"
+ * ></obc-alert-counter-item>
+ * ```
+ *
+ * @property type - How each count is drawn: `badges` (filled severity badges, default) or `alert-level` (flat badges with the severity glyph).
+ * @property counts - Alert count per severity (`countAlarm`, `countWarning`, `countCaution` and the `level-*` counts); counts of zero or less are not shown.
+ * @property shelvedCount - Number of shelved alerts, shown as a neutral badge after the severities; hidden at zero.
+ * @experimental
+ */
+@customElement('obc-alert-counter-item')
+@localized()
+export class ObcAlertCounterItem extends LitElement {
+  @property({type: String}) type: ObcAlertCounterItemType =
+    ObcAlertCounterItemType.Badges;
+  @property({type: Object, attribute: false}) counts: AlertCounts = {};
+  @property({type: Number}) shelvedCount = 0;
+
+  override render() {
+    const ranked = rankAlertCounts(this.counts);
+    if (ranked.length === 0 && this.shelvedCount <= 0) {
+      return nothing;
+    }
+    const alertLevel = this.type === ObcAlertCounterItemType.AlertLevel;
+    const variant = alertLevel ? BadgeVariant.flat : BadgeVariant.default;
+    return html`
+      <div
+        class="row"
+        role="img"
+        aria-label=${alertCountsLabel(this.counts, this.shelvedCount)}
+      >
+        ${repeat(
+          ranked,
+          (entry) => entry.type,
+          (entry) =>
+            html`<obc-badge
+              size=${BadgeSize.large}
+              type=${entry.type}
+              .variant=${variant}
+              .showIcon=${alertLevel}
+              .number=${entry.count}
+            ></obc-badge>`
+        )}
+        ${this.shelvedCount > 0
+          ? html`<obc-badge
+              size=${BadgeSize.large}
+              type=${BadgeType.regular}
+              .variant=${variant}
+              .showIcon=${alertLevel}
+              .number=${this.shelvedCount}
+            >
+              ${alertLevel
+                ? html`<obi-alerts-shelf slot="badge-icon"></obi-alerts-shelf>`
+                : nothing}
+            </obc-badge>`
+          : nothing}
+      </div>
+    `;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-alert-counter-item': ObcAlertCounterItem;
+  }
+}