@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.
- package/dist/autocomplete/autocomplete-item-text.svelte +31 -8
- package/dist/autocomplete/autocomplete.svelte +2 -2
- package/dist/autocomplete/autocomplete.svelte.d.ts +2 -2
- package/dist/autocomplete.d.ts +1 -1
- package/dist/combobox/combobox-item-text.svelte +31 -8
- package/dist/combobox/combobox.svelte +4 -2
- package/dist/combobox/combobox.svelte.d.ts +1 -1
- package/dist/command/command-item-text.svelte +31 -8
- package/dist/dialog/dialog-content.svelte +9 -3
- package/dist/dialog/dialog-content.svelte.d.ts +1 -0
- package/dist/drawer/drawer-content.svelte.d.ts +2 -6
- package/dist/field/field-description.svelte +2 -0
- package/dist/field/field-error.svelte +3 -6
- package/dist/listbox/listbox.svelte +7 -1
- package/dist/listbox/listbox.svelte.d.ts +2 -0
- package/dist/pagination/pagination.svelte +4 -0
- package/dist/pagination/pagination.svelte.d.ts +2 -0
- package/dist/popover/popover-content.svelte +4 -2
- package/dist/popover/popover-content.svelte.d.ts +1 -0
- package/dist/segmented-control.d.ts +1 -1
- package/dist/select/select-item-text.svelte +31 -8
- package/dist/select/select-trigger-binding.svelte +7 -8
- package/dist/select/select-trigger-binding.svelte.d.ts +2 -1
- package/dist/select/select-trigger.svelte +19 -11
- package/dist/select/select.svelte +7 -1
- package/dist/select/select.svelte.d.ts +2 -0
- package/dist/shortcuts.svelte.d.ts +2 -1
- package/dist/shortcuts.svelte.js +2 -1
- package/dist/use-primitive.svelte.js +20 -3
- package/docs/agents.md +84 -21
- package/docs/components/alert-dialog.md +2 -1
- package/docs/components/autocomplete.md +9 -2
- package/docs/components/calendar.md +2 -2
- package/docs/components/collapsible.md +1 -0
- package/docs/components/combobox.md +12 -3
- package/docs/components/command.md +1 -0
- package/docs/components/date-input.md +2 -0
- package/docs/components/date-picker.md +3 -1
- package/docs/components/dialog.md +50 -1
- package/docs/components/drawer.md +4 -1
- package/docs/components/file-input.md +3 -3
- package/docs/components/hover-card.md +6 -1
- package/docs/components/image-cropper.md +12 -12
- package/docs/components/listbox.md +55 -2
- package/docs/components/menu.md +10 -2
- package/docs/components/menubar.md +1 -0
- package/docs/components/navigation-menu.md +1 -0
- package/docs/components/number-input.md +1 -0
- package/docs/components/pagination.md +3 -2
- package/docs/components/popover.md +45 -2
- package/docs/components/resizable.md +6 -1
- package/docs/components/segmented-control.md +9 -0
- package/docs/components/select.md +18 -2
- package/docs/components/tabs.md +1 -1
- package/docs/components/time-input.md +2 -0
- package/docs/components/tooltip.md +6 -1
- package/docs/components/trigger-menu.md +3 -0
- package/docs/core.md +102 -24
- package/docs/forms.md +1 -1
- package/docs/installation.md +16 -1
- package/docs/introduction.md +2 -2
- package/docs/lists-and-menus.md +1 -1
- package/docs/llms.txt +33 -13
- package/docs/popups.md +1 -1
- package/docs/styling-and-animation.md +4 -0
- package/docs/utilities/async-options.md +6 -5
- package/docs/utilities/shortcuts.md +2 -2
- package/package.json +3 -3
|
@@ -1550,6 +1550,8 @@ Each part has a `data-slot`, such as `select-trigger`, and its state attributes
|
|
|
1550
1550
|
- `data-open`: Present while the list is open.
|
|
1551
1551
|
- `data-starting-style`: Present for the first frame. Style the state you animate from.
|
|
1552
1552
|
- `data-ending-style`: Present while the list animates out. Style the state you animate to.
|
|
1553
|
+
- `data-side` (`top`, `right`, `bottom`, `left`): Where the list ended up, after flipping away from edges.
|
|
1554
|
+
- `data-align` (`start`, `center`, `end`): How the list lines up with the trigger.
|
|
1553
1555
|
- `data-modality` (`keyboard`, `pointer`): Whether the keyboard or a pointer is in use, for focus styles.
|
|
1554
1556
|
- `data-has-icons`: Present while any item inside holds an icon part, so items without one can line up.
|
|
1555
1557
|
|
|
@@ -1594,6 +1596,9 @@ Each part has a `data-slot`, such as `select-trigger`, and its state attributes
|
|
|
1594
1596
|
|
|
1595
1597
|
- `data-closed`: Present while the list is closed, including while it animates out.
|
|
1596
1598
|
- `data-open`: Present while the list is open.
|
|
1599
|
+
- `data-side` (`top`, `right`, `bottom`, `left`): Where the list ended up, after flipping away from edges.
|
|
1600
|
+
- `data-align` (`start`, `center`, `end`): How the list lines up with the trigger.
|
|
1601
|
+
- `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the trigger, held back by `arrowPadding`.
|
|
1597
1602
|
|
|
1598
1603
|
### SelectItemIcon
|
|
1599
1604
|
`[data-slot="select-item-icon"]`
|
|
@@ -1626,6 +1631,7 @@ Props and callbacks are the same as below, as Svelte props. `value`, `open` and
|
|
|
1626
1631
|
- `isItemEqualToValue?` (`((itemValue: T, value: T) => boolean)`): Whether an item's value is the selected value, for object values that aren't the same object.
|
|
1627
1632
|
- `onHighlight?` (`((value: T | null, details: ListHighlightDetails) => void)`): Runs when the highlight moves, with the item's index among the visible items, so a virtualized list can scroll to it.
|
|
1628
1633
|
- `loop?` (`boolean`): Whether arrow keys wrap from the last item to the first.
|
|
1634
|
+
- `virtualFocus?` (`boolean`): Keeps focus on the trigger while the list is open, as on a native select: arrow keys, Home, End and typing move the highlight, and the trigger points at the highlighted item with `aria-activedescendant`. A search field in the list still takes focus.
|
|
1629
1635
|
- `modal?` (`"pointer" | boolean`): `"pointer"`: an outside press only closes the list. `true`: also locks scroll and makes the rest of the page inert. `false`: outside presses reach what they hit.
|
|
1630
1636
|
- `presentation?` (`PresentationSetting<"popover">`): How the list presents. `"sheet"` slides it up from the bottom of the screen, where it can be swiped away, and `"auto"` does that on small touch screens. Decided each time it opens; the server renders `"popover"` for `"auto"`.
|
|
1631
1637
|
- `disabled?` (`boolean`): Disables the select like a native one: it can't be focused or changed, and the value isn't submitted.
|
|
@@ -1653,7 +1659,7 @@ A trigger outside the select also takes `controller`.
|
|
|
1653
1659
|
### SelectValue
|
|
1654
1660
|
|
|
1655
1661
|
- `placeholder?` (`string`): What shows while nothing is selected. Overrides the select's `placeholder`.
|
|
1656
|
-
- `maxLabels?` (`number`): With `multiple`, how many labels show before the rest are counted, as in "Apple, Banana and 2 more", joined the way the page's language joins lists
|
|
1662
|
+
- `maxLabels?` (`number`): With `multiple`, how many labels show before the rest are counted, as in "Apple, Banana and 2 more", joined the way the page's language joins lists, or in English with the default `getMoreLabel`.
|
|
1657
1663
|
- `getMoreLabel?` (`((count: number) => string)`): The words for the labels past `maxLabels`.
|
|
1658
1664
|
|
|
1659
1665
|
### SelectContent
|
|
@@ -1667,7 +1673,7 @@ A trigger outside the select also takes `controller`.
|
|
|
1667
1673
|
- `anchor?` (`string | Anchor | null`): Positions the popup against this instead of its trigger: an element, a CSS selector, a point like `{ x, y }`, or anything with `getBoundingClientRect()`. It's read on every check, so it can move. A controller's `open({ anchor })` wins for that open.
|
|
1668
1674
|
- `container?` (`DocumentFragment | Element | null`): Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
|
|
1669
1675
|
- `alignItemWithTrigger?` (`boolean`): Whether the list overlaps the trigger so the selected item sits on it, like a native select on macOS. Falls back to opening below when there isn't room, and for touch.
|
|
1670
|
-
- `keepMounted?` (`boolean`): Whether the list stays in the page, hidden, while closed.
|
|
1676
|
+
- `keepMounted?` (`boolean`): Whether the list stays in the page, hidden, while closed. Its content keeps its state between opens.
|
|
1671
1677
|
|
|
1672
1678
|
### SelectItem
|
|
1673
1679
|
|
|
@@ -1870,6 +1876,8 @@ The select follows the [WAI-ARIA select-only combobox pattern](https://www.w3.or
|
|
|
1870
1876
|
|
|
1871
1877
|
Arrow keys move through the open list; Home and End reach its first and last items. Set `loop={false}` to stop arrow keys at either end. The popup follows the trigger's inherited text direction; use logical CSS properties for spacing in right-to-left layouts.
|
|
1872
1878
|
|
|
1879
|
+
Set `virtualFocus` to keep focus on the trigger while the list is open, as on a native select: arrow keys, Home, End and typing move the highlight, the trigger points at it with `aria-activedescendant`, and Tab closes the list and moves on. A search field in the list still takes focus.
|
|
1880
|
+
|
|
1873
1881
|
### Tested Behavior
|
|
1874
1882
|
|
|
1875
1883
|
Every line below is an automated test.
|
|
@@ -1897,6 +1905,7 @@ Every line below is an automated test.
|
|
|
1897
1905
|
- Enter chooses the focused item, closes and returns focus to the trigger.
|
|
1898
1906
|
- Space chooses the focused item.
|
|
1899
1907
|
- Escape closes without choosing and returns focus to the trigger.
|
|
1908
|
+
- An ancestor hears Escape already handled.
|
|
1900
1909
|
- The chosen item is selected when the list opens again, and takes focus.
|
|
1901
1910
|
|
|
1902
1911
|
**Typing on the closed trigger**
|
|
@@ -1934,6 +1943,7 @@ Every line below is an automated test.
|
|
|
1934
1943
|
**Forms**
|
|
1935
1944
|
|
|
1936
1945
|
- The form submits the value under the select's name.
|
|
1946
|
+
- Enter in the form's one text field submits it, with no submit button.
|
|
1937
1947
|
- A required select blocks submission until a value is chosen.
|
|
1938
1948
|
- A disabled select can't be opened.
|
|
1939
1949
|
- A read-only select doesn't change its value.
|
|
@@ -1957,6 +1967,12 @@ Also tested:
|
|
|
1957
1967
|
- A form reset returns the select to its default value.
|
|
1958
1968
|
- Typing on the closed trigger selects items before the list has ever been in the page.
|
|
1959
1969
|
|
|
1970
|
+
**Focus on the trigger**
|
|
1971
|
+
|
|
1972
|
+
- With virtualFocus, keys move the highlight while focus stays on the trigger, which points at it.
|
|
1973
|
+
- With virtualFocus, Tab closes the list and moves on from the trigger.
|
|
1974
|
+
- With virtualFocus, a click on an item chooses it and keeps focus on the trigger.
|
|
1975
|
+
|
|
1960
1976
|
Runs in React, Vue and web components.
|
|
1961
1977
|
|
|
1962
1978
|
Searching, with a search field in the list:
|
package/docs/components/tabs.md
CHANGED
|
@@ -29,7 +29,7 @@ Tabs
|
|
|
29
29
|
└── TabsPanel
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
Give each tab and its panel the same unique `value`. Give the list an accessible name. Set `defaultValue` to choose the initial tab; otherwise, the first enabled tab is selected.
|
|
32
|
+
Give each tab and its panel the same unique `value`. Give the list an accessible name. Set `defaultValue` to choose the initial tab; otherwise, the first enabled tab is selected. On the server, panels that render before the list don't know that tab yet, so a layout with the panels first, like a bottom tab bar, needs `defaultValue` or `bind:value` to render its panel before hydration.
|
|
33
33
|
|
|
34
34
|
## Usage
|
|
35
35
|
|
|
@@ -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.
|
|
@@ -214,5 +215,6 @@ Every line below is an automated test.
|
|
|
214
215
|
- The field's label focuses the first segment.
|
|
215
216
|
- A read-only date takes focus but doesn't change.
|
|
216
217
|
- A disabled date can't be focused.
|
|
218
|
+
- Digits committed through an input method fill the segment.
|
|
217
219
|
|
|
218
220
|
Runs in React, Vue and web components.
|
|
@@ -44,7 +44,7 @@ Tooltip
|
|
|
44
44
|
|
|
45
45
|
Wrap the trigger and its hint in a tooltip. The arrow and the shortcut are optional.
|
|
46
46
|
|
|
47
|
-
The content has the `tooltip` role, and it's in the page from the start, hidden, so it names or describes its trigger before focus reaches it. It names a trigger without a name of its own, like a button with only an icon, and describes any other: one with text, an `aria-label` or a `title`. `type="label"` or `type="description"` overrides the guess. Keep it to plain text: a tooltip can't be focused, so links or buttons inside it can't be reached. For anything interactive, use a [Popover](./popover.md) or a [Hover Card](./hover-card.md).
|
|
47
|
+
The content has the `tooltip` role, and it's in the page from the start, hidden, so it names or describes its trigger before focus reaches it. It names a trigger without a name of its own, like a button with only an icon, and describes any other: one with text, an `aria-label` or a `title`. `type="label"` or `type="description"` overrides the guess. The guess happens in the browser, so server-rendered HTML describes a trigger with only an icon until then. Pass `type="label"` to name it from the first HTML. Keep it to plain text: a tooltip can't be focused, so links or buttons inside it can't be reached. For anything interactive, use a [Popover](./popover.md) or a [Hover Card](./hover-card.md).
|
|
48
48
|
|
|
49
49
|
## Usage
|
|
50
50
|
|
|
@@ -611,12 +611,17 @@ Each part has a `data-slot`, such as `tooltip-content`, and its state attributes
|
|
|
611
611
|
- `data-open`: Present while the tooltip is open.
|
|
612
612
|
- `data-starting-style`: Present for the first frame. Style the state you animate from.
|
|
613
613
|
- `data-ending-style`: Present while the tooltip animates out. Style the state you animate to.
|
|
614
|
+
- `data-side` (`top`, `right`, `bottom`, `left`): Where the tooltip ended up, after flipping away from edges. Set on the arrow too.
|
|
615
|
+
- `data-align` (`start`, `center`, `end`): How the tooltip lines up with its trigger.
|
|
614
616
|
|
|
615
617
|
### TooltipArrow
|
|
616
618
|
`[data-slot="tooltip-arrow"]`
|
|
617
619
|
|
|
618
620
|
- `data-closed`: Present while the tooltip is closed, including while it animates out.
|
|
619
621
|
- `data-open`: Present while the tooltip is open.
|
|
622
|
+
- `data-side` (`top`, `right`, `bottom`, `left`): Where the tooltip ended up, after flipping away from edges. Set on the arrow too.
|
|
623
|
+
- `data-align` (`start`, `center`, `end`): How the tooltip lines up with its trigger.
|
|
624
|
+
- `data-arrow-clamped`: Present on the arrow when it stops short of the middle of the trigger, held back by `arrowPadding`.
|
|
620
625
|
|
|
621
626
|
## API Reference
|
|
622
627
|
|
|
@@ -870,6 +870,8 @@ Each part has a `data-slot`, such as `trigger-menu-item`, and shows its state th
|
|
|
870
870
|
- `data-closed`: Present while the list is closed, including while it animates out.
|
|
871
871
|
- `data-starting-style`: Present for the first frame. Style the state you animate from.
|
|
872
872
|
- `data-ending-style`: Present while the list animates out. Style the state you animate to.
|
|
873
|
+
- `data-side` (`top`, `right`, `bottom`, `left`): Where the list ended up, after flipping away from edges.
|
|
874
|
+
- `data-align` (`start`, `center`, `end`): How the list lines up with the trigger.
|
|
873
875
|
- `data-open`: Present while the list is open.
|
|
874
876
|
- `data-trigger`: The trigger of the current match, like `@`, while there is one.
|
|
875
877
|
- `data-has-icons`: Present while any item inside holds an icon part, so items without one can line up.
|
|
@@ -1121,6 +1123,7 @@ Every line below is an automated test.
|
|
|
1121
1123
|
|
|
1122
1124
|
- Typing a trigger opens the list with every item.
|
|
1123
1125
|
- Typing after the trigger filters the list.
|
|
1126
|
+
- Text an input method commits filters the list.
|
|
1124
1127
|
- Queries match Unicode letters and ignore accents.
|
|
1125
1128
|
- A trigger mid-word doesn't open.
|
|
1126
1129
|
- A trigger followed by a space doesn't open.
|
package/docs/core.md
CHANGED
|
@@ -179,7 +179,7 @@ function Example() {
|
|
|
179
179
|
|
|
180
180
|
**Vue**
|
|
181
181
|
|
|
182
|
-
```ts title="components/ui/mute-button.
|
|
182
|
+
```ts title="components/ui/mute-button.ts"
|
|
183
183
|
import { createParts } from "@ui-sdk/vue/primitive"
|
|
184
184
|
import { muteButton } from "@/lib/mute-button"
|
|
185
185
|
|
|
@@ -202,7 +202,7 @@ import { MuteButton } from "@/components/ui/mute-button"
|
|
|
202
202
|
|
|
203
203
|
**Svelte**
|
|
204
204
|
|
|
205
|
-
```ts title="components/ui/mute-button.
|
|
205
|
+
```ts title="components/ui/mute-button.ts"
|
|
206
206
|
import { createParts } from "@ui-sdk/svelte/primitive"
|
|
207
207
|
import { muteButton } from "@/lib/mute-button"
|
|
208
208
|
|
|
@@ -223,7 +223,7 @@ export { MuteButton }
|
|
|
223
223
|
|
|
224
224
|
**Solid**
|
|
225
225
|
|
|
226
|
-
```ts title="components/ui/mute-button.
|
|
226
|
+
```ts title="components/ui/mute-button.ts"
|
|
227
227
|
import { createParts } from "@ui-sdk/solid/primitive"
|
|
228
228
|
import { muteButton } from "@/lib/mute-button"
|
|
229
229
|
|
|
@@ -248,7 +248,7 @@ export { Example }
|
|
|
248
248
|
|
|
249
249
|
For web components, register a custom element:
|
|
250
250
|
|
|
251
|
-
```ts title="components/ui/mute-button.
|
|
251
|
+
```ts title="components/ui/mute-button.ts"
|
|
252
252
|
import { createParts, wrappedButton } from "@ui-sdk/web"
|
|
253
253
|
import { muteButton } from "@/lib/mute-button"
|
|
254
254
|
|
|
@@ -503,6 +503,9 @@ item: slot({
|
|
|
503
503
|
role: "option",
|
|
504
504
|
focus: "roving",
|
|
505
505
|
press: ({ api, key }) => api.choose(key),
|
|
506
|
+
attrs: (state, part) => ({
|
|
507
|
+
"aria-selected": String(state.value === part.key),
|
|
508
|
+
}),
|
|
506
509
|
}),
|
|
507
510
|
```
|
|
508
511
|
|
|
@@ -764,7 +767,7 @@ createParts(copyButton, {
|
|
|
764
767
|
|
|
765
768
|
`createParts` registers a custom element for each slot you map. `wrappedButton` puts the root's behavior and attributes on a native button inside the element. Import this file from your app's browser entry point.
|
|
766
769
|
|
|
767
|
-
`Root` creates the primitive's instance and shares it with the parts inside. Every other slot becomes a part named in Pascal case, so a `star` slot becomes `Star`.
|
|
770
|
+
`Root` creates the primitive's instance and shares it with the parts inside. Every other slot you map becomes a part named in Pascal case, so a `star` slot becomes `Star`.
|
|
768
771
|
|
|
769
772
|
## Pass Options
|
|
770
773
|
|
|
@@ -2335,7 +2338,9 @@ In a textarea, the arrow keys move between lines first. An entry comes back only
|
|
|
2335
2338
|
|
|
2336
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.
|
|
2337
2340
|
|
|
2338
|
-
|
|
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
|
+
|
|
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.
|
|
2339
2344
|
|
|
2340
2345
|
### Report It as a Change
|
|
2341
2346
|
|
|
@@ -3296,7 +3301,7 @@ keys: slot({
|
|
|
3296
3301
|
|
|
3297
3302
|
Try the shortcut while typing in the note:
|
|
3298
3303
|
|
|
3299
|
-
`formatShortcut` keeps the label in left-to-right order, even on a right-to-left page. For tests, import `setPlatform` from `@ui-sdk/core/testing` and call `setPlatform("apple")` or `setPlatform("other")`.
|
|
3304
|
+
`formatShortcut` keeps the label in left-to-right order, even on a right-to-left page, by wrapping it in two invisible characters. For tests, import `setPlatform` from `@ui-sdk/core/testing` and call `setPlatform("apple")` or `setPlatform("other")`.
|
|
3300
3305
|
|
|
3301
3306
|
## Layers and Positioning
|
|
3302
3307
|
|
|
@@ -3404,6 +3409,8 @@ A phone picks its keyboard from the field: `inputmode` chooses the keys, like a
|
|
|
3404
3409
|
|
|
3405
3410
|
`createPointerKind` reports whether the main pointer is a finger or a mouse and whether it can hover, from the `pointer` and `hover` media features, plus `anyPointer` and `anyHover` for every pointer attached, like a trackpad on a tablet. Read it like a preference, with `usePreference` in each framework:
|
|
3406
3411
|
|
|
3412
|
+
**React**
|
|
3413
|
+
|
|
3407
3414
|
```tsx
|
|
3408
3415
|
import { createPointerKind } from "@ui-sdk/core"
|
|
3409
3416
|
import { usePreference } from "@ui-sdk/react/preferences"
|
|
@@ -3414,6 +3421,53 @@ const { hover } = usePreference(pointerKind)
|
|
|
3414
3421
|
// "hover" with a mouse, "none" on a phone, "unknown" on the server
|
|
3415
3422
|
```
|
|
3416
3423
|
|
|
3424
|
+
**Vue**
|
|
3425
|
+
|
|
3426
|
+
```ts
|
|
3427
|
+
import { createPointerKind } from "@ui-sdk/core"
|
|
3428
|
+
import { usePreference } from "@ui-sdk/vue/preferences"
|
|
3429
|
+
|
|
3430
|
+
const pointerKind = createPointerKind()
|
|
3431
|
+
|
|
3432
|
+
const pointer = usePreference(pointerKind)
|
|
3433
|
+
// pointer.value.hover: "hover" with a mouse, "none" on a phone, "unknown" on the server
|
|
3434
|
+
```
|
|
3435
|
+
|
|
3436
|
+
**Svelte**
|
|
3437
|
+
|
|
3438
|
+
```ts
|
|
3439
|
+
import { createPointerKind } from "@ui-sdk/core"
|
|
3440
|
+
import { usePreference } from "@ui-sdk/svelte/preferences"
|
|
3441
|
+
|
|
3442
|
+
const pointerKind = createPointerKind()
|
|
3443
|
+
|
|
3444
|
+
const pointer = usePreference(pointerKind)
|
|
3445
|
+
// pointer.current.hover: "hover" with a mouse, "none" on a phone, "unknown" on the server
|
|
3446
|
+
```
|
|
3447
|
+
|
|
3448
|
+
**Solid**
|
|
3449
|
+
|
|
3450
|
+
```tsx
|
|
3451
|
+
import { createPointerKind } from "@ui-sdk/core"
|
|
3452
|
+
import { usePreference } from "@ui-sdk/solid/preferences"
|
|
3453
|
+
|
|
3454
|
+
const pointerKind = createPointerKind()
|
|
3455
|
+
|
|
3456
|
+
const pointer = usePreference(pointerKind)
|
|
3457
|
+
// pointer().hover: "hover" with a mouse, "none" on a phone, "unknown" on the server
|
|
3458
|
+
```
|
|
3459
|
+
|
|
3460
|
+
**Web Components**
|
|
3461
|
+
|
|
3462
|
+
```ts
|
|
3463
|
+
import { createPointerKind } from "@ui-sdk/core"
|
|
3464
|
+
|
|
3465
|
+
const pointerKind = createPointerKind()
|
|
3466
|
+
|
|
3467
|
+
const { hover } = pointerKind.get()
|
|
3468
|
+
// "hover" with a mouse, "none" on a phone, "unknown" on the server
|
|
3469
|
+
```
|
|
3470
|
+
|
|
3417
3471
|
It's for behavior and content, like opening on tap where nothing can hover. Style with the media queries themselves, `@media (hover: hover)` or Tailwind's `pointer-coarse:`, which are right from the first paint.
|
|
3418
3472
|
|
|
3419
3473
|
With a mouse, the details open on hover. On a phone, they open on tap, and the button says so.
|
|
@@ -3802,7 +3856,7 @@ In Notes, press Control or Command with U, then Shift+Tab. Focus returns to Unde
|
|
|
3802
3856
|
|
|
3803
3857
|
### Any Layout
|
|
3804
3858
|
|
|
3805
|
-
|
|
3859
|
+
`move` decides where each key goes. A keypad can use it to move three items at a time for Up and Down:
|
|
3806
3860
|
|
|
3807
3861
|
```ts
|
|
3808
3862
|
move: (event, { from, items, rtl }) => {
|
|
@@ -3996,8 +4050,8 @@ api: (context) => ({
|
|
|
3996
4050
|
Each cell has a zero-based `row` and `col`. Connect its tab stop, keys and element to the behavior:
|
|
3997
4051
|
|
|
3998
4052
|
```ts
|
|
3999
|
-
seat: slot<{ row: number; col: number }>({
|
|
4000
|
-
props: { row: "number", col: "number" },
|
|
4053
|
+
seat: slot<{ id: string; row: number; col: number }>({
|
|
4054
|
+
props: { id: "string", row: "number", col: "number" },
|
|
4001
4055
|
selects: selects({ active: byCell }),
|
|
4002
4056
|
attrs: (state, { props, api }) => ({
|
|
4003
4057
|
role: "gridcell",
|
|
@@ -4106,7 +4160,7 @@ They're only hints: a field keeps its own `type` and validation, so a `type="ema
|
|
|
4106
4160
|
### Roving Focus Options
|
|
4107
4161
|
|
|
4108
4162
|
- `slot` (`string`): The slot whose parts are the group's items. Each joins in the slot's `bind` with `roving.bind(el, part)`. Example: [One Tab Stop](#one-tab-stop).
|
|
4109
|
-
- `key` (`keyof State & string`): The state key that holds the key of the item with the tab stop. Start it at `null
|
|
4163
|
+
- `key` (`keyof State & string`): The state key that holds the key of the item with the tab stop. Start it at `null`, and set it back to `null` to forget the item focused last. Example: [One Tab Stop](#one-tab-stop).
|
|
4110
4164
|
- `orientation?` (`(() => RovingOrientation | "both")`): Which arrows move focus when there's no `move`: Up and Down, Left and Right, or `"both"` for all four, like a rating. Defaults to `"vertical"`. Example: [One Tab Stop](#one-tab-stop).
|
|
4111
4165
|
- `loop?` (`(() => boolean)`): Whether moving past either end wraps around. Defaults to `false`. Example: [Disabled Items and Wrapping](#disabled-items-and-wrapping).
|
|
4112
4166
|
- `remember?` (`boolean`): Whether the item focused last keeps the stop, like a toolbar, rather than the preferred one, like tabs. Defaults to `true`. Example: [One Tab Stop](#one-tab-stop).
|
|
@@ -4218,6 +4272,15 @@ if (moved?.shift) {
|
|
|
4218
4272
|
|
|
4219
4273
|
`from` supplies the starting point when there isn't an anchor yet. `selection.anchor()` returns the current anchor's key.
|
|
4220
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
|
+
|
|
4221
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.
|
|
4222
4285
|
|
|
4223
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.
|
|
@@ -5441,7 +5504,11 @@ option: slot<{ value: string }>({
|
|
|
5441
5504
|
...part.api.listbox.attrs(state, part),
|
|
5442
5505
|
"aria-selected": String(state.value === part.key),
|
|
5443
5506
|
}),
|
|
5444
|
-
|
|
5507
|
+
press: ({ key, api }, event) => api.choose(key, event),
|
|
5508
|
+
on: {
|
|
5509
|
+
pointerdown: (event) => event.preventDefault(),
|
|
5510
|
+
pointermove: (event, { key, api }) => api.listbox.highlight(key, { event }),
|
|
5511
|
+
},
|
|
5445
5512
|
bind: (el, part) => part.api.listbox.bind(el, part),
|
|
5446
5513
|
}),
|
|
5447
5514
|
```
|
|
@@ -7930,6 +7997,16 @@ document.head.append(
|
|
|
7930
7997
|
|
|
7931
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.
|
|
7932
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
|
+
|
|
7933
8010
|
|
|
7934
8011
|
# Get Started
|
|
7935
8012
|
|
|
@@ -7948,9 +8025,9 @@ Pick your framework, then copy this prompt into your agent.
|
|
|
7948
8025
|
```text prompt
|
|
7949
8026
|
Set up ui-sdk in this React project. It needs React 19 or newer.
|
|
7950
8027
|
|
|
7951
|
-
1. Install @ui-sdk/react and @ui-sdk/core with the project's package manager.
|
|
8028
|
+
1. Install @ui-sdk/react and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
7952
8029
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/react/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/react/docs/core.md by heading, and read rendering.md next to it.
|
|
7953
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
8030
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
7954
8031
|
```
|
|
7955
8032
|
|
|
7956
8033
|
**Vue**
|
|
@@ -7958,9 +8035,10 @@ Set up ui-sdk in this React project. It needs React 19 or newer.
|
|
|
7958
8035
|
```text prompt
|
|
7959
8036
|
Set up ui-sdk in this Vue project. It needs Vue 3.5 or newer.
|
|
7960
8037
|
|
|
7961
|
-
1. Install @ui-sdk/vue and @ui-sdk/core with the project's package manager.
|
|
7962
|
-
2.
|
|
7963
|
-
3.
|
|
8038
|
+
1. Install @ui-sdk/vue and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
8039
|
+
2. If it's a Nuxt 4 or newer app, add "@ui-sdk/vue" to modules in nuxt.config.ts.
|
|
8040
|
+
3. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/vue/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/vue/docs/core.md by heading, and read rendering.md next to it.
|
|
8041
|
+
4. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
7964
8042
|
```
|
|
7965
8043
|
|
|
7966
8044
|
**Svelte**
|
|
@@ -7968,19 +8046,19 @@ Set up ui-sdk in this Vue project. It needs Vue 3.5 or newer.
|
|
|
7968
8046
|
```text prompt
|
|
7969
8047
|
Set up ui-sdk in this Svelte project. It needs Svelte 5.33 or newer.
|
|
7970
8048
|
|
|
7971
|
-
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager.
|
|
8049
|
+
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
7972
8050
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/svelte/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/svelte/docs/core.md by heading, and read rendering.md next to it.
|
|
7973
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
8051
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
7974
8052
|
```
|
|
7975
8053
|
|
|
7976
8054
|
**Solid**
|
|
7977
8055
|
|
|
7978
8056
|
```text prompt
|
|
7979
|
-
Set up ui-sdk in this Solid project. It needs Solid 2: solid-js and @solidjs/web 2.0.0
|
|
8057
|
+
Set up ui-sdk in this Solid project. It needs Solid 2: solid-js and @solidjs/web 2.0.0 or newer.
|
|
7980
8058
|
|
|
7981
|
-
1. Install @ui-sdk/solid and @ui-sdk/core with the project's package manager.
|
|
8059
|
+
1. Install @ui-sdk/solid and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
7982
8060
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/solid/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/solid/docs/core.md by heading, and read rendering.md next to it.
|
|
7983
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
8061
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
7984
8062
|
```
|
|
7985
8063
|
|
|
7986
8064
|
**Web Components**
|
|
@@ -7988,9 +8066,9 @@ Set up ui-sdk in this Solid project. It needs Solid 2: solid-js and @solidjs/web
|
|
|
7988
8066
|
```text prompt
|
|
7989
8067
|
Set up ui-sdk in this Web Components project. Each component registers its tags when you import its entry, like @ui-sdk/web/dialog.
|
|
7990
8068
|
|
|
7991
|
-
1. Install @ui-sdk/web and @ui-sdk/core with the project's package manager.
|
|
8069
|
+
1. Install @ui-sdk/web and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
7992
8070
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/web/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/web/docs/core.md by heading, and read rendering.md next to it.
|
|
7993
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
8071
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
7994
8072
|
```
|
|
7995
8073
|
|
|
7996
8074
|
Then ask your agent to build a component:
|
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/installation.md
CHANGED
|
@@ -42,7 +42,22 @@ Each [component page](./README.md) lists the parts you can use.
|
|
|
42
42
|
|
|
43
43
|
Components are unstyled, so you style them with your app's CSS or with Tailwind CSS. [Styling and Animation](./styling-and-animation.md) covers both.
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
For a default look to start from, import `@ui-sdk/core/web.css` once. In SvelteKit, import it in the `<script>` of `src/routes/+layout.svelte`. In a Vite app, import it at the top of `main.ts`:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import "@ui-sdk/core/web.css"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
With Tailwind CSS, import it in your global stylesheet instead, after Tailwind. `layer(components)` puts it above Tailwind's base styles, so they don't reset it, and below its utilities, so a class still wins. Declare [the ui-sdk layer](./styling-and-animation.md#the-ui-sdk-layer) above both:
|
|
52
|
+
|
|
53
|
+
```css
|
|
54
|
+
@layer ui-sdk;
|
|
55
|
+
|
|
56
|
+
@import "tailwindcss";
|
|
57
|
+
@import "@ui-sdk/core/web.css" layer(components);
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
You can render your first component without setting up a provider or adding a portal root. SvelteKit can render the initial HTML on the server; [Server Rendering](./server-rendering.md) explains how to keep it consistent when the page hydrates.
|
|
46
61
|
|
|
47
62
|
## Right to Left
|
|
48
63
|
|
package/docs/introduction.md
CHANGED
|
@@ -15,9 +15,9 @@ Copy this prompt into your agent:
|
|
|
15
15
|
```text prompt
|
|
16
16
|
Set up ui-sdk in this Svelte project. It needs Svelte 5.33 or newer.
|
|
17
17
|
|
|
18
|
-
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager.
|
|
18
|
+
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
19
19
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/svelte/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/svelte/docs/core.md by heading, and read rendering.md next to it.
|
|
20
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
20
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
It installs ui-sdk and points your `AGENTS.md` at the docs that ship with the packages.
|
package/docs/lists-and-menus.md
CHANGED
|
@@ -76,7 +76,7 @@ A list that searches still filters the items you render, and hides the ones that
|
|
|
76
76
|
|
|
77
77
|
Searchable components accept a `filter` to change how typing narrows their items. [Async Options](./utilities/async-options.md) handles server results, debouncing, and stale requests.
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
For a large list, pass every option through `items` and render only the visible rows. [Select](./components/select.md#virtualized) and [Combobox](./components/combobox.md#virtualized) show how.
|
|
80
80
|
|
|
81
81
|
## Describe a Menu
|
|
82
82
|
|
package/docs/llms.txt
CHANGED
|
@@ -22,9 +22,9 @@ Copy this prompt into your agent:
|
|
|
22
22
|
```text prompt
|
|
23
23
|
Set up ui-sdk in this Svelte project. It needs Svelte 5.33 or newer.
|
|
24
24
|
|
|
25
|
-
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager.
|
|
25
|
+
1. Install @ui-sdk/svelte and @ui-sdk/core with the project's package manager. If a release-age policy blocks the install, stop and ask me instead of changing it.
|
|
26
26
|
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/svelte/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/svelte/docs/core.md by heading, and read rendering.md next to it.
|
|
27
|
-
3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
|
|
27
|
+
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
It installs ui-sdk and points your `AGENTS.md` at the docs that ship with the packages.
|
|
@@ -80,7 +80,22 @@ Each [component page](./README.md) lists the parts you can use.
|
|
|
80
80
|
|
|
81
81
|
Components are unstyled, so you style them with your app's CSS or with Tailwind CSS. [Styling and Animation](./styling-and-animation.md) covers both.
|
|
82
82
|
|
|
83
|
-
|
|
83
|
+
For a default look to start from, import `@ui-sdk/core/web.css` once. In SvelteKit, import it in the `<script>` of `src/routes/+layout.svelte`. In a Vite app, import it at the top of `main.ts`:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import "@ui-sdk/core/web.css"
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
With Tailwind CSS, import it in your global stylesheet instead, after Tailwind. `layer(components)` puts it above Tailwind's base styles, so they don't reset it, and below its utilities, so a class still wins. Declare [the ui-sdk layer](./styling-and-animation.md#the-ui-sdk-layer) above both:
|
|
90
|
+
|
|
91
|
+
```css
|
|
92
|
+
@layer ui-sdk;
|
|
93
|
+
|
|
94
|
+
@import "tailwindcss";
|
|
95
|
+
@import "@ui-sdk/core/web.css" layer(components);
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
You can render your first component without setting up a provider or adding a portal root. SvelteKit can render the initial HTML on the server; [Server Rendering](./server-rendering.md) explains how to keep it consistent when the page hydrates.
|
|
84
99
|
|
|
85
100
|
### Right to Left
|
|
86
101
|
|
|
@@ -493,6 +508,8 @@ Popup content gets `data-starting-style` before it enters and `data-ending-style
|
|
|
493
508
|
|
|
494
509
|
Put exit styles on `data-ending-style`. `data-closed` describes the state but doesn't keep the element around for an exit.
|
|
495
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
|
+
|
|
496
513
|
#### Svelte Transitions
|
|
497
514
|
|
|
498
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:
|
|
@@ -543,6 +560,8 @@ ui-sdk adds this CSS once a component mounts, so HTML rendered on the server doe
|
|
|
543
560
|
|
|
544
561
|
It leaves `hidden="until-found"` alone, so find in page can still open a closed panel.
|
|
545
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
|
+
|
|
546
565
|
### Content Security Policy
|
|
547
566
|
|
|
548
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>`:
|
|
@@ -716,7 +735,7 @@ Dialogs, alert dialogs, drawers, and popovers move focus into their content when
|
|
|
716
735
|
| Hover | Nowhere. Focus stays where it is. |
|
|
717
736
|
| Rendered open | Nowhere, except in a dialog, which takes focus as it mounts. |
|
|
718
737
|
|
|
719
|
-
`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.
|
|
720
739
|
|
|
721
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.
|
|
722
741
|
|
|
@@ -808,7 +827,7 @@ A list that searches still filters the items you render, and hides the ones that
|
|
|
808
827
|
|
|
809
828
|
Searchable components accept a `filter` to change how typing narrows their items. [Async Options](./utilities/async-options.md) handles server results, debouncing, and stale requests.
|
|
810
829
|
|
|
811
|
-
|
|
830
|
+
For a large list, pass every option through `items` and render only the visible rows. [Select](./components/select.md#virtualized) and [Combobox](./components/combobox.md#virtualized) show how.
|
|
812
831
|
|
|
813
832
|
### Describe a Menu
|
|
814
833
|
|
|
@@ -891,7 +910,7 @@ A reset also goes through `onCheckedChange` and `bind:checked`. Keep the binding
|
|
|
891
910
|
</form>
|
|
892
911
|
```
|
|
893
912
|
|
|
894
|
-
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.
|
|
895
914
|
|
|
896
915
|
### Label and Validate a Field
|
|
897
916
|
|
|
@@ -1351,11 +1370,12 @@ Use `ComboboxStatus` and `ComboboxEmpty` to show loading, error, and empty messa
|
|
|
1351
1370
|
|
|
1352
1371
|
The second argument sets the starting behavior:
|
|
1353
1372
|
|
|
1354
|
-
| Option | What It Does
|
|
1355
|
-
| ----------- |
|
|
1356
|
-
| `debounce` | Milliseconds typing must pause before a request starts.
|
|
1357
|
-
| `query` | The starting search text.
|
|
1358
|
-
| `immediate` | Loads that text as soon as the component mounts.
|
|
1373
|
+
| Option | What It Does | Default |
|
|
1374
|
+
| ----------- | ------------------------------------------------------------------------------- | ------- |
|
|
1375
|
+
| `debounce` | Milliseconds typing must pause before a request starts. | `200` |
|
|
1376
|
+
| `query` | The starting search text. | `""` |
|
|
1377
|
+
| `immediate` | Loads that text as soon as the component mounts. | `false` |
|
|
1378
|
+
| `minLength` | Characters the text needs before anything loads. Shorter text clears the items. | `0` |
|
|
1359
1379
|
|
|
1360
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`.
|
|
1361
1381
|
|
|
@@ -1427,11 +1447,11 @@ Call the helper in the component's script. It unregisters when the component goe
|
|
|
1427
1447
|
|
|
1428
1448
|
Its fields are reactive getters. Read `hint.text` and `hint.ariaKeyshortcuts` in markup.
|
|
1429
1449
|
|
|
1430
|
-
Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` for the ARIA value, from the same entry.
|
|
1450
|
+
Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` for the ARIA value, from the same entry. The hint's text and `formatShortcut` both keep their left-to-right order on a right-to-left page, because two invisible characters wrap the text. Compare the original keys, not the formatted hint.
|
|
1431
1451
|
|
|
1432
1452
|
#### While Someone Is Typing
|
|
1433
1453
|
|
|
1434
|
-
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.
|
|
1435
1455
|
|
|
1436
1456
|
#### Limit a Shortcut to an Area
|
|
1437
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
|
|