@keenmate/web-multiselect 1.12.0-rc08 → 2.0.0-rc02

package/README.md

@@ -21,6 +21,52 @@ 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.0-rc02
+
+**Form association restored for host frameworks (`el.form`).** Selecting inside a
+`<web-multiselect>` that lives in a `<form>` again delivers changes to frameworks
+that resolve the parent form via `event.target.form` — most notably Phoenix
+LiveView's `phx-change` delegation, which silently dropped changes in rc01.
+`<web-multiselect>` is a form-associated custom element, so it now exposes a real
+`el.form` / `event.target.form` like a native control. (rc01 had hardened its
+internal `ElementInternals` handle to a true `#private` field, which killed the
+`.form` that host-framework wrappers read.) The fix lives upstream in
+[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core)
+1.0.0-rc02 (the `el.form` getter), which this release pins.
+
+See `CHANGELOG.md` for the full list.
+
+## What's New in v2.0.0-rc01
+
+**The core-adoption major.** `<web-multiselect>` is now built on
+[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core)
+(`BlissElement`) — shared, tested custom-element plumbing (attribute parsing,
+reactivity, reflection, event handling, logging, registration, positioning). The
+dropdown, tree, virtual scroll, theming, and every attribute behave the same; the
+change is under the hood, with three **breaking** API changes to be aware of:
+
+- **`onSelect` / `onDeselect` / `onChange` are event-handler properties now.** They
+  receive the `CustomEvent` (like `el.onclick`), so read `e.detail.option` /
+  `e.detail.selectedOptions` / `e.detail.selectedValues` instead of a bare
+  argument — equivalent to `addEventListener('select', …)`. The bubbling
+  `select` / `deselect` / `change` events are unchanged.
+- **`setAttributes()` takes typed property values by camelCase key.**
+  `el.setAttributes({ searchPlaceholder: 'Search…', isCounterShown: true })`. To
+  batch attribute **strings**, use `el.batch(() => { el.setAttribute('search-placeholder', 'Search…'); … })`.
+- **Property writes are async (coalesced).** Setting a property (e.g.
+  `el.options = […]`) applies on a microtask; `await el.whenSettled()` before
+  reading back rendered state. `setAttributes()` / `batch()` still flush
+  synchronously.
+- **`data-options` gains CSV & plain formats.** The `data-options` attribute now
+  takes `data-options-format="json|csv|plain"` (default `json`) — feed a CSV table
+  (first row is a header; columns mapped via `*-member`) or a bare, newline-
+  delimited value list without hand-writing JSON. Field and row delimiters are
+  configurable via `data-options-splitter` / `data-options-row-splitter` (so TSV
+  or a custom separator is expressible in the attribute), and `data-options` is
+  now a fully reactive, shape-validated input — changing any of these re-renders.
+
+See `CHANGELOG.md` for the full list.
+
 ## What's New in v1.12.0-rc08
 
 - **Panel sizing — dropdown and popover are independently sizable via CSS variables** — The options dropdown and selected-items popover no longer inherit the input's width. `--ms-dropdown-width` (defaults to the live input width) and `--ms-selected-popover-width` (intrinsic 32rem) drive them, alongside the existing max-height variables. Set them at app level (`web-multiselect { --ms-dropdown-width: 60rem }`) or override a single instance with the new `dropdown-width` / `selected-popover-width` attributes, which write those variables inline on the element. This also fixes a latent bug where `--ms-selected-popover-width` was dead (an internal width-sync always overrode it), so the popover now honours its 32rem default. See section 14 of `examples-tree.html`.
@@ -29,12 +75,6 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - **Theming cleanup — dead input size-variant surface removed from the bundle** — The unused `.ms__input--xs/sm/lg/xl` preset classes and their `--ms-input-size-*` variable chain were never wired to anything (no `size` attribute toggles them), so they've been commented out — kept for a possible future preset API but no longer shipped as dead CSS (the compiled stylesheet shrank ~2 kB). Input sizing still works through `--ms-rem` for proportional global scale or the individual `--ms-input-*` variables for targeted overrides.
 - **Fixes — badge hover and live cascade switching** — Badge hover no longer washes the chip to white (the hover background fell through to the white input background; it now deepens the accent tint, dark-mode aware). And switching `checkbox-mode` or `cascade-select-policy` live rebuilds the cascade index and silently re-projects the current selection, so badges, form value, and checkboxes all reflect the new mode instantly.
 
-## What's New in v1.12.0-rc07
-
-- **Selection — `setSelected(values, { notify: true })` announces programmatic changes** — `setSelected()` stays silent by default (restoring saved state, cascade/dependent resets, and server-authoritative corrections must not re-fire `change`, or they trip "the user changed it" handlers and can bounce in a feedback loop), but the new `{ notify: true }` option fires a **single aggregate `change`** — no per-item `select`/`deselect` flood — for when a programmatic change is a deliberate user gesture, e.g. a custom action button that sets the selection and should reach the same listeners a manual pick does. Threaded through both the internal picker and the web component's `setSelected`.
-- **Cascade mode — Select All now honours the value policy** — the built-in `select-all` action added every selectable node's value directly, bypassing the cascade projection, so with `checkbox-mode="cascade"` + `cascade-select-policy="rolled-up"` it emitted every node instead of the rolled-up roots (unlike a click, which rolls up). `selectAll()` is now cascade-aware — it fills the checked-atom set from the visible nodes and projects through the active policy via a shared `commitCascadeAtoms` helper — so Select All emits the same shape a click does. Shown in the new "Action Buttons" section of `examples-tree.html`.
-- **Options no longer text-select on click-drag** — clicking a row, or dragging across the dropdown, used to highlight the labels like selectable text, which reads as broken for a pure selection gesture (most visible on the denser tree rows). Options now set `user-select: none` (with the `-webkit-` prefix) on `.ms__option`. Purely presentational — no API or behaviour change.
-
 > ⚠️ **Security notice:** This component intentionally allows raw HTML in rendering callbacks to give developers full control over content display. If you display user-generated content, you must sanitize it yourself. See [docs/examples.md → HTML Injection (XSS) notice](./docs/examples.md#html-injection-xss-notice) for the complete list of affected callbacks.
 
 ## Demos & docs
@@ -90,6 +130,32 @@ npm install @keenmate/web-multiselect
 
 See [docs/usage.md](./docs/usage.md) for the full API and [docs/examples.md](./docs/examples.md) for advanced patterns (async data, virtual scrolling, custom rendering, form integration).
 
+## Editor IntelliSense
+
+The package ships editor metadata so you get autocomplete and hover docs for the
+element's attributes, events, and all `--ms-*` CSS custom properties. All of it is
+generated from the component's source on every build, so it never drifts.
+
+- **JetBrains** (WebStorm / IntelliJ) — works automatically. The IDE discovers
+  `web-types.json` via the `web-types` field in `package.json`; no setup needed.
+- **VS Code** — the data files ship but VS Code doesn't auto-discover them from a
+  dependency, so point your workspace at them once in `.vscode/settings.json`:
+
+  ```json
+  {
+    "html.customData": [
+      "./node_modules/@keenmate/web-multiselect/vscode.html-custom-data.json"
+    ],
+    "css.customData": [
+      "./node_modules/@keenmate/web-multiselect/vscode.css-custom-data.json"
+    ]
+  }
+  ```
+
+  `html.customData` powers tag/attribute completion on `<web-multiselect>`;
+  `css.customData` powers completion for the `--ms-*` theming variables. Reload
+  the window after adding them.
+
 ## Browser support
 
 Modern evergreen browsers — anything with native `customElements`, Shadow DOM, and CSS `@layer` support: