mn-angular-lib 1.0.161 → 1.0.163

package/package.json

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

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

@@ -2826,6 +2826,8 @@ type MnMultiSelectUIConfig = {
     errorMessages?: Record<string, string>;
     /** Text shown when no options match the search filter */
     noOptionsFound?: string;
+    /** Placeholder and accessible name for the dropdown's search input */
+    searchPlaceholder?: string;
 };
 
 declare const MN_MULTI_SELECT_CONFIG: InjectionToken<MnMultiSelectUIConfig>;
@@ -3047,6 +3049,34 @@ declare class MnMultiSelect implements OnInit {
      * is selected, then `collapsePlaceholder`, then `"{count} selected"`.
      */
     get collapseSummaryText(): string;
+    /** Trigger text shown while nothing is selected. */
+    get placeholderLabel(): string;
+    /**
+     * Placeholder and accessible name of the dropdown's search input.
+     *
+     * Search auto-enables at `searchThreshold` options, so this box appears without any
+     * call site opting in — which is exactly why it must be translatable without one.
+     */
+    get searchPlaceholderLabel(): string;
+    /** Empty text shown when the search filters every option away. */
+    get noOptionsLabel(): string;
+    /**
+     * Resolves one of the component's own labels, preferring what the caller gave it
+     * and falling back through the config layer, a conventional translation key and
+     * finally a readable English default.
+     *
+     * Mirrors `MnCollectionBase.resolveLabel`. Every string this component puts on
+     * screen that is not caller data goes through here: without the key step a
+     * consumer could only translate these by repeating the same literal at every call
+     * site, which is how "Search..." ends up in English on an otherwise Dutch page.
+     *
+     * @param explicit The label the caller passed through `props`, if any.
+     * @param key The conventional translation key to try next.
+     * @param fallback The English text used when neither resolves.
+     * @param configured The value the config layer resolved, if any.
+     * @returns The resolved label.
+     */
+    private resolveLabel;
     handleBlur(): void;
     get control(): _angular_forms.AbstractControl<any, any, any> | null;
     get showError(): boolean;
@@ -3909,6 +3939,28 @@ type MnSelectProps<TValue = unknown> = {
     placeholder?: string;
     /** Available options to select from */
     options: MnSelectOption<TValue>[];
+    /**
+     * Whether to show a search/filter input at the top of the panel. When omitted, search
+     * auto-enables once the number of options reaches `searchThreshold`, so long lists stay
+     * filterable without every call site having to opt in. Set explicitly to force it on or off.
+     */
+    searchable?: boolean;
+    /**
+     * Number of options at which the search input auto-enables (default: 8).
+     * Ignored when `searchable` is set explicitly.
+     */
+    searchThreshold?: number;
+    /** Placeholder text for the search input */
+    searchPlaceholder?: string;
+    /**
+     * Whether the option panel renders as a bottom sheet on small screens (< 640px).
+     * Defaults to true. Set to false to keep the trigger-anchored panel on mobile.
+     *
+     * The anchored panel sits at the trigger's bottom edge, which puts it directly in
+     * the path of the soft keyboard as soon as the search input takes focus. The sheet
+     * is anchored to the viewport instead, so the list stays reachable.
+     */
+    mobileSheet?: boolean;
     /** Size variant of the select (default: 'md') */
     size?: MnSelectVariants['size'];
     /** Border radius variant (default: 'md') */
@@ -3940,45 +3992,248 @@ type MnSelectUIConfig = {
      * These override built-in error messages but are overridden by props.errorMessages.
      */
     errorMessages?: Record<string, string>;
+    /** Text shown when no options match the search filter */
+    noOptionsFound?: string;
+    /** Placeholder and accessible name for the dropdown's search input */
+    searchPlaceholder?: string;
 };
 
 declare const MN_SELECT_CONFIG: InjectionToken<MnSelectUIConfig>;
+/**
+ * A single-value picker. The trigger opens a `role="listbox"` of {@link MnSelectOption}s;
+ * choosing one sets the value and closes — this is the value-picker twin of the ⋯
+ * command menu mn-dropdown, so it *is* a ControlValueAccessor.
+ *
+ * Presentation mirrors mn-multi-select: one custom field trigger at every size, an
+ * anchored popover on desktop and the shared {@link MnBottomSheet} on mobile (< 640px) —
+ * the same sheet mn-dropdown itself wraps. Both the popover and the sheet host are
+ * portalled to `document.body` so their `position: fixed` anchors to the viewport rather
+ * than any transformed/filtered ancestor (a table cell, a card) — the same root-cause fix
+ * the multi-select applies.
+ */
 declare class MnSelect implements OnInit {
     ngControl: NgControl | null;
     props: MnSelectProps;
     /** Currently selected value */
     selectedValue: unknown;
+    isOpen: boolean;
     isDisabled: boolean;
+    searchTerm: string;
     protected uiConfig: MnSelectUIConfig;
     private readonly configService;
     private readonly sectionPath;
     private readonly explicitInstanceId;
+    private readonly elRef;
     private readonly lang;
     private readonly destroyRef;
+    private readonly renderer;
+    private readonly cdr;
+    /** Lucide data for the trailing check shown on the selected row. */
+    protected readonly checkIcon: mn_angular_lib.LucideIconData;
+    /** Reference to the trigger element for positioning the dropdown. */
+    triggerRef: ElementRef<HTMLElement>;
+    /** Layout classes for the anchored popover panel. The mobile sheet is rendered by
+     *  mn-bottom-sheet instead, so it no longer needs a branch here. */
+    readonly panelClasses = "fixed z-9999 bg-base-100 border border-base-300 rounded-md shadow-lg max-h-60 overflow-auto";
+    /** Layout classes for the invisible click shield rendered under the anchored panel.
+     *  One step below the panel's z-index so the panel itself stays clickable, and above
+     *  any modal/drawer chrome (which tops out well under 9998). */
+    readonly shieldClasses = "fixed inset-0 z-9998";
+    /** Option count at which the search input auto-enables when `searchable` is unset. */
+    private static readonly DEFAULT_SEARCH_THRESHOLD;
+    /** Tailwind's `sm` breakpoint — below this the panel renders as a bottom sheet.
+     *  Kept in step with the same constant in mn-bottom-sheet / mn-multi-select. */
+    private static readonly SHEET_MAX_WIDTH;
+    /** The anchored popover panel currently moved into `document.body`, if any. */
+    private movedPanel;
+    /** The click shield currently moved into `document.body`, if any. */
+    private movedShield;
+    /** The bottom-sheet host, for outside-click tests. The sheet owns its own placement. */
+    private sheetHost;
+    /** Whether the viewport is currently narrow enough for the sheet layout. */
+    private isNarrowViewport;
+    /** Live breakpoint match, so rotating the device re-evaluates the layout. */
+    private sheetMedia;
+    /** The listener registered on `sheetMedia`, retained for teardown. */
+    private sheetMediaListener;
+    /** `document.body`'s inline `overflow` before the sheet locked it, restored on close. */
+    private previousBodyOverflow;
+    /**
+     * The sheet's height (px) captured the moment it opened, before any search. Re-applied
+     * as a `min-height` floor so filtering the option list shorter cannot shrink the sheet
+     * mid-type. Null while anchored or closed, so the popover and desktop path are untouched.
+     */
+    sheetFloorPx: number | null;
+    /**
+     * Watches the trigger while the panel is open. The panel lives in `document.body`, so it
+     * survives its own trigger being hidden by an ancestor — a wizard step or a tab switched
+     * away with `display: none`. When the trigger stops being visible the panel goes with it.
+     */
+    private visibilityObserver;
+    /**
+     * Capture-phase scroll listener installed while open. `window:scroll` only fires for the
+     * document scroller, so scrolling an inner container (a modal body, a scrollable card)
+     * would otherwise leave the portalled panel floating at its stale coordinates.
+     */
+    private scrollCapture;
+    /** Dropdown position calculated from the trigger's bounding rect. */
+    dropdownStyle: {
+        top: string;
+        left: string;
+        width: string;
+    };
+    private onChange;
+    private onTouched;
     private readonly builtInErrorMessages;
     constructor();
-    get selectedOption(): MnSelectOption | undefined;
+    /**
+     * The dropdown panel element, queried while it is rendered by the `@if` block. The setter
+     * relocates the panel to `document.body` so that its `position: fixed` coordinates resolve
+     * against the viewport rather than any transformed/filtered ancestor (which would otherwise
+     * become the containing block and push the panel to the middle of the screen — also broken
+     * on iOS). Cleanup is handled when the query clears on close/destroy.
+     */
+    set dropdownRef(ref: ElementRef<HTMLElement> | undefined);
+    /**
+     * The click shield sitting under the anchored panel, portalled alongside it for the same
+     * reason: `position: fixed` must resolve against the viewport, not a transformed ancestor.
+     */
+    set shieldRef(ref: ElementRef<HTMLElement> | undefined);
+    /**
+     * The bottom-sheet host, kept as a reference for outside-click tests. The sheet relocates
+     * itself to `document.body`, so nothing is moved here. On open its container height is
+     * captured as the sheet's `min-height` floor.
+     */
+    set sheetRef(ref: ElementRef<HTMLElement> | undefined);
     get control(): _angular_forms.AbstractControl<any, any, any> | null;
+    get selectedOption(): MnSelectOption | undefined;
+    /** The label shown in the trigger: the selected option, else the placeholder. */
+    get displayText(): string;
+    /** Trigger text shown while no option is selected. */
+    get placeholderLabel(): string;
+    /** Placeholder and accessible name of the dropdown's search input. */
+    get searchPlaceholderLabel(): string;
+    /** Empty text shown when the search filters every option away. */
+    get noOptionsLabel(): string;
+    /**
+     * Resolves one of the component's own labels, preferring what the caller gave it
+     * and falling back through the config layer, a conventional translation key and
+     * finally a readable English default.
+     *
+     * Mirrors `MnCollectionBase.resolveLabel` and its twin in `MnMultiSelect`. Without
+     * the key step a consumer could only translate these by repeating the same literal
+     * at every call site, and the search box in particular auto-enables on option
+     * count — it appears without anyone asking for it, so it must be translatable
+     * without anyone asking either.
+     *
+     * @param explicit The label the caller passed through `props`, if any.
+     * @param key The conventional translation key to try next.
+     * @param fallback The English text used when neither resolves.
+     * @param configured The value the config layer resolved, if any.
+     * @returns The resolved label.
+     */
+    private resolveLabel;
     get showError(): boolean;
     get errorMessages(): string[];
     get errorMessage(): string | null;
     get resolvedId(): string;
     get resolvedName(): string | null;
-    get selectClasses(): string;
+    get triggerClasses(): string;
+    /** Whether the panel should currently render as a bottom sheet. */
+    get isSheet(): boolean;
+    /**
+     * Whether the search input is shown: the explicit `searchable` prop when set, otherwise
+     * auto-enabled once the option count reaches the threshold.
+     */
+    get isSearchable(): boolean;
+    get filteredOptions(): MnSelectOption[];
     ngOnInit(): void;
     writeValue(val: unknown): void;
     registerOnChange(fn: (val: unknown) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
-    /** Returns the index of an option, used as the <option> value attribute */
-    optionIndex(option: MnSelectOption): string;
-    /** Handles native select change event */
-    onSelectChange(event: Event): void;
+    toggle(): void;
+    /** Selects an option, notifies the form and closes — a single choice ends the interaction. */
+    selectOption(option: MnSelectOption): void;
     isSelected(option: MnSelectOption): boolean;
+    onSearch(term: string | null): void;
+    /**
+     * The single close path. Every trigger (outside click, Escape, scroll, resize, the trigger
+     * being hidden, a choice) funnels through here so the open-only listeners are always torn
+     * down with the panel and never leak.
+     */
+    close(): void;
     handleBlur(): void;
+    /**
+     * Dismisses the anchored panel from a shield click, and stops the event there.
+     *
+     * Swallowing it is the point: the shield spans the viewport, so the click would otherwise
+     * land on whatever the panel was floating over. Inside a modal that is the modal's own
+     * backdrop, and "close the dropdown" would double as "throw away the modal". A first click
+     * that only dismisses the overlay is also how native selects and menus behave.
+     */
+    onShieldClick(event: Event): void;
+    onDocumentClick(event: Event): void;
+    /** Closes the dropdown on Escape for keyboard accessibility. */
+    onEscape(): void;
+    /**
+     * Closes the dropdown when the page or a scrollable parent is scrolled.
+     *
+     * Skipped for a sheet: it is anchored to the viewport, not to the trigger, so it has no
+     * stale position to escape. Crucially, opening the soft keyboard fires a `resize` on
+     * Android — closing on that would dismiss the sheet the instant search is focused. A
+     * genuine layout switch is handled by the `matchMedia` listener instead.
+     */
+    onWindowScrollOrResize(): void;
     protected isRequired(): boolean;
-    private onChange;
-    private onTouched;
+    /**
+     * Tracks the sheet breakpoint through `matchMedia` rather than reading `innerWidth` once,
+     * so rotating the device switches layout instead of leaving a panel positioned for the
+     * previous orientation. An open panel is closed on the switch — its anchored coordinates
+     * and its sheet layout are not interchangeable.
+     */
+    private startWatchingViewport;
+    /** Tears down the breakpoint listener. Idempotent. */
+    private stopWatchingViewport;
+    /**
+     * Freezes the page behind an open sheet. The previous inline value is captured and restored
+     * verbatim so a surrounding modal that set its own lock is left intact.
+     */
+    private lockBodyScroll;
+    /** Restores the pre-lock `overflow`. Idempotent. */
+    private unlockBodyScroll;
+    /** Calculates the fixed position for the dropdown based on the trigger element. */
+    private updateDropdownPosition;
+    /**
+     * Starts the open-only watchers: an `IntersectionObserver` on the trigger (closes the panel
+     * as soon as the trigger stops being rendered/visible) and a capture-phase `scroll` listener
+     * (closes it when any ancestor scroller moves under it). Scrolls that originate inside the
+     * panel's own option list are ignored.
+     */
+    private startWatchingTrigger;
+    /** Tears down the watchers installed by `startWatchingTrigger`. Idempotent. */
+    private stopWatchingTrigger;
+    /**
+     * Records the sheet's opened height as its `min-height` floor. Measured on the next frame
+     * so the read reflects the fully-rendered, unfiltered list (the search box is empty on
+     * open) and never forces a reflow mid change-detection. The floor equals the content height
+     * at that instant, so applying it triggers no resize — it only stops a later, shorter
+     * filtered list from pulling the sheet down.
+     *
+     * `hostEl` is the portalled mn-bottom-sheet host (`display: contents`), so the height is
+     * read from its `.mn-sheet-container` child rather than the host itself.
+     */
+    private captureSheetFloor;
+    /**
+     * Move an overlay element to `document.body` when it appears, and detach it when the query
+     * clears. Appending to the body root makes the element immune to ancestor
+     * `transform`/`filter`/`will-change`, so `position: fixed` anchors to the viewport — without
+     * this the panel lands mid-screen (and breaks outright on iOS).
+     *
+     * Returns the element now portalled, so the caller can store it. Idempotent and safe to
+     * call with `null`.
+     */
+    private portal;
     private resolveConfig;
     private pickErrorKey;
     private resolveErrorMessageForKey;
@@ -4239,10 +4494,14 @@ type MnTranslatable = {
  */
 type MnConfigValue<T = string> = T | MnTranslatable;
 /**
- * A flat key-value map of translations for a single locale.
- * Supports nested keys via dot notation: "form.email.label"
+ * Translations for a single locale, as a tree of keys.
+ *
+ * Both shapes resolve through the same dotted lookup: a bundle may nest
+ * (`{ form: { email: { label } } }`), flatten (`{ "form.email.label": … }`), or mix the two.
  */
-type MnTranslationMap = Record<string, string>;
+type MnTranslationMap = {
+    [key: string]: string | MnTranslationMap;
+};
 /**
  * All loaded translations keyed by locale code (e.g. "en", "nl", "de").
  */
@@ -4278,6 +4537,11 @@ declare class MnLanguageService {
     private _locale$;
     private _urlPattern;
     private _debug;
+    /**
+     * `Intl.PluralRules` per locale. Cached because {@link translate} runs on every change
+     * detection through the impure `mnTranslate` pipe, and constructing one is not cheap.
+     */
+    private readonly _pluralRules;
     /** Observable of the current active locale. */
     readonly locale$: Observable<string>;
     /** Current active locale. */
@@ -4309,8 +4573,42 @@ declare class MnLanguageService {
      * Falls back to the key itself if no translation is found.
      *
      * Interpolation replaces `{{paramName}}` with the provided value.
+     *
+     * A `count` param additionally selects the wording that agrees with it: the key is
+     * resolved against its CLDR plural category first (`key` + `One`/`Two`/`Few`/`Many`/
+     * `Zero`), falling back to `key` when that sibling is undefined. Nothing has to opt in —
+     * a key with no sibling behaves exactly as before.
+     *
+     * ```ts
+     * // 'shift.asked'    → '{{count}} members are notified'
+     * // 'shift.askedOne' → '{{count}} member is notified'
+     * lang.translate('shift.asked', { count: 3 }); // 3 members are notified
+     * lang.translate('shift.asked', { count: 1 }); // 1 member is notified
+     * ```
      */
     translate(key: string, params?: Record<string, string | number>): string;
+    /**
+     * Picks the wording that agrees with a `count` param.
+     *
+     * A key carrying a count resolves against its CLDR plural category first, so
+     * `askedMessage` + `askedMessageOne` render "3 leden krijgen bericht" and "1 lid krijgt
+     * bericht" off the same call. Both languages change the verb as well as the noun, which
+     * is why each form is a whole sentence under its own key rather than a swapped noun.
+     *
+     * Falls back to `key` whenever the sibling is undefined, so a key that never needed a
+     * plural — or an app that has not written one yet — behaves exactly as it did before.
+     * @param map The active locale's translations.
+     * @param key The dot-notated translation key.
+     * @param params The interpolation values, inspected for `count`.
+     * @returns The key to look up: the plural sibling, or `key` itself.
+     */
+    private resolvePluralKey;
+    /**
+     * The CLDR plural category of a count in the active locale.
+     * @param count The count being quoted.
+     * @returns The category, falling back to English rules for an unusable locale.
+     */
+    private pluralCategory;
     /**
      * Helper to retrieve a value from a potentially nested translation map using a dot-notated key.
      */
@@ -7120,6 +7418,8 @@ declare class MnList<T = unknown> extends MnSelectableCollectionBase<T, ListData
     protected applyFilter(searchForItems: boolean): void;
     /** Accessible name for the scrollable list region. */
     get listRegionLabel(): string;
+    /** Label on the header checkbox that selects or clears every visible row. */
+    get selectAllLabel(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<MnList<any>, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MnList<any>, "mn-list", never, {}, { "itemClick": "itemClick"; }, never, never, true, never>;
 }
@@ -8562,8 +8862,12 @@ declare class MnBreadcrumbs {
     crumbClick: EventEmitter<MnBreadcrumbItem>;
     /** Emits when the fallback "Back" control is activated. */
     back: EventEmitter<void>;
-    /** Default translation key / literal for the Back control's label. */
-    private static readonly DEFAULT_BACK_LABEL;
+    /** Conventional key an app defines to translate the Back control's label. */
+    private static readonly BACK_LABEL_KEY;
+    /** Conventional key an app defines to name the navigation landmark. */
+    private static readonly NAV_LABEL_KEY;
+    /** Resolves this component's own labels against the app's bundle. */
+    private readonly lang;
     /** Resolved tailwind-variants slot functions for the current size. */
     get styles(): {
         root: (slotProps?: ({
@@ -8604,9 +8908,25 @@ declare class MnBreadcrumbs {
             size?: "sm" | "md" | undefined;
         } & tailwind_variants.ClassProp<tailwind_merge.ClassNameValue>) | undefined) => string;
     } & {};
+    /**
+     * Accessible name of the `<nav>` landmark.
+     *
+     * A landmark's name is announced verbatim, so leaving it as a hardcoded English
+     * "Breadcrumb" put one English word into every page of a translated app — in the
+     * one place only screen-reader users hear.
+     */
+    get navLabel(): string;
     /** Whether a linkable trail should render (vs the Back fallback). */
     get hasTrail(): boolean;
-    /** Label for the Back control — the configured key/literal, or the default. */
+    /**
+     * Text of the Back control, already translated.
+     *
+     * `data.backLabel` is a key (or a literal, which `translate` passes through
+     * unchanged). Without one this falls back to the conventional key and then to
+     * English — never to a raw key: the old default was the bare key `'back'`, which
+     * the template's translate pipe echoed as lowercase "back" in every app that had
+     * not happened to define it.
+     */
     get backLabel(): string;
     /** The last crumb is the current page and is rendered as plain text. */
     isCurrent(index: number): boolean;