sb-floating-panel-vue 5.1.0 → 5.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -192
- package/dist/components/SbContainer.vue.d.ts +8 -8
- package/dist/components/SbFloating.vue.d.ts +0 -3
- package/dist/components/SbReference.vue.d.ts +0 -2
- package/dist/composables/useSbFloatingContext.d.ts +20 -2
- package/dist/composables/useSbFloatingPanel.d.ts +6 -16
- package/dist/index.d.ts +1 -1
- package/dist/sb-floating-panel.es.js +317 -296
- package/dist/sb-floating-panel.umd.js +1 -1
- package/dist/types.d.ts +55 -9
- package/dist/utils/dom.d.ts +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,11 +1,6 @@
|
|
|
1
1
|
# sb-floating-panel-vue
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/sb-floating-panel-vue)
|
|
4
|
-
[](https://github.com/stefanBid/sb-floating-panel-vue/blob/main/LICENSE)
|
|
5
|
-
[](https://vuejs.org)
|
|
6
|
-
[](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml)
|
|
7
|
-
[](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml)
|
|
8
|
-
[](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml)
|
|
3
|
+
[](https://www.npmjs.com/package/sb-floating-panel-vue) [](https://github.com/stefanBid/sb-floating-panel-vue/blob/main/LICENSE) [](https://vuejs.org) [](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml) [](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml) [](https://github.com/stefanBid/sb-floating-panel-vue/actions/workflows/ci.yml)
|
|
9
4
|
|
|
10
5
|
Headless Vue 3 components for floating panels (dropdowns, menus, listboxes, popovers, tooltips) built on [`@floating-ui/vue`](https://floating-ui.com/). You write three components; the library handles placement, flipping, viewport collisions, open state, keyboard and accessibility. It never decides how your panel looks: no stylesheet, only data attributes and CSS variables your styles can read.
|
|
11
6
|
|
|
@@ -22,14 +17,7 @@ Headless Vue 3 components for floating panels (dropdowns, menus, listboxes, popo
|
|
|
22
17
|
## 📦 Installation
|
|
23
18
|
|
|
24
19
|
```bash
|
|
25
|
-
# npm
|
|
26
20
|
npm install sb-floating-panel-vue vue @floating-ui/vue
|
|
27
|
-
|
|
28
|
-
# yarn
|
|
29
|
-
yarn add sb-floating-panel-vue vue @floating-ui/vue
|
|
30
|
-
|
|
31
|
-
# pnpm
|
|
32
|
-
pnpm add sb-floating-panel-vue vue @floating-ui/vue
|
|
33
21
|
```
|
|
34
22
|
|
|
35
23
|
`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.
|
|
@@ -101,45 +89,64 @@ Holds the state and the positioning. Renders no element of its own, only its slo
|
|
|
101
89
|
|
|
102
90
|
**Positioning**
|
|
103
91
|
|
|
104
|
-
| Prop
|
|
105
|
-
|
|
106
|
-
| `placement`
|
|
107
|
-
| `strategy`
|
|
108
|
-
| `offset`
|
|
109
|
-
| `padding`
|
|
110
|
-
| `matchWidth`
|
|
111
|
-
| `hideWhenDetached` | `boolean \| 'close'`
|
|
92
|
+
| Prop | Type | Default | Description |
|
|
93
|
+
| --- | --- | --- | --- |
|
|
94
|
+
| `placement` | `SbPlacement` | `'bottom-start'` | Preferred placement; the panel flips when there is not enough space |
|
|
95
|
+
| `strategy` | `'absolute' \| 'fixed'` | `'absolute'` | CSS position strategy. Use `fixed` inside scroll containers or fixed layouts |
|
|
96
|
+
| `offset` | `number` | `8` | Distance in px between reference and panel |
|
|
97
|
+
| `padding` | `number` | `8` | Minimum distance in px between the panel and the viewport edges |
|
|
98
|
+
| `matchWidth` | `boolean \| 'min'` | `false` | `true` sets `width`, `'min'` sets `min-width` to the reference width |
|
|
99
|
+
| `hideWhenDetached` | `boolean \| 'close'` | `false` | When the reference is scrolled out of view: `true` hides the panel (`visibility: hidden`) until it is back, `'close'` closes it |
|
|
112
100
|
|
|
113
101
|
**Open state**
|
|
114
102
|
|
|
115
|
-
| Prop
|
|
116
|
-
|
|
117
|
-
| `v-model:open` | `boolean` | —
|
|
118
|
-
| `defaultOpen`
|
|
119
|
-
| `disabled`
|
|
120
|
-
| `trigger`
|
|
121
|
-
| `delay`
|
|
122
|
-
|
|
123
|
-
| `trigger`
|
|
124
|
-
|
|
125
|
-
| `'click'`
|
|
126
|
-
| `'hover'`
|
|
127
|
-
| `'focus'`
|
|
128
|
-
| `'manual'` | Only `v-model:open`, the slot props or the exposed methods | Same, or any dismissal below
|
|
103
|
+
| Prop | Type | Default | Description |
|
|
104
|
+
| --- | --- | --- | --- |
|
|
105
|
+
| `v-model:open` | `boolean` | — | Open state. Leave it unset to let the container manage it |
|
|
106
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when `v-model:open` is not used |
|
|
107
|
+
| `disabled` | `boolean` | `false` | Prevents opening; closes the panel if it is open |
|
|
108
|
+
| `trigger` | `SbTrigger` | `'click'` | How the reference opens the panel, see below |
|
|
109
|
+
| `delay` | `number \| { open?: number; close?: number }` | `{ open: 300, close: 150 }` | Milliseconds before the `hover` trigger opens and closes; a number sets both |
|
|
110
|
+
|
|
111
|
+
| `trigger` | Opens | Closes |
|
|
112
|
+
| --- | --- | --- |
|
|
113
|
+
| `'click'` | Click (Enter/Space) on the reference toggles the panel | Same, or any dismissal below |
|
|
114
|
+
| `'hover'` | Pointer over the reference after `delay.open`; keyboard focus at once (touch has no hover) | `delay.close` after the pointer leaves the reference and the panel, or when focus moves elsewhere |
|
|
115
|
+
| `'focus'` | Focus on the reference | Focus moving elsewhere |
|
|
116
|
+
| `'manual'` | Only `v-model:open`, the slot props or the exposed methods | Same, or any dismissal below |
|
|
129
117
|
|
|
130
118
|
**Dismissal**
|
|
131
119
|
|
|
132
|
-
| Prop
|
|
133
|
-
|
|
134
|
-
| `closeOnEscape`
|
|
135
|
-
| `closeOnClickOutside` | `boolean` | `true`
|
|
136
|
-
| `closeOnFocusOut`
|
|
120
|
+
| Prop | Type | Default | Description |
|
|
121
|
+
| --- | --- | --- | --- |
|
|
122
|
+
| `closeOnEscape` | `boolean` | `true` | Closes on Escape |
|
|
123
|
+
| `closeOnClickOutside` | `boolean` | `true` | Closes on a pointer press outside the reference and the panel (on touch, on the tap's click) |
|
|
124
|
+
| `closeOnFocusOut` | `boolean` | `true` | Closes when keyboard focus moves outside the reference and the panel |
|
|
125
|
+
|
|
126
|
+
| Event | Payload | Description |
|
|
127
|
+
| ------------- | --------------- | ----------------------------- |
|
|
128
|
+
| `update:open` | `boolean` | Used by `v-model:open` |
|
|
129
|
+
| `open` | `SbOpenReason` | The panel has opened, and why |
|
|
130
|
+
| `close` | `SbCloseReason` | The panel has closed, and why |
|
|
131
|
+
|
|
132
|
+
The reason tells what opened or closed the panel, e.g. for analytics or to react only to a dismissal:
|
|
133
|
+
|
|
134
|
+
| Reason | `open` | `close` |
|
|
135
|
+
| --- | --- | --- |
|
|
136
|
+
| `trigger` | Click on the reference, Enter, Space or an arrow key on it | Click on the reference, Enter or Space on it |
|
|
137
|
+
| `hover` | Pointer over the reference (`hover` trigger) | Pointer left the reference and the panel (`hover` trigger) |
|
|
138
|
+
| `focus` | Focus on the reference (`hover` and `focus` triggers) | — |
|
|
139
|
+
| `focus-out` | — | Focus moved outside, e.g. Tab out of a menu |
|
|
140
|
+
| `escape` | — | Escape, or the arrow key that closes a submenu |
|
|
141
|
+
| `outside` | — | Press outside the reference and the panel |
|
|
142
|
+
| `select` | — | Item activated with `closeOnSelect` |
|
|
143
|
+
| `detached` | — | Reference scrolled out of view, with `hideWhenDetached: 'close'` |
|
|
144
|
+
| `disabled` | — | The container was disabled |
|
|
145
|
+
| `api` | `v-model:open`, slot props, exposed methods, `useSbFloating()` | Same, or the reference unmounting |
|
|
137
146
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
| `open` | — | The panel has opened |
|
|
142
|
-
| `close` | — | The panel has closed |
|
|
147
|
+
```vue
|
|
148
|
+
<SbContainer @close="(reason) => reason === 'select' && track('menu-pick')">
|
|
149
|
+
```
|
|
143
150
|
|
|
144
151
|
**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).
|
|
145
152
|
|
|
@@ -149,10 +156,10 @@ Holds the state and the positioning. Renders no element of its own, only its slo
|
|
|
149
156
|
|
|
150
157
|
The trigger the panel is anchored to.
|
|
151
158
|
|
|
152
|
-
| Prop
|
|
153
|
-
|
|
154
|
-
| `as`
|
|
155
|
-
| `id`
|
|
159
|
+
| Prop | Type | Default | Description |
|
|
160
|
+
| --- | --- | --- | --- |
|
|
161
|
+
| `as` | `string \| Component` | `'button'` | Tag or component to render. `button` gets `type="button"`; form controls (`input`, `textarea`, `select`), `a` with `href` and components keep their own semantics; any other tag (also `a` without `href`) gets `role="button"`, `tabindex="0"` and Enter/Space. A text field opens the panel on click without closing it, and keeps focus (see [Text field references](#text-field-references)) |
|
|
162
|
+
| `id` | `string` | generated | `id` of the element, used to name the panel |
|
|
156
163
|
| `ariaHaspopup` | `'dialog' \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'true' \| 'false'` | follows `role` | Value of `aria-haspopup`. When unset it follows the `role` of the panel (`alertdialog` gives `dialog`) and is left out for other roles |
|
|
157
164
|
|
|
158
165
|
Sets `aria-expanded`, `aria-controls` (while open) and `data-sbf-state`; a tooltip reference gets `aria-describedby` instead (see [Tooltip](#tooltip-1)). When the container is `disabled`, a `button` gets `disabled`, anything else gets `aria-disabled="true"` (and non-interactive tags `tabindex="-1"`). Your own `class`, attributes and listeners (`@click`, `@mouseenter`, …) are applied to the element; the click is not stopped.
|
|
@@ -163,21 +170,21 @@ With a component (e.g. the `Button` of your design system), its root element bec
|
|
|
163
170
|
|
|
164
171
|
The panel, teleported to `body`. It is rendered while open and stays mounted until its leave transition has finished.
|
|
165
172
|
|
|
166
|
-
| Prop
|
|
167
|
-
|
|
168
|
-
| `as`
|
|
169
|
-
| `role`
|
|
170
|
-
| `transition`
|
|
171
|
-
| `teleport`
|
|
172
|
-
| `zIndex`
|
|
173
|
-
| `autoFocus`
|
|
174
|
-
| `keyboardNavigation` | `boolean`
|
|
175
|
-
| `closeOnSelect`
|
|
176
|
-
|
|
177
|
-
| Event | Description
|
|
178
|
-
|
|
179
|
-
| `after-enter` | The enter transition has finished
|
|
180
|
-
| `after-leave` | The leave transition has finished and the panel is removed
|
|
173
|
+
| Prop | Type | Default | Description |
|
|
174
|
+
| --- | --- | --- | --- |
|
|
175
|
+
| `as` | `string \| Component` | `'div'` | Tag or component of the panel element; a component must render a single root element |
|
|
176
|
+
| `role` | `SbFloatingRole \| null` | `'dialog'` | ARIA role of the panel; `null` renders no role (disclosure pattern). Known roles are suggested by your editor, any string is accepted |
|
|
177
|
+
| `transition` | `string \| TransitionProps` | — | Name of a Vue `<Transition>` defined in your CSS, or an object of `<Transition>` props (e.g. Tailwind classes). No animation when unset |
|
|
178
|
+
| `teleport` | `string \| HTMLElement \| false` | `'body'` | Teleport target (selector or element); `false` renders the panel in place |
|
|
179
|
+
| `zIndex` | `number \| string` | — | `z-index` of the positioned wrapper. Use this, not a `z-*` class on the panel (see [Stacking](#stacking)) |
|
|
180
|
+
| `autoFocus` | `boolean` | `true`, `false` with `role="tooltip"`, the `hover` / `focus` trigger or a text field reference | Once positioned, focuses the first `[autofocus]` or focusable element inside, else the panel itself (a menu: its first item; a listbox: its selected option) |
|
|
181
|
+
| `keyboardNavigation` | `boolean` | `true` | Handles the keyboard model of `role="menu"` and `role="listbox"` panels (see [Keyboard](#keyboard)). No effect with other roles |
|
|
182
|
+
| `closeOnSelect` | `boolean` | `false` | With `role="menu"` / `"listbox"`, activating a `menuitem` / `option` closes the panel (a submenu: with its parent menus) and gives focus back to the reference, after the item's `click` handler. Not for `menuitemcheckbox` / `menuitemradio`, submenu triggers, disabled items or a listbox with `aria-multiselectable="true"`; `event.preventDefault()` in the handler keeps it open |
|
|
183
|
+
|
|
184
|
+
| Event | Description |
|
|
185
|
+
| ------------- | ---------------------------------------------------------- |
|
|
186
|
+
| `after-enter` | The enter transition has finished |
|
|
187
|
+
| `after-leave` | The leave transition has finished and the panel is removed |
|
|
181
188
|
|
|
182
189
|
With a popup role (`dialog`, `alertdialog`, `menu`, `listbox`, `tree`, `grid`), the panel is named after the reference with `aria-labelledby`, unless you pass `aria-label` or `aria-labelledby` yourself. When focus is inside the panel as it closes, it goes back to the reference.
|
|
183
190
|
|
|
@@ -192,7 +199,7 @@ const { isOpen, open, close, toggle } = useSbFloating();
|
|
|
192
199
|
```
|
|
193
200
|
|
|
194
201
|
| Returns | Type | Description |
|
|
195
|
-
|
|
202
|
+
| -------- | ------------------------ | ------------------------- |
|
|
196
203
|
| `isOpen` | `Readonly<Ref<boolean>>` | Whether the panel is open |
|
|
197
204
|
| `open` | `() => void` | Opens the panel |
|
|
198
205
|
| `close` | `() => void` | Closes the panel |
|
|
@@ -202,22 +209,7 @@ Call it in `setup` of a component rendered inside an `SbContainer` (in the refer
|
|
|
202
209
|
|
|
203
210
|
### Types
|
|
204
211
|
|
|
205
|
-
|
|
206
|
-
import type {
|
|
207
|
-
SbContainerProps,
|
|
208
|
-
SbContainerSlotProps,
|
|
209
|
-
SbContainerExposed,
|
|
210
|
-
SbReferenceProps,
|
|
211
|
-
SbFloatingProps,
|
|
212
|
-
SbTrigger,
|
|
213
|
-
SbPlacement,
|
|
214
|
-
SbSide,
|
|
215
|
-
SbAlignment,
|
|
216
|
-
SbStrategy,
|
|
217
|
-
SbFloatingRole,
|
|
218
|
-
UseSbFloatingReturn,
|
|
219
|
-
} from 'sb-floating-panel-vue';
|
|
220
|
-
```
|
|
212
|
+
Every prop, slot prop, event and option type is exported (`SbContainerProps`, `SbPlacement`, `SbFloatingRole`, …): import them with `import type { … } from 'sb-floating-panel-vue'`.
|
|
221
213
|
|
|
222
214
|
---
|
|
223
215
|
|
|
@@ -225,12 +217,12 @@ import type {
|
|
|
225
217
|
|
|
226
218
|
- `SbReference` gets an `id`, `aria-expanded`, `aria-controls` (pointing to the panel `id`) and `aria-haspopup` (following the panel `role`); non-interactive tags get `role="button"`, `tabindex="0"` and Enter/Space.
|
|
227
219
|
- `SbFloating` gets an `id` generated with Vue `useId()` (SSR safe), a `role` (`dialog` by default) and, with a popup role (`dialog`, `alertdialog`, `menu`, `listbox`, `tree`, `grid`), `aria-labelledby` pointing to the reference.
|
|
228
|
-
- **Tab order.** The panel is teleported to the end of `body`, so the library keeps the order a reader expects: Tab on the open reference enters the panel, Shift+Tab from its first element returns to the reference, Tab from its last element moves on to what follows the reference. Two hidden focus guards (`data-sbf-focus-guard`) around the panel do this; they are not rendered with `:teleport="false"` nor around a tooltip.
|
|
229
|
-
- **Focus.** By default (`autoFocus`) focus moves inside the panel once it is positioned. When the panel closes with focus inside it, focus returns to the reference without scrolling the page.
|
|
220
|
+
- **Tab order.** The panel is teleported to the end of `body`, so the library keeps the order a reader expects: Tab on the open reference enters the panel, Shift+Tab from its first element returns to the reference, Tab from its last element moves on to what follows the reference, and Shift+Tab from there enters the panel again from its last element while it is still open (with `closeOnFocusOut: false`). Two hidden focus guards (`data-sbf-focus-guard`) around the panel do this; they are not rendered with `:teleport="false"` nor around a tooltip.
|
|
221
|
+
- **Focus.** By default (`autoFocus`) focus moves inside the panel once it is positioned. When the panel closes with focus inside it, focus returns to the reference without scrolling the page. When it unmounts open with focus inside, focus is not left on the body: it goes back to the reference when only `SbFloating` is removed, and to what follows the reference in the page when the reference is removed too.
|
|
230
222
|
- <a id="keyboard"></a>**Keyboard.** With `role="menu"` or `role="listbox"` the components follow the WAI-ARIA [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and [listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) patterns. Items are the elements with role `menuitem`, `menuitemcheckbox`, `menuitemradio` (menu) or `option` (listbox); they must be focusable (a `button`, or `tabindex="-1"`). Turn it off with `:keyboard-navigation="false"`.
|
|
231
223
|
|
|
232
224
|
| Key | On the reference | In the panel |
|
|
233
|
-
|
|
225
|
+
| --- | --- | --- |
|
|
234
226
|
| ArrowDown / ArrowUp | Opens on the first / last item (or the selected option), except with the `manual` trigger | Next / previous item; a menu wraps around, a listbox stops at its ends |
|
|
235
227
|
| Home / End | — | First / last item |
|
|
236
228
|
| Letters | — | Next item whose text starts with the typed letters |
|
|
@@ -239,6 +231,7 @@ import type {
|
|
|
239
231
|
| ArrowRight / ArrowLeft | A submenu trigger: ArrowRight opens the submenu on its first item | A submenu: ArrowLeft closes it and focuses its trigger |
|
|
240
232
|
|
|
241
233
|
A submenu is a menu `SbContainer` inside a menu panel; its arrows are mirrored in right-to-left text. Keys whose `keydown` you already handled with `event.preventDefault()`, and keys typed in text fields, are left alone.
|
|
234
|
+
|
|
242
235
|
- <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.
|
|
243
236
|
- **Dismissal.**
|
|
244
237
|
- 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.
|
|
@@ -258,7 +251,13 @@ The library writes values on the elements; your CSS reads them. `SbFloating` ren
|
|
|
258
251
|
<!-- wrapper: positioning only (Floating UI styles, z-index, CSS variables) -->
|
|
259
252
|
<div style="position: absolute; transform: translate(120px, 40px); --sbf-reference-width: 180px; …">
|
|
260
253
|
<!-- panel: your class, style and attributes -->
|
|
261
|
-
<div
|
|
254
|
+
<div
|
|
255
|
+
class="my-panel"
|
|
256
|
+
role="dialog"
|
|
257
|
+
data-sbf-state="open"
|
|
258
|
+
data-sbf-side="bottom"
|
|
259
|
+
data-sbf-align="start"
|
|
260
|
+
>
|
|
262
261
|
…
|
|
263
262
|
</div>
|
|
264
263
|
</div>
|
|
@@ -268,22 +267,22 @@ Your styles, transitions and transforms go on the panel, so they never fight wit
|
|
|
268
267
|
|
|
269
268
|
### Data attributes
|
|
270
269
|
|
|
271
|
-
| Attribute
|
|
272
|
-
|
|
273
|
-
| `data-sbf-state` | `open` / `closed`
|
|
274
|
-
| `data-sbf-state` | `open` / `closed`
|
|
275
|
-
| `data-sbf-side`
|
|
276
|
-
| `data-sbf-align` | `start` / `end` / absent
|
|
270
|
+
| Attribute | Values | On | Use |
|
|
271
|
+
| --- | --- | --- | --- |
|
|
272
|
+
| `data-sbf-state` | `open` / `closed` | reference | Open/closed styles (e.g. rotate an icon) |
|
|
273
|
+
| `data-sbf-state` | `open` / `closed` | panel | `closed` from the start of the leave transition: style or animate the exit |
|
|
274
|
+
| `data-sbf-side` | `top` / `bottom` / `left` / `right` | panel | Real side after flip: directional animation |
|
|
275
|
+
| `data-sbf-align` | `start` / `end` / absent | panel | Alignment part of the placement |
|
|
277
276
|
|
|
278
277
|
### CSS variables
|
|
279
278
|
|
|
280
279
|
Set on the wrapper and inherited by the panel:
|
|
281
280
|
|
|
282
|
-
| Variable
|
|
283
|
-
|
|
284
|
-
| `--sbf-reference-width`
|
|
285
|
-
| `--sbf-available-width`
|
|
286
|
-
| `--sbf-available-height` | Vertical space left before overflowing the viewport
|
|
281
|
+
| Variable | Meaning |
|
|
282
|
+
| --- | --- |
|
|
283
|
+
| `--sbf-reference-width` | Width of the reference |
|
|
284
|
+
| `--sbf-available-width` | Horizontal space left before overflowing the viewport |
|
|
285
|
+
| `--sbf-available-height` | Vertical space left before overflowing the viewport |
|
|
287
286
|
| `--sbf-transform-origin` | Corner or edge of the panel facing the reference, for `transform-origin` |
|
|
288
287
|
|
|
289
288
|
All attributes and variables use the `sbf` prefix, so they do not clash with other libraries in the same app (e.g. Radix / Reka UI `data-state`).
|
|
@@ -313,7 +312,9 @@ Panels are teleported to `body`, so their styles cannot be `scoped` to the compo
|
|
|
313
312
|
.pop-enter-active,
|
|
314
313
|
.pop-leave-active {
|
|
315
314
|
transform-origin: var(--sbf-transform-origin);
|
|
316
|
-
transition:
|
|
315
|
+
transition:
|
|
316
|
+
opacity 150ms ease,
|
|
317
|
+
transform 150ms ease;
|
|
317
318
|
}
|
|
318
319
|
.pop-enter-from,
|
|
319
320
|
.pop-leave-to {
|
|
@@ -322,8 +323,12 @@ Panels are teleported to `body`, so their styles cannot be `scoped` to the compo
|
|
|
322
323
|
}
|
|
323
324
|
|
|
324
325
|
/* direction from the side resolved after flip */
|
|
325
|
-
.pop-enter-from[data-sbf-side='bottom'] {
|
|
326
|
-
|
|
326
|
+
.pop-enter-from[data-sbf-side='bottom'] {
|
|
327
|
+
transform: translateY(-6px);
|
|
328
|
+
}
|
|
329
|
+
.pop-enter-from[data-sbf-side='top'] {
|
|
330
|
+
transform: translateY(6px);
|
|
331
|
+
}
|
|
327
332
|
|
|
328
333
|
/* respect the user's motion setting */
|
|
329
334
|
@media (prefers-reduced-motion: reduce) {
|
|
@@ -363,20 +368,7 @@ Panels are teleported to `body`, so their styles cannot be `scoped` to the compo
|
|
|
363
368
|
|
|
364
369
|
## 🧭 How It Works
|
|
365
370
|
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
`SbContainer` owns the state (open state, positioning, ARIA ids) and shares it with its descendants through Vue `provide`/`inject`:
|
|
369
|
-
|
|
370
|
-
```
|
|
371
|
-
SbContainer ── provides the state ──┬─▶ SbReference
|
|
372
|
-
└─▶ SbFloating
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
- `SbReference` and `SbFloating` find their container on their own: you pass no refs, styles or handlers, and never write `.value`.
|
|
376
|
-
- The lookup follows the component tree, not the DOM, so it keeps working although `SbFloating` is teleported to `body`.
|
|
377
|
-
- They can sit at any depth inside the container slot, also inside your own components, which can read the same state with [`useSbFloating()`](#usesbfloating).
|
|
378
|
-
- Used outside an `SbContainer`, they throw: `[sb-floating-panel-vue] <SbFloating> must be used inside <SbContainer>.`
|
|
379
|
-
- In development, the console warns about a second `SbReference` or `SbFloating` in the same container, about an `as` component that renders no single root element, about a text field reference of a `menu` or `listbox` panel, about a `tooltip` opened by click, and, the first time the arrow keys look for them, about a `menu` or `listbox` with no items or with items that cannot take focus. The warnings depend on `process.env.NODE_ENV`, which your bundler replaces: they are left out of production builds.
|
|
371
|
+
`SbContainer` owns the state (open state, positioning, ARIA ids) and shares it with `SbReference` and `SbFloating` through `provide`/`inject`. The lookup follows the component tree, not the DOM, so it keeps working although `SbFloating` is teleported to `body`; used outside an `SbContainer`, they throw.
|
|
380
372
|
|
|
381
373
|
### Nested containers
|
|
382
374
|
|
|
@@ -386,92 +378,19 @@ An `SbContainer` placed inside another one (e.g. a submenu in a menu panel) regi
|
|
|
386
378
|
- Escape closes the innermost open panel first, then the next one;
|
|
387
379
|
- a press outside all of them closes them all.
|
|
388
380
|
|
|
389
|
-
###
|
|
381
|
+
### Development warnings
|
|
390
382
|
|
|
391
|
-
|
|
392
|
-
2. **Open state changes.** `SbReference` gets `aria-expanded="true"`, `aria-controls` and `data-sbf-state="open"`; the container starts listening for Escape, outside presses and focus moving outside (only while open) and emits `open`.
|
|
393
|
-
3. **The panel mounts.** `SbFloating` renders the wrapper in the teleport target, with the panel and two hidden focus guards inside it; the enter classes of your `transition`, if any, are applied to the panel.
|
|
394
|
-
4. **Positioning.** Floating UI starts tracking the reference (scroll, resize, layout changes) and computes the position with `offset`, `flip`, `shift`, `size` and, with `hideWhenDetached`, `hide`. `size` writes the `--sbf-*` variables and applies `matchWidth`; the position is written on the wrapper.
|
|
395
|
-
5. **Positioned.** With `autoFocus` (the default), focus moves inside the panel now, not earlier, so the page does not jump to the panel's initial (0, 0) position.
|
|
383
|
+
In development, the console warns about a second `SbReference` or `SbFloating` in the same container, about an `as` component that renders no single root element, about a text field reference of a `menu` or `listbox` panel, about a `tooltip` opened by click, and, the first time the arrow keys look for them, about a `menu` or `listbox` with no items or with items that cannot take focus. The warnings depend on `process.env.NODE_ENV`, which your bundler replaces: they are left out of production builds.
|
|
396
384
|
|
|
397
|
-
|
|
385
|
+
### Directives on `SbFloating`
|
|
398
386
|
|
|
399
|
-
|
|
400
|
-
2. The panel gets `data-sbf-state="closed"` and the leave classes of your `transition`; the wrapper stays mounted and positioned until the animation ends (immediately without `transition`).
|
|
401
|
-
3. The wrapper is removed, Floating UI stops tracking, `SbFloating` emits `after-leave`.
|
|
387
|
+
`<SbFloating>` renders a `<teleport>` root, so a custom directive applied to the component is not inherited and Vue warns about it: put the directive on an element inside the slot.
|
|
402
388
|
|
|
403
389
|
---
|
|
404
390
|
|
|
405
|
-
## 🔀 Migrating
|
|
406
|
-
|
|
407
|
-
v5 is a breaking release.
|
|
408
|
-
|
|
409
|
-
- **`teleportTo` and `teleportDisabled` are replaced by `teleport`**: `teleport-to="#overlays"` becomes `teleport="#overlays"`, `teleport-disabled` becomes `:teleport="false"`.
|
|
410
|
-
- **Menus and listboxes handle the keyboard.** Remove your own arrow-key, Home/End and typeahead handlers on `role="menu"` and `role="listbox"` panels, or keep them and call `event.preventDefault()` on the keys they handle (the library then leaves those keys alone), or set `:keyboard-navigation="false"`. Tab now closes a menu.
|
|
411
|
-
- **Tooltips.** With `role="tooltip"` the reference no longer gets `aria-expanded` nor `aria-controls`, and gets `aria-describedby` pointing to the panel while open; `autoFocus` defaults to `false`. Replace a `trigger="manual"` tooltip opened with your own `@mouseenter` / `@focus` handlers by `trigger="hover"`.
|
|
412
|
-
- **`SbTrigger` also takes `'hover'` and `'focus'`**: a `switch` over it in your code may need the new cases.
|
|
413
|
-
- **The panel closes when its reference unmounts** while open.
|
|
414
|
-
- **Escape closes the open panel that has focus**, else the most recently opened one (it was always the most recently opened one).
|
|
415
|
-
|
|
416
|
-
## 🔀 Migrating from v3
|
|
417
|
-
|
|
418
|
-
v4 changed these defaults:
|
|
419
|
-
|
|
420
|
-
- **`autoFocus` is `true`.** Focus moves inside the panel when it opens. Set `:auto-focus="false"` on panels that must not take focus, such as tooltips.
|
|
421
|
-
- **`ariaHaspopup` follows the panel `role`** instead of defaulting to `dialog`: drop the matching `aria-haspopup` you set by hand, keep it only where it differs from the role.
|
|
422
|
-
- **Focus moving outside closes the panel.** Set `:close-on-focus-out="false"` to keep the previous behaviour.
|
|
423
|
-
- **The panel is named after the reference** with `aria-labelledby`; pass `aria-label` or `aria-labelledby` to name it differently.
|
|
424
|
-
- **Escape** no longer closes the panel when a widget inside called `preventDefault()` on it, and it now calls `preventDefault()` itself.
|
|
425
|
-
- **`data-sbf-state` on the panel** becomes `closed` during the leave transition.
|
|
391
|
+
## 🔀 Migrating
|
|
426
392
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
## 🔀 Migrating from v2
|
|
430
|
-
|
|
431
|
-
v3 is a breaking release.
|
|
432
|
-
|
|
433
|
-
- **The composable is no longer exported.** Use the components; for full control use `@floating-ui/vue` directly.
|
|
434
|
-
- **No refs or styles in the slot.** Remove `reference-ref`, `floating-ref`, `is-open`, `floating-placement`, `floating-style` and `:on-click`: the components share their state.
|
|
435
|
-
- **No arrow.** `hasArrow`, `floating-arrow-ref`, `floating-arrow-style` and `arrow-dimensions` are gone.
|
|
436
|
-
- **No CSS.** Remove `import 'sb-floating-panel-vue/style.css'`. `animation` and `duration` are replaced by `transition`, the name of your own `<Transition>` classes.
|
|
437
|
-
- **Renamed props:** `offsetValue` → `offset` (default `15` → `8`), `hasResize` → `matchWidth`.
|
|
438
|
-
- **New defaults:** `padding: 8` from the viewport edges; Escape and click outside close the panel.
|
|
439
|
-
- `SbContainer` no longer renders a `<div>`; `SbReference` no longer stops click propagation and sets `type="button"`.
|
|
440
|
-
|
|
441
|
-
```vue
|
|
442
|
-
<!-- v2 -->
|
|
443
|
-
<SbContainer :has-resize="true">
|
|
444
|
-
<template #default="{ reference, floating, floatingPlacement, floatingStyle, isOpen, toggle }">
|
|
445
|
-
<SbReference :reference-ref="reference" :on-click="toggle">Toggle</SbReference>
|
|
446
|
-
<SbFloating
|
|
447
|
-
:is-open="isOpen.value"
|
|
448
|
-
:floating-ref="floating"
|
|
449
|
-
:floating-placement="floatingPlacement.value"
|
|
450
|
-
:floating-style="floatingStyle.value"
|
|
451
|
-
>
|
|
452
|
-
Hello Panel!
|
|
453
|
-
</SbFloating>
|
|
454
|
-
</template>
|
|
455
|
-
</SbContainer>
|
|
456
|
-
|
|
457
|
-
<!-- v3 -->
|
|
458
|
-
<SbContainer match-width>
|
|
459
|
-
<SbReference>Toggle</SbReference>
|
|
460
|
-
<SbFloating>Hello Panel!</SbFloating>
|
|
461
|
-
</SbContainer>
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
---
|
|
465
|
-
|
|
466
|
-
## ⚠️ Directive Note (Teleport Limitation)
|
|
467
|
-
|
|
468
|
-
`<SbFloating>` renders a `<teleport>` root, so a custom directive applied directly to the component cannot be inherited and Vue warns about it. Move the directive to an element inside the slot:
|
|
469
|
-
|
|
470
|
-
```vue
|
|
471
|
-
<SbFloating>
|
|
472
|
-
<div v-my-directive>...</div>
|
|
473
|
-
</SbFloating>
|
|
474
|
-
```
|
|
393
|
+
Breaking changes between major versions and how to update: [MIGRATING.md](MIGRATING.md).
|
|
475
394
|
|
|
476
395
|
---
|
|
477
396
|
|
|
@@ -1,28 +1,28 @@
|
|
|
1
|
-
import { SbContainerExposed, SbContainerProps, SbContainerSlotProps } from '../types';
|
|
1
|
+
import { SbCloseReason, SbContainerExposed, SbContainerProps, SbContainerSlotProps, SbOpenReason } from '../types';
|
|
2
2
|
declare const _default: typeof __VLS_export;
|
|
3
3
|
export default _default;
|
|
4
4
|
declare const __VLS_export: __VLS_WithSlots<import('vue').DefineComponent<Omit<SbContainerProps, "open"> & {
|
|
5
5
|
open?: boolean | undefined;
|
|
6
6
|
}, SbContainerExposed, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
|
|
7
|
-
close: () => any;
|
|
8
|
-
open: () => any;
|
|
7
|
+
close: (reason: SbCloseReason) => any;
|
|
8
|
+
open: (reason: SbOpenReason) => any;
|
|
9
9
|
"update:open": (value: boolean | undefined) => any;
|
|
10
10
|
}, string, import('vue').PublicProps, Readonly<Omit<SbContainerProps, "open"> & {
|
|
11
11
|
open?: boolean | undefined;
|
|
12
12
|
}> & Readonly<{
|
|
13
|
-
onClose?: (() => any) | undefined;
|
|
14
|
-
onOpen?: (() => any) | undefined;
|
|
13
|
+
onClose?: ((reason: SbCloseReason) => any) | undefined;
|
|
14
|
+
onOpen?: ((reason: SbOpenReason) => any) | undefined;
|
|
15
15
|
"onUpdate:open"?: ((value: boolean | undefined) => any) | undefined;
|
|
16
16
|
}>, {
|
|
17
|
+
trigger: import('..').SbTrigger;
|
|
18
|
+
disabled: boolean;
|
|
17
19
|
placement: import('..').SbPlacement;
|
|
18
20
|
strategy: import('..').SbStrategy;
|
|
19
|
-
padding: number;
|
|
20
21
|
offset: number;
|
|
22
|
+
padding: number;
|
|
21
23
|
matchWidth: boolean | "min";
|
|
22
24
|
hideWhenDetached: boolean | "close";
|
|
23
25
|
defaultOpen: boolean;
|
|
24
|
-
disabled: boolean;
|
|
25
|
-
trigger: import('..').SbTrigger;
|
|
26
26
|
delay: number | {
|
|
27
27
|
open?: number;
|
|
28
28
|
close?: number;
|
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import { TransitionProps } from 'vue';
|
|
2
1
|
import { SbFloatingProps } from '../types';
|
|
3
2
|
declare var __VLS_26: {};
|
|
4
3
|
type __VLS_Slots = {} & {
|
|
@@ -13,9 +12,7 @@ declare const __VLS_base: import('vue').DefineComponent<SbFloatingProps, {}, {},
|
|
|
13
12
|
}>, {
|
|
14
13
|
as: string | import('vue').Component;
|
|
15
14
|
role: import('..').SbFloatingRole | null;
|
|
16
|
-
transition: string | TransitionProps;
|
|
17
15
|
teleport: string | false | HTMLElement;
|
|
18
|
-
zIndex: string | number;
|
|
19
16
|
autoFocus: boolean;
|
|
20
17
|
keyboardNavigation: boolean;
|
|
21
18
|
closeOnSelect: boolean;
|
|
@@ -5,8 +5,6 @@ type __VLS_Slots = {} & {
|
|
|
5
5
|
};
|
|
6
6
|
declare const __VLS_base: import('vue').DefineComponent<SbReferenceProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<SbReferenceProps> & Readonly<{}>, {
|
|
7
7
|
as: string | import('vue').Component;
|
|
8
|
-
id: string;
|
|
9
|
-
ariaHaspopup: "dialog" | "menu" | "listbox" | "tree" | "grid" | "true" | "false";
|
|
10
8
|
}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
|
|
11
9
|
declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
|
|
12
10
|
declare const _default: typeof __VLS_export;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { InjectionKey, Ref } from 'vue';
|
|
2
|
-
import { SbTrigger } from '../types';
|
|
2
|
+
import { SbCloseReason, SbOpenReason, SbTrigger } from '../types';
|
|
3
3
|
import { NavigableRole } from '../utils/navigation';
|
|
4
4
|
import { FloatingPanel } from './useSbFloatingPanel';
|
|
5
5
|
/**
|
|
@@ -20,7 +20,10 @@ export interface SbFloatingContext extends FloatingPanel {
|
|
|
20
20
|
focusRequest: Ref<'first' | 'last' | null>;
|
|
21
21
|
/** Container of the panel this one is nested in (e.g. the menu of a submenu). */
|
|
22
22
|
parent: SbFloatingContext | null;
|
|
23
|
-
/**
|
|
23
|
+
/**
|
|
24
|
+
* Set before closing when focus must not go back to the reference: an outside press on a
|
|
25
|
+
* focusable element keeps it, a menu closing with the menus it opened from moves it.
|
|
26
|
+
*/
|
|
24
27
|
skipFocusReturn: boolean;
|
|
25
28
|
/** Mounted `SbReference` and `SbFloating` components, to warn about extra ones. */
|
|
26
29
|
parts: {
|
|
@@ -29,9 +32,16 @@ export interface SbFloatingContext extends FloatingPanel {
|
|
|
29
32
|
};
|
|
30
33
|
/** Set while the container unmounts, when its parts must not change the open state. */
|
|
31
34
|
isUnmounting: boolean;
|
|
35
|
+
/** Public actions: their reason is `api`. */
|
|
32
36
|
open: () => void;
|
|
33
37
|
close: () => void;
|
|
34
38
|
toggle: () => void;
|
|
39
|
+
/** Opens or closes the panel from an interaction of the components, with its reason. */
|
|
40
|
+
setOpen: {
|
|
41
|
+
(value: true, reason: SbOpenReason): void;
|
|
42
|
+
(value: false, reason: SbCloseReason): void;
|
|
43
|
+
(value: boolean, reason: SbOpenReason & SbCloseReason): void;
|
|
44
|
+
};
|
|
35
45
|
/** Pointer entering or leaving the reference or the panel, for the `hover` trigger. */
|
|
36
46
|
hover: (event: PointerEvent) => void;
|
|
37
47
|
/** Whether an event target is inside the reference, the panel or a nested container. */
|
|
@@ -39,6 +49,14 @@ export interface SbFloatingContext extends FloatingPanel {
|
|
|
39
49
|
/** Registers a nested container; returns the function that unregisters it. */
|
|
40
50
|
registerChild: (child: SbFloatingContext) => () => void;
|
|
41
51
|
}
|
|
52
|
+
/** Whether the container is nested in a menu (a submenu): its reference is an item of it. */
|
|
53
|
+
export declare const inMenu: (context: SbFloatingContext) => boolean;
|
|
54
|
+
/**
|
|
55
|
+
* Moves focus out of the panel (or a panel nested in it) about to unmount, which would leave it on
|
|
56
|
+
* the body: to the reference, or to what follows the reference in the page when that goes too.
|
|
57
|
+
* Returns whether focus was in the panel.
|
|
58
|
+
*/
|
|
59
|
+
export declare function moveFocusOut(context: SbFloatingContext, toReference: boolean): boolean;
|
|
42
60
|
export declare const sbFloatingContextKey: InjectionKey<SbFloatingContext>;
|
|
43
61
|
/** Counts a mounted part of the container, warning about a second one; returns the release. */
|
|
44
62
|
export declare function claimPart(context: SbFloatingContext, part: 'reference' | 'floating', component: string): () => void;
|
|
@@ -1,18 +1,7 @@
|
|
|
1
|
-
import { ComputedRef, CSSProperties,
|
|
2
|
-
import { SbAlignment, SbPlacement, SbSide
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
* a ref or a getter, so `SbContainer` props stay reactive.
|
|
6
|
-
*/
|
|
7
|
-
export interface FloatingPanelOptions {
|
|
8
|
-
isOpen: MaybeRefOrGetter<boolean>;
|
|
9
|
-
placement: MaybeRefOrGetter<SbPlacement>;
|
|
10
|
-
strategy: MaybeRefOrGetter<SbStrategy>;
|
|
11
|
-
offset: MaybeRefOrGetter<number>;
|
|
12
|
-
padding: MaybeRefOrGetter<number>;
|
|
13
|
-
matchWidth: MaybeRefOrGetter<boolean | 'min'>;
|
|
14
|
-
hideWhenDetached: MaybeRefOrGetter<boolean | 'close'>;
|
|
15
|
-
}
|
|
1
|
+
import { ComputedRef, CSSProperties, Ref } from 'vue';
|
|
2
|
+
import { SbAlignment, SbContainerProps, SbPlacement, SbSide } from '../types';
|
|
3
|
+
/** Positioning props of `SbContainer`, with their defaults: read reactively. */
|
|
4
|
+
type PositioningProps = Readonly<Required<Pick<SbContainerProps, 'placement' | 'strategy' | 'offset' | 'padding' | 'matchWidth' | 'hideWhenDetached'>>>;
|
|
16
5
|
export interface FloatingPanel {
|
|
17
6
|
reference: Ref<HTMLElement | null>;
|
|
18
7
|
floating: Ref<HTMLElement | null>;
|
|
@@ -30,4 +19,5 @@ export interface FloatingPanel {
|
|
|
30
19
|
/**
|
|
31
20
|
* Wraps Floating UI for the components. Not part of the public API.
|
|
32
21
|
*/
|
|
33
|
-
export declare function useSbFloatingPanel(
|
|
22
|
+
export declare function useSbFloatingPanel(props: PositioningProps, isOpen: Readonly<Ref<boolean>>): FloatingPanel;
|
|
23
|
+
export {};
|
package/dist/index.d.ts
CHANGED
|
@@ -2,4 +2,4 @@ export { default as SbContainer } from './components/SbContainer.vue';
|
|
|
2
2
|
export { default as SbReference } from './components/SbReference.vue';
|
|
3
3
|
export { default as SbFloating } from './components/SbFloating.vue';
|
|
4
4
|
export { useSbFloating } from './composables/useSbFloating';
|
|
5
|
-
export type { SbContainerProps, SbContainerSlotProps, SbContainerExposed, SbReferenceProps, SbFloatingProps, SbTrigger, SbPlacement, SbSide, SbAlignment, SbStrategy, SbFloatingRole, UseSbFloatingReturn, } from './types';
|
|
5
|
+
export type { SbContainerProps, SbContainerSlotProps, SbContainerExposed, SbReferenceProps, SbFloatingProps, SbTrigger, SbPlacement, SbSide, SbAlignment, SbStrategy, SbFloatingRole, SbOpenReason, SbCloseReason, UseSbFloatingReturn, } from './types';
|