@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.
@@ -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. [Your Own Components](./agents.md#your-own-components) shows how to add the key and what each part of it does.
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
- # Your Own Components
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` last, after `slots`, so TypeScript has read your API by then.
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 an `agent` key, the bridge guesses from method names: `set` followed by a capital letter, like `setValue`, and verbs like `open`, `toggle` or `clear`. It can't guess `rate`, so the rating would show `"actions": []`, and a step that asks for `rate` would get:
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
- The snapshot shows the items with the component when there are 10 or fewer and none are on the page. That works for any action, not only `setValue`, so a stepper's `goTo` shows its steps. Longer lists come back from `query({ within })`.
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` | The value is always redacted, in the snapshot, in step results and in `observe`. |
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.` 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.
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 is always redacted, like a password's. |
1696
+ | `secret` | Its value reads `"[redacted]"` once it's filled, like a password's. |
1575
1697
 
1576
- [Your Own Components](./agents.md#your-own-components) walks through each key with examples.
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 last, after `slots`, so TypeScript has read the api by then. Without it, the bridge picks methods named like changes, such as `setValue` or `toggle`. [Your Own Components](./agents.md#your-own-components) shows a rating an agent can use, and every part of the key.
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
- That covers the Core guides. [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.
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-rc.14 or newer.
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.10",
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.10"
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.10"
396
+ "@ui-sdk/core": "0.1.0-beta.13"
397
397
  },
398
398
  "scripts": {
399
399
  "build": "node ../../scripts/build/build-svelte-package.mjs",