@keenmate/web-multiselect 2.0.1 → 2.2.0-rc01

package/README.md

@@ -21,50 +21,24 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - Custom rendering callbacks for options, badges, and group headers.
 - Form integration via standard hidden inputs (FormData-compatible).
 
-## What's New in v2.0.1
-
-- **Single-select — re-clicking the selected option no longer clears the field** — In a `multiple="false"` picker, clicking or pressing Enter on the option that's already selected used to toggle it off and empty the control. Because a single-select row shows no checkbox, there was no cue you were un-picking, so a confirming click read as an accidental wipe. It's now a no-op that simply closes the dropdown, keeping the value selected; clearing stays the dedicated ✕ button's job (`show-clear`). Multi-select toggle-off and single-select replacement are untouched.
-- **Checkbox tick now sizes from the shared `--base-icon-check-size` token** — The selected-row checkmark was masked at `contain` (≈100% of the box), which only looked right when the glyph carried its own viewBox padding; a theme swapping `--base-icon-check` for an edge-to-edge glyph (e.g. a star) rendered it oversized, and it didn't match pure-admin's `.pa-checkbox`. It now reads `var(--base-icon-check-size, 68%)` — the exact knob pure-admin uses — so the mark renders identically in both and a theme can rescale it once for every component. The indeterminate dash inherits the same mask box. The default Lucide check shrinks slightly (≈100% → 68%) to match; that's intended.
-- **Build-time variable-manifest validator** — A new `scripts/check-variable-manifest.mjs` step (wired into `npm run build` as `check:vars`) diffs the `--ms-*` declared and `--base-*` consumed across `src/css/**` against `component-variables.manifest.json` and fails the build on dead or missing entries. This closes the silent-drift gap behind the generated IDE autocomplete and theme-designer surfaces, which are all derived from that manifest.
-- **Manifest drift cleanup** — Removed 24 inert entries the manifest still advertised (the commented-out `--ms-input-size-*` size-preset surface and five positioning vars dropped in the rc11 field-shell rework) and added the missing `--base-icon-plus` / `--base-icon-add` glyphs, so autocomplete no longer offers non-functional knobs and now covers the "add new" prompt icons.
-
-## What's New in v2.0.0
-
-- **"Add new" creation mode — the picker doubles as a creation tool.** Turn on `allow-add-new`
-  and a search with no matches shows a clickable "Add new …" prompt (label via `add-new-text` /
-  `getAddNewTextCallback`). Choosing it (click, Enter, or arrow-to-focus) fires a new bubbling
-  `add` event; `addNewCallback` creates the option and is **async and cancelable** (return
-  `null`/`undefined` to abort after a confirm dialog or server round-trip) and may return a
-  **rich option** that renders like any other. While it runs the prompt shows a spinner +
-  `add-new-pending-text`. Creation also works with no callback — handle it entirely off the `add`
-  event. See `examples-events-callbacks.html` §EV4b/EV4c.
-
-- **Scroll-to imperative API — jump to any option or group.** New `scrollToIndex()` /
-  `scrollToValue()` / `scrollToGroup()` on the element and picker bring a row into view — pair with
-  `open()` for an "open + jump" gesture. Mode-aware (virtual scroll, tree, mobile fullscreen sheet),
-  they align to the top by default (`{ block: 'center' }` to center) and return `false` when the
-  target isn't in the current filtered list. A companion public `clearSearch()` reveals a
-  filtered-out option so you can then scroll to it, plus a `searchText` getter and a `search(term)`
-  method to read and programmatically drive the query. See §BU06b, §VS03, §TR09b.
-
-- **Checkbox check/dash + filter funnel now flow from the shared `--base-icon-*` contract.** The
-  checkmark and indeterminate dash are now `currentColor` mask glyphs (not CSS-border shapes) reading
-  `--base-icon-check` / `--base-icon-indeterminate`, and the search-mode funnel reads
-  `--base-icon-filter` — so one base override reskins them across every Keenmate component. Inline
-  Lucide fallbacks keep the default look unchanged.
-
-- **`--ms-rem` now bridges to the shared `--base-rem` knob.** The global sizing unit resolves
-  `var(--base-rem, 10px)`, so a theme that sets `--base-rem` rescales the whole component from one
-  variable (the `10px` fallback and per-instance overrides still work with no base layer loaded).
-
-- **Fixed: the count-chip clear ✕ and popover close ✕ vanished on hover.** Both derived their hover
-  background *and* glyph colour from the same accent, so the ✕ melted into its own hover state
-  (fully invisible on near-white accents like Minimal dark). They now fill with a solid accent
-  background and flip the glyph to the on-accent colour, matching the badge remove button.
+## What's New in v2.2.0-rc01
+
+- **Tree cascade is now the default — check a branch, check its subtree** — In a multi-select tree, `checkbox-mode` now defaults to `cascade` (previously `independent`), so ticking a branch selects its whole subtree and branches render a tristate (checked / indeterminate / unchecked) box — what most tree-select UIs do. The emitted selection follows `cascade-select-policy` (default `rolled-up`: a fully-checked subtree collapses to its root value). This is a behavior change for existing tree consumers — set `checkbox-mode="independent"` to keep the old per-node toggling. Flat and single-select lists are unaffected, since there's no subtree to cascade into.
+- **Per-group select-all in flat grouped lists — `group-select-mode="cascade"`** — A new attribute puts a tristate checkbox on each group header in a flat, multi-select, grouped list; clicking it checks or unchecks all of that group's currently-visible members. The group name itself is never a selected value — `getValue()`, badges, and form output carry member values only — a partially-selected group reads indeterminate, and a header toggle fires a single `change`. Disabled members are excluded from the select-all. Default `none` leaves headers inert, as before.
+- **Per-group selected counts + one shared count formatter** — Every group header now shows a count of that group's selected members, rendered as the same small chip as the in-input `[N]` counter (not a new badge style). A new `getCountLabelCallback((selected, total) => string)` formats both the in-input counter and the group chip together so they always read the same way — default `[3]`, or return `` `${s}/${t}` `` for an "x / y of total" style, where `total` is the whole option list for the counter and the group's member count for a header.
+- **Order the selected items — `selected-order`** — Control the sequence chosen items appear in across badges, partial "+N more", and the selected-items popover: `as-selected` (default), `label-asc` / `label-desc`, `member` (by a `selected-order-member` property or `getSelectedOrderCallback`), or `custom` (a comparator). It's display-only — `getValue()`, form output, and `getSelected()` keep insertion order — and because the ordering runs in one shared place, the partial "+N more" split and its remove button always act on the items sorted *after* the visible slice.
+- **Every render callback now receives a context** — `renderGroupLabelContentCallback` gains a second `GroupLabelRenderContext` argument (the group's members and selection, e.g. `selectedCount`), and `renderSelectedItemContentCallback` / `renderSelectedContentCallback` now also receive a context carrying the presentation (`isFullscreen` / `isModal`) — matching the option and badge callbacks. Everything is additive, so existing one-argument callbacks keep working; branch on `isFullscreen` to render leaner content in the phone overlay.
+- **Fixes — selection preservation, hidden search field, "+N more" ✕** — Changing a cosmetic attribute (`badges-display-mode` / `badges-position`) no longer wipes the current selection (it's applied in place, and genuine rebuilds now preserve the runtime selection); `search-input-mode="hidden"` no longer collapses the input row, so the toggle stays at the trailing edge; and the "+N more" badge's ✕ now removes exactly the hidden items instead of silently opening the popover.
+
+## What's New in v2.1.0
+
+- **Render gate — `defer` / `ready()` for flash-free initialization** — A custom element upgrades the instant its script loads and paints with the component's *default* styles, so anything you wire in afterward — a `customStylesCallback`, a framework's shared stylesheet, your options array — lands a beat too late and the badges visibly restyle: the classic custom-element flash. The new boolean `defer` attribute holds the entire first render: while it's set the element builds nothing (it only reserves space via `:host([defer]:not([is-ready]))`), so you assign options, callbacks and listeners first, then call `el.ready()` — or simply remove the attribute, which suits server-driven frameworks like Phoenix LiveView — to build once with everything already in place. The gate is latched, exposes an `el.isReady` getter reflected as an `is-ready` attribute, and fires a one-time `ready` event right after the first build. Elements without `defer` behave exactly as before.
+- **External controls no longer close the dropdown they just re-drove** — Driving an already-open panel from your *own* button — a repeat `open()`/`toggle()`, or a `scrollToIndex()`/`scrollToValue()`/`scrollToGroup()` command — used to let that click bubble to the component's outside-click listener and immediately re-close the panel (the "every second click closes it" symptom). `open()` armed a one-tick guard against exactly this but bailed early when already open, and the `scrollTo*` methods never armed it at all. The guard is now centralized in `armClickGuard()` and armed by `open()` before its early-return and by every `scrollTo*` entry point. Consumers who worked around this with `stopPropagation()` can drop it.
 
 ## Demos & docs
 
-- 🚀 [Live demo](https://web-multiselect.keenmate.dev)
+- 🚀 [Showcase](https://web-multiselect.keenmate.dev)
+- 🧪 [Live demo](https://examples.web-multiselect.keenmate.dev)
 - 📘 [Usage / API reference](./docs/usage.md) — attributes, properties, methods, events.
 - 🎨 [Theming](./docs/theming.md) — `--ms-*` variables, dark mode, cascade layers, Theme Designer integration.
 - 📚 [Examples / cookbook](./docs/examples.md) — rich content, async search, virtual scroll, custom rendering, forms.

package/component-variables.manifest.json

@@ -64,7 +64,7 @@
     { "name": "base-icon-plus", "required": false, "usage": "Plus glyph for the \"add new\" empty-state prompt; chained by --ms-icon-add-new; falls back to base-icon-add then inline Lucide SVG" },
     { "name": "base-icon-add", "required": false, "usage": "Alternate add glyph (fallback for base-icon-plus in the \"add new\" prompt)" },
     { "name": "base-icon-check", "required": false, "usage": "Checkbox/option checkmark glyph; chained by --ms-icon-check; inline Lucide SVG fallback" },
-    { "name": "base-icon-check-size", "required": false, "usage": "mask-size for the checkbox glyph inside its box (shared with pure-admin's .pa-checkbox); default 68%. Also sizes the indeterminate dash (shares the mask box)" },
+    { "name": "base-icon-check-size", "required": false, "usage": "mask-size for the checkbox glyph inside its box (shared with pure-admin's .pa-checkbox); default 68%. Chained by --ms-icon-check-size. Also sizes the indeterminate dash (shares the mask box)" },
     { "name": "base-icon-indeterminate", "required": false, "usage": "Tri-state (partial) checkbox dash glyph; chained by --ms-icon-indeterminate; inline Lucide SVG fallback" },
     { "name": "base-danger-bg", "required": false, "usage": "Error message background" },
     { "name": "base-danger-color", "required": false, "usage": "Error message text color" },
@@ -277,6 +277,7 @@
     { "name": "ms-icon-filter", "category": "icon", "usage": "Funnel glyph (fullscreen search-mode toggle); chains to --base-icon-filter" },
     { "name": "ms-icon-check", "category": "checkbox", "usage": "Checkmark glyph (mask) for a checked checkbox/option; chains to --base-icon-check" },
     { "name": "ms-icon-indeterminate", "category": "checkbox", "usage": "Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate" },
+    { "name": "ms-icon-check-size", "category": "checkbox", "usage": "mask-size for the checkmark/dash glyph inside the checkbox box; chains to --base-icon-check-size (default 68%, the same knob as pure-admin's .pa-checkbox)" },
     { "name": "ms-badge-counter-bg", "category": "badge", "usage": "Counter badge background" },
     { "name": "ms-badge-counter-border", "category": "badge", "usage": "Counter badge border" },
     { "name": "ms-badge-counter-border-color", "category": "badge", "usage": "Counter badge border color" },