sb-floating-panel-vue 5.2.1 → 5.3.1

package/README.md

@@ -17,10 +17,12 @@ Headless Vue 3 components for floating panels (dropdowns, menus, listboxes, popo
 ## 📦 Installation
 
 ```bash
-npm install sb-floating-panel-vue vue @floating-ui/vue
+npm install sb-floating-panel-vue
 ```
 
-`vue` (`^3.5.13`) and `@floating-ui/vue` (`^2.0.1`) are peer dependencies: your app provides them, so only one copy of each ends up in the bundle. Vue is usually already installed in your app.
+`vue` (`^3.5.13`) and `@floating-ui/vue` (`^2.0.1`) are peer dependencies, so only one copy of each ends up in the bundle. Vue is already in your app. You don't need to install `@floating-ui/vue` yourself: npm 7+ and pnpm 8+ add missing peers automatically. Yarn doesn't, so add it there: `yarn add sb-floating-panel-vue @floating-ui/vue`.
+
+If your app already depends on `@floating-ui/vue`, it must be a 2.x version (npm stops with `ERESOLVE` otherwise), and the library uses that same copy. If you only used it to position dropdowns, menus, popovers or tooltips, the library already does that for you: move those panels to its components and remove `@floating-ui/vue` from your `package.json`. Keep it only if your own code still imports it.
 
 There is no CSS file to import.
 
@@ -123,34 +125,17 @@ Holds the state and the positioning. Renders no element of its own, only its slo
 | `closeOnClickOutside` | `boolean` | `true` | Closes on a pointer press outside the reference and the panel (on touch, on the tap's click) |
 | `closeOnFocusOut` | `boolean` | `true` | Closes when keyboard focus moves outside the reference and the panel |
 
-| Event         | Payload         | Description                   |
-| ------------- | --------------- | ----------------------------- |
-| `update:open` | `boolean`       | Used by `v-model:open`        |
-| `open`        | `SbOpenReason`  | The panel has opened, and why |
-| `close`       | `SbCloseReason` | The panel has closed, and why |
-
-The reason tells what opened or closed the panel, e.g. for analytics or to react only to a dismissal:
-
-| Reason | `open` | `close` |
-| --- | --- | --- |
-| `trigger` | Click on the reference, Enter, Space or an arrow key on it | Click on the reference, Enter or Space on it |
-| `hover` | Pointer over the reference (`hover` trigger) | Pointer left the reference and the panel (`hover` trigger) |
-| `focus` | Focus on the reference (`hover` and `focus` triggers) | — |
-| `focus-out` | — | Focus moved outside, e.g. Tab out of a menu |
-| `escape` | — | Escape, or the arrow key that closes a submenu |
-| `outside` | — | Press outside the reference and the panel |
-| `select` | — | Item activated with `closeOnSelect` |
-| `detached` | — | Reference scrolled out of view, with `hideWhenDetached: 'close'` |
-| `disabled` | — | The container was disabled |
-| `api` | `v-model:open`, slot props, exposed methods, `useSbFloating()` | Same, or the reference unmounting |
+| Event         | Payload                      | Description            |
+| ------------- | ---------------------------- | ---------------------- |
+| `update:open` | `boolean`                    | Used by `v-model:open` |
+| `open`        | `SbOpenReason` (deprecated)  | The panel has opened   |
+| `close`       | `SbCloseReason` (deprecated) | The panel has closed   |
 
-```vue
-<SbContainer @close="(reason) => reason === 'select' && track('menu-pick')">
-```
+The reason passed to `open` and `close` (what opened or closed the panel) is deprecated and removed in v6; the events stay. Its values are described on the `SbOpenReason` and `SbCloseReason` types.
 
-**Slot props**: `isOpen`, `open()`, `close()`, `toggle()`, `placement` (resolved after flip), `side`, `align`, `floatingId` and `referenceId` (the `id` of the panel and of the reference, for ARIA attributes of your own).
+**Slot props**: `isOpen`, `open()`, `close()`, `toggle()`, `placement` (resolved after flip) and `floatingId` (the `id` of the panel, for ARIA attributes of your own). `side`, `align` and `referenceId` are deprecated: read the side and alignment from `placement`, and pass your own `id` to `SbReference`.
 
-**Exposed** (template ref): `isOpen`, `open()`, `close()`, `toggle()`, `update()` (recomputes the position).
+**Exposed** (template ref): `update()` (recomputes the position). `isOpen`, `open()`, `close()` and `toggle()` are deprecated: use `v-model:open`.
 
 ### `<SbReference>`
 
@@ -234,10 +219,10 @@ Every prop, slot prop, event and option type is exported (`SbContainerProps`, `S
 
 - <a id="tooltip-1"></a>**Tooltip.** With `role="tooltip"` the panel follows the WAI-ARIA [tooltip](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) pattern: the reference gets no `aria-expanded` nor `aria-controls`, and while open `aria-describedby` points to the panel (pass your own `aria-describedby` on `SbReference` to replace it). Focus stays on the reference and no focus guards are rendered. Use it with `trigger="hover"`, which meets WCAG [1.4.13](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus): it opens on keyboard focus too, the pointer can move onto the tooltip within `delay.close`, and Escape dismisses it.
 - **Dismissal.**
-  - Escape closes the open panel that has focus, else the most recently opened one. It is ignored when a widget inside has already handled it (`event.preventDefault()`) and while an IME composition is in progress.
+  - Escape closes the open panel that has focus, else the most recently opened one, skipping panels with `closeOnEscape` set to `false`. It is ignored when a widget inside has already handled it (`event.preventDefault()`) and while an IME composition is in progress.
   - A press outside closes the panel; on touch, only a tap does, so starting a scroll keeps it open.
   - Moving focus outside (e.g. tabbing past the last element) closes it.
-  - A container nested inside a panel counts as part of it.
+  - A container nested inside a panel counts as part of it. Anything else outside the reference and the panel does not: a datepicker, select or other popup of another library, teleported out of the panel, closes it when pressed or focused. Set `:close-on-click-outside="false"` and `:close-on-focus-out="false"` on that container and close it yourself.
 - **What is up to you.** The library does not implement the keyboard model of `tree` and `grid` panels, nor selection: a listbox option or a menu item does what its `click` handler does (e.g. set `aria-selected`); add `closeOnSelect` to close the panel after it. Use valid structure: items directly inside the `menu` / `listbox`, or inside `ul` / `li` with `role="none"`.
 - <a id="text-field-references"></a>**Text field references.** `<SbReference as="input">` (or `textarea`) stays a text field: no `role="button"`, Enter and Space type as usual, a click opens the panel without closing it, and focus stays in the field when the panel opens. The [combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) (autocomplete with focus kept in the field and `aria-activedescendant`) is not supported: with a `menu` or `listbox` panel the arrow keys move focus into the panel, and the console warns about it in development.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sb-floating-panel-vue",
-  "version": "5.2.1",
+  "version": "5.3.1",
   "description": "Headless Vue 3 floating panel components (dropdowns, popovers, menus) powered by @floating-ui/vue: positioning, accessibility and open state handled, zero CSS shipped.",
   "keywords": [
     "vue",