@keenmate/web-multiselect 2.0.1 → 2.2.0-rc01

package/dist/index.d.ts

@@ -72,7 +72,7 @@ declare type ActionsPosition = 'top' | 'bottom';
 /**
  * Context provided to renderBadgeContentCallback
  */
-declare interface BadgeContentRenderContext extends PresentationContext {
+export declare interface BadgeContentRenderContext extends PresentationContext {
     /** Current badges display mode */
     displayMode: BadgesDisplayMode;
     /** Whether the badge is being rendered in the selected items popover */
@@ -114,6 +114,35 @@ export { EnvironmentSnapshot }
 
 export { getEnvironment }
 
+/**
+ * Context handed to `renderGroupLabelContentCallback` as its second argument, so a custom group
+ * header can reflect the selection — e.g. render a "3 / 8" count next to the title. The fields are
+ * populated for every group header; the selection fields are meaningful mainly under
+ * `groupSelectMode: 'cascade'` (a flat multi-select grouped list). Under the default rendering
+ * (no callback) the component draws the count itself; with a callback, YOU own the content and can
+ * render the count however you like from these fields.
+ *
+ * Like {@link OptionContentRenderContext} / {@link BadgeContentRenderContext}, it extends the
+ * shared {@link PresentationContext} (`presentation` / `isFullscreen` / `isModal`), so a group
+ * header can also render leaner in the phone fullscreen overlay.
+ */
+export declare interface GroupLabelRenderContext<T = any> extends PresentationContext {
+    /** The group name (identical to the callback's first argument). */
+    groupName: string;
+    /** The group's currently-visible (filtered) members, in render order. */
+    members: T[];
+    /** The subset of `members` that are currently selected (includes disabled-but-selected). */
+    selectedMembers: T[];
+    /** `selectedMembers.length` — the number to show "behind the group title". */
+    selectedCount: number;
+    /** `members.length` — total visible members in the group. */
+    memberCount: number;
+    /** Visible, non-disabled members — the cascade "select-all" denominator. */
+    selectableCount: number;
+    /** Tristate roll-up of the group under cascade selection. */
+    checkState: 'checked' | 'indeterminate' | 'unchecked';
+}
+
 export declare const initLogger: Logger;
 
 export declare const interactionLogger: Logger;
@@ -191,6 +220,25 @@ declare interface MultiSelectConfig<T = any> {
     getDisplayValueCallback?: (item: T) => string;
     /** Callback to customize badge display text (defaults to display value if not provided) */
     getBadgeDisplayCallback?: (item: T) => string;
+    /**
+     * Order of the CURRENTLY-SELECTED items *where they are displayed* — badges, partial mode
+     * (i.e. which items sit behind the "+N more" badge), and the selected-items popover. This is a
+     * display concern only: `getValue()`, the form output, and `getSelected()` always keep
+     * as-selected (insertion) order regardless of this setting, and the options dropdown is never
+     * reordered.
+     * - `as-selected` (default) — the order items were picked.
+     * - `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).
+     * - `member` — by the `selectedOrderMember` property (or `getSelectedOrderCallback`); numeric
+     *   keys sort numerically, everything else with a locale string compare.
+     * - `custom` — delegate to `selectedOrderCompareCallback`.
+     */
+    selectedOrder?: 'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom';
+    /** Property name used as the sort key when `selectedOrder === 'member'` (selected-items display only). */
+    selectedOrderMember?: string;
+    /** Extract the sort key when `selectedOrder === 'member'` (overrides `selectedOrderMember`). */
+    getSelectedOrderCallback?: (item: T) => string | number;
+    /** Comparator used when `selectedOrder === 'custom'`; standard `(a,b) => number` contract. */
+    selectedOrderCompareCallback?: (a: T, b: T) => number;
     /**
      * Member property name for a "full title" — a fully-qualified label that ships with the
      * data (e.g. a breadcrumb like "Fruit / Pome fruit / Apple"). It is never computed by the
@@ -250,9 +298,10 @@ declare interface MultiSelectConfig<T = any> {
      */
     getIsSelectableCallback?: (node: LTreeNode<T>) => boolean;
     /**
-     * Tree checkbox interaction. `independent` (default) toggles only the clicked
-     * node. `cascade` checks a node's whole subtree and shows a tristate
-     * (checked / indeterminate / unchecked) box on branches. Tree + multiple only.
+     * Tree checkbox interaction. `cascade` (default) checks a node's whole subtree
+     * and shows a tristate (checked / indeterminate / unchecked) box on branches —
+     * what most tree-select UIs do. `independent` toggles only the clicked node.
+     * Tree + multiple only (no subtree to cascade otherwise). Unset → cascade.
      */
     checkboxMode?: 'independent' | 'cascade';
     /**
@@ -270,8 +319,23 @@ declare interface MultiSelectConfig<T = any> {
     groupMember?: string;
     /** Callback to extract group from item */
     getGroupCallback?: (item: T) => string;
-    /** Callback to customize group label content (can return HTML) */
-    renderGroupLabelContentCallback?: (groupName: string) => string | HTMLElement;
+    /**
+     * Callback to customize group label content (can return HTML). Receives the group name and a
+     * {@link GroupLabelRenderContext} with the group's members and selection (e.g. `selectedCount`),
+     * so a custom header can show a per-group count. The second argument is additive — existing
+     * one-argument callbacks keep working.
+     */
+    renderGroupLabelContentCallback?: (groupName: string, context: GroupLabelRenderContext<T>) => string | HTMLElement;
+    /**
+     * Group-header selection in a flat (non-tree) grouped, multi-select list.
+     * - `none` (default) — group headers are inert labels.
+     * - `cascade` — each header shows a **tristate** checkbox that checks/unchecks
+     *   all of that group's currently-visible members. The group itself is never a
+     *   selected value (`getValue()`/badges/form carry member values only); a
+     *   partially-selected group reads indeterminate. Flat + multiple only — no
+     *   effect in tree mode (use `checkboxMode`) or single-select.
+     */
+    groupSelectMode?: 'none' | 'cascade';
     /** Member property name for disabled state extraction */
     disabledMember?: string;
     /** Callback to extract disabled state from item */
@@ -291,12 +355,22 @@ declare interface MultiSelectConfig<T = any> {
      * selected-items popover keeps using renderSelectedItemContentCallback).
      */
     renderBadgeCallback?: (item: T, context: BadgeContentRenderContext) => string | HTMLElement | null | undefined;
-    /** Custom renderer for selected item content in popover - return HTML string or HTMLElement */
-    renderSelectedItemContentCallback?: (item: T) => string | HTMLElement;
+    /**
+     * Custom renderer for selected item content in the selected-items popover — return HTML string
+     * or HTMLElement. Receives a {@link BadgeContentRenderContext} (2nd arg) since a popover item
+     * is rendered through the same badge path: `isInPopover` is `true`, plus the shared
+     * presentation fields. The second argument is additive; one-argument callbacks keep working.
+     */
+    renderSelectedItemContentCallback?: (item: T, context: BadgeContentRenderContext) => string | HTMLElement;
     /** Callback to add custom CSS classes to selected items in popover - return string or array of class names */
     getSelectedItemClassCallback?: (item: T) => string | string[];
-    /** Custom renderer for selected item display in single-select mode - return plain text */
-    renderSelectedContentCallback?: (item: T) => string;
+    /**
+     * Custom renderer for the selected item display in single-select mode — return plain text (it
+     * becomes the input value). Receives a {@link SelectedContentRenderContext} (2nd arg) carrying
+     * the shared presentation fields. The second argument is additive; one-argument callbacks keep
+     * working.
+     */
+    renderSelectedContentCallback?: (item: T, context: SelectedContentRenderContext) => string;
     /** HTML form field ID/name for hidden input */
     formFieldId?: string;
     /**
@@ -595,8 +669,22 @@ declare interface MultiSelectConfig<T = any> {
     onDeselect?: ((option: T) => void) | null;
     /** Event handler: the selection set changed (fire-and-forget). Mirrors the bubbling `change` CustomEvent on the element. */
     onChange?: ((selectedOptions: T[]) => void) | null;
-    /** Callback to format count badge text (for i18n/pluralization). When moreCount is provided, it's for the "+X more" badge in partial mode. */
+    /**
+     * Formats the badges-area count/summary text: the `count` mode badge ("N selected") and the
+     * partial-mode "+X more" badge (when `moreCount` is provided). NOT the small `[N]` chip — that's
+     * {@link getCountLabelCallback}. For i18n/pluralization.
+     */
     getCounterCallback?: ((count: number, moreCount?: number) => string) | null;
+    /**
+     * Formats the small count CHIP shared by the in-input counter (`show-counter`) and each group
+     * header's per-group count. Distinct from {@link getCounterCallback}, which formats the
+     * badges-area "N selected" / "+X more" text. Receives `selected` and `total`: for the in-input
+     * counter `total` is the whole option list; for a group header it's that group's member count.
+     * Return the label as plain text. Default `[selected]` (e.g. `[3]`). Set it to
+     * `` (s, t) => `${s}/${t}` `` for an "x / y" style. One callback drives both so they always
+     * read the same way.
+     */
+    getCountLabelCallback?: ((selected: number, total: number) => string) | null;
     /** Enable tooltips on selected item badges (internal: isBadgeTooltipsEnabled) */
     isBadgeTooltipsEnabled?: boolean;
     /** Callback to generate custom tooltip content for a badge */
@@ -657,11 +745,15 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     }, {
         readonly name: "add";
         readonly description: "The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.";
+    }, {
+        readonly name: "ready";
+        readonly description: "The picker was built and painted for the first time (once per element lifetime). Fires right after the first build — synchronously during upgrade for a normal element, or when the render gate is released (`el.ready()` / removing `defer`) for a deferred one. No detail.";
     }];
     onSelect: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     onDeselect: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     onChange: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     onAdd: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
+    onReady: ((e: CustomEvent<undefined>) => void) | null;
     constructor();
     /**
      * Called by the browser when the surrounding <form> is reset. Clears the
@@ -766,6 +858,17 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     get isOpen(): boolean;
     set isOpen(value: boolean);
     destroy(): void;
+    /**
+     * Release the `defer` render gate: build the picker now (once), with every
+     * option, callback and listener wired while deferred already in place. No-op
+     * when the element wasn't deferred or is already built. `flush()` first so a
+     * synchronous `el.options = …; el.customStylesCallback = …; el.ready()` lands
+     * those pending writes in the single build rather than after it. Latched — the
+     * gate never re-closes. Fires the `ready` event on the first build.
+     */
+    ready(): void;
+    /** Whether the picker has been built (the `ready` event has fired). False while a `defer` gate is still held. */
+    get isReady(): boolean;
 }
 
 /**
@@ -788,6 +891,7 @@ declare type MultiSelectEvents = {
     deselect: MultiSelectEventDetail;
     change: MultiSelectEventDetail;
     add: MultiSelectEventDetail;
+    ready: undefined;
 };
 
 /**
@@ -912,7 +1016,7 @@ export { observeViewport }
  * render leaner content in the phone overlay. Reactive: swapping presentation re-renders and
  * re-invokes the callback with the new value.
  */
-declare interface OptionContentRenderContext extends PresentationContext {
+export declare interface OptionContentRenderContext extends PresentationContext {
     /** Index of the option in the filtered list */
     index: number;
     /** Whether the option is currently selected */
@@ -998,6 +1102,13 @@ export declare type SearchInputMode = 'normal' | 'readonly' | 'hidden';
  */
 export declare type SearchMode = 'filter' | 'navigate';
 
+/**
+ * Context handed to `renderSelectedContentCallback` (single-select selected-value display). Carries
+ * only the shared {@link PresentationContext} fields (`presentation` / `isFullscreen` / `isModal`),
+ * so the single-select label can render leaner in the phone fullscreen overlay.
+ */
+export declare type SelectedContentRenderContext = PresentationContext;
+
 /**
  * Set the level of one category. Accepts the full prefixed name
  * (`MULTISELECT:UI`) or the bare suffix (`UI`) — both normalize to the category
@@ -1120,6 +1231,14 @@ export declare class WebMultiSelect<T = any> {
      */
     private getItemFullTitle;
     private getItemSearchValue;
+    /** Sort key for `selectedOrder === 'member'` (member/callback pattern). */
+    private getItemSortKey;
+    /**
+     * Selected options in the order they should be DISPLAYED (badges / partial "+N more" / popover).
+     * Never mutates state — always returns a fresh array. Display concern only: getValue()/form
+     * output/getSelected() keep as-selected (insertion) order. See `selectedOrder`.
+     */
+    private getOrderedSelectedOptions;
     private getItemIcon;
     private getItemSubtitle;
     private getItemGroup;
@@ -1142,8 +1261,10 @@ export declare class WebMultiSelect<T = any> {
     private buildTree;
     /**
      * Whether cascade checkbox mode is active: a multi-select tree with
-     * `checkbox-mode="cascade"`. Checking a node then toggles its whole subtree
-     * and branches show a tristate box.
+     * `checkbox-mode` NOT set to `independent`. Checking a node then toggles its
+     * whole subtree and branches show a tristate box. Cascade is the DEFAULT
+     * (unset → cascade); opt out per-instance with `checkbox-mode="independent"`.
+     * Only ever active in tree + multiple — no subtree to cascade otherwise.
      */
     private isCascadeMode;
     private cascadePolicy;
@@ -1234,6 +1355,46 @@ export declare class WebMultiSelect<T = any> {
      * Check if any options have groups
      */
     private hasGroups;
+    /**
+     * Whether the flat-group cascade checkbox is active: a multi-select, grouped,
+     * non-tree list with `group-select-mode="cascade"`. When on, each group header
+     * gets a tristate checkbox that toggles all of that group's visible members.
+     * Tree mode has its own `checkbox-mode` cascade, so this stays flat-only.
+     */
+    private isGroupCascadeActive;
+    /**
+     * Tristate check-state of a group from its members: `checked` if every
+     * non-disabled member is selected, `unchecked` if none are, else
+     * `indeterminate`. Disabled members are excluded from the denominator so a
+     * group with a stuck-disabled member can still read fully checked. An empty
+     * (or all-disabled) group reads `unchecked`.
+     */
+    private groupCheckState;
+    /**
+     * Selection roll-up for a flat group's (visible) members: which are selected, how many, and
+     * the tristate check-state. `selectedCount` counts every selected member (including a
+     * disabled-but-selected one) — it's the "N behind the group title". `checkState` excludes
+     * disabled members from its denominator (mirrors the select-all), so a group with a stuck
+     * disabled member can still read fully `checked`. Shared by the header count, the tristate
+     * checkbox, and the `renderGroupLabelContentCallback` context.
+     */
+    private groupSelectionInfo;
+    /**
+     * Formats the small count chip shared by the in-input counter and the per-group header count.
+     * Default `[selected]` (matches the historical in-input `[N]`); a `getCountLabelCallback` can
+     * switch both to e.g. `selected/total`.
+     */
+    private formatCountLabel;
+    /** Trailing count chip for a group header — any grouped list (rendered only when >0 selected). */
+    private groupCountHtml;
+    /**
+     * Shared markup for a `.ms__checkbox` input — the single source of truth for option rows, tree
+     * nodes, and group headers. Indeterminate is a pure CSS state (the box is `appearance: none`, so
+     * no native `input.indeterminate` is needed — virtual-scroll-safe) plus `aria-checked="mixed"`.
+     */
+    private checkboxHtml;
+    /** Group-header tristate checkbox (maps the group's roll-up state onto `checkboxHtml`). */
+    private groupCheckboxHtml;
     private renderDropdown;
     /**
      * Round the OUTER corners of the row at the very top and the row at the very
@@ -1463,6 +1624,16 @@ export declare class WebMultiSelect<T = any> {
     private deselectOption;
     private selectAll;
     clearAll(): void;
+    /**
+     * Flat-group cascade toggle: check or uncheck every (visible) member of a group
+     * in one shot. If the group is fully checked → deselect all its members; else →
+     * select all its non-disabled members. Operates on the currently-filtered
+     * members (same scope as Select-All) and, like Select-All / Clear-All,
+     * batch-mutates then fires a single `commit` — so one render and one `change`
+     * event, and it deliberately bypasses the per-item beforeSelect/beforeDeselect
+     * veto. The group name itself is never added to the selection.
+     */
+    private toggleGroup;
     /**
      * Inline clear (✕) handler: wipe the whole selection and any search text, then
      * restore focus to the input. clearAll() → commit() → renderBadges() already
@@ -1481,6 +1652,18 @@ export declare class WebMultiSelect<T = any> {
      * `onChange` fires once if anything actually changed.
      */
     private commit;
+    /**
+     * Shield the trailing document `click` for one tick. A consumer that drives the
+     * dropdown from their OWN button's click handler (`el.open()` / `el.toggle()`, or a
+     * scrollTo* command re-driving the already-open panel) would otherwise have that
+     * same click bubble to our document-level outside-click listener and immediately
+     * close it. Centralizing it here means every entry point — open(), the internal
+     * pointer path, and the public scrollTo* API — is covered. Cleared next tick, so a
+     * genuine later outside-click still closes as normal. Harmless for non-click
+     * callers (typing, programmatic-on-load, server-driven): no trailing click arrives
+     * before it clears.
+     */
+    private armClickGuard;
     /** Open the dropdown (no-op if already open, or if there is nothing to show). */
     open(): void;
     /** Close the dropdown (no-op if already closed). */