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

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

@@ -185,3 +185,8 @@
     min-width: 0;
   }
 }
+
+obc-tree-navigation-item.tree {
+  display: block;
+  width: 100%;
+}

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

@@ -6,6 +6,12 @@ import {ifDefined} from 'lit/directives/if-defined.js';
 import '../../icons/icon-arrow-flyout-google.js';
 import {ObcNavigationMenuVariant} from '../navigation-menu/navigation-menu.js';
 import {customElement} from '../../decorator.js';
+import '../tree-navigation-item/tree-navigation-item.js';
+import {
+  TreeBranchType,
+  TreeTerminalType,
+} from '../tree-navigation-item/tree-navigation-item.js';
+import {BadgeType} from '../badge/badge.js';
 
 enum NavigationItemRole {
   Button = 'button',
@@ -142,8 +148,32 @@ export class ObcNavigationItem extends LitElement {
 
   @property({type: Boolean}) hasTrailingIcon = false;
 
+  /** Set by `obc-navigation-menu` in its Tree variant — renders the row as a tree item. */
+  @property({type: Boolean}) treeMode = false;
+
+  /** Indentation columns for tree mode, assigned by `obc-navigation-menu`. */
+  @property({type: Array}) treeBranches: TreeBranchType[] = [];
+
+  /**
+   * Terminal type for the row in the Tree variant — one of `regular` (default),
+   * `aggregated-header`, or `group-header`. Has no effect in the flat variants.
+   */
+  @property({type: String}) terminalType: string = TreeTerminalType.regular;
+
+  /** Whether a trailing alert counter badge is shown (Tree variant only). */
+  @property({type: Boolean}) hasAlertBadge = false;
+
+  /** The number shown in the alert badge when `hasAlertBadge` is true (Tree variant only). */
+  @property({type: Number}) alertCount = 0;
+
+  /** The severity/type of the alert badge — one of the `obc-badge` types (Tree variant only). */
+  @property({type: String}) alertType: string = BadgeType.alarm;
+
   @query('a') private anchorElement?: HTMLAnchorElement;
 
+  // In tree mode the row renders an `obc-tree-navigation-item` instead of an `<a>`.
+  @query('obc-tree-navigation-item') private treeItemElement?: HTMLElement;
+
   /**
    * Fired when the navigation item is clicked (either as a link or button).
    * @fires click {CustomEvent<void>}
@@ -165,7 +195,7 @@ export class ObcNavigationItem extends LitElement {
   }
 
   public override focus(options?: FocusOptions): void {
-    this.anchorElement?.focus(options);
+    (this.treeItemElement ?? this.anchorElement)?.focus(options);
   }
 
   private getItemRole(): NavigationItemRole | undefined {
@@ -188,6 +218,31 @@ export class ObcNavigationItem extends LitElement {
   }
 
   override render() {
+    if (this.treeMode) {
+      // Delegate the whole row to the tree item: it owns focus, keyboard
+      // activation, the checked-inert behavior, and href navigation. Forward its
+      // activation as this item's own `click` so selection wiring is unchanged.
+      return html`
+        <obc-tree-navigation-item
+          class="tree"
+          .label=${this.label}
+          .branches=${this.treeBranches}
+          ?checked=${this.checked}
+          .hasLeadingIcon=${this.hasIcon}
+          .href=${this.href}
+          .terminalType=${this.terminalType}
+          ?hasAlertBadge=${this.hasAlertBadge}
+          .alertCount=${this.alertCount}
+          .alertType=${this.alertType}
+          @click=${this.onClick}
+        >
+          ${this.hasIcon
+            ? html`<slot name="icon" slot="icon"></slot>`
+            : nothing}
+        </obc-tree-navigation-item>
+      `;
+    }
+
     const showFlyout =
       this.group && this.variant !== ObcNavigationMenuVariant.IconOnly;
     const isCompact = this.variant === ObcNavigationMenuVariant.Compact;

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

@@ -100,3 +100,11 @@
   display: flex;
   flex-direction: column;
 }
+
+[part="children"] {
+  display: block;
+}
+
+[part="children"][hidden] {
+  display: none;
+}

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

@@ -4,6 +4,12 @@ import compentStyle from './navigation-item-group.css?inline';
 import {ObcNavigationMenuVariant} from '../navigation-menu/navigation-menu.js';
 import {classMap} from 'lit/directives/class-map.js';
 import {customElement} from '../../decorator.js';
+import '../tree-navigation-item/tree-navigation-item.js';
+import {
+  TreeBranchType,
+  TreeTerminalType,
+} from '../tree-navigation-item/tree-navigation-item.js';
+import {BadgeType} from '../badge/badge.js';
 
 /**
  * `<obc-navigation-item-group>` – A collapsible navigation group component for organizing related navigation items under a single expandable label.
@@ -90,9 +96,47 @@ export class ObcNavigationItemGroup extends LitElement {
 
   @property({type: Boolean}) hasIcon = false;
 
+  /** Set by `obc-navigation-menu` in its Tree variant — renders the group as a tree row. */
+  @property({type: Boolean}) treeMode = false;
+
+  /** Indentation columns for tree mode, assigned by `obc-navigation-menu`. */
+  @property({type: Array}) treeBranches: TreeBranchType[] = [];
+
+  /**
+   * Terminal type for the group header in the Tree variant — one of `regular`
+   * (default), `aggregated-header`, or `group-header`. No effect in flat variants.
+   */
+  @property({type: String}) terminalType: string = TreeTerminalType.regular;
+
+  /** Whether a trailing alert counter badge is shown on the header (Tree variant only). */
+  @property({type: Boolean}) hasAlertBadge = false;
+
+  /** The number shown in the header's alert badge when `hasAlertBadge` is true (Tree variant only). */
+  @property({type: Number}) alertCount = 0;
+
+  /** The severity/type of the header's alert badge — one of the `obc-badge` types (Tree variant only). */
+  @property({type: String}) alertType: string = BadgeType.alarm;
+
+  /** Whether the group starts expanded. Useful for trees that open by default. */
+  @property({type: Boolean}) defaultOpen = false;
+
   @state() private openContainer = false;
 
-  @query('obc-navigation-item') private groupItem?: HTMLElement;
+  // Flat mode renders an `obc-navigation-item` header; tree mode renders an
+  // `obc-tree-navigation-item`. Match whichever is present so `focus()` works in both.
+  @query('obc-navigation-item, obc-tree-navigation-item')
+  private groupItem?: HTMLElement;
+
+  override firstUpdated() {
+    if (this.defaultOpen) {
+      this.openContainer = true;
+    }
+  }
+
+  /** Whether the group is currently open (its children are disclosed). */
+  public get expanded(): boolean {
+    return this.openContainer;
+  }
 
   private onClickGroup() {
     if (this.openContainer) {
@@ -123,6 +167,32 @@ export class ObcNavigationItemGroup extends LitElement {
   }
 
   override render() {
+    if (this.treeMode) {
+      return html`
+        <obc-tree-navigation-item
+          part="header"
+          .label=${this.label}
+          .branches=${this.treeBranches}
+          expandable
+          ?expanded=${this.openContainer}
+          ?checked=${this.checked}
+          .hasLeadingIcon=${this.hasIcon}
+          .terminalType=${this.terminalType}
+          ?hasAlertBadge=${this.hasAlertBadge}
+          .alertCount=${this.alertCount}
+          .alertType=${this.alertType}
+          @expand-toggle=${this.onClickGroup}
+        >
+          ${this.hasIcon
+            ? html`<slot name="icon" slot="icon"></slot>`
+            : nothing}
+        </obc-tree-navigation-item>
+        <div part="children" role="group" ?hidden=${!this.openContainer}>
+          <slot></slot>
+        </div>
+      `;
+    }
+
     return html`
       <obc-navigation-item
         @click=${this.onClickGroup}

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

@@ -252,3 +252,57 @@ export const TestDynamicElementsInSpan: Story = {
     await expect(newItem.variant).toBe(ObcNavigationMenuVariant.Compact);
   },
 };
+
+export const Tree: Story = {
+  args: {
+    variant: ObcNavigationMenuVariant.Tree,
+  },
+  render: (args) => {
+    return html`
+      <obc-navigation-menu
+        .variant=${args.variant}
+        style="position: fixed; top: 0; bottom: 0; left: 0;"
+      >
+        <obc-navigation-item-group
+          slot="main"
+          label="Vessel"
+          hasIcon
+          defaultOpen
+        >
+          <obi-placeholder slot="icon"></obi-placeholder>
+          <obc-navigation-item-group
+            label="Engine room"
+            hasIcon
+            defaultOpen
+            terminalType="aggregated-header"
+          >
+            <obi-placeholder slot="icon"></obi-placeholder>
+            <obc-navigation-item label="Main engine" hasIcon checked>
+              <obi-placeholder slot="icon"></obi-placeholder>
+            </obc-navigation-item>
+            <obc-navigation-item
+              label="Cooling system"
+              hasIcon
+              hasAlertBadge
+              .alertCount=${3}
+            >
+              <obi-placeholder slot="icon"></obi-placeholder>
+            </obc-navigation-item>
+          </obc-navigation-item-group>
+          <obc-navigation-item-group label="Bridge" hasIcon>
+            <obi-placeholder slot="icon"></obi-placeholder>
+            <obc-navigation-item label="Radar" hasIcon>
+              <obi-placeholder slot="icon"></obi-placeholder>
+            </obc-navigation-item>
+            <obc-navigation-item label="Autopilot" hasIcon>
+              <obi-placeholder slot="icon"></obi-placeholder>
+            </obc-navigation-item>
+          </obc-navigation-item-group>
+          <obc-navigation-item label="Deck" hasIcon>
+            <obi-placeholder slot="icon"></obi-placeholder>
+          </obc-navigation-item>
+        </obc-navigation-item-group>
+      </obc-navigation-menu>
+    `;
+  },
+};

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

@@ -4,6 +4,29 @@ import compentStyle from './navigation-menu.css?inline';
 import {ObcNavigationItemGroup} from '../navigation-item-group/navigation-item-group.js';
 import {ObcNavigationItem} from '../navigation-item/navigation-item.js';
 import {customElement} from '../../decorator.js';
+import {
+  ObcTreeNavigationItem,
+  TreeBranchType,
+} from '../tree-navigation-item/tree-navigation-item.js';
+import {
+  TreeRovingNavigator,
+  TreeRovingAdapter,
+} from '../../internal/tree-roving-navigator.js';
+
+/** A nav-menu tree row is either a navigation item or a navigation item group. */
+type NavTreeRow = ObcNavigationItem | ObcNavigationItemGroup;
+
+const NAV_ITEM_TAG = 'obc-navigation-item';
+const NAV_GROUP_TAG = 'obc-navigation-item-group';
+
+function isNavGroup(el: Element): el is ObcNavigationItemGroup {
+  return el.tagName.toLowerCase() === NAV_GROUP_TAG;
+}
+
+function isNavRow(el: Element): el is NavTreeRow {
+  const tag = el.tagName.toLowerCase();
+  return tag === NAV_ITEM_TAG || tag === NAV_GROUP_TAG;
+}
 
 /**
  * `ObcNavigationMenuVariant` – Enumerates the available visual and behavioral variants for `<obc-navigation-menu>`.
@@ -12,6 +35,7 @@ import {customElement} from '../../decorator.js';
  * - `IconOnly`: Compact menu showing only icons (should only be used when no flyouts/submenus are present).
  * - `IconOnlyLarge`: Icon-only menu variant designed for use when flyouts/submenus are present.
  * - `Compact`: Space-saving menu with reduced padding and layout.
+ * - `Tree`: Hierarchical tree — groups expand inline and rows are indented by depth.
  *
  * Use these variants to adapt the navigation menu to different layouts or device sizes.
  */
@@ -20,6 +44,7 @@ export enum ObcNavigationMenuVariant {
   IconOnly = 'icon-only', // Should only be used when no flyouts are present in the navigation menu
   IconOnlyLarge = 'icon-only-large', // Should be used when flyouts are present in the navigation menu
   Compact = 'compact',
+  Tree = 'tree',
 }
 
 /**
@@ -49,6 +74,11 @@ export enum ObcNavigationMenuFlyoutVariant {
  *   - **IconOnly:** Shows only icons for a compact appearance. *Should only be used when no navigation items have sub-items or flyouts.*
  *   - **IconOnlyLarge:** Icon-only mode that supports flyouts/submenus. Use when navigation contains groups or nested items.
  *   - **Compact:** Reduces padding and overall width for a space-saving layout.
+ *   - **Tree:** Renders the same `obc-navigation-item` / `obc-navigation-item-group`
+ *     markup as a hierarchical tree. Groups expand inline (instead of as flyouts),
+ *     rows are indented by depth, multiple branches can stay open at once, and the
+ *     tree-row presentation (alert badge, terminal marker) is available via the
+ *     items' `hasAlertBadge`/`alertCount`/`alertType`/`terminalType` properties.
  * - **Responsive Layout:**
  *   - `smallScreen` property adapts the footer and logo layout for smaller viewports.
  * - **Slot-based Content:**
@@ -71,6 +101,10 @@ export enum ObcNavigationMenuFlyoutVariant {
  * - Use the `Full` variant for standard navigation with both icons and labels.
  * - Use `IconOnly` only when there are no nested groups or flyouts; otherwise, use `IconOnlyLarge` for icon-only navigation with flyout support.
  * - The `Compact` variant is suitable for layouts with limited space or when a minimal navigation appearance is desired.
+ * - Use the `Tree` variant for hierarchical navigation (file trees, nested
+ *   sections). The existing item/group markup is reused unchanged — only the
+ *   `variant` changes. Footer and logo slots remain flat. Mark a group with
+ *   `defaultOpen` to have it start expanded.
  * - Set `smallScreen` to `true` to optimize the layout for smaller devices or responsive breakpoints.
  *
  * **TODO(designer):** Provide additional guidance on when to use each variant and recommended slot content for best usability.
@@ -129,6 +163,7 @@ export class ObcNavigationMenu extends LitElement {
    * - `icon-only`: Compact, icon-only menu (use only when no flyouts/groups are present).
    * - `icon-only-large`: Icon-only menu supporting flyouts/groups.
    * - `compact`: Minimal, space-saving menu.
+   * - `tree`: Hierarchical tree — groups expand inline and rows are indented by depth.
    */
   @property({type: String}) variant: ObcNavigationMenuVariant =
     ObcNavigationMenuVariant.Full;
@@ -148,6 +183,59 @@ export class ObcNavigationMenu extends LitElement {
   private slotObservers: MutationObserver[] = [];
   @state() private hasFooter = false;
 
+  /**
+   * Roving-tabindex + arrow-key navigation for the Tree variant, sharing the
+   * navigator that drives `obc-tree-navigation`. Engaged only while
+   * `variant === Tree` (see `onTreeKeydown`).
+   */
+  private readonly treeNavigator = new TreeRovingNavigator<NavTreeRow>(this, {
+    getRows: () => this.treeRootRows(),
+    childRows: (row) => this.treeChildRows(row),
+    isGroup: (row) => isNavGroup(row),
+    // Read the group's own synchronous open state, not the shadow header's
+    // attribute (which lags a render tick behind a keyboard expand/collapse).
+    isExpanded: (row) => isNavGroup(row) && row.expanded,
+    setExpanded: (row, expanded) => {
+      if (!isNavGroup(row)) return;
+      if (expanded) row.open();
+      else row.close();
+    },
+    innerItem: (row) => this.treeInnerItem(row),
+  } satisfies TreeRovingAdapter<NavTreeRow>);
+
+  /** Top-level tree rows of the main slot (mirrors `assignTreeBranches`'s filter). */
+  private treeRootRows(): NavTreeRow[] {
+    return Array.from(this.children).filter((child): child is NavTreeRow => {
+      if (!isNavRow(child)) return false;
+      const slot = child.getAttribute('slot');
+      return slot === null || slot === 'main';
+    });
+  }
+
+  /** Direct tree-row children of a row, in document order. */
+  private treeChildRows(row: NavTreeRow): NavTreeRow[] {
+    return Array.from(row.children).filter(isNavRow);
+  }
+
+  /** The inline `obc-tree-navigation-item` a tree-mode row renders in its shadow root. */
+  private treeInnerItem(row: NavTreeRow): ObcTreeNavigationItem | null {
+    return (
+      row.shadowRoot?.querySelector<ObcTreeNavigationItem>(
+        'obc-tree-navigation-item'
+      ) ?? null
+    );
+  }
+
+  private onTreeKeydown = (event: KeyboardEvent): void => {
+    if (this.variant !== ObcNavigationMenuVariant.Tree) return;
+    if (this.treeNavigator.handleKeydown(event)) event.preventDefault();
+  };
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.addEventListener('keydown', this.onTreeKeydown);
+  }
+
   findAllElements<T extends Element>(
     el: Element,
     tag: string,
@@ -212,6 +300,7 @@ export class ObcNavigationMenu extends LitElement {
   registerGroup(groups: ObcNavigationItemGroup[]) {
     groups.forEach((group) => {
       group.addEventListener('open', () => {
+        if (this.variant === ObcNavigationMenuVariant.Tree) return;
         groups.forEach((g) => {
           if (g !== group) {
             g.close();
@@ -296,6 +385,7 @@ export class ObcNavigationMenu extends LitElement {
   override disconnectedCallback(): void {
     super.disconnectedCallback();
     this.cleanupSlotObservers();
+    this.removeEventListener('keydown', this.onTreeKeydown);
   }
 
   private handleSlotChange() {
@@ -303,7 +393,68 @@ export class ObcNavigationMenu extends LitElement {
     this.setupSlotObservers();
   }
 
+  private assignTreeBranches(el: Element, depth: number): void {
+    for (const child of el.children) {
+      const tag = child.tagName.toLowerCase();
+      const isItem = tag === 'obc-navigation-item';
+      const isGroup = tag === 'obc-navigation-item-group';
+      if (!isItem && !isGroup) continue;
+      // Top-level rows are slotted; only treeify the main slot. Nested rows have
+      // no slot attribute and always belong to their group's tree.
+      if (depth === 0) {
+        const slot = child.getAttribute('slot');
+        if (slot !== null && slot !== 'main') continue;
+      }
+      const branches: TreeBranchType[] = Array.from(
+        {length: depth},
+        () => TreeBranchType.blank
+      );
+      const row = child as ObcNavigationItem | ObcNavigationItemGroup;
+      row.treeMode = true;
+      row.treeBranches = branches;
+      if (isGroup) {
+        this.assignTreeBranches(child, depth + 1);
+      }
+    }
+  }
+
+  // Reset tree mode on every descendant item/group so switching away from the
+  // Tree variant restores the flat rendering.
+  private clearTreeMode(el: Element): void {
+    for (const child of el.children) {
+      const tag = child.tagName.toLowerCase();
+      const isItem = tag === 'obc-navigation-item';
+      const isGroup = tag === 'obc-navigation-item-group';
+      if (!isItem && !isGroup) continue;
+      const row = child as ObcNavigationItem | ObcNavigationItemGroup;
+      row.treeMode = false;
+      row.treeBranches = [];
+      if (isGroup) {
+        this.clearTreeMode(child);
+      }
+    }
+  }
+
   private setupItems() {
+    if (this.variant === ObcNavigationMenuVariant.Tree) {
+      this.assignTreeBranches(this, 0);
+      // Footer and logo are not part of the tree — keep them as flat full-variant
+      // items (and clear any tree mode left over from the main slot's walk).
+      (['footer', 'logo'] as const).forEach((slot) => {
+        this.findAllItems(this, slot).forEach((item) => {
+          item.treeMode = false;
+          item.treeBranches = [];
+          item.variant = ObcNavigationMenuVariant.Full;
+        });
+      });
+      // Defer so the rows' inline tree-item headers exist before the roving
+      // tabindex is assigned to them.
+      queueMicrotask(() => this.treeNavigator.refresh());
+      return;
+    }
+
+    this.clearTreeMode(this);
+
     const hug =
       this.variant !== ObcNavigationMenuVariant.Full ||
       this.flyoutVariant === ObcNavigationMenuFlyoutVariant.Compact;

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

@@ -0,0 +1,7 @@
+:host {
+  display: block;
+}
+
+[role="tree"] {
+  display: block;
+}

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