@ui-sdk/svelte 0.1.0-beta.7 → 0.1.0-beta.9
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/dist/autocomplete/autocomplete.svelte +2 -2
- package/dist/autocomplete/autocomplete.svelte.d.ts +2 -2
- package/dist/autocomplete.d.ts +1 -1
- package/dist/combobox/combobox.svelte +4 -2
- package/dist/combobox/combobox.svelte.d.ts +1 -1
- package/dist/dialog/dialog-content.svelte +9 -3
- package/dist/dialog/dialog-content.svelte.d.ts +1 -0
- package/dist/drawer/drawer-content.svelte.d.ts +2 -6
- package/dist/listbox/listbox.svelte +7 -1
- package/dist/listbox/listbox.svelte.d.ts +2 -0
- package/dist/pagination/pagination.svelte +4 -0
- package/dist/pagination/pagination.svelte.d.ts +2 -0
- package/dist/popover/popover-content.svelte +4 -2
- package/dist/popover/popover-content.svelte.d.ts +1 -0
- package/dist/segmented-control.d.ts +1 -1
- package/dist/select/select.svelte +7 -1
- package/dist/select/select.svelte.d.ts +2 -0
- package/dist/use-primitive.svelte.js +20 -3
- package/docs/agents.md +2 -2
- package/docs/components/alert-dialog.md +2 -1
- package/docs/components/autocomplete.md +4 -2
- package/docs/components/calendar.md +2 -2
- package/docs/components/collapsible.md +1 -0
- package/docs/components/combobox.md +5 -3
- package/docs/components/command.md +1 -0
- package/docs/components/date-input.md +1 -0
- package/docs/components/date-picker.md +1 -1
- package/docs/components/dialog.md +47 -1
- package/docs/components/drawer.md +3 -1
- package/docs/components/file-input.md +3 -3
- package/docs/components/hover-card.md +1 -1
- package/docs/components/image-cropper.md +12 -12
- package/docs/components/listbox.md +55 -2
- package/docs/components/menu.md +3 -1
- package/docs/components/pagination.md +3 -2
- package/docs/components/popover.md +40 -2
- package/docs/components/resizable.md +2 -1
- package/docs/components/segmented-control.md +9 -0
- package/docs/components/select.md +13 -2
- package/docs/components/time-input.md +1 -0
- package/docs/core.md +21 -0
- package/docs/forms.md +1 -1
- package/docs/llms.txt +13 -8
- package/docs/popups.md +1 -1
- package/docs/styling-and-animation.md +4 -0
- package/docs/utilities/async-options.md +6 -5
- package/docs/utilities/shortcuts.md +1 -1
- package/package.json +3 -3
|
@@ -166,6 +166,8 @@ Put long content in an inner `min-h-0 flex-1 overflow-y-auto` area. A downward d
|
|
|
166
166
|
|
|
167
167
|
Open the long sheet and scroll its text. At the top, drag downward to move the sheet; on a keyboard, Tab reaches the controls and Escape closes it.
|
|
168
168
|
|
|
169
|
+
Fields, sliders and color areas inside the sheet keep their own drags. For a drag surface of your own, like a canvas or a map, add `data-drawer-no-drag` to it, and a drag that starts there won't move the drawer.
|
|
170
|
+
|
|
169
171
|
## Sides
|
|
170
172
|
|
|
171
173
|
`side` chooses bottom, top, left, or right. Logical `start` and `end` follow text direction. The content’s `data-side` tells you which physical edge to style.
|
|
@@ -865,7 +867,7 @@ Dims the page behind a modal drawer, which manages its opacity. Renders a `div`.
|
|
|
865
867
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
866
868
|
- `initialFocus?` (`DialogInitialFocus`): Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
|
|
867
869
|
- `finalFocus?` (`PopupFocusTarget`): Where focus goes when the dialog closes while focus is inside it.
|
|
868
|
-
- `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed.
|
|
870
|
+
- `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
869
871
|
|
|
870
872
|
### DrawerHandle
|
|
871
873
|
|
|
@@ -145,7 +145,7 @@ Without `multiple`, a new file replaces the current one. A rejected file leaves
|
|
|
145
145
|
|
|
146
146
|
## Validation
|
|
147
147
|
|
|
148
|
-
Add `validate` for checks of your own. Return a reason string to reject a file, or `null` to accept it. It runs after the built-in type and size checks, and its reason reaches `onReject` like theirs. Validate uploads on your server too.
|
|
148
|
+
Add `validate` for checks of your own. Return a reason string to reject a file, or `null` to accept it. Its second argument's `accepted` holds the files of the same drop accepted before this one, so a duplicate check catches two files with one name in a single drop. It runs after the built-in type and size checks, and its reason reaches `onReject` like theirs. Validate uploads on your server too.
|
|
149
149
|
|
|
150
150
|
```svelte
|
|
151
151
|
<script lang="ts">
|
|
@@ -155,7 +155,7 @@ Add `validate` for checks of your own. Return a reason string to reject a file,
|
|
|
155
155
|
<FileInput
|
|
156
156
|
multiple
|
|
157
157
|
controller={files}
|
|
158
|
-
validate={(file) => (files.getValue().some((other) => other.name === file.name) ? "duplicate" : null)}
|
|
158
|
+
validate={(file, { accepted }) => ([...files.getValue(), ...accepted].some((other) => other.name === file.name) ? "duplicate" : null)}
|
|
159
159
|
onReject={(next) => (rejected = next)}
|
|
160
160
|
>
|
|
161
161
|
```
|
|
@@ -441,7 +441,7 @@ Props and callbacks are the same as below, as Svelte props. `value` can be bound
|
|
|
441
441
|
- `maxFiles?` (`number`): The most files accepted at a time. The first ones that pass the other checks are accepted, and the rest are rejected.
|
|
442
442
|
- `maxSize?` (`number`): The largest size accepted, in bytes.
|
|
443
443
|
- `minSize?` (`number`): The smallest size accepted, in bytes.
|
|
444
|
-
- `validate?` (`((file: File) => string | null | undefined | void)`): A check of your own. Return a reason, like `"duplicate"`, to reject the file, or nothing to accept it.
|
|
444
|
+
- `validate?` (`((file: File, batch: { accepted: readonly File[]; }) => string | null | undefined | void)`): A check of your own. Return a reason, like `"duplicate"`, to reject the file, or nothing to accept it. `accepted` holds the files of the same choice, drop or paste accepted before this one.
|
|
445
445
|
- `value?` (`File[]`): The files, to control the file input.
|
|
446
446
|
- `defaultValue?` (`File[]`): The files at first, when uncontrolled. A form reset returns to them.
|
|
447
447
|
- `onValueChange?` (`((value: File[], details: FileInputValueChangeDetails) => void)`): Runs when files are added or removed, with what changed in the details. `details.cancel()` stops it.
|
|
@@ -358,7 +358,7 @@ A trigger outside the card also takes `controller`.
|
|
|
358
358
|
- `arrowPadding?` (`number`): Space to keep between the arrow and the popup's corners, in pixels.
|
|
359
359
|
- `anchor?` (`string | Anchor | null`): Positions the popup against this instead of its trigger: an element, a CSS selector, a point like `{ x, y }`, or anything with `getBoundingClientRect()`. It's read on every check, so it can move. A controller's `open({ anchor })` wins for that open.
|
|
360
360
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
361
|
-
- `keepMounted?` (`boolean`): Whether the card stays in the page, hidden, while closed.
|
|
361
|
+
- `keepMounted?` (`boolean`): Whether the card stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
362
362
|
|
|
363
363
|
### HoverCardArrow
|
|
364
364
|
|
|
@@ -24,9 +24,9 @@ Use the following composition to build an `ImageCropper`:
|
|
|
24
24
|
ImageCropper
|
|
25
25
|
├── ImageCropperViewport
|
|
26
26
|
│ ├── ImageCropperImage
|
|
27
|
-
│
|
|
28
|
-
│
|
|
29
|
-
│
|
|
27
|
+
│ ├── ImageCropperSelection
|
|
28
|
+
│ │ └── ImageCropperGrid
|
|
29
|
+
│ └── ImageCropperHandle
|
|
30
30
|
├── ImageCropperZoom
|
|
31
31
|
├── ImageCropperRotate
|
|
32
32
|
└── ImageCropperFlip
|
|
@@ -37,7 +37,7 @@ ImageCropper
|
|
|
37
37
|
- **ImageCropperImage** is the image, turned and flipped. Give it `alt`.
|
|
38
38
|
- **ImageCropperSelection** shows the crop over the image. It's a slider you drag or move with the arrow keys.
|
|
39
39
|
- **ImageCropperGrid** draws lines across the selection, in thirds, for you to style.
|
|
40
|
-
- **ImageCropperHandle** resizes the selection from one edge or corner, its `position`, like `"se"` for the bottom right.
|
|
40
|
+
- **ImageCropperHandle** resizes the selection from one edge or corner, its `position`, like `"se"` for the bottom right. It goes beside the selection, not inside it, and sits on its edge or corner.
|
|
41
41
|
- **ImageCropperZoom** is a range input from 1, the largest crop, to `maxZoom`.
|
|
42
42
|
- **ImageCropperRotate** turns the image a quarter clockwise.
|
|
43
43
|
- **ImageCropperFlip** mirrors the image left to right, or top to bottom with `direction="vertical"`.
|
|
@@ -68,10 +68,9 @@ Import the parts and put them together:
|
|
|
68
68
|
<ImageCropper aria-label="Cover photo" {src} aspectRatio={3}>
|
|
69
69
|
<ImageCropperViewport>
|
|
70
70
|
<ImageCropperImage alt="Your cover photo" />
|
|
71
|
-
<ImageCropperSelection
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
</ImageCropperSelection>
|
|
71
|
+
<ImageCropperSelection />
|
|
72
|
+
<ImageCropperHandle position="nw" />
|
|
73
|
+
<ImageCropperHandle position="se" />
|
|
75
74
|
</ImageCropperViewport>
|
|
76
75
|
</ImageCropper>
|
|
77
76
|
```
|
|
@@ -142,10 +141,10 @@ Set `aspectRatio` to keep the crop's width over its height, like `1` for a squar
|
|
|
142
141
|
<ImageCropperImage alt="Mountains at sunset" />
|
|
143
142
|
<ImageCropperSelection>
|
|
144
143
|
<ImageCropperGrid />
|
|
145
|
-
{#each handles as position (position)}
|
|
146
|
-
<ImageCropperHandle {position} />
|
|
147
|
-
{/each}
|
|
148
144
|
</ImageCropperSelection>
|
|
145
|
+
{#each handles as position (position)}
|
|
146
|
+
<ImageCropperHandle {position} />
|
|
147
|
+
{/each}
|
|
149
148
|
</ImageCropperViewport>
|
|
150
149
|
<div data-slot="row">
|
|
151
150
|
<ImageCropperFlip>Flip</ImageCropperFlip>
|
|
@@ -303,7 +302,7 @@ See [Parts and Composition](../parts-and-composition.md) for the rendering contr
|
|
|
303
302
|
|
|
304
303
|
## Styling
|
|
305
304
|
|
|
306
|
-
Parts are unstyled, apart from the positions they need: the viewport is `position: relative` with `overflow: hidden`, and the image
|
|
305
|
+
Parts are unstyled, apart from the positions they need: the viewport is `position: relative` with `overflow: hidden`, and the image, the selection and each handle get their place as inline styles in pixels. A handle's place is the point on its edge or corner, so give it a size and center it with `translate: -50% -50%`. Give the viewport a size too.
|
|
307
306
|
|
|
308
307
|
A box viewport fits the whole image, so set its `aspect-ratio` to `--image-cropper-aspect-ratio`. A wide `box-shadow` on the selection dims the image outside it. Show the grid only while `data-dragging` is on it.
|
|
309
308
|
|
|
@@ -527,6 +526,7 @@ Every line below is an automated test.
|
|
|
527
526
|
|
|
528
527
|
- A drag moves the selection over the image and commits once.
|
|
529
528
|
- A handle resizes from its corner, within the image.
|
|
529
|
+
- Each handle sits on its edge or corner of the selection, and follows it.
|
|
530
530
|
- At a ratio, a handle keeps it.
|
|
531
531
|
- Escape during a drag puts the selection back.
|
|
532
532
|
|
|
@@ -147,7 +147,7 @@ Choose Basil, then hold Shift and choose Pepper to select a range. Use Ctrl+A or
|
|
|
147
147
|
|
|
148
148
|
## Selection That Follows Focus
|
|
149
149
|
|
|
150
|
-
A single list selects as arrow keys, Home, End, or typing move focus. A multiple list can do the same with `activation="automatic"`, like a file list: a press or arrow replaces the selection, Ctrl or Cmd adds to it, and Ctrl or Cmd with an arrow moves focus without selecting.
|
|
150
|
+
A single list selects as arrow keys, Page Up and Page Down, Home, End, or typing move focus. Page Up and Page Down move ten options, and stop at the ends. A multiple list can do the same with `activation="automatic"`, like a file list: a press or arrow replaces the selection, Ctrl or Cmd adds to it, and Ctrl or Cmd with an arrow moves focus without selecting.
|
|
151
151
|
|
|
152
152
|
Taps and screen-reader presses toggle an option instead, since they do not have modifier keys.
|
|
153
153
|
|
|
@@ -238,6 +238,51 @@ Set `activation="manual"` on a single list to browse without selecting. Space, E
|
|
|
238
238
|
|
|
239
239
|
Move through the options with the arrow keys. Nothing is selected until you press Space or Enter, and the console logs the choice.
|
|
240
240
|
|
|
241
|
+
## Focus on the List
|
|
242
|
+
|
|
243
|
+
Set `virtualFocus` to keep focus on the list itself while arrow keys, Home, End, and typing move a highlight through the options. The list points at the highlighted option with `aria-activedescendant`, so screen readers still announce it. Style the highlight with `[data-highlighted]`, since the options don't take focus.
|
|
244
|
+
|
|
245
|
+
```svelte title="virtual-focus.svelte"
|
|
246
|
+
<script lang="ts">
|
|
247
|
+
import { CheckIcon } from "@lucide/svelte"
|
|
248
|
+
import {
|
|
249
|
+
Listbox,
|
|
250
|
+
ListboxItem,
|
|
251
|
+
ListboxItemIndicator,
|
|
252
|
+
} from "@ui-sdk/svelte/listbox"
|
|
253
|
+
import { useLog } from "./log"
|
|
254
|
+
|
|
255
|
+
const frameworks = [
|
|
256
|
+
{ value: "next", label: "Next.js" },
|
|
257
|
+
{ value: "remix", label: "Remix" },
|
|
258
|
+
{ value: "astro", label: "Astro" },
|
|
259
|
+
{ value: "nuxt", label: "Nuxt" },
|
|
260
|
+
{ value: "sveltekit", label: "SvelteKit" },
|
|
261
|
+
]
|
|
262
|
+
|
|
263
|
+
const log = useLog()
|
|
264
|
+
</script>
|
|
265
|
+
|
|
266
|
+
<Listbox
|
|
267
|
+
activation="manual"
|
|
268
|
+
virtualFocus
|
|
269
|
+
onValueChange={(value, details) =>
|
|
270
|
+
log(`${value ?? "Nothing"} (${details.reason})`)}
|
|
271
|
+
aria-label="Framework"
|
|
272
|
+
>
|
|
273
|
+
{#each frameworks as framework (framework.value)}
|
|
274
|
+
<ListboxItem value={framework.value}>
|
|
275
|
+
{framework.label}
|
|
276
|
+
<ListboxItemIndicator>
|
|
277
|
+
<CheckIcon aria-hidden="true" />
|
|
278
|
+
</ListboxItemIndicator>
|
|
279
|
+
</ListboxItem>
|
|
280
|
+
{/each}
|
|
281
|
+
</Listbox>
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Tab into the list and move through it with the arrow keys. Focus stays on the list, and Space or Enter chooses the highlighted option.
|
|
285
|
+
|
|
241
286
|
## Deselectable
|
|
242
287
|
|
|
243
288
|
Add `deselectable` to let pressing the selected option clear a single selection. Without it, the selection stays as it is.
|
|
@@ -812,6 +857,7 @@ Props and callbacks are the same as below, as Svelte props. `value` can be bound
|
|
|
812
857
|
- `deselectable?` (`boolean`): Whether pressing the selected item of a single listbox unselects it, so nothing is selected.
|
|
813
858
|
- `orientation?` (`"horizontal" | "vertical"`): Which arrow keys move between items. Horizontal lists use Left and Right, swapped in right-to-left text.
|
|
814
859
|
- `loop?` (`boolean`): Whether arrow keys wrap from the last item to the first. Shift with an arrow never wraps.
|
|
860
|
+
- `virtualFocus?` (`boolean`): Keeps focus on the list itself, which points at the highlighted option with `aria-activedescendant`, instead of moving focus onto the options.
|
|
815
861
|
- `keepInView?` (`boolean`): Whether the list scrolls the option keys move to into view, and the selected option when it first shows. Turn it off when something else scrolls the list, like `bindScrollPicker`.
|
|
816
862
|
- `items?` (`ListData<T>`): The items as data. Renders them for you, and lets typing find items a virtualized list hasn't rendered.
|
|
817
863
|
- `itemToValue?` (`((value: T) => string)`): The string an item's value submits as and is identified by, for object values. Strings pass through, and objects use their `value` or `id`.
|
|
@@ -889,6 +935,8 @@ Every write method takes an optional `{ reason, event }`, passed to `onValueChan
|
|
|
889
935
|
- `setValue(value, options?)` (`(value: ListboxValue<T, Multiple>, options?: ListboxChangeOptions | undefined) => boolean`): Selects a value, as a user would. A disabled or read-only listbox ignores it. Returns false when the change was canceled or nothing changed.
|
|
890
936
|
- `clear(options?)` (`(options?: ListboxChangeOptions | undefined) => boolean`): Selects nothing: `null`, or an empty list with `multiple`. Returns false when the change was canceled or nothing changed.
|
|
891
937
|
- `selectAll(options?)` (`(options?: ListboxChangeOptions | undefined) => boolean`): Selects every enabled item, with `multiple`. Returns false when the change was canceled or nothing changed.
|
|
938
|
+
- `getHighlighted()` (`() => T | null`): The value of the highlighted option, or null when none is, like while focus is outside the list.
|
|
939
|
+
- `highlight(value)` (`(value: T | null) => boolean`): Highlights the option with this value, scrolled into view, or none with null. While focus is outside the list, the option takes the tab stop instead, so focus lands on it next. Returns false when no enabled option has the value.
|
|
892
940
|
- `focus()` (`() => void`): Moves focus into the list, onto the option that holds its tab stop.
|
|
893
941
|
|
|
894
942
|
### Events
|
|
@@ -907,7 +955,7 @@ Follows the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/
|
|
|
907
955
|
|
|
908
956
|
### Focus
|
|
909
957
|
|
|
910
|
-
The list is one tab stop. Tab returns to the last focused option, then falls back to the first selected or enabled option. Options receive real DOM focus, so `focus-visible` works directly.
|
|
958
|
+
The list is one tab stop. Tab returns to the last focused option, then falls back to the first selected or enabled option. Options receive real DOM focus, so `focus-visible` works directly. With `virtualFocus`, the list is the tab stop and keeps focus instead.
|
|
911
959
|
|
|
912
960
|
The root forwards focus into the options, including when you press a Field label or the list’s padding. Escape stays available to an enclosing dialog.
|
|
913
961
|
|
|
@@ -1013,6 +1061,11 @@ Beyond the pattern:
|
|
|
1013
1061
|
|
|
1014
1062
|
- Taps toggle where clicks replace, since touch has no modifier keys.
|
|
1015
1063
|
|
|
1064
|
+
**Focus on the list**
|
|
1065
|
+
|
|
1066
|
+
- With virtualFocus, keys move the highlight while focus stays on the list, which points at it.
|
|
1067
|
+
- With virtualFocus, a press chooses an option and keeps focus on the list.
|
|
1068
|
+
|
|
1016
1069
|
Runs in React, Vue and web components.
|
|
1017
1070
|
|
|
1018
1071
|
Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:
|
package/docs/components/menu.md
CHANGED
|
@@ -439,6 +439,8 @@ Arrow keys wrap by default; `loop` false stops at the ends. Typing finds an item
|
|
|
439
439
|
</Menu>
|
|
440
440
|
```
|
|
441
441
|
|
|
442
|
+
A menu holds items, groups and separators. For a text field beside a list of choices, like a search box or a rename field, use a [Popover](./popover.md). The field keeps its keys there, while in a menu the pointer moves focus from item to item.
|
|
443
|
+
|
|
442
444
|
## Focus After Closing
|
|
443
445
|
|
|
444
446
|
When the menu closes with focus inside it, focus returns to the trigger. If an action removes the trigger or moves people on to something else, set `finalFocus` on the content to a selector, an element or a function returning one, or to `"none"` to leave focus where the action put it. See [popup focus](../popups.md#focus) for the shared focus rules.
|
|
@@ -953,7 +955,7 @@ A trigger outside the menu also takes `controller`.
|
|
|
953
955
|
- `anchor?` (`string | Anchor | null`): Positions the popup against this instead of its trigger: an element, a CSS selector, a point like `{ x, y }`, or anything with `getBoundingClientRect()`. It's read on every check, so it can move. A controller's `open({ anchor })` wins for that open.
|
|
954
956
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
955
957
|
- `finalFocus?` (`PopupFocusTarget`): Where focus goes when the menu closes while focus is inside it. `"trigger"` returns it to the trigger and `"none"` leaves it. A CSS selector, an element or a function picks a specific element.
|
|
956
|
-
- `keepMounted?` (`boolean`): Whether the menu stays in the page, hidden, while closed.
|
|
958
|
+
- `keepMounted?` (`boolean`): Whether the menu stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
957
959
|
|
|
958
960
|
### MenuItem
|
|
959
961
|
|
|
@@ -91,7 +91,7 @@ The list's `children` snippet receives its state, whose `items` contains page nu
|
|
|
91
91
|
|
|
92
92
|
`PaginationLink` shows its page number unless you supply children. The current link gets `aria-current="page"` and `data-current`. `PaginationEllipsis` shows “…” and is hidden from screen readers.
|
|
93
93
|
|
|
94
|
-
Give Previous, Next, First, and Last text or an `aria-label`. At an end, a step gets `aria-disabled="true"` and `data-disabled` and stops changing the page. As a button, it stays in the tab order.
|
|
94
|
+
Give Previous, Next, First, and Last text or an `aria-label`. At an end, a step gets `aria-disabled="true"` and `data-disabled` and stops changing the page. As a button, it stays in the tab order. Set `disabled` on the root to do the same for every page and step, like while results load. A controller still changes the page.
|
|
95
95
|
|
|
96
96
|
## Usage
|
|
97
97
|
|
|
@@ -490,6 +490,7 @@ Props and callbacks are the same as below, as Svelte props. `page` can be bound
|
|
|
490
490
|
- `siblings?` (`number`): How many pages show on each side of the current one.
|
|
491
491
|
- `boundaries?` (`number`): How many pages always show at each end.
|
|
492
492
|
- `getHref?` (`((page: number) => string)`): The URL of a page. With it, parts are links: they navigate, open in a new tab with a modifier key, and work before JavaScript loads. Without it, they're buttons.
|
|
493
|
+
- `disabled?` (`boolean`): Whether every page and step does nothing, like a step at its end. A controller still pages it.
|
|
493
494
|
- `controller?` (`object`): Pages it from anywhere. Create one with `createPaginationController()`.
|
|
494
495
|
- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
|
|
495
496
|
|
|
@@ -517,7 +518,7 @@ What `render` and `children` snippets receive, per part.
|
|
|
517
518
|
`PaginationPrevious`, `PaginationNext`, `PaginationFirst` and `PaginationLast`:
|
|
518
519
|
|
|
519
520
|
- `page` (`number`): The page it goes to.
|
|
520
|
-
- `disabled` (`boolean`): Whether it's at the end it goes to, so it does nothing.
|
|
521
|
+
- `disabled` (`boolean`): Whether it's at the end it goes to, or the pagination is disabled, so it does nothing.
|
|
521
522
|
|
|
522
523
|
### Reasons
|
|
523
524
|
|
|
@@ -708,7 +708,7 @@ Open each one: Rename focuses its field, Publish focuses its Publish button, and
|
|
|
708
708
|
|
|
709
709
|
## Open on Hover
|
|
710
710
|
|
|
711
|
-
`openOnHover` adds pointer opening while keeping click, keyboard, and touch activation. `delay` and `closeDelay` control the pause before opening and closing. You can cross the gap into the content and interact with it.
|
|
711
|
+
`openOnHover` adds pointer opening while keeping click, keyboard, and touch activation. `delay` and `closeDelay` control the pause before opening and closing. You can cross the gap into the content and interact with it. Another popover or hover card opening on hover closes it, unless that one is inside it, so a row of hover triggers shows one at a time.
|
|
712
712
|
|
|
713
713
|
```svelte title="hover.svelte"
|
|
714
714
|
<script lang="ts">
|
|
@@ -1087,6 +1087,42 @@ Popovers render in place by default and use the browser's top layer. `container`
|
|
|
1087
1087
|
</Popover>
|
|
1088
1088
|
```
|
|
1089
1089
|
|
|
1090
|
+
## In Place
|
|
1091
|
+
|
|
1092
|
+
A popover opens above the page. Set `inline` on the content to render it where it is, inside its parent's layout and stacking, like a panel that opens out of a corner widget. Your CSS places it, so `side`, `align` and the offsets don't apply.
|
|
1093
|
+
|
|
1094
|
+
```svelte title="inline.svelte"
|
|
1095
|
+
<script lang="ts">
|
|
1096
|
+
import {
|
|
1097
|
+
Popover,
|
|
1098
|
+
PopoverClose,
|
|
1099
|
+
PopoverContent,
|
|
1100
|
+
PopoverDescription,
|
|
1101
|
+
PopoverTitle,
|
|
1102
|
+
PopoverTrigger,
|
|
1103
|
+
} from "@ui-sdk/svelte/popover"
|
|
1104
|
+
</script>
|
|
1105
|
+
|
|
1106
|
+
<div data-slot="popover-frame">
|
|
1107
|
+
<div data-slot="popover-corner">
|
|
1108
|
+
<Popover>
|
|
1109
|
+
<PopoverTrigger>Feedback</PopoverTrigger>
|
|
1110
|
+
<PopoverContent inline>
|
|
1111
|
+
<PopoverTitle>Send feedback</PopoverTitle>
|
|
1112
|
+
<PopoverDescription
|
|
1113
|
+
>The panel sits in the corner box, above its trigger.</PopoverDescription
|
|
1114
|
+
>
|
|
1115
|
+
<div data-slot="row">
|
|
1116
|
+
<PopoverClose>Close</PopoverClose>
|
|
1117
|
+
</div>
|
|
1118
|
+
</PopoverContent>
|
|
1119
|
+
</Popover>
|
|
1120
|
+
</div>
|
|
1121
|
+
</div>
|
|
1122
|
+
```
|
|
1123
|
+
|
|
1124
|
+
Open Feedback. The panel opens above the button, inside the corner box.
|
|
1125
|
+
|
|
1090
1126
|
## Custom Rendering
|
|
1091
1127
|
|
|
1092
1128
|
Every part takes a `render` snippet, which receives the props to spread and the part's state, and the `children` snippet receives the state too. The content's `children` snippet can read its payload, as the row editor does.
|
|
@@ -1233,7 +1269,8 @@ A trigger outside the popover also takes `controller`.
|
|
|
1233
1269
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
1234
1270
|
- `initialFocus?` (`PopoverInitialFocus`): Where focus goes when the popover opens. Opening on hover never moves focus, and opening with touch focuses the popover itself so no on-screen keyboard appears.
|
|
1235
1271
|
- `finalFocus?` (`PopupFocusTarget`): Where focus goes when the popover closes while focus is inside it.
|
|
1236
|
-
- `keepMounted?` (`boolean`): Whether the popover stays in the page, hidden, while closed.
|
|
1272
|
+
- `keepMounted?` (`boolean`): Whether the popover stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
1273
|
+
- `inline?` (`boolean`): Renders the popover where it is in the page instead of above it, inside its parent's layout and stacking, and leaves placing it to your CSS: `side`, `align` and the offsets don't apply.
|
|
1237
1274
|
|
|
1238
1275
|
### PopoverArrow
|
|
1239
1276
|
|
|
@@ -1362,6 +1399,7 @@ Every line below is an automated test.
|
|
|
1362
1399
|
- Tab from the last element moves focus to the element after the trigger.
|
|
1363
1400
|
- Focus leaving the popover closes it.
|
|
1364
1401
|
- Escape closes the popover and returns focus to the trigger.
|
|
1402
|
+
- An ancestor hears Escape already handled.
|
|
1365
1403
|
- Escape after a click returns focus to the trigger.
|
|
1366
1404
|
- The close button closes the popover and returns focus to the trigger.
|
|
1367
1405
|
- With initial focus none, opening leaves focus on the trigger.
|
|
@@ -344,7 +344,7 @@ Resize Files to log the layout and its reason. Split Evenly and Reset set the la
|
|
|
344
344
|
|
|
345
345
|
## Saving on Complete
|
|
346
346
|
|
|
347
|
-
`onLayoutChange` runs on every frame of a drag. `onLayoutCommit` runs once, when the interaction that changed the layout ends: the pointer lifts, the key comes up, or a panel collapses. Save there.
|
|
347
|
+
`onLayoutChange` runs on every frame of a drag. `onLayoutCommit` runs once, when the interaction that changed the layout ends: the pointer lifts, the key comes up, or a panel collapses. Save there. Escape during a drag puts the panels back where they started, and nothing commits.
|
|
348
348
|
|
|
349
349
|
```svelte title="complete.svelte"
|
|
350
350
|
<script lang="ts">
|
|
@@ -857,6 +857,7 @@ Every line below is an automated test.
|
|
|
857
857
|
- Dragging a vertical group's handle moves it up and down.
|
|
858
858
|
- Dragging past half a collapsible panel's minimum collapses it, and back opens it.
|
|
859
859
|
- A drag stops at the panels' bounds.
|
|
860
|
+
- Escape during a drag puts the panels back where they started.
|
|
860
861
|
- A double-click on a handle collapses its panel, and another restores it.
|
|
861
862
|
- A press just beside the thin handle drags it.
|
|
862
863
|
- A press farther from the handle doesn't drag.
|
|
@@ -88,9 +88,15 @@ Name the control with `aria-label`, or put it in a [Field](./field.md) whose lab
|
|
|
88
88
|
height: var(--segmented-control-indicator-height);
|
|
89
89
|
transition-property: top, left, width, height;
|
|
90
90
|
transition-duration: 200ms;
|
|
91
|
+
|
|
92
|
+
&[data-activation-direction="none"] {
|
|
93
|
+
transition: none;
|
|
94
|
+
}
|
|
91
95
|
}
|
|
92
96
|
```
|
|
93
97
|
|
|
98
|
+
Skip the transitions while `data-activation-direction` is `"none"`, so the indicator doesn't slide in on its first placement. After that it says which way the checked item moved: `left`, `right`, `up` or `down`.
|
|
99
|
+
|
|
94
100
|
## Vertical
|
|
95
101
|
|
|
96
102
|
Set `orientation="vertical"` to stack the items. Arrow keys on both axes still move between them, as in any radio group, and `data-orientation` on every part lets one stylesheet lay out both directions.
|
|
@@ -298,6 +304,7 @@ Each part has a `data-slot`, such as `segmented-control-item`, and its state att
|
|
|
298
304
|
`[data-slot="segmented-control-indicator"]`
|
|
299
305
|
|
|
300
306
|
- `data-orientation` (`horizontal`, `vertical`): Which way the items run.
|
|
307
|
+
- `data-activation-direction` (`none`)
|
|
301
308
|
|
|
302
309
|
## API Reference
|
|
303
310
|
|
|
@@ -340,6 +347,7 @@ What render functions, state-based class names and slots receive.
|
|
|
340
347
|
|
|
341
348
|
- `value` (`string | null`): The checked item's value, which the indicator sits behind.
|
|
342
349
|
- `orientation` (`SegmentedControlOrientation`): Which way the items run.
|
|
350
|
+
- `direction` (`Direction`): Which way the checked item last moved on screen, `"none"` before it first moves.
|
|
343
351
|
|
|
344
352
|
### Reasons
|
|
345
353
|
|
|
@@ -409,6 +417,7 @@ Every line below is an automated test.
|
|
|
409
417
|
|
|
410
418
|
- The indicator covers the checked item.
|
|
411
419
|
- The indicator follows the checked item.
|
|
420
|
+
- The indicator says which way the checked item moved, and none at first.
|
|
412
421
|
- The indicator covers the checked item in a vertical control.
|
|
413
422
|
- The indicator matches items with fractional widths exactly.
|
|
414
423
|
- A scaled ancestor doesn't move the indicator off fractional items.
|
|
@@ -1631,6 +1631,7 @@ Props and callbacks are the same as below, as Svelte props. `value`, `open` and
|
|
|
1631
1631
|
- `isItemEqualToValue?` (`((itemValue: T, value: T) => boolean)`): Whether an item's value is the selected value, for object values that aren't the same object.
|
|
1632
1632
|
- `onHighlight?` (`((value: T | null, details: ListHighlightDetails) => void)`): Runs when the highlight moves, with the item's index among the visible items, so a virtualized list can scroll to it.
|
|
1633
1633
|
- `loop?` (`boolean`): Whether arrow keys wrap from the last item to the first.
|
|
1634
|
+
- `virtualFocus?` (`boolean`): Keeps focus on the trigger while the list is open, as on a native select: arrow keys, Home, End and typing move the highlight, and the trigger points at the highlighted item with `aria-activedescendant`. A search field in the list still takes focus.
|
|
1634
1635
|
- `modal?` (`"pointer" | boolean`): `"pointer"`: an outside press only closes the list. `true`: also locks scroll and makes the rest of the page inert. `false`: outside presses reach what they hit.
|
|
1635
1636
|
- `presentation?` (`PresentationSetting<"popover">`): How the list presents. `"sheet"` slides it up from the bottom of the screen, where it can be swiped away, and `"auto"` does that on small touch screens. Decided each time it opens; the server renders `"popover"` for `"auto"`.
|
|
1636
1637
|
- `disabled?` (`boolean`): Disables the select like a native one: it can't be focused or changed, and the value isn't submitted.
|
|
@@ -1658,7 +1659,7 @@ A trigger outside the select also takes `controller`.
|
|
|
1658
1659
|
### SelectValue
|
|
1659
1660
|
|
|
1660
1661
|
- `placeholder?` (`string`): What shows while nothing is selected. Overrides the select's `placeholder`.
|
|
1661
|
-
- `maxLabels?` (`number`): With `multiple`, how many labels show before the rest are counted, as in "Apple, Banana and 2 more", joined the way the page's language joins lists
|
|
1662
|
+
- `maxLabels?` (`number`): With `multiple`, how many labels show before the rest are counted, as in "Apple, Banana and 2 more", joined the way the page's language joins lists, or in English with the default `getMoreLabel`.
|
|
1662
1663
|
- `getMoreLabel?` (`((count: number) => string)`): The words for the labels past `maxLabels`.
|
|
1663
1664
|
|
|
1664
1665
|
### SelectContent
|
|
@@ -1672,7 +1673,7 @@ A trigger outside the select also takes `controller`.
|
|
|
1672
1673
|
- `anchor?` (`string | Anchor | null`): Positions the popup against this instead of its trigger: an element, a CSS selector, a point like `{ x, y }`, or anything with `getBoundingClientRect()`. It's read on every check, so it can move. A controller's `open({ anchor })` wins for that open.
|
|
1673
1674
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
1674
1675
|
- `alignItemWithTrigger?` (`boolean`): Whether the list overlaps the trigger so the selected item sits on it, like a native select on macOS. Falls back to opening below when there isn't room, and for touch.
|
|
1675
|
-
- `keepMounted?` (`boolean`): Whether the list stays in the page, hidden, while closed.
|
|
1676
|
+
- `keepMounted?` (`boolean`): Whether the list stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
1676
1677
|
|
|
1677
1678
|
### SelectItem
|
|
1678
1679
|
|
|
@@ -1875,6 +1876,8 @@ The select follows the [WAI-ARIA select-only combobox pattern](https://www.w3.or
|
|
|
1875
1876
|
|
|
1876
1877
|
Arrow keys move through the open list; Home and End reach its first and last items. Set `loop={false}` to stop arrow keys at either end. The popup follows the trigger's inherited text direction; use logical CSS properties for spacing in right-to-left layouts.
|
|
1877
1878
|
|
|
1879
|
+
Set `virtualFocus` to keep focus on the trigger while the list is open, as on a native select: arrow keys, Home, End and typing move the highlight, the trigger points at it with `aria-activedescendant`, and Tab closes the list and moves on. A search field in the list still takes focus.
|
|
1880
|
+
|
|
1878
1881
|
### Tested Behavior
|
|
1879
1882
|
|
|
1880
1883
|
Every line below is an automated test.
|
|
@@ -1902,6 +1905,7 @@ Every line below is an automated test.
|
|
|
1902
1905
|
- Enter chooses the focused item, closes and returns focus to the trigger.
|
|
1903
1906
|
- Space chooses the focused item.
|
|
1904
1907
|
- Escape closes without choosing and returns focus to the trigger.
|
|
1908
|
+
- An ancestor hears Escape already handled.
|
|
1905
1909
|
- The chosen item is selected when the list opens again, and takes focus.
|
|
1906
1910
|
|
|
1907
1911
|
**Typing on the closed trigger**
|
|
@@ -1939,6 +1943,7 @@ Every line below is an automated test.
|
|
|
1939
1943
|
**Forms**
|
|
1940
1944
|
|
|
1941
1945
|
- The form submits the value under the select's name.
|
|
1946
|
+
- Enter in the form's one text field submits it, with no submit button.
|
|
1942
1947
|
- A required select blocks submission until a value is chosen.
|
|
1943
1948
|
- A disabled select can't be opened.
|
|
1944
1949
|
- A read-only select doesn't change its value.
|
|
@@ -1962,6 +1967,12 @@ Also tested:
|
|
|
1962
1967
|
- A form reset returns the select to its default value.
|
|
1963
1968
|
- Typing on the closed trigger selects items before the list has ever been in the page.
|
|
1964
1969
|
|
|
1970
|
+
**Focus on the trigger**
|
|
1971
|
+
|
|
1972
|
+
- With virtualFocus, keys move the highlight while focus stays on the trigger, which points at it.
|
|
1973
|
+
- With virtualFocus, Tab closes the list and moves on from the trigger.
|
|
1974
|
+
- With virtualFocus, a click on an item chooses it and keeps focus on the trigger.
|
|
1975
|
+
|
|
1965
1976
|
Runs in React, Vue and web components.
|
|
1966
1977
|
|
|
1967
1978
|
Searching, with a search field in the list:
|
|
@@ -206,6 +206,7 @@ Every line below is an automated test.
|
|
|
206
206
|
- A canceled change keeps the date.
|
|
207
207
|
- The form submits the ISO date and time under their names.
|
|
208
208
|
- Enter submits the form with what was typed.
|
|
209
|
+
- Enter submits a form with no submit button, in a segment or the form's one text field.
|
|
209
210
|
- Resetting the form brings back the default date.
|
|
210
211
|
- A partly filled date can't be submitted.
|
|
211
212
|
- A required empty date can't be submitted.
|
package/docs/core.md
CHANGED
|
@@ -2338,6 +2338,8 @@ In a textarea, the arrow keys move between lines first. An entry comes back only
|
|
|
2338
2338
|
|
|
2339
2339
|
Edits to an entry you brought back stay while you move through the others. When `entries` changes, like after a send, it starts again from the newest. Call `history.reset()` to do the same yourself.
|
|
2340
2340
|
|
|
2341
|
+
Entries that are objects made from your messages, like `messages.map((m) => ({ id: m.id, text: m.text }))`, are new every time. Pass `getEntryKey`, like `(entry) => entry.id`, and entries are matched by key instead: the one you brought back keeps its place when the list is made again, or when a new message arrives while you're stepping through.
|
|
2342
|
+
|
|
2341
2343
|
It leaves the arrow keys alone while a modifier is held, while an input method is composing, while text is selected in a textarea, and on a read-only field. It also leaves them to a popup, like a suggestion menu, while the field's `aria-expanded` is `"true"` or the field has `data-open`, which a Trigger Menu sets on its textarea. On an input, it works for the `text`, `search`, `url` and `tel` types, so a number field keeps its steps.
|
|
2342
2344
|
|
|
2343
2345
|
### Report It as a Change
|
|
@@ -4270,6 +4272,15 @@ if (moved?.shift) {
|
|
|
4270
4272
|
|
|
4271
4273
|
`from` supplies the starting point when there isn't an anchor yet. `selection.anchor()` returns the current anchor's key.
|
|
4272
4274
|
|
|
4275
|
+
When arrow keys move focus without selecting, like in a table with a checkbox column, move the anchor along with focus so the next Shift range starts there. `setAnchor` leaves the selection as it is, and `null` clears the anchor:
|
|
4276
|
+
|
|
4277
|
+
```ts
|
|
4278
|
+
const moved = roving.keydown(event, el)
|
|
4279
|
+
if (moved && !moved.shift) {
|
|
4280
|
+
selection.setAnchor(moved.key)
|
|
4281
|
+
}
|
|
4282
|
+
```
|
|
4283
|
+
|
|
4273
4284
|
A range keeps what was selected when the anchor was set, then adds the items between the anchor and the target. Pass `additive: false` to select only the range. Supplying a different selection from outside starts the next range over.
|
|
4274
4285
|
|
|
4275
4286
|
Click a file, then Shift-click another for a range. Control or Command-click toggles one file. Turn on Ranges replace the selection to compare.
|
|
@@ -7986,6 +7997,16 @@ document.head.append(
|
|
|
7986
7997
|
|
|
7987
7998
|
These stubs don't exercise native popup or animation behavior. Use a browser for those checks, and for checking the finished component with a keyboard and screen reader.
|
|
7988
7999
|
|
|
8000
|
+
Some things land a moment after a render or an event. An icon-only button gets its name from its tooltip a tick after it renders, and focus moves into a menu that opened on a press in the next frame. Wait for them with `settle`, inside `act` in React, or query with `findByRole`:
|
|
8001
|
+
|
|
8002
|
+
```ts
|
|
8003
|
+
import { checkPattern, settle } from "@ui-sdk/core/testing"
|
|
8004
|
+
|
|
8005
|
+
await user.click(screen.getByRole("button", { name: "Options" }))
|
|
8006
|
+
await act(settle)
|
|
8007
|
+
await checkPattern(screen.getByRole("menu"), "menu")
|
|
8008
|
+
```
|
|
8009
|
+
|
|
7989
8010
|
|
|
7990
8011
|
# Get Started
|
|
7991
8012
|
|
package/docs/forms.md
CHANGED
|
@@ -49,7 +49,7 @@ A reset also goes through `onCheckedChange` and `bind:checked`. Keep the binding
|
|
|
49
49
|
</form>
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
Uncheck the box, then press Reset. `defaultChecked` supplies the reset value. The callback receives `true` with reason `"reset"`, and the binding updates `checked`. The callback runs when reset requests a different value; it does not run if the checkbox is already at its default.
|
|
52
|
+
Uncheck the box, then press Reset. `defaultChecked` supplies the reset value. The callback receives `true` with reason `"reset"`, and the binding updates `checked`. The callback runs when reset requests a different value; it does not run if the checkbox is already at its default. Without `defaultChecked`, a reset leaves a controlled checkbox as it is, so your state stays the only source of its value.
|
|
53
53
|
|
|
54
54
|
## Label and Validate a Field
|
|
55
55
|
|
package/docs/llms.txt
CHANGED
|
@@ -508,6 +508,8 @@ Popup content gets `data-starting-style` before it enters and `data-ending-style
|
|
|
508
508
|
|
|
509
509
|
Put exit styles on `data-ending-style`. `data-closed` describes the state but doesn't keep the element around for an exit.
|
|
510
510
|
|
|
511
|
+
An exit animation you start from script is waited for too, when it starts in the same task that closes the popup, like in its open change callback. One started later, from an effect or an observer, isn't.
|
|
512
|
+
|
|
511
513
|
#### Svelte Transitions
|
|
512
514
|
|
|
513
515
|
Svelte's own transitions work too. Put one on the element you render, with `|global`, since the block that adds and removes the element is inside the component. A popup stays visible above the page until its outro ends:
|
|
@@ -558,6 +560,8 @@ ui-sdk adds this CSS once a component mounts, so HTML rendered on the server doe
|
|
|
558
560
|
|
|
559
561
|
It leaves `hidden="until-found"` alone, so find in page can still open a closed panel.
|
|
560
562
|
|
|
563
|
+
The same layer takes the browser's own popover border, padding and background off Popover, Dialog, Drawer, Tooltip and Hover Card content. Menu, Select, Combobox and Date Picker content keep them, so give those parts a `border`, `padding` and `background` of your own. `web.css` already does.
|
|
564
|
+
|
|
561
565
|
### Content Security Policy
|
|
562
566
|
|
|
563
567
|
A Content Security Policy without `'unsafe-inline'` in `style-src` blocks the CSS ui-sdk adds. Give ui-sdk your policy's nonce with a meta tag in the page's `<head>`:
|
|
@@ -731,7 +735,7 @@ Dialogs, alert dialogs, drawers, and popovers move focus into their content when
|
|
|
731
735
|
| Hover | Nowhere. Focus stays where it is. |
|
|
732
736
|
| Rendered open | Nowhere, except in a dialog, which takes focus as it mounts. |
|
|
733
737
|
|
|
734
|
-
`initialFocus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one.
|
|
738
|
+
`initialFocus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one. When focus lands on a text field that already holds a value, its text is selected, so typing replaces it.
|
|
735
739
|
|
|
736
740
|
`modal` decides whether Tab can leave. With `true` or `"trap-focus"`, Tab and Shift+Tab wrap inside the content. With `false`, Tab moves from the trigger into a popover and on to the page after it, and focus leaving closes the popover. A non-modal dialog stays open.
|
|
737
741
|
|
|
@@ -906,7 +910,7 @@ A reset also goes through `onCheckedChange` and `bind:checked`. Keep the binding
|
|
|
906
910
|
</form>
|
|
907
911
|
```
|
|
908
912
|
|
|
909
|
-
Uncheck the box, then press Reset. `defaultChecked` supplies the reset value. The callback receives `true` with reason `"reset"`, and the binding updates `checked`. The callback runs when reset requests a different value; it does not run if the checkbox is already at its default.
|
|
913
|
+
Uncheck the box, then press Reset. `defaultChecked` supplies the reset value. The callback receives `true` with reason `"reset"`, and the binding updates `checked`. The callback runs when reset requests a different value; it does not run if the checkbox is already at its default. Without `defaultChecked`, a reset leaves a controlled checkbox as it is, so your state stays the only source of its value.
|
|
910
914
|
|
|
911
915
|
### Label and Validate a Field
|
|
912
916
|
|
|
@@ -1366,11 +1370,12 @@ Use `ComboboxStatus` and `ComboboxEmpty` to show loading, error, and empty messa
|
|
|
1366
1370
|
|
|
1367
1371
|
The second argument sets the starting behavior:
|
|
1368
1372
|
|
|
1369
|
-
| Option | What It Does
|
|
1370
|
-
| ----------- |
|
|
1371
|
-
| `debounce` | Milliseconds typing must pause before a request starts.
|
|
1372
|
-
| `query` | The starting search text.
|
|
1373
|
-
| `immediate` | Loads that text as soon as the component mounts.
|
|
1373
|
+
| Option | What It Does | Default |
|
|
1374
|
+
| ----------- | ------------------------------------------------------------------------------- | ------- |
|
|
1375
|
+
| `debounce` | Milliseconds typing must pause before a request starts. | `200` |
|
|
1376
|
+
| `query` | The starting search text. | `""` |
|
|
1377
|
+
| `immediate` | Loads that text as soon as the component mounts. | `false` |
|
|
1378
|
+
| `minLength` | Characters the text needs before anything loads. Shorter text clears the items. | `0` |
|
|
1374
1379
|
|
|
1375
1380
|
For initial choices, add `{ immediate: true, debounce: 300 }` after the loader. Until that first load starts, `status` is already `"loading"`, so the list never flashes an empty state. If you set `query`, use the same starting text for the component's `defaultQuery`.
|
|
1376
1381
|
|
|
@@ -1446,7 +1451,7 @@ Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` f
|
|
|
1446
1451
|
|
|
1447
1452
|
#### While Someone Is Typing
|
|
1448
1453
|
|
|
1449
|
-
Shortcuts with Command, Control, or Option can run in text fields. Plain letters and other keys stay available for typing. Set `allowInInput: true` when a shortcut should work there too, such as Escape to clear a search.
|
|
1454
|
+
Shortcuts with Command, Control, or Option can run in text fields. Plain letters and other keys stay available for typing. Set `allowInInput: true` when a shortcut should work there too, such as Escape to clear a search. A shortcut runs once per press. Set `repeat: true` to keep it running while the keys are held, like `j` moving down a list.
|
|
1450
1455
|
|
|
1451
1456
|
#### Limit a Shortcut to an Area
|
|
1452
1457
|
|
package/docs/popups.md
CHANGED
|
@@ -85,7 +85,7 @@ Dialogs, alert dialogs, drawers, and popovers move focus into their content when
|
|
|
85
85
|
| Hover | Nowhere. Focus stays where it is. |
|
|
86
86
|
| Rendered open | Nowhere, except in a dialog, which takes focus as it mounts. |
|
|
87
87
|
|
|
88
|
-
`initialFocus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one.
|
|
88
|
+
`initialFocus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one. When focus lands on a text field that already holds a value, its text is selected, so typing replaces it.
|
|
89
89
|
|
|
90
90
|
`modal` decides whether Tab can leave. With `true` or `"trap-focus"`, Tab and Shift+Tab wrap inside the content. With `false`, Tab moves from the trigger into a popover and on to the page after it, and focus leaving closes the popover. A non-modal dialog stays open.
|
|
91
91
|
|
|
@@ -91,6 +91,8 @@ Popup content gets `data-starting-style` before it enters and `data-ending-style
|
|
|
91
91
|
|
|
92
92
|
Put exit styles on `data-ending-style`. `data-closed` describes the state but doesn't keep the element around for an exit.
|
|
93
93
|
|
|
94
|
+
An exit animation you start from script is waited for too, when it starts in the same task that closes the popup, like in its open change callback. One started later, from an effect or an observer, isn't.
|
|
95
|
+
|
|
94
96
|
### Svelte Transitions
|
|
95
97
|
|
|
96
98
|
Svelte's own transitions work too. Put one on the element you render, with `|global`, since the block that adds and removes the element is inside the component. A popup stays visible above the page until its outro ends:
|
|
@@ -141,6 +143,8 @@ ui-sdk adds this CSS once a component mounts, so HTML rendered on the server doe
|
|
|
141
143
|
|
|
142
144
|
It leaves `hidden="until-found"` alone, so find in page can still open a closed panel.
|
|
143
145
|
|
|
146
|
+
The same layer takes the browser's own popover border, padding and background off Popover, Dialog, Drawer, Tooltip and Hover Card content. Menu, Select, Combobox and Date Picker content keep them, so give those parts a `border`, `padding` and `background` of your own. `web.css` already does.
|
|
147
|
+
|
|
144
148
|
## Content Security Policy
|
|
145
149
|
|
|
146
150
|
A Content Security Policy without `'unsafe-inline'` in `style-src` blocks the CSS ui-sdk adds. Give ui-sdk your policy's nonce with a meta tag in the page's `<head>`:
|