@ui-sdk/svelte 0.1.0-beta.7 → 0.1.0-beta.8

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 (39) hide show
  1. package/dist/autocomplete/autocomplete.svelte +2 -2
  2. package/dist/autocomplete/autocomplete.svelte.d.ts +2 -2
  3. package/dist/autocomplete.d.ts +1 -1
  4. package/dist/combobox/combobox.svelte +4 -2
  5. package/dist/combobox/combobox.svelte.d.ts +1 -1
  6. package/dist/listbox/listbox.svelte +3 -1
  7. package/dist/pagination/pagination.svelte +4 -0
  8. package/dist/pagination/pagination.svelte.d.ts +2 -0
  9. package/dist/segmented-control.d.ts +1 -1
  10. package/dist/select/select.svelte +3 -1
  11. package/dist/use-primitive.svelte.js +20 -3
  12. package/docs/agents.md +2 -2
  13. package/docs/components/alert-dialog.md +1 -1
  14. package/docs/components/autocomplete.md +2 -2
  15. package/docs/components/calendar.md +2 -2
  16. package/docs/components/collapsible.md +1 -0
  17. package/docs/components/combobox.md +3 -3
  18. package/docs/components/command.md +1 -0
  19. package/docs/components/date-input.md +1 -0
  20. package/docs/components/date-picker.md +1 -1
  21. package/docs/components/dialog.md +7 -1
  22. package/docs/components/drawer.md +3 -1
  23. package/docs/components/file-input.md +3 -3
  24. package/docs/components/hover-card.md +1 -1
  25. package/docs/components/menu.md +3 -1
  26. package/docs/components/pagination.md +3 -2
  27. package/docs/components/popover.md +3 -2
  28. package/docs/components/resizable.md +2 -1
  29. package/docs/components/segmented-control.md +9 -0
  30. package/docs/components/select.md +4 -2
  31. package/docs/components/time-input.md +1 -0
  32. package/docs/core.md +21 -0
  33. package/docs/forms.md +1 -1
  34. package/docs/llms.txt +13 -8
  35. package/docs/popups.md +1 -1
  36. package/docs/styling-and-animation.md +4 -0
  37. package/docs/utilities/async-options.md +6 -5
  38. package/docs/utilities/shortcuts.md +1 -1
  39. package/package.json +3 -3
@@ -12,7 +12,7 @@ A text field that suggests as you type. The text is the value. Renders no elemen
12
12
  type AutocompleteDismissReason,
13
13
  type AutocompleteOpenChangeReason,
14
14
  type AutocompleteSubmitDetails,
15
- type AutocompleteValueChangeReason,
15
+ type AutocompleteValueChangeDetails,
16
16
  type ListAnnouncement,
17
17
  type ListData,
18
18
  type ListHighlightDetails,
@@ -28,7 +28,7 @@ A text field that suggests as you type. The text is the value. Renders no elemen
28
28
  import { ContainerKey, OwnContentKey } from "./context.js"
29
29
  import AutocompleteContent from "./autocomplete-content.svelte"
30
30
 
31
- type ValueDetails = ChangeDetails<AutocompleteValueChangeReason>
31
+ type ValueDetails = AutocompleteValueChangeDetails
32
32
  type OpenDetails = ChangeDetails<AutocompleteOpenChangeReason>
33
33
 
34
34
  let {
@@ -1,9 +1,9 @@
1
1
  import type { ChangeDetails, DismissAttemptDetails } from "@ui-sdk/core";
2
2
  import type { AsyncOptionsStatus } from "@ui-sdk/core/async-options";
3
- import { type AutocompleteController, type AutocompleteDismissReason, type AutocompleteOpenChangeReason, type AutocompleteSubmitDetails, type AutocompleteValueChangeReason, type ListAnnouncement, type ListData, type ListHighlightDetails, type SearchFilter } from "@ui-sdk/core/autocomplete";
3
+ import { type AutocompleteController, type AutocompleteDismissReason, type AutocompleteOpenChangeReason, type AutocompleteSubmitDetails, type AutocompleteValueChangeDetails, type ListAnnouncement, type ListData, type ListHighlightDetails, type SearchFilter } from "@ui-sdk/core/autocomplete";
4
4
  import { type Snippet } from "svelte";
5
5
  import { type PopupContainer } from "../popup.svelte";
6
- type ValueDetails = ChangeDetails<AutocompleteValueChangeReason>;
6
+ type ValueDetails = AutocompleteValueChangeDetails;
7
7
  type OpenDetails = ChangeDetails<AutocompleteOpenChangeReason>;
8
8
  type $$ComponentProps = {
9
9
  /** The text. Bind it with `bind:value` to control it. */
@@ -16,4 +16,4 @@ export { default as AutocompleteSeparator } from "./autocomplete/autocomplete-se
16
16
  export { default as AutocompleteStatus } from "./autocomplete/autocomplete-status.svelte";
17
17
  export { default as AutocompleteTrigger } from "./autocomplete/autocomplete-trigger.svelte";
18
18
  export { createAutocompleteController } from "@ui-sdk/core/autocomplete";
19
- export type { AutocompleteApi, AutocompleteArrowState, AutocompleteChangeOptions, AutocompleteClearProps, AutocompleteClearState, AutocompleteContentProps, AutocompleteContentState, AutocompleteController, AutocompleteDismissReason, AutocompleteEmptyState, AutocompleteInputState, AutocompleteItemIconProps, AutocompleteItemIconState, AutocompleteItemProps, AutocompleteItemState, AutocompleteItemTextState, AutocompleteOpenChangeReason, AutocompleteOptions, AutocompletePrimitive, AutocompleteStatusState, AutocompleteSubmitDetails, AutocompleteTriggerState, AutocompleteValueChangeReason, ListAnnouncement, ListData, ListFilter, ListGroup, ListHighlightDetails, ListItem, ListSeparator, MatchSegment, SearchFilter, } from "@ui-sdk/core/autocomplete";
19
+ export type { AutocompleteApi, AutocompleteArrowState, AutocompleteChangeOptions, AutocompleteClearProps, AutocompleteClearState, AutocompleteContentProps, AutocompleteContentState, AutocompleteController, AutocompleteDismissReason, AutocompleteEmptyState, AutocompleteInputState, AutocompleteItemIconProps, AutocompleteItemIconState, AutocompleteItemProps, AutocompleteItemState, AutocompleteItemTextState, AutocompleteOpenChangeReason, AutocompleteOptions, AutocompletePrimitive, AutocompleteStatusState, AutocompleteSubmitDetails, AutocompleteTriggerState, AutocompleteValueChangeDetails, AutocompleteValueChangeReason, ListAnnouncement, ListData, ListFilter, ListGroup, ListHighlightDetails, ListItem, ListSeparator, MatchSegment, SearchFilter, } from "@ui-sdk/core/autocomplete";
@@ -144,7 +144,7 @@ list are its parts.
144
144
  /** Whether an item's value is the selected value, for object values that aren't the same object. */
145
145
  isItemEqualToValue?: (itemValue: T, value: T) => boolean
146
146
  /** Whether the first matching item is highlighted while typing, so Enter chooses it. `"always"` also highlights the selected item, or the first, when the list opens. */
147
- autoHighlight?: boolean | "always"
147
+ autoHighlight?: boolean | "always" | "selected"
148
148
  /** With `multiple`, whether the input keeps its text after an item is chosen. */
149
149
  keepQuery?: boolean
150
150
  /** What screen readers hear once the Create part's action has been pending for a second. An empty string says nothing. */
@@ -269,6 +269,8 @@ list are its parts.
269
269
  // more per value with `multiple`. The input's attributes change with the
270
270
  // value, so reading them keeps the list of values current.
271
271
  const formInput = useHandlePart(combobox, "form-input")
272
+ // A textarea's value is its text, which the server renders too.
273
+ const { value: formValue, ...formAttrs } = $derived(formInput.slot())
272
274
  const values = $derived(
273
275
  (formInput.attrs,
274
276
  combobox.state.multiple ? combobox.api.internal.serialized() : [])
@@ -279,7 +281,7 @@ list are its parts.
279
281
  {#if items && !own()}
280
282
  <ComboboxContent fromRoot />
281
283
  {/if}
282
- <input {...formInput.slot()} />
284
+ <textarea {...formAttrs}>{formValue}</textarea>
283
285
  {#each values as key (key)}
284
286
  <ValueInput owner={combobox} value={key} />
285
287
  {/each}
@@ -30,7 +30,7 @@ declare function $$render<T = string, Multiple extends boolean | undefined = fal
30
30
  /** Whether an item's value is the selected value, for object values that aren't the same object. */
31
31
  isItemEqualToValue?: (itemValue: T, value: T) => boolean;
32
32
  /** Whether the first matching item is highlighted while typing, so Enter chooses it. `"always"` also highlights the selected item, or the first, when the list opens. */
33
- autoHighlight?: boolean | "always";
33
+ autoHighlight?: boolean | "always" | "selected";
34
34
  /** With `multiple`, whether the input keeps its text after an item is chosen. */
35
35
  keepQuery?: boolean;
36
36
  /** What screen readers hear once the Create part's action has been pending for a second. An empty string says nothing. */
@@ -137,6 +137,8 @@ An always-visible list to choose one option from, or several with `multiple`.
137
137
  // more per value with `multiple`. The input's attributes change with the
138
138
  // value, so reading them keeps the list of values current.
139
139
  const formInput = useHandlePart(listbox, "form-input")
140
+ // A textarea's value is its text, which the server renders too.
141
+ const { value: formValue, ...formAttrs } = $derived(formInput.slot())
140
142
  const values = $derived(
141
143
  (formInput.attrs,
142
144
  listbox.state.multiple ? listbox.api.internal.serialized() : [])
@@ -153,7 +155,7 @@ An always-visible list to choose one option from, or several with `multiple`.
153
155
  part={wrapPart(root, control)}
154
156
  props={{ ...rest, children: children ?? data }}
155
157
  />
156
- <input {...formInput.slot()} />
158
+ <textarea {...formAttrs}>{formValue}</textarea>
157
159
  {#each values as key (key)}
158
160
  <ValueInput owner={listbox} value={key} />
159
161
  {/each}
@@ -31,6 +31,7 @@ A navigation landmark around the page links. Name it with `aria-label`.
31
31
  siblings,
32
32
  boundaries,
33
33
  getHref,
34
+ disabled,
34
35
  controller,
35
36
  debug,
36
37
  onPageChange,
@@ -52,6 +53,8 @@ A navigation landmark around the page links. Name it with `aria-label`.
52
53
  boundaries?: number
53
54
  /** The URL of a page. With it, parts are links that work before JavaScript loads. Without it, they're buttons. */
54
55
  getHref?: (page: number) => string
56
+ /** Whether every page and step does nothing, like a step at its end. A controller still pages it. */
57
+ disabled?: boolean
55
58
  /** Pages it from anywhere. Create one with `createPaginationController()`. */
56
59
  controller?: PaginationController
57
60
  /** Logs every change with its reason. */
@@ -73,6 +76,7 @@ A navigation landmark around the page links. Name it with `aria-label`.
73
76
  siblings,
74
77
  boundaries,
75
78
  getHref,
79
+ disabled,
76
80
  controller,
77
81
  debug,
78
82
  onPageChange: (next: number, details: Details) => {
@@ -19,6 +19,8 @@ type $$ComponentProps = PartProps<"nav", PaginationState> & {
19
19
  boundaries?: number;
20
20
  /** The URL of a page. With it, parts are links that work before JavaScript loads. Without it, they're buttons. */
21
21
  getHref?: (page: number) => string;
22
+ /** Whether every page and step does nothing, like a step at its end. A controller still pages it. */
23
+ disabled?: boolean;
22
24
  /** Pages it from anywhere. Create one with `createPaginationController()`. */
23
25
  controller?: PaginationController;
24
26
  /** Logs every change with its reason. */
@@ -2,4 +2,4 @@ export { default as SegmentedControl } from "./segmented-control/segmented-contr
2
2
  export { default as SegmentedControlIndicator } from "./segmented-control/segmented-control-indicator.svelte";
3
3
  export { default as SegmentedControlItem } from "./segmented-control/segmented-control-item.svelte";
4
4
  export { createSegmentedControlController } from "@ui-sdk/core/segmented-control";
5
- export type { SegmentedControlApi, SegmentedControlChangeOptions, SegmentedControlController, SegmentedControlIndicatorState, SegmentedControlItemProps, SegmentedControlItemState, SegmentedControlOptions, SegmentedControlOrientation, SegmentedControlPrimitive, SegmentedControlState, SegmentedControlValueChangeReason, } from "@ui-sdk/core/segmented-control";
5
+ export type { SegmentedControlApi, SegmentedControlChangeOptions, SegmentedControlController, SegmentedControlDirection, SegmentedControlIndicatorState, SegmentedControlItemProps, SegmentedControlItemState, SegmentedControlOptions, SegmentedControlOrientation, SegmentedControlPrimitive, SegmentedControlState, SegmentedControlValueChangeReason, } from "@ui-sdk/core/segmented-control";
@@ -253,6 +253,8 @@ Picks one value, or several with `multiple`, from a list in a popup.
253
253
  // more per value with `multiple`. The input's attributes change with the
254
254
  // value, so reading them keeps the list of values current.
255
255
  const formInput = useHandlePart(select, "form-input")
256
+ // A textarea's value is its text, which the server renders too.
257
+ const { value: formValue, ...formAttrs } = $derived(formInput.slot())
256
258
  const values = $derived(
257
259
  (formInput.attrs,
258
260
  select.state.multiple ? select.api.internal.serialized() : [])
@@ -263,7 +265,7 @@ Picks one value, or several with `multiple`, from a list in a popup.
263
265
  {#if items && !own()}
264
266
  <SelectContent fromRoot />
265
267
  {/if}
266
- <input {...formInput.slot()} />
268
+ <textarea {...formAttrs}>{formValue}</textarea>
267
269
  {#each values as key (key)}
268
270
  <ValueInput owner={select} value={key} />
269
271
  {/each}
@@ -11,6 +11,10 @@ const deliveries = new WeakMap();
11
11
  // Svelte starts a `transition:` or `out:` outro only once the core has
12
12
  // finished closing, so a close completes when those outros end.
13
13
  const exits = new WeakMap();
14
+ // Svelte runs an element's cleanup in the teardown of the effect removing it,
15
+ // where reading `current` runs it again and it stops following the props.
16
+ // Reads from such a cleanup get the options delivered last.
17
+ let tearingDown = 0;
14
18
  const memo = (compute) => {
15
19
  const value = $derived.by(compute);
16
20
  return () => value;
@@ -59,7 +63,8 @@ function usePrimitive(primitive, options) {
59
63
  // `value`, from here: a read sees it in the same update as the parent's own
60
64
  // state, before the effect below hands it over. Untracked, or every part
61
65
  // would hear every prop.
62
- const delivered = instance.follow(() => untrack(() => current));
66
+ let seen;
67
+ const delivered = instance.follow(() => tearingDown && seen ? seen : (seen = untrack(() => current)));
63
68
  // What the props changed in it, counted by the names parts read it by
64
69
  // (`followed`). Each part compares its own counts, so a value moving
65
70
  // between two of 500 items updates two. Both sides read the state held
@@ -277,7 +282,13 @@ function useHandlePart(owner, name, props = () => ({}), portal) {
277
282
  return () => {
278
283
  cleanups.forEach((cleanup) => cleanup());
279
284
  bound = undefined;
280
- ref(null);
285
+ tearingDown++;
286
+ try {
287
+ ref(null);
288
+ }
289
+ finally {
290
+ tearingDown--;
291
+ }
281
292
  restore();
282
293
  removed?.();
283
294
  removed = undefined;
@@ -294,7 +305,13 @@ function useHandlePart(owner, name, props = () => ({}), portal) {
294
305
  // element shows is what Svelte gets, so its write changes nothing.
295
306
  const styleFor = (merged) => {
296
307
  styleShown = merged;
297
- if (!bound || typeof merged !== "string") {
308
+ if (!bound) {
309
+ return merged;
310
+ }
311
+ // A style that goes away takes what it wrote with it, even when the owner
312
+ // left `style` out of its spread and Svelte writes nothing.
313
+ if (typeof merged !== "string") {
314
+ applyAttrs(bound, { style: undefined }, "svelte-style");
298
315
  return merged;
299
316
  }
300
317
  applyAttrs(bound, { style: merged }, "svelte-style");
package/docs/agents.md CHANGED
@@ -1014,7 +1014,7 @@ The snapshot lists the button with `confirm: "Charges $20 to your card for 1,000
1014
1014
  Needs a person: "Charges $20 to your card for 1,000 credits". Ask them to press "Buy credits" themselves.
1015
1015
  ```
1016
1016
 
1017
- With `allow`, the step waits for your callback, and `step.confirm` carries the sentence. Show it to the person and return their answer:
1017
+ With `allow`, the step waits for your callback, and `step.confirm` carries the sentence. A step that touches several marks, like replacing one marked option with another, carries every sentence, joined by semicolons. Show it to the person and return their answer:
1018
1018
 
1019
1019
  ```ts
1020
1020
  const agent = createAgent({
@@ -1051,7 +1051,7 @@ Two more marks change what the agent sees:
1051
1051
  </Field>
1052
1052
  ```
1053
1053
 
1054
- Changes inside `data-agent-hidden` still reach [Observe](./agents.md#observe-changes), so your own logs see them, while `agent.subscribe` stays quiet. A secret value stays out of `snapshot`, `act` results and change events, and the field's error text reads `"[redacted]"` too. Password, card and one-time-code fields are treated as secret without a mark. A hidden input is left out without one.
1054
+ Changes inside `data-agent-hidden` still reach [Observe](./agents.md#observe-changes), so your own logs see them, while `agent.subscribe` stays quiet. A secret value stays out of `snapshot`, `act` results and change events, and the field's error text reads `"[redacted]"` too. A secret File Input lists its files without their names. Password, card and one-time-code fields are treated as secret without a mark. A hidden input is left out without one.
1055
1055
 
1056
1056
  In development, a misspelled mark such as `data-agent-confim` logs a warning with the name it meant.
1057
1057
 
@@ -674,7 +674,7 @@ Dims the page behind the dialog. Renders a `div` and accepts its attributes and
674
674
  - `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.
675
675
  - `initialFocus?` (`DialogInitialFocus`): Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
676
676
  - `finalFocus?` (`PopupFocusTarget`): Where focus goes when the dialog closes while focus is inside it.
677
- - `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
677
+ - `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. Its content keeps its state between opens.
678
678
 
679
679
  ### AlertDialogTitle
680
680
 
@@ -746,7 +746,7 @@ Suggestions can change while the list is open. The highlight stays with its sugg
746
746
 
747
747
  ## Controlled
748
748
 
749
- The value is always a string. Control it with `value` and `onValueChange`, or start uncontrolled with `defaultValue`. Suggestions have a separate `open` state and `onOpenChange`. Callbacks receive the proposed value first, then change details. Call `details.cancel()` to reject a text or open change. [State and Events](../state-and-events.md) covers controlled state and cancellation.
749
+ The value is always a string. Control it with `value` and `onValueChange`, or start uncontrolled with `defaultValue`. Suggestions have a separate `open` state and `onOpenChange`. Callbacks receive the proposed value first, then change details. Call `details.cancel()` to reject a text or open change. When a suggestion is chosen, `details.item` holds its `value` and `label`, so suggestions that share a label can still be told apart. [State and Events](../state-and-events.md) covers controlled state and cancellation.
750
750
 
751
751
  ```svelte title="controlled.svelte"
752
752
  <script lang="ts">
@@ -1560,7 +1560,7 @@ to decide.
1560
1560
  - `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.
1561
1561
  - `value?` (`string`): The text. Pass it to control it.
1562
1562
  - `defaultValue?` (`string`): The text at first, when uncontrolled. A form reset returns to it.
1563
- - `onValueChange?` (`((value: string, details: ChangeDetails<AutocompleteValueChangeReason>) => void)`): Runs when the text wants to change: typing, choosing a suggestion, a Clear part, a form reset or a controller. `details.cancel()` keeps it as it was.
1563
+ - `onValueChange?` (`((value: string, details: AutocompleteValueChangeDetails) => void)`): Runs when the text wants to change: typing, choosing a suggestion, a Clear part, a form reset or a controller. `details.cancel()` keeps it as it was.
1564
1564
  - `open?` (`boolean`): Whether the suggestions are open. Pass it to control them.
1565
1565
  - `defaultOpen?` (`boolean`): Whether the suggestions start open, when uncontrolled.
1566
1566
  - `onOpenChange?` (`((open: boolean, details: ChangeDetails<AutocompleteOpenChangeReason>) => void)`): Runs when the suggestions want to open or close. `details.reason` says why, and `details.cancel()` stops it.
@@ -602,7 +602,7 @@ Choose a year and month to jump directly to a birthday, then choose the day.
602
602
 
603
603
  ## Custom Month and Year Selects
604
604
 
605
- The month and year selects are native `select` elements. To use your own select, control the calendar's `month` and drive it from your select's value, as with the [Select](./select.md) component here. Keep a `CalendarHeading` in the calendar, visually hidden if you like, so the grid stays named.
605
+ The month and year selects are native `select` elements. To use your own select, control the calendar's `month` and drive it from your select's value, as with the [Select](./select.md) component here. Keep a `CalendarHeading` in the calendar, visually hidden if you like, so a month change is still announced. Each grid names itself.
606
606
 
607
607
  ```svelte title="custom-select.svelte"
608
608
  <script lang="ts">
@@ -1465,7 +1465,7 @@ Renders the week rows. Its `children` snippet receives each cell, with its `date
1465
1465
  ### CalendarDay
1466
1466
 
1467
1467
  - `value` (`string`): Its ISO date.
1468
- - `offset?` (`number`): The offset of the grid it's in.
1468
+ - `offset?` (`number`): The offset of the grid it's in, read from that grid, so you don't pass it.
1469
1469
 
1470
1470
  ### State
1471
1471
 
@@ -509,6 +509,7 @@ Beyond the pattern's baseline:
509
509
 
510
510
  - Closing the panel while focus is inside it moves focus to the trigger.
511
511
  - OnOpenChangeComplete runs once the animation has finished.
512
+ - An inert its owner writes during the exit stays once the exit ends.
512
513
  - Find in page reports its own reason and opens without an animation.
513
514
  - A canceled find in page keeps the panel hidden until found.
514
515
  - An infinite exit animation still unmounts the panel.
@@ -333,7 +333,7 @@ Choose a framework, then press the clear button. The selection and text clear, f
333
333
 
334
334
  ## Auto Highlight
335
335
 
336
- Add `autoHighlight` to highlight the first match while typing, so Enter can choose it immediately. With `autoHighlight="always"`, opening the list also highlights the selected item, or the first, so the arrow keys move from there. A highlight it placed follows the list as items arrive, and one the user moved stays while its item is there.
336
+ Add `autoHighlight` to highlight the first match while typing, so Enter can choose it immediately. With `autoHighlight="always"`, opening the list also highlights the selected item, or the first, so the arrow keys move from there. `autoHighlight="selected"` highlights only the selected item when the list opens, and nothing when none is. A highlight it placed follows the list as items arrive, and one the user moved stays while its item is there.
337
337
 
338
338
  ```svelte title="auto-highlight.svelte"
339
339
  <script lang="ts">
@@ -2869,7 +2869,7 @@ Props and callbacks are the same as below, as Svelte props. `value`, `query` and
2869
2869
  - `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`.
2870
2870
  - `itemToLabel?` (`((value: T) => string)`): The text a value shows, for values whose item isn't rendered, like async results.
2871
2871
  - `isItemEqualToValue?` (`((itemValue: T, value: T) => boolean)`): Whether an item's value is the selected value, for object values that aren't the same object.
2872
- - `autoHighlight?` (`"always" | boolean`): Whether the first matching item is highlighted while typing, so Enter chooses it. `"always"` also highlights the selected item, or the first, when the list opens, so arrows move from there.
2872
+ - `autoHighlight?` (`"always" | "selected" | boolean`): Whether the first matching item is highlighted while typing, so Enter chooses it. `"always"` also highlights the selected item, or the first, when the list opens, so arrows move from there. `"selected"` highlights only the selected item when the list opens, and nothing when none is.
2873
2873
  - `keepQuery?` (`boolean`): With `multiple`, whether the input keeps its text after an item is chosen.
2874
2874
  - `pendingAnnouncement?` (`string`): What screen readers hear once the Create part's `onCreate` has been pending for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
2875
2875
  - `allowCustomValue?` (`boolean`): Whether text that matches no item becomes the value, when Enter is pressed with nothing highlighted, or, without `multiple`, when the list closes. The value is the text itself.
@@ -2918,7 +2918,7 @@ Holds the chips and the input for a multiple selection. Renders a `div`.
2918
2918
 
2919
2919
  ### ComboboxValue
2920
2920
 
2921
- - `maxLabels?` (`number`): With `multiple`, how many labels the `label` in its state shows before the rest are counted, as in "France, Chile and 2 more", joined the way the page's language joins lists.
2921
+ - `maxLabels?` (`number`): With `multiple`, how many labels the `label` in its state shows before the rest are counted, as in "France, Chile and 2 more", joined the way the page's language joins lists, or in English with the default `getMoreLabel`.
2922
2922
  - `getMoreLabel?` (`((count: number) => string)`): The words for the labels past `maxLabels`.
2923
2923
 
2924
2924
  ### ComboboxChip
@@ -1399,6 +1399,7 @@ The first available command is highlighted by default. Set `autoHighlight` to `f
1399
1399
  **Field**
1400
1400
 
1401
1401
  - Is a combobox that controls an always-expanded listbox.
1402
+ - The list is named by the field, not by what's typed.
1402
1403
  - The first command is highlighted from the start.
1403
1404
 
1404
1405
  **Filtering**
@@ -508,6 +508,7 @@ Every line below is an automated test.
508
508
  - A canceled change keeps the date.
509
509
  - The form submits the ISO date and time under their names.
510
510
  - Enter submits the form with what was typed.
511
+ - Enter submits a form with no submit button, in a segment or the form's one text field.
511
512
  - Resetting the form brings back the default date.
512
513
  - A partly filled date can't be submitted.
513
514
  - A required empty date can't be submitted.
@@ -1122,7 +1122,7 @@ Clears the value and focuses the input. Renders a `button`.
1122
1122
  - `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.
1123
1123
  - `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.
1124
1124
  - `finalFocus?` (`PopupFocusTarget`): Where focus goes when the popup closes while focus is inside it.
1125
- - `keepMounted?` (`boolean`): Whether the popup stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
1125
+ - `keepMounted?` (`boolean`): Whether the popup stays in the page, hidden, while closed. Its content keeps its state between opens.
1126
1126
  ### DatePickerPreset
1127
1127
 
1128
1128
  - `value` (`DatePickerValue`): The value it selects: an ISO date, or `[start, end]` in range mode.
@@ -1069,7 +1069,7 @@ Dims the page behind a modal dialog. Renders a `div`.
1069
1069
  - `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
1070
  - `initialFocus?` (`DialogInitialFocus`): Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
1071
1071
  - `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.
1072
+ - `keepMounted?` (`boolean`): Whether the dialog stays in the page, hidden, while closed. Its content keeps its state between opens.
1073
1073
 
1074
1074
  ### DialogTitle
1075
1075
 
@@ -1209,6 +1209,7 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1209
1209
  - Tab moves through the dialog in order.
1210
1210
  - Tab from the last element wraps to the first.
1211
1211
  - Shift+Tab from the first element wraps to the last.
1212
+ - … from inside an iframe that is the … element wraps around the dialog.
1212
1213
  - Shift+Tab from the first element wraps to the checked radio of a group outside a form.
1213
1214
  - Tab reaches radios whose group's checked radio is behind the dialog.
1214
1215
  - Tab visits a positive tabindex first, like the browser.
@@ -1217,8 +1218,12 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1217
1218
  - With a positive tabindex in the dialog, Tab still moves through a shadow root and slots.
1218
1219
  - With a positive tabindex in the dialog, Tab from a focused element outside the tab order goes to the next stop.
1219
1220
  - Tab from a custom element with a positive tabindex enters its shadow root.
1221
+ - Tab from a last control inside a shadow root wraps to the first, and Shift+Tab comes back to it.
1222
+ - Tab wraps past a shadow root that Tab skips, under an inert or tabindex -1 host.
1223
+ - Tab wraps from the last stop of a shadow root that orders a positive tabindex first.
1220
1224
  - Opening focuses the first field even when a later one has a positive tabindex.
1221
1225
  - Escape closes the dialog and returns focus to the trigger.
1226
+ - An ancestor hears Escape already handled.
1222
1227
  - Escape after a click returns focus to the trigger.
1223
1228
  - The close button closes the dialog and returns focus to the trigger.
1224
1229
  - A virtual click from a screen reader moves focus into the dialog.
@@ -1229,6 +1234,7 @@ The trigger is a button that opens a dialog, and the dialog follows the [WAI-ARI
1229
1234
 
1230
1235
  - Pressing the backdrop closes the dialog.
1231
1236
  - Pressing the backdrop returns focus to the trigger.
1237
+ - After pressing the backdrop, Space on the trigger opens it again.
1232
1238
  - Clicking inside the dialog keeps it open.
1233
1239
  - An outside press doesn't reach the page.
1234
1240
 
@@ -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.
@@ -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. 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.
362
362
 
363
363
  ### HoverCardArrow
364
364
 
@@ -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. 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.
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">
@@ -1233,7 +1233,7 @@ A trigger outside the popover also takes `controller`.
1233
1233
  - `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
1234
  - `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
1235
  - `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. For animation libraries that drive the exit from state.
1236
+ - `keepMounted?` (`boolean`): Whether the popover stays in the page, hidden, while closed. Its content keeps its state between opens.
1237
1237
 
1238
1238
  ### PopoverArrow
1239
1239
 
@@ -1362,6 +1362,7 @@ Every line below is an automated test.
1362
1362
  - Tab from the last element moves focus to the element after the trigger.
1363
1363
  - Focus leaving the popover closes it.
1364
1364
  - Escape closes the popover and returns focus to the trigger.
1365
+ - An ancestor hears Escape already handled.
1365
1366
  - Escape after a click returns focus to the trigger.
1366
1367
  - The close button closes the popover and returns focus to the trigger.
1367
1368
  - 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.
@@ -1658,7 +1658,7 @@ A trigger outside the select also takes `controller`.
1658
1658
  ### SelectValue
1659
1659
 
1660
1660
  - `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.
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, or in English with the default `getMoreLabel`.
1662
1662
  - `getMoreLabel?` (`((count: number) => string)`): The words for the labels past `maxLabels`.
1663
1663
 
1664
1664
  ### SelectContent
@@ -1672,7 +1672,7 @@ A trigger outside the select also takes `controller`.
1672
1672
  - `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
1673
  - `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
1674
  - `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. For animation libraries that drive the exit from state.
1675
+ - `keepMounted?` (`boolean`): Whether the list stays in the page, hidden, while closed. Its content keeps its state between opens.
1676
1676
 
1677
1677
  ### SelectItem
1678
1678
 
@@ -1902,6 +1902,7 @@ Every line below is an automated test.
1902
1902
  - Enter chooses the focused item, closes and returns focus to the trigger.
1903
1903
  - Space chooses the focused item.
1904
1904
  - Escape closes without choosing and returns focus to the trigger.
1905
+ - An ancestor hears Escape already handled.
1905
1906
  - The chosen item is selected when the list opens again, and takes focus.
1906
1907
 
1907
1908
  **Typing on the closed trigger**
@@ -1939,6 +1940,7 @@ Every line below is an automated test.
1939
1940
  **Forms**
1940
1941
 
1941
1942
  - The form submits the value under the select's name.
1943
+ - Enter in the form's one text field submits it, with no submit button.
1942
1944
  - A required select blocks submission until a value is chosen.
1943
1945
  - A disabled select can't be opened.
1944
1946
  - A read-only select doesn't change its value.
@@ -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 | Default |
1370
- | ----------- | ------------------------------------------------------- | ------- |
1371
- | `debounce` | Milliseconds typing must pause before a request starts. | `200` |
1372
- | `query` | The starting search text. | `""` |
1373
- | `immediate` | Loads that text as soon as the component mounts. | `false` |
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>`:
@@ -171,11 +171,12 @@ Use `ComboboxStatus` and `ComboboxEmpty` to show loading, error, and empty messa
171
171
 
172
172
  The second argument sets the starting behavior:
173
173
 
174
- | Option | What It Does | Default |
175
- | ----------- | ------------------------------------------------------- | ------- |
176
- | `debounce` | Milliseconds typing must pause before a request starts. | `200` |
177
- | `query` | The starting search text. | `""` |
178
- | `immediate` | Loads that text as soon as the component mounts. | `false` |
174
+ | Option | What It Does | Default |
175
+ | ----------- | ------------------------------------------------------------------------------- | ------- |
176
+ | `debounce` | Milliseconds typing must pause before a request starts. | `200` |
177
+ | `query` | The starting search text. | `""` |
178
+ | `immediate` | Loads that text as soon as the component mounts. | `false` |
179
+ | `minLength` | Characters the text needs before anything loads. Shorter text clears the items. | `0` |
179
180
 
180
181
  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`.
181
182
 
@@ -69,7 +69,7 @@ Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` f
69
69
 
70
70
  ## While Someone Is Typing
71
71
 
72
- 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.
72
+ 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.
73
73
 
74
74
  ## Limit a Shortcut to an Area
75
75
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ui-sdk/svelte",
3
- "version": "0.1.0-beta.7",
3
+ "version": "0.1.0-beta.8",
4
4
  "description": "UI SDK for Svelte.",
5
5
  "keywords": [
6
6
  "svelte",
@@ -381,7 +381,7 @@
381
381
  ],
382
382
  "peerDependencies": {
383
383
  "svelte": ">=5.33",
384
- "@ui-sdk/core": "^0.1.0-beta.7"
384
+ "@ui-sdk/core": "^0.1.0-beta.8"
385
385
  },
386
386
  "devDependencies": {
387
387
  "@sveltejs/package": "^2.5.8",
@@ -393,7 +393,7 @@
393
393
  "typescript": "~5.9.3",
394
394
  "vite": "^8.3.3",
395
395
  "vitest": "^5.0.3",
396
- "@ui-sdk/core": "0.1.0-beta.7"
396
+ "@ui-sdk/core": "0.1.0-beta.8"
397
397
  },
398
398
  "scripts": {
399
399
  "build": "node ../../scripts/build/build-svelte-package.mjs",