@keenmate/web-multiselect 2.1.0 → 2.2.0-rc02

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@keenmate/web-multiselect",
-  "version": "2.1.0",
+  "version": "2.2.0-rc02",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -76,6 +76,11 @@
               "description": "HTML form field name/id used for the hidden input(s).",
               "value": { "type": "string | null" }
             },
+            {
+              "name": "custom-styles",
+              "description": "Raw CSS injected into the Shadow DOM — the declarative alternative to `customStylesCallback`. The value is a full stylesheet (selectors and all), dropped verbatim into a replaceable style slot at the top of the shadow root. `customStylesCallback` takes precedence when both are set.",
+              "value": { "type": "string | null" }
+            },
             {
               "name": "dropdown-width",
               "description": "Fixed dropdown width; mirrored to the `--ms-dropdown-width` CSS variable.",
@@ -158,10 +163,10 @@
             },
             {
               "name": "checkbox-mode",
-              "description": "Tree checkbox interaction.\n- `independent` (default) — toggles only the clicked node.\n- `cascade` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches.\n\nTree + multiple only.",
+              "description": "Tree checkbox interaction.\n- `cascade` (default) — checks a node's whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. This is what most tree-select UIs do, so it's the default.\n- `independent` — toggles only the clicked node, ignoring ancestors/descendants.\n\nTree + multiple only — has no effect on flat lists or single-select (there is no subtree to cascade into).",
               "value": {
                 "type": "'independent' | 'cascade'",
-                "default": "'independent'"
+                "default": "'cascade'"
               }
             },
             {
@@ -172,6 +177,11 @@
                 "default": "'rolled-up'"
               }
             },
+            {
+              "name": "group-select-mode",
+              "description": "Group-header selection in a FLAT (non-tree) grouped, multi-select list.\n- `none` (default) — group headers are inert labels.\n- `cascade` — each header shows a tristate checkbox that checks/unchecks all of that group's currently-visible members; a partially-selected group reads indeterminate. The group itself is never a selected value (getValue / badges / form carry member values only).\n\nFlat + multiple only — no effect in tree mode (use `checkbox-mode`) or single-select.",
+              "value": { "type": "'none' | 'cascade'", "default": "'none'" }
+            },
             {
               "name": "badges-display-mode",
               "description": "How the current selection is shown in the control.",
@@ -193,6 +203,19 @@
               "description": "How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.",
               "value": { "type": "'count' | 'partial'", "default": "'count'" }
             },
+            {
+              "name": "selected-order",
+              "description": "Order of the CURRENTLY-SELECTED items where they are displayed — badges, partial mode (which items sit behind the \"+N more\" badge), and the selected-items popover. Display only: `getValue()`, the form output, and `getSelected()` keep as-selected (insertion) order, and the options dropdown is never reordered.\n- `as-selected` (default) — the order items were picked.\n- `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).\n- `member` — by the `selected-order-member` property (or `getSelectedOrderCallback`); numeric keys sort numerically, everything else with a locale string compare.\n- `custom` — delegate to `selectedOrderCompareCallback`.",
+              "value": {
+                "type": "'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom'",
+                "default": "'as-selected'"
+              }
+            },
+            {
+              "name": "selected-order-member",
+              "description": "Property name used as the sort key when `selected-order=\"member\"`. Sorts the SELECTED-items display only (not the dropdown). Overridden by `getSelectedOrderCallback`.",
+              "value": { "type": "string | null" }
+            },
             {
               "name": "search-input-mode",
               "description": "Search field mode: editable, read-only, or hidden.",
@@ -610,6 +633,11 @@
                 "description": "HTML form field name/id used for the hidden input(s).",
                 "type": "string | null"
               },
+              {
+                "name": "customStyles",
+                "description": "Raw CSS injected into the Shadow DOM — the declarative alternative to `customStylesCallback`. The value is a full stylesheet (selectors and all), dropped verbatim into a replaceable style slot at the top of the shadow root. `customStylesCallback` takes precedence when both are set.",
+                "type": "string | null"
+              },
               {
                 "name": "dropdownWidth",
                 "description": "Fixed dropdown width; mirrored to the `--ms-dropdown-width` CSS variable.",
@@ -697,7 +725,7 @@
               },
               {
                 "name": "checkboxMode",
-                "description": "Tree checkbox interaction.\n- `independent` (default) — toggles only the clicked node.\n- `cascade` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches.\n\nTree + multiple only.",
+                "description": "Tree checkbox interaction.\n- `cascade` (default) — checks a node's whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. This is what most tree-select UIs do, so it's the default.\n- `independent` — toggles only the clicked node, ignoring ancestors/descendants.\n\nTree + multiple only — has no effect on flat lists or single-select (there is no subtree to cascade into).",
                 "type": "'independent' | 'cascade'"
               },
               {
@@ -705,6 +733,11 @@
                 "description": "In `cascade` mode, which values a selection emits (badges / form / change):\n- `rolled-up` (default) — minimal cover: a fully-selected subtree collapses to its root; partially-selected branches emit their individually-checked descendants.\n- `leaves` — only the checked leaf-level nodes.\n- `all` — every fully-checked node (branches and leaves).",
                 "type": "'rolled-up' | 'leaves' | 'all'"
               },
+              {
+                "name": "groupSelectMode",
+                "description": "Group-header selection in a FLAT (non-tree) grouped, multi-select list.\n- `none` (default) — group headers are inert labels.\n- `cascade` — each header shows a tristate checkbox that checks/unchecks all of that group's currently-visible members; a partially-selected group reads indeterminate. The group itself is never a selected value (getValue / badges / form carry member values only).\n\nFlat + multiple only — no effect in tree mode (use `checkbox-mode`) or single-select.",
+                "type": "'none' | 'cascade'"
+              },
               {
                 "name": "badgesDisplayMode",
                 "description": "How the current selection is shown in the control.",
@@ -720,6 +753,16 @@
                 "description": "How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.",
                 "type": "'count' | 'partial'"
               },
+              {
+                "name": "selectedOrder",
+                "description": "Order of the CURRENTLY-SELECTED items where they are displayed — badges, partial mode (which items sit behind the \"+N more\" badge), and the selected-items popover. Display only: `getValue()`, the form output, and `getSelected()` keep as-selected (insertion) order, and the options dropdown is never reordered.\n- `as-selected` (default) — the order items were picked.\n- `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).\n- `member` — by the `selected-order-member` property (or `getSelectedOrderCallback`); numeric keys sort numerically, everything else with a locale string compare.\n- `custom` — delegate to `selectedOrderCompareCallback`.",
+                "type": "'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom'"
+              },
+              {
+                "name": "selectedOrderMember",
+                "description": "Property name used as the sort key when `selected-order=\"member\"`. Sorts the SELECTED-items display only (not the dropdown). Overridden by `getSelectedOrderCallback`.",
+                "type": "string | null"
+              },
               {
                 "name": "searchInputMode",
                 "description": "Search field mode: editable, read-only, or hidden.",
@@ -1035,6 +1078,16 @@
                 "description": "Extra CSS class(es) for an option badge.",
                 "type": "(item: unknown) => string | string[]"
               },
+              {
+                "name": "getSelectedOrderCallback",
+                "description": "Sort key for the selected-items display when `selected-order=\"member\"` (overrides `selected-order-member`).",
+                "type": "(item: unknown) => string | number"
+              },
+              {
+                "name": "selectedOrderCompareCallback",
+                "description": "Comparator for the selected-items display when `selected-order=\"custom\"`.",
+                "type": "(a: unknown, b: unknown) => number"
+              },
               {
                 "name": "getIconCallback",
                 "description": "Icon for an option (overrides iconMember).",
@@ -1055,6 +1108,11 @@
                 "description": "Render the selected-count label.",
                 "type": "(count: number, moreCount?: number) => string"
               },
+              {
+                "name": "getCountLabelCallback",
+                "description": "Format the small count chip shared by the in-input counter and each group header count (default `[selected]`; e.g. `(s,t)=>`${s}/${t}``). One callback drives both.",
+                "type": "(selected: number, total: number) => string"
+              },
               {
                 "name": "getValueFormatCallback",
                 "description": "Serialize the selected values for form submission.",
@@ -1097,18 +1155,18 @@
               },
               {
                 "name": "renderGroupLabelContentCallback",
-                "description": "Customize a group label; may return an HTML string or element.",
-                "type": "(groupName: string) => string | HTMLElement"
+                "description": "Customize a group label; may return an HTML string or element. The second arg carries the group members + selection (e.g. `context.selectedCount`) so a custom header can show a per-group count.",
+                "type": "(groupName: string, context: GroupLabelRenderContext) => string | HTMLElement"
               },
               {
                 "name": "renderSelectedContentCallback",
-                "description": "Custom render for the whole selected area.",
-                "type": "(item: unknown) => string"
+                "description": "Custom render for the single-select selected value (2nd arg carries the presentation context).",
+                "type": "(item: unknown, context: SelectedContentRenderContext) => string"
               },
               {
                 "name": "renderSelectedItemContentCallback",
-                "description": "Custom render for one selected item.",
-                "type": "(item: unknown) => string | HTMLElement"
+                "description": "Custom render for one selected item in the popover (2nd arg is a BadgeContentRenderContext; isInPopover=true).",
+                "type": "(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement"
               },
               {
                 "name": "customStylesCallback",