mn-angular-lib 1.0.130 → 1.0.132

package/package.json

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

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

@@ -3354,7 +3354,24 @@ declare abstract class MnCollectionBase<T, DS extends MnCollectionDataSource<T>>
     /** Client-side search filtering shared by list and grid. */
     protected applySearchFilter(items: T[]): T[];
     protected processLoadedRows(rows: T[]): void;
-    protected validateDataSource(): void;
+    /**
+     * Reports every misconfigured pagination setting and repairs it in place.
+     *
+     * This deliberately does **not** throw. It runs first in {@link ngOnInit}, and a
+     * throw there aborts the rest of init — the data subscription is never made and
+     * {@link applyFilter} never runs, so the component renders a permanently empty
+     * body that only "heals" once some later interaction happens to call
+     * {@link applyFilter}. That failure mode reads as "the table is broken" rather
+     * than "the data source is misconfigured", and inside a modal the thrown error
+     * is easy to miss entirely. Logging loudly and degrading to the nearest working
+     * mode keeps the misconfiguration visible while still rendering the rows.
+     */
+    protected normalizeDataSource(): void;
+    /**
+     * Logs a data-source configuration problem, prefixed with the component name.
+     * @param message What is wrong and how it was compensated for.
+     */
+    private reportConfigError;
     static ɵfac: i0.ɵɵFactoryDeclaration<MnCollectionBase<any, any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<MnCollectionBase<any, any>, never, never, { "dataSource": { "alias": "dataSource"; "required": false; }; }, {}, never, never, true, never>;
 }
@@ -3456,6 +3473,31 @@ type TableAppearance = {
     hover?: boolean;
     compact?: boolean;
     bordered?: boolean;
+    /**
+     * How column widths are computed. Defaults to `stable`.
+     *
+     * - `stable` (default): the best of both. The first render with rows on screen
+     *   uses the browser's automatic layout, so each column is sized in proportion to
+     *   its real content; those measured widths are then pinned and the table switches
+     *   to a fixed layout. Columns therefore keep sensible, content-derived
+     *   proportions **and** stop moving when the rows change underneath — a new page,
+     *   a filter or a search cannot resize them. Widths are re-measured only when the
+     *   table itself is resized (or a {@link ColumnBase.hiddenBelow} column appears or
+     *   disappears), never when the rows change. Content that no longer fits is
+     *   truncated with an ellipsis and exposed as a `title` tooltip.
+     * - `auto`: the plain browser layout. Every column is re-sized to its widest cell
+     *   on every change, so the columns shift on each new page, filter and search.
+     *   Use it for a static table, or when a cell must never be truncated.
+     * - `fixed`: widths are **data-independent**. Nothing is measured — not the cell
+     *   content, and not the header text either. Each column is either its declared
+     *   {@link ColumnBase.width} or an even share of whatever is left over:
+     *   `(table width − Σ declared widths) ÷ number of undeclared visible columns`.
+     *   Only worth choosing over `stable` when every column declares a `width`, or
+     *   when a deliberate even split is what you want: with widths undeclared, a
+     *   two-character status column is handed exactly as much room as a long
+     *   description.
+     */
+    layout?: 'auto' | 'fixed' | 'stable';
 };
 /**
  * The control rendered for a column filter, and the shape of the value it produces:
@@ -3702,7 +3744,20 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     private readonly filterDebounce;
     /** The open filter popover, used to tell inside clicks from outside ones. */
     private filterPopover?;
-    constructor();
+    /**
+     * 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
+     * a phone is the opposite of what it is for — it pushes the paginator below the
+     * fold, which is most damaging inside a modal, where the sheet is already short
+     * and its footer is pinned over the bottom of the table.
+     */
+    private static readonly MOBILE_PAGE_SIZE;
+    /**
+     * The component's own element, measured for every responsive decision. Typed via
+     * the annotation, not `inject(ElementRef<HTMLElement>)` — that form is a generic
+     * call on the token and leaves `nativeElement` untyped.
+     */
+    private readonly host;
     /** Whether the consumer owns filtering (server-side), mirroring {@link isServerSearched}. */
     get isServerFiltered(): boolean;
     /** Every column filter that is actually set, in column order. */
@@ -3774,12 +3829,21 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     get clearFiltersButtonLabel(): string;
     /** Opens/closes the stacked filter panel shown on small screens. */
     toggleFiltersPanel(): void;
-    /** Re-evaluate responsive page size and filter layout when the viewport changes. */
-    protected onWindowResize(): void;
+    private readonly baseTableClasses;
+    /**
+     * Column widths measured from the automatic layout and pinned, keyed by column
+     * key, for `stable`. Empty until the first render that has real rows on screen,
+     * and cleared whenever the table is resized so the next render re-measures.
+     */
+    private pinnedWidths;
     /** Sets sort/filter state seeded from the data source before the first filter pass. */
     protected beforeInitialFilter(): void;
-    /** True when the viewport is below the filter-collapse breakpoint. */
-    private isFilterViewport;
+    /**
+     * Whether {@link pinColumnWidths} has run. Tracked separately from
+     * {@link pinnedWidths} being non-empty, because the widest column is deliberately
+     * left unpinned and a table with a single flexible column therefore pins nothing.
+     */
+    private widthsPinned;
     /**
      * Recomputes whether the inline filter row should collapse into the panel.
      * Closes the panel when returning to the wide layout so reopened state never
@@ -3796,19 +3860,74 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     getColumnSkeletonData(column: ColumnDefinition<T>): Partial<MnSkeletonProps>;
     getSortIcon(column: ColumnDefinition<T>): string;
     isSortable(column: ColumnDefinition<T>): boolean;
-    /** Rows shown per page on mobile (< md). Forced regardless of any configured pageSize. */
-    private static readonly MOBILE_PAGE_SIZE;
+    constructor();
+    /**
+     * Classes for the `<table>` element. `table-fixed` is added once column widths
+     * are no longer allowed to follow the content: always for the `fixed` layout, and
+     * for `stable` from the moment its widths have been measured and pinned.
+     */
+    get tableClasses(): string;
     /** Page size to use at/above the `md` breakpoint (consumer's pageSize, or the user's selection). */
     private desktopPageSize;
-    /** True when the viewport is below the `md` (768px) breakpoint. */
-    private isMobileViewport;
+    /** The effective column-width strategy, defaulting to `stable`. */
+    get layoutMode(): 'auto' | 'fixed' | 'stable';
     /**
-     * Applies the breakpoint-appropriate page size: {@link MOBILE_PAGE_SIZE} below `md`,
-     * the desktop size at/above it. When the size actually changes, client-side tables
-     * re-slice locally and server-side tables ask the consumer to refetch, so the
-     * rendered rows update in every pagination mode (used at init and on window resize).
+     * Whether column widths have stopped following the cell content — `fixed` always,
+     * `stable` once {@link pinColumnWidths} has captured them. Drives `table-fixed`
+     * and the cell truncation together, so a cell is never clipped while the column
+     * it sits in could still have grown to fit it.
      */
-    private applyResponsivePageSize;
+    get widthsArePinned(): boolean;
+    /**
+     * The width to render for a column: the consumer's own declared width always
+     * wins, then a width pinned by the `stable` layout, otherwise none.
+     * @param column The column being rendered.
+     * @returns A CSS width, or `null` to leave it to the layout algorithm.
+     */
+    columnWidth(column: ColumnDefinition<T>): string | null;
+    /**
+     * The `title` tooltip for a cell, so text truncated by a pinned column stays
+     * readable. Only string cells have text to expose; template cells render their
+     * own markup and are left alone.
+     * @param column The column being rendered.
+     * @param row The row being rendered.
+     * @returns The full cell text, or `null` when there is nothing to expose.
+     */
+    cellTitle(column: ColumnDefinition<T>, row: T): string | null;
+    /**
+     * Captures the current, automatically-derived width of every visible column and
+     * pins it, which flips the table to `table-fixed` on the next render.
+     *
+     * Runs only with real rows on screen: measuring the loading skeletons would pin
+     * the placeholder bars' widths rather than the data's. Hidden columns
+     * ({@link ColumnBase.hiddenBelow}) measure 0 and are skipped, so they are free to
+     * size themselves if a resize later reveals them.
+     *
+     * The **widest** column is measured but deliberately left unpinned, so it absorbs
+     * whatever space the pinned ones leave over. Pinning every column instead makes the
+     * widths sum to slightly more than the container — `border-collapse` shares borders
+     * between neighbours, so rounding each cell's measured width over-counts them — and
+     * the table then overflows into a spurious horizontal scrollbar. Leaving one column
+     * elastic also means a later resize squeezes the widest column first instead of
+     * clipping every column equally.
+     */
+    private pinColumnWidths;
+    /**
+     * Drops the pinned widths so the next render with rows re-measures them. Called
+     * when the table is resized: the old pixel widths were shares of a box that no
+     * longer exists, and a resize is also what makes `hiddenBelow` columns come and
+     * 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.
@@ -3821,7 +3940,36 @@ declare class MnTable<T = object> extends MnSelectableCollectionBase<T, TableDat
     /** Returns the small-screen cell value for a column with cellSm defined. */
     getCellSmValue(column: ColumnDefinition<T>, row: T): string;
     trackByKey: (_index: number, column: ColumnDefinition<T>) => string;
-    readonly tableClasses = "w-full border-collapse overflow-y-hidden";
+    /** True when the table is narrower than the filter-collapse breakpoint. */
+    private isFilterViewport;
+    /**
+     * True when the **window** is below the `md` (768px) breakpoint.
+     *
+     * Deliberately viewport-based, unlike {@link isFilterViewport}: the forced
+     * mobile page size exists to keep a phone screen scrollable, and it is paired
+     * with the rows-per-page selector that mn-collection-pagination hides at the
+     * same viewport breakpoint. Measuring the table's own width instead would let
+     * the two disagree — a 700px table on a desktop would be pinned to the mobile
+     * row count while still offering the selector that overrides it.
+     */
+    private isMobileViewport;
+    /**
+     * The table's own rendered width, which every responsive decision is made
+     * against — the same width the `@container` queries in the template use, so
+     * the TS and CSS halves of the responsive layout can never disagree.
+     *
+     * Falls back to the window width before the host has been laid out (and in
+     * SSR), which is the closest available approximation at that point.
+     * @returns The width in CSS pixels.
+     */
+    private measuredWidth;
+    /**
+     * Applies the breakpoint-appropriate page size: capped at {@link MOBILE_PAGE_SIZE}
+     * below `md`, the desktop size at/above it. When the size actually changes, client-side tables
+     * re-slice locally and server-side tables ask the consumer to refetch, so the
+     * rendered rows update in every pagination mode (used at init and on window resize).
+     */
+    private applyResponsivePageSize;
     get totalColumnCount(): number;
     /**
      * Hands the active filters to the consumer. Locks the body height first so the
@@ -3889,6 +4037,14 @@ declare function matchesColumnFilter<T>(column: ColumnDefinition<T>, row: T, val
  * Attribute directive that applies responsive-hiding classes to table cells/headers.
  * Hides the element by default and shows it as `table-cell` at the specified breakpoint.
  *
+ * The breakpoints are **container** queries against the table's own width, not the
+ * viewport: a table inside a modal (or any narrow column) is far narrower than the
+ * window, so viewport breakpoints would reveal columns the table has no room for.
+ * mn-table marks its chrome `@container` for exactly this.
+ *
+ * Because of that, `sm`/`md`/`lg` mean "the table is at least this wide", and the
+ * thresholds are **not** the viewport values of the same names — see {@link classMap}.
+ *
  * Uses a static class map so Tailwind CSS can detect the full class names at build time.
  *
  * Usage: `<td [mnHiddenBelow]="column.hiddenBelow">`
@@ -3899,7 +4055,18 @@ declare class MnHiddenBelowDirective implements OnChanges {
     private readonly el;
     private readonly renderer;
     private appliedClasses;
-    /** Static mapping of breakpoints to their full Tailwind class names. */
+    /**
+     * Static mapping of breakpoints to their full Tailwind class names, so Tailwind
+     * can detect them at build time.
+     *
+     * These are **container** widths, deliberately lower than the viewport
+     * breakpoints they are named after. A table almost never gets the whole window:
+     * a page table sits inside a docked sidebar plus page padding, which on a
+     * 1280px screen leaves it under 900px. Reusing 1024px for `lg` would demand a
+     * ~1400px window before an `lg` column ever appeared — hiding columns on the
+     * most ordinary laptop. These values instead express how much room the column
+     * itself needs, which is what a container query should measure.
+     */
     private readonly classMap;
     ngOnChanges(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<MnHiddenBelowDirective, never>;