@nanahoshi/mona-ui 0.9.0 → 0.11.0

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

@@ -3,11 +3,11 @@ import * as _angular_core from '@angular/core';
 import { TemplateRef, WritableSignal, OnInit, ElementRef } from '@angular/core';
 import { FieldTree, SchemaOrSchemaFn, ValidationError } from '@angular/forms/signals';
 import { SortDirection, CompositeFilterDescriptor, SortDescriptor, FilterLogic, FilterOperators } from '@nanahoshi/mona-ui/query';
-import { Selector, ImmutableDictionary, ImmutableList, ImmutableSet } from '@mirei/ts-collections';
 import * as _nanahoshi_mona_ui_grid from '@nanahoshi/mona-ui/grid';
 import { CdkDropList, CdkDragEnter, CdkDragStart, CdkDragDrop } from '@angular/cdk/drag-drop';
 import { PageChangeEvent, PageSizeChangeEvent } from '@nanahoshi/mona-ui/pager';
 import { FilterMenuValue } from '@nanahoshi/mona-ui/filter';
+import { Selector, ImmutableDictionary, ImmutableList, ImmutableSet } from '@mirei/ts-collections';
 import * as rxjs from 'rxjs';
 import { Subject, BehaviorSubject } from 'rxjs';
 import { PopupMenuItem } from '@nanahoshi/mona-ui/popup-menu';
@@ -345,8 +345,6 @@ interface EditableOptions {
     schema?: GridEditSchemaFactory;
 }
 
-type GridKeySelector<TData, TKey = unknown> = string | Selector<TData, TKey> | null;
-
 declare class GridEditableDirective {
     #private;
     /**
@@ -378,17 +376,13 @@ declare class GridEditableDirective {
      * @description Emitted when a row edit is committed (row mode only).
      */
     readonly rowEdit: _angular_core.OutputEmitterRef<RowEditEvent>;
-    /**
-     * @description Field name or selector used to keep edited row identity stable when data is rebound.
-     */
-    readonly rowKey: _angular_core.InputSignal<GridKeySelector<unknown>>;
     /**
      * @description Emitted before an edited or new row is saved.
      */
     readonly save: _angular_core.OutputEmitterRef<GridSaveEvent>;
     constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridEditableDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridEditableDirective, "mona-grid[monaGridEditable]", never, { "newRowFactory": { "alias": "newRowFactory"; "required": false; "isSignal": true; }; "options": { "alias": "monaGridEditable"; "required": false; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": false; "isSignal": true; }; }, { "add": "add"; "cancel": "cancel"; "cellEdit": "cellEdit"; "edit": "edit"; "remove": "remove"; "rowEdit": "rowEdit"; "save": "save"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridEditableDirective, "mona-grid[monaGridEditable]", never, { "newRowFactory": { "alias": "newRowFactory"; "required": false; "isSignal": true; }; "options": { "alias": "monaGridEditable"; "required": false; "isSignal": true; }; }, { "add": "add"; "cancel": "cancel"; "cellEdit": "cellEdit"; "edit": "edit"; "remove": "remove"; "rowEdit": "rowEdit"; "save": "save"; }, never, never, true, never>;
 }
 
 declare class GridFilterableDirective {
@@ -504,6 +498,65 @@ declare class GridResizableDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridResizableDirective, "mona-grid[monaGridResizable]", never, { "options": { "alias": "monaGridResizable"; "required": false; "isSignal": true; }; }, { "columnResize": "columnResize"; }, never, never, true, never>;
 }
 
+interface RowReorderableOptions {
+    /**
+     * Determines whether an individual row may be reordered.
+     *
+     * Rows for which this returns false must show a disabled handle.
+     */
+    canReorder?: (rowData: Record<PropertyKey, unknown>) => boolean;
+    /**
+     * Enables row reordering.
+     *
+     * @default true when the directive is used without a value
+     */
+    enabled?: boolean;
+    /**
+     * Returns the accessible label for a row's reorder handle.
+     *
+     * The default must be positional, such as:
+     * "Reorder row 3"
+     */
+    rowAriaLabel?: (rowData: Record<PropertyKey, unknown>, absoluteIndex: number) => string;
+}
+
+declare class RowReorderEvent<TData extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>> extends PreventableEvent {
+    #private;
+    constructor(options: RowReorderEventOptions<TData>);
+    get currentIndex(): number;
+    get currentPageIndex(): number;
+    get previousIndex(): number;
+    get previousPageIndex(): number;
+    get reorderedData(): readonly TData[];
+    get rowData(): TData;
+}
+interface RowReorderEventOptions<TData extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>> {
+    currentIndex: number;
+    currentPageIndex: number;
+    previousIndex: number;
+    previousPageIndex: number;
+    reorderedData: readonly TData[];
+    rowData: TData;
+}
+
+declare class GridRowReorderableDirective {
+    #private;
+    /**
+     * @description Enables row reordering via the reorder-handle column. Pass a `RowReorderableOptions`
+     * object to configure it explicitly.
+     * @default ""
+     */
+    readonly options: _angular_core.InputSignal<"" | RowReorderableOptions>;
+    /**
+     * @description Emitted when a row is moved to a new position. The event carries the moved row,
+     * source- and page-relative indices, and the complete reordered application data.
+     */
+    readonly rowReorder: _angular_core.OutputEmitterRef<RowReorderEvent<Record<PropertyKey, unknown>>>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridRowReorderableDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridRowReorderableDirective, "mona-grid[monaGridRowReorderable]", never, { "options": { "alias": "monaGridRowReorderable"; "required": false; "isSignal": true; }; }, { "rowReorder": "rowReorder"; }, never, never, true, never>;
+}
+
 declare class GridSelectableDirective {
     #private;
     /**
@@ -768,6 +821,8 @@ interface ColumnFilterState {
     filterMenuValue?: FilterMenuValue;
 }
 
+type GridKeySelector<TData, TKey = unknown> = string | Selector<TData, TKey> | null;
+
 type ResizeMethod = "auto" | "fitView" | number;
 
 interface ColumnSortState {
@@ -819,6 +874,13 @@ interface PaginationState {
     readonly take: number;
 }
 
+type StructuralColumnKind = "detail" | "reorder" | "selection";
+interface StructuralColumnDescriptor {
+    readonly kind: StructuralColumnKind;
+    readonly visible: boolean;
+    readonly width: number;
+}
+
 interface RowEditDataItem extends Record<string, unknown> {
     readonly $rowId: string;
 }
@@ -836,7 +898,7 @@ declare class GridService {
     readonly appliedSorts: _angular_core.WritableSignal<ImmutableDictionary<string, ColumnSortState>>;
     readonly bodyScrollElement: _angular_core.WritableSignal<HTMLElement | null>;
     readonly bodyTableElement: _angular_core.WritableSignal<HTMLTableElement | null>;
-    readonly bulkSelectionRows: _angular_core.Signal<ImmutableSet<Row>>;
+    readonly bulkSelectionRows: _angular_core.Signal<ImmutableList<Row>>;
     readonly cellEdit$: Subject<CellEditEvent>;
     readonly cancel$: Subject<GridCancelEvent>;
     /** Set of currently collapsed group keys (global, shared by both paginated and virtual list). */
@@ -847,6 +909,7 @@ declare class GridService {
     readonly columns: _angular_core.WritableSignal<ImmutableList<Column>>;
     readonly contextMenuItems: _angular_core.WritableSignal<ImmutableSet<PopupMenuItem>>;
     readonly detailColumnWidth = 36;
+    readonly detailColumnOffset: _angular_core.Signal<number>;
     readonly detailStructuralWidth: _angular_core.Signal<0 | 36>;
     readonly editBaseDict: _angular_core.Signal<ImmutableDictionary<string, RowEditDataItem>>;
     readonly editContext: _angular_core.Signal<GridEditContext | null>;
@@ -854,9 +917,8 @@ declare class GridService {
     readonly editViewDict: _angular_core.Signal<ImmutableDictionary<string, RowEditDataItem>>;
     readonly editSession: _angular_core.Signal<GridEditSession | null>;
     readonly editableOptions: _angular_core.WritableSignal<EditableOptions>;
-    readonly editableRowKey: _angular_core.WritableSignal<GridKeySelector<unknown>>;
     readonly editingRowUid: _angular_core.Signal<string | null>;
-    readonly expandedKeys: _angular_core.WritableSignal<ImmutableSet<unknown>>;
+    readonly expandedKeys: _angular_core.WritableSignal<ImmutableSet<string>>;
     readonly filterChange$: Subject<CompositeFilterDescriptor[]>;
     readonly filterableOptions: _angular_core.Signal<FilterableOptions>;
     readonly footerScrollElement: _angular_core.WritableSignal<HTMLElement | null>;
@@ -872,6 +934,7 @@ declare class GridService {
     readonly headerTableElement: _angular_core.WritableSignal<HTMLTableElement | null>;
     readonly horizontalScrollLeft: _angular_core.Signal<number>;
     readonly isInEditMode: _angular_core.Signal<boolean>;
+    readonly lastLeftStructuralOffset: _angular_core.Signal<number | null>;
     readonly leftLockedStructuralWidth: _angular_core.Signal<number>;
     readonly lockedColumnStates: _angular_core.Signal<ReadonlyMap<string, GridLockedColumnState>>;
     readonly leadingStructuralWidth: _angular_core.Signal<number>;
@@ -885,9 +948,20 @@ declare class GridService {
     readonly remove$: Subject<GridRemoveEvent>;
     readonly reorderableOptions: _angular_core.Signal<ReorderableOptions>;
     readonly resizableOptions: _angular_core.Signal<ResizableOptions>;
+    readonly rowDragInProgress: _angular_core.Signal<boolean>;
     readonly rowEdit$: Subject<RowEditEvent>;
-    readonly rows: _angular_core.WritableSignal<ImmutableSet<Row>>;
+    readonly rowKey: _angular_core.WritableSignal<GridKeySelector<unknown>>;
+    readonly rowReorder$: Subject<RowReorderEvent<Record<PropertyKey, unknown>>>;
+    readonly rowReorderColumnOffset: _angular_core.Signal<number>;
+    readonly rowReorderColumnVisible: _angular_core.Signal<boolean>;
+    readonly rowReorderColumnWidth = 36;
+    readonly rowReorderDisabledReason: _angular_core.Signal<RowReorderDisabledReason>;
+    readonly rowReorderInteractionEnabled: _angular_core.Signal<boolean>;
+    readonly rowReorderStructuralWidth: _angular_core.Signal<0 | 36>;
+    readonly rowReorderableOptions: _angular_core.Signal<RowReorderableOptions>;
+    readonly rows: _angular_core.WritableSignal<ImmutableList<Row>>;
     readonly save$: Subject<GridSaveEvent>;
+    readonly draggingRowUid: _angular_core.WritableSignal<string | null>;
     readonly scrollEnd$: Subject<void>;
     readonly scrollEndThreshold: _angular_core.WritableSignal<number>;
     readonly scrollbarGutterWidth: _angular_core.Signal<number>;
@@ -903,17 +977,22 @@ declare class GridService {
     readonly selectionStructuralWidth: _angular_core.Signal<0 | 40>;
     readonly someBulkSelectionRowsSelected: _angular_core.Signal<boolean>;
     readonly sortableOptions: _angular_core.WritableSignal<SortableOptions>;
+    readonly structuralColIndexMap: _angular_core.Signal<Map<StructuralColumnKind, number>>;
+    readonly structuralColumns: _angular_core.Signal<readonly StructuralColumnDescriptor[]>;
+    readonly structuralLastKind: _angular_core.Signal<StructuralColumnKind | null>;
     readonly tableWidth: _angular_core.Signal<number | null>;
-    readonly viewPageRows: _angular_core.Signal<ImmutableSet<Row>>;
+    readonly viewPageRows: _angular_core.Signal<ImmutableList<Row>>;
     readonly viewRowCount: _angular_core.Signal<number>;
-    readonly viewRows: _angular_core.Signal<ImmutableSet<Row>>;
+    readonly viewRows: _angular_core.Signal<ImmutableList<Row>>;
     readonly virtualGridMaxBuffer: _angular_core.Signal<number>;
     readonly virtualGridMinBuffer: _angular_core.WritableSignal<number>;
     readonly virtualScrollOptions: _angular_core.WritableSignal<VirtualScrollOptions>;
     readonly visibleColumns: _angular_core.Signal<ImmutableList<Column>>;
+    readonly visibleStructuralColumns: _angular_core.Signal<StructuralColumnDescriptor[]>;
     constructor();
     addGroupColumn(column: Column): void;
     applyState(state: GridState | null, options?: GridStatePersistenceOptions): GridStateLoadResult;
+    canReorderRow(row: Row): boolean;
     cancelAddRow(originalEvent?: Event): boolean;
     cancelEdit(originalEvent?: Event): boolean;
     captureState(options?: GridStatePersistenceOptions): GridState;
@@ -926,6 +1005,7 @@ declare class GridService {
     getColumnStateId(column: Column): string | null;
     getColumnWidth(column: Column): number;
     getGroupDescriptors(columns: Iterable<Column>): GroupDescriptor[];
+    getRowReorderAriaLabel(row: Row, absoluteIndex: number): string;
     handleMultipleSelection(event: MouseEvent, row: Row): void;
     handleRowClick(event: MouseEvent, row: Row): void;
     handleSingleSelection(event: MouseEvent, row: Row): void;
@@ -941,6 +1021,7 @@ declare class GridService {
     patchAddCell(field: string, value: unknown): void;
     patchCellEdit(rowUid: string, field: string, value: unknown): void;
     removeRow(row: Row, originalEvent?: Event): boolean;
+    requestRowReorder(row: Row, previousPageIndex: number, currentPageIndex: number): boolean;
     resolveAggregateValue(bucket: GridAggregateBucket | null, aggregateFunction: AggregateFunction | null): unknown;
     saveAddRow(originalEvent?: Event): boolean;
     selectRow(row: Row): void;
@@ -963,6 +1044,7 @@ declare class GridService {
     setReorderableOptions(options: Partial<ReorderableOptions>): void;
     setResizableOptions(options: Partial<ResizableOptions>): void;
     setRowExpanded(row: Row, expanded: boolean): void;
+    setRowReorderableOptions(options: RowReorderableOptions): void;
     setRows(value: Iterable<Record<PropertyKey, unknown>>, rowKey?: GridKeySelector<unknown> | null): void;
     setSelectableOptions(options: SelectableOptions): void;
     setRowSelected(row: Row, selected: boolean): void;
@@ -973,6 +1055,7 @@ declare class GridService {
     startCellEdit(uid: string, row: Row, column: Column, originalEvent?: Event): boolean;
     startRowEdit(row: Row, originalEvent?: Event): boolean;
     stopCellEdit(originalEvent?: Event): boolean;
+    structuralColumnOffset(kind: StructuralColumnKind, groupPrefixWidth: number): number;
     toggleGroupCollapse(groupKey: string): void;
     updateColumn(columnId: string, patch: Partial<Omit<Column, "id">>): void;
     private applyColumnIndexes;
@@ -1017,6 +1100,7 @@ declare class GridService {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<GridService>;
 }
+type RowReorderDisabledReason = "disabled" | "editing" | "filtered" | "grouped" | "single-row" | "sorted" | "virtual-scroll" | null;
 
 declare const gridBaseThemeVariants: (props?: ({
     rounded?: "small" | "none" | "medium" | "large" | null | undefined;
@@ -1118,6 +1202,12 @@ declare class GridComponent<T> implements GridVariantInput {
      * @default "fitView"
      */
     readonly resizeMethod: _angular_core.InputSignal<ResizeMethod>;
+    /**
+     * @description Field name or selector used to derive a stable identity for each row.
+     * The resolved value must be unique within the grid data.
+     * @default null
+     */
+    readonly rowKey: _angular_core.InputSignal<GridKeySelector<unknown>>;
     /**
      * @description Whether the pager is responsive.
      * If set to `true`, the pager will be displayed as a dropdown when the grid width gets smaller.
@@ -1171,8 +1261,8 @@ declare class GridComponent<T> implements GridVariantInput {
     private setResizeObserver;
     private syncToolbarFocusTargets;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<GridComponent<any>, "mona-grid", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "pageSizeValues": { "alias": "pageSizeValues"; "required": false; "isSignal": true; }; "resizeMethod": { "alias": "resizeMethod"; "required": false; "isSignal": true; }; "responsivePager": { "alias": "responsivePager"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; }, {}, ["columnDefinitions", "gridDetailTemplate", "noDataTemplate", "toolbarTemplate"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<GridComponent<any>, "mona-grid", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "pageSizeValues": { "alias": "pageSizeValues"; "required": false; "isSignal": true; }; "resizeMethod": { "alias": "resizeMethod"; "required": false; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": false; "isSignal": true; }; "responsivePager": { "alias": "responsivePager"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; }, {}, ["columnDefinitions", "gridDetailTemplate", "noDataTemplate", "toolbarTemplate"], never, true, never>;
 }
 
-export { CellEditEvent, ColumnReorderEvent, ColumnSortEvent, GridAddCommandDirective, GridAddEvent, GridCancelCommandDirective, GridCancelEvent, GridCellTemplateDirective, GridColumnComponent, GridColumnTitleTemplateDirective, GridCommandColumnComponent, GridComponent, GridContextMenuDirective, GridDetailTemplateDirective, GridEditCommandDirective, GridEditEvent, GridEditTemplateDirective, GridEditableDirective, GridExportDirective, GridFilterableDirective, GridFooterTemplateDirective, GridGroupFooterTemplateDirective, GridGroupableDirective, GridHeaderTemplateDirective, GridNoDataTemplateDirective, GridRemoveCommandDirective, GridRemoveEvent, GridReorderableDirective, GridResizableDirective, GridSaveCommandDirective, GridSaveEvent, GridSelectableDirective, GridSortableDirective, GridStatePersistenceDirective, GridToolbarTemplateDirective, GridVirtualScrollDirective, RowEditEvent };
-export type { AggregateFunction, Column, ColumnConfig, ColumnFormat, ColumnKind, ColumnResizeEvent, EditableOptions, FilterableOptions, GridColumnLockedPosition, GridColumnState, GridEditFormContext, GridEditOperation, GridEditSchemaFactory, GridEditSession, GridEditTemplateContext, GridSaveOperation, GridState, GridStateCompositeFilterDescriptor, GridStateFilterDescriptor, GridStateFilterValue, GridStateLoadResult, GridStateLoadStatus, GridStatePersistenceOptions, GridStateSortDescriptor, GridStateVersion, GroupDescriptor, GroupableOptions, ReorderableOptions, ResizableOptions, ResizeMethod, SelectableOptions, SortableOptions };
+export { CellEditEvent, ColumnReorderEvent, ColumnSortEvent, GridAddCommandDirective, GridAddEvent, GridCancelCommandDirective, GridCancelEvent, GridCellTemplateDirective, GridColumnComponent, GridColumnTitleTemplateDirective, GridCommandColumnComponent, GridComponent, GridContextMenuDirective, GridDetailTemplateDirective, GridEditCommandDirective, GridEditEvent, GridEditTemplateDirective, GridEditableDirective, GridExportDirective, GridFilterableDirective, GridFooterTemplateDirective, GridGroupFooterTemplateDirective, GridGroupableDirective, GridHeaderTemplateDirective, GridNoDataTemplateDirective, GridRemoveCommandDirective, GridRemoveEvent, GridReorderableDirective, GridResizableDirective, GridRowReorderableDirective, GridSaveCommandDirective, GridSaveEvent, GridSelectableDirective, GridSortableDirective, GridStatePersistenceDirective, GridToolbarTemplateDirective, GridVirtualScrollDirective, RowEditEvent, RowReorderEvent };
+export type { AggregateFunction, Column, ColumnConfig, ColumnFormat, ColumnKind, ColumnResizeEvent, EditableOptions, FilterableOptions, GridColumnLockedPosition, GridColumnState, GridEditFormContext, GridEditOperation, GridEditSchemaFactory, GridEditSession, GridEditTemplateContext, GridSaveOperation, GridState, GridStateCompositeFilterDescriptor, GridStateFilterDescriptor, GridStateFilterValue, GridStateLoadResult, GridStateLoadStatus, GridStatePersistenceOptions, GridStateSortDescriptor, GridStateVersion, GroupDescriptor, GroupableOptions, ReorderableOptions, ResizableOptions, ResizeMethod, RowReorderableOptions, SelectableOptions, SortableOptions };

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

@@ -122,7 +122,7 @@ declare class ListService<TData> {
     readonly selectedListItems: _angular_core.Signal<ImmutableSet<ListItem<TData>>>;
     readonly selectionChange$: Subject<ListItem<TData>>;
     readonly textField: _angular_core.WritableSignal<string | Selector<TData, string>>;
-    readonly valueField: _angular_core.WritableSignal<string | Selector<TData, any>>;
+    readonly valueField: _angular_core.WritableSignal<string | Selector<TData, unknown>>;
     readonly viewItems: _angular_core.Signal<ImmutableSet<ListItem<TData>>>;
     readonly virtualScrollOptions: _angular_core.WritableSignal<VirtualScrollOptions>;
     readonly itemPositions: _angular_core.Signal<Map<string, {
@@ -133,6 +133,16 @@ declare class ListService<TData> {
         position: number;
         total: number;
     } | null;
+    /**
+     * Resolves the selection value of a data item through `valueField`.
+     *
+     * When no `valueField` is configured, the data item itself is the value.
+     * When `valueField` is a string, the item property is read with a nullish fallback to the item.
+     * When `valueField` is a function, its result is used as-is.
+     *
+     * 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;
@@ -161,12 +171,11 @@ declare class ListService<TData> {
     setPageableOptions(settings: PagerSettings): void;
     setSelectableOptions(options: Partial<SelectableOptions>): void;
     setSelectedDataItems(dataItems: Iterable<TData>): void;
-    setSelectedKeys(selectedKeys: Iterable<any>): void;
+    setSelectedKeys(selectedKeys: Iterable<unknown>): void;
     setTextField(textField: string | Selector<TData, string>): void;
-    setValueField(valueField: string | Selector<TData, any>): void;
+    setValueField(valueField: string | Selector<TData, unknown>): void;
     setVirtualScrollOptions(options: VirtualScrollOptions): void;
     private filterItem;
-    private getDataItemSelectionKey;
     private getOrderKey;
     private getPreviousItemForNavigation;
     private getSelectionKey;

package/types/nanahoshi-mona-ui-multi-select.d.ts

@@ -36,7 +36,7 @@ type MultiSelectIndicatorContainerVariantInput = VariantInputs<MultiSelectIndica
 type MultiSelectVariantProps = MultiSelectBaseVariantProps & MultiSelectItemContainerVariantProps & MultiSelectAffixContainerVariantProps & MultiSelectIndicatorContainerVariantProps;
 type MultiSelectVariantInput = Omit<MultiSelectBaseVariantInput, "focused" | "invalid"> & MultiSelectItemContainerVariantInput & MultiSelectAffixContainerVariantInput & MultiSelectIndicatorContainerVariantInput;
 
-declare class MultiSelectComponent<TData = unknown> implements FormValueControl<Iterable<TData>>, MultiSelectVariantInput, DropdownDataInput<TData>, DropdownPopupInput, DropdownPopupVariantInput {
+declare class MultiSelectComponent<TData = unknown, TValue = TData> implements FormValueControl<Iterable<TValue>>, MultiSelectVariantInput, DropdownDataInput<TData>, DropdownPopupInput, DropdownPopupVariantInput {
     #private;
     protected readonly activeDescendant: _angular_core.Signal<string | null>;
     protected readonly affixClass: _angular_core.Signal<string>;
@@ -168,7 +168,7 @@ declare class MultiSelectComponent<TData = unknown> implements FormValueControl<
      * If null, the item itself will be used as the text representation.
      * @default null
      */
-    readonly textField: _angular_core.InputSignal<DropdownFieldSelectorType<TData>>;
+    readonly textField: _angular_core.InputSignal<DropdownFieldSelectorType<TData, string>>;
     /**
      * @description Emitted when the multi select is interacted with on blur, selection, remove, or clear.
      * The `FormField` directive listens to this to mark the field as touched.
@@ -187,18 +187,32 @@ declare class MultiSelectComponent<TData = unknown> implements FormValueControl<
     readonly userClass: _angular_core.InputSignal<string>;
     /**
      * @description Sets the value field of the multi select component.
-     * It can be null, string, or a function that takes an item and returns a string.
+     * It is used for stable item identity, matching externally supplied values, and primitive
+     * value projection when {@link valuePrimitive} is enabled.
+     * It can be null, string, or a function that takes an item and returns a value.
      * If null, the item itself will be used as the value representation.
+     * Should resolve to a stable, unique scalar.
      * @default null
      */
-    readonly valueField: _angular_core.InputSignal<DropdownFieldSelectorType<TData>>;
+    readonly valueField: _angular_core.InputSignal<DropdownFieldSelectorType<TData, unknown>>;
+    /**
+     * @description Determines whether the bound value contains complete data items
+     * or values extracted through {@link valueField}.
+     *
+     * When `false`, selecting an item writes the complete data item.
+     * When `true`, selecting an item writes the value resolved through `valueField`.
+     *
+     * @default false
+     */
+    readonly valuePrimitive: _angular_core.InputSignal<boolean>;
     /**
-     * @description Two-way bindable current selected values. Implements `FormValueControl<Iterable<TData>>`,
-     * enabling signal forms `[formField]` binding. When `valueField` is set, primitive field values can be
-     * written into this model to restore matching selected items.
+     * @description Two-way bindable current selected values. Implements `FormValueControl<Iterable<TValue>>`,
+     * enabling signal forms `[formField]` binding.
+     * Object mode contains selected data items; primitive mode (see {@link valuePrimitive}) contains values
+     * resolved through {@link valueField}. An empty selection is represented by an empty iterable/array.
      * @default []
      */
-    readonly value: _angular_core.ModelSignal<Iterable<TData>>;
+    readonly value: _angular_core.ModelSignal<Iterable<TValue>>;
     constructor();
     focus(): void;
     protected onBlur(): void;
@@ -206,6 +220,7 @@ declare class MultiSelectComponent<TData = unknown> implements FormValueControl<
     protected onSelectedItemRemove(event: Event, listItem: ListItem<TData>): void;
     protected onSelectedItemGroupRemove(event: Event): void;
     protected onValueClear(event: Event): void;
+    private getSelectedControlValues;
     private handleEnterKey;
     private handlePopupPositionUpdate;
     private initialize;
@@ -213,9 +228,10 @@ declare class MultiSelectComponent<TData = unknown> implements FormValueControl<
     private setEnterKeySubscription;
     private setEventListeners;
     private setSubscriptions;
+    private synchronizeSelection;
     private updateValue;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MultiSelectComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MultiSelectComponent<any>, "mona-multi-select", never, { "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "autoClose": { "alias": "autoClose"; "required": false; "isSignal": true; }; "checkboxes": { "alias": "checkboxes"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "itemDisabled": { "alias": "itemDisabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "popupClass": { "alias": "popupClass"; "required": false; "isSignal": true; }; "popupHeight": { "alias": "popupHeight"; "required": false; "isSignal": true; }; "popupWidth": { "alias": "popupWidth"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "showClearButton": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "textField": { "alias": "textField"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "close": "close"; "closed": "closed"; "disabled": "disabledChange"; "open": "open"; "opened": "opened"; "touch": "touch"; "value": "valueChange"; }, ["footerTemplate", "groupHeaderTemplate", "headerTemplate", "itemTemplate", "noDataTemplate", "prefixTemplate", "tagTemplate"], never, true, [{ directive: typeof i1.DropdownDataHandlerDirective; inputs: {}; outputs: {}; }, { directive: typeof i1.DropdownListPopupHandlerDirective; inputs: {}; outputs: {}; }]>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MultiSelectComponent<any, any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MultiSelectComponent<any, any>, "mona-multi-select", never, { "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "autoClose": { "alias": "autoClose"; "required": false; "isSignal": true; }; "checkboxes": { "alias": "checkboxes"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "itemDisabled": { "alias": "itemDisabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "popupClass": { "alias": "popupClass"; "required": false; "isSignal": true; }; "popupHeight": { "alias": "popupHeight"; "required": false; "isSignal": true; }; "popupWidth": { "alias": "popupWidth"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "showClearButton": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "textField": { "alias": "textField"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": false; "isSignal": true; }; "valuePrimitive": { "alias": "valuePrimitive"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "close": "close"; "closed": "closed"; "disabled": "disabledChange"; "open": "open"; "opened": "opened"; "touch": "touch"; "value": "valueChange"; }, ["footerTemplate", "groupHeaderTemplate", "headerTemplate", "itemTemplate", "noDataTemplate", "prefixTemplate", "tagTemplate"], never, true, [{ directive: typeof i1.DropdownDataHandlerDirective; inputs: {}; outputs: {}; }, { directive: typeof i1.DropdownListPopupHandlerDirective; inputs: {}; outputs: {}; }]>;
 }
 
 declare class MultiSelectSummaryTagDirective<TData> {