@keenmate/web-multiselect 2.0.0-rc02 → 2.0.0-rc03

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { BlissElement } from '@keenmate/web-components-core';
+import { EnvironmentSnapshot } from '@keenmate/web-components-core';
 import { InputDef } from '@keenmate/web-components-core';
 import { Logger } from '@keenmate/web-components-core';
 import { LogLevelDesc } from '@keenmate/web-components-core';
@@ -123,6 +124,31 @@ declare interface LTreeNode<T> {
     data: T | null | undefined;
 }
 
+/**
+ * Options for `showMessage()` — the transient toast the component can surface on top of
+ * itself. It exists mainly so a veto (or any consumer feedback) is visible in the
+ * fullscreen overlay, where page-level UI is covered by the sheet.
+ */
+declare interface MessageOptions {
+    /** Visual tone. Default `'info'`. */
+    variant?: MessageVariant;
+    /** Auto-dismiss after this many ms. `0` keeps it until replaced, tapped, or the panel closes. Default `3000`. */
+    duration?: number;
+    /**
+     * Where the message anchors relative to the control in the **floating/anchored** case
+     * (a floating-ui `Placement`, e.g. `'top'`, `'bottom-start'`, `'right'`). Default
+     * `'bottom'`. Ignored when a fullscreen overlay is open — there the message is pinned
+     * to the bottom-centre of the viewport.
+     */
+    placement?: Placement;
+}
+
+/**
+ * Visual tone of a transient message shown via `showMessage()` (or a veto callback's
+ * returned reason string). Each maps to a `.ms__message--{variant}` theming hook.
+ */
+declare type MessageVariant = 'info' | 'warning' | 'error' | 'success';
+
 /**
  * Generic configuration options for the MultiSelect component
  * @template T The type of data items
@@ -261,6 +287,13 @@ declare interface MultiSelectConfig<T = any> {
     isActionsSticky?: boolean;
     /** Close dropdown after selecting an option (internal: isCloseOnSelect) */
     isCloseOnSelect?: boolean;
+    /**
+     * In the phone fullscreen overlay, auto-focus the search field when it opens — which
+     * pops the soft keyboard immediately. Default `false`: the sheet opens showing the list
+     * (keyboard closed), and the keyboard appears only when the user taps the search. Set
+     * `true` to type-to-filter right away (matches native pickers). No effect in the floating
+     * presentation. (internal: fullscreenAutofocus) */
+    fullscreenAutofocus?: boolean;
     /** Lock dropdown placement after first open (internal: isPlacementLocked) */
     isPlacementLocked?: boolean;
     /** Allow adding new options not in the list (internal: isAddNewAllowed) */
@@ -404,20 +437,23 @@ declare interface MultiSelectConfig<T = any> {
     /**
      * Interceptor: runs before an option is selected via user interaction.
      * Receives the option about to be added and the current selection (before the change).
-     * Return `false` to block the selection; return `true`/`undefined` to allow.
-     * Silent — a blocked action fires no event. Bypassed by programmatic `setSelected`
-     * and the Select-All action button.
+     * Return `false` to block the selection; return `true`/`undefined` to allow. Return a
+     * **string** to block AND surface it as a message (see `showMessage`) — the touch-safe
+     * way to explain a veto in the fullscreen overlay, where page-level UI is hidden behind
+     * it. Silent otherwise — a blocked action fires no event. Bypassed by programmatic
+     * `setSelected` and the Select-All action button.
      */
-    beforeSelectCallback?: ((option: T, selectedOptions: T[]) => boolean | void) | null;
+    beforeSelectCallback?: ((option: T, selectedOptions: T[]) => boolean | string | void) | null;
     /**
      * Interceptor: runs before an option is deselected via user interaction — the dropdown
      * option toggle, a badge's remove (×) button, the selected-items popover's remove button,
      * and the "remove hidden" badge (checked per item). Receives the option about to be
      * removed and the current selection (before the change). Return `false` to block the
-     * deselection; return `true`/`undefined` to allow. Silent — a blocked action fires no
-     * event. Bypassed by programmatic `setSelected` and the Clear-All action button.
+     * deselection; return `true`/`undefined` to allow. Return a **string** to block AND
+     * surface it as a message (see `showMessage`). Silent otherwise — a blocked action fires
+     * no event. Bypassed by programmatic `setSelected` and the Clear-All action button.
      */
-    beforeDeselectCallback?: ((option: T, selectedOptions: T[]) => boolean | void) | null;
+    beforeDeselectCallback?: ((option: T, selectedOptions: T[]) => boolean | string | void) | null;
     /**
      * Async function to load data: `(searchTerm, signal) => Promise<options[]>`.
      * The optional second argument is an `AbortSignal` that fires when a newer search
@@ -502,6 +538,11 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
      * picker's selection so the control participates in the standard reset.
      */
     formResetCallback(): void;
+    /** Runtime writing-direction switch (core observes `dir`): re-mirror the live
+     *  picker. Layout mostly follows the inherited `direction` (logical properties);
+     *  refreshDirection() fixes the parts pinned at build time (the `.ms--rtl` class
+     *  and the panels' explicit `dir`). The initial direction is read by the build. */
+    protected directionChanged(_isRTL: boolean): void;
     /** Structural change (or first connect): mirror CSS vars, then (re)build the picker. */
     protected reinit(): void;
     /** Cosmetic change: mirror CSS vars / custom styles / debug, patch the picker in place. */
@@ -510,6 +551,15 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     protected connect(): void;
     /** Deactivate: tear the picker down (rebuilt on the next connect). */
     protected disconnect(): void;
+    /**
+     * Device/viewport/orientation changed (core §12.9). Overriding this opts the
+     * element into the shared environment observable — core subscribes on connect
+     * (firing immediately with the current snapshot) and unsubscribes on disconnect.
+     * We map it to the picker's floating/fullscreen presentation; the immediate fire
+     * lands right after `connect()` builds the picker, so the initial presentation is
+     * set before the dropdown can open.
+     */
+    protected environmentChanged(env: EnvironmentSnapshot): void;
     /** Form field name (mirrors the `name` attribute → `formFieldId`). */
     get name(): string | null;
     set name(value: string | null);
@@ -520,6 +570,16 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
         notify?: boolean;
     }): void;
     getValue(): string | number | (string | number)[] | null;
+    /**
+     * Surface a transient message ("toast") on top of the component — visible even in the
+     * fullscreen overlay, where page-level UI is hidden behind the sheet. Content is text or
+     * an element; `opts.variant` sets the tone and `opts.duration` the auto-dismiss (0 =
+     * sticky). Also reached automatically when a `beforeSelect`/`beforeDeselect` callback
+     * returns a reason string.
+     */
+    showMessage(content: string | HTMLElement, opts?: MessageOptions): void;
+    /** Dismiss the transient message shown by {@link showMessage}, if any. */
+    hideMessage(): void;
     destroy(): void;
 }
 
@@ -712,11 +772,29 @@ export declare class WebMultiSelect<T = any> {
     private isRTL;
     private effectiveBadgesPosition;
     private justClosedViaClick;
+    private justOpenedViaClick;
     private positioningDriftWarned;
+    private presentationMode;
+    private fullscreenHeader;
+    private fullscreenSearchInput;
+    private fullscreenNav;
+    private fullscreenNavCount;
+    private fullscreenNavPrev;
+    private fullscreenNavNext;
+    private bodyScrollUnlock;
+    private keyboardInsetCleanup;
+    private overlayHistoryActive;
+    private readonly onOverlayPopstate;
     private dropdownCleanup;
     private hintCleanup;
     private selectedPopoverCleanup;
     private tooltips;
+    private labelRevealTrigger;
+    private labelRevealPanel;
+    private labelRevealPopover;
+    private messageEl;
+    private messageCleanup;
+    private messageTimer;
     private readonly onDropdownScroll;
     private virtualScroll;
     private optionsContainer;
@@ -837,6 +915,23 @@ export declare class WebMultiSelect<T = any> {
      * here. Pass all options to show the whole tree.
      */
     private rebuildTreeVisibleFromMatches;
+    /**
+     * (Re)compute `isRTL` from the host's `dir` (or an RTL ancestor) and derive the
+     * direction-mirrored badges position. Pure state — callers apply the DOM effects
+     * (class toggle, panel `dir`, badge re-render). In Shadow DOM the `dir` lives on
+     * the host element, not the shadow content, so we resolve the host first.
+     */
+    private detectRTL;
+    /**
+     * Re-read `dir` and re-apply RTL mirroring live. The web-component calls this when
+     * its `dir` attribute changes at runtime (e.g. an app-wide language/direction
+     * switch). Most layout follows the inherited CSS `direction` automatically (the
+     * component is authored with logical properties); this fixes the parts pinned at
+     * build time — the `.ms--rtl` class (badges/count-display placement) and the
+     * explicit `dir` on the shadow-root-appended panels (which don't sit under the
+     * `.ms--rtl` element, so they'd otherwise keep a stale build-time direction).
+     */
+    refreshDirection(): void;
     private buildHTML;
     /**
      * Check if virtual scroll should be used
@@ -865,6 +960,15 @@ export declare class WebMultiSelect<T = any> {
     private getBuiltInActionDisabled;
     private renderActionsHTML;
     private renderOption;
+    /**
+     * Trailing info affordance for an option row, emitted only for the fullscreen
+     * overlay. CSS keeps it hidden until `markTruncatedOptions()` tags the row
+     * `.ms__option--truncated`, so it appears only when the label is actually clipped.
+     * Tapping it reveals the full label — the touch substitute for the hover option
+     * tooltip, which never fires on touch (the very devices that get fullscreen).
+     * `tabindex="-1"` keeps it out of the tab order; the search input owns keyboarding.
+     */
+    private renderOptionInfoButton;
     /**
      * Render a single tree-mode row. Separate from `renderOption`: a tree row is
      * indented by its depth (via the `--ms-tree-depth` custom property) and
@@ -974,6 +1078,103 @@ export declare class WebMultiSelect<T = any> {
      */
     private warnDrift;
     private positionDropdown;
+    /**
+     * Switch how the open panels are presented. 'floating' anchors them to the input
+     * (the default); 'fullscreen' renders them as full-viewport overlays (the phone
+     * pattern) — the dropdown with its own search header + close, the selected-items
+     * popover with its existing header + close. Driven by the element's
+     * `environmentChanged` hook (auto → fullscreen on phones). A no-op when unchanged;
+     * when a panel is already open it re-applies live so an orientation flip / viewport
+     * resize can swap presentation without a reopen.
+     */
+    setPresentation(mode: 'floating' | 'fullscreen'): void;
+    /**
+     * Lock page scroll behind a fullscreen overlay via the core ref-counted helper.
+     * Idempotent per instance: the dropdown and the selected-items popover are mutually
+     * exclusive (opening one closes the other), so we hold at most one lock at a time,
+     * and a redundant call is a no-op rather than acquiring a second.
+     */
+    private lockBodyScroll;
+    /** Restore page scroll (no-op if it wasn't locked). */
+    private unlockBodyScroll;
+    /**
+     * While the fullscreen dropdown is open, keep it sitting above the soft keyboard.
+     * Delegates to core's `observeKeyboardInset` (which tracks `window.visualViewport`
+     * and pins the panel's height/top so its flex column reflows above the keyboard);
+     * we just hold the returned cleanup. No-op where `visualViewport` is unavailable.
+     */
+    private observeKeyboardInset;
+    /** Detach keyboard-inset tracking and restore the panel's CSS-driven geometry. */
+    private unobserveKeyboardInset;
+    /**
+     * The fullscreen size multiplier = `--ms-fullscreen-rem ÷ --ms-rem` (both read off
+     * the host). CSS scales itself — every size is `calc(N × --ms-rem)` and the panel
+     * overrides `--ms-rem` — so this exists only for the JS-driven pixel heights that
+     * CSS can't reach: the virtual/fixed option rows and the popover's virtual badges.
+     * Returns 1 when floating (or when computed styles aren't readable, e.g. jsdom).
+     */
+    private fullscreenScale;
+    /** Virtual/fixed row height (px), scaled up in the fullscreen phone view. */
+    private scaledOptionHeight;
+    /**
+     * Size the virtual options scroll container for the current presentation. Applied on
+     * every render (the container itself is built once), so a floating⇄fullscreen switch
+     * re-sizes it: floating = a fixed maxHeight scroll box; fullscreen = flex-fill the
+     * panel's flex column (no fixed height). Also refreshes --ms-option-height to the
+     * scaled row height so the CSS row height matches the virtual scroller's itemHeight.
+     */
+    private applyVirtualOptionsSizing;
+    /**
+     * Virtual popover badge row height (px). In the fullscreen phone view the rows are
+     * scaled up AND given extra height so a selected item is a comfortable, dropdown-like
+     * touch target (the default 36px pill is short for touch). Mirrors the CSS
+     * `--ms-badge-height` override for the fullscreen popover (floating.css) so the
+     * virtual list's fixed height agrees with the non-virtual pills.
+     */
+    private scaledBadgeHeight;
+    /**
+     * Clear the inline geometry that floating-ui's `anchor` writes on a panel
+     * (position/left/top plus our composed max-width/min-width). Inline styles beat
+     * the stylesheet, so a panel left over from a floating cycle would otherwise pin
+     * itself where it last anchored and ignore the fullscreen CSS (position: fixed;
+     * inset: 0; width: 100vw). Must run when switching a panel floating → fullscreen.
+     */
+    private clearFloatingInlineGeometry;
+    /** Stand up the fullscreen dropdown overlay: modifier class, header, scroll lock, focus. */
+    private enterFullscreen;
+    /** Tear down the fullscreen dropdown chrome and restore page scroll (no-op if floating). */
+    private exitFullscreen;
+    /**
+     * Back-gesture handling for the fullscreen sheet. On open we push a history entry
+     * (same URL) and listen for `popstate`; the phone Back gesture/button then pops that
+     * entry — which we treat as "close the sheet" — instead of navigating away from the
+     * page. A programmatic close (✕, selection, Escape) consumes the entry via
+     * `history.back()` so the stack is left as it was found.
+     */
+    private pushOverlayHistory;
+    /** Back gesture/button fired: our pushed entry is already gone, so just close the
+     *  sheet — WITHOUT popping history again (popOverlayHistory becomes a no-op). */
+    private handleOverlayPopstate;
+    /** Programmatic close: remove the listener and pop the entry we pushed (so the
+     *  history stack returns to its pre-open state). No-op if a Back gesture already
+     *  consumed it (overlayHistoryActive is false by then). */
+    private popOverlayHistory;
+    /**
+     * Build the fullscreen overlay header: a search field (proxying to the same
+     * `handleSearch`/`handleKeydown` path as the main input, since the overlay covers
+     * it) plus a close button. Inserted before the scrolling list so it pins to the
+     * top of the fixed panel. `renderDropdown()` only rewrites `dropdownInner`, so the
+     * header survives re-renders.
+     */
+    private buildFullscreenHeader;
+    /**
+     * Sync the fullscreen match navigator (navigate mode only) with the current search
+     * state: hide it until there's a term, then show "N of M" while a match is focused
+     * (or "M matches" / "No matches"), and disable the prev/next buttons when there's
+     * nothing to step through. No-op when the navigator isn't built (floating panel,
+     * filter mode, or search disabled).
+     */
+    private updateFullscreenNav;
     private positionHint;
     private parseInitialSelection;
     /**
@@ -1052,6 +1253,42 @@ export declare class WebMultiSelect<T = any> {
      * `filteredOptions`, the same global index `renderOption` was given.
      */
     private attachOptionTooltips;
+    /**
+     * Tag each currently-rendered fullscreen option row whose title is horizontally
+     * clipped with `.ms__option--truncated`, so CSS reveals its info affordance.
+     * Runs per virtual-scroll render (rows recycle) and on the non-virtual render.
+     * Horizontal (ellipsis) overflow only — the truncation mode this pairs with;
+     * a wrapping title isn't "cut", it grows vertically. No-op unless fullscreen.
+     */
+    private markTruncatedOptions;
+    /**
+     * Reveal (or dismiss) the full label of a clipped fullscreen row when its info
+     * affordance is tapped — hover tooltips don't fire on touch, and a hover tooltip's
+     * synthetic mouseleave (from the tap itself, under devtools touch emulation) would
+     * flash it away. So this is a manually-controlled `createPopover` panel, mounted in
+     * the shadow root for component styling, that stays until explicitly dismissed:
+     * a second tap on the same button, a list scroll, a re-render, an outside tap, or
+     * closing the panel (see hideLabelReveal + its call sites). Tapping the same button
+     * while it's shown toggles it off.
+     */
+    private toggleLabelReveal;
+    /** Dismiss the full-label reveal popover, if shown. Idempotent. */
+    private hideLabelReveal;
+    /**
+     * Show a transient message ("toast") on top of the component. Its reason for existing:
+     * in the fullscreen overlay the sheet covers the whole page, so a consumer can't surface
+     * feedback (a blocked veto, a hint) where the user can see it. This renders above the
+     * panel in BOTH presentations — anchored under the control when floating, pinned to the
+     * bottom of the viewport (over the overlay) when fullscreen.
+     *
+     * Content is a string (plain text) or an HTMLElement (rich markup). `opts.variant`
+     * (info | warning | error | success) picks the tone; `opts.duration` sets auto-dismiss
+     * (0 = sticky). Tapping the message dismisses it. Only one shows at a time — a new call
+     * replaces the previous. Also reached automatically when a veto callback returns a string.
+     */
+    showMessage(content: string | HTMLElement, opts?: MessageOptions): void;
+    /** Dismiss the transient message, if shown. Idempotent. */
+    hideMessage(): void;
     /**
      * Hide (don't destroy) every currently-shown option tooltip immediately,
      * ignoring the hide delay. Wired to dropdown scroll so a tooltip can't trail