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

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 +84 -21
  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 +4 -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 +102 -24
  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
@@ -10,9 +10,10 @@ The button that opens the list: a combobox named by the label. Typing on it sele
10
10
  type SelectTriggerState,
11
11
  } from "@ui-sdk/core/select"
12
12
  import { getContext } from "svelte"
13
+ import { useFieldControl } from "../field/context.js"
13
14
  import Part from "../part.svelte"
14
15
  import { useControllerTarget } from "../popup.svelte.js"
15
- import { plainPart, type PartProps } from "../use-primitive.svelte.js"
16
+ import { plainPart, wrapPart, type PartProps } from "../use-primitive.svelte.js"
16
17
  import type { SelectContext } from "./context.js"
17
18
  import TriggerBinding from "./select-trigger-binding.svelte"
18
19
 
@@ -27,23 +28,30 @@ The button that opens the list: a combobox named by the label. Typing on it sele
27
28
  getContext<SelectContext | undefined>(selectPrimitive)
28
29
  )
29
30
  const select = $derived(connected())
31
+ const control = useFieldControl()?.control(
32
+ () => rest.id as string | undefined,
33
+ () => rest["aria-describedby"]
34
+ )
30
35
  </script>
31
36
 
32
37
  {#if select}
33
- <TriggerBinding owner={select} {disabled} {...rest} />
38
+ <TriggerBinding owner={select} {control} {disabled} {...rest} />
34
39
  {:else}
35
40
  <!-- Until the select it names mounts, a trigger outside the select is a plain button. -->
36
41
  <Part
37
42
  tag="button"
38
- part={plainPart(
39
- {
40
- open: false,
41
- disabled: !!disabled,
42
- readOnly: false,
43
- required: false,
44
- placeholder: true,
45
- },
46
- { type: "button" }
43
+ part={wrapPart(
44
+ plainPart(
45
+ {
46
+ open: false,
47
+ disabled: !!disabled,
48
+ readOnly: false,
49
+ required: false,
50
+ placeholder: true,
51
+ },
52
+ { type: "button" }
53
+ ),
54
+ control
47
55
  )}
48
56
  props={rest}
49
57
  />
@@ -92,6 +92,7 @@ Picks one value, or several with `multiple`, from a list in a popup.
92
92
  itemToLabel,
93
93
  isItemEqualToValue,
94
94
  loop,
95
+ virtualFocus,
95
96
  modal,
96
97
  presentation,
97
98
  disabled,
@@ -141,6 +142,8 @@ Picks one value, or several with `multiple`, from a list in a popup.
141
142
  isItemEqualToValue?: (itemValue: T, value: T) => boolean
142
143
  /** Whether arrow keys wrap from the last item to the first. */
143
144
  loop?: boolean
145
+ /** Keeps focus on the trigger while the list is open, which points at the highlighted item. */
146
+ virtualFocus?: boolean
144
147
  /** Whether the page behind the list is inert, or only shielded from the pointer. */
145
148
  modal?: boolean | "pointer"
146
149
  /** How the list presents: a popover, a sheet, or `"auto"` for a sheet on small touch screens. */
@@ -210,6 +213,7 @@ Picks one value, or several with `multiple`, from a list in a popup.
210
213
  itemToLabel,
211
214
  isItemEqualToValue,
212
215
  loop,
216
+ virtualFocus,
213
217
  modal,
214
218
  presentation,
215
219
  disabled: disabled || field?.disabled(),
@@ -253,6 +257,8 @@ Picks one value, or several with `multiple`, from a list in a popup.
253
257
  // more per value with `multiple`. The input's attributes change with the
254
258
  // value, so reading them keeps the list of values current.
255
259
  const formInput = useHandlePart(select, "form-input")
260
+ // A textarea's value is its text, which the server renders too.
261
+ const { value: formValue, ...formAttrs } = $derived(formInput.slot())
256
262
  const values = $derived(
257
263
  (formInput.attrs,
258
264
  select.state.multiple ? select.api.internal.serialized() : [])
@@ -263,7 +269,7 @@ Picks one value, or several with `multiple`, from a list in a popup.
263
269
  {#if items && !own()}
264
270
  <SelectContent fromRoot />
265
271
  {/if}
266
- <input {...formInput.slot()} />
272
+ <textarea {...formAttrs}>{formValue}</textarea>
267
273
  {#each values as key (key)}
268
274
  <ValueInput owner={select} value={key} />
269
275
  {/each}
@@ -33,6 +33,8 @@ declare function $$render<T = string, Multiple extends boolean | undefined = fal
33
33
  isItemEqualToValue?: (itemValue: T, value: T) => boolean;
34
34
  /** Whether arrow keys wrap from the last item to the first. */
35
35
  loop?: boolean;
36
+ /** Keeps focus on the trigger while the list is open, which points at the highlighted item. */
37
+ virtualFocus?: boolean;
36
38
  /** Whether the page behind the list is inert, or only shielded from the pointer. */
37
39
  modal?: boolean | "pointer";
38
40
  /** How the list presents: a popover, a sheet, or `"auto"` for a sheet on small touch screens. */
@@ -24,7 +24,8 @@ declare function useShortcut(keys: MaybeGetter<string | null | undefined>, handl
24
24
  * Keys formatted for this platform, like `⌘S` on Apple platforms and `Ctrl+S`
25
25
  * elsewhere, with the matching `aria-keyshortcuts`, as reactive getters. The
26
26
  * server and the first client render use the same platform, so hydration
27
- * matches, and they update after mount. Keys can be a getter.
27
+ * matches, and they update after mount. Keys can be a getter. The text is
28
+ * wrapped in a left-to-right isolate, like `formatShortcut`'s.
28
29
  * @stable
29
30
  */
30
31
  declare function useShortcutHint(keys: MaybeGetter<string>): {
@@ -25,7 +25,8 @@ function useShortcut(keys, handler, options = {}) {
25
25
  * Keys formatted for this platform, like `⌘S` on Apple platforms and `Ctrl+S`
26
26
  * elsewhere, with the matching `aria-keyshortcuts`, as reactive getters. The
27
27
  * server and the first client render use the same platform, so hydration
28
- * matches, and they update after mount. Keys can be a getter.
28
+ * matches, and they update after mount. Keys can be a getter. The text is
29
+ * wrapped in a left-to-right isolate, like `formatShortcut`'s.
29
30
  * @stable
30
31
  */
31
32
  function useShortcutHint(keys) {
@@ -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
@@ -77,16 +77,62 @@ You can give these tools to your own agent, or register them with a supported br
77
77
 
78
78
  ## Benchmark
79
79
 
80
- In a project-settings benchmark, agents renamed a project, updated members and notification settings, then saved. One used browser tools on a page built with another component library; the other used the agent bridge on the same screen built with ui-sdk.
80
+ We gave an agent one task on a project settings screen: rename the project, change its visibility, update two members and the notification settings, then save. We built the same screen with ui-sdk and with other component libraries, in React, Vue and Svelte.
81
81
 
82
- | | Browser tools | ui-sdk + agent bridge | Delta |
83
- | ---------- | ------------- | --------------------- | ----- |
84
- | Tool calls | 16 | **5** | −69% |
85
- | Text read | 39.8k | **6.8k** | −83% |
86
- | Time | 41 s | **16 s** | −61% |
87
- | Cost | $0.073 | **$0.032** | −56% |
82
+ On the other libraries, the agent used browser tools: it reads the page's accessibility tree, then clicks and types. On ui-sdk, it used the agent bridge.
88
83
 
89
- These are medians from three runs per approach. Both agents used Sonnet through Claude Code with the same task and system prompt, plus instructions for their available tools. Every run completed the task. Text read counts characters returned by the tools. Time and cost are what Claude Code reported for those runs.
84
+ ### React
85
+
86
+ | | Base UI + browser tools | Ark UI + browser tools | ui-sdk + agent bridge | Delta |
87
+ | ---------- | ----------------------- | ---------------------- | --------------------- | ----------- |
88
+ | Tool calls | 17 | 19 | **7** | 59% fewer |
89
+ | Tokens | 291.7k | 330.9k | **69.5k** | 76% fewer |
90
+ | Time | 53 s | 65 s | **31 s** | 41% faster |
91
+ | Cost | $0.139 | $0.144 | **$0.044** | 68% cheaper |
92
+
93
+ ### Vue
94
+
95
+ | | Reka UI + browser tools | ui-sdk + agent bridge | Delta |
96
+ | ---------- | ----------------------- | --------------------- | ----------- |
97
+ | Tool calls | 16 | **9** | 44% fewer |
98
+ | Tokens | 226.5k | **90.2k** | 60% fewer |
99
+ | Time | 56 s | **34 s** | 39% faster |
100
+ | Cost | $0.113 | **$0.051** | 55% cheaper |
101
+
102
+ ### Svelte
103
+
104
+ | | Bits UI + browser tools | ui-sdk + agent bridge | Delta |
105
+ | ---------- | ----------------------- | --------------------- | ----------- |
106
+ | Tool calls | 17 | **8** | 53% fewer |
107
+ | Tokens | 259.1k | **92.8k** | 64% fewer |
108
+ | Time | 56 s | **30 s** | 45% faster |
109
+ | Cost | $0.123 | **$0.056** | 54% cheaper |
110
+
111
+ These are medians from three runs per column. Every agent used Sonnet through Claude Code with the same task and system prompt, plus instructions for its tools. Every run completed the task. Time runs from the agent's start to its last message. Tokens and cost are what Claude Code reported for the run. Delta compares ui-sdk with the best other result in the row.
112
+
113
+ We also ran the ui-sdk screen with browser tools. It took about as much as the other libraries, so the difference comes from the tools.
114
+
115
+ ### Run It Yourself
116
+
117
+ The benchmark is in the repo, in [`benchmarks/agent`](https://github.com/vercel-labs/ui/tree/main/benchmarks/agent). It runs its agents with [Claude Code](https://claude.com/claude-code), so install it and sign in first.
118
+
119
+ ```sh
120
+ git clone https://github.com/vercel-labs/ui
121
+ cd ui
122
+ pnpm install
123
+ pnpm exec playwright install chromium
124
+ pnpm --filter agent-benchmark bench
125
+ ```
126
+
127
+ This opens every version of the React screen in its own browser window and starts one agent in each. When they finish, it prints a table with each run's tool calls, text read, time, tokens and cost, and whether the agent saved the right settings.
128
+
129
+ Pass `--framework vue` or `--framework svelte` for the other frameworks, and `--runs 3` for medians:
130
+
131
+ ```sh
132
+ pnpm --filter agent-benchmark bench --framework vue --runs 3
133
+ ```
134
+
135
+ The [README](https://github.com/vercel-labs/ui/tree/main/benchmarks/agent#readme) explains the task, what's measured, and how to add another library.
90
136
 
91
137
  ## Where to Start
92
138
 
@@ -170,7 +216,7 @@ The [Core guides](./core.md#build-a-component) walk through the code. [All Behav
170
216
  If your agent supports skills, install `ui-sdk`:
171
217
 
172
218
  ```bash
173
- npx skills add vercel-labs/ui --skill ui-sdk
219
+ npx skills@latest add vercel-labs/ui --skill ui-sdk
174
220
  ```
175
221
 
176
222
  It gives the agent a workflow for choosing behaviors, defining a primitive, rendering it and testing it. The same skill ships with `@ui-sdk/core` in `node_modules/@ui-sdk/core/skills/`, so an agent without skills can read it there. [Skills](./agents.md#skills) shows how to use it. You can also work directly from the docs.
@@ -288,7 +334,7 @@ Help your agent build custom components with @ui-sdk/core.
288
334
  If your agent supports skills, install it with:
289
335
 
290
336
  ```bash
291
- npx skills add vercel-labs/ui --skill ui-sdk
337
+ npx skills@latest add vercel-labs/ui --skill ui-sdk
292
338
  ```
293
339
 
294
340
  The skill also ships inside `@ui-sdk/core`, at `node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md`. That copy always matches the version you installed. If your agent doesn't support skills, point it there instead.
@@ -410,10 +456,14 @@ Put several steps in one call to run them in order. If a step fails, `result.ok`
410
456
  For components with choices, such as a Select or Combobox, `query` with `within` lists the available values. For a Select labeled **Region**:
411
457
 
412
458
  ```ts
413
- const [region] = await agent.query({ within: "Region", text: "Europe" })
459
+ const found = await agent.query({ within: "Region", text: "Europe" })
460
+ if ("error" in found) {
461
+ throw new Error(found.error)
462
+ }
463
+ const [region] = found
414
464
  ```
415
465
 
416
- `region.items` holds up to 50 matching choices, each with a `value` and `label`, and `region.more` says how many matched beyond that. Leave out `text` to list the first 50. Depending on how the component supplies its items, the bridge may briefly open it to read them.
466
+ `query` returns `{ error }` when nothing on the page is named **Region**. Otherwise `region.items` holds up to 50 matching choices, each with a `value` and `label`, and `region.more` says how many matched beyond that. Leave out `text` to list the first 50. `query()` never opens anything. When a list's items only show while it's open, `items` is empty and `note` says so.
417
467
 
418
468
  `query` also finds components without listing the page. `agent.query({ text: "Europe" })` returns the components whose label or row text has that word, and lists whose choices match, with those choices under them. `kind` keeps one kind, such as `"select"`.
419
469
 
@@ -777,6 +827,7 @@ Here's the rating's primitive. Its API has one method, `rate`:
777
827
  ```ts title="rating.ts"
778
828
  const rating = definePrimitive({
779
829
  name: "rating",
830
+ options: { defaultValue: "number" },
780
831
  state: (options: { defaultValue?: number }) => ({
781
832
  value: options.defaultValue ?? 0,
782
833
  }),
@@ -946,7 +997,7 @@ For your own confirmation UI, return a `Promise<boolean>` that resolves with the
946
997
 
947
998
  ## Mark What Needs a Person
948
999
 
949
- Some controls should always wait for the person, whatever your `allow` rules say. Add `data-agent-confirm` with a sentence that says what the control does:
1000
+ Some controls should always wait for the person. Add `data-agent-confirm` with a sentence that says what the control does:
950
1001
 
951
1002
  ```tsx
952
1003
  <Button
@@ -963,7 +1014,7 @@ The snapshot lists the button with `confirm: "Charges $20 to your card for 1,000
963
1014
  Needs a person: "Charges $20 to your card for 1,000 credits". Ask them to press "Buy credits" themselves.
964
1015
  ```
965
1016
 
966
- 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:
967
1018
 
968
1019
  ```ts
969
1020
  const agent = createAgent({
@@ -974,8 +1025,12 @@ const agent = createAgent({
974
1025
 
975
1026
  If the person says no, the step fails with `The person said no to "…"`.
976
1027
 
1028
+ An `allow` that returns `true` without reading `step.confirm` answers yes for the person. Check it in every `allow` you write, including the one you pass to [`registerTools`](./agents.md#webmcp).
1029
+
977
1030
  The mark covers its element and everything inside it, for any action. Put it on a form or section to cover every control in it, or on a dialog's content to cover the buttons inside, wherever the dialog renders.
978
1031
 
1032
+ A mark on one option of a Select or Combobox counts even while the list is closed, since the agent opens it for a moment to look. A list that renders only some of its options, like a virtualized one, or one filtered by text in its field, shows the agent only those. Mark something that stays on the page instead, like its trigger or a wrapper around it, and every choice in it waits for the person.
1033
+
979
1034
  ## Keep Parts of the Page from the Agent
980
1035
 
981
1036
  Two more marks change what the agent sees:
@@ -996,7 +1051,7 @@ Two more marks change what the agent sees:
996
1051
  </Field>
997
1052
  ```
998
1053
 
999
- 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.
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.
1000
1055
 
1001
1056
  In development, a misspelled mark such as `data-agent-confim` logs a warning with the name it meant.
1002
1057
 
@@ -1024,7 +1079,7 @@ Put value checks in these change callbacks. Actions such as `setValue` call the
1024
1079
 
1025
1080
  `allow` checks actions. Components and their actions remain visible in `snapshot()`, and the agent can still read choices with `query()`. Use `data-agent-hidden` to keep a region out of view.
1026
1081
 
1027
- Finding a component or its choices can open a section or popup before the requested action is checked. `query()` may also briefly open a popup to read its choices. Use the component's `onOpenChange` or equivalent callback if you need to reject those changes too.
1082
+ Finding a component or its choices can open a section or popup before the requested action is checked. Use the component's `onOpenChange` or equivalent callback if you need to reject those changes too.
1028
1083
 
1029
1084
  The [Reference](./agents.md#reference) lists the fields passed to `allow` and the results returned by `act`.
1030
1085
 
@@ -1265,7 +1320,9 @@ const unregister = registerTools(agent, {
1265
1320
  })
1266
1321
  ```
1267
1322
 
1268
- The browser's agent can now read components and call their actions. You didn't write that agent, so `registerTools` asks for an `allow` of its own. It runs for every step the browser's agent asks for, after your bridge's [permissions](./agents.md#permissions), and works the same way: return `false` to refuse a step. Here it asks you before every press. To let every step run, pass `allow: () => true`. Your change callbacks still apply.
1323
+ The browser's agent can now read components and call their actions. You didn't write that agent, so `registerTools` asks for an `allow` of its own. It runs for every step the browser's agent asks for, after your bridge's [permissions](./agents.md#permissions), and works the same way: return `false` to refuse a step. Here it asks you before every press. Your change callbacks still apply.
1324
+
1325
+ A step on a control you marked with [`data-agent-confirm`](./agents.md#mark-what-needs-a-person) arrives with `step.confirm`, and this `allow` answers for the person. To let every other step run and leave those to the person, pass `allow: (step) => !step.confirm`.
1269
1326
 
1270
1327
  Registration requires a browser that provides `document.modelContext.registerTool`. In a browser without it, `registerTools` does nothing.
1271
1328
 
@@ -1283,6 +1340,8 @@ This removes the browser tools. You can still call methods on `agent` directly.
1283
1340
 
1284
1341
  `snapshot` and `query` have `readOnlyHint: true`. All three tools have `untrustedContentHint: true` because their results include page content, such as labels and text people entered.
1285
1342
 
1343
+ `act` has `consequentialHint: true` because a step can press any button, including one whose action can't be undone. A browser can use it to ask the person before it runs `act`.
1344
+
1286
1345
  These are hints for the tool consumer. `snapshot` and `query` never open a component. Use [Permissions](./agents.md#permissions) to decide which requested actions your app accepts.
1287
1346
 
1288
1347
 
@@ -1376,7 +1435,7 @@ Each step is an `AgentStep`:
1376
1435
 
1377
1436
  Use a specific ref when a name is ambiguous. A step can reach a component revealed by an earlier step. The bridge can also look for a target inside closed accordion sections.
1378
1437
 
1379
- For choices, an argument can be the item's value or its label. Labels match regardless of case and accents, like component names; values match exactly. Ambiguous item labels are refused. When a list's items show only while it's open, `setValue` with a label asks `allow` with the label before it opens the list to read them, then again with the item's value. Numeric `setValue` actions also accept text that starts with a number, such as `"90 days"`.
1438
+ For choices, an argument can be the item's value or its label. Labels match regardless of case and accents, like component names; values match exactly. Ambiguous item labels are refused. When a list's items show only while it's open, `setValue` with a label asks `allow` with the label before it opens the list to read them, then again with the item's value. Numeric `setValue` actions also accept text that starts with a number, such as `"90 days"`. Text with grouped digits, such as `"1,499.5"`, is refused. A component that holds a list, such as a multiple Select, takes one value or label as a list of one.
1380
1439
 
1381
1440
  A `set` action's first argument is checked against the kind of the option it sets in the primitive's schema, like `setChecked` against `checked`. A `"boolean"` option takes only `true` or `false`, a `"number"` option takes a number or text that is one, like `"3"`, and an option read by an attribute parser takes what that parser reads, so a resizable group takes `"30,70"` as its layout but a checkbox refuses `"yes"`. A value the kind doesn't take fails the step, with the type it expects, and changes nothing.
1382
1441
 
@@ -1401,7 +1460,7 @@ The bridge tries these in order and uses the first that fits:
1401
1460
 
1402
1461
  Names match regardless of case and accents, so `"Region"` finds "Région" and `"strasse"` finds "Straße".
1403
1462
 
1404
- When a name fits more than one component, the step fails and lists each one's ref, label and row text, such as `"Jane Doe" names 2 components: c1 Admin (Jane Doe), c4 Jane Doe. Use a ref.` Retry the step with one of those refs. That holds even when one label matches exactly, since labels and rows are page text anyone can write, like a person's display name. If exactly one of them takes the step's action, like a Textarea and the Trigger Menu on the same field for `setValue`, the step uses that one. Otherwise, if exactly one of them is an open popup, the step uses that one.
1463
+ When a name fits more than one component, the step fails and lists each one's ref, label and row text, such as `"Jane Doe" names 2 components: c1 Admin (Jane Doe), c4 Jane Doe. Use a ref.`, then a hint for whoever builds the page. Retry the step with one of those refs. That holds even when one label matches exactly, since labels and rows are page text anyone can write, like a person's display name. On your own page, two labels that share their words, like a "Technician" filter and a "Technician" field, each name their component once one has a word the other lacks. If exactly one of them takes the step's action, like a Textarea and the Trigger Menu on the same field for `setValue`, the step uses that one. Otherwise, if exactly one of them is an open popup, the step uses that one.
1405
1464
 
1406
1465
  A returning component can reuse a remembered ref when its kind, label, and row text match. The bridge remembers refs for the last 500 that left. Identical components receive remembered refs in the order they return. Read a fresh snapshot after reordering or renaming components instead of assuming each ref still names the same control.
1407
1466
 
@@ -1429,7 +1488,11 @@ A failed step stops the call. Earlier steps stay applied; there is no rollback.
1429
1488
  Finds components and their choices without listing the page, and returns a promise:
1430
1489
 
1431
1490
  ```ts
1432
- const [region] = await agent.query({ within: "Region", text: "Europe" })
1491
+ const found = await agent.query({ within: "Region", text: "Europe" })
1492
+ if ("error" in found) {
1493
+ throw new Error(found.error)
1494
+ }
1495
+ const [region] = found
1433
1496
  ```
1434
1497
 
1435
1498
  | Input | What It Does |
@@ -1487,7 +1550,7 @@ const unregister = registerTools(agent, {
1487
1550
  })
1488
1551
  ```
1489
1552
 
1490
- `allow` is required. It decides each step the browser's agent asks for, after the bridge's own `allow`, and works the same way: return `false` to refuse the step, or `true` to let every step run. It returns a cleanup function. In a browser without WebMCP, registration does nothing. See [WebMCP](./agents.md#webmcp) for registration, cleanup, and tool annotations.
1553
+ `allow` is required. It decides each step the browser's agent asks for, after the bridge's own `allow`, and works the same way: return `false` to refuse the step, or `true` to let it run. A step with `confirm` is one you marked for a person, and `true` answers for them. It returns a cleanup function. In a browser without WebMCP, registration does nothing. See [WebMCP](./agents.md#webmcp) for registration, cleanup, and tool annotations.
1491
1554
 
1492
1555
  ## Custom Primitives
1493
1556
 
@@ -674,7 +674,8 @@ 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
+ - `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.
678
679
 
679
680
  ### AlertDialogTitle
680
681
 
@@ -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">
@@ -1506,6 +1506,8 @@ While focus stays in the input, use the content’s `data-modality="keyboard"` w
1506
1506
  - `data-open`: Present while the suggestions are open.
1507
1507
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
1508
1508
  - `data-ending-style`: Present while the list animates out. Style the state you animate to.
1509
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the suggestions ended up, after flipping away from edges.
1510
+ - `data-align` (`start`, `center`, `end`): How the suggestions line up with the field.
1509
1511
  - `data-modality` (`keyboard`, `pointer`): Whether the keyboard or a pointer moves the highlight. Style a focus ring for the keyboard only.
1510
1512
  - `data-has-icons`: Present while any suggestion inside holds an icon part, so items without one can line up.
1511
1513
 
@@ -1537,6 +1539,9 @@ While focus stays in the input, use the content’s `data-modality="keyboard"` w
1537
1539
 
1538
1540
  - `data-closed`: Present while the suggestions are closed, including while they animate out.
1539
1541
  - `data-open`: Present while the suggestions are open.
1542
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the suggestions ended up, after flipping away from edges.
1543
+ - `data-align` (`start`, `center`, `end`): How the suggestions line up with the field.
1544
+ - `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the field, held back by `arrowPadding`.
1540
1545
 
1541
1546
  ### AutocompleteItemIcon
1542
1547
  `[data-slot="autocomplete-item-icon"]`
@@ -1555,7 +1560,7 @@ to decide.
1555
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.
1556
1561
  - `value?` (`string`): The text. Pass it to control it.
1557
1562
  - `defaultValue?` (`string`): The text at first, when uncontrolled. A form reset returns to it.
1558
- - `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.
1559
1564
  - `open?` (`boolean`): Whether the suggestions are open. Pass it to control them.
1560
1565
  - `defaultOpen?` (`boolean`): Whether the suggestions start open, when uncontrolled.
1561
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.
@@ -1765,6 +1770,8 @@ Create one with `createAutocompleteController()` and pass it as `controller`.
1765
1770
  - `getValue()` (`() => string`): The text.
1766
1771
  - `setValue(value, options?)` (`(value: string, options?: AutocompleteChangeOptions<AutocompleteValueChangeReason> | undefined) => boolean`): Changes the text, which filters the suggestions. Returns false when the change was canceled or nothing changed.
1767
1772
  - `clear(options?)` (`(options?: AutocompleteChangeOptions<AutocompleteValueChangeReason> | undefined) => boolean`): Empties the field. Returns false when the change was canceled or nothing changed.
1773
+ - `getHighlighted()` (`() => string | null`): The value of the highlighted suggestion, or null when none is.
1774
+ - `highlight(value)` (`(value: string | null) => boolean`): Highlights the suggestion with this value in the open list, scrolled into view, or none with null. Returns false when the suggestions are closed, or no enabled suggestion has the value.
1768
1775
  - `focus()` (`() => void`): Moves focus to the field.
1769
1776
 
1770
1777
  ### Events
@@ -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">
@@ -2776,6 +2776,8 @@ Use `data-highlighted` for the active option and `data-selected` for chosen valu
2776
2776
  - `data-open`: Present while the list is open.
2777
2777
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
2778
2778
  - `data-ending-style`: Present while the list animates out. Style the state you animate to.
2779
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the list ended up, after flipping away from edges.
2780
+ - `data-align` (`start`, `center`, `end`): How the list lines up with the input.
2779
2781
  - `data-modality` (`keyboard`, `pointer`): Whether the keyboard or a pointer moves the highlight. Style a focus ring for the keyboard only.
2780
2782
  - `data-has-icons`: Present while any item inside holds an icon part, so items without one can line up.
2781
2783
 
@@ -2813,6 +2815,9 @@ Use `data-highlighted` for the active option and `data-selected` for chosen valu
2813
2815
 
2814
2816
  - `data-closed`: Present while the list is closed, including while it animates out.
2815
2817
  - `data-open`: Present while the list is open.
2818
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the list ended up, after flipping away from edges.
2819
+ - `data-align` (`start`, `center`, `end`): How the list lines up with the input.
2820
+ - `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the input, held back by `arrowPadding`.
2816
2821
 
2817
2822
  ### ComboboxItemIcon
2818
2823
  `[data-slot="combobox-item-icon"]`
@@ -2864,7 +2869,7 @@ Props and callbacks are the same as below, as Svelte props. `value`, `query` and
2864
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`.
2865
2870
  - `itemToLabel?` (`((value: T) => string)`): The text a value shows, for values whose item isn't rendered, like async results.
2866
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.
2867
- - `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.
2868
2873
  - `keepQuery?` (`boolean`): With `multiple`, whether the input keeps its text after an item is chosen.
2869
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.
2870
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.
@@ -2913,7 +2918,7 @@ Holds the chips and the input for a multiple selection. Renders a `div`.
2913
2918
 
2914
2919
  ### ComboboxValue
2915
2920
 
2916
- - `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`.
2917
2922
  - `getMoreLabel?` (`((count: number) => string)`): The words for the labels past `maxLabels`.
2918
2923
 
2919
2924
  ### ComboboxChip
@@ -3177,6 +3182,8 @@ Every write method takes an optional `{ reason, event }`, passed to the change c
3177
3182
  - `clear(options?)` (`(options?: ComboboxChangeOptions<ComboboxValueChangeReason> | undefined) => boolean`): Selects nothing and empties the input. Returns false when the change was canceled or nothing changed.
3178
3183
  - `getQuery()` (`() => string`): The input's text.
3179
3184
  - `setQuery(query, options?)` (`(query: string, options?: ComboboxChangeOptions<ComboboxQueryChangeReason> | undefined) => boolean`): Changes the input's text, which filters the list. Returns false when the change was canceled or nothing changed.
3185
+ - `getHighlighted()` (`() => T | null`): The value of the highlighted item, or null when none is.
3186
+ - `highlight(value)` (`(value: T | null) => boolean`): Highlights the item with this value in the open list, scrolled into view, or none with null. Returns false when the list is closed, or no enabled item has the value.
3180
3187
  - `focus()` (`() => void`): Moves focus to the input.
3181
3188
 
3182
3189
  ### Events
@@ -3260,6 +3267,7 @@ The combobox follows the [WAI-ARIA combobox pattern with list autocomplete](http
3260
3267
  **Default value**
3261
3268
 
3262
3269
  - Shows its label in the input.
3270
+ - Typing inside the label keeps the caret where it is.
3263
3271
 
3264
3272
  **Multiple**
3265
3273
 
@@ -3302,6 +3310,7 @@ Also tested:
3302
3310
  **Enhancements**
3303
3311
 
3304
3312
  - The list is named by the combobox's label.
3313
+ - A click on the label focuses the input and leaves the list closed.
3305
3314
  - Filtering matches an item's keywords as well as its label.
3306
3315
  - A create option offers the text, and hides when an item's label matches it exactly.
3307
3316
  - Enter on the create option calls onCreate with the text.
@@ -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.
@@ -516,5 +517,6 @@ Every line below is an automated test.
516
517
  - The field's label focuses the first segment.
517
518
  - A read-only date takes focus but doesn't change.
518
519
  - A disabled date can't be focused.
520
+ - Digits committed through an input method fill the segment.
519
521
 
520
522
  Runs in React, Vue and web components.
@@ -1034,6 +1034,8 @@ Each part has a `data-slot`, such as `date-picker-input`, and its state attribut
1034
1034
  - `data-closed`: Present while the popup is closed, including while it animates out.
1035
1035
  - `data-starting-style`: Present for the first frame. Style the state you animate from.
1036
1036
  - `data-ending-style`: Present while the popup animates out. Style the state you animate to.
1037
+ - `data-side` (`top`, `right`, `bottom`, `left`): Where the popup ended up, after flipping away from edges.
1038
+ - `data-align` (`start`, `center`, `end`): How the popup lines up with the input.
1037
1039
 
1038
1040
  ### DatePickerClear
1039
1041
  `[data-slot="date-picker-clear"]`
@@ -1120,7 +1122,7 @@ Clears the value and focuses the input. Renders a `button`.
1120
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.
1121
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.
1122
1124
  - `finalFocus?` (`PopupFocusTarget`): Where focus goes when the popup closes while focus is inside it.
1123
- - `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.
1124
1126
  ### DatePickerPreset
1125
1127
 
1126
1128
  - `value` (`DatePickerValue`): The value it selects: an ISO date, or `[start, end]` in range mode.