@zeyos/zx 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -8,6 +8,57 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.0.0 — 2026-08-24
+
+### Added
+
+- **`Card`.** A semantic, product-agnostic content and record surface with optional media, native
+  title link, secondary actions, footer metadata, three variants, horizontal/vertical layout, and
+  exact enhanced-target restoration. The root never impersonates a link or button, so nested
+  controls remain valid and independently keyboard-accessible.
+
+### Changed
+
+- **One public application-navigation component.** `AppSidebar` now owns expanded vertical, minimized
+  vertical, and horizontal rail presentations over one active/branch state model. Descendants are
+  inline only while expanded and use pointer-, focus-, and keyboard-accessible flyouts in rail
+  states; its minimized renderer is an implementation detail, not a second public component.
+- **Richer Select presets.** `Select.priority()` now uses the five-square ZeyOS scale;
+  `Select.status()` adds shape- and semantic-color-distinct workflow states; and the optional
+  `zeyosEntitySelect()` binding adds grouped remote records, module-colored icons, an explicit
+  empty choice, and application-owned command rows without changing the selected-ID contract.
+- **Full launcher parity.** `Launcher` now distinguishes application tiles from record rows,
+  exposes current and pinned state, spatial keyboard movement, visible hints, query-state/source
+  ordering, and injected icon factories. The optional ZeyOS adapter maps all 29 prototype
+  applications, forks/weblets, cached or async recent records, and grouped abortable search while
+  leaving permissions, icons, destinations, and routing with the host application.
+- The documentation now has a global destination search, a clearer uppercase green
+  Presets/Examples hierarchy, and product-agnostic Xenon positioning. The internal rollout guide
+  is no longer shipped or linked from public surfaces.
+
+### Removed
+
+- **The separate `AppRail` constructor.** Use `AppSidebar` with `collapsed: true` for a vertical
+  rail or `orientation: 'horizontal'` for a horizontal rail. This completes the single-owner
+  navigation contract instead of maintaining two public root-DOM models.
+- **Public gx compatibility entry points and bundles.** The compact `__()` DOM builder is part of
+  the Zx core; gx adapter source remains repository-internal and is no longer exported, built, or
+  included in the npm package.
+
+### Fixed
+
+- Late Launcher sources preserve the current keyboard choice only while completing the same query;
+  a new query resets to its own best match.
+- Card rejects control-obfuscated unsafe URL schemes; Launcher and every AppSidebar presentation
+  strip executable/data destinations and disable inert descriptors. AppSidebar also relocates focus,
+  emits its effective collapse state across layout changes, and releases obsolete mode listeners.
+- Card restores an enhanced target after failed construction, releases callbacks when links or
+  actions are replaced, and keeps the full non-interactive body inside the primary-link target.
+- Status shortcut hints now activate their options, async permission group loaders cannot be
+  disconnected by a filter override, and enhanced billing grids restore every target attribute.
+- Billing totals now distinguish a missing operand from an explicit zero, and Chart renders a
+  consistent error state for falsy payloads and errors without a message.
+
 ## 3.0.0 — 2026-08-24
 
 ### Added

package/DESIGN-SYSTEM.md

@@ -1,8 +1,9 @@
-# Xenon design-system audit
+# Xenon Design System
 
-Audit date: 2026-08-24. Xenon is the design system; Zx is its dependency-free JavaScript
-implementation. This document records the current coverage against ZeyOS Classic and the work
-needed for an incremental adoption that keeps the existing routing and business logic.
+Xenon is a product-agnostic design system for browser applications; Zx is its dependency-free
+JavaScript implementation. It provides shared foundations, accessible components, interaction
+patterns, and application layouts without taking ownership of an application's routing or domain
+logic.
 
 ## System boundary
 
@@ -16,66 +17,48 @@ Xenon has four layers:
 4. **Application layouts** — rails, bars, workspaces, master/detail, dashboards, inboxes, wizards,
    and responsive shell geometry.
 
-This separation follows the enterprise-system intent described by the
-[Carbon Design System](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) and
-[SAP Fiori design principles](https://experience.sap.com/fiori-design-web/design-principles/),
-without copying either system's code, assets, or component contracts.
+This separation keeps foundations, components, patterns, and layouts independently reusable while
+preserving a coherent API and visual language.
 
-Zx currently has more than 50 public component classes, 63 registered documentation/demo entries,
-a generated API reference, bundled local icons, and no runtime dependency. The foundations,
-component layer, and persistent application shell now cover the first ZeyOS adoption wave; domain
-patterns remain intentionally application-owned until their business invariants are specified.
-
-## ZeyOS adoption boundary
-
-ZeyOS Classic does not use `gx`. Across its 30 module files it has roughly 2,500 `UI.*` calls and
-2,600 `PG.*` calls. `PG` already owns navigation, transport, history, exit guards, and page
-lifecycle and remains authoritative.
-
-The existing compact DOM surface has 2,668 executable builder calls: 871 bare `__()` calls, 1,710
-parent-returning `parent.__()` calls, and 87 child-returning `parent.$__()` calls. Zx now provides
-the exact compact builder plus pure append/property/event helpers. Existing global and prototype
-names remain application-owned delegation seams; Zx does not install or replace them.
-
-Migration therefore replaces `UI.new*` implementations one family at a time, keeps their current
-DOM/value contracts until call sites reach zero, and leaves `PG`, `MD`, routes, and server payloads
-in place. See [MIGRATION.md](./MIGRATION.md) for the ordering and shell invariants.
+Zx has a generated API reference, live examples, bundled local icons, and no runtime dependency.
+Its compact `__()` DOM builder and pure append/property/event helpers let established applications
+adopt the system without introducing a framework runtime. Domain policy, transport, persistence,
+and navigation remain application-owned.
 
 ## Coverage ledger
 
-| Capability in current ZeyOS | Xenon/Zx status | Decision |
+| Front-end capability | Xenon/Zx status | Design-system boundary |
 | --- | --- | --- |
-| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Replace `UI.new*` families incrementally and preserve value/event contracts. |
+| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Components preserve native semantics and expose consistent value/event contracts. |
 | Forms and fieldsets | Covered, including component-backed field adapters | Use for record editors; keep validation/business rules application-owned. |
 | Dialogs, sheets, dropdowns, context menus, tooltips, messages | Covered | Consolidate duplicate menu behavior before building account/launcher surfaces. |
 | Tabs, panels, toolbar, breadcrumbs, stepper, split view, dock | Covered | Compose layouts; do not let navigation components own routes. |
 | Sorting, selection, filtering, pagination, trees/finder | Covered | Suitable for generic data screens. |
 | Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes typed editable currency/unit columns and flat hierarchy over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
-| Global launcher/search | Covered | `Launcher` combines ranked local applications with abortable grouped sources. ZeyOS still filters the catalogue and resolves selection through `PG`. |
-| Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. ZeyOS supplies role-filtered actions and owns preferences, authentication, and logout. |
-| Persistent app rail / side navigation | Covered | `AppSidebar` is the expanded vertical tree; minimized `AppRail` uses flyouts in every orientation. Both are route- and persistence-agnostic. |
+| Global launcher/search | Covered | `Launcher` combines an application grid, current/pinned state, recent records, and abortable grouped sources. The optional ZeyOS adapter maps the complete 29-app shell catalogue while the host retains permissions, icons, and routing. |
+| Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. The host supplies permitted actions and owns preferences, authentication, and logout. |
+| Persistent app rail / side navigation | Covered | One route-agnostic `AppSidebar` owns expanded, minimized, and horizontal presentations. Only expanded vertical branches render inline; every rail presentation uses flyouts. |
 | Charts and analytical summaries | Covered through an adapter | `Chart` is engine-neutral and accessible; `ChartJsAdapter` accepts an injected Chart.js 4 engine. Chart.js is documentation/test tooling only. |
 | Local product/module icons | Partial | Use bundled icons or registered local assets; do not require the optional remote Font Awesome kit. |
-| Domain entity selectors/cards/links | Partial | Build patterns on `Select`, Table, Panel, and ContextMenu after the shell blockers. |
+| Domain entity selectors/cards/links | Covered at generic presentation level | `Card` provides media, native primary links, secondary actions, and metadata; applications own entity routing and policy. |
 | Persistent notification/activity center | Missing, lower priority | `Message` covers ephemeral feedback, not read/unread activity history. |
 
 ### Launcher contract
 
-The current launcher searches applications, recent records, and grouped remote record types. A
-replacement supplies pinned-order ranking, request cancellation, Cmd/Ctrl+K, listbox keyboard
-behavior, native link metadata, and a cancelable action. Permission filtering, active-route state,
-cache and recent-history policy remain inputs from ZeyOS, which resolves actions through `PG.go()`.
-The component is deliberately not a second router.
+The launcher searches applications, recent records, and grouped remote record types. The generic
+component supplies the tile/list layouts, pinned-order ranking, current-route marker, request
+cancellation, spatial keyboard movement, visible keyboard hints, native link metadata, and a
+cancelable action. The optional ZeyOS adapter accepts all 29 prototype modules plus forks and
+weblets, cached or async recent items, grouped legacy search payloads, permission/current state,
+and host icon renderers. All state is injected; the adapter reads no shell globals and deliberately
+does not become a second router.
 
 ### Account contract
 
-The current account surface includes identity, role-dependent links, language, authentication and
-logout, theme and menu-position preferences, and About/version content. A shared `Menu` should
-first centralize the keyboard/typeahead/selection behavior currently duplicated by `MenuButton`
-and `ContextMenu`; `AccountMenu` then composes that primitive with `Avatar`/`Identity` and emits
-actions without owning routes or session state. `AccountMenu` now provides that composition over
-`MenuButton`; a future shared low-level `Menu` remains an internal consolidation opportunity, not
-an adoption blocker.
+A typical account surface includes identity, role-dependent links, language, authentication and
+logout, preferences, and About/version content. `AccountMenu` composes `Avatar` with the existing
+menu behavior and emits actions without owning routes or session state. The host decides which
+actions exist and what each one does.
 
 ## Table and transaction follow-ups
 
@@ -111,26 +94,3 @@ owns loading/empty/error states, and mirrors its data in an accessible table. Ch
 default adapter; Frappe Charts remains the lean ERP-oriented alternative, uPlot a specialized
 time-series candidate, and ECharts an opt-in advanced adapter. Any additional package still
 requires explicit dependency approval.
-
-## Review corrections completed
-
-- Generated API records no longer let helper typedefs overwrite component options; inline JSDoc
-  tags are parsed, and audited runtime events are present in types and documentation.
-- Form documentation exposes `Form`, `Fieldset`, and `Field`; `MonthPicker` has its own constructor
-  type.
-- Theme Studio destroys registered component instances on every rebuild and describes its honest
-  family-level coverage.
-- Documentation separates Presets from green-accent Examples and uses callable preset names.
-- Current source and documentation no longer carry branding from the retired framework experiment.
-
-## Recommended sequence
-
-1. Ship the Zx runtime and delegate the current compact DOM/event seams; verify no navigation or
-   listener regressions.
-2. Mount `Launcher`, `Avatar`/`AccountMenu`, and `AppSidebar`/`AppRail` behind the current shell
-   fixtures, permission filters, and preference store.
-3. Replace high-volume `UI.new*` families, one discriminating fixture set at a time.
-4. Introduce `Grid.BillingItems()` where its generic schema fits; add domain presets only with
-   formula and rounding fixtures.
-5. Inject Chart.js into `ChartJsAdapter` only on analytical surfaces that need it; keep the engine
-   out of the base Zx runtime bundle.

package/README.md

@@ -1,10 +1,10 @@
 # Xenon Design System (Zx)
 
-Xenon is the dependency-free design system for ZeyOS business applications; Zx is its
-vanilla-JavaScript implementation. It combines foundations, accessible components, repeatable
-workflow patterns, and application layouts in plain ES2022 modules. Source modules run directly in
-a browser; the distribution also provides ESM and classic-script bundles. An opt-in compatibility
-layer remains available for genuine MooTools-era `gx` applications while they are modernised.
+Xenon is a dependency-free design system for browser applications; Zx is its vanilla-JavaScript
+implementation. It combines foundations, accessible components, repeatable workflow patterns,
+and application layouts in plain ES2022 modules. Source modules run directly in a browser; the
+distribution also provides ESM and classic-script bundles. Xenon originated at ZeyOS, while its
+components and contracts remain product- and framework-agnostic.
 
 The [design-system audit](./DESIGN-SYSTEM.md) records current ZeyOS coverage, missing shell
 patterns, the adoption boundary, transaction-grid follow-ups, and chart-engine candidates.
@@ -41,15 +41,15 @@ For an application built from classic scripts, the IIFE bundle exposes the same
 </script>
 ```
 
-Import one component instead of the library when a bundler is doing the work:
+Import a component source module directly when a bundler needs the narrowest possible graph:
 
 ```js
 import { Slider } from '@zeyos/zx/src/components/slider/slider.js';
 ```
 
-An application using two components bundles 26 kB minified this way against 157 kB through the
-package entry point. Load the one stylesheet either way — it is 13 kB gzipped whole, and splitting
-it per component costs more than it saves.
+The package also exposes the bundled ESM entry for ordinary named imports. Load the complete
+stylesheet either way: it contains the shared tokens and cross-component states that make the
+system coherent, while JavaScript can still be tree-shaken or imported component by component.
 
 TypeScript definitions ship with the package. They are generated from the JSDoc that documents
 every option, method, and event, so `new Slider(null, { … })` is checked against `SliderOptions`
@@ -99,7 +99,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `Toggle` | Native-button switch with a separate submitted value. |
 | `Search` | Search input with debounced input, submit, and clear events. |
 | `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
-| `Select` | APG combobox with local or async filtering, pinned fixed items, and priority/permission presets. |
+| `Select` | APG combobox with local or async filtering, pinned items, priority/status/permission presets, and an optional ZeyOS entity picker. |
 | `Checklist` | Searchable checkbox group with optional async loading. |
 | `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
 | `NumberField` | APG spinbutton with step buttons, ranges, units, and wrapping. |
@@ -158,12 +158,12 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | API | Description |
 | --- | --- |
 | `Groupbox` | Collapsible section backed by native `<details>`. |
+| `Card` | Semantic content/record surface with media, native title link, actions, and footer. |
 | `Panel` | Framed, optionally collapsible section with a footer. |
 | `MasterPanel` | Full-height application panel with fixed header actions and footer. |
 | `Tabbox` | APG tabs in four appearances, with lazy content, closing, badges, and disabled states. |
 | `NavigationBar` | Responsive application navigation with optional tab panels and overflow. |
-| `AppSidebar` | Expanded vertical application navigation with inline disclosure children. |
-| `AppRail` | Minimized vertical/horizontal application navigation with flyout-only descendants. |
+| `AppSidebar` | Expanded or minimized vertical application navigation plus horizontal rails; descendants are inline only while expanded. |
 | `Toolbar` | APG toolbar: one tab stop, arrow-key movement, and overflow into a menu. |
 | `SplitView` | Resizable two-pane split with a keyboard-operable separator. |
 | `Stepper` | Linear multi-step progress with completed, active, and error states. |
@@ -297,7 +297,7 @@ classic-script distribution tests.
 
 ```sh
 npm test           # Node unit tests plus semantic-token lint
-npm run build      # writes ESM, global, compatibility, and CSS assets to dist/
+npm run build      # writes ESM, ZeyOS, global, CSS, and declaration assets to dist/
 npm run build:site # assembles the deployable documentation site into site/
 npm run serve:site # serves site/ exactly as it will be deployed
 ```
@@ -313,28 +313,7 @@ import { Table, Message } from '@zeyos/zx';
 import '@zeyos/zx/zx.css';
 ```
 
-Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding), `@zeyos/zx/compat`
-(the gx compatibility namespace), and `@zeyos/zx/global` for classic script tags.
+Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding) and
+`@zeyos/zx/global` for classic script tags.
 
-Documentation lives at <https://zx.zeyos.com>; see `docs/RELEASING.md` for how the site and the
-package are published.
-
-## `gx` compatibility layer
-
-During an incremental migration, load the global API before the compatibility bundle:
-
-```html
-<link rel="stylesheet" href="/assets/zx.css">
-<script src="/assets/zx.global.js"></script>
-<script src="/assets/zx-compat.global.js"></script>
-<script>
-  // Only for gx-era free functions; an existing ZeyOS __() is preserved:
-  gx.compat.installGlobals();
-</script>
-```
-
-The compatibility bundle always exposes `window.gx` and installs only the element
-`store`/`retrieve`/`eliminate` shim automatically. Legacy globals and prototype conveniences are
-an explicit opt-in through `gx.compat.installGlobals()`; it never replaces an existing `__`.
-See [MIGRATION.md](./MIGRATION.md) for
-class mappings, script replacement, deliberate behavior changes, and unsupported legacy APIs.
+Documentation lives at <https://zx.zeyos.com>.

package/dist/types/components/app-sidebar/app-sidebar.d.ts

@@ -1,7 +1,7 @@
 import { Component } from '../../core/component.js';
-import { AppRail } from '../app-rail/app-rail.js';
-export type AppNavItem = import('../app-rail/app-rail.js').AppNavItem;
-export type AppNavSelectDetail = import('../app-rail/app-rail.js').AppNavSelectDetail;
+import { AppRailPresenter as MinimizedPresenter } from '../../internal/app-rail.js';
+export type AppNavItem = import('../../internal/app-rail.js').AppNavItem;
+export type AppNavSelectDetail = import('../../internal/app-rail.js').AppNavSelectDetail;
 export type AppSidebarOptions = {
     /**
      * Application navigation tree.
@@ -16,13 +16,21 @@ export type AppSidebarOptions = {
      */
     expanded?: Array<string | number>;
     /**
-     * Whether the minimized AppRail is shown.
+     * Whether the minimized presentation is shown.
      */
     collapsed?: boolean;
     /**
-     * Workspace side.
+     * Whether vertical navigation exposes a mode toggle.
      */
-    side?: 'left' | 'right';
+    collapsible?: boolean;
+    /**
+     * Navigation flow; horizontal is always minimized.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Workspace edge occupied by navigation.
+     */
+    side?: 'left' | 'right' | 'top' | 'bottom';
     /**
      * Navigation accessible label.
      */
@@ -40,23 +48,35 @@ export type AppSidebarOptions = {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized rail header content.
+     * Minimized leading content.
      */
     railHeader?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized rail footer content.
+     * Minimized trailing content.
      */
     railFooter?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
+    /**
+     * Minimized flyout hover-open delay.
+     */
+    openDelay?: number;
+    /**
+     * Minimized flyout crossing grace.
+     */
+    closeDelay?: number;
+    /**
+     * Optional host icon renderer.
+     */
+    renderIcon?: (item: AppNavItem, context: Record<string, any>) => Node | null;
     /**
      * Preventable action listener.
      */
     onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
     /**
-     * Branch-state listener; bulk replacement reports null state.
+     * Branch-state listener.
      */
     onbranchchange?: (event: CustomEvent<{
         item: AppNavItem | null;
@@ -70,58 +90,79 @@ export type AppSidebarOptions = {
     oncollapsechange?: (event: CustomEvent<{
         collapsed: boolean;
     }>) => void;
+    /**
+     * Minimized flyout-state listener.
+     */
+    onflyoutchange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        open: boolean;
+    }>) => void;
 };
-/** @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 declare class AppSidebar extends Component<AppSidebarOptions> {
+    _rail: MinimizedPresenter;
     _railExpandButton: HTMLElement;
-    _rail: AppRail;
     _createdRoot: boolean;
     _original: {
         attributes: string[][];
         children: ChildNode[];
     };
-    _items: import("../app-rail/app-rail.js").AppNavItem[];
+    _items: import("../../internal/app-rail.js").AppNavItem[];
     _active: string | number;
     _expanded: Set<string>;
     _collapsed: boolean;
+    _orientation: any;
+    _side: "bottom" | "left" | "right" | "top";
+    _modeAbort: AbortController;
     static cssName: string;
     /** @type {Readonly<AppSidebarOptions>} */
     static defaults: Readonly<AppSidebarOptions>;
     /**
-     * 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?: Element | string | null, options?: AppSidebarOptions);
     /** @returns {HTMLElement} */
     render(): HTMLElement;
-    /** 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: AppNavItem[]): 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(): AppNavItem[];
+    /** Sets the active id without routing. @param {string|number|null} id @returns {this} */
     setActive(id: string | number | null): this;
     /** Replaces expanded branch ids. @param {Array<string|number>} ids @param {{silent?: boolean}} [options={}] @returns {this} */
     setExpanded(ids: Array<string | number>, { silent }?: {
@@ -133,30 +174,62 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     toggleBranch(id: string | number, { silent }?: {
         silent?: boolean;
     }): 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?: {
         silent?: boolean;
     }): this;
-    /** Shows the minimized AppRail presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    /** Shows the minimized presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
     collapse(options?: {
         silent?: boolean;
     }): this;
-    /** 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: boolean, { silent }?: {
         silent?: boolean;
     }): this;
-    /** Reports whether the rail presentation is active. @returns {boolean} */
+    /** Reports the effective presentation state; horizontal navigation is always minimized. @returns {boolean} */
     isCollapsed(): boolean;
-    /** Returns the composed minimized rail. @returns {AppRail} */
-    getRail(): AppRail;
-    /** Destroys the rail and restores/removes the sidebar host. @returns {void} */
+    /**
+     * 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?: {
+        orientation?: 'vertical' | 'horizontal';
+        side?: 'left' | 'right' | 'top' | 'bottom';
+    }, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Opens a minimized descendant flyout. @param {string|number} id @param {{focus?: boolean}} [options={}] @returns {this} */
+    openFlyout(id: string | number, options?: {
+        focus?: boolean;
+    }): this;
+    /** Closes a minimized descendant flyout. @param {string|number} id @returns {this} */
+    closeFlyout(id: string | number): this;
+    /** Closes every minimized flyout. @returns {this} */
+    closeAllFlyouts(): this;
+    /** Reports whether a minimized flyout is open. @param {string|number} id @returns {boolean} */
+    isFlyoutOpen(id: string | number): boolean;
+    /** Focuses the first navigation action. @returns {this} */
+    focus(): this;
+    /** Destroys flyouts and restores/removes the host. @returns {void} */
     destroy(): void;
+    /** Mounts exactly one expanded tree or minimized flyout presentation. @returns {void} */
+    _renderMode(): void;
+    /** @returns {void} */
+    _renderExpanded(): void;
+    /** @returns {void} */
+    _renderRail(): void;
+    /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
+    _listenMode(target: EventTarget, type: string, listener: EventListener): void;
     /** @returns {void} */
     _renderTree(): void;
     /** @param {AppNavItem} item @param {number} level @returns {HTMLElement} */
     _treeRow(item: AppNavItem, level: number): HTMLElement;
-    /** Handles dynamic tree controls without retaining detached nodes after a rerender. @param {Event} event @returns {void} */
+    /** @param {Event} event @returns {void} */
     _onTreeClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onTreeKeydown(event: KeyboardEvent): void;
     /** @param {AppNavItem} item @param {Event} event @returns {void} */
     _select(item: AppNavItem, event: Event): void;
     /** @returns {void} */
@@ -167,3 +240,4 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
 /** 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}>} */