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

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

@@ -0,0 +1,162 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {ObcTreeNavigation} from './tree-navigation.js';
+import './tree-navigation.js';
+import '../tree-navigation-group/tree-navigation-group.js';
+import '../tree-navigation-item/tree-navigation-item.js';
+import {TreeTerminalType} from '../tree-navigation-item/tree-navigation-item.js';
+import {iconIdToIconHtml} from '../../storybook-util.js';
+import {LitElement, html} from 'lit';
+import {state} from 'lit/decorators.js';
+import {customElement} from '../../decorator.js';
+
+/**
+ * `<obc-tree-navigation>` builds the guide lines automatically from the nested
+ * markup. Write groups and items as real nested elements; the container assigns
+ * each row's `branches` from its position. Click a group header to expand or
+ * collapse — the guides recompute to match.
+ */
+const meta: Meta<typeof ObcTreeNavigation> = {
+  title: 'UI Components/Menus and Navigation/Tree Navigation',
+  tags: ['autodocs', '6.0'],
+  component: 'obc-tree-navigation',
+  render: () => html`
+    <obc-tree-navigation>
+      <obc-tree-navigation-group label="Vessel" expanded>
+        ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+        <obc-tree-navigation-group
+          label="Engine room"
+          expanded
+          .terminalType=${TreeTerminalType.aggregatedHeader}
+        >
+          ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          <obc-tree-navigation-item label="Main engine" checked>
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          </obc-tree-navigation-item>
+          <obc-tree-navigation-group
+            label="Auxiliary engine"
+            expanded
+            hasAlertBadge
+            .alertCount=${3}
+          >
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            <obc-tree-navigation-item label="Fuel pump">
+              ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            </obc-tree-navigation-item>
+            <obc-tree-navigation-item
+              label="Starter"
+              hasAlertBadge
+              .alertCount=${1}
+            >
+              ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            </obc-tree-navigation-item>
+            <obc-tree-navigation-item label="Oil filter">
+              ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            </obc-tree-navigation-item>
+          </obc-tree-navigation-group>
+          <obc-tree-navigation-group label="Cooling system" expanded>
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            <obc-tree-navigation-item label="Seawater pump">
+              ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            </obc-tree-navigation-item>
+          </obc-tree-navigation-group>
+        </obc-tree-navigation-group>
+        <obc-tree-navigation-group label="Bridge" expanded>
+          ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          <obc-tree-navigation-item label="Radar">
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          </obc-tree-navigation-item>
+          <obc-tree-navigation-item label="Autopilot" disabled>
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          </obc-tree-navigation-item>
+          <obc-tree-navigation-item label="ECDIS">
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          </obc-tree-navigation-item>
+        </obc-tree-navigation-group>
+        <obc-tree-navigation-item label="Deck">
+          ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+        </obc-tree-navigation-item>
+      </obc-tree-navigation-group>
+      <obc-tree-navigation-item label="Shore power">
+        ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+      </obc-tree-navigation-item>
+    </obc-tree-navigation>
+  `,
+} satisfies Meta<ObcTreeNavigation>;
+
+export default meta;
+type Story = StoryObj<ObcTreeNavigation>;
+
+/**
+ * A fully expanded tree. The guide lines — pass-through verticals, intersections,
+ * and last-child corners — are all computed by the container from the nested
+ * markup. The header rows are groups; the leaves are items.
+ */
+export const Default: Story = {};
+
+/**
+ * `<tree-navigation-selection-demo>` – Wraps the tree to track which leaf is
+ * selected. Selection is purely consumer state: it sets `checked` on the chosen
+ * item; the container still owns all guide-line logic.
+ *
+ * Not exported: Storybook treats every module export as a story, so the demo
+ * element is kept file-local and registered only via the `@customElement` side
+ * effect.
+ */
+@customElement('tree-navigation-selection-demo')
+class TreeNavigationSelectionDemo extends LitElement {
+  @state() private selectedLabel = 'Main engine';
+
+  override createRenderRoot() {
+    return this;
+  }
+
+  private select(label: string) {
+    this.selectedLabel = label;
+  }
+
+  private leaf(label: string) {
+    return html`<obc-tree-navigation-item
+      label=${label}
+      ?checked=${this.selectedLabel === label}
+      @click=${() => this.select(label)}
+    >
+      ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+    </obc-tree-navigation-item>`;
+  }
+
+  override render() {
+    return html`
+      <obc-tree-navigation>
+        <obc-tree-navigation-group label="Vessel" expanded>
+          ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+          <obc-tree-navigation-group label="Engine room" expanded>
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            ${this.leaf('Main engine')} ${this.leaf('Auxiliary engine')}
+            ${this.leaf('Cooling system')}
+          </obc-tree-navigation-group>
+          <obc-tree-navigation-group label="Bridge" expanded>
+            ${iconIdToIconHtml('placeholder', {slot: 'icon'})}
+            ${this.leaf('Radar')} ${this.leaf('Autopilot')}
+          </obc-tree-navigation-group>
+          ${this.leaf('Deck')}
+        </obc-tree-navigation-group>
+      </obc-tree-navigation>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'tree-navigation-selection-demo': TreeNavigationSelectionDemo;
+  }
+}
+
+/**
+ * Click a leaf to select it; click a group chevron to expand or collapse. The
+ * container keeps the guide lines correct through every change — the consumer
+ * only tracks the selected item.
+ */
+export const Interactive: Story = {
+  render: () =>
+    html`<tree-navigation-selection-demo></tree-navigation-selection-demo>`,
+};

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