@ui-sdk/svelte 0.1.0-beta.10 → 0.1.0-beta.13
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/use-primitive.svelte.js +2 -1
- package/docs/agents.md +134 -12
- package/docs/components/drawer.md +1 -0
- package/docs/core.md +372 -3
- package/package.json +3 -3
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { applyAttrs, attrs as partAttrs, createListSnapshots, directNames, followed, handlers as partHandlers, on, partState, present as isPresent, ref as partRef, renderVersion, sameSlotState, schemaOf, selectedKeys, subscribe, takeOwnId, touched, yieldToAuthor, } from "@ui-sdk/core/renderer";
|
|
1
|
+
import { applyAttrs, attrs as partAttrs, createListSnapshots, directNames, followed, handlers as partHandlers, noteEarlyText, on, partState, present as isPresent, ref as partRef, renderVersion, sameSlotState, schemaOf, selectedKeys, subscribe, takeOwnId, touched, yieldToAuthor, } from "@ui-sdk/core/renderer";
|
|
2
2
|
import { onDestroy, untrack } from "svelte";
|
|
3
3
|
import { createAttachmentKey } from "svelte/attachments";
|
|
4
4
|
import { trackBindable } from "./bindable.svelte.js";
|
|
@@ -33,6 +33,7 @@ function usePrimitive(primitive, options) {
|
|
|
33
33
|
// The first options go into the constructor, since effects never run on the server.
|
|
34
34
|
const first = untrack(() => snapshot(options()));
|
|
35
35
|
const prefixed = `ui-sdk-${first.id}`;
|
|
36
|
+
noteEarlyText();
|
|
36
37
|
const instance = primitive({ ...first, id: prefixed });
|
|
37
38
|
const bindable = trackBindable(primitive, instance.get(), first, options);
|
|
38
39
|
const removals = [];
|
package/docs/agents.md
CHANGED
|
@@ -485,7 +485,7 @@ For a browser that supports WebMCP, [register the tools with the browser](./agen
|
|
|
485
485
|
|
|
486
486
|
A component built with [`definePrimitive`](./core.md#define-a-primitive) joins the bridge too. Its `agent` key lists the API methods an agent can call, like `agent: { actions: ["setValue"] }`. Without one, methods named like changes, such as `setValue` or `toggle`, become its actions, and event handlers such as `keydown` stay internal.
|
|
487
487
|
|
|
488
|
-
The snapshot reads the primitive's `controlled` state keys. If none are declared, it reads `open`, `value`, and `checked` when present. [
|
|
488
|
+
The snapshot reads the primitive's `controlled` state keys. If none are declared, it reads `open`, `value`, and `checked` when present. [The Agent Key](./agents.md#the-agent-key) shows how to add the key and what each part of it does.
|
|
489
489
|
|
|
490
490
|
## Next Steps
|
|
491
491
|
|
|
@@ -808,7 +808,7 @@ It should return `"function"` in a browser that supports registration. If it ret
|
|
|
808
808
|
[Permissions](./agents.md#permissions) shows how to limit the actions an agent can run. [Observe Changes](./agents.md#observe-changes) keeps it informed when you change the UI. Use the [Reference](./agents.md#reference) to look up the bridge's options and results.
|
|
809
809
|
|
|
810
810
|
|
|
811
|
-
#
|
|
811
|
+
# The Agent Key
|
|
812
812
|
|
|
813
813
|
Let an agent use the components you build with definePrimitive, wherever they're rendered.
|
|
814
814
|
|
|
@@ -816,6 +816,8 @@ A component you build with [`definePrimitive`](./core.md#define-a-primitive) sho
|
|
|
816
816
|
|
|
817
817
|
You write the key once, in the component. Anyone who renders the component gets it: an app that installs your rating from npm [creates the bridge](./agents.md#create-the-bridge), renders `<Rating>`, and its agent can rate, with no tool or schema to write.
|
|
818
818
|
|
|
819
|
+
ui-sdk's components use the same key. A Checkbox has `agent: { actions: ["setChecked"] }`. You'll find a few more [at the end of this page](#in-ui-sdks-components).
|
|
820
|
+
|
|
819
821
|
## Try It
|
|
820
822
|
|
|
821
823
|
This rating has `agent: { actions: ["rate"] }`. Press **Read the page** to see what an agent sees, then **Ask for 4 stars** to send the step an agent would send.
|
|
@@ -845,9 +847,17 @@ const rating = definePrimitive({
|
|
|
845
847
|
})
|
|
846
848
|
```
|
|
847
849
|
|
|
848
|
-
`actions` lists the API methods an agent can call. Put `agent`
|
|
850
|
+
`actions` lists the API methods an agent can call. Put `agent` after `api`.
|
|
851
|
+
|
|
852
|
+
Then give the rating a name where you render it:
|
|
853
|
+
|
|
854
|
+
```tsx
|
|
855
|
+
<Rating aria-label="Your rating">
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
The name is the rating's `label` in the snapshot, and a step can use it as its `ref`. A rating is a `group`, and a group doesn't take its name from the text inside it, so it needs `aria-label`, or `aria-labelledby` pointing at a visible label. A screen reader announces the same name.
|
|
849
859
|
|
|
850
|
-
With the key, the snapshot lists `rate`:
|
|
860
|
+
With the key and the name, the snapshot lists `rate`:
|
|
851
861
|
|
|
852
862
|
```json
|
|
853
863
|
[
|
|
@@ -865,18 +875,45 @@ And an agent can call it with the arguments the method takes:
|
|
|
865
875
|
|
|
866
876
|
```ts
|
|
867
877
|
await agent.act({ steps: [{ ref: "Your rating", action: "rate", args: [4] }] })
|
|
868
|
-
// { ok: true, steps: [{ ref: "c1", changes: [{ key: "value", value: 4, ... }] }], ... }
|
|
869
878
|
```
|
|
870
879
|
|
|
880
|
+
The step returns `ok: true` and what it changed: the rating's `value` is now `4`.
|
|
881
|
+
|
|
871
882
|
The change goes through `createChange`, so the app's `onValueChange` sees `details.source === "agent"` and can cancel it, like any other change. [Permissions](./agents.md#permissions) covers that.
|
|
872
883
|
|
|
873
884
|
## Choose What an Agent Calls
|
|
874
885
|
|
|
875
|
-
Only the methods in `actions` are offered. The rest of your API, like a `keydown` handler or a roving focus helper, stays private to your component, and a step that names one is refused
|
|
886
|
+
Only the methods in `actions` are offered. The rest of your API, like a `keydown` handler or a roving focus helper, stays private to your component, and a step that names one is refused:
|
|
887
|
+
|
|
888
|
+
```txt
|
|
889
|
+
rating c1 takes no keydown now. It takes: rate.
|
|
890
|
+
```
|
|
876
891
|
|
|
877
892
|
If `actions` names a method your API doesn't have, development builds warn, so a typo shows up right away.
|
|
878
893
|
|
|
879
|
-
Without
|
|
894
|
+
## Without the Key
|
|
895
|
+
|
|
896
|
+
Without an `agent` key, the bridge guesses from method names: `set` followed by a capital letter, like `setValue`, and verbs like `open`, `toggle` or `clear`.
|
|
897
|
+
|
|
898
|
+
A popover built on `createPopup` gets `setOpen` from it:
|
|
899
|
+
|
|
900
|
+
```ts
|
|
901
|
+
api: (context) => createPopup(context, { preset: popoverPreset }),
|
|
902
|
+
```
|
|
903
|
+
|
|
904
|
+
It has no `agent` key, and an agent can open it:
|
|
905
|
+
|
|
906
|
+
```json
|
|
907
|
+
{
|
|
908
|
+
"ref": "c1",
|
|
909
|
+
"component": "share",
|
|
910
|
+
"actions": ["setOpen", "press"],
|
|
911
|
+
"label": "Share",
|
|
912
|
+
"open": false
|
|
913
|
+
}
|
|
914
|
+
```
|
|
915
|
+
|
|
916
|
+
The bridge can't guess `rate`. Without the key, the rating would show `"actions": []`, and a step that asks for `rate` would get:
|
|
880
917
|
|
|
881
918
|
```txt
|
|
882
919
|
rating c1 takes no rate now. It takes: nothing.
|
|
@@ -884,6 +921,67 @@ rating c1 takes no rate now. It takes: nothing.
|
|
|
884
921
|
|
|
885
922
|
Listing your actions makes the component say exactly what it does, whatever its methods are called.
|
|
886
923
|
|
|
924
|
+
## Arguments
|
|
925
|
+
|
|
926
|
+
A step's `args` become the method's arguments. This board has two actions. `moveCard` takes a card and a column, and `addCard` takes a title:
|
|
927
|
+
|
|
928
|
+
```ts title="board.ts"
|
|
929
|
+
const columns = ["todo", "doing", "done"]
|
|
930
|
+
|
|
931
|
+
const board = definePrimitive({
|
|
932
|
+
name: "board",
|
|
933
|
+
state: () => ({
|
|
934
|
+
value: { "Fix login": "todo", "Write docs": "doing" } as Record<
|
|
935
|
+
string,
|
|
936
|
+
string
|
|
937
|
+
>,
|
|
938
|
+
}),
|
|
939
|
+
api: (context) => {
|
|
940
|
+
const change = createChange(context)
|
|
941
|
+
const cards = () => context.store.get().value
|
|
942
|
+
return {
|
|
943
|
+
moveCard: (card: string, column: string) => {
|
|
944
|
+
if (!columns.includes(column)) {
|
|
945
|
+
throw new Error(
|
|
946
|
+
`No column "${column}". Columns: ${columns.join(", ")}.`
|
|
947
|
+
)
|
|
948
|
+
}
|
|
949
|
+
return change(
|
|
950
|
+
"value",
|
|
951
|
+
{ ...cards(), [card]: column },
|
|
952
|
+
{ reason: "drag" }
|
|
953
|
+
)
|
|
954
|
+
},
|
|
955
|
+
addCard: (card: string) =>
|
|
956
|
+
change("value", { ...cards(), [card]: "todo" }, { reason: "input" }),
|
|
957
|
+
}
|
|
958
|
+
},
|
|
959
|
+
slots: (slot) => ({
|
|
960
|
+
root: slot({ attrs: () => ({ role: "group" }) }),
|
|
961
|
+
}),
|
|
962
|
+
agent: { actions: ["moveCard", "addCard"] },
|
|
963
|
+
})
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
An agent can move one card and add another in the same call:
|
|
967
|
+
|
|
968
|
+
```ts
|
|
969
|
+
await agent.act({
|
|
970
|
+
steps: [
|
|
971
|
+
{ ref: "Sprint board", action: "moveCard", args: ["Fix login", "done"] },
|
|
972
|
+
{ ref: "Sprint board", action: "addCard", args: ["Write tests"] },
|
|
973
|
+
],
|
|
974
|
+
})
|
|
975
|
+
```
|
|
976
|
+
|
|
977
|
+
The bridge doesn't check the arguments of your own methods, so check them yourself, the way `moveCard` checks the column. When a method throws, the step fails with your message, and the steps after it don't run:
|
|
978
|
+
|
|
979
|
+
```txt
|
|
980
|
+
No column "shipped". Columns: todo, doing, done.
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
An action can also return a promise. The bridge doesn't wait for it to resolve, so the step's result is `"pending"`. If the promise rejects before the step ends, the step fails with its message.
|
|
984
|
+
|
|
887
985
|
## Lists
|
|
888
986
|
|
|
889
987
|
When your component's value is always one of its items, like a size picker, add `closed: true`:
|
|
@@ -904,7 +1002,9 @@ The bridge reads the items from your state's `items`. If they live somewhere els
|
|
|
904
1002
|
agent: { actions: ["setValue"], items: (api) => api.allItems() },
|
|
905
1003
|
```
|
|
906
1004
|
|
|
907
|
-
|
|
1005
|
+
`items` reads your API, which is why `agent` goes after `api`. Placed before it, TypeScript reports that `allItems` doesn't exist.
|
|
1006
|
+
|
|
1007
|
+
The snapshot lists the items with the component: the ones on the page, or the ones in your data when there are 10 or fewer. Longer lists come back from `query({ within })`. With an `items` function that works for any action, not only `setValue`, so a stepper's `goTo` shows its steps.
|
|
908
1008
|
|
|
909
1009
|
## Content Behind Items
|
|
910
1010
|
|
|
@@ -914,6 +1014,12 @@ Tabs and accordions hide other components behind their closed items. Add `reveal
|
|
|
914
1014
|
agent: { actions: ["setValue"], closed: true, reveals: true },
|
|
915
1015
|
```
|
|
916
1016
|
|
|
1017
|
+
For a setup flow on its Account step, a step that asks for a field on another step gets:
|
|
1018
|
+
|
|
1019
|
+
```txt
|
|
1020
|
+
No component "Card number" on the page. Its labels: Setup. It may be behind one of these, which a step can open first: Setup (c1): Billing, Team.
|
|
1021
|
+
```
|
|
1022
|
+
|
|
917
1023
|
## Show It When It Matters
|
|
918
1024
|
|
|
919
1025
|
`shown` decides whether an agent sees the component right now. A field wrapper, for example, only needs to show while it has errors, since its input already carries the label:
|
|
@@ -932,6 +1038,20 @@ agent: { actions: ["setValue", "clear"], secret: true },
|
|
|
932
1038
|
|
|
933
1039
|
To hide one particular field instead, the app can mark it with `data-agent-secret`. See [Permissions](./agents.md#permissions).
|
|
934
1040
|
|
|
1041
|
+
## In ui-sdk's Components
|
|
1042
|
+
|
|
1043
|
+
These are the `agent` keys of a few ui-sdk components, as they're written in `@ui-sdk/core`:
|
|
1044
|
+
|
|
1045
|
+
| Component | `agent` |
|
|
1046
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
1047
|
+
| Checkbox | `{ actions: ["setChecked"] }` |
|
|
1048
|
+
| Number Input | `{ actions: ["setValue", "increment", "decrement"] }` |
|
|
1049
|
+
| Select | `{ actions: ["setOpen", "setValue", "clear", "setQuery"], closed: true }` |
|
|
1050
|
+
| Tabs | `{ actions: ["setValue"], closed: true, reveals: true }` |
|
|
1051
|
+
| Accordion | `{ actions: ["setValue", "open", "close", "toggle", "openAll", "closeAll"], closed: true, reveals: true }` |
|
|
1052
|
+
| OTP Input | `{ actions: ["setValue", "clear"], secret: true }` |
|
|
1053
|
+
| Field | `{ shown: (state) => !!state.errors.length }` |
|
|
1054
|
+
|
|
935
1055
|
## API Reference
|
|
936
1056
|
|
|
937
1057
|
| Key | Type | Description |
|
|
@@ -941,7 +1061,7 @@ To hide one particular field instead, the app can mark it with `data-agent-secre
|
|
|
941
1061
|
| `items` | `(api) => unknown` | The items as data, when they aren't the state's `items`. |
|
|
942
1062
|
| `reveals` | `boolean` | Closed items hide other components. A component the agent can't find is reported as maybe behind them. |
|
|
943
1063
|
| `shown` | `(state) => boolean` | Whether an agent sees the component right now. |
|
|
944
|
-
| `secret` | `boolean` |
|
|
1064
|
+
| `secret` | `boolean` | A filled value reads `"[redacted]"` in the snapshot, in step results and in `observe`. |
|
|
945
1065
|
|
|
946
1066
|
The `agent` key is experimental.
|
|
947
1067
|
|
|
@@ -1053,6 +1173,8 @@ Two more marks change what the agent sees:
|
|
|
1053
1173
|
|
|
1054
1174
|
Changes inside `data-agent-hidden` still reach [Observe](./agents.md#observe-changes), so your own logs see them, while `agent.subscribe` stays quiet. A secret value stays out of `snapshot`, `act` results and change events, and the field's error text reads `"[redacted]"` too. A secret File Input lists its files without their names. Password, card and one-time-code fields are treated as secret without a mark. A hidden input is left out without one.
|
|
1055
1175
|
|
|
1176
|
+
The agent reaches what a person can reach. A component hidden with CSS, the `hidden` attribute, a closed `<details>` or `aria-hidden="true"` is left out without a mark. A component in an `inert` region, like the page behind a modal dialog, is listed as disabled until the region is usable again.
|
|
1177
|
+
|
|
1056
1178
|
In development, a misspelled mark such as `data-agent-confim` logs a warning with the name it meant.
|
|
1057
1179
|
|
|
1058
1180
|
## Cancel a Value Change
|
|
@@ -1460,7 +1582,7 @@ The bridge tries these in order and uses the first that fits:
|
|
|
1460
1582
|
|
|
1461
1583
|
Names match regardless of case and accents, so `"Region"` finds "Région" and `"strasse"` finds "Straße".
|
|
1462
1584
|
|
|
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
|
|
1585
|
+
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.
|
|
1464
1586
|
|
|
1465
1587
|
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.
|
|
1466
1588
|
|
|
@@ -1571,9 +1693,9 @@ const sizePicker = definePrimitive({
|
|
|
1571
1693
|
| `items` | A function from the api to its items, when they aren't in the state's `items`. |
|
|
1572
1694
|
| `reveals` | Its closed items hide other components, like tabs. When a step names a component it can't find, the error lists them. |
|
|
1573
1695
|
| `shown` | A function from the state that says whether the agent sees it now, like a field only while it has errors. |
|
|
1574
|
-
| `secret` | Its value
|
|
1696
|
+
| `secret` | Its value reads `"[redacted]"` once it's filled, like a password's. |
|
|
1575
1697
|
|
|
1576
|
-
[
|
|
1698
|
+
[The Agent Key](./agents.md#the-agent-key) walks through each key with examples.
|
|
1577
1699
|
|
|
1578
1700
|
Without `actions`, the bridge picks methods by name: `set` followed by a capital letter, such as `setValue`, and these verbs alone or followed by a capital letter:
|
|
1579
1701
|
|
|
@@ -1102,6 +1102,7 @@ Runs in React, Vue and web components.
|
|
|
1102
1102
|
- Side="start" comes from the right in a right-to-left layout.
|
|
1103
1103
|
- Side="end" comes from the left in a right-to-left layout.
|
|
1104
1104
|
- A drag toward the start edge closes it in a right-to-left layout.
|
|
1105
|
+
- Side="top" stays at the top in a right-to-left layout.
|
|
1105
1106
|
|
|
1106
1107
|
Runs in React, Vue and web components.
|
|
1107
1108
|
|
package/docs/core.md
CHANGED
|
@@ -610,7 +610,7 @@ The `agent` key tells [the agent bridge](./agents.md#custom-primitives) which ap
|
|
|
610
610
|
agent: { actions: ["setValue", "clear"], closed: true },
|
|
611
611
|
```
|
|
612
612
|
|
|
613
|
-
Put it
|
|
613
|
+
Put it after `api`, so its `items` function can read the api's types. Without it, the bridge picks methods named like changes, such as `setValue` or `toggle`. [The Agent Key](./agents.md#the-agent-key) shows a rating an agent can use, and every part of the key.
|
|
614
614
|
|
|
615
615
|
## Naming
|
|
616
616
|
|
|
@@ -1473,6 +1473,7 @@ export { rating, type RatingOptions }
|
|
|
1473
1473
|
|
|
1474
1474
|
Next, [Handle Changes](./core.md#handle-changes) goes further into the change pattern the rating uses: callbacks, controlled state, commits and undo.
|
|
1475
1475
|
|
|
1476
|
+
- [Customize a Behavior](./core.md#customize-a-behavior) adds keys to this rating and changes its rules.
|
|
1476
1477
|
- [Focus](./core.md#focus-and-keys) covers grids and other ways to move through a group.
|
|
1477
1478
|
- [Testing](./core.md#testing) checks the component's keyboard behavior and accessibility.
|
|
1478
1479
|
|
|
@@ -2031,7 +2032,375 @@ A controlled drag has one more timing concern: its draft may need to stay visibl
|
|
|
2031
2032
|
|
|
2032
2033
|
## Next
|
|
2033
2034
|
|
|
2034
|
-
|
|
2035
|
+
Next, [Customize a Behavior](./core.md#customize-a-behavior) changes the keys and rules of a behavior you imported. That's the last Core guide. [Reference](./core.md#reference) lists every export by the job it does, and [Behaviors](./core.md#all-behaviors) has the building blocks for focus, selection, popups and more.
|
|
2036
|
+
|
|
2037
|
+
|
|
2038
|
+
# Customize a Behavior
|
|
2039
|
+
|
|
2040
|
+
Change a rule, add or remove a key, refuse a change, and build your own behavior on top of one.
|
|
2041
|
+
|
|
2042
|
+
[Compose Behaviors](./core.md#compose-behaviors) built a rating from `createChange` and `createRovingFocus`. Each behavior came with rules of its own: roving focus decides which keys move focus, where each one goes, and which star Tab lands on. When your component needs something different, keep the behavior and change it in one of these places:
|
|
2043
|
+
|
|
2044
|
+
| You Want To | Where |
|
|
2045
|
+
| ----------------------------------------- | ---------------------------------------------------- |
|
|
2046
|
+
| Change one of its rules | [An option](#change-a-rule) |
|
|
2047
|
+
| Add a key, or take one away | [Your `api`, around the call](#add-a-key) |
|
|
2048
|
+
| Choose what happens after it runs | [What the call returns](#choose-what-a-move-does) |
|
|
2049
|
+
| Reuse your version in other components | [A function around the behavior](#extend-a-behavior) |
|
|
2050
|
+
| Change a behavior other than roving focus | [The same places, by behavior](#other-behaviors) |
|
|
2051
|
+
| Stop a change from outside | [The change callback](#refuse-a-change) |
|
|
2052
|
+
| Take a key from outside the component | [Your own event handler](#handle-an-event-first) |
|
|
2053
|
+
|
|
2054
|
+
We'll keep working on [that rating](./core.md#complete-primitive). Each step changes a few lines of `rating.ts` or the code that renders it.
|
|
2055
|
+
|
|
2056
|
+
## Change a Rule
|
|
2057
|
+
|
|
2058
|
+
Each rule a behavior follows is an option. The rating wraps from the last star to the first because it passes `loop`. To stop at either end, change that option in `createRovingFocus`:
|
|
2059
|
+
|
|
2060
|
+
```ts
|
|
2061
|
+
loop: () => false,
|
|
2062
|
+
```
|
|
2063
|
+
|
|
2064
|
+
Most options are functions, so a rule can depend on state or on the component's own options. They run each time the behavior needs an answer.
|
|
2065
|
+
|
|
2066
|
+
Start here for any behavior: its options are listed with its guide, and [All Behaviors](./core.md#all-behaviors) links to each one. For roving focus, [Focus and Keys](./core.md#roving-focus) covers `orientation`, `loop`, `disabled`, `focusable`, `preferred` and `remember`.
|
|
2067
|
+
|
|
2068
|
+
One option goes further. `move` replaces every built-in key, which fits a layout the built-in keys don't describe, such as a [keypad](./core.md#any-layout). To add one key and keep the rest, wrap the call.
|
|
2069
|
+
|
|
2070
|
+
## Add a Key
|
|
2071
|
+
|
|
2072
|
+
Roving focus doesn't listen for keys by itself. The star's `keydown` handler calls `api.keydown`, and that calls `roving.keydown`. The call is yours, so you can handle a key before the behavior sees it.
|
|
2073
|
+
|
|
2074
|
+
Let's make the number keys jump to a star. Update `keydown` in the object returned from `api`:
|
|
2075
|
+
|
|
2076
|
+
```ts {2-14}
|
|
2077
|
+
keydown(event: KeyboardEvent, el: HTMLElement) {
|
|
2078
|
+
const modified = event.ctrlKey || event.metaKey || event.altKey
|
|
2079
|
+
const star = modified
|
|
2080
|
+
? undefined
|
|
2081
|
+
: roving.items().find((item) => item.key === event.key)
|
|
2082
|
+
if (star) {
|
|
2083
|
+
event.preventDefault()
|
|
2084
|
+
roving.focus(star.key)
|
|
2085
|
+
change("value", Number(star.key), {
|
|
2086
|
+
reason: "list-navigation",
|
|
2087
|
+
event,
|
|
2088
|
+
})
|
|
2089
|
+
return
|
|
2090
|
+
}
|
|
2091
|
+
|
|
2092
|
+
const moved = roving.keydown(event, el)
|
|
2093
|
+
if (moved) {
|
|
2094
|
+
change("value", Number(moved.key), {
|
|
2095
|
+
reason: "list-navigation",
|
|
2096
|
+
event,
|
|
2097
|
+
})
|
|
2098
|
+
}
|
|
2099
|
+
},
|
|
2100
|
+
```
|
|
2101
|
+
|
|
2102
|
+
- `roving.items()` returns the stars that can take focus. Each star's key is its value, so pressing 4 finds the fourth star.
|
|
2103
|
+
- `roving.focus(key)` moves focus to that star. The tab stop follows the new rating, as it did before.
|
|
2104
|
+
- Every other key still reaches `roving.keydown`, so the arrows, Home and End work as before.
|
|
2105
|
+
|
|
2106
|
+
Focus a star and press 4. The arrows, Home and End still work.
|
|
2107
|
+
|
|
2108
|
+
## Take a Key Away
|
|
2109
|
+
|
|
2110
|
+
To drop a key, return before the call. Add this at the top of `keydown`, and Home and End no longer change the rating:
|
|
2111
|
+
|
|
2112
|
+
```ts
|
|
2113
|
+
if (event.key === "Home" || event.key === "End") {
|
|
2114
|
+
return
|
|
2115
|
+
}
|
|
2116
|
+
```
|
|
2117
|
+
|
|
2118
|
+
The behavior never sees the key, so the browser handles it as usual.
|
|
2119
|
+
|
|
2120
|
+
## Choose What a Move Does
|
|
2121
|
+
|
|
2122
|
+
`roving.keydown` moves focus and tells you where it went. It returns `key`, the item it moved to, `from`, the item it left, and `shift`, whether Shift was held. For a key that isn't its own, it returns `undefined`.
|
|
2123
|
+
|
|
2124
|
+
What a move means is up to the component. The rating selects the star it lands on:
|
|
2125
|
+
|
|
2126
|
+
```ts
|
|
2127
|
+
const moved = roving.keydown(event, el)
|
|
2128
|
+
if (moved) {
|
|
2129
|
+
change("value", Number(moved.key), { reason: "list-navigation", event })
|
|
2130
|
+
}
|
|
2131
|
+
```
|
|
2132
|
+
|
|
2133
|
+
A row of buttons can ignore the result, so focus moves and nothing else changes. A file list uses `shift` to extend a selection, as [Ranges and Select All](./core.md#ranges-and-select-all) shows.
|
|
2134
|
+
|
|
2135
|
+
## Extend a Behavior
|
|
2136
|
+
|
|
2137
|
+
The number keys now live inside the rating. To use them in other components, move them into a function that wraps the behavior and returns it with your `keydown` in place of the original:
|
|
2138
|
+
|
|
2139
|
+
```ts title="number-keys.ts"
|
|
2140
|
+
import {
|
|
2141
|
+
createRovingFocus,
|
|
2142
|
+
type PrimitiveContext,
|
|
2143
|
+
type RovingFocusOptions,
|
|
2144
|
+
} from "@ui-sdk/core"
|
|
2145
|
+
|
|
2146
|
+
function createNumberKeys<State extends object>(
|
|
2147
|
+
context: PrimitiveContext<any, State, any>,
|
|
2148
|
+
options: RovingFocusOptions<State>
|
|
2149
|
+
) {
|
|
2150
|
+
const roving = createRovingFocus(context, options)
|
|
2151
|
+
|
|
2152
|
+
return {
|
|
2153
|
+
...roving,
|
|
2154
|
+
keydown(event: KeyboardEvent, el: HTMLElement) {
|
|
2155
|
+
const modified = event.ctrlKey || event.metaKey || event.altKey
|
|
2156
|
+
const items = roving.items()
|
|
2157
|
+
const from = items.find((item) => item.el === el)
|
|
2158
|
+
const to = modified
|
|
2159
|
+
? undefined
|
|
2160
|
+
: items.find((item) => item.key === event.key)
|
|
2161
|
+
if (from && to) {
|
|
2162
|
+
event.preventDefault()
|
|
2163
|
+
roving.focus(to.key)
|
|
2164
|
+
return { key: to.key, from: from.key, shift: event.shiftKey }
|
|
2165
|
+
}
|
|
2166
|
+
|
|
2167
|
+
return roving.keydown(event, el)
|
|
2168
|
+
},
|
|
2169
|
+
}
|
|
2170
|
+
}
|
|
2171
|
+
|
|
2172
|
+
export { createNumberKeys }
|
|
2173
|
+
```
|
|
2174
|
+
|
|
2175
|
+
- It takes the same `context` and options as `createRovingFocus`, so each component still passes its own rules.
|
|
2176
|
+
- `...roving` keeps `bind`, `tabIndex`, `items` and the rest.
|
|
2177
|
+
- Its `keydown` returns the same result as the original, so a component treats a number key like any other move.
|
|
2178
|
+
|
|
2179
|
+
In `rating.ts`, call `createNumberKeys` in place of `createRovingFocus` and leave its options as they are. `keydown` goes back to what it was in Compose Behaviors:
|
|
2180
|
+
|
|
2181
|
+
```ts
|
|
2182
|
+
keydown(event: KeyboardEvent, el: HTMLElement) {
|
|
2183
|
+
const moved = roving.keydown(event, el)
|
|
2184
|
+
if (moved) {
|
|
2185
|
+
change("value", Number(moved.key), { reason: "list-navigation", event })
|
|
2186
|
+
}
|
|
2187
|
+
},
|
|
2188
|
+
```
|
|
2189
|
+
|
|
2190
|
+
Any group whose keys are numbers can use it now. A row of page buttons passes its own slot and `orientation`, and gets the number keys with them.
|
|
2191
|
+
|
|
2192
|
+
Your `keydown` runs wherever your component calls it. You can replace `focus` or `tabIndex` the same way. Inside, the behavior keeps using its own methods: when focus lands on an item, it calls the original `remember`. To change what it does by itself, use its options.
|
|
2193
|
+
|
|
2194
|
+
## Other Behaviors
|
|
2195
|
+
|
|
2196
|
+
The other behaviors change in the same places. Their rules are options too. Where roving focus returns each move from `keydown`, a behavior that changes a value hands you the value to write, through `set`.
|
|
2197
|
+
|
|
2198
|
+
A selection writes each new value through `set`, so a limit goes there. This one allows three toppings:
|
|
2199
|
+
|
|
2200
|
+
```ts
|
|
2201
|
+
const selection = createSelection(context, {
|
|
2202
|
+
key: "value",
|
|
2203
|
+
set: (value, details) => value.length <= 3 && change("value", value, details),
|
|
2204
|
+
order: () => roving.items().map((item) => item.key),
|
|
2205
|
+
multiple: () => true,
|
|
2206
|
+
})
|
|
2207
|
+
```
|
|
2208
|
+
|
|
2209
|
+
`set` returns whether the value went through. Returning `false` leaves the selection as it was.
|
|
2210
|
+
|
|
2211
|
+
Here's where to look in the behaviors you'll use most. Each name links to its guide:
|
|
2212
|
+
|
|
2213
|
+
| Behavior | Rules You Can Change | What It Hands You |
|
|
2214
|
+
| ------------------------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------- |
|
|
2215
|
+
| [`createRovingFocus`](./core.md#roving-focus) | `orientation`, `loop`, `disabled`, `focusable`, `move` | Each move, returned from `keydown` |
|
|
2216
|
+
| [`createGridFocus`](./core.md#grids) | `disabled`, `pageSize` | Each move, in `onMove` |
|
|
2217
|
+
| [`createSelection`](./core.md#selecting-items) | `multiple`, `selectable` | Each selection, in `set` |
|
|
2218
|
+
| [`createListbox`](./core.md#options-you-search) | `filter`, `loop` | Each highlight, in `onHighlight` |
|
|
2219
|
+
| [`createReorder`](./core.md#reordering) | `orientation`, `group`, `disabled` | Each order, in `set`, and each announcement, in `message` |
|
|
2220
|
+
| [`createTransfer`](./core.md#moving-between-lists) | `accepts`, `order`, `disabled` | Each move between lists, in `set`, and each announcement, in `message` |
|
|
2221
|
+
| [`createMove`](./core.md#moving-in-two-dimensions) | `bounds`, `step`, `disabled` | Each position, in `set`, and each announcement, in `message` |
|
|
2222
|
+
| [`createResize`](./core.md#resizing-boxes) | `min`, `max`, `aspect`, `bounds` | Each size, in `set`, and each announcement, in `message` |
|
|
2223
|
+
| [`createPopup`](./core.md#pick-its-behavior) | A preset, and `role` | Each open and close, in `onOpenChange` |
|
|
2224
|
+
|
|
2225
|
+
A `message` can reword one announcement and keep the others, since each default is exported: `reorderMessage`, `transferMessage`, `moveMessage` and `resizeMessage`. [What's Read Out](./core.md#whats-read-out) shows one.
|
|
2226
|
+
|
|
2227
|
+
## Refuse a Change
|
|
2228
|
+
|
|
2229
|
+
The next two steps need no changes to `rating.ts`. They're for whoever renders the rating.
|
|
2230
|
+
|
|
2231
|
+
Every change the rating makes goes through `change`, which calls `onValueChange` before it writes the value. The callback can refuse. Here a review form keeps the value as it is while it saves:
|
|
2232
|
+
|
|
2233
|
+
**React**
|
|
2234
|
+
|
|
2235
|
+
```tsx
|
|
2236
|
+
<Rating
|
|
2237
|
+
aria-label="Rating"
|
|
2238
|
+
onValueChange={(value, details) => {
|
|
2239
|
+
if (saving) {
|
|
2240
|
+
details.cancel()
|
|
2241
|
+
}
|
|
2242
|
+
}}
|
|
2243
|
+
>
|
|
2244
|
+
{children}
|
|
2245
|
+
</Rating>
|
|
2246
|
+
```
|
|
2247
|
+
|
|
2248
|
+
**Vue**
|
|
2249
|
+
|
|
2250
|
+
```vue
|
|
2251
|
+
<Rating
|
|
2252
|
+
aria-label="Rating"
|
|
2253
|
+
@value-change="(value, details) => saving && details.cancel()"
|
|
2254
|
+
>
|
|
2255
|
+
<slot />
|
|
2256
|
+
</Rating>
|
|
2257
|
+
```
|
|
2258
|
+
|
|
2259
|
+
**Svelte**
|
|
2260
|
+
|
|
2261
|
+
```svelte
|
|
2262
|
+
<Rating
|
|
2263
|
+
aria-label="Rating"
|
|
2264
|
+
onValueChange={(value, details) => {
|
|
2265
|
+
if (saving) {
|
|
2266
|
+
details.cancel()
|
|
2267
|
+
}
|
|
2268
|
+
}}
|
|
2269
|
+
>
|
|
2270
|
+
{@render children()}
|
|
2271
|
+
</Rating>
|
|
2272
|
+
```
|
|
2273
|
+
|
|
2274
|
+
**Solid**
|
|
2275
|
+
|
|
2276
|
+
```tsx
|
|
2277
|
+
<Rating
|
|
2278
|
+
aria-label="Rating"
|
|
2279
|
+
onValueChange={(value, details) => {
|
|
2280
|
+
if (saving()) {
|
|
2281
|
+
details.cancel()
|
|
2282
|
+
}
|
|
2283
|
+
}}
|
|
2284
|
+
>
|
|
2285
|
+
{props.children}
|
|
2286
|
+
</Rating>
|
|
2287
|
+
```
|
|
2288
|
+
|
|
2289
|
+
**Web Components**
|
|
2290
|
+
|
|
2291
|
+
```ts
|
|
2292
|
+
const rating = document.querySelector<HTMLElement>("my-rating")!
|
|
2293
|
+
|
|
2294
|
+
rating.addEventListener("valuechange", (event) => {
|
|
2295
|
+
if (saving) {
|
|
2296
|
+
event.preventDefault()
|
|
2297
|
+
}
|
|
2298
|
+
})
|
|
2299
|
+
```
|
|
2300
|
+
|
|
2301
|
+
It refuses a press, an arrow key and a number key alike, since they all ask through `change`. To refuse only some of them, check `details.reason`: the rating reports `item-press` and `list-navigation`. [What a Change Reports](./core.md#what-a-change-reports) lists everything a callback gets.
|
|
2302
|
+
|
|
2303
|
+
Focus still follows the keys while a change is refused. Only the value stays.
|
|
2304
|
+
|
|
2305
|
+
`cancel()` refuses a change the rating would write itself. If you pass `value`, you decide instead: keep the old value and the rating stays where it is.
|
|
2306
|
+
|
|
2307
|
+
## Handle an Event First
|
|
2308
|
+
|
|
2309
|
+
An event handler you pass to a part runs before the part's own. Call `event.preventDefault()` and the part skips its handler for that event.
|
|
2310
|
+
|
|
2311
|
+
Say the rating sits in a table row, where Up and Down move between rows. Take those two keys and leave the others to the rating:
|
|
2312
|
+
|
|
2313
|
+
**React**
|
|
2314
|
+
|
|
2315
|
+
```tsx
|
|
2316
|
+
<RatingStar
|
|
2317
|
+
value="3"
|
|
2318
|
+
onKeyDown={(event) => {
|
|
2319
|
+
if (event.key === "ArrowUp" || event.key === "ArrowDown") {
|
|
2320
|
+
event.preventDefault()
|
|
2321
|
+
moveRow(event.key)
|
|
2322
|
+
}
|
|
2323
|
+
}}
|
|
2324
|
+
/>
|
|
2325
|
+
```
|
|
2326
|
+
|
|
2327
|
+
**Vue**
|
|
2328
|
+
|
|
2329
|
+
```vue
|
|
2330
|
+
<script setup lang="ts">
|
|
2331
|
+
function onKeydown(event: KeyboardEvent) {
|
|
2332
|
+
if (event.key === "ArrowUp" || event.key === "ArrowDown") {
|
|
2333
|
+
event.preventDefault()
|
|
2334
|
+
moveRow(event.key)
|
|
2335
|
+
}
|
|
2336
|
+
}
|
|
2337
|
+
</script>
|
|
2338
|
+
|
|
2339
|
+
<template>
|
|
2340
|
+
<RatingStar value="3" @keydown="onKeydown" />
|
|
2341
|
+
</template>
|
|
2342
|
+
```
|
|
2343
|
+
|
|
2344
|
+
**Svelte**
|
|
2345
|
+
|
|
2346
|
+
```svelte
|
|
2347
|
+
<RatingStar
|
|
2348
|
+
value="3"
|
|
2349
|
+
onkeydown={(event) => {
|
|
2350
|
+
if (event.key === "ArrowUp" || event.key === "ArrowDown") {
|
|
2351
|
+
event.preventDefault()
|
|
2352
|
+
moveRow(event.key)
|
|
2353
|
+
}
|
|
2354
|
+
}}
|
|
2355
|
+
/>
|
|
2356
|
+
```
|
|
2357
|
+
|
|
2358
|
+
**Solid**
|
|
2359
|
+
|
|
2360
|
+
```tsx
|
|
2361
|
+
<RatingStar
|
|
2362
|
+
value="3"
|
|
2363
|
+
onKeyDown={(event) => {
|
|
2364
|
+
if (event.key === "ArrowUp" || event.key === "ArrowDown") {
|
|
2365
|
+
event.preventDefault()
|
|
2366
|
+
moveRow(event.key)
|
|
2367
|
+
}
|
|
2368
|
+
}}
|
|
2369
|
+
/>
|
|
2370
|
+
```
|
|
2371
|
+
|
|
2372
|
+
**Web Components**
|
|
2373
|
+
|
|
2374
|
+
```ts
|
|
2375
|
+
const rating = document.querySelector<HTMLElement>("my-rating")!
|
|
2376
|
+
|
|
2377
|
+
rating.addEventListener(
|
|
2378
|
+
"keydown",
|
|
2379
|
+
(event) => {
|
|
2380
|
+
if (event.key === "ArrowUp" || event.key === "ArrowDown") {
|
|
2381
|
+
event.preventDefault()
|
|
2382
|
+
moveRow(event.key)
|
|
2383
|
+
}
|
|
2384
|
+
},
|
|
2385
|
+
{ capture: true }
|
|
2386
|
+
)
|
|
2387
|
+
```
|
|
2388
|
+
|
|
2389
|
+
Listen in the capture phase, on the rating or anything around it. The star's own listener is on its button, so a plain listener added to that button later runs after it.
|
|
2390
|
+
|
|
2391
|
+
Left, Right, Home, End and the number keys still belong to the rating. `preventDefault()` also stops what the browser would do with the key, such as scrolling the page.
|
|
2392
|
+
|
|
2393
|
+
Both work the same way on the ready-made components, since they're built from the same pieces. [Tabs](./components/tabs.md) takes `onValueChange` with `details.cancel()`, and a key handler on its list runs before the arrow keys do. With web components, listen in the capture phase there too.
|
|
2394
|
+
|
|
2395
|
+
## Replace One Behavior
|
|
2396
|
+
|
|
2397
|
+
Behaviors don't know about each other. The rating's `createChange` and `createRovingFocus` meet only in your `api`. So when a component needs focus rules of its own, you can write that one piece yourself and keep the rest: changes, callbacks and controlled state stay as they are.
|
|
2398
|
+
|
|
2399
|
+
## Keep Building
|
|
2400
|
+
|
|
2401
|
+
- [Focus and Keys](./core.md#focus-and-keys) has every roving focus option, with a demo for each.
|
|
2402
|
+
- [Handle Changes](./core.md#handle-changes) goes further into callbacks, reasons and controlled state.
|
|
2403
|
+
- [Testing](./core.md#testing) checks that the keyboard still matches the pattern after you change it.
|
|
2035
2404
|
|
|
2036
2405
|
|
|
2037
2406
|
# Reference
|
|
@@ -8054,7 +8423,7 @@ Set up ui-sdk in this Svelte project. It needs Svelte 5.33 or newer.
|
|
|
8054
8423
|
**Solid**
|
|
8055
8424
|
|
|
8056
8425
|
```text prompt
|
|
8057
|
-
Set up ui-sdk in this Solid project. It needs Solid 2: solid-js and @solidjs/web 2.0.0
|
|
8426
|
+
Set up ui-sdk in this Solid project. It needs Solid 2: solid-js and @solidjs/web 2.0.0 or newer.
|
|
8058
8427
|
|
|
8059
8428
|
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.
|
|
8060
8429
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ui-sdk/svelte",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.13",
|
|
4
4
|
"description": "UI SDK for Svelte.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"svelte",
|
|
@@ -381,7 +381,7 @@
|
|
|
381
381
|
],
|
|
382
382
|
"peerDependencies": {
|
|
383
383
|
"svelte": ">=5.33",
|
|
384
|
-
"@ui-sdk/core": "^0.1.0-beta.
|
|
384
|
+
"@ui-sdk/core": "^0.1.0-beta.13"
|
|
385
385
|
},
|
|
386
386
|
"devDependencies": {
|
|
387
387
|
"@sveltejs/package": "^2.5.8",
|
|
@@ -393,7 +393,7 @@
|
|
|
393
393
|
"typescript": "~5.9.3",
|
|
394
394
|
"vite": "^8.3.3",
|
|
395
395
|
"vitest": "^5.0.3",
|
|
396
|
-
"@ui-sdk/core": "0.1.0-beta.
|
|
396
|
+
"@ui-sdk/core": "0.1.0-beta.13"
|
|
397
397
|
},
|
|
398
398
|
"scripts": {
|
|
399
399
|
"build": "node ../../scripts/build/build-svelte-package.mjs",
|