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

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

@@ -0,0 +1,188 @@
+import {LitElement, html, unsafeCSS} from 'lit';
+import componentStyle from './tree-navigation.css?inline';
+import {customElement} from '../../decorator.js';
+import {
+  ObcTreeNavigationItem,
+  TreeBranchType,
+} from '../tree-navigation-item/tree-navigation-item.js';
+import {ObcTreeNavigationGroup} from '../tree-navigation-group/tree-navigation-group.js';
+import '../tree-navigation-group/tree-navigation-group.js';
+import {
+  TreeRovingNavigator,
+  TreeRovingAdapter,
+} from '../../internal/tree-roving-navigator.js';
+
+/** A tree row is either a leaf item or an expandable group. */
+type TreeRow = ObcTreeNavigationItem | ObcTreeNavigationGroup;
+
+const ITEM_TAG = 'obc-tree-navigation-item';
+const GROUP_TAG = 'obc-tree-navigation-group';
+
+function isGroup(el: Element): el is ObcTreeNavigationGroup {
+  return el.tagName.toLowerCase() === GROUP_TAG;
+}
+
+function isRow(el: Element): el is TreeRow {
+  const tag = el.tagName.toLowerCase();
+  return tag === ITEM_TAG || tag === GROUP_TAG;
+}
+
+/**
+ * `<obc-tree-navigation>` – The container for a tree- or file-explorer-style
+ * navigation list. Holds nested `<obc-tree-navigation-group>` and
+ * `<obc-tree-navigation-item>` rows and computes each row's indentation guide
+ * lines automatically from its position in the hierarchy.
+ *
+ * Consumers write the tree as plain nested markup; the container assigns every
+ * row's `branches` array so the guide lines (pass-through verticals, elbows, and
+ * the last-child corner) connect correctly — there is no need to compute depth or
+ * branch types by hand. It re-derives the guides whenever rows are added, removed,
+ * or groups expand and collapse.
+ *
+ * ## Features
+ * - **Automatic guide lines:** Each row receives a `branches` array derived from
+ *   its depth and whether each ancestor still has siblings below it. Last children
+ *   get a corner (`└`); rows with siblings below get an intersection (`├`); and
+ *   ancestor columns become a pass-through (`│`) or blank as appropriate.
+ * - **Live updates:** Reacts to slotted content changes and to group expand state,
+ *   recomputing the guides so they always match the visible structure.
+ * - **Composable:** Works with any nesting depth of groups and items.
+ *
+ * ## Usage Guidelines
+ * - Use as the root of a hierarchical navigation list. For flat navigation, use
+ *   `obc-navigation-menu` instead.
+ * - Place `<obc-tree-navigation-group>` for expandable parents and
+ *   `<obc-tree-navigation-item>` for leaves; nest groups to any depth.
+ * - Do not set each row's `branches` manually — the container manages them.
+ *
+ * ## Slots
+ *
+ * | Slot Name | Renders When... | Purpose                                            |
+ * |-----------|-----------------|----------------------------------------------------|
+ * | (default) | Always          | Top-level rows (`obc-tree-navigation-group`/`-item`). |
+ *
+ * @slot - Top-level tree rows (groups and items).
+ */
+@customElement('obc-tree-navigation')
+export class ObcTreeNavigation extends LitElement {
+  private mutationObserver?: MutationObserver;
+
+  /** The focusable header item for a row: a leaf is itself; a group's is its shadow header. */
+  private innerItem(row: TreeRow): ObcTreeNavigationItem | null {
+    return isGroup(row)
+      ? (row.shadowRoot?.querySelector<ObcTreeNavigationItem>(ITEM_TAG) ?? null)
+      : row;
+  }
+
+  private readonly navigator = new TreeRovingNavigator<TreeRow>(this, {
+    getRows: () => this.childRows(this),
+    childRows: (row) => this.childRows(row),
+    isGroup: (row) => isGroup(row),
+    isExpanded: (row) => isGroup(row) && row.hasAttribute('expanded'),
+    setExpanded: (row, expanded) => {
+      if (isGroup(row)) row.expanded = expanded;
+    },
+    innerItem: (row) => this.innerItem(row),
+    isDisabled: (row) => this.innerItem(row)?.hasAttribute('disabled') ?? false,
+  } satisfies TreeRovingAdapter<TreeRow>);
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    // Recompute guides on any structural change: rows added/removed, or a group's
+    // `expanded` attribute toggled anywhere in the subtree.
+    this.mutationObserver = new MutationObserver(() => this.updateBranches());
+    this.mutationObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['expanded'],
+    });
+    this.addEventListener('expand-toggle', this.onExpandToggle);
+    this.addEventListener('keydown', this.onKeydown);
+  }
+
+  private onKeydown = (event: KeyboardEvent): void => {
+    if (this.navigator.handleKeydown(event)) event.preventDefault();
+  };
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.mutationObserver?.disconnect();
+    this.mutationObserver = undefined;
+    this.removeEventListener('expand-toggle', this.onExpandToggle);
+    this.removeEventListener('keydown', this.onKeydown);
+  }
+
+  private onExpandToggle = () => {
+    // Defer so the group's `expanded` attribute and slotted children reflect the
+    // new state before guides are recomputed.
+    queueMicrotask(() => this.updateBranches());
+  };
+
+  override firstUpdated(): void {
+    this.updateBranches();
+  }
+
+  /** Direct tree-row children of an element, in document order. */
+  private childRows(el: Element): TreeRow[] {
+    return Array.from(el.children).filter(isRow);
+  }
+
+  /**
+   * Walk the row tree and assign each row's `branches`. Mirrors the guide-line
+   * model: a row gets one column per ancestor (pass-through `straight` if that
+   * ancestor still has siblings below, else `blank`) followed by its own elbow
+   * (`corner` if it is the last child, else `intersection`). Top-level rows draw
+   * no columns at all.
+   *
+   * @param rows - sibling rows at this level, in order
+   * @param ancestorHasNextSibling - one flag per ancestor *below the root*: true
+   *   if that ancestor has a sibling still below it (so its column is a
+   *   pass-through), false if its subtree has ended (a blank column)
+   * @param depth - nesting depth; 0 for top-level rows (which draw no columns)
+   */
+  private assignBranches(
+    rows: TreeRow[],
+    ancestorHasNextSibling: boolean[],
+    depth: number
+  ): void {
+    rows.forEach((row, index) => {
+      const isLast = index === rows.length - 1;
+      row.branches =
+        depth === 0
+          ? []
+          : [
+              ...ancestorHasNextSibling.map((hasNext) =>
+                hasNext ? TreeBranchType.straight : TreeBranchType.blank
+              ),
+              isLast ? TreeBranchType.corner : TreeBranchType.intersection,
+            ];
+
+      if (isGroup(row)) {
+        const childAncestry =
+          depth === 0 ? [] : [...ancestorHasNextSibling, !isLast];
+        this.assignBranches(this.childRows(row), childAncestry, depth + 1);
+      }
+    });
+  }
+
+  private updateBranches(): void {
+    this.assignBranches(this.childRows(this), [], 0);
+    // Keep the roving tabindex in lockstep with the visible structure.
+    this.navigator.refresh();
+  }
+
+  override render() {
+    return html`<div role="tree">
+      <slot @slotchange=${() => this.updateBranches()}></slot>
+    </div>`;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-tree-navigation': ObcTreeNavigation;
+  }
+}

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

@@ -0,0 +1,11 @@
+:host {
+  display: block;
+}
+
+[part="children"] {
+  display: block;
+}
+
+[part="children"][hidden] {
+  display: none;
+}

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

@@ -0,0 +1,157 @@
+import {LitElement, html, nothing, unsafeCSS} from 'lit';
+import {property, query} from 'lit/decorators.js';
+import componentStyle from './tree-navigation-group.css?inline';
+import {customElement} from '../../decorator.js';
+import {
+  ObcTreeNavigationItem,
+  TreeBranchType,
+  TreeTerminalType,
+} from '../tree-navigation-item/tree-navigation-item.js';
+import '../tree-navigation-item/tree-navigation-item.js';
+import {BadgeType} from '../badge/badge.js';
+
+/**
+ * `<obc-tree-navigation-group>` – An expandable parent row in a tree-navigation
+ * structure: a header row with an expand/collapse chevron, plus a slot for the
+ * child rows it discloses.
+ *
+ * A group renders an `<obc-tree-navigation-item>` header (carrying its own label,
+ * icon, terminal type, and alert badge) followed by its slotted children. When
+ * placed inside `<obc-tree-navigation>`, the container computes and assigns the
+ * `branches` guide lines for every row automatically from each row's position —
+ * a group does not need its depth configured by hand.
+ *
+ * The group manages only its own open/closed state and forwards header presentation
+ * to its internal header item. It does not draw guide lines itself; that is the
+ * container's responsibility (see `<obc-tree-navigation>`).
+ *
+ * ## Features
+ * - **Disclosure:** A chevron in the header toggles the slotted children. The open
+ *   state is held in `expanded` and reflected so the container and CSS can react.
+ * - **Header presentation:** `label`, the `icon` slot, `terminalType`, and the
+ *   alert badge (`hasAlertBadge`, `alertCount`, `alertType`) are forwarded to the
+ *   header row.
+ * - **Selection:** `checked` marks the group's header as the current item.
+ * - **Automatic guides:** Inside `<obc-tree-navigation>`, the header's `branches`
+ *   are assigned by the container; nested groups continue the guide columns down.
+ *
+ * ## Usage Guidelines
+ * - Nest `<obc-tree-navigation-item>` (leaves) and further `<obc-tree-navigation-group>`
+ *   elements as children to build the hierarchy.
+ * - Always place groups and items inside an `<obc-tree-navigation>` container so the
+ *   guide lines are computed; using a group standalone draws a header with no guides.
+ * - Provide a header icon via the `icon` slot (forwarded to the header row).
+ *
+ * ## Slots
+ *
+ * | Slot Name | Renders When...          | Purpose                                                      |
+ * |-----------|--------------------------|--------------------------------------------------------------|
+ * | icon      | `hasIcon` is true        | Leading icon for the group header row.                       |
+ * | (default) | Always                   | Child rows (`obc-tree-navigation-item` / `-group`).          |
+ *
+ * @slot icon - Leading icon for the group header (shown when `hasIcon` is true).
+ * @slot - Child rows disclosed when the group is expanded.
+ * @fires expand-toggle {CustomEvent<boolean>} Fired when the header is activated; detail is the next `expanded` value.
+ */
+@customElement('obc-tree-navigation-group')
+export class ObcTreeNavigationGroup extends LitElement {
+  /** The text label displayed for the group header row. */
+  @property({type: String}) label = 'Group';
+
+  /**
+   * Guide line to draw for each ancestor level of the header row. Normally set by
+   * the parent `<obc-tree-navigation>` container from the group's position; only
+   * set it manually when using a group outside the container.
+   */
+  @property({type: Array}) branches: TreeBranchType[] = [];
+
+  /** Whether the group is expanded, disclosing its children. Rotates the chevron. */
+  @property({type: Boolean, reflect: true}) expanded = false;
+
+  /** Whether the group header is the current selection. */
+  @property({type: Boolean, reflect: true}) checked = false;
+
+  /** Disables the group header, removing it from the tab order and dimming it. */
+  @property({type: Boolean, reflect: true}) disabled = false;
+
+  /** Whether the group header shows a leading icon (provided via the `icon` slot). */
+  @property({type: Boolean, attribute: false}) hasIcon = true;
+
+  /**
+   * Terminal type for the header row, 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 on the header row. */
+  @property({type: Boolean}) hasAlertBadge = false;
+
+  /** The number shown in the header's alert badge when `hasAlertBadge` is true. */
+  @property({type: Number}) alertCount = 0;
+
+  /** The severity/type of the header's alert badge. One of the `obc-badge` types (default `alarm`). */
+  @property({type: String}) alertType: string = BadgeType.alarm;
+
+  /**
+   * The URL to navigate to when the header is activated. If set, the header row
+   * renders as a link; otherwise it acts as a button.
+   */
+  @property({type: String}) href: string | undefined;
+
+  @query('obc-tree-navigation-item') private headerItem?: ObcTreeNavigationItem;
+
+  private onHeaderToggle(event: CustomEvent<boolean>) {
+    this.expanded = event.detail;
+    this.dispatchEvent(
+      new CustomEvent<boolean>('expand-toggle', {detail: this.expanded})
+    );
+  }
+
+  /** Closes the group (and, recursively, any nested groups inside it). */
+  close() {
+    this.expanded = false;
+    this.querySelectorAll('obc-tree-navigation-group').forEach((group) =>
+      group.close()
+    );
+  }
+
+  public override focus(options?: FocusOptions): void {
+    this.headerItem?.focus(options);
+  }
+
+  override render() {
+    return html`
+      <obc-tree-navigation-item
+        part="header"
+        .label=${this.label}
+        .branches=${this.branches}
+        expandable
+        ?expanded=${this.expanded}
+        ?checked=${this.checked}
+        ?disabled=${this.disabled}
+        .hasLeadingIcon=${this.hasIcon}
+        .terminalType=${this.terminalType}
+        ?hasAlertBadge=${this.hasAlertBadge}
+        .alertCount=${this.alertCount}
+        .alertType=${this.alertType}
+        .href=${this.href}
+        @expand-toggle=${this.onHeaderToggle}
+      >
+        ${this.hasIcon ? html`<slot name="icon" slot="icon"></slot>` : nothing}
+      </obc-tree-navigation-item>
+      <div part="children" role="group" ?hidden=${!this.expanded}>
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  static override styles = unsafeCSS(componentStyle);
+}
+
+export type ObcTreeNavigationGroupExpandToggleEvent = CustomEvent<boolean>;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'obc-tree-navigation-group': ObcTreeNavigationGroup;
+  }
+}

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;
+}