@zeyos/zx 3.0.0 → 4.0.0

package/src/components/app-sidebar/app-sidebar.js

@@ -2,32 +2,42 @@ import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import { uid } from '../../core/util.js';
-import { AppRail, normalizeAppItems } from '../app-rail/app-rail.js';
+import {
+  AppRailPresenter as MinimizedPresenter, appNavIcon, normalizeAppItems
+} from '../../internal/app-rail.js';
 
-/** @typedef {import('../app-rail/app-rail.js').AppNavItem} AppNavItem */
-/** @typedef {import('../app-rail/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
+/** @typedef {import('../../internal/app-rail.js').AppNavItem} AppNavItem */
+/** @typedef {import('../../internal/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
 /**
  * @typedef {Object} AppSidebarOptions
  * @property {AppNavItem[]} [items=[]] Application navigation tree.
  * @property {string|number|null} [active=null] Active item id.
  * @property {Array<string|number>} [expanded=[]] Initially expanded branch ids.
- * @property {boolean} [collapsed=false] Whether the minimized AppRail is shown.
- * @property {'left'|'right'} [side='left'] Workspace side.
+ * @property {boolean} [collapsed=false] Whether the minimized presentation is shown.
+ * @property {boolean} [collapsible=true] Whether vertical navigation exposes a mode toggle.
+ * @property {'vertical'|'horizontal'} [orientation='vertical'] Navigation flow; horizontal is always minimized.
+ * @property {'left'|'right'|'top'|'bottom'} [side='left'] Workspace edge occupied by navigation.
  * @property {string} [label='Applications'] Navigation accessible label.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [header=null] Expanded header content.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Expanded sticky footer content.
- * @property {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized rail header content.
- * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized rail footer content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized leading content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized trailing content.
+ * @property {number} [openDelay=80] Minimized flyout hover-open delay.
+ * @property {number} [closeDelay=160] Minimized flyout crossing grace.
+ * @property {(item: AppNavItem, context: Record<string, any>) => Node|null} [renderIcon] Optional host icon renderer.
  * @property {(event: CustomEvent<AppNavSelectDetail>) => void} [onselect] Preventable action listener.
- * @property {(event: CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>) => void} [onbranchchange] Branch-state listener; bulk replacement reports null state.
+ * @property {(event: CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>) => void} [onbranchchange] Branch-state listener.
  * @property {(event: CustomEvent<{collapsed: boolean}>) => void} [oncollapsechange] Presentation-state listener.
+ * @property {(event: CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>) => void} [onflyoutchange] Minimized flyout-state listener.
  */
 
 /**
- * Expanded vertical application navigation; the only Xenon shell mode with inline descendants.
+ * One application navigation component. Vertical expanded descendants render inline; minimized
+ * vertical and horizontal descendants use pointer-, focus-, and keyboard-accessible flyouts.
  * @fires AppSidebar#select
  * @fires AppSidebar#branchchange
  * @fires AppSidebar#collapsechange
+ * @fires AppSidebar#flyoutchange
  * @extends {Component<AppSidebarOptions>}
  */
 export class AppSidebar extends Component {
@@ -39,48 +49,29 @@ export class AppSidebar extends Component {
     active: null,
     expanded: [],
     collapsed: false,
+    collapsible: true,
+    orientation: 'vertical',
     side: 'left',
     label: 'Applications',
     header: null,
     footer: null,
     railHeader: null,
-    railFooter: null
+    railFooter: null,
+    openDelay: 80,
+    closeDelay: 160,
+    renderIcon: null
   };
 
   /**
-   * Creates or enhances an application-sidebar host.
-   * @param {Element|string|null} target Sidebar target.
-   * @param {AppSidebarOptions} [options={}] Sidebar options.
+   * Creates or enhances an application-navigation host.
+   * @param {Element|string|null} [target=null] Navigation target.
+   * @param {AppSidebarOptions} [options={}] Navigation options.
    */
   constructor(target = null, options = {}) {
     super(target, options);
-    this.listen(this.refs.rail, 'zx-select', (event) => event.stopPropagation());
-    const expandButton = h('button', {
-      class: 'zx-app-sidebar__rail-toggle zx-icon-btn',
-      type: 'button',
-      ariaLabel: 'Expand application sidebar'
-    }, icon(this.el.dataset.side === 'right' ? 'chevron-left' : 'chevron-right'));
-    this._railExpandButton = expandButton;
-    const railHeader = h('div', { class: 'zx-app-sidebar__rail-header' }, expandButton);
-    appendSlot(railHeader, this.options.railHeader);
-    this._rail = new AppRail(this.refs.rail, {
-      items: this._items,
-      active: this._active,
-      orientation: 'vertical',
-      side: this.el.dataset.side,
-      label: this.options.label,
-      header: railHeader,
-      footer: this.options.railFooter,
-      onselect: (event) => {
-        const selected = this.emit('select', event.detail);
-        if (selected.defaultPrevented) event.preventDefault();
-      }
-    });
-    this.listen(expandButton, 'click', () => {
-      this.expand();
-    });
-    this._renderTree();
-    this.setCollapsed(Boolean(this.options.collapsed), { silent: true });
+    this._rail = null;
+    this._railExpandButton = null;
+    this._renderMode();
   }
 
   /** @returns {HTMLElement} */
@@ -94,49 +85,38 @@ export class AppSidebar extends Component {
     };
     this._items = normalizeAppItems(this.options.items);
     this._active = this.options.active;
-    this._expanded = new Set(Array.isArray(this.options.expanded) ? this.options.expanded.map(String) : []);
+    this._expanded = new Set(Array.isArray(this.options.expanded)
+      ? this.options.expanded.map(String) : []);
     this._collapsed = Boolean(this.options.collapsed);
-    root.dataset.side = this.options.side === 'right' ? 'right' : 'left';
-
-    const headerContent = h('div', { class: 'zx-app-sidebar__header-content' });
-    appendSlot(headerContent, this.options.header);
-    const collapseButton = h('button', {
-      ref: 'collapse',
-      class: 'zx-app-sidebar__collapse zx-icon-btn',
-      type: 'button',
-      ariaLabel: 'Minimize application sidebar'
-    }, icon(root.dataset.side === 'right' ? 'chevron-right' : 'chevron-left'));
-    const footer = h('footer', { class: 'zx-app-sidebar__footer' });
-    appendSlot(footer, this.options.footer);
-    footer.hidden = !footer.hasChildNodes();
-    const expanded = h('div', { ref: 'expanded', class: 'zx-app-sidebar__expanded' },
-      h('header', { class: 'zx-app-sidebar__header' }, headerContent, collapseButton),
-      h('nav', { class: 'zx-app-sidebar__nav', ariaLabel: this.options.label },
-        h('ul', { ref: 'list', class: 'zx-app-sidebar__list' })),
-      footer);
-    const rail = h('div', { ref: 'rail', class: 'zx-app-sidebar__rail' });
-    root.replaceChildren(expanded, rail);
-    this.listen(collapseButton, 'click', () => {
-      this.collapse();
-    });
-    this.listen(this.refs.list, 'click', (event) => this._onTreeClick(event));
+    this._orientation = this.options.orientation === 'horizontal' ? 'horizontal' : 'vertical';
+    this._side = normalizeSide(this._orientation, this.options.side);
+    this._modeAbort = null;
+    root.replaceChildren();
     return root;
   }
 
-  /** Replaces the navigation tree in both expanded and rail presentations. @param {AppNavItem[]} items @returns {this} */
+  /** Replaces the navigation tree in the active presentation. @param {AppNavItem[]} items @returns {this} */
   setItems(items) {
     this._items = normalizeAppItems(items);
     this._reconcileExpanded();
-    this._renderTree();
-    this._rail.setItems(this._items);
+    if (this._rail) this._rail.setItems(this._items);
+    else this._renderTree();
     return this;
   }
 
-  /** Sets the active id in both presentations without routing. @param {string|number|null} id @returns {this} */
+  /** Returns a shallow copy of normalized items. @returns {AppNavItem[]} */
+  getItems() {
+    return this._items.map((item) => ({
+      ...item,
+      children: item.children?.map((child) => ({ ...child }))
+    }));
+  }
+
+  /** Sets the active id without routing. @param {string|number|null} id @returns {this} */
   setActive(id) {
     this._active = id;
-    this._syncActive();
-    this._rail.setActive(id);
+    if (this._rail) this._rail.setActive(id);
+    else this._syncActive();
     return this;
   }
 
@@ -144,7 +124,7 @@ export class AppSidebar extends Component {
   setExpanded(ids, { silent = false } = {}) {
     this._expanded = new Set(Array.isArray(ids) ? ids.map(String) : []);
     this._reconcileExpanded();
-    this._renderTree();
+    if (!this._rail) this._renderTree();
     if (!silent) this.emit('branchchange', {
       item: null,
       id: null,
@@ -171,53 +151,122 @@ export class AppSidebar extends Component {
     const expanded = !this._expanded.has(key);
     if (expanded) this._expanded.add(key);
     else this._expanded.delete(key);
-    this._renderTree();
-    if (!silent) this.emit('branchchange', { item, id: item.id, expanded, ids: this.getExpanded() });
+    if (!this._rail) this._renderTree();
+    if (!silent) this.emit('branchchange', {
+      item,
+      id: item.id,
+      expanded,
+      ids: this.getExpanded()
+    });
     return this;
   }
 
-  /** Shows the expanded sidebar presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+  /** Shows the expanded vertical presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
   expand(options = {}) {
     return this.setCollapsed(false, options);
   }
 
-  /** Shows the minimized AppRail presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+  /** Shows the minimized presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
   collapse(options = {}) {
     return this.setCollapsed(true, options);
   }
 
-  /** Sets expanded/minimized presentation while preserving branch state. @param {boolean} collapsed @param {{silent?: boolean}} [options={}] @returns {this} */
+  /** Sets the saved vertical expanded/minimized state. @param {boolean} collapsed @param {{silent?: boolean}} [options={}] @returns {this} */
   setCollapsed(collapsed, { silent = false } = {}) {
-    const next = Boolean(collapsed);
-    const changed = next !== this._collapsed;
+    const previous = this.isCollapsed();
     const active = document.activeElement;
-    const focusRailToggle = next && Boolean(active && this.refs.expanded.contains(active));
-    const focusSidebarToggle = !next && this._rail?._containsNode(active);
-    if (!next) this._rail?.closeAllFlyouts();
-    this._collapsed = next;
-    this.el.dataset.collapsed = String(next);
-    this.refs.expanded.hidden = next;
-    this.refs.rail.hidden = !next;
-    if (focusRailToggle) this._railExpandButton?.focus();
-    else if (focusSidebarToggle) this.refs.collapse.focus();
-    if (changed && !silent) this.emit('collapsechange', { collapsed: next });
+    const outgoingOwnedFocus = Boolean(active
+      && (this.el.contains(active) || this._rail?._containsNode(active)));
+    this._collapsed = Boolean(collapsed);
+    const next = this.isCollapsed();
+    if (previous !== next) {
+      this._renderMode();
+      if (outgoingOwnedFocus) {
+        if (next) this._railExpandButton?.focus();
+        else this.refs.collapse?.focus();
+      }
+      if (!silent) this.emit('collapsechange', { collapsed: next });
+    }
     return this;
   }
 
-  /** Reports whether the rail presentation is active. @returns {boolean} */
+  /** Reports the effective presentation state; horizontal navigation is always minimized. @returns {boolean} */
   isCollapsed() {
-    return this._collapsed;
+    return this._orientation === 'horizontal' || this._collapsed;
+  }
+
+  /**
+   * Changes navigation flow/edge without replacing state.
+   * @param {{orientation?: 'vertical'|'horizontal', side?: 'left'|'right'|'top'|'bottom'}} layout
+   * @param {{silent?: boolean}} [options]
+   * @returns {this}
+   */
+  setLayout(layout = {}, { silent = false } = {}) {
+    const orientation = layout.orientation === 'horizontal' ? 'horizontal'
+      : layout.orientation === 'vertical' ? 'vertical' : this._orientation;
+    const side = normalizeSide(orientation, layout.side ?? this._side);
+    if (orientation === this._orientation && side === this._side) return this;
+    const previous = this.isCollapsed();
+    const active = document.activeElement;
+    const outgoingOwnedFocus = Boolean(active
+      && (this.el.contains(active) || this._rail?._containsNode(active)));
+    const focusedId = outgoingOwnedFocus && active instanceof Element
+      ? active.closest('[data-app-nav-id]')?.getAttribute('data-app-nav-id') ?? null : null;
+    this._orientation = orientation;
+    this._side = side;
+    this._renderMode();
+    const next = this.isCollapsed();
+    if (outgoingOwnedFocus) {
+      const replacement = focusedId === null ? null
+        : [...this.el.querySelectorAll('[data-app-nav-id]')]
+          .find((control) => control.getAttribute('data-app-nav-id') === focusedId) ?? null;
+      if (replacement instanceof HTMLElement) replacement.focus();
+      else if (next) this.focus();
+      else if (this.refs.collapse instanceof HTMLElement && !this.refs.collapse.hidden) {
+        this.refs.collapse.focus();
+      } else visibleTreeControls(this.refs.list)[0]?.focus();
+    }
+    if (previous !== next && !silent) this.emit('collapsechange', { collapsed: next });
+    return this;
+  }
+
+  /** Opens a minimized descendant flyout. @param {string|number} id @param {{focus?: boolean}} [options={}] @returns {this} */
+  openFlyout(id, options = {}) {
+    this._rail?.openFlyout(id, options);
+    return this;
+  }
+
+  /** Closes a minimized descendant flyout. @param {string|number} id @returns {this} */
+  closeFlyout(id) {
+    this._rail?.closeFlyout(id);
+    return this;
+  }
+
+  /** Closes every minimized flyout. @returns {this} */
+  closeAllFlyouts() {
+    this._rail?.closeAllFlyouts();
+    return this;
   }
 
-  /** Returns the composed minimized rail. @returns {AppRail} */
-  getRail() {
-    return this._rail;
+  /** Reports whether a minimized flyout is open. @param {string|number} id @returns {boolean} */
+  isFlyoutOpen(id) {
+    return this._rail?.isFlyoutOpen(id) ?? false;
   }
 
-  /** Destroys the rail and restores/removes the sidebar host. @returns {void} */
+  /** Focuses the first navigation action. @returns {this} */
+  focus() {
+    if (this._rail) this._rail.focus();
+    else visibleTreeControls(this.refs.list)[0]?.focus();
+    return this;
+  }
+
+  /** Destroys flyouts and restores/removes the host. @returns {void} */
   destroy() {
     const original = this._original;
-    this._rail.destroy();
+    this._modeAbort?.abort();
+    this._modeAbort = null;
+    this._rail?.destroy();
+    this._rail = null;
     super.destroy();
     if (!this._createdRoot && original) {
       for (const attribute of Array.from(this.el.attributes)) this.el.removeAttribute(attribute.name);
@@ -226,10 +275,100 @@ export class AppSidebar extends Component {
     }
   }
 
+  /** Mounts exactly one expanded tree or minimized flyout presentation. @returns {void} */
+  _renderMode() {
+    this._modeAbort?.abort();
+    this._modeAbort = new AbortController();
+    this._rail?.destroy();
+    this._rail = null;
+    this._railExpandButton = null;
+    for (const key of ['expanded', 'list', 'collapse', 'rail']) delete this.refs[key];
+    this.el.replaceChildren();
+    this.el.dataset.orientation = this._orientation;
+    this.el.dataset.side = this._side;
+    this.el.dataset.collapsed = String(this.isCollapsed());
+    if (this.isCollapsed()) this._renderRail();
+    else this._renderExpanded();
+  }
+
+  /** @returns {void} */
+  _renderExpanded() {
+    const headerContent = h('div', { class: 'zx-app-sidebar__header-content' });
+    appendSlot(headerContent, this.options.header);
+    const collapseButton = h('button', {
+      class: 'zx-app-sidebar__collapse zx-icon-btn',
+      type: 'button',
+      ariaLabel: 'Minimize application sidebar'
+    }, icon(this._side === 'right' ? 'chevron-right' : 'chevron-left'));
+    collapseButton.hidden = !this.options.collapsible;
+    const footer = h('footer', { class: 'zx-app-sidebar__footer' });
+    appendSlot(footer, this.options.footer);
+    footer.hidden = !footer.hasChildNodes();
+    const list = h('ul', { class: 'zx-app-sidebar__list' });
+    const expanded = h('div', { class: 'zx-app-sidebar__expanded' },
+      h('header', { class: 'zx-app-sidebar__header' }, headerContent, collapseButton),
+      h('nav', { class: 'zx-app-sidebar__nav', ariaLabel: this.options.label }, list),
+      footer);
+    this.refs.expanded = expanded;
+    this.refs.list = list;
+    this.refs.collapse = collapseButton;
+    this.el.append(expanded);
+    this._listenMode(collapseButton, 'click', () => this.collapse());
+    this._listenMode(list, 'click', (event) => this._onTreeClick(event));
+    this._listenMode(list, 'keydown', (event) => this._onTreeKeydown(/** @type {KeyboardEvent} */ (event)));
+    this._renderTree();
+  }
+
+  /** @returns {void} */
+  _renderRail() {
+    const railHost = h('nav', { class: 'zx-app-sidebar__rail' });
+    this.el.append(railHost);
+    this.refs.rail = railHost;
+    const showToggle = this._orientation === 'vertical' && Boolean(this.options.collapsible);
+    const railHeader = h('div', { class: 'zx-app-sidebar__rail-header' });
+    if (showToggle) {
+      const expandButton = h('button', {
+        class: 'zx-app-sidebar__rail-toggle zx-icon-btn',
+        type: 'button',
+        ariaLabel: 'Expand application sidebar'
+      }, icon(this._side === 'right' ? 'chevron-left' : 'chevron-right'));
+      railHeader.append(expandButton);
+      this._railExpandButton = expandButton;
+      this._listenMode(expandButton, 'click', () => this.expand());
+    }
+    appendSlot(railHeader, this.options.railHeader);
+    this._rail = new MinimizedPresenter(railHost, {
+      items: this._items,
+      active: this._active,
+      orientation: this._orientation,
+      side: this._side,
+      label: this.options.label,
+      header: railHeader.hasChildNodes() ? railHeader : null,
+      footer: this.options.railFooter,
+      openDelay: this.options.openDelay,
+      closeDelay: this.options.closeDelay,
+      renderIcon: this.options.renderIcon,
+      onselect: (event) => {
+        const selected = this.emit('select', event.detail);
+        if (selected.defaultPrevented) event.preventDefault();
+      },
+      onflyoutchange: (event) => this.emit('flyoutchange', event.detail)
+    });
+    this._listenMode(railHost, 'zx-select', (event) => event.stopPropagation());
+    this._listenMode(railHost, 'zx-flyoutchange', (event) => event.stopPropagation());
+  }
+
+  /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
+  _listenMode(target, type, listener) {
+    target.addEventListener(type, listener, { signal: this._modeAbort.signal });
+  }
+
   /** @returns {void} */
   _renderTree() {
+    if (!this.refs.list) return;
     const focused = this.refs.list.contains(document.activeElement)
-      ? /** @type {Element} */ (document.activeElement).closest('[data-app-nav-id]')?.getAttribute('data-app-nav-id')
+      ? /** @type {Element} */ (document.activeElement).closest('[data-app-nav-id]')
+        ?.getAttribute('data-app-nav-id')
       : null;
     this.refs.list.replaceChildren(...this._items.map((item) => this._treeRow(item, 1)));
     this._syncActive();
@@ -247,7 +386,14 @@ export class AppSidebar extends Component {
     const key = String(item.id);
     const expanded = hasChildren && this._expanded.has(key);
     const childId = hasChildren ? uid('zx-app-sidebar-branch') : null;
-    const control = navControl(item, hasChildren, expanded, childId);
+    const visual = appNavIcon(item, this.options.renderIcon, {
+      orientation: this._orientation,
+      collapsed: false,
+      side: this._side,
+      level,
+      location: level === 1 ? 'root' : 'inline'
+    });
+    const control = navControl(item, hasChildren, expanded, childId, visual);
     const row = h('li', {
       class: 'zx-app-sidebar__row',
       dataset: { level }
@@ -262,7 +408,7 @@ export class AppSidebar extends Component {
     return row;
   }
 
-  /** Handles dynamic tree controls without retaining detached nodes after a rerender. @param {Event} event @returns {void} */
+  /** @param {Event} event @returns {void} */
   _onTreeClick(event) {
     const control = /** @type {Element|null} */ (event.target)?.closest?.('[data-app-nav-id]');
     if (!control || !this.refs.list.contains(control)) return;
@@ -275,6 +421,43 @@ export class AppSidebar extends Component {
     else this._select(item, event);
   }
 
+  /** @param {KeyboardEvent} event @returns {void} */
+  _onTreeKeydown(event) {
+    const current = /** @type {Element|null} */ (event.target)?.closest?.('[data-app-nav-id]');
+    if (!(current instanceof HTMLElement)) return;
+    const item = findItem(this._items, current.getAttribute('data-app-nav-id'));
+    const controls = visibleTreeControls(this.refs.list);
+    const index = controls.indexOf(current);
+    if (event.key === 'ArrowRight' && item?.children?.length) {
+      event.preventDefault();
+      if (!this._expanded.has(String(item.id))) this.toggleBranch(item.id);
+      else visibleTreeControls(current.parentElement?.querySelector('.zx-app-sidebar__sublist'))[0]?.focus();
+      return;
+    }
+    if (event.key === 'ArrowLeft') {
+      if (item?.children?.length && this._expanded.has(String(item.id))) {
+        event.preventDefault();
+        this.toggleBranch(item.id);
+        return;
+      }
+      const parentList = current.closest('.zx-app-sidebar__sublist');
+      const parentControl = parentList?.parentElement?.querySelector(':scope > [data-app-nav-id]');
+      if (parentControl instanceof HTMLElement) {
+        event.preventDefault();
+        parentControl.focus();
+      }
+      return;
+    }
+    let nextIndex;
+    if (event.key === 'Home') nextIndex = 0;
+    else if (event.key === 'End') nextIndex = controls.length - 1;
+    else if (event.key === 'ArrowDown') nextIndex = Math.min(controls.length - 1, index + 1);
+    else if (event.key === 'ArrowUp') nextIndex = Math.max(0, index - 1);
+    else return;
+    event.preventDefault();
+    controls[nextIndex]?.focus();
+  }
+
   /** @param {AppNavItem} item @param {Event} event @returns {void} */
   _select(item, event) {
     if (item.disabled) {
@@ -297,15 +480,15 @@ export class AppSidebar extends Component {
 
   /** @returns {void} */
   _syncActive() {
+    if (!this.refs.list) return;
     const activeId = this._active == null ? null : String(this._active);
     for (const control of this.refs.list.querySelectorAll('[data-app-nav-id]')) {
       const item = findItem(this._items, control.getAttribute('data-app-nav-id'));
       const direct = activeId !== null && control.getAttribute('data-app-nav-id') === activeId;
       const descendant = activeId !== null && item
         ? containsItemId(item.children ?? [], activeId) : false;
-      if (direct) {
-        control.setAttribute('aria-current', 'page');
-      } else control.removeAttribute('aria-current');
+      if (direct) control.setAttribute('aria-current', 'page');
+      else control.removeAttribute('aria-current');
       if (descendant) control.dataset.activeDescendant = 'true';
       else delete control.dataset.activeDescendant;
     }
@@ -314,13 +497,15 @@ export class AppSidebar extends Component {
   /** @returns {void} */
   _reconcileExpanded() {
     const branchIds = new Set();
-    walkItems(this._items, (item) => { if (item.children?.length) branchIds.add(String(item.id)); });
+    walkItems(this._items, (item) => {
+      if (item.children?.length) branchIds.add(String(item.id));
+    });
     for (const id of this._expanded) if (!branchIds.has(id)) this._expanded.delete(id);
   }
 }
 
-/** @param {AppNavItem} item @param {boolean} disclosure @param {boolean} expanded @param {string|null} controls @returns {HTMLElement} */
-function navControl(item, disclosure, expanded, controls) {
+/** @param {AppNavItem} item @param {boolean} disclosure @param {boolean} expanded @param {string|null} controls @param {Node|null} visual @returns {HTMLElement} */
+function navControl(item, disclosure, expanded, controls, visual) {
   const tag = item.href && !disclosure ? 'a' : 'button';
   return /** @type {HTMLElement} */ (h(tag, {
     class: 'zx-app-sidebar__item',
@@ -332,14 +517,21 @@ function navControl(item, disclosure, expanded, controls) {
     ariaControls: controls,
     dataset: { appNavId: String(item.id) }
   },
-  item.icon ? h('span', { class: 'zx-app-sidebar__item-icon', ariaHidden: 'true' }, icon(item.icon)) : null,
+  visual ? h('span', { class: 'zx-app-sidebar__item-icon', ariaHidden: 'true' }, visual) : null,
   h('span', { class: 'zx-app-sidebar__item-label' }, item.label),
   item.badge != null ? h('span', { class: 'zx-app-sidebar__item-badge' }, String(item.badge)) : null,
   disclosure ? h('span', { class: 'zx-app-sidebar__item-disclosure', ariaHidden: 'true' },
     icon(expanded ? 'chevron-down' : 'chevron-right')) : null));
 }
 
-/** Returns a control or the nearest owning disclosure when that control is inside a collapsed branch. @param {Element|null} control @returns {HTMLElement|null} */
+/** @param {Element|null|undefined} root @returns {HTMLElement[]} */
+function visibleTreeControls(root) {
+  if (!root) return [];
+  return /** @type {HTMLElement[]} */ ([...root.querySelectorAll('[data-app-nav-id]')]
+    .filter((control) => !control.closest('.zx-app-sidebar__sublist[hidden]')));
+}
+
+/** Returns a control or its nearest owning disclosure when inside a collapsed branch. @param {Element|null} control @returns {HTMLElement|null} */
 function visibleTreeControl(control) {
   let candidate = /** @type {HTMLElement|null} */ (control);
   while (candidate) {
@@ -350,7 +542,7 @@ function visibleTreeControl(control) {
   return null;
 }
 
-/** @param {AppNavItem[]} items @param {string|number} id @returns {AppNavItem|null} */
+/** @param {AppNavItem[]} items @param {string|number|null} id @returns {AppNavItem|null} */
 function findItem(items, id) {
   for (const item of items) {
     if (String(item.id) === String(id)) return item;
@@ -376,13 +568,21 @@ function containsItemId(items, id) {
 /** @param {Element} target @param {unknown} content @returns {void} */
 function appendSlot(target, content) {
   if (content == null) return;
-  if (typeof content === 'string' || typeof content === 'number') target.append(document.createTextNode(String(content)));
-  else if (typeof content === 'object' && typeof content.toElement === 'function') {
+  if (typeof content === 'string' || typeof content === 'number') {
+    target.append(document.createTextNode(String(content)));
+  } else if (typeof content === 'object' && typeof content.toElement === 'function') {
     const element = content.toElement();
     if (element) target.append(element);
   } else if (typeof content === 'object' && typeof content.nodeType === 'number') target.append(content);
 }
 
+/** @param {'vertical'|'horizontal'} orientation @param {unknown} side @returns {'left'|'right'|'top'|'bottom'} */
+function normalizeSide(orientation, side) {
+  if (orientation === 'horizontal') return side === 'bottom' ? 'bottom' : 'top';
+  return side === 'right' ? 'right' : 'left';
+}
+
 /** Fired when a destination/action is activated. @event AppSidebar#select @type {CustomEvent<AppNavSelectDetail>} */
 /** Fired when an inline branch changes. @event AppSidebar#branchchange @type {CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>} */
 /** Fired when expanded/minimized presentation changes. @event AppSidebar#collapsechange @type {CustomEvent<{collapsed: boolean}>} */
+/** Fired when a minimized flyout changes. @event AppSidebar#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */