@nanahoshi/mona-ui 0.23.0 → 0.23.1

package/fesm2022/nanahoshi-mona-ui-internal.mjs

@@ -1,9 +1,8 @@
 import * as i0 from '@angular/core';
 import { inject, ElementRef, Renderer2, input, effect, Directive } from '@angular/core';
-import { forEach, compact } from '@mirei/ts-collections';
+import { forEach } from '@mirei/ts-collections';
 import { Observable, timer, take, debounceTime, map, merge, scan, filter } from 'rxjs';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { isIterable } from 'rxjs/internal/util/isIterable';
 
 class AttributeBinderDirective {
     #element;
@@ -111,23 +110,16 @@ const hsva2rgba = (hue, saturation, value, alpha) => {
     };
 };
 
+const toHexByte = (value) => {
+    const byte = Math.min(255, Math.max(0, Math.round(value)));
+    return byte.toString(16).padStart(2, "0");
+};
 const rgba2hex = (r, g, b, a) => {
     if (r == null || g == null || b == null || a == null) {
         return "";
     }
-    let rHex = r.toString(16);
-    let gHex = g.toString(16);
-    let bHex = b.toString(16);
-    let aHex = a.toString(16);
-    if (rHex.length == 1)
-        rHex = "0" + rHex;
-    if (gHex.length == 1)
-        gHex = "0" + gHex;
-    if (bHex.length == 1)
-        bHex = "0" + bHex;
-    if (aHex.length == 1)
-        aHex = "0" + aHex;
-    return `#${rHex}${gHex}${bHex}${aHex.toUpperCase() !== "FF" ? aHex : ""}`;
+    const aHex = toHexByte(a);
+    return `#${toHexByte(r)}${toHexByte(g)}${toHexByte(b)}${aHex !== "ff" ? aHex : ""}`;
 };
 
 const rgba2hsla = (red, green, blue, alpha) => {
@@ -179,10 +171,9 @@ const rgba2hsva = (r, g, b, a) => {
     const max = Math.max(r, g, b);
     const min = Math.min(r, g, b);
     let h = 0;
-    let s;
     const v = max;
     const d = max - min;
-    s = max === 0 ? 0 : d / max;
+    const s = max === 0 ? 0 : d / max;
     if (max !== min) {
         if (max === r) {
             h = (g - b) / d + (g < b ? 6 : 0);
@@ -231,7 +222,8 @@ const string2rgba = (rgbText) => {
 
 /**
  * Generates a unique control ID for an element.
- * The ID consists of a prefix, a random hexadecimal string, and a suffix.
+ * The ID consists of the `mona-` prefix followed by a random hexadecimal string.
+ * It contains only characters that are safe in CSS selectors, so it can be used with `querySelector("#…")` unescaped.
  * @param {number} [level=0] - The nesting level of the element. This increases the length of the generated ID.
  * @param {number} [length=7] - The base length of the random part of the ID.
  * @returns {string} A unique control ID string for use for elements.
@@ -245,14 +237,14 @@ const createElementControlId = (level = 0, length = 7) => {
         const randomId = Array.from(array, byte => byte.toString(16).padStart(2, "0"))
             .join("")
             .substring(0, idLength);
-        return `${prefix}:${randomId}:`;
+        return `${prefix}${randomId}`;
     }
     let hex = "";
     const chars = "0123456789abcdef";
     for (let i = 0; i < idLength; i++) {
         hex += chars[Math.floor(Math.random() * 16)];
     }
-    return `${prefix}:${hex}:`;
+    return `${prefix}${hex}`;
 };
 
 function focusElement(host, element) {
@@ -272,7 +264,7 @@ function focusElement(host, element) {
 
 const rxFromResize = (target, options) => {
     return new Observable(observer => {
-        const elements = Array.isArray(target) ? target : [target];
+        const elements = target instanceof Element ? [target] : Array.from(target ?? []);
         for (const element of elements) {
             if (!(element instanceof Element)) {
                 observer.error(new TypeError("target must be an Element or an iterable of Elements"));
@@ -348,18 +340,22 @@ const findScrollableElement = (container) => {
     return null;
 };
 
+const toPixels = (value) => (value != null ? `${value}px` : "");
 const setWindowStyles = (element, settings) => {
     if (!element) {
         return;
     }
-    const classes = isIterable(settings.windowClass) ? [...settings.windowClass] : [settings.windowClass];
-    compact(classes).forEach(className => element.classList.add(className));
-    const minWidth = settings.minWidth ? `${settings.minWidth}px` : "";
-    const minHeight = settings.minHeight ? `${settings.minHeight}px` : "";
-    const maxWidth = settings.maxWidth ? `${settings.maxWidth}px` : "";
-    const maxHeight = settings.maxHeight ? `${settings.maxHeight}px` : "";
-    const top = settings.top ? `${settings.top}px` : `calc(50% - ${element.getBoundingClientRect().height / 2}px)`;
-    const left = settings.left ? `${settings.left}px` : `calc(50% - ${element.getBoundingClientRect().width / 2}px)`;
+    const classes = typeof settings.windowClass === "string" ? [settings.windowClass] : (settings.windowClass ?? []);
+    classes
+        .flatMap(className => (className ?? "").split(/\s+/))
+        .filter(className => className !== "")
+        .forEach(className => element.classList.add(className));
+    const minWidth = toPixels(settings.minWidth);
+    const minHeight = toPixels(settings.minHeight);
+    const maxWidth = toPixels(settings.maxWidth);
+    const maxHeight = toPixels(settings.maxHeight);
+    const top = settings.top != null ? `${settings.top}px` : `calc(50% - ${element.getBoundingClientRect().height / 2}px)`;
+    const left = settings.left != null ? `${settings.left}px` : `calc(50% - ${element.getBoundingClientRect().width / 2}px)`;
     const position = "absolute";
     Object.assign(element.style, { left, maxHeight, maxWidth, minHeight, minWidth, position, top });
 };
@@ -374,7 +370,7 @@ const setWindowStyles = (element, settings) => {
  * @returns A CSS-compliant string value.
  */
 const toCssValue = (value) => {
-    if (value == null || value === "") {
+    if (value == null || (typeof value === "string" && value.trim() === "")) {
         return "";
     }
     if (typeof value === "number" || isFinite(Number(value))) {
@@ -402,8 +398,15 @@ const isNavigationKey = (key) => {
     return NavigationKeysList.includes(key);
 };
 
-const isTypeaheadKey = (key) => {
-    return /^[a-zA-Z0-9\-_\s]$/.test(key);
+/**
+ * Returns whether a `KeyboardEvent.key` value should feed typeahead.
+ * Any single letter or digit in any script counts, plus space, `-` and `_`.
+ */
+const isTypeaheadKey = (key, modifiers) => {
+    if (modifiers?.ctrlKey || modifiers?.metaKey || modifiers?.altKey) {
+        return false;
+    }
+    return /^[\p{L}\p{M}\p{N}\-_\s]$/u.test(key);
 };
 const setupTypeahead = (typeaheadKey$) => {
     const resetTrigger$ = typeaheadKey$.pipe(debounceTime(200), map(() => ({ type: "reset", value: "" })));

package/fesm2022/nanahoshi-mona-ui-locales.mjs

@@ -260,6 +260,7 @@ const AR_SA_MESSAGES = {
         selectRow: (rowNumber) => `تحديد الصف ${formatInteger(rowNumber)}`
     },
     list: {
+        filterList: "تصفية القائمة",
         noData: "لا توجد بيانات"
     },
     listBox: {
@@ -639,6 +640,7 @@ const ES_ES_MESSAGES = {
         selectRow: (rowNumber) => `Seleccionar fila ${rowNumber}`
     },
     list: {
+        filterList: "Filtrar lista",
         noData: "No hay datos"
     },
     listBox: {
@@ -1018,6 +1020,7 @@ const DE_DE_MESSAGES = {
         selectRow: (rowNumber) => `Zeile ${rowNumber} auswählen`
     },
     list: {
+        filterList: "Liste filtern",
         noData: "Keine Daten"
     },
     listBox: {
@@ -1397,6 +1400,7 @@ const FR_FR_MESSAGES = {
         selectRow: (rowNumber) => `Sélectionner la ligne ${rowNumber}`
     },
     list: {
+        filterList: "Filtrer la liste",
         noData: "Aucune donnée"
     },
     listBox: {
@@ -1776,6 +1780,7 @@ const IT_IT_MESSAGES = {
         selectRow: (rowNumber) => `Seleziona riga ${rowNumber}`
     },
     list: {
+        filterList: "Filtra elenco",
         noData: "Nessun dato disponibile"
     },
     listBox: {
@@ -2155,6 +2160,7 @@ const JA_JP_MESSAGES = {
         selectRow: (rowNumber) => `${rowNumber}行目を選択`
     },
     list: {
+        filterList: "リストをフィルター",
         noData: "データがありません"
     },
     listBox: {
@@ -2534,6 +2540,7 @@ const KO_KR_MESSAGES = {
         selectRow: (rowNumber) => `${rowNumber}행 선택`
     },
     list: {
+        filterList: "목록 필터",
         noData: "데이터 없음"
     },
     listBox: {
@@ -2913,6 +2920,7 @@ const PT_BR_MESSAGES = {
         selectRow: (rowNumber) => `Selecionar linha ${rowNumber}`
     },
     list: {
+        filterList: "Filtrar lista",
         noData: "Nenhum dado disponível"
     },
     listBox: {
@@ -3292,6 +3300,7 @@ const ZH_CN_MESSAGES = {
         selectRow: (rowNumber) => `选择第 ${rowNumber} 行`
     },
     list: {
+        filterList: "筛选列表",
         noData: "没有数据"
     },
     listBox: {
@@ -3671,6 +3680,7 @@ const ZH_TW_MESSAGES = {
         selectRow: (rowNumber) => `選取第 ${rowNumber} 個資料列`
     },
     list: {
+        filterList: "篩選清單",
         noData: "沒有資料"
     },
     listBox: {
@@ -4050,6 +4060,7 @@ const TR_TR_MESSAGES = {
         selectRow: (rowNumber) => `${rowNumber}. satırı seç`
     },
     list: {
+        filterList: "Listeyi filtrele",
         noData: "Veri yok"
     },
     listBox: {
@@ -4429,6 +4440,7 @@ const ID_ID_MESSAGES = {
         selectRow: (rowNumber) => `Pilih baris ${rowNumber}`
     },
     list: {
+        filterList: "Saring daftar",
         noData: "Tidak ada data"
     },
     listBox: {
@@ -4837,6 +4849,7 @@ const RU_RU_MESSAGES = {
         selectRow: (rowNumber) => `Выбрать строку ${rowNumber}`
     },
     list: {
+        filterList: "Фильтр списка",
         noData: "Нет данных"
     },
     listBox: {

package/fesm2022/nanahoshi-mona-ui-popup-menu.mjs

@@ -545,7 +545,7 @@ class PopupMenuListComponent {
                 this.#typeaheadKey$.next("");
                 this.handleNavigationKey(e);
             }
-            else if (isTypeaheadKey(e.key)) {
+            else if (isTypeaheadKey(e.key, e)) {
                 e.preventDefault();
                 this.handleTypeaheadKey(e);
             }

package/fesm2022/nanahoshi-mona-ui-tree-view.mjs

@@ -196,7 +196,7 @@ class TreeViewComponent {
         this.treeService.blur$.pipe(takeUntilDestroyed(this.#destroyRef)).subscribe(e => this.blur.emit(e));
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.6", ngImport: i0, type: TreeViewComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.6", type: TreeViewComponent, isStandalone: true, selector: "mona-tree-view", inputs: { animate: { classPropertyName: "animate", publicName: "animate", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, children: { classPropertyName: "children", publicName: "children", isSignal: true, isRequired: false, transformFunction: null }, data: { classPropertyName: "data", publicName: "data", isSignal: true, isRequired: false, transformFunction: null }, hasChildren: { classPropertyName: "hasChildren", publicName: "hasChildren", isSignal: true, isRequired: false, transformFunction: null }, idField: { classPropertyName: "idField", publicName: "idField", isSignal: true, isRequired: false, transformFunction: null }, mode: { classPropertyName: "mode", publicName: "mode", isSignal: true, isRequired: false, transformFunction: null }, parentIdField: { classPropertyName: "parentIdField", publicName: "parentIdField", isSignal: true, isRequired: false, transformFunction: null }, textField: { classPropertyName: "textField", publicName: "textField", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { blur: "blur", focus: "focus", nodeClick: "nodeClick" }, providers: [TreeService], queries: [{ propertyName: "nodeTemplate", first: true, predicate: TreeViewNodeTemplateDirective, descendants: true, read: TemplateRef, isSignal: true }], ngImport: i0, template: "@if (treeService.filterableOptions().enabled) {\n    <div role=\"search\" [attr.aria-label]=\"filterAriaLabel()\">\n        <mona-filter-input\n            [filter]=\"treeService.filterText()\"\n            [debounce]=\"treeService.filterableOptions().debounce\"\n            [placeholder]=\"treeService.filterPlaceholder()\"\n            (filterChange)=\"onFilterChange($event)\"></mona-filter-input>\n    </div>\n}\n<div class=\"flex-1 overflow-auto\">\n    <mona-tree [ariaLabel]=\"ariaLabel()\">\n        @if (nodeTemplate()) {\n            <ng-template monaTreeNodeTemplate let-dataItem let-element=\"element\">\n                <ng-container\n                    [ngTemplateOutlet]=\"nodeTemplate() ?? null\"\n                    [ngTemplateOutletContext]=\"{ $implicit: dataItem, element }\"></ng-container>\n            </ng-template>\n        }\n    </mona-tree>\n</div>\n", dependencies: [{ kind: "component", type: FilterInputComponent, selector: "mona-filter-input", inputs: ["debounce", "filter", "placeholder", "size"], outputs: ["filterChange", "inputBlur", "inputFocus"] }, { kind: "component", type: TreeComponent, selector: "mona-tree", inputs: ["ariaLabel", "data"] }, { kind: "directive", type: TreeNodeTemplateDirective, selector: "ng-template[monaTreeNodeTemplate]" }, { kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }] }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.6", type: TreeViewComponent, isStandalone: true, selector: "mona-tree-view", inputs: { animate: { classPropertyName: "animate", publicName: "animate", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, children: { classPropertyName: "children", publicName: "children", isSignal: true, isRequired: false, transformFunction: null }, data: { classPropertyName: "data", publicName: "data", isSignal: true, isRequired: false, transformFunction: null }, hasChildren: { classPropertyName: "hasChildren", publicName: "hasChildren", isSignal: true, isRequired: false, transformFunction: null }, idField: { classPropertyName: "idField", publicName: "idField", isSignal: true, isRequired: false, transformFunction: null }, mode: { classPropertyName: "mode", publicName: "mode", isSignal: true, isRequired: false, transformFunction: null }, parentIdField: { classPropertyName: "parentIdField", publicName: "parentIdField", isSignal: true, isRequired: false, transformFunction: null }, textField: { classPropertyName: "textField", publicName: "textField", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { blur: "blur", focus: "focus", nodeClick: "nodeClick" }, providers: [TreeService], queries: [{ propertyName: "nodeTemplate", first: true, predicate: TreeViewNodeTemplateDirective, descendants: true, read: TemplateRef, isSignal: true }], ngImport: i0, template: "@if (treeService.filterableOptions().enabled) {\n    <div role=\"search\" [attr.aria-label]=\"filterAriaLabel()\">\n        <mona-filter-input\n            [filter]=\"treeService.filterText()\"\n            [debounce]=\"treeService.filterableOptions().debounce\"\n            [placeholder]=\"treeService.filterPlaceholder()\"\n            (filterChange)=\"onFilterChange($event)\"></mona-filter-input>\n    </div>\n}\n<div class=\"flex-1 overflow-auto\">\n    <mona-tree [ariaLabel]=\"ariaLabel()\">\n        @if (nodeTemplate()) {\n            <ng-template monaTreeNodeTemplate let-dataItem let-element=\"element\">\n                <ng-container\n                    [ngTemplateOutlet]=\"nodeTemplate() ?? null\"\n                    [ngTemplateOutletContext]=\"{ $implicit: dataItem, element }\"></ng-container>\n            </ng-template>\n        }\n    </mona-tree>\n</div>\n", dependencies: [{ kind: "component", type: FilterInputComponent, selector: "mona-filter-input", inputs: ["activeDescendant", "ariaLabel", "controls", "debounce", "filter", "placeholder", "size"], outputs: ["filterChange", "inputBlur", "inputFocus"] }, { kind: "component", type: TreeComponent, selector: "mona-tree", inputs: ["ariaLabel", "data"] }, { kind: "directive", type: TreeNodeTemplateDirective, selector: "ng-template[monaTreeNodeTemplate]" }, { kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }] }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.6", ngImport: i0, type: TreeViewComponent, decorators: [{
             type: Component,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanahoshi/mona-ui",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "A very light Angular UI framework",
   "author": "Nanahoshi",
   "repository": {

package/types/nanahoshi-mona-ui-i18n.d.ts

@@ -271,6 +271,7 @@ interface MonaGridMessages {
 }
 
 interface MonaListMessages {
+    readonly filterList: string;
     readonly noData: string;
 }
 

package/types/nanahoshi-mona-ui-internal-filter-input.d.ts

@@ -7,6 +7,40 @@ declare class FilterInputComponent implements OnInit {
     #private;
     protected readonly filter$: Subject<string>;
     protected readonly filterText: _angular_core.WritableSignal<string>;
+    /**
+     * When the input controls a list, it acts as a combobox (WAI-ARIA APG): focus stays in the input
+     * and the highlighted option is exposed through `aria-activedescendant`.
+     */
+    protected readonly inputAttributes: _angular_core.Signal<{
+        "aria-label": string | null;
+        role?: undefined;
+        "aria-activedescendant"?: undefined;
+        "aria-autocomplete"?: undefined;
+        "aria-controls"?: undefined;
+        "aria-expanded"?: undefined;
+    } | {
+        role: string;
+        "aria-label": string | null;
+        "aria-activedescendant": string | null;
+        "aria-autocomplete": string;
+        "aria-controls": string;
+        "aria-expanded": boolean;
+    }>;
+    /**
+     * @description Id of the highlighted option in the controlled list, exposed as `aria-activedescendant`.
+     * @default ""
+     */
+    readonly activeDescendant: _angular_core.InputSignal<string | null>;
+    /**
+     * @description Accessible name of the input. The placeholder is not a reliable label, so set this whenever possible.
+     * @default ""
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /**
+     * @description Id of the list this input filters. When set, the input is exposed as a combobox controlling it.
+     * @default ""
+     */
+    readonly controls: _angular_core.InputSignal<string>;
     readonly debounce: _angular_core.InputSignal<number>;
     readonly filter: _angular_core.InputSignal<string>;
     readonly filterChange: _angular_core.OutputEmitterRef<FilterChangeEvent>;
@@ -19,7 +53,7 @@ declare class FilterInputComponent implements OnInit {
     ngOnInit(): void;
     private setSubscriptions;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FilterInputComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FilterInputComponent, "mona-filter-input", never, { "debounce": { "alias": "debounce"; "required": false; "isSignal": true; }; "filter": { "alias": "filter"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "filterChange": "filterChange"; "inputBlur": "inputBlur"; "inputFocus": "inputFocus"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FilterInputComponent, "mona-filter-input", never, { "activeDescendant": { "alias": "activeDescendant"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "debounce": { "alias": "debounce"; "required": false; "isSignal": true; }; "filter": { "alias": "filter"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "filterChange": "filterChange"; "inputBlur": "inputBlur"; "inputFocus": "inputFocus"; }, never, never, true, never>;
 }
 
 export { FilterInputComponent };

package/types/nanahoshi-mona-ui-internal-list.d.ts

@@ -10,10 +10,21 @@ import { Subject, ReplaySubject } from 'rxjs';
 interface ListItemOptions<T> {
     data: T;
     header?: string;
+    /**
+     * Marks the item as a group header. Defaults to `true` when a non-empty `header` is given.
+     * Set it explicitly for groups whose key is empty, which still need a header row.
+     */
+    isHeader?: boolean;
+    /**
+     * Reuses an existing identifier, so an item rebuilt for refreshed data keeps its DOM id and tracking.
+     * A new UUID is generated when omitted.
+     */
+    uid?: string;
 }
 declare class ListItem<TData> {
     readonly data: TData;
     readonly header: string;
+    readonly isHeader: boolean;
     readonly uid: string;
     constructor(options: ListItemOptions<TData>);
 }
@@ -108,11 +119,27 @@ declare class ListService<TData> {
     readonly focus$: Subject<void>;
     readonly focusableItem: _angular_core.Signal<ListItem<TData> | null>;
     readonly groupBy: _angular_core.WritableSignal<ListKeySelector<TData>>;
+    /**
+     * Maps each option uid to the uid of the group header it is listed under.
+     */
+    readonly groupHeaderUids: _angular_core.Signal<Map<string, string>>;
     readonly groupableOptions: _angular_core.WritableSignal<GroupableOptions<TData, any>>;
+    /**
+     * The highlighted (active) item. When the data changes, it is re-resolved to the item with the same `uid`,
+     * or cleared when that item is gone.
+     */
     readonly highlightedItem: _angular_core.WritableSignal<ListItem<TData> | null>;
     readonly itemFocusOut$: Subject<ListItem<TData>>;
-    readonly navigatedItem$: Subject<ListItem<TData> | null>;
+    /**
+     * Position of each option among all filtered options (not only the current page), for `aria-posinset`
+     * and `aria-setsize`.
+     */
+    readonly itemPositions: _angular_core.Signal<Map<string, {
+        position: number;
+        total: number;
+    }>>;
     readonly navigableOptions: _angular_core.WritableSignal<NavigableOptions>;
+    readonly navigatedItem$: Subject<ListItem<TData> | null>;
     readonly pageState: _angular_core.WritableSignal<PageState>;
     readonly pageableOptions: _angular_core.WritableSignal<PagerSettings>;
     readonly scrollToItem$: ReplaySubject<{
@@ -126,16 +153,20 @@ declare class ListService<TData> {
     readonly selectionChange$: Subject<ListItem<TData>>;
     readonly textField: _angular_core.WritableSignal<string | Selector<TData, string>>;
     readonly valueField: _angular_core.WritableSignal<string | Selector<TData, unknown>>;
+    /**
+     * Visible items in display order: filtered, ordered and grouped (with header rows), but not paged.
+     */
     readonly viewItems: _angular_core.Signal<ImmutableSet<ListItem<TData>>>;
     readonly virtualScrollOptions: _angular_core.WritableSignal<VirtualScrollOptions>;
-    readonly itemPositions: _angular_core.Signal<Map<string, {
-        position: number;
-        total: number;
-    }>>;
-    getItemPosition(item: ListItem<TData>): {
-        position: number;
-        total: number;
-    } | null;
+    clearFilter(): void;
+    clearHighlightedItem(): void;
+    clearSelections(): void;
+    /**
+     * Finds the next item whose text starts with the typeahead buffer, starting after the active item.
+     * Group headers and disabled items are never matched.
+     */
+    cycleThroughMatchedItems(buffer: string): ListItem<TData> | null;
+    deselectItems(item: Iterable<ListItem<TData>>): void;
     /**
      * Resolves the selection value of a data item through `valueField`.
      *
@@ -146,14 +177,25 @@ declare class ListService<TData> {
      * Falsy results such as `0`, `false`, and `""` are valid values and do not fall back to the item.
      */
     getDataItemValue(dataItem: TData): unknown;
-    clearFilter(): void;
-    clearHighlightedItem(): void;
-    clearSelections(): void;
-    cycleThroughMatchedItems(buffer: string): ListItem<TData> | null;
-    deselectItems(item: Iterable<ListItem<TData>>): void;
     getFilterDebounceDuration(): number;
     getGroupField(item: ListItem<TData>): any;
+    /**
+     * Returns the uid of the group header an item is rendered under, or `null` when the list is not grouped.
+     */
+    getGroupHeaderUid(item: ListItem<TData>): string | null;
+    getItemPosition(item: ListItem<TData>): {
+        position: number;
+        total: number;
+    } | null;
+    /**
+     * Resolves the display text of an item through `textField`.
+     * Non-string field values (numbers, dates, …) are converted with `String()`, and nullish values become `""`.
+     */
     getItemText(item: ListItem<TData>): string;
+    /**
+     * Finds the item that typed text should resolve to: an exact text match first (respecting `caseSensitive`),
+     * otherwise the first item accepted by the filter operator. Group headers and disabled items are skipped.
+     */
     getMatchingFilteredItem(text: string): ListItem<TData> | null;
     isDisabled(item: ListItem<TData>): boolean;
     isFilteringEnabled(): boolean;
@@ -162,6 +204,11 @@ declare class ListService<TData> {
     navigate(direction: NavigationDirection, mode: NavigationMode, focus: boolean): ListItem<TData> | null;
     notifySelectionChange(item: ListItem<TData>): void;
     scrollToItem(item: ListItem<TData>, focus: boolean): void;
+    /**
+     * Selects every enabled item currently in view, keeping existing selections. Only applies in multiple mode.
+     * @returns whether the selection changed.
+     */
+    selectAllItems(): boolean;
     selectItem(item: ListItem<TData>, scroll?: boolean, focus?: boolean): void;
     setData(data: Iterable<TData>): void;
     setDisabledBy(disabledBy: string | Predicate<TData>): void;
@@ -179,11 +226,16 @@ declare class ListService<TData> {
     setValueField(valueField: string | Selector<TData, unknown>): void;
     setVirtualScrollOptions(options: VirtualScrollOptions): void;
     private filterItem;
+    /**
+     * Returns the item when it is one of the navigable items, otherwise `null`.
+     * An anchor that was filtered out or removed must not be navigated from.
+     */
+    private getItemInView;
     private getOrderKey;
     private getPreviousItemForNavigation;
     private getSelectionKey;
-    private navigateForMultipleSelection;
     private navigateFirstForSingleSelection;
+    private navigateForMultipleSelection;
     private navigateForSingleSelection;
     private navigateLastForSingleSelection;
     private navigateNextForSingleSelection;
@@ -196,7 +248,15 @@ declare class ListService<TData> {
 declare class ListComponent<TData> implements OnInit {
     #private;
     private readonly filterInput;
+    /**
+     * Id of the highlighted option, used as `aria-activedescendant` by the filter input.
+     */
+    protected readonly activeDescendant: Signal<string | null>;
     protected readonly classes: Signal<string>;
+    /**
+     * The `listId` input, or a generated id so the listbox can always be referenced by `aria-controls`.
+     */
+    protected readonly effectiveListId: Signal<string>;
     protected readonly footerTemplate: Signal<TemplateRef<any> | undefined>;
     protected readonly groupHeaderClasses: Signal<string>;
     protected readonly groupHeaderTemplate: Signal<TemplateRef<any> | undefined>;
@@ -235,10 +295,16 @@ declare class ListComponent<TData> implements OnInit {
     constructor();
     ngOnInit(): void;
     protected onFilterChange(event: FilterChangeEvent): void;
-    protected onListItemCheck(item: ListItem<TData>): void;
     protected onListItemClick(item: ListItem<TData>): void;
+    protected trackByUid(_: number, item: ListItem<TData>): string;
     private cycleThroughMatchedItems;
     private focusToItem;
+    /**
+     * Handles multiple-selection shortcuts from the WAI-ARIA listbox pattern:
+     * Space toggles the highlighted option and Ctrl/Cmd+A selects every enabled option.
+     * @returns whether the event was handled.
+     */
+    private handleMultipleSelectionKeys;
     private handleNavigation;
     private handlePageScroll;
     private scrollToItem;

package/types/nanahoshi-mona-ui-internal-tree.d.ts

@@ -67,6 +67,11 @@ declare class TreeNode<T> {
     readonly data: T;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly uid: string;
+    /**
+     * Whether children from an asynchronous children selector have been loaded. Loaded children are cached,
+     * so collapsing and re-expanding the node does not request them again.
+     */
+    childrenLoaded: boolean;
     index: string;
     parent: TreeNode<T> | null;
     constructor(data: T);
@@ -269,6 +274,15 @@ declare class TreeService<T> {
     static flatten<T>(nodes: Iterable<TreeNode<T>>): List<TreeNode<T>>;
     clearFilter(): void;
     detachNode(node: TreeNode<T>): void;
+    /**
+     * Expands every expandable, enabled sibling of a node (the `*` key of the WAI-ARIA tree pattern).
+     */
+    expandSiblings(node: TreeNode<T>): void;
+    /**
+     * Finds the next visible node, after the navigated node and wrapping around, whose text starts with `prefix`
+     * (case-insensitive). Used for typeahead.
+     */
+    findNodeByText(prefix: string): TreeNode<T> | null;
     getNodeByUid(uid: string): TreeNode<T> | null;
     getNodeElementId(uid: string): string;
     getNodeText(node: TreeNode<T>): string;
@@ -283,7 +297,15 @@ declare class TreeService<T> {
     isSelected(node: TreeNode<T>): boolean;
     isTreeFiltered(): boolean;
     isVisible(node: TreeNode<T>): boolean;
-    loadNodeChildren(node: TreeNode<T>): void;
+    /**
+     * Loads the children of a node from an asynchronous children selector.
+     * Children are loaded once and cached; pass `reload` to request them again. A new load cancels a pending one.
+     */
+    loadNodeChildren(node: TreeNode<T>, reload?: boolean): void;
+    /**
+     * Moves a node relative to a target node. Moving a node onto itself or into its own subtree is ignored,
+     * because it would detach the subtree and create a parent cycle.
+     */
     moveNode(sourceNode: TreeNode<T>, targetNode: TreeNode<T>, position: DropPosition): void;
     navigate(direction: "next" | "previous" | "first" | "last"): TreeNode<T> | null;
     notifySelectionChange(node: TreeNode<T>): void;
@@ -314,21 +336,40 @@ declare class TreeService<T> {
     setSelectedDataItems(dataItems: Iterable<T>): void;
     setSelectedKeys(keys: Iterable<any>): void;
     setTextField(selector: string | Selector<T, string>): void;
+    /**
+     * Expands or collapses a node the way user interaction does: disabled nodes are left alone, children of an
+     * asynchronous children selector are loaded on first expand, and `nodeExpand$` is notified.
+     * @returns whether the expand state changed.
+     */
+    toggleNodeExpand(node: TreeNode<T>, expanded: boolean): boolean;
     getCheckKey(node: TreeNode<T>): any;
     getDisableKey(node: TreeNode<T>): any;
     private applyCheckedKeysToNodes;
     private computeVisibleUids;
     private createFlatNodes;
+    /**
+     * Builds tree nodes for hierarchical data, reusing the existing node of each data item so node state survives
+     * a data refresh. A data object that appears more than once gets a node of its own for every extra occurrence.
+     */
     private createHierarchicalNodes;
     private createNodeDictionary;
     private createNodes;
+    /**
+     * The derived check state of a parent: `true` when all of its check-state children are checked,
+     * or `null` when it has none (its own state then stands).
+     */
+    private deriveParentChecked;
+    /**
+     * Children that determine a parent's derived check state: those with a checkbox and, unless
+     * `checkDisabledChildren` is set, only enabled ones, because the user cannot change disabled children.
+     */
+    private getCheckStateChildren;
     private getExpandKey;
     private getChildNodes;
     private getDataItemSelectKey;
     private getParentNodes;
     private getSelectKey;
     private isAnyParentCollapsed;
-    private isAnyParentDisabled;
     private isFiltered;
     private loadCheckedKeysForChildren;
     private moveNodeAfter;
@@ -360,6 +401,7 @@ declare class TreeComponent<T> {
     private setKeydownSubscription;
     private setNodeDragHandlerSubscription;
     private setSubscriptions;
+    private setTypeaheadSubscription;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeComponent<any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TreeComponent<any>, "mona-tree", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; }, {}, ["nodeTemplate"], never, true, never>;
 }
@@ -378,6 +420,8 @@ declare const TREE_DEFAULT_MESSAGES: MonaTreeViewMessages;
  * @param idKey - The property key used to uniquely identify each node (e.g., 'id').
  * @param parentIdKey - The property key holding the parent node's id, or null for roots (e.g., 'parentId').
  * @returns A new array representing the updated flat tree, with the moved node's parentIdKey updated.
+ * The array is returned unchanged when the position is "outside" or the target is the dragged node or one of its
+ * descendants, which would otherwise create a parent cycle.
  */
 declare function moveFlatTreeNode<T extends Record<string, any>>(treeData: Iterable<T>, event: NodeDropEvent<T>, idKey: keyof T, parentIdKey: keyof T): T[];
 
@@ -387,7 +431,10 @@ declare function moveFlatTreeNode<T extends Record<string, any>>(treeData: Itera
  * @param event - The drag-and-drop event payload.
  * @param idKey - The property key used to identify nodes (e.g., 'id').
  * @param childrenKey - The property key containing the nested items (e.g., 'items').
- * @returns A new array representing the updated tree structure.
+ * @returns A new top-level array representing the updated tree structure.
+ * Nested children arrays are updated in place, so untouched data items keep their identity (and their tree state).
+ * The move is skipped, returning the tree unchanged, when the position is "outside", the target is missing,
+ * or the target is the dragged node or one of its descendants, so a node is never lost or made its own ancestor.
  */
 declare function moveTreeNode<T extends Record<string, any>>(treeData: Iterable<T>, event: NodeDropEvent<T>, idKey: keyof T, childrenKey: keyof T): T[];