@ui-sdk/svelte 0.1.0-beta.1 → 0.1.0-beta.10

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.
Files changed (68) hide show
  1. package/dist/autocomplete/autocomplete-item-text.svelte +31 -8
  2. package/dist/autocomplete/autocomplete.svelte +2 -2
  3. package/dist/autocomplete/autocomplete.svelte.d.ts +2 -2
  4. package/dist/autocomplete.d.ts +1 -1
  5. package/dist/combobox/combobox-item-text.svelte +31 -8
  6. package/dist/combobox/combobox.svelte +4 -2
  7. package/dist/combobox/combobox.svelte.d.ts +1 -1
  8. package/dist/command/command-item-text.svelte +31 -8
  9. package/dist/dialog/dialog-content.svelte +9 -3
  10. package/dist/dialog/dialog-content.svelte.d.ts +1 -0
  11. package/dist/drawer/drawer-content.svelte.d.ts +2 -6
  12. package/dist/field/field-description.svelte +2 -0
  13. package/dist/field/field-error.svelte +3 -6
  14. package/dist/listbox/listbox.svelte +7 -1
  15. package/dist/listbox/listbox.svelte.d.ts +2 -0
  16. package/dist/pagination/pagination.svelte +4 -0
  17. package/dist/pagination/pagination.svelte.d.ts +2 -0
  18. package/dist/popover/popover-content.svelte +4 -2
  19. package/dist/popover/popover-content.svelte.d.ts +1 -0
  20. package/dist/segmented-control.d.ts +1 -1
  21. package/dist/select/select-item-text.svelte +31 -8
  22. package/dist/select/select-trigger-binding.svelte +7 -8
  23. package/dist/select/select-trigger-binding.svelte.d.ts +2 -1
  24. package/dist/select/select-trigger.svelte +19 -11
  25. package/dist/select/select.svelte +7 -1
  26. package/dist/select/select.svelte.d.ts +2 -0
  27. package/dist/shortcuts.svelte.d.ts +2 -1
  28. package/dist/shortcuts.svelte.js +2 -1
  29. package/dist/use-primitive.svelte.js +20 -3
  30. package/docs/agents.md +83 -20
  31. package/docs/components/alert-dialog.md +2 -1
  32. package/docs/components/autocomplete.md +9 -2
  33. package/docs/components/calendar.md +2 -2
  34. package/docs/components/collapsible.md +1 -0
  35. package/docs/components/combobox.md +12 -3
  36. package/docs/components/command.md +1 -0
  37. package/docs/components/date-input.md +2 -0
  38. package/docs/components/date-picker.md +3 -1
  39. package/docs/components/dialog.md +50 -1
  40. package/docs/components/drawer.md +3 -1
  41. package/docs/components/file-input.md +3 -3
  42. package/docs/components/hover-card.md +6 -1
  43. package/docs/components/image-cropper.md +12 -12
  44. package/docs/components/listbox.md +55 -2
  45. package/docs/components/menu.md +10 -2
  46. package/docs/components/menubar.md +1 -0
  47. package/docs/components/navigation-menu.md +1 -0
  48. package/docs/components/number-input.md +1 -0
  49. package/docs/components/pagination.md +3 -2
  50. package/docs/components/popover.md +45 -2
  51. package/docs/components/resizable.md +6 -1
  52. package/docs/components/segmented-control.md +9 -0
  53. package/docs/components/select.md +18 -2
  54. package/docs/components/tabs.md +1 -1
  55. package/docs/components/time-input.md +2 -0
  56. package/docs/components/tooltip.md +6 -1
  57. package/docs/components/trigger-menu.md +3 -0
  58. package/docs/core.md +101 -23
  59. package/docs/forms.md +1 -1
  60. package/docs/installation.md +16 -1
  61. package/docs/introduction.md +2 -2
  62. package/docs/lists-and-menus.md +1 -1
  63. package/docs/llms.txt +33 -13
  64. package/docs/popups.md +1 -1
  65. package/docs/styling-and-animation.md +4 -0
  66. package/docs/utilities/async-options.md +6 -5
  67. package/docs/utilities/shortcuts.md +2 -2
  68. package/package.json +3 -3
@@ -574,6 +574,45 @@ Dialogs render where you put them and use the browser's top layer. Set `containe
574
574
 
575
575
  Choose a mode, open Notes, and try Tab or clicking the page. Check Close on outside press to compare dismissal.
576
576
 
577
+ ## Inside a Frame
578
+
579
+ A dialog opens above the whole page. Set `inline` on the content to keep it and its backdrop where they are in the page, like inside an app preview. Your CSS sizes and places them in their frame. Pair it with `modal="trap-focus"` so the page around the frame stays usable.
580
+
581
+ ```svelte title="inline.svelte"
582
+ <script lang="ts">
583
+ import {
584
+ Dialog,
585
+ DialogBackdrop,
586
+ DialogClose,
587
+ DialogContent,
588
+ DialogDescription,
589
+ DialogTitle,
590
+ DialogTrigger,
591
+ } from "@ui-sdk/svelte/dialog"
592
+ </script>
593
+
594
+ <div data-slot="dialog-frame">
595
+ <Dialog modal="trap-focus" closeOnOutsidePress={false}>
596
+ <DialogTrigger>Delete Draft</DialogTrigger>
597
+ <DialogBackdrop />
598
+ <DialogContent inline>
599
+ <div data-slot="stack">
600
+ <DialogTitle>Delete this draft?</DialogTitle>
601
+ <DialogDescription
602
+ >The preview keeps its dialog inside the frame.</DialogDescription
603
+ >
604
+ </div>
605
+ <div data-slot="row">
606
+ <DialogClose>Cancel</DialogClose>
607
+ <DialogClose data-variant="destructive">Delete</DialogClose>
608
+ </div>
609
+ </DialogContent>
610
+ </Dialog>
611
+ </div>
612
+ ```
613
+
614
+ Open Delete Draft. The dialog and its dim cover only the frame, and Tab stays inside the dialog.
615
+
577
616
  ## Warn Before Closing a Dirty Form
578
617
 
579
618
  Set `dismissible` to false while there are unsaved changes. Escape, an outside press, or a back gesture then keeps the dialog open and reports `onDismissAttempt`. Explicit Close parts and controller calls still work, so you can offer a deliberate way out.
@@ -1069,7 +1108,8 @@ Dims the page behind a modal dialog. Renders a `div`.
1069
1108
  - `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.
1070
1109
  - `initialFocus?` (`DialogInitialFocus`): Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
1071
1110
  - `finalFocus?` (`PopupFocusTarget`): Where focus goes when the dialog closes while focus is inside it.
1072
- - `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
1111
+ - `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. Its content keeps its state between opens.
1112
+ - `inline?` (`boolean`): Renders the dialog and its backdrop where they are in the page instead of above it, so it can stay inside a frame, like an app preview. Pair it with `modal="trap-focus"` to keep the rest of the page usable. A `container` on the dialog still moves its backdrop, so leave it off.
1073
1113
 
1074
1114
  ### DialogTitle
1075
1115
 
@@ -1209,6 +1249,7 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1209
1249
  - Tab moves through the dialog in order.
1210
1250
  - Tab from the last element wraps to the first.
1211
1251
  - Shift+Tab from the first element wraps to the last.
1252
+ - … from inside an iframe that is the … element wraps around the dialog.
1212
1253
  - Shift+Tab from the first element wraps to the checked radio of a group outside a form.
1213
1254
  - Tab reaches radios whose group's checked radio is behind the dialog.
1214
1255
  - Tab visits a positive tabindex first, like the browser.
@@ -1217,8 +1258,12 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1217
1258
  - With a positive tabindex in the dialog, Tab still moves through a shadow root and slots.
1218
1259
  - With a positive tabindex in the dialog, Tab from a focused element outside the tab order goes to the next stop.
1219
1260
  - Tab from a custom element with a positive tabindex enters its shadow root.
1261
+ - Tab from a last control inside a shadow root wraps to the first, and Shift+Tab comes back to it.
1262
+ - Tab wraps past a shadow root that Tab skips, under an inert or tabindex -1 host.
1263
+ - Tab wraps from the last stop of a shadow root that orders a positive tabindex first.
1220
1264
  - Opening focuses the first field even when a later one has a positive tabindex.
1221
1265
  - Escape closes the dialog and returns focus to the trigger.
1266
+ - An ancestor hears Escape already handled.
1222
1267
  - Escape after a click returns focus to the trigger.
1223
1268
  - The close button closes the dialog and returns focus to the trigger.
1224
1269
  - A virtual click from a screen reader moves focus into the dialog.
@@ -1229,6 +1274,7 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1229
1274
 
1230
1275
  - Pressing the backdrop closes the dialog.
1231
1276
  - Pressing the backdrop returns focus to the trigger.
1277
+ - After pressing the backdrop, Space on the trigger opens it again.
1232
1278
  - Clicking inside the dialog keeps it open.
1233
1279
  - An outside press doesn't reach the page.
1234
1280
 
@@ -1297,6 +1343,9 @@ Additional behaviors:
1297
1343
  - A pending open() resolves with reason unmount when the dialog leaves the page. Web components only.
1298
1344
  - A form with method dialog closes the dialog and reports the submitter's value.
1299
1345
  - A confirm helper resolves true for the action and false otherwise.
1346
+ - A confirm opened from inside a modal dialog takes focus and stays usable.
1347
+ - A confirm opened over a modal dialog with nothing focused stays usable.
1348
+ - A confirm opened as a modal dialog shows, before the page freezes, stays usable.
1300
1349
  - Closing reports why, for every way a dialog closes.
1301
1350
 
1302
1351
  **Shortcuts**
@@ -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. For animation libraries that drive the exit from state.
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.
@@ -311,12 +311,17 @@ Keep overflow visible around an arrow that extends outside the card. If the body
311
311
  - `data-open`: Present while the card is open. On a trigger, while it's open from that trigger.
312
312
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
313
313
  - `data-ending-style`: Present while the card animates out. Style the state you animate to.
314
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the card ended up, after flipping away from edges. Set on the arrow too.
315
+ - `data-align` (`start`, `center`, `end`): How the card lines up with its trigger.
314
316
 
315
317
  ### HoverCardArrow
316
318
  `[data-slot="hover-card-arrow"]`
317
319
 
318
320
  - `data-closed`: Present while the card is closed, including while it animates out.
319
321
  - `data-open`: Present while the card is open. On a trigger, while it's open from that trigger.
322
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the card ended up, after flipping away from edges. Set on the arrow too.
323
+ - `data-align` (`start`, `center`, `end`): How the card lines up with its trigger.
324
+ - `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the trigger, held back by `arrowPadding`.
320
325
 
321
326
  ## API Reference
322
327
 
@@ -353,7 +358,7 @@ A trigger outside the card also takes `controller`.
353
358
  - `arrowPadding?` (`number`): Space to keep between the arrow and the popup's corners, in pixels.
354
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.
355
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.
356
- - `keepMounted?` (`boolean`): Whether the card stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
361
+ - `keepMounted?` (`boolean`): Whether the card stays in the page, hidden, while closed. Its content keeps its state between opens.
357
362
 
358
363
  ### HoverCardArrow
359
364
 
@@ -24,9 +24,9 @@ Use the following composition to build an `ImageCropper`:
24
24
  ImageCropper
25
25
  ├── ImageCropperViewport
26
26
  │ ├── ImageCropperImage
27
- │ └── ImageCropperSelection
28
- │ ├── ImageCropperGrid
29
- │ └── ImageCropperHandle
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
- <ImageCropperHandle position="nw" />
73
- <ImageCropperHandle position="se" />
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 and selection get their place as inline styles in pixels. Give the viewport a size, and the handles a size and a place on their edge or corner of the selection.
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:
@@ -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.
@@ -851,7 +853,8 @@ Each part has a `data-slot`, such as `menu-item`, and its state attributes are l
851
853
  `[data-slot="menu-context-trigger"]`
852
854
 
853
855
  - `data-closed`: Present on an area while the menu isn't open from it.
854
- - `data-disabled`: Present when the item can't be chosen.
856
+ - `data-disabled`: Present when the area is disabled.
857
+ - `data-open`: Present on the area that opened the menu, while it's open.
855
858
 
856
859
  ### MenuContent
857
860
  `[data-slot="menu-content"]`
@@ -862,12 +865,15 @@ Each part has a `data-slot`, such as `menu-item`, and its state attributes are l
862
865
  - `data-open`: Present while the menu is open. A submenu trigger has it while its submenu is open.
863
866
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
864
867
  - `data-ending-style`: Present while the menu animates out. Style the state you animate to.
868
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the menu ended up, after flipping away from edges.
869
+ - `data-align` (`start`, `center`, `end`): How the menu lines up with its trigger.
865
870
  - `data-has-icons`: Present while any item inside holds an icon part, so items without one can line up.
866
871
 
867
872
  ### MenuItem
868
873
  `[data-slot="menu-item"]`
869
874
 
870
875
  - `data-disabled`: Present when the item can't be chosen.
876
+ - `data-highlighted`: Present on the item with keyboard focus or under the pointer.
871
877
  - `data-has-icon`: Present on an item while it holds an icon part.
872
878
 
873
879
  ### MenuCheckboxItem
@@ -875,6 +881,7 @@ Each part has a `data-slot`, such as `menu-item`, and its state attributes are l
875
881
 
876
882
  - `data-checked`: Present on checked checkbox items, and on the radio item that's its group's value.
877
883
  - `data-unchecked`: Present on items that aren't checked.
884
+ - `data-highlighted`: Present on the item with keyboard focus or under the pointer.
878
885
 
879
886
  ### MenuItemIndicator
880
887
  `[data-slot="menu-item-indicator"]`
@@ -887,6 +894,7 @@ Each part has a `data-slot`, such as `menu-item`, and its state attributes are l
887
894
 
888
895
  - `data-checked`: Present on checked checkbox items, and on the radio item that's its group's value.
889
896
  - `data-unchecked`: Present on items that aren't checked.
897
+ - `data-highlighted`: Present on the item with keyboard focus or under the pointer.
890
898
 
891
899
  ### MenuItemIcon
892
900
  `[data-slot="menu-item-icon"]`
@@ -947,7 +955,7 @@ A trigger outside the menu also takes `controller`.
947
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.
948
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.
949
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.
950
- - `keepMounted?` (`boolean`): Whether the menu stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
958
+ - `keepMounted?` (`boolean`): Whether the menu stays in the page, hidden, while closed. Its content keeps its state between opens.
951
959
 
952
960
  ### MenuItem
953
961
 
@@ -405,6 +405,7 @@ Every line below is an automated test.
405
405
  - Enter opens a menu and focuses its first item.
406
406
  - Space opens a menu and focuses its first item.
407
407
  - Escape closes the menu and focuses its trigger.
408
+ - Escape in a menu reached with ArrowRight returns focus to its trigger.
408
409
  - Tab in an open menu closes it and moves past the menubar.
409
410
  - A press opens a menu, and a press on its trigger closes it.
410
411
  - While a menu is open, pointing at another trigger opens its menu instead.
@@ -1409,6 +1409,7 @@ Every line below is an automated test.
1409
1409
  - Tab past the panel's last link moves on to the next trigger.
1410
1410
  - Shift+Tab from the panel's first link returns to its trigger.
1411
1411
  - Shift+Tab from the item after an open panel goes back into the panel.
1412
+ - Tab from the last item past an open panel leaves the navigation and closes it.
1412
1413
  - Escape inside a panel closes it and returns focus to its trigger.
1413
1414
  - Escape on an open trigger closes its panel.
1414
1415
  - Focus leaving the navigation closes the panel.
@@ -933,6 +933,7 @@ Every line below is an automated test.
933
933
 
934
934
  - Starts with its default value, formatted.
935
935
  - ArrowUp and ArrowDown step the value.
936
+ - Full-width digits from an input method commit as a number.
936
937
  - Shift with an arrow key steps by the large step.
937
938
  - Home and End go to the minimum and the maximum.
938
939
  - Stepping stops at the bounds.
@@ -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.
@@ -1177,12 +1213,17 @@ Each part has a `data-slot`, such as `popover-content`, and its state attributes
1177
1213
  - `data-open`: Present while the popover is open. On a trigger, while it's open from that trigger.
1178
1214
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
1179
1215
  - `data-ending-style`: Present while the popover animates out. Style the state you animate to.
1216
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the popover ended up, after flipping away from edges. Set on the arrow too.
1217
+ - `data-align` (`start`, `center`, `end`): How the popover lines up with its trigger.
1180
1218
 
1181
1219
  ### PopoverArrow
1182
1220
  `[data-slot="popover-arrow"]`
1183
1221
 
1184
1222
  - `data-closed`: Present while the popover is closed, including while it animates out.
1185
1223
  - `data-open`: Present while the popover is open. On a trigger, while it's open from that trigger.
1224
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the popover ended up, after flipping away from edges. Set on the arrow too.
1225
+ - `data-align` (`start`, `center`, `end`): How the popover lines up with its trigger.
1226
+ - `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the trigger, held back by `arrowPadding`.
1186
1227
 
1187
1228
  ## API Reference
1188
1229
 
@@ -1228,7 +1269,8 @@ A trigger outside the popover also takes `controller`.
1228
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.
1229
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.
1230
1271
  - `finalFocus?` (`PopupFocusTarget`): Where focus goes when the popover closes while focus is inside it.
1231
- - `keepMounted?` (`boolean`): Whether the popover stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
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.
1232
1274
 
1233
1275
  ### PopoverArrow
1234
1276
 
@@ -1357,6 +1399,7 @@ Every line below is an automated test.
1357
1399
  - Tab from the last element moves focus to the element after the trigger.
1358
1400
  - Focus leaving the popover closes it.
1359
1401
  - Escape closes the popover and returns focus to the trigger.
1402
+ - An ancestor hears Escape already handled.
1360
1403
  - Escape after a click returns focus to the trigger.
1361
1404
  - The close button closes the popover and returns focus to the trigger.
1362
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.
@@ -882,4 +883,8 @@ Every line below is an automated test.
882
883
  - At a limit, the cursor points the only way a handle can go.
883
884
  - A saved layout is there on the first paint.
884
885
 
886
+ **Touch**
887
+
888
+ - A touch drag that starts beside the handle, in its touch hit area, resizes without scrolling.
889
+
885
890
  Runs in React, Vue and web components.
@@ -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.