@nexterajs/ui 0.0.1 → 0.1.0

package/types/nexterajs-ui-shell.d.ts

@@ -0,0 +1,294 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, TemplateRef } from '@angular/core';
+import { Params } from '@angular/router';
+import { NxeStatusFamily } from '@nexterajs/ui/display';
+import { NxeMessageKey } from '@nexterajs/ui/core';
+
+/**
+ * One entry of the side navigation.
+ *
+ * - A **link** has `route` (router) or `href` (plain anchor).
+ * - A **parent** has `children`: it is a disclosure button, not a link. Its children appear under it
+ *   when it is open, and it opens by itself when one of them is the current page.
+ * - A **group** has `heading: true` and `children`: a non-interactive heading, with its items in a
+ *   labelled list under it. Groups sit at the top level; items inside them nest as deep as needed.
+ * - An entry with none of those is a plain button; `itemClick` reports it.
+ */
+interface NxeNavItem {
+    /** Unique within the tree. Keys the open state and the DOM ids. */
+    readonly id: string;
+    /** What the entry says. Translate it. */
+    readonly label: string;
+    /**
+     * The icon, named for `<i class="nxe-icon nxe-icon-NAME">`, or, when the app supplies an
+     * `ng-template[nxeSidenavIcon]`, any key that template maps to an icon. An entry without one
+     * shows the first letter of its label so a collapsed rail is still usable.
+     */
+    readonly icon?: string;
+    /** Router link: a URL (`'/buyer/inbox'`) or commands (`['/buyer/price-lists', id]`). */
+    readonly route?: string | unknown[];
+    /** Query parameters for `route`. When set they take part in the active match. */
+    readonly queryParams?: Params;
+    /** A plain `href`, for a link that leaves the app. Never shown as the current page. */
+    readonly href?: string;
+    /** A count, or a signal of one (read in the template, so it updates without a new tree). */
+    readonly badge?: number | Signal<number | null | undefined>;
+    /** Colour of the badge; `danger` by default. */
+    readonly badgeFamily?: NxeStatusFamily;
+    /** Spoken name of the badge ("5 items need action"); defaults to the number. */
+    readonly badgeLabel?: string;
+    /** Children of a parent entry, or the items of a group. */
+    readonly children?: readonly NxeNavItem[];
+    /** Make this a group heading; its `children` are the group's items. */
+    readonly heading?: boolean;
+    /** Not interactive, not focusable, announced as disabled. */
+    readonly disabled?: boolean;
+    /**
+     * Match the URL exactly. Without it an entry is the current page for its URL and everything
+     * below it (`/buyer/purchase-orders` for `/buyer/purchase-orders/42`). Give the home entry
+     * (`/buyer`) `exact: true`, or it is current everywhere.
+     */
+    readonly exact?: boolean;
+}
+/** `docked`: beside the content, expanded or a rail. `drawer`: off-canvas, over the content. */
+type NxeShellMode = 'docked' | 'drawer';
+/**
+ * What `nxe-topbar` and `nxe-sidenav` need from the `nxe-shell` around them, through
+ * {@link NXE_SHELL}. Both also work without a shell; they then do not toggle anything.
+ */
+interface NxeShellState {
+    readonly mode: Signal<NxeShellMode>;
+    /** The sidenav is a narrow icon rail (docked and collapsed). */
+    readonly rail: Signal<boolean>;
+    /** Docked: the user's collapsed choice. */
+    readonly collapsed: Signal<boolean>;
+    /** The drawer is on screen (drawer mode and open). */
+    readonly drawerShown: Signal<boolean>;
+    /** DOM id of the projected `nxe-sidenav`, for `aria-controls`. */
+    readonly sidenavId: Signal<string | null>;
+    setCollapsed(collapsed: boolean): void;
+    /** Hamburger: open or close the drawer, or collapse or expand the dock. */
+    toggleNavigation(): void;
+    closeDrawer(): void;
+}
+/** Provided by `nxe-shell` to the topbar and sidenav projected into it. */
+declare const NXE_SHELL: InjectionToken<NxeShellState>;
+/**
+ * `<ng-template nxeSidenavIcon let-item>` inside `nxe-sidenav` draws the icon of every entry that
+ * has an `icon`, given the entry. Use it to map `icon` keys to your own SVGs:
+ *
+ * ```html
+ * <nxe-sidenav [items]="items">
+ *     <ng-template nxeSidenavIcon let-item>
+ *         <svg viewBox="0 0 24 24"><path [attr.d]="paths[item.icon]" /></svg>
+ *     </ng-template>
+ * </nxe-sidenav>
+ * ```
+ */
+declare class NxeSidenavIconDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeSidenavIconDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NxeSidenavIconDirective, "ng-template[nxeSidenavIcon]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * `nxe-shell` is the page frame of an application: an optional banner, the topbar, the sidenav and
+ * the main content.
+ *
+ * ```html
+ * <nxe-shell [(collapsed)]="collapsed">
+ *     <sb-impersonation-banner nxeShellBanner />
+ *     <nxe-topbar>...</nxe-topbar>
+ *     <nxe-sidenav [items]="items" />
+ *     <router-outlet />
+ * </nxe-shell>
+ * ```
+ *
+ * **Slots.** `[nxeShellBanner]` (full width above the topbar, for a banner that must stay on screen),
+ * an `nxe-topbar`, an `nxe-sidenav`, and everything else, which goes in the `<main>` landmark. A
+ * "Skip to content" link, the first tab stop, jumps to that `<main>`.
+ *
+ * **Responsive.** The shell measures its own width. At or above `breakpoint` (960px by default, the
+ * design system's `md`) the sidenav is docked beside the content, expanded or, when `collapsed`, an
+ * icon rail. Below it the sidenav is an off-canvas drawer over the content with a scrim: the
+ * topbar's toggle button opens it, focus is trapped inside while it is open, Esc and a click on the
+ * scrim close it, a navigation closes it, and focus returns to the control that opened it.
+ * Widening the shell past the breakpoint closes the drawer.
+ *
+ * The shell is as tall as `--nxe-shell-height` (default `100dvh`): give it the height of the space
+ * it fills, and the content scrolls inside `<main>`.
+ */
+declare class NxeShellComponent implements NxeShellState {
+    private readonly host;
+    private readonly messages;
+    private readonly router;
+    private readonly injector;
+    private readonly focusTrapFactory;
+    /** Docked sidenav shows only icons. Two-way: `[(collapsed)]`. */
+    readonly collapsed: _angular_core.ModelSignal<boolean>;
+    /** The off-canvas drawer is open (only meaningful below the breakpoint). Two-way: `[(drawerOpen)]`. */
+    readonly drawerOpen: _angular_core.ModelSignal<boolean>;
+    /** Shell width, in CSS px, from which the sidenav is docked rather than a drawer. */
+    readonly breakpoint: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Skip-link target id; unique per shell. */
+    protected readonly mainId: string;
+    private readonly sidenav;
+    /** Own width, kept by a ResizeObserver; the window's until the first measurement. */
+    private readonly width;
+    readonly mode: _angular_core.Signal<NxeShellMode>;
+    readonly rail: _angular_core.Signal<boolean>;
+    readonly drawerShown: _angular_core.Signal<boolean>;
+    readonly sidenavId: _angular_core.Signal<string | null>;
+    private trap;
+    private returnFocusTo;
+    constructor();
+    setCollapsed(collapsed: boolean): void;
+    /** The hamburger: the drawer below the breakpoint, the dock's collapsed state above it. */
+    toggleNavigation(): void;
+    closeDrawer(): void;
+    protected t(key: 'shell.skipToContent'): string;
+    protected skipToContent(event: Event): void;
+    protected onEscape(event: Event): void;
+    private onDrawerShown;
+    private onDrawerHidden;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeShellComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeShellComponent, "nxe-shell", never, { "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "drawerOpen": { "alias": "drawerOpen"; "required": false; "isSignal": true; }; "breakpoint": { "alias": "breakpoint"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; "drawerOpen": "drawerOpenChange"; }, ["sidenav"], ["[nxeShellBanner]", "nxe-topbar", "nxe-sidenav", "*"], true, never>;
+}
+
+/**
+ * `nxe-sidenav` is the application's primary navigation, drawn from a tree of {@link NxeNavItem}.
+ *
+ * ```html
+ * <nxe-sidenav [items]="items" (itemClick)="track($event)">
+ *     <img nxeSidenavHeader src="logo.svg" alt="Nextera" />
+ * </nxe-sidenav>
+ * ```
+ *
+ * **Structure and ARIA.** A `<nav>` landmark holding nested lists, in the pattern the ARIA Authoring
+ * Practices call a *disclosure navigation menu*: a link is `<a aria-current="page">` when it is the
+ * current page; a parent is a `<button aria-expanded aria-controls>` that shows or hides the list
+ * under it; a group heading labels its list (`aria-labelledby`). It is deliberately not
+ * `role="tree"`: a tree makes one node focusable and needs the full tree keyboard contract, where
+ * every link here is an ordinary tab stop and the arrow keys are a shortcut on top of Tab.
+ *
+ * **Keyboard.** Tab and Shift+Tab visit every link and parent. On a link or parent, Arrow Down/Up
+ * move to the next/previous visible entry, Home/End to the first/last. Arrow Right opens a closed
+ * parent, or moves into an open one's first child; Arrow Left closes an open parent, or moves from
+ * a child to its parent (Right and Left swap in a right-to-left document). Enter and Space activate.
+ *
+ * **Current page.** From the router: an entry is current when its URL matches (a prefix, or the
+ * whole URL with `exact`), and when several do, the most specific one alone is `aria-current`
+ * (`/payments/aging` over `/payments`). The parents of the current page open themselves on
+ * navigation; what the user opened or closed by hand holds until the next navigation into it.
+ *
+ * **Collapsed rail.** With the sidenav collapsed (through `nxe-shell` or the `collapsed` model) only
+ * the icons show, each with its label as a native `title` and as visually-hidden text, and a badge
+ * pins to the icon. There is no flyout for children (that waits for the menu): activating a parent
+ * in the rail expands the rail with that parent open.
+ *
+ * Inside an `nxe-shell` the shell owns the collapsed state and the off-canvas drawer; on its own the
+ * sidenav is a plain docked column.
+ */
+declare class NxeSidenavComponent {
+    private readonly router;
+    private readonly messages;
+    private readonly shell;
+    /** The sidenav's own element; `nxe-shell` traps focus in it while the drawer is open. */
+    readonly element: HTMLElement;
+    private readonly navElement;
+    /** DOM id, which the topbar's toggle button names in `aria-controls`. */
+    readonly id: string;
+    /** The navigation tree. */
+    readonly items: _angular_core.InputSignal<readonly NxeNavItem[]>;
+    /** Accessible name of the `<nav>` landmark; "Main navigation" in the active language by default. */
+    readonly label: _angular_core.InputSignal<string>;
+    /**
+     * Collapsed to the icon rail. Inside an `nxe-shell` the shell's `collapsed` wins and this is
+     * left alone; the sidenav writes the user's choice through the shell instead.
+     */
+    readonly collapsed: _angular_core.ModelSignal<boolean>;
+    /** Show the collapse/expand button at the foot of a docked sidenav. Default true. */
+    readonly collapsible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** An entry was activated: a link followed, a plain button pressed. Parents do not emit. */
+    readonly itemClick: _angular_core.OutputEmitterRef<NxeNavItem>;
+    /** Draws the icon of every entry that has an `icon`. */
+    protected readonly iconTemplate: _angular_core.Signal<TemplateRef<any> | undefined>;
+    protected readonly navLabel: _angular_core.Signal<string>;
+    protected readonly rail: _angular_core.Signal<boolean>;
+    protected readonly drawer: _angular_core.Signal<boolean>;
+    protected readonly drawerOpen: _angular_core.Signal<boolean>;
+    /** Every entry by id, with its place in the tree and the URL it points at. */
+    private readonly nodes;
+    /** The router's URL, re-read at every navigation so what is current is a signal. */
+    private readonly url;
+    /** Id of the one entry that is the current page. */
+    private readonly currentId;
+    /** Ids of the parents above the current page. They open by themselves. */
+    private readonly currentAncestors;
+    /**
+     * What the user opened or closed by hand. Navigating to a new page forgets the choices about
+     * its ancestors, so they open for it, and keeps the rest.
+     */
+    private readonly manual;
+    protected t(key: NxeMessageKey): string;
+    protected isCurrent(id: string): boolean;
+    /** The current page is somewhere under this parent. */
+    protected holdsCurrent(id: string): boolean;
+    protected isOpen(id: string): boolean;
+    protected hasChildren(item: NxeNavItem): boolean;
+    protected badgeValue(item: NxeNavItem): number | null | undefined;
+    protected badgeName(item: NxeNavItem): string;
+    protected initial(item: NxeNavItem): string;
+    /** Toggle a parent; in the rail, expand the rail with the parent open instead. */
+    protected onParent(item: NxeNavItem): void;
+    protected onActivate(item: NxeNavItem): void;
+    protected toggleCollapsed(): void;
+    protected closeDrawer(): void;
+    protected onKeydown(event: KeyboardEvent, item: NxeNavItem): void;
+    /** Links and parent buttons in document order; the ones inside a closed parent are not rendered. */
+    private focusables;
+    private setOpen;
+    private setCollapsed;
+    private treeOf;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeSidenavComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeSidenavComponent, "nxe-sidenav", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; "itemClick": "itemClick"; }, ["iconTemplate"], ["[nxeSidenavHeader]", "[nxeSidenavFooter]"], true, never>;
+}
+
+/**
+ * `nxe-topbar` is the bar across the top of an `nxe-shell`: a start, a centre and an end slot.
+ *
+ * ```html
+ * <nxe-topbar>
+ *     <img nxeTopbarStart src="logo.svg" alt="Nextera" />
+ *     <sb-search nxeTopbarCenter />
+ *     <ng-container nxeTopbarEnd>
+ *         <sb-company-switcher />
+ *         <sb-notifications />
+ *     </ng-container>
+ * </nxe-topbar>
+ * ```
+ *
+ * The start slot is preceded by a hamburger button: an icon-only `nxe-button` named "Toggle
+ * navigation" with `aria-controls` the sidenav and `aria-expanded` the sidenav's state. Inside an
+ * `nxe-shell` it opens and closes the drawer below the breakpoint and collapses and expands the dock
+ * above it. `menuToggle` also fires, so a topbar used without a shell can drive its own sidenav.
+ * `[nxeTopbarEnd]` elements sit at the inline end of the bar, where a company switcher, language
+ * toggle, notification bell and user menu go.
+ */
+declare class NxeTopbarComponent {
+    private readonly messages;
+    private readonly shell;
+    /** Show the hamburger button. Default true. */
+    readonly menuButton: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The hamburger was pressed. */
+    readonly menuToggle: _angular_core.OutputEmitterRef<void>;
+    protected readonly label: _angular_core.Signal<string>;
+    protected readonly controls: _angular_core.Signal<string | null>;
+    /** Drawer: open. Dock: not collapsed. Without a shell the button says nothing about it. */
+    protected readonly expanded: _angular_core.Signal<boolean | null>;
+    protected toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeTopbarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeTopbarComponent, "nxe-topbar", never, { "menuButton": { "alias": "menuButton"; "required": false; "isSignal": true; }; }, { "menuToggle": "menuToggle"; }, never, ["[nxeTopbarStart]", "[nxeTopbarCenter]", "[nxeTopbarEnd]"], true, never>;
+}
+
+export { NXE_SHELL, NxeShellComponent, NxeSidenavComponent, NxeSidenavIconDirective, NxeTopbarComponent };
+export type { NxeNavItem, NxeShellMode, NxeShellState };

package/types/nexterajs-ui-styling.d.ts

@@ -1,10 +1,12 @@
 import { OverlayRef } from '@angular/cdk/overlay';
 import { Subscription } from 'rxjs';
+import * as i0 from '@angular/core';
+import { EnvironmentProviders, OnInit, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 
 /**
  * Marker class carried by every nxe surface — component hosts and CDK overlay panes alike.
  *
- * It is the nxe counterpart of DevExtreme's `.dx-widget` base and is what gives a surface its
+ * It is the nxe counterpart of DevExtreme's `.nxe-widget` base and is what gives a surface its
  * font family/size/weight/line-height (see styling/_widget.scss).
  *
  * It matters most on overlays: a CDK pane is appended to `<body>`, so a portaled dropdown
@@ -30,11 +32,169 @@ declare function nxePane(...extra: (string | null | undefined)[]): string[];
  *
  * DevExtreme drew dropdowns flush against the editor — no border on the shared edge — and moved
  * that seam to the other side when the popup flipped up
- * (`.dx-overlay-content.dx-dropdowneditor-overlay-flipped { border-top-width:1px; border-bottom-width:0 }`).
+ * (`.nxe-overlay-content.nxe-dropdowneditor-overlay-flipped { border-top-width:1px; border-bottom-width:0 }`).
  * CDK does not emit any equivalent hook, so panels need this to reproduce it.
  *
  * Returns the subscription; callers dispose it with the overlay.
  */
 declare function trackPaneFlip(overlayRef: OverlayRef): Subscription | undefined;
 
-export { NXE_PANE_FLIPPED_CLASS, NXE_WIDGET_CLASS, nxePane, trackPaneFlip };
+/**
+ * Migration aid: re-emit the old `dx-*` class names alongside the library's `nxe-*` ones.
+ *
+ * The library dropped the `dx-` prefix from its DOM. Applications that still style themselves
+ * with rules like `.dx-datagrid .dx-row > td { padding: 4px }` would silently lose that styling,
+ * and no stylesheet can fix it: CSS cannot alias a class, so a rule keyed on `.dx-datagrid` will
+ * never match an element that only says `nxe-datagrid`. The class has to be back on the element.
+ *
+ * So this mirrors them at runtime. Provide it once and unmigrated stylesheets keep working
+ * unchanged; provide nothing and the library costs nothing, which is the point of it being
+ * opt-in. `tools/dx-compat/rewrite-styles.mjs` rewrites an application's own stylesheets when it
+ * is ready to drop the flag — this is a bridge, not a destination.
+ *
+ * ```ts
+ * bootstrapApplication(AppComponent, { providers: [provideNxeDxCompat()] });
+ * ```
+ */
+declare class NxeDxCompatService {
+    private readonly document;
+    private readonly ngZone;
+    private observer?;
+    /** Our own writes retrigger the observer; this stops it chasing its own tail. */
+    private mirroring;
+    start(): void;
+    stop(): void;
+    private onMutations;
+    private mirrorSubtree;
+    /** Keep `dx-x` present exactly while `nxe-x` is, so a removed state class is removed here too. */
+    private mirrorElement;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NxeDxCompatService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NxeDxCompatService>;
+}
+/**
+ * Opt into the `dx-*` compatibility classes. See {@link NxeDxCompatService} for why this is a
+ * runtime mirror rather than a stylesheet.
+ */
+declare function provideNxeDxCompat(): EnvironmentProviders;
+
+/** Where the scroll position sits on each axis: -1 at the start, 1 at the end, 0 in between. */
+interface NxeScrollbarPosition {
+    x: number;
+    y: number;
+}
+/** Scroll geometry of the host element. */
+interface NxeScrollbarGeometry {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The options that map onto this implementation.
+ *
+ * `wheelPropagation` is accepted and ignored: it existed because the original took the wheel over
+ * from the browser and had to decide when to hand it back. Scrolling here is native, so the
+ * browser makes that decision itself — which is what the option was trying to restore.
+ */
+interface NxeScrollbarOptions {
+    suppressScrollX?: boolean;
+    suppressScrollY?: boolean;
+    wheelPropagation?: boolean;
+    /** Rail is hidden below this content overflow, in px. Matches the original's default. */
+    minScrollbarLength?: number;
+    maxScrollbarLength?: number;
+}
+/**
+ * `[nxeScrollbar]` — a container with custom overlay scrollbars.
+ *
+ * This replaces a Perfect Scrollbar wrapper, and reproduces its DOM and its rendering exactly:
+ * two absolutely-positioned rails, each holding a thumb, sized and offset from the host's own
+ * scroll geometry. The stylesheet (`@nexterajs/ui/styles/_scrollbar.scss`) is a value-for-value
+ * port, so applications that restyle the rails keep their appearance unchanged.
+ *
+ * **What is different, deliberately:** the original set `overflow: hidden` and reimplemented
+ * wheel, touch, keyboard and momentum scrolling in JavaScript. Here the element scrolls natively
+ * and only the native scrollbar is hidden — the rails are painted from the `scroll` event. That is
+ * less code and better behaviour on touch and trackpads, and it is invisible: a hidden native
+ * scrollbar takes no layout width, exactly like the overlay rails it replaces.
+ *
+ * The host carries `nxe-scrollbar` while enabled, which is the marker callers branch on.
+ */
+declare class NxeScrollbarDirective implements OnInit, OnChanges, OnDestroy {
+    private readonly elementRef;
+    private readonly zone;
+    private readonly destroyRef;
+    nxeScrollbar: boolean;
+    nxeScrollbarOptions: NxeScrollbarOptions | null;
+    private options;
+    private animation;
+    private railX?;
+    private railY?;
+    private thumbX?;
+    private thumbY?;
+    private resizeObserver?;
+    private mutationObserver?;
+    private scrollingXTimer;
+    private scrollingYTimer;
+    private teardown;
+    private initialised;
+    get element(): HTMLElement;
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    isEnabled(): boolean;
+    /**
+     * Recompute rail and thumb geometry. Call after changing content the directive cannot observe.
+     *
+     * This reproduces the original's arithmetic exactly, down to how it rounds — the requirement was
+     * no visual difference, and each of these is worth a pixel:
+     * - the container is measured from `getBoundingClientRect()` rounded, not from `clientHeight`;
+     * - sizes and offsets are **truncated** (the original ran them through `parseInt`), not rounded;
+     * - `scrollTop` is floored before it is used;
+     * - the thumb offset is clamped so it cannot overhang the end of the rail.
+     */
+    update(): void;
+    /** Kept for parity with the wrapper this replaces; teardown also happens in ngOnDestroy. */
+    destroy(): void;
+    isScrollableX(): boolean;
+    isScrollableY(): boolean;
+    geometry(prefix?: 'scroll' | 'client' | 'offset'): NxeScrollbarGeometry;
+    /** -1 at the start of an axis, 1 at its end, 0 anywhere between. */
+    position(absolute?: boolean): NxeScrollbarPosition;
+    scrollTo(x: number, y?: number, speed?: number): void;
+    scrollToX(x: number, speed?: number): void;
+    scrollToY(y: number, speed?: number): void;
+    scrollToTop(offset?: number, speed?: number): void;
+    scrollToBottom(offset?: number, speed?: number): void;
+    scrollToLeft(offset?: number, speed?: number): void;
+    scrollToRight(offset?: number, speed?: number): void;
+    /**
+     * Bring the first descendant matching `selector` into view.
+     *
+     * `ignoreVisible` skips the scroll when the target already sits inside the viewport less the
+     * offset, so an item that is merely low on screen is not yanked to the top on every change.
+     */
+    scrollToElement(selector: string, offset?: number, ignoreVisible?: boolean, speed?: number): void;
+    /**
+     * Move one axis to `value`, easing over `speed` ms when one is given.
+     *
+     * The easing bails as soon as the position stops matching what it last wrote, so a user who
+     * grabs the wheel mid-flight takes over instead of fighting the animation.
+     */
+    animateScrolling(axis: 'scrollTop' | 'scrollLeft', value: number, speed?: number): void;
+    private init;
+    private buildRail;
+    private onScroll;
+    private bindThumbDrag;
+    /** Only the configured bounds, and only when set — the same shape the original's clamp had. */
+    private clampThumb;
+    private on;
+    private dispose;
+    private cancelAnimation;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NxeScrollbarDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NxeScrollbarDirective, "[nxeScrollbar]", ["nxeScrollbar"], { "nxeScrollbar": { "alias": "nxeScrollbar"; "required": false; }; "nxeScrollbarOptions": { "alias": "nxeScrollbarOptions"; "required": false; }; }, {}, never, never, true, never>;
+    static ngAcceptInputType_nxeScrollbar: boolean | string | null | undefined;
+}
+
+export { NXE_PANE_FLIPPED_CLASS, NXE_WIDGET_CLASS, NxeDxCompatService, NxeScrollbarDirective, nxePane, provideNxeDxCompat, trackPaneFlip };
+export type { NxeScrollbarGeometry, NxeScrollbarOptions, NxeScrollbarPosition };

package/types/nexterajs-ui-tree-view.d.ts

@@ -1,4 +1,5 @@
 import * as _angular_core from '@angular/core';
+import { NxeMessageService } from '@nexterajs/ui/core';
 
 /** A node in the assembled tree (children built from the flat `parentIdExpr` list). */
 interface NxeTreeNode {
@@ -10,6 +11,12 @@ interface NxeTreeNode {
     hasChildren: boolean;
     level: number;
 }
+/** A visible node with the sibling position a flattened tree has to state explicitly. */
+interface NxeTreeRow {
+    node: NxeTreeNode;
+    posInSet: number;
+    setSize: number;
+}
 /** DevExtreme-shaped `onItemClick` payload (consumers read `event.itemData.<field>`). */
 interface NxeTreeItemClickEvent {
     itemData: Record<string, unknown>;
@@ -29,7 +36,10 @@ interface NxeTreeItemClickEvent {
  * keeps reading `event.itemData.url/urlParams/objectName`.
  */
 declare class NxeTreeViewComponent {
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
+    private readonly elementRef;
+    /** The library's runtime-switchable messages. */
+    protected readonly messages: NxeMessageService;
+    readonly dataSource: _angular_core.InputSignal<readonly unknown[] | null | undefined>;
     /** Accepted for parity; this component always assembles a tree from the flat list. */
     readonly dataStructure: _angular_core.InputSignal<"plain" | "tree">;
     readonly keyExpr: _angular_core.InputSignal<string>;
@@ -44,15 +54,27 @@ declare class NxeTreeViewComponent {
     readonly searchMode: _angular_core.InputSignal<"contains" | "startswith" | "equals">;
     /** Accepted for parity (native scrolling is the default here anyway). */
     readonly useNativeScrolling: _angular_core.InputSignal<boolean>;
-    readonly width: _angular_core.InputSignal<string | number>;
+    readonly width: _angular_core.InputSignal<string | number | undefined>;
     readonly onItemClick: _angular_core.OutputEmitterRef<NxeTreeItemClickEvent>;
     readonly expanded: _angular_core.WritableSignal<ReadonlySet<unknown>>;
     readonly selectedKey: _angular_core.WritableSignal<unknown>;
     readonly searchText: _angular_core.WritableSignal<string>;
+    private readonly searchInput;
     /** DevExtreme `.instance` facade — `expandAll()` is the only method used. */
     get instance(): this;
-    protected readonly widthStyle: _angular_core.Signal<string>;
+    protected readonly widthStyle: _angular_core.Signal<string | undefined>;
     private readonly tree;
+    /**
+     * The visible nodes, each with its position among its siblings.
+     *
+     * The tree renders as one flat `<ul>` with indentation rather than nested lists, so a screen
+     * reader cannot infer depth or sibling counts from the DOM. `aria-level`, `aria-setsize` and
+     * `aria-posinset` are what carry that, which makes them required for a flattened tree rather
+     * than optional extras. They are computed during the walk, where the sibling array is already
+     * in hand — reconstructing them from the flat list afterwards is possible but much harder to
+     * read for no gain.
+     */
+    protected readonly visibleRows: _angular_core.Signal<NxeTreeRow[]>;
     /** Flattened list of currently-visible nodes (respects expand state + search). */
     protected readonly visibleNodes: _angular_core.Signal<NxeTreeNode[]>;
     expandAll(): void;
@@ -61,9 +83,39 @@ declare class NxeTreeViewComponent {
     protected toggle(node: NxeTreeNode, event: Event): void;
     protected onNodeClick(node: NxeTreeNode, event: Event): void;
     protected onSearch(event: Event): void;
+    /**
+     * The search box's clear button. dx empties the value and leaves the caret in the box (its
+     * clear button swallows the mouse-down so the input never loses focus); refocusing here covers
+     * the case where focus had already left the input.
+     */
+    protected clearSearch(): void;
+    /**
+     * The node holding the tree's single tab stop.
+     *
+     * A tree is one stop in the tab order, not one per node, so a roving tabindex is part of the
+     * role rather than an extra: `role="tree"` on a list nothing can focus would announce a
+     * structure a keyboard user cannot reach.
+     */
+    protected readonly focusedKey: _angular_core.WritableSignal<unknown>;
+    protected isTabStop(node: NxeTreeNode, index: number): boolean;
+    /**
+     * The node that holds DOM focus right now, or `null` while focus is anywhere else.
+     *
+     * Deliberately not `focusedKey`: that is the roving tab stop and has to outlive a blur, so Tab
+     * comes back to the same node. dx drops `dx-state-focused` the moment focus leaves the node,
+     * and the focused look goes with it — the row colour, and the toggle, which follows the row's
+     * colour only while focused (`color: unset`, dx.light.css). Keyed off focusin/focusout so the
+     * class means exactly what it says.
+     */
+    private readonly focusedNode;
+    protected isFocused(node: NxeTreeNode): boolean;
+    protected onNodeFocus(node: NxeTreeNode): void;
+    protected onNodeBlur(node: NxeTreeNode): void;
+    /** Arrow-key navigation, per the WAI-ARIA tree pattern. */
+    protected onKeydown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeTreeViewComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeTreeViewComponent, "nxe-tree-view", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "dataStructure": { "alias": "dataStructure"; "required": false; "isSignal": true; }; "keyExpr": { "alias": "keyExpr"; "required": false; "isSignal": true; }; "displayExpr": { "alias": "displayExpr"; "required": false; "isSignal": true; }; "parentIdExpr": { "alias": "parentIdExpr"; "required": false; "isSignal": true; }; "rootValue": { "alias": "rootValue"; "required": false; "isSignal": true; }; "expandedExpr": { "alias": "expandedExpr"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "selectByClick": { "alias": "selectByClick"; "required": false; "isSignal": true; }; "searchEnabled": { "alias": "searchEnabled"; "required": false; "isSignal": true; }; "searchMode": { "alias": "searchMode"; "required": false; "isSignal": true; }; "useNativeScrolling": { "alias": "useNativeScrolling"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; }, { "onItemClick": "onItemClick"; }, never, never, true, never>;
 }
 
 export { NxeTreeViewComponent };
-export type { NxeTreeItemClickEvent, NxeTreeNode };
+export type { NxeTreeItemClickEvent, NxeTreeNode, NxeTreeRow };