mn-angular-lib 1.0.132 → 1.0.134

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mn-angular-lib",
-  "version": "1.0.132",
+  "version": "1.0.134",
   "peerDependencies": {
     "@angular/common": "^21.1.3",
     "@angular/core": "^21.1.3"

package/types/mn-angular-lib.d.ts

@@ -3089,6 +3089,66 @@ type MnSelectableCollectionDataSource<T> = MnCollectionDataSource<T> & {
     selectedRows?: BehaviorSubject<T[]>;
     /** IDs to pre-select when the component initializes. */
     initialSelectedIds?: string[];
+    /**
+     * Rows behind {@link initialSelectedIds}, for collections whose rows are paged in
+     * from a server. The component can only recognise a selected row once it has been
+     * loaded, so on page 1 of a server-paginated table it knows the *ids* that are
+     * selected but not what they are called — which is exactly what
+     * {@link selectionSummary} needs to render. Supplying the rows here fills that
+     * gap. Unnecessary when every row is client-side: the ids resolve against
+     * `dataRows` on their own.
+     */
+    initialSelectedRows?: T[];
+    /**
+     * Renders an always-visible summary of the current selection above the
+     * collection: a count and one removable tag per selected row.
+     *
+     * It exists because a selection and a paginated list answer different questions.
+     * The list is for *finding* rows and is therefore filtered, searched and paged;
+     * the selection is the answer the user is assembling, and hiding it on page 40
+     * makes people re-pick rows they already had. The summary never pages, filters or
+     * sorts — it always shows the whole selection.
+     */
+    selectionSummary?: boolean;
+    /**
+     * Label for a row inside {@link selectionSummary}. Defaults to the first column
+     * that renders a plain string, falling back to the row's id.
+     */
+    selectionLabel?: (row: T) => string;
+    /**
+     * How many tags {@link selectionSummary} shows before collapsing the rest behind
+     * a "+N more" control. Defaults to 8.
+     *
+     * A summary exists to be taken in at a glance, so it must not grow without bound:
+     * left uncapped, selecting a few hundred rows turns the header into the page and
+     * pushes the table — the thing being worked in — off screen entirely. The count in
+     * the heading always states the true total, so collapsing hides tags, never
+     * information.
+     */
+    selectionSummaryLimit?: number;
+    /** Labels for the {@link selectionSummary} chrome. */
+    selectionSummaryLabels?: {
+        /** Heading, supporting a `{{count}}` placeholder. Defaults to `Selected ({{count}})`. */
+        title?: string;
+        /** Translation key for {@link title}. */
+        titleKey?: string;
+        /** Label for the clear-everything action. Defaults to `Clear all`. */
+        clearAll?: string;
+        /** Translation key for {@link clearAll}. */
+        clearAllKey?: string;
+        /** Accessible label for a tag's remove button, supporting `{{label}}`. */
+        remove?: string;
+        /** Translation key for {@link remove}. */
+        removeKey?: string;
+        /** Expand action, supporting a `{{count}}` placeholder. Defaults to `+{{count}} more`. */
+        showMore?: string;
+        /** Translation key for {@link showMore}. */
+        showMoreKey?: string;
+        /** Collapse action. Defaults to `Show less`. */
+        showLess?: string;
+        /** Translation key for {@link showLess}. */
+        showLessKey?: string;
+    };
 };
 
 /**
@@ -3333,6 +3393,12 @@ declare abstract class MnCollectionBase<T, DS extends MnCollectionDataSource<T>>
     protected abstract applyFilter(searchForItems: boolean): void;
     /** Runs after pageSize is set but before the first {@link applyFilter}. */
     protected beforeInitialFilter(): void;
+    /**
+     * Runs after a fresh batch of rows has been filtered in, for work that needs the
+     * rows to exist. Subclasses override to react to data arriving late; call `super`
+     * to keep the default (currently nothing).
+     */
+    protected onRowsChanged(): void;
     /**
      * Resolves translation keys to display strings via {@link MnLanguageService}.
      * Subclasses override to resolve their own keys; call `super` to keep these.
@@ -3383,15 +3449,100 @@ declare abstract class MnCollectionBase<T, DS extends MnCollectionDataSource<T>>
 declare abstract class MnSelectableCollectionBase<T, DS extends MnSelectableCollectionDataSource<T>> extends MnCollectionBase<T, DS> {
     selectionChange: EventEmitter<T[]>;
     selectedIds: Set<string>;
+    /** Whether the summary is currently showing every tag rather than the first few. */
+    selectionSummaryExpanded: boolean;
     get allSelected(): boolean;
+    /**
+     * The row behind every selected id, kept so the selection survives the rows
+     * themselves going away.
+     *
+     * {@link selectedIds} alone is enough to tick a checkbox, because that only ever
+     * asks about a row already on screen. The summary asks the opposite question —
+     * "what is selected, including what isn't on this page?" — and a server-paginated
+     * collection has long since discarded those rows. Rows are captured as they are
+     * selected and backfilled from {@link MnSelectableCollectionDataSource.initialSelectedRows}
+     * and from each batch that loads.
+     */
+    protected selectedRowsById: Map<string, T>;
+    /**
+     * Whether a seeded initial selection still has to be announced, because none of
+     * its ids matched a loaded row yet. See {@link beforeInitialFilter}.
+     */
+    private pendingInitialEmit;
+    /**
+     * The ids that arrived pre-selected, kept apart from {@link selectedIds} so
+     * {@link prioritizeInitialSelection} has a set that does **not** move as the user
+     * clicks. Null when the collection opened with nothing selected.
+     */
+    private pinnedSelectionIds;
+    /**
+     * Every selected row, in selection order, for the summary. Ids whose row was
+     * never seen are skipped rather than rendered as a bare id.
+     */
+    get selectedSummaryRows(): T[];
+    /** Whether the selection summary should render. */
+    get showSelectionSummary(): boolean;
+    /** How many tags to show before collapsing the remainder. */
+    get selectionSummaryLimit(): number;
+    /**
+     * The tags to render: the first {@link selectionSummaryLimit} rows, or all of them
+     * once expanded. Keeps a large selection from turning the header into the page.
+     */
+    get visibleSelectionRows(): T[];
+    /** How many selected rows are collapsed out of view; 0 when all are shown. */
+    get hiddenSelectionCount(): number;
+    /** Expands or re-collapses the summary's tag list. */
+    toggleSelectionSummary(): void;
+    /**
+     * The label for a row in the summary: the consumer's {@link
+     * MnSelectableCollectionDataSource.selectionLabel}, else the first column that
+     * renders a plain string, else the row's id.
+     * @param row The selected row.
+     * @returns The text to show on the row's tag.
+     */
+    selectionLabelFor(row: T): string;
+    /** Removes one row from the selection, from its tag in the summary. */
+    removeSelection(row: T): void;
     get hasSelection(): boolean;
     get isMultiSelect(): boolean;
     isSelected(item: T): boolean;
+    /** Clears the whole selection, from the summary's clear-all action. */
+    clearSelection(): void;
     toggle(item: T): void;
     toggleAll(): void;
+    /**
+     * Fallback label used when the data source declares no `selectionLabel`.
+     * Subclasses that know how to render a row as text (a table knows its columns)
+     * override this; the base has nothing to go on.
+     * @returns The label, or null when none can be derived.
+     */
+    protected defaultSelectionLabel(_row: T): string | null;
+    /**
+     * Reorders rows so the ones that were already selected when the collection
+     * opened come first, preserving the incoming order within each group.
+     *
+     * Deliberately keyed on the *initial* selection rather than the live one: pinning
+     * what the user is currently ticking would make a row jump to the top the instant
+     * it is clicked, moving the next row under the pointer mid-click. Freezing the set
+     * answers the actual question — "what was already chosen?" — and leaves the list
+     * still while it is being worked with. A row deselected during the session keeps
+     * its place for the same reason.
+     *
+     * Callers apply this only when no explicit sort is active, so a sorted column
+     * always wins.
+     * @param items The rows in their current order.
+     * @returns The rows with the initially-selected ones hoisted to the top.
+     */
+    protected prioritizeInitialSelection(items: T[]): T[];
     /** Seeds selection from `initialSelectedIds` before the first filter pass. */
     protected beforeInitialFilter(): void;
+    /** Announces a deferred initial selection as soon as its rows are loaded. */
+    protected onRowsChanged(): void;
     protected emitSelection(): void;
+    /** Records the row object for every loaded row that is currently selected. */
+    private captureSelectedRows;
+    /** The currently loaded rows whose id is selected. */
+    private resolveSelectedRows;
     static ɵfac: i0.ɵɵFactoryDeclaration<MnSelectableCollectionBase<any, any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<MnSelectableCollectionBase<any, any>, never, never, {}, { "selectionChange": "selectionChange"; }, never, never, true, never>;
 }
@@ -3697,6 +3848,15 @@ type MnTableFilterLabels = {
     /** False option of a boolean filter. Defaults to "No". */
     no?: string;
     noKey?: string;
+    /**
+     * Summary a multi-select filter collapses to from the second selection onwards.
+     * The `{count}` token is replaced with how many are selected. Defaults to
+     * `{count} selected`. A column header has room for about one value, so listing
+     * them all would overflow the cell the moment a second one is picked.
+     */
+    selected?: string;
+    /** Translation key for {@link selected}. */
+    selectedKey?: string;
 };
 /** @deprecated Use {@link MnCollectionLabels}. */
 type TableLabels = MnCollectionLabels;
@@ -3709,17 +3869,8 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     currentSort: SortState | null;
     /** Per-column filter values keyed by column key. */
     columnFilters: ColumnFilterState;
-    /** Filter types compact enough to render directly inside the header cell. */
-    private static readonly INLINE_FILTER_TYPES;
-    /** Width (px) of the filter popover, mirrored from its `w-64` class for clamping. */
-    private static readonly POPOVER_WIDTH;
     /** Viewport width (px) below which the inline filter row collapses into a panel. */
     private static readonly FILTER_COLLAPSE_WIDTH;
-    /**
-     * Key of the column whose filter popover is open, or `null` when none is.
-     * Only the rich filter types ({@link isPopoverFilter}) use a popover.
-     */
-    protected openFilterKey: string | null;
     /** Bounds rendered by a number-range filter, in input order. */
     protected readonly numberBounds: RangeBound[];
     /**
@@ -3735,15 +3886,8 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     protected collectionBody?: ElementRef<HTMLElement>;
     /** Bounds rendered by a date-range filter, in input order. */
     protected readonly dateBounds: RangeBound[];
-    /** Viewport coordinates of the open filter popover. */
-    protected popoverPosition: {
-        top: number;
-        left: number;
-    };
     /** Debounces server-side text filters so typing doesn't fire a request per keystroke. */
     private readonly filterDebounce;
-    /** The open filter popover, used to tell inside clicks from outside ones. */
-    private filterPopover?;
     /**
      * Most rows shown per page on mobile (< md). A **cap**, not an override: a data
      * source asking for fewer rows keeps its own size. Raising a small page size on
@@ -3776,25 +3920,8 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     onBooleanFilter(column: ColumnDefinition<T>, raw: string): void;
     /** The effective filter type of a column, defaulting to text. */
     filterTypeOf(column: ColumnDefinition<T>): ColumnFilterType;
-    /** Whether a column's filter renders inline in the header cell (vs. in a popover). */
-    isInlineFilter(column: ColumnDefinition<T>): boolean;
-    /** Whether a column's filter is rich enough to need the popover panel. */
-    isPopoverFilter(column: ColumnDefinition<T>): boolean;
     /** Whether a specific column's filter currently narrows the rows. */
     isColumnFilterActive(column: ColumnDefinition<T>): boolean;
-    /** The column whose filter popover is open, or `null`. */
-    openFilterColumn(): ColumnDefinition<T> | null;
-    /**
-     * Opens/closes a column's filter popover, closing any other that was open, and
-     * anchors it under the trigger. The popover is positioned `fixed` from the
-     * trigger's viewport rect because it renders outside the table's
-     * `overflow-x-auto` wrapper, which would otherwise clip it.
-     */
-    toggleFilterPopover(column: ColumnDefinition<T>, event: Event): void;
-    /** Resets a single column's filter (from its popover) and re-applies filtering. */
-    clearColumnFilter(column: ColumnDefinition<T>): void;
-    /** Closes the filter popover, if one is open. */
-    closeFilterPopover(): void;
     /** Filter options formatted for mn-multi-select for a given column. */
     getFilterMultiSelectOptions(column: ColumnDefinition<T>): MnMultiSelectOption<string>[];
     /** Any / Yes / No options for a boolean column filter. */
@@ -3813,18 +3940,15 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     rangeBoundLabel(bound: RangeBound): string;
     /** Resets every column filter and re-applies (or re-requests) filtering. */
     clearAllFilters(): void;
-    /**
-     * Closes the filter popover when the click landed outside it. Membership is
-     * tested against the popover element rather than stopping propagation inside
-     * it, so the popover's own controls stay ordinary, focusable elements.
-     */
-    protected onDocumentClick(event: MouseEvent): void;
     /** Whether any column has filtering enabled. */
     get hasColumnFilters(): boolean;
-    /** Closes the filter popover on Escape. */
-    protected onEscape(): void;
     /** Label for the small-screen filters toggle button. */
     get filtersButtonLabel(): string;
+    /**
+     * Summary a multi-select filter collapses to once more than one option is picked.
+     * Resolved with the `{count}` token intact for mn-multi-select to fill in.
+     */
+    get filterSelectedLabel(): string;
     /** Label for the "clear all filters" action in the small-screen panel. */
     get clearFiltersButtonLabel(): string;
     /** Opens/closes the stacked filter panel shown on small screens. */
@@ -3869,6 +3993,20 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     get tableClasses(): string;
     /** Page size to use at/above the `md` breakpoint (consumer's pageSize, or the user's selection). */
     private desktopPageSize;
+    /** Heading for the selection summary, with the count filled in. */
+    get selectionSummaryTitle(): string;
+    /** Label for the summary's clear-everything action. */
+    get selectionClearAllLabel(): string;
+    /** Label for the summary's expand/collapse control. */
+    get selectionSummaryToggleLabel(): string;
+    /**
+     * Accessible label for a tag's remove button.
+     * @param row The row the tag stands for.
+     * @returns The label, naming the row so screen readers announce which one goes.
+     */
+    selectionRemoveLabel(row: T): string;
+    /** Tracks the desktop page size when the user picks one (selector only shows at >= md). */
+    onPageSizeChange(newSize: number): void;
     /** The effective column-width strategy, defaulting to `stable`. */
     get layoutMode(): 'auto' | 'fixed' | 'stable';
     /**
@@ -3894,6 +4032,29 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
      * @returns The full cell text, or `null` when there is nothing to expose.
      */
     cellTitle(column: ColumnDefinition<T>, row: T): string | null;
+    /**
+     * Falls back to the first column that renders a plain string, which is almost
+     * always the name-like column a person would use to identify the row. Template
+     * columns are skipped: they render markup this cannot flatten to a tag label.
+     * @param row The selected row.
+     * @returns The label, or null when every column renders a template.
+     */
+    protected defaultSelectionLabel(row: T): string | null;
+    /**
+     * Resolves table-specific translation keys (column headers/filters) plus the
+     * shared keys handled by the base.
+     */
+    protected resolveTranslationKeys(): void;
+    protected applyFilter(searchForItems: boolean): void;
+    /**
+     * Re-evaluate on a window resize too. The ResizeObserver covers every change to
+     * the table's own box, but {@link isMobileViewport} reads the window, which can
+     * change without the table's width following it (a fixed-width table, a modal
+     * pinned to a max width).
+     */
+    protected onWindowResize(): void;
+    /** Re-evaluate responsive page size and filter layout when the table is resized. */
+    private onHostResize;
     /**
      * Captures the current, automatically-derived width of every visible column and
      * pins it, which flips the table to `table-fixed` on the next render.
@@ -3919,23 +4080,6 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
      * go, changing which columns need a share at all.
      */
     private unpinColumnWidths;
-    /**
-     * Re-evaluate on a window resize too. The ResizeObserver covers every change to
-     * the table's own box, but {@link isMobileViewport} reads the window, which can
-     * change without the table's width following it (a fixed-width table, a modal
-     * pinned to a max width).
-     */
-    protected onWindowResize(): void;
-    /** Re-evaluate responsive page size and filter layout when the table is resized. */
-    private onHostResize;
-    /**
-     * Resolves table-specific translation keys (column headers/filters) plus the
-     * shared keys handled by the base.
-     */
-    protected resolveTranslationKeys(): void;
-    /** Tracks the desktop page size when the user picks one (selector only shows at >= md). */
-    onPageSizeChange(newSize: number): void;
-    protected applyFilter(searchForItems: boolean): void;
     getCellValue(column: ColumnDefinition<T>, row: T): string;
     /** Returns the small-screen cell value for a column with cellSm defined. */
     getCellSmValue(column: ColumnDefinition<T>, row: T): string;
@@ -3979,6 +4123,12 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     private emitServerFilters;
     /** Resets every filterable column to its type's empty value. */
     private seedFilterValues;
+    /**
+     * Resolves the selection-summary labels from their translation keys. Resolved
+     * without params so the `{{count}}` / `{{label}}` placeholders survive for the
+     * getters to fill in per render.
+     */
+    private resolveSelectionSummaryKeys;
     /** Resolves the range / boolean filter control labels from their translation keys. */
     private resolveFilterLabelKeys;
     private applySorting;