@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.59 → 2.0.0-next.60

package/src/components/tree-navigation-item/tree-navigation-item.css

@@ -0,0 +1,258 @@
+* {
+  box-sizing: border-box;
+}
+
+:host {
+  display: block;
+}
+
+.wrapper {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  height: var(--menu-navigation-components-tree-navigation-item-touch-target);
+  user-select: none;
+
+  @mixin outline-inward;
+  @mixin style style=flat visibleWrapperClass=.visible-wrapper;
+  @mixin font-body;
+  color: var(--on-flat-active-color);
+
+  .visible-wrapper {
+    display: flex;
+    align-items: center;
+    width: 100%;
+    height: 100%;
+    border-radius: var(--global-border-radius-border-radius-base);
+    padding: 0
+      var(--menu-navigation-components-tree-navigation-item-padding-horizontal);
+  }
+
+  /*
+   * A checked row is not re-selectable, so it stays on the amplified enabled
+   * style with no hover/pressed feedback.
+   */
+  &.checked {
+    @mixin style style=amplified visibleWrapperClass=.visible-wrapper;
+    cursor: default;
+
+    & .visible-wrapper,
+    &:hover .visible-wrapper,
+    &:active .visible-wrapper {
+      background-color: var(--amplified-enabled-background-color);
+      border-color: var(--amplified-enabled-border-color);
+    }
+
+    & .label {
+      @mixin font-body-active;
+      color: var(--on-flat-active-color);
+    }
+
+    & .leading-icon {
+      color: var(--on-amplified-active-color);
+    }
+  }
+
+  /* Guide lines are tree structure, not row state, so they do not dim here. */
+  &.disabled {
+    color: var(--on-flat-disabled-color);
+
+    & .leading-icon {
+      color: var(--on-flat-disabled-color);
+    }
+  }
+}
+
+.tree-node-row {
+  display: flex;
+  align-items: center;
+  height: 100%;
+  flex-shrink: 0;
+}
+
+.branch {
+  position: relative;
+  height: 100%;
+  width: var(--menu-navigation-components-branch-width);
+  flex-shrink: 0;
+}
+
+/*
+ * Guide lines all run on a rail at 75% of each 32px column and share the faint
+ * outline color. Verticals and the dropdown bleed 1px past the row edges so they
+ * cross the visible-wrapper's 1px transparent flat border and meet the adjacent
+ * row's line with no seam gap.
+ */
+.branch-vertical {
+  position: absolute;
+  top: -1px;
+  bottom: -1px;
+  left: 75%;
+  width: 1px;
+  transform: translateX(-0.5px);
+  background: var(--border-outline-color);
+}
+
+.branch-horizontal {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-0.5px);
+  left: 75%;
+  right: 0;
+  height: 1px;
+  background: var(--border-outline-color);
+}
+
+/*
+ * Corner (└, last child): a single bordered box replaces the straight rects so
+ * the bend can be rounded. The box bleeds 1px past the column's right edge so its
+ * bottom border overlaps the terminal connector with no break, and translateY
+ * drops it 0.5px so that border lands on the connector's pixel row (else the join
+ * reads as a `---___` step). The radius stays tight — the stub is only 8px, so a
+ * larger fillet would consume the whole flat run.
+ */
+.branch-corner .branch-vertical,
+.branch-corner .branch-horizontal {
+  display: none;
+}
+
+.branch-corner .branch-elbow {
+  position: absolute;
+  top: -1px;
+  bottom: 50%;
+  left: 75%;
+  right: -1px;
+  transform: translate(-0.5px, 0.5px);
+  border-left: 1px solid var(--border-outline-color);
+  border-bottom: 1px solid var(--border-outline-color);
+  border-bottom-left-radius: var(
+    --menu-navigation-components-branch-corner-radius,
+    2px
+  );
+}
+
+.terminal {
+  position: relative;
+  height: 100%;
+  width: var(--global-size-spacing-touch-target-min);
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Stub entering the terminal, continuing the guide line up to the chevron gap. */
+.terminal-connector {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-0.5px);
+  left: 0;
+  width: 25%;
+  height: 1px;
+  background: var(--border-outline-color);
+}
+
+/* On a leaf (no chevron) the stub runs further, stopping ~13px before the icon. */
+.terminal:not(:has(.chevron)) .terminal-connector {
+  width: calc(100% - 13px);
+}
+
+/* Descends from below the chevron to connect an expanded node to its children. */
+.terminal-dropdown {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-0.5px);
+  top: 75%;
+  bottom: -1px;
+  width: 1px;
+  background: var(--border-outline-color);
+}
+
+/* Visual expand/collapse indicator only — not a separate control. */
+.chevron {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  height: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  color: var(--element-neutral-color);
+  transition: transform 100ms ease-in-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .chevron {
+    transition: none;
+  }
+}
+
+.wrapper.disabled .chevron {
+  color: var(--on-flat-disabled-color);
+}
+
+:host([expanded]) .chevron {
+  transform: rotate(90deg);
+}
+
+/* Alert-header marker for non-regular terminal types, at the terminal's top-right. */
+.terminal-header {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  justify-content: flex-end;
+  align-items: flex-start;
+  padding: var(--menu-navigation-components-terminal-padding-aggregated-icon);
+  color: var(--element-neutral-color);
+  pointer-events: none;
+}
+
+.terminal-header > * {
+  width: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  height: var(--menu-navigation-components-tree-navigation-item-icon-size);
+}
+
+.wrapper.disabled .terminal-header {
+  color: var(--on-flat-disabled-color);
+}
+
+.label-container {
+  display: flex;
+  flex: 1;
+  gap: var(
+    --menu-navigation-components-tree-navigation-item-padding-horizontal
+  );
+  align-items: center;
+  min-width: 0;
+  padding-right: var(
+    --menu-navigation-components-tree-navigation-item-padding-horizontal
+  );
+}
+
+.leading-icon {
+  position: relative;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  height: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  color: var(--on-flat-neutral-color);
+}
+
+::slotted([slot="icon"]) {
+  display: block;
+  width: var(--menu-navigation-components-tree-navigation-item-icon-size);
+  height: var(--menu-navigation-components-tree-navigation-item-icon-size);
+}
+
+.label {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.alert-badge {
+  flex-shrink: 0;
+}

package/src/components/tree-navigation-item/tree-navigation-item.stories.ts

@@ -0,0 +1,119 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {
+  ObcTreeNavigationItem,
+  TreeBranchType,
+  TreeTerminalType,
+} from './tree-navigation-item.js';
+import './tree-navigation-item.js';
+import {iconIds, iconIdToIconHtml} from '../../storybook-util.js';
+import {html} from 'lit';
+import {BadgeType} from '../badge/badge.js';
+
+const meta: Meta<typeof ObcTreeNavigationItem> = {
+  title: 'UI Components/Menus and Navigation/Tree Navigation Item',
+  tags: ['autodocs', '6.0'],
+  component: 'obc-tree-navigation-item',
+  args: {
+    label: 'List item',
+    icon: 'placeholder',
+    branches: [TreeBranchType.straight, TreeBranchType.intersection],
+    expandable: true,
+    expanded: false,
+    checked: false,
+    disabled: false,
+    hasLeadingIcon: true,
+    terminalType: TreeTerminalType.regular,
+    hasAlertBadge: false,
+    alertCount: 9,
+    alertType: BadgeType.alarm,
+  },
+  argTypes: {
+    icon: {
+      options: iconIds,
+      control: {type: 'select'},
+    },
+    label: {control: {type: 'text'}},
+    branches: {control: {type: 'object'}},
+    expandable: {control: {type: 'boolean'}},
+    expanded: {control: {type: 'boolean'}},
+    checked: {control: {type: 'boolean'}},
+    disabled: {control: {type: 'boolean'}},
+    hasLeadingIcon: {control: {type: 'boolean'}},
+    terminalType: {
+      control: {type: 'select'},
+      options: Object.values(TreeTerminalType),
+    },
+    hasAlertBadge: {control: {type: 'boolean'}},
+    alertCount: {control: {type: 'number'}},
+    alertType: {
+      control: {type: 'select'},
+      options: Object.values(BadgeType),
+      if: {arg: 'hasAlertBadge'},
+    },
+  },
+  render: (args) => {
+    return html`<obc-tree-navigation-item
+      .label=${args.label}
+      .branches=${args.branches}
+      ?expandable=${args.expandable}
+      ?expanded=${args.expanded}
+      ?checked=${args.checked}
+      ?disabled=${args.disabled}
+      .hasLeadingIcon=${args.hasLeadingIcon}
+      .terminalType=${args.terminalType}
+      .hasAlertBadge=${args.hasAlertBadge}
+      .alertCount=${args.alertCount}
+      .alertType=${args.alertType}
+      @expand-toggle=${(e: CustomEvent<boolean>) => {
+        (e.currentTarget as ObcTreeNavigationItem).expanded = e.detail;
+      }}
+    >
+      ${args.hasLeadingIcon && args.icon
+        ? iconIdToIconHtml(args.icon as unknown as string, {slot: 'icon'})
+        : ''}
+    </obc-tree-navigation-item>`;
+  },
+} satisfies Meta<ObcTreeNavigationItem>;
+
+export default meta;
+type Story = StoryObj<ObcTreeNavigationItem>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Checked: Story = {
+  args: {checked: true, expandable: false},
+};
+
+export const Expanded: Story = {
+  args: {expanded: true},
+};
+
+export const Disabled: Story = {
+  args: {disabled: true},
+};
+
+export const Leaf: Story = {
+  args: {expandable: false},
+};
+
+export const Root: Story = {
+  args: {branches: []},
+};
+
+export const IndentedNoConnectors: Story = {
+  args: {branches: [TreeBranchType.blank, TreeBranchType.blank]},
+};
+
+export const WithAlertBadge: Story = {
+  args: {hasAlertBadge: true, alertCount: 9},
+};
+
+export const AggregatedHeader: Story = {
+  args: {terminalType: TreeTerminalType.aggregatedHeader},
+};
+
+export const GroupHeader: Story = {
+  args: {terminalType: TreeTerminalType.groupHeader},
+};

package/src/components/tree-navigation-item/tree-navigation-item.ts

@@ -0,0 +1,307 @@
+import {LitElement, html, nothing, unsafeCSS} from 'lit';
+import {property, query} from 'lit/decorators.js';
+import componentStyle from './tree-navigation-item.css?inline';
+import {classMap} from 'lit/directives/class-map.js';
+import {ifDefined} from 'lit/directives/if-defined.js';
+import {customElement} from '../../decorator.js';
+import '../../icons/icon-chevron-right-google.js';
+import '../../icons/icon-alert-header-aggregated-iec.js';
+import '../../icons/icon-alert-header-group-iec.js';
+import '../badge/badge.js';
+import {BadgeType} from '../badge/badge.js';
+
+/**
+ * Guide line drawn for one indentation column. Normally computed by
+ * `obc-tree-navigation`; rarely set by hand.
+ *
+ * - `straight`: vertical pass-through (`│`)
+ * - `intersection`: vertical + stub for a non-last child (`├`)
+ * - `corner`: half vertical + stub for the last child (`└`)
+ * - `blank`: empty spacer
+ */
+export enum TreeBranchType {
+  straight = 'straight',
+  intersection = 'intersection',
+  corner = 'corner',
+  blank = 'blank',
+}
+
+/**
+ * Terminal type for a tree item, controlling the alert-header marker shown in
+ * the terminal (top-right, by the chevron).
+ *
+ * - `regular`: No marker — a plain expand/collapse terminal.
+ * - `aggregatedHeader`: Shows the aggregated alert-header marker, indicating the
+ *   node aggregates alerts from its descendants.
+ * - `groupHeader`: Shows the group alert-header marker, indicating a grouped set
+ *   of alerts beneath the node.
+ */
+export enum TreeTerminalType {
+  regular = 'regular',
+  aggregatedHeader = 'aggregated-header',
+  groupHeader = 'group-header',
+}
+
+/**
+ * `<obc-tree-navigation-item>` – A single row in a tree- or file-explorer-style
+ * navigation list, with indentation guide lines, an optional expand/collapse
+ * chevron, a leading icon, a label, and an optional alert badge.
+ *
+ * Each row represents one node in a hierarchy. Depth is expressed through the
+ * `branches` array: one entry per ancestor level, each describing the guide line
+ * to draw for that level. The expand chevron lets a node disclose its children,
+ * emitting `expand-toggle` so a parent can manage the open/closed state.
+ *
+ * ## Features
+ * - **Indentation guides:** Render one 32px guide column per `branches` entry —
+ *   pass-through vertical lines for ancestors that continue, and an elbow
+ *   (`intersection`) connecting the row to its parent.
+ * - **Expand/collapse:** Set `expandable` to show a chevron that rotates when
+ *   `expanded`. The chevron is a visual indicator only — activating the row
+ *   fires `expand-toggle` with the next state; manage `expanded` in response.
+ *   When `expanded`, a vertical guide descends from the chevron to connect to
+ *   the revealed child rows below.
+ * - **Terminal type:** `terminalType` adds an alert-header marker in the terminal
+ *   (`aggregatedHeader` or `groupHeader`), indicating the node heads a set of
+ *   aggregated or grouped alerts.
+ * - **Leading icon:** Provide an icon via the `icon` slot (shown when
+ *   `hasLeadingIcon`).
+ * - **Alert badge:** A trailing counter badge (e.g. an alarm count), toggled with
+ *   `hasAlertBadge` and configured via `alertCount` and `alertType`.
+ * - **Checked state:** `checked` highlights the current selection using the
+ *   amplified elevation style. A checked row is the current item and is not
+ *   re-selectable — it shows no hover/pressed feedback and fires no `click` or
+ *   navigation. An expandable checked row still toggles (fires `expand-toggle`),
+ *   so a group that is the current selection can be opened and closed. It stays
+ *   keyboard-focusable.
+ * - **Link or button:** Set `href` to render the row as a link; otherwise it acts
+ *   as a button.
+ *
+ * ## Usage Guidelines
+ * - Use for hierarchical navigation such as file trees, layer panels, or nested
+ *   menus. For flat navigation lists, use `obc-navigation-item` instead.
+ * - Build `branches` from the row's ancestry: `intersection` for the level that
+ *   owns this row, `straight` for ancestors with siblings still to come, and
+ *   `blank` for ancestors whose subtrees have ended. When placed inside
+ *   `obc-tree-navigation`, the container computes `branches` automatically.
+ * - Keep one row `checked` at a time within a tree to mark the current location.
+ * - Leaf nodes should leave `expandable` as `false` so no chevron is shown.
+ *
+ * ## Slots
+ *
+ * | Slot Name      | Renders When...                 | Purpose                                                                 |
+ * |----------------|---------------------------------|-------------------------------------------------------------------------|
+ * | icon           | `hasLeadingIcon` is true        | Leading icon for the row, e.g. `<obi-placeholder slot="icon">`.         |
+ *
+ * @slot icon - Leading icon slot (shown when `hasLeadingIcon` is true).
+ * @fires expand-toggle {CustomEvent<boolean>} Fired when an expandable row is activated; detail is the next `expanded` value.
+ * @fires click {CustomEvent<void>} Fired when the row is activated.
+ */
+@customElement('obc-tree-navigation-item')
+export class ObcTreeNavigationItem extends LitElement {
+  /** The text label displayed for the row. */
+  @property({type: String}) label = 'List item';
+
+  /**
+   * Guide line for each ancestor level, outermost first; one 32px column per
+   * entry. Computed by `obc-tree-navigation` — rarely set by hand.
+   */
+  @property({type: Array}) branches: TreeBranchType[] = [];
+
+  /** Whether the row shows an expand/collapse chevron. Leave false for leaf nodes. */
+  @property({type: Boolean}) expandable = false;
+
+  /** Whether the node is expanded. Rotates the chevron and sets `aria-expanded`. */
+  @property({type: Boolean, reflect: true}) expanded = false;
+
+  /**
+   * Whether the row is the current selection. Applies the amplified style and
+   * makes the row inert to re-selection (no hover/pressed feedback, no `click`
+   * or navigation); it remains keyboard-focusable. An expandable checked row
+   * still fires `expand-toggle` so a selected group can open and close.
+   */
+  @property({type: Boolean, reflect: true}) checked = false;
+
+  /** Disables the row, removing it from the tab order and dimming its appearance. */
+  @property({type: Boolean, reflect: true}) disabled = false;
+
+  /**
+   * Whether the row is in the tab order. A tree container manages this as a
+   * roving tabindex (one row focusable at a time); standalone rows stay tabbable.
+   */
+  @property({type: Boolean, attribute: false}) focusable = true;
+
+  /**
+   * Whether the row shows a leading icon (provided via the `icon` slot).
+   */
+  @property({type: Boolean, attribute: false}) hasLeadingIcon = true;
+
+  /**
+   * Terminal type, controlling the alert-header marker shown in the terminal.
+   * One of `regular` (default), `aggregated-header`, or `group-header`.
+   */
+  @property({type: String}) terminalType: string = TreeTerminalType.regular;
+
+  /** Whether a trailing alert counter badge is shown. */
+  @property({type: Boolean}) hasAlertBadge = false;
+
+  /** The number shown in the alert badge when `hasAlertBadge` is true. */
+  @property({type: Number}) alertCount = 0;
+
+  /** The severity/type of the alert badge. One of the `obc-badge` types (default `alarm`). */
+  @property({type: String}) alertType: string = BadgeType.alarm;
+
+  /**
+   * The URL to navigate to when the row is activated. If set, the row renders as
+   * a link; otherwise it acts as a button.
+   */
+  @property({type: String}) href: string | undefined;
+
+  @query('.wrapper') private wrapperElement?: HTMLElement;
+
+  /** Focuses the row's interactive wrapper (the host itself is not focusable). */
+  public override focus(options?: FocusOptions): void {
+    this.wrapperElement?.focus(options);
+  }
+
+  /** A root-level row has no ancestor columns, so it draws no connector lines. */
+  private get isRoot(): boolean {
+    return this.branches.length === 0;
+  }
+
+  /**
+   * All ancestor columns are blank spacers — the row is indented but draws no
+   * guide lines, so the terminal connector and dropdown are suppressed too.
+   */
+  private get isBlankAncestry(): boolean {
+    return (
+      this.branches.length > 0 &&
+      this.branches.every((b) => b === TreeBranchType.blank)
+    );
+  }
+
+  private activate() {
+    if (this.disabled) return;
+    // An expandable row always toggles, even when checked — a group that is the
+    // current selection must still open and close. A checked leaf, however, is
+    // the current selection and is inert (no re-selection click or navigation).
+    if (this.expandable) {
+      this.dispatchEvent(
+        new CustomEvent<boolean>('expand-toggle', {detail: !this.expanded})
+      );
+    }
+    if (this.checked) return;
+    this.dispatchEvent(new CustomEvent('click'));
+    if (this.href !== undefined) {
+      window.location.href = this.href;
+    }
+  }
+
+  private handleKeydown(event: KeyboardEvent) {
+    if (this.disabled) return;
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    event.preventDefault();
+    this.activate();
+  }
+
+  private renderBranch(type: TreeBranchType) {
+    const hasVertical =
+      type === TreeBranchType.straight ||
+      type === TreeBranchType.intersection ||
+      type === TreeBranchType.corner;
+    const hasHorizontal =
+      type === TreeBranchType.intersection || type === TreeBranchType.corner;
+    return html`<div
+      class=${classMap({branch: true, ['branch-' + type]: true})}
+    >
+      ${hasVertical ? html`<div class="branch-vertical"></div>` : nothing}
+      ${hasHorizontal ? html`<div class="branch-horizontal"></div>` : nothing}
+      ${type === TreeBranchType.corner
+        ? html`<div class="branch-elbow"></div>`
+        : nothing}
+    </div>`;
+  }
+
+  private renderTerminalHeader() {
+    if (this.terminalType === TreeTerminalType.aggregatedHeader) {
+      return html`<div class="terminal-header" aria-hidden="true">
+        <obi-alert-header-aggregated-iec></obi-alert-header-aggregated-iec>
+      </div>`;
+    }
+    if (this.terminalType === TreeTerminalType.groupHeader) {
+      return html`<div class="terminal-header" aria-hidden="true">
+        <obi-alert-header-group-iec></obi-alert-header-group-iec>
+      </div>`;
+    }
+    return nothing;
+  }
+
+  override render() {
+    return html`
+      <div
+        class=${classMap({
+          wrapper: true,
+          checked: this.checked,
+          disabled: this.disabled,
+          'has-icon': this.hasLeadingIcon,
+        })}
+        role="treeitem"
+        aria-expanded=${ifDefined(this.expandable ? this.expanded : undefined)}
+        aria-current=${ifDefined(this.checked ? 'page' : undefined)}
+        aria-selected=${ifDefined(this.checked ? 'true' : undefined)}
+        aria-disabled=${ifDefined(this.disabled ? 'true' : undefined)}
+        tabindex=${this.disabled ? -1 : this.focusable ? 0 : -1}
+        @click=${this.activate}
+        @keydown=${this.handleKeydown}
+      >
+        <div class="visible-wrapper">
+          <div class="tree-node-row">
+            ${this.branches.map((branch) => this.renderBranch(branch))}
+            <div class="terminal">
+              ${this.isRoot || this.isBlankAncestry
+                ? nothing
+                : html`<div class="terminal-connector"></div>`}
+              ${!this.isRoot &&
+              !this.isBlankAncestry &&
+              this.expandable &&
+              this.expanded
+                ? html`<div class="terminal-dropdown"></div>`
+                : nothing}
+              ${this.expandable
+                ? html`<div class="chevron" aria-hidden="true">
+                    <obi-chevron-right-google></obi-chevron-right-google>
+                  </div>`
+                : nothing}
+              ${this.renderTerminalHeader()}
+            </div>
+          </div>
+          <div class="label-container">
+            ${this.hasLeadingIcon
+              ? html`<div class="leading-icon">
+                  <slot name="icon"></slot>
+                </div>`
+              : nothing}
+            <span part="label" class="label">${this.label}</span>
+          </div>
+          ${this.hasAlertBadge
+            ? html`<obc-badge
+                class="alert-badge"
+                .type=${this.alertType}
+                .number=${this.alertCount}
+              ></obc-badge>`
+            : nothing}
+        </div>
+      </div>
+    `;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+export type ObcTreeNavigationItemExpandToggleEvent = CustomEvent<boolean>;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-tree-navigation-item': ObcTreeNavigationItem;
+  }
+}