@metamorph-labs/polymorph-angular 0.0.0-stage → 1.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +859 -0
  2. package/LICENSE +21 -0
  3. package/README.md +93 -2
  4. package/dist/conventions/cells.d.ts +89 -0
  5. package/dist/conventions/classes.d.ts +23 -0
  6. package/dist/conventions/departure.d.ts +13 -0
  7. package/dist/conventions/dev.d.ts +12 -0
  8. package/dist/conventions/direction.d.ts +10 -0
  9. package/dist/conventions/effects.d.ts +19 -0
  10. package/dist/conventions/media.d.ts +17 -0
  11. package/dist/conventions/member.d.ts +212 -0
  12. package/dist/conventions/mode.d.ts +17 -0
  13. package/dist/conventions/page-transitions.d.ts +72 -0
  14. package/dist/conventions/slots.d.ts +108 -0
  15. package/dist/conventions/states.d.ts +38 -0
  16. package/dist/conventions/theme-values.d.ts +21 -0
  17. package/dist/conventions/toast.d.ts +31 -0
  18. package/dist/conventions/types.d.ts +6 -0
  19. package/dist/conventions/typing.d.ts +18 -0
  20. package/dist/fesm2022/polymorph-angular-motion.mjs +272 -0
  21. package/dist/fesm2022/polymorph-angular-motion.mjs.map +1 -0
  22. package/dist/fesm2022/polymorph-angular.mjs +3348 -0
  23. package/dist/fesm2022/polymorph-angular.mjs.map +1 -0
  24. package/dist/icon/BrandMark.d.ts +28 -0
  25. package/dist/icon/Glyph.d.ts +24 -0
  26. package/dist/icon/Icon.d.ts +51 -0
  27. package/dist/icon/glyphs.d.ts +14 -0
  28. package/dist/index.d.ts +56 -0
  29. package/dist/motion/index.d.ts +7 -0
  30. package/dist/motion/presence.d.ts +66 -0
  31. package/dist/styles/icon/icon.module.css.d.ts +6 -0
  32. package/dist/zag/bindable.d.ts +19 -0
  33. package/dist/zag/dom.d.ts +15 -0
  34. package/dist/zag/index.d.ts +11 -0
  35. package/dist/zag/machine.d.ts +21 -0
  36. package/dist/zag/normalize-props.d.ts +12 -0
  37. package/dist/zag/spread.d.ts +16 -0
  38. package/package.json +41 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,859 @@
1
+ # @polymorph/angular
2
+
3
+ ## 1.0.16
4
+
5
+ ### Patch Changes
6
+
7
+ - e774b49: **The Angular members lay out as the other renderers' do.** Every Angular member renders inside a
8
+ host element (`<pm-card>`) that draws no box, and a recipe selector that reads a parent or a
9
+ sibling matched the host instead of the member inside it. A `Grid` drew each cell one column wide
10
+ whatever `columns` said, a `SettingsRow` after the first drew no rule above it, a
11
+ `TableOfContents` column was half its width, and a nested list in `Markdown` lost its spacing.
12
+ The Angular build now compiles each recipe with forms that also match through a host, and each
13
+ host carries `data-pm-host`, the attribute those forms read. A new law holds every Angular member
14
+ to the box it has with the hosts removed. An Angular screen that uses these members changes its
15
+ layout to the one the specs describe.
16
+
17
+ The elements' recipes gain one form of the same transform: siblings that one host holds together
18
+ after a child step (`.item > * + *`) now match through it.
19
+
20
+ - Updated dependencies [2f0ddd2]
21
+ - @polymorph/engine@1.0.16
22
+
23
+ ## 1.0.15
24
+
25
+ ### Patch Changes
26
+
27
+ - @polymorph/engine@1.0.15
28
+
29
+ ## 1.0.14
30
+
31
+ ### Patch Changes
32
+
33
+ - 9b60a94: **`ScatterChart` reports nothing where it draws no point.** A row whose x, y or bubble value is
34
+ `null` draws no point for that series. The arrow keys still reach that position, and the live
35
+ region still says it, but Enter, Space and a click there no longer call `onSelect`. Before, they
36
+ called it with `{ index, key, datum }` for a point the plot did not draw. An agent does not list
37
+ such a position among the chart's `items`, and its `choose` refuses one. The engine's
38
+ `scatterChartSelection` returns `null` there, as `heatmapSelection` does at an absent cell.
39
+
40
+ **`BarChart` reports nothing at a walked bar that is not drawn.** With the reading walked to one
41
+ series (Up and Down) at a band where that series' value is `null`, Enter, Space or a click called
42
+ `onSelect` for a bar the plot does not draw. `barChartSelection` returns `null` there. A whole-band
43
+ reading reports the band as before.
44
+
45
+ **An agent action names the list it chooses among.** The agent fence's grammar has an optional
46
+ clause, `action <name> <id|ids> among <state> …`, which names the `choices` state whose choices
47
+ the argument names. A handle's action may carry it (`{ argument: 'id', among: 'series', run }`),
48
+ and so may a description's `agent` block, which every renderer hands to `agentMember` as written.
49
+ With `among`, the bridge checks the value, and whether a choice is marked destructive, against
50
+ that state's choices only, and refuses an id of another list with `invalid-value`. The snapshot
51
+ lists it beside the argument (`{ name: 'toggle', argument: 'id', among: 'series' }`). Without it
52
+ nothing changes, and no existing fence, handle or description changes meaning.
53
+
54
+ - `pnpm registry` fails on `among` on an action that takes no id, on `among` naming a state that
55
+ is not one of the fence's `choices` states, and on an `id` or `ids` action with no `among` in a
56
+ fence that declares more than one `choices` state.
57
+ - The staleness law holds the React member's and the description's `among` to the fence's.
58
+ - The agent conformance law draws an action's probe from the state it chooses among, checks that
59
+ the snapshot lists the same `among`, and checks that an id of another `choices` state is
60
+ refused and changes nothing.
61
+
62
+ **An agent hides and shows a chart's series with its legend.** `AreaChart`, `BarChart`,
63
+ `LineChart`, `RadarChart` and `ScatterChart` draw a legend whose keys hide and show a series. An
64
+ agent now reads them as two states and runs one action, in every web framework:
65
+
66
+ - `series` lists the legend's keys in the legend's order, each `{ id, label }`: the id is the
67
+ series' `key`, and the label is what its key says. `hidden` lists the ids of the series now
68
+ hidden. A chart with one series draws no legend, so both are empty there.
69
+ - `toggle` takes the id of one of `series` (`among series`) and presses its key with the key's own
70
+ click, as a person does, so the chart refits its domains as it does for a person.
71
+ - `choose` takes the id of one of `items` (`among items`), so a series' id is refused there, and
72
+ a mark's id is refused by `toggle`.
73
+ - Such a chart is listed for an agent while a person has something to operate in it: `onSelect`,
74
+ or a legend. A chart with a legend and no `onSelect` is listed now, with `items` empty and
75
+ `choose` refused, where before it registered nothing. `DonutChart` and `Treemap` draw a legend
76
+ that only labels, so nothing changes for them.
77
+
78
+ The engine exports `chartSeries`, `chartHiddenSeries` and `toggleChartSeries`, which read a
79
+ chart's legend keys from its element and press one, for every renderer, and the types
80
+ `ChartSeriesChoice` and `ChartLegendSeries`; each web framework's foundation re-exports them.
81
+
82
+ **An agent brushes a range on a `LineChart` or an `AreaChart`.** A chart with `onBrushEnd` on an
83
+ x it brushes (`time` or `linear` for `LineChart`, `time` for `AreaChart`) has a brush, and an agent
84
+ now reads and uses it through the machine a person's keys drive:
85
+
86
+ - `range-start` and `range-end` are the range a person sees drawn, in rows, the unit `position`
87
+ uses: the row the range was begun on and the row it ends on, or `null` while there is none.
88
+ - `brush` takes the row the range ends on, presses Shift and the arrow toward it once per row,
89
+ as a person does, and commits with Enter, so `onBrushEnd` receives what a person's committed
90
+ range reports. The range starts where a person's would: at the start of a range a person has
91
+ begun, else at the reading position, which `read` sets, else at an end of the chart.
92
+ - A chart without a brush lists both states as `null`, and `brush` throws, saying why. A number
93
+ that is not a row, and a range of one row, are refused too.
94
+ - A chart with a brush is listed for an agent with no `onSelect` and no legend.
95
+
96
+ The engine exports `chartRange` and `brushChartRange`, and the types `ChartRange` and
97
+ `ChartRangeSource`; each web framework's foundation re-exports them. `LineChart` and `AreaChart`
98
+ have a states fixture entry `brushable`.
99
+
100
+ - Updated dependencies [9b60a94]
101
+ - @polymorph/engine@1.0.14
102
+
103
+ ## 1.0.13
104
+
105
+ ### Patch Changes
106
+
107
+ - d84171d: An agent on a running page can read and operate the mounted members through an API, instead of
108
+ clicking or reading screenshots. A member's spec declares what an agent may read and do in an
109
+ `## Agent` section, and nothing else grants access. The bridge is opt-in: a page that does not
110
+ import `@polymorph/engine/agent` does not ship it. `docs/agents.md` describes the bridge for an
111
+ application and the section for a member's author.
112
+
113
+ **The bridge.**
114
+
115
+ `@polymorph/engine/agent` is a new entry point. `createAgentBridge({ confirm, policy, settleMs })`
116
+ returns a bridge with `snapshot()`, `query({ name, text, member })`, `act(steps)`,
117
+ `subscribe(listener)`, `acting` and `dispose()`.
118
+
119
+ - An action the spec does not declare is refused, and the error lists the actions that are
120
+ allowed.
121
+ - A secret value is reported as `{ secret: true }`, and so is any value that holds the text of a
122
+ password field.
123
+ - An action of a destructive instance runs only after `confirm` resolves true. Without a
124
+ `confirm`, it is refused.
125
+ - A policy can hide a member or deny an action. It cannot add either.
126
+ - A member is listed only while its element is in the document, so a closed Dialog, Drawer,
127
+ Popover or ConfirmDialog is not listed, and a step on it answers `unknown-member`. A member in
128
+ content marked `hidden` is not listed either, so a closed panel a renderer keeps in the
129
+ document gives an agent what a removed one does. A step that removes its member's element
130
+ still reports what changed.
131
+ - Each member carries `description`, the text of the elements its control names with
132
+ `aria-describedby`, such as a field's hint and error, when there is any. `query`'s `text`
133
+ matches it. A member that holds a secret, or a password field, gives none.
134
+ - A step that succeeds dispatches `polymorph:agentchange`, bubbling, on the element its member
135
+ names after the step, else on the one it named before if that is still in the document, else
136
+ on the document, with `detail: { id, member, action, changed, source: 'agent' }`, and
137
+ `bridge.acting` is true while its action runs, so a handler can tell an agent's change from a
138
+ person's.
139
+ - `agentTools(bridge)` returns the bridge as three tools, `polymorph_snapshot`,
140
+ `polymorph_query` and `polymorph_act`, for an application's own agent.
141
+ `registerWebMCP(bridge)` registers them with the browser's WebMCP API on
142
+ `document.modelContext` or `navigator.modelContext` and returns the function that unregisters
143
+ them. Where the API is absent it does nothing.
144
+
145
+ **Registration.**
146
+
147
+ `agentMember(handle)`, `agentFill(element, text)` and `agentPress(element)` are new exports of
148
+ `@polymorph/engine` and of every foundation, with the types `AgentHandle`, `AgentAction`,
149
+ `AgentArgumentType` and `AgentArgumentValues`. A member registers a handle while it is mounted.
150
+ `useAgentMember(handle)` in `@polymorph/react` registers a React member on mount, removes it on
151
+ unmount and calls the latest render's closures; `useAgentMember(handle, { unless })` registers
152
+ nothing while `unless` is true. The engine and every foundation also export
153
+ what several renderers share: `menuChoices`, `chooseMenuEntry`, `menubarChoices` and
154
+ `chooseMenubarEntry`; `railDestinations`, `currentRailDestination` and `goToRailDestination`,
155
+ which read an AppShell's destinations from its navigation in the document and press one, with
156
+ the types `RailClasses` and `RailDestination`; `listItems`, `currentListItem` and
157
+ `chooseListItem`, which read a List's items from its list in the document and press one, with
158
+ the type `ListItemChoice`; `jsonTreeBranches`, `jsonTreeExpanded` and `setJsonTreeBranch`, which
159
+ read a JsonTree's branches from its toggles by their JSON Pointer and press one, with the type
160
+ `JsonTreeBranch`; `chartMarks`, `chartPosition`, `readChartPosition` and `chooseChartMark`,
161
+ which read a window of at most `CHART_MARK_CAP` of a chart's marks through its reading, read and
162
+ move the reading's position, and pick a mark as Enter does, with the types `ChartMarkChoice`,
163
+ `ChartMarkReading` and `ChartMarkSource`; a
164
+ Table's sortable headers and its sort
165
+ (`tableSortColumns`, `tableSort`, `pressTableSort`); the notices of the toast store and an answer to
166
+ one (`toastNotices`, `toastDetails`, `dismissToastNotice`, `actOnToastNotice`); and the readers of
167
+ the text an agent sets on a date or duration field (`agentDate`, `agentDateTime`, `agentTime`,
168
+ `agentMonth`, `agentDateRange`, `agentDuration`).
169
+
170
+ A handle may give `withholds`, the element or elements whose registered members are not an
171
+ agent's. The bridge lists, matches and runs none of them, the policy cannot list them, and the
172
+ member is listed in their place. A member that holds a secret withholds its own element.
173
+
174
+ A custom element of `@polymorph/elements-ui` renders its Solid member, so the member inside it
175
+ registers too, and a page that builds the elements with a bundler creates a bridge as any
176
+ application does. A page with no build loads the bridge with `loadAgentBridge`, which
177
+ `polymorph.js` and `polymorph-all.js` export: it resolves to `@polymorph/engine/agent`, built with
178
+ the elements so it reads the registry they write to, and `polymorph.js` fetches it as a chunk of
179
+ its own on the first call.
180
+
181
+ **Registering before the bridge loads.**
182
+
183
+ `@polymorph/engine/webmcp` is a new entry point, an addition that changes no existing one, and
184
+ holds none of the bridge. `registerWebMCPOnCall(load, options)` registers the three tools with the
185
+ browser's WebMCP API at once, and on the first call of any of them calls `load`, a dynamic import
186
+ of `@polymorph/engine/agent`, once, and creates the bridge with `options`. A load that fails
187
+ resolves the call to `{ error: { code: 'failed', message } }`, and the next call loads again.
188
+ `applyAgentSetting(value)` and `AGENT_ATTRIBUTE` (`data-agent`) do what a page's agent setting
189
+ says: nothing without one, `on-call` as `registerWebMCPOnCall`, and `eager`, which loads the
190
+ bridge at once; another value warns, and without a WebMCP API neither registers nor loads
191
+ anything. `agentTools` and the new registration read one list of the tools' names, titles,
192
+ descriptions, schemas and hints.
193
+
194
+ One registration of the tools stands on a page at a time. While one does, a second
195
+ `registerWebMCP`, a `registerWebMCPOnCall` or a page's setting registers nothing and warns in the
196
+ console, where before the browser refused the second registration's names without a word.
197
+
198
+ A page with no build states `<html data-agent="on-call">` or `data-agent="eager"` and writes no
199
+ script: `polymorph.js` and `polymorph-all.js` read it as they load. `polymorph init --framework
200
+ elements` names the setting in the app's `AGENTS.md`, and its example page states none.
201
+
202
+ **The members.**
203
+
204
+ These members register, in every web vocabulary. Their props, markup and defaults are
205
+ unchanged. The system card lists each one's actions and states.
206
+
207
+ - Controls: Button, AvatarButton, ProviderButton, RecordButton, SplitButton, Link, Input,
208
+ Textarea, SearchInput, NumberInput, PhoneInput, PasswordInput, OTPInput, TagInput, InlineEdit,
209
+ ColorInput, Select, Combobox, MultiSelect, TreeSelect, Checkbox, CheckboxGroup, RadioGroup,
210
+ ChoiceCard, SegmentedControl, ModeSwitch, Switch, Slider, Rating, Calendar, DatePicker,
211
+ DateRangePicker, MonthInput, TimeInput, DurationInput, FileUpload and ImageEditor. A Button
212
+ reads `pressed` as `aria-pressed` says it, and as `null` on a Button that is not a toggle, and
213
+ `expanded` as `aria-expanded` says it, and as `null` on a Button that discloses nothing.
214
+ - Overlays: Dialog, ConfirmDialog, Drawer, Popover, Lightbox, Tour, Menu, ContextMenu, Menubar,
215
+ Command, Tabs and Toast. Toast registers on its viewport, which reads the notices on screen
216
+ and dismisses one or runs its action through the toast store.
217
+ - Structure: Accordion, Collapsible, Alert, Banner, Pagination, CursorPagination, Table,
218
+ DataTable, Tree, Stepper, Carousel, FilterBar, SectionNav, TableOfContents, Breadcrumbs, List
219
+ and AudioPlayer. A Table reads its own sortable headers, and its `sort` presses a header's
220
+ control once, so its caller decides the order; the Table a DataTable draws registers nothing. A
221
+ List reads the items that navigate or are picked from its list, with the current one, and its
222
+ `choose` presses an item's link or button, so `onSelect`, `onNavigate` or the browser takes it
223
+ as a person's press; an item that is only read is not a choice.
224
+ A Card with `href` registers its stretched link, which an agent presses as a person clicks
225
+ it, and ErrorSummary lists its errors and follows one to its field with `choose`, reading its
226
+ links with List's `listItems`. A JsonTree reads its open branches and the branches a reader can
227
+ see, each by the JSON Pointer of its value, and its `expand` and `collapse` press a branch's
228
+ toggle.
229
+ - Layout: SplitPane reads its divider's position in percent, as `aria-valuenow` reports it, and
230
+ its `set` moves the divider within the bounds its floors give and commits, as a key press does.
231
+ - Charts: AreaChart, BarChart, DonutChart, FunnelChart, Heatmap, Histogram, LineChart,
232
+ RadarChart, ScatterChart and Treemap, while they have `onSelect`. `items` lists the marks the
233
+ keys reach, labelled with what the live region says there, at most `CHART_MARK_CAP` of them:
234
+ the whole positions around the reading position. `position`, which the figure shows as
235
+ `data-position`, and `count` say where the reading is and how many positions the chart has,
236
+ `read` moves the reading as Left and Right do, and `choose` moves it to a listed mark and
237
+ activates it as Enter does, so `onSelect` receives a person's payload. A chart without
238
+ `onSelect` registers nothing, and Sparkline, which takes none, never does.
239
+ - Conversation: PromptInput, ChatThread, ToolCall, ReasoningDisclosure, AttachmentChip,
240
+ ArtifactPane and ApprovalCard. AppShell registers too: an agent collapses and expands its rail,
241
+ opens and closes its drawer below the breakpoint, reads the application's destinations from
242
+ its navigation, with the current one, and goes to one by pressing its NavItem, so `onNavigate`
243
+ or the browser takes it as a person's press.
244
+
245
+ What an agent is not given:
246
+
247
+ - A password and a one-time code are secret, and no action writes them. PasswordInput's reveal
248
+ toggle is not an agent's.
249
+ - No action confirms for a person. ConfirmDialog declares `cancel` only and withholds its
250
+ confirm Button, its phrase field and the Dialog it draws. ApprovalCard declares no action and
251
+ withholds its Buttons.
252
+ - A Button with `tone="danger"`, and a `danger`-toned entry of a Menu, ContextMenu, Menubar or
253
+ SplitButton, asks a person to confirm.
254
+ - RecordButton lets an agent stop a recording and never start one. FileUpload lets an agent
255
+ remove or retry a file and never add one. AudioPlayer and ImageEditor are read only.
256
+ - CopyButton, Tooltip, HoverCard and FormField give an agent nothing, and each spec says why.
257
+ Plan and ChatMessage are not registered, so they stay server components.
258
+ Citation and SourceList are not registered either: each of their links opens a new tab,
259
+ which an agent's press cannot open, and their words are on the page.
260
+ - The Popover ColorInput draws for its picker registers nothing, and ColorInput withholds its
261
+ panel, so an agent sees one ColorInput.
262
+
263
+ A React member that passed `value` or `defaultValue` straight to its substrate now holds the
264
+ value itself and keeps the substrate controlled, controlled when the prop is given, so an
265
+ agent's action and a person's reach the same handler in both forms: Checkbox, Switch,
266
+ RadioGroup, SegmentedControl, ChoiceCard, Select, Slider, Tabs, ReasoningDisclosure and
267
+ ToolCall. A native `form.reset()` now resets a Checkbox row's state attribute too.
268
+
269
+ **The tooling.**
270
+
271
+ - `@polymorph/registry`: each member carries an `agent` field, the statements of its spec's
272
+ `agent` fence, or `null` for a member agents cannot see. `@polymorph/registry/agent` exports
273
+ the grammar, in which a `number` state reads `null` while the member holds none, as an `id`
274
+ state does, and an action may say `presses <part>`, the part whose element it presses with the
275
+ element's own click. The coverage law fails on a control or an overlay whose spec has no decided
276
+ `## Agent` section, and the staleness law on a fence the code does not match.
277
+ - `@polymorph/shells`: a description takes an `agent` block (`on` or `element`, `state`,
278
+ `actions`, `secret`, `destructive`, `withholds`), which each renderer writes as a mount effect
279
+ that registers the instance. A compound part may give the block instead, which registers under
280
+ its member's name (Toast's viewport). A member that lends its identity reads the element the member it
281
+ lends to hands back, as `borrowed`; the Solid foundation exports `BORROWED` and
282
+ `BorrowedHolder`, and the Angular foundation `BORROWED`, `BorrowedHolder`, `handBack`,
283
+ `borrowedHolder`, `lenderHolder` and `KEEPS_HOLDER`.
284
+ - `@polymorph/conformance`: the runner executes every statement of an agent fence against every
285
+ renderer, with a bridge installed; `agentConformanceLaw` holds a shell's fences, and
286
+ `conformanceLaw` calls it. `WINDOW_SIZES` lists the fixture entries the runner mounts at a
287
+ window size other than the default, through the harness's new `viewport`, so an action that
288
+ exists only below a breakpoint is checked there.
289
+ - `@polymorph/engine/testing` exports `agentRegistrations()`, every registered member's id, name
290
+ and elements, withheld ones included.
291
+ - `pnpm new:member` writes the `## Agent` section with a placeholder the coverage law refuses.
292
+
293
+ - 73837b5: `MasterDetailPage` is a new page archetype: a list of items of one kind beside the detail of the
294
+ selected one, for an inbox, a notifications page, an audit log or a file browser. It takes
295
+ `title`, `description` and `actions` as PageHeader does, the `list` (a List, Table or Tree with its
296
+ FilterBar and pagination, the selected item marked `current`) named by `listLabel`, the selected
297
+ item's `detail`, an `emptyState` for the detail pane while nothing is selected, and `backLabel`
298
+ and `onBack` for the way back on a phone. It fills AppShell's content region, as ConversationPage
299
+ does, and the list and the detail scroll on their own. At or above a 48rem page the two sit side
300
+ by side in a SplitPane; below it the page draws the list, or the detail under the way back, and
301
+ `onBack` is where the application clears its selection. Focus moves only when the element that
302
+ held it is no longer drawn. A page that draws the selected item under a table can move to it.
303
+
304
+ The engine and every foundation export `masterDetailFocus`, `masterDetailHolds` and
305
+ `MASTER_DETAIL_PART`, the focus rule every renderer's MasterDetailPage shares. The SwiftUI and
306
+ Compose contracts gain `PMMasterDetailPageProps` and its rendering protocol, and both platforms
307
+ draw the page: two panes from a 48rem page, and below it the list, or the detail under the way
308
+ back. On iOS the way back is the page's own button and no system gesture. The elements vocabulary
309
+ has it as `<poly-master-detail-page>`.
310
+
311
+ - Updated dependencies [d84171d]
312
+ - Updated dependencies [508275a]
313
+ - Updated dependencies [73837b5]
314
+ - Updated dependencies [709d7b3]
315
+ - @polymorph/engine@1.0.13
316
+
317
+ ## 1.0.12
318
+
319
+ ### Patch Changes
320
+
321
+ - 6d714a7: `clockTime(seconds, locale?)`, `spokenDuration(seconds, locale?)` and
322
+ `pauseOtherPlayers(audio)` are new exports of the engine, and of every foundation, which
323
+ re-exports the engine.
324
+
325
+ `clockTime` writes a length as a media clock: `65` is `1:05`, and from an hour on the hours come
326
+ first, `3725` is `1:02:05`. The digits are the locale's numerals. `spokenDuration` writes the
327
+ same length in the locale's words, from `Intl`'s unit names joined as a list: `65` is
328
+ `1 minute, 5 seconds` in English. Both drop the fraction of a second, and both read a value that
329
+ is not a finite length above zero as zero.
330
+
331
+ `pauseOtherPlayers` pauses every other AudioPlayer's recording in the document, in whatever
332
+ framework it is drawn. Media the application plays itself is left alone. AudioPlayer calls it
333
+ when it starts, so one recording plays at a time.
334
+
335
+ - aec76ec: `DataTable` takes `rowDetail`, which lets a row show more under itself. Passing it adds an
336
+ expansion column after the selection column. Each row gets a disclosure button, and an open
337
+ row draws what `rowDetail` returns for it in a full-width row below. Any number of rows can be
338
+ open. The table holds the open rows itself, starting with the rows `defaultExpanded` names, or
339
+ the app holds them with `expanded`, a set of row ids. `onExpandedChange` is called with the next
340
+ set in both cases.
341
+
342
+ `rowDetail` is called with one object, `{ row, close }`. `row` is the caller's own row. `close`
343
+ closes that row's detail and returns focus to the row's disclosure when focus was inside the
344
+ detail, so a detail's Save or Done calls it. In Vue `rowDetail` is a scoped slot
345
+ (`#rowDetail="{ row, close }"`), in Svelte a snippet that takes the object, in Solid a function
346
+ prop, and in Angular an input that takes an `ng-template`
347
+ (`<ng-template #detail let-row="row" let-close="close">`).
348
+
349
+ `isRowExpandable` says whether a row has a detail. A row it refuses has an empty cell in the
350
+ expansion column and never draws a detail.
351
+
352
+ `getRowName` returns a row's own name, "Invoice 12". `messages` gains an optional
353
+ `detailsLabel`, which names each row's disclosure from it, "Details for Invoice 12", and names
354
+ the expansion column's header. A localized app that passes `rowDetail` passes it as well.
355
+ `getRowLabel` keeps its meaning, the whole name of the row's checkbox, and the disclosure does
356
+ not read it.
357
+
358
+ In a narrow container the table pans, and the detail stays as wide as the part of the table
359
+ a reader sees.
360
+
361
+ The grid's arrow keys reach a detail. ArrowDown from a cell of an open row moves to the
362
+ row's detail cell, and ArrowDown again to the next row, in the column the reader was in.
363
+ ArrowUp is the reverse. ArrowLeft, ArrowRight, Home and End do nothing in a detail cell. What
364
+ a detail holds stays in the page's tab order, so Tab from the detail cell goes into it. The
365
+ expansion column's header draws nothing and is never the grid's first tab stop. In a table
366
+ without selection the first stop is the first data column's header.
367
+
368
+ The detail adds content and hides no column. Choosing which columns to show stays with the
369
+ app, which filters the `columns` it passes.
370
+
371
+ A table without `rowDetail` is unchanged.
372
+
373
+ The SwiftUI and Compose members draw the detail too, in the list and in the table. Each row's
374
+ disclosure is an icon-only Button after the row's Checkbox, with the platform's expanded or
375
+ collapsed state, named by `detailsLabel` from `getRowName`. An open row's detail is a row of its
376
+ own under it. `expanded`, `defaultExpanded`, `onExpandedChange` and `isRowExpandable` behave as
377
+ on the web. The expansion column has no header on either platform. `close` closes the row. In
378
+ Compose it moves keyboard focus that is inside the detail to the disclosure, and in SwiftUI it
379
+ leaves focus to the system.
380
+
381
+ On both platforms `getRowName` also names the row itself, so VoiceOver and TalkBack announce
382
+ "Invoice 12" for a row that opens and the row's Checkbox stays "Select Invoice 12". A table
383
+ without `getRowName` names its rows as before: by `getRowLabel` when the app passes it, else by
384
+ each column's header and value.
385
+
386
+ `@polymorph/angular` gains `bindSlot`, which binds a scoped slot's template to the slot's
387
+ props and gives the template each prop as a variable of that name. A generated Angular member
388
+ calls it for a slot outlet that has `props`.
389
+
390
+ - 51e8566: `diffLines(before, after)` and `diffRuns(rows, context)` are new exports of the engine, and of
391
+ every foundation, which re-exports the engine.
392
+
393
+ `diffLines` compares two texts line by line and returns one row for each line:
394
+ `{ kind: 'same' | 'added' | 'removed', text, beforeLine?, afterLine? }`. A missing, `null` or
395
+ empty text has no lines. `\r\n` ends a line as `\n` does, and a final line ending adds no empty
396
+ line. The rows are a longest common subsequence of the lines, so the same texts always give the
397
+ same rows. Within one change, the removed lines come before the added ones. The comparison
398
+ between the lines the two texts start and end with is bounded: past `DIFF_LINES_LIMIT`
399
+ (1,000,000) old lines × new lines, every old line there is removed and every new line added.
400
+
401
+ `diffRuns` groups those rows for a reader. It keeps `context` unchanged lines beside each change
402
+ (3 by default) and returns the rest as collapsed runs, each `{ key, collapsed, rows }`. A run
403
+ collapses only when it hides two lines or more. `Infinity` collapses nothing.
404
+
405
+ `Diff` draws both. An application that needs the rows for something else, such as a count of
406
+ changed lines, calls them directly. The types are `DiffRow`, `DiffRowKind` and `DiffRun`.
407
+
408
+ - e708348: `DurationInput` is a new member in every web vocabulary: a field for a length of time, such as
409
+ a session lifetime, a retention period or a timeout. It holds whole seconds and shows them as
410
+ counts of days, hours, minutes or seconds, each a spinbutton with its unit's word beside it,
411
+ so a reader sees "7 days" where a number field labelled "(seconds)" shows 604800.
412
+
413
+ `value`, `defaultValue` and `onChange` are whole seconds, and `null` is the empty field.
414
+ `onChange` reports committed values, as NumberInput's does: an arrow key commits at once, and
415
+ typed digits commit when focus leaves the field or on Enter. `min` (0 by default) and `max`
416
+ hold every commit, and the arrows stop at them. `units` chooses the counts, days, hours and
417
+ minutes by default. The largest count shown has no ceiling, so 36 hours is lawful when hours
418
+ are the largest. An arrow carries into the next count: one minute more than 59 minutes is an
419
+ hour. A typed count stays under the next unit: 90 cannot be typed into the minutes while hours
420
+ show. A value the counts cannot write exactly is drawn rounded to the smallest unit and kept
421
+ as it was until the reader changes it. `name` posts whole seconds as a decimal string. The
422
+ unit words, the digits and each count's name come from `Intl` in `locale`, and the one word
423
+ the member writes itself, what an empty count says, is `messages.empty`. The label, the
424
+ description and the error are FormField's.
425
+
426
+ It is not TimeInput, which holds a time of day, and it has no presets: a screen that offers a
427
+ few fixed lengths uses `Select` or `RadioGroup`.
428
+
429
+ The arithmetic is new in the engine, and so in every foundation, which re-exports it:
430
+ `durationKey` (what a key does in a count), `durationSegments` (the counts a draft draws),
431
+ `durationDraft` (seconds as counts), `typeIntoDuration` and `commitDuration`, with the types
432
+ `DurationUnit`, `DurationDraft`, `DurationFieldOptions`, `DurationSegment`, `DurationKey`,
433
+ `DurationKeyResult` and `DurationMessages`.
434
+
435
+ The SwiftUI and Compose renderings are not written yet. `DurationInput` is in both platforms'
436
+ pending lists, and both contracts are generated.
437
+
438
+ - f69f55e: `followEnd(region, content, report)` and `jumpToEnd(region)` are new exports of the engine, and
439
+ of every foundation, which re-exports the engine. `ChatThread` follows its newest turn with them
440
+ in every web vocabulary, and `LogView` follows its newest line with them.
441
+
442
+ `followEnd` keeps a scroll container at its end while the element inside it grows, for as long
443
+ as the reader is at the end: within `FOLLOW_SLACK_PX` (24) of it. A reader who scrolls away is
444
+ left where they scrolled. `report` receives `{ detached, overflowing }` once at the start and
445
+ again each time either changes, and `overflowing` counts both axes. It returns the function that
446
+ stops following. Without a container, without content or without `ResizeObserver` it does
447
+ nothing. `jumpToEnd` moves the container to its end and follows again from that call, which is
448
+ what a "Jump to latest" control does.
449
+
450
+ `ChatThread`'s jump control now follows from the press, so a turn that grows in the frame
451
+ before the browser reports the jump's scroll is followed too. A thread that is wider than its
452
+ box is a tab stop, as a taller one already was.
453
+
454
+ - 766b5fd: `FunnelChart` is a new chart member in every web vocabulary: the count that survives each stage
455
+ of an ordered process, such as a signup, a checkout or a ticket from opened to resolved. It
456
+ takes `label` and `stages`, where a `FunnelStage` is `{ key, label, value }`, and the tier's
457
+ `format`, `size`, `locale`, `tooltip`, `onSelect`, `loading` and `messages`.
458
+
459
+ Each stage is one horizontal bar from the inline start, its length its value against the
460
+ largest stage, with its label in a column before it and its value and share of the first stage
461
+ after it. Between two bars it writes the share of the stage above that reached the stage below:
462
+ "62% continued". Stages are drawn as given. A stage larger than the one before it dev-warns and
463
+ is not clamped or reordered. A first stage of zero has no shares, and a stage of zero has no
464
+ step after it. The tooltip, the live region and the table twin (stage, value, share,
465
+ continued) state every number the plot has no room for. It is one series, so it has one colour
466
+ and no legend.
467
+
468
+ `funnelChartModel`, `funnelChartReadout` and `funnelChartSelection` are new exports of
469
+ `@polymorph/engine/charts`, and of every foundation, which re-exports it, with the types
470
+ `FunnelStage`, `FunnelChartInput`, `FunnelChartModel`, `FunnelPlot`, `FunnelBar` and
471
+ `FunnelText`.
472
+
473
+ `ChartMessages` has four new keys, with English defaults in `DEFAULT_CHART_MESSAGES`:
474
+ `funnelSummary`, `stageColumn`, `continuedColumn` and `continued`. A host that spreads the
475
+ defaults is unaffected. A host that writes its own whole catalog adds the four keys, because the
476
+ catalog takes all keys or none.
477
+
478
+ On iOS, `PMChartMessages` takes the same four, and `PMSpecDefault.chartMessages` gives their
479
+ English. `FunnelChart` is native on iOS and its SwiftUI rendering is not written yet: it is in
480
+ the pending list, and its contract is generated. Android marks it absent, with `Table`, as it
481
+ does every chart member.
482
+
483
+ - 982e684: `Highlight` is a new member: the parts of a text that match a search, marked. It is phrasing
484
+ content, so it sits inside a Text, a table cell or a description's detail and takes the font
485
+ around it. The app passes `text` and either `query`, one term or several, matched as written and
486
+ never as a pattern, with case folded by `locale`, or `ranges`, the `[start, end]` offsets its
487
+ search engine returned, which take the query's place. Marks that overlap or touch are one mark,
488
+ and a range is cut at the text's end. An app that printed its search engine's highlight data as
489
+ JSON, because nothing drew it, passes it here.
490
+
491
+ A mark is a `<mark>` in `warning.text` on `warning.subtle`, a pair the contrast law measures in
492
+ every pairing, at the emphasis weight, so it is marked by more than colour. A screen reader reads
493
+ the text once, as it is, and hears no mark.
494
+
495
+ `highlightRuns(text, { query, ranges, locale })` is a new export of the engine, and of every
496
+ foundation, which re-exports the engine. It returns the text as runs, `{ text, marked }`, which
497
+ every framework's Highlight draws.
498
+
499
+ The SwiftUI and Compose renderings are pending.
500
+
501
+ - 2ffb66b: `Menubar` is a new member in every web vocabulary: an application's command menus in one row, as
502
+ a desktop application's File, Edit and View. It is for an editor, a canvas or a document tool
503
+ whose commands are too many for one Menu. It is not navigation: a title never links.
504
+
505
+ `Menubar` takes `label`, which names the bar, `menus`, each a `MenubarMenu` with a `label`, Menu's
506
+ `entries` and an optional `disabled`, and `defaultOpen`, the title whose menu is open on mount.
507
+ Each menu is Menu's panel with Menu's entries, and each entry reports through its own handler, as
508
+ in Menu. The bar is one tab stop. ArrowRight and ArrowLeft move along the row in the reading
509
+ direction and stop at the ends, Home and End go to the first and the last title, and a letter
510
+ goes to the title that starts with it. ArrowDown, Enter and Space open a menu on its first entry
511
+ and ArrowUp on its last. In an open menu, ArrowRight and ArrowLeft open the neighbour's menu.
512
+ While a menu is open, the title a mouse moves onto opens its own. A long row scrolls inside its
513
+ box. Below `30rem` the bar is one Menu behind one overflow Button named by `label`, each menu a
514
+ group under its title. The member is absent on iOS and Android, where the substitute is Menu.
515
+
516
+ The engine exports the model every framework's Menubar runs: `menubarStep`, `menubarStop`,
517
+ `menubarOpens`, `menubarHandOff`, `menubarEntries`, `roveMenubar`, `menubarNeighbour` and
518
+ `menubarEdge`, with their types. Each foundation re-exports them.
519
+
520
+ In the Vue, Svelte, Solid and Angular vocabularies, a Menu's, a ContextMenu's and a SplitButton's
521
+ submenu row now takes focus when the keys highlight it, as every other row does, and closing the
522
+ submenu returns focus to its row when focus is still in the submenu, as Radix's submenu does.
523
+
524
+ - d9713d4: `monthDraft(value)`, `monthFieldValue(draft)`, `monthOutOfBounds(value, { min, max })` and
525
+ `segmentValueText(segment, locale, empty)` are new exports of the engine, and of every
526
+ foundation, which re-exports the engine. The first three read and write a month field's
527
+ `YYYY-MM` text over the segmented field's draft, and compare it with its bounds. The last is what
528
+ a segment says as its value: its text, a month's number and name (`7 – July`), or the caller's
529
+ word for an empty segment.
530
+ - 3dc5f0f: `PromptInput` takes `triggers`, in every web vocabulary: characters that open a list of the app's
531
+ suggestions, such as `@` for people and `/` for commands. A composer without `triggers` is
532
+ unchanged.
533
+
534
+ ```tsx
535
+ <PromptInput
536
+ label="Message"
537
+ onSubmit={send}
538
+ triggers={[
539
+ {
540
+ char: '@',
541
+ label: 'People',
542
+ options: people,
543
+ onSelect: (person) => mention(person.id),
544
+ },
545
+ { char: '/', label: 'Commands', at: 'start', options: commands },
546
+ ]}
547
+ />
548
+ ```
549
+
550
+ A trigger is `{ char, label, options, at?, filter?, loading?, onQueryChange?, onSelect? }`, and
551
+ an option `{ id, label, description?, icon?, insert? }`. The list opens while the caret is in a
552
+ token: the character at the start of the prompt or after whitespace (`at: 'word'`, the default),
553
+ or only as the prompt's first character (`at: 'start'`), followed by the query, which holds no
554
+ whitespace. The member filters the options by the query as Combobox does; `filter: false` shows
555
+ the app's own results, which it loads from `onQueryChange` while `loading` is set.
556
+
557
+ The prompt stays plain text. Enter, Tab or a press picks the active option: the typed token is
558
+ replaced by the option's `insert`, or by the character and the label (`@Ada Lovelace`), and a
559
+ space, and the trigger's `onSelect` is called with the option. `insert: ''` removes the token and
560
+ writes nothing, for a command the app runs at once. The composer reports picks only: an app that
561
+ sends mentions checks, when the prompt is sent, which picked options' text is still in it.
562
+
563
+ While the list is open, ArrowUp and ArrowDown move the active option. Enter does nothing while the
564
+ trigger is `loading` with no option shown, and sends the prompt when nothing matches, as with the
565
+ list closed. Escape closes the list and keeps the text; inside a Dialog the dialog stays open until
566
+ the next Escape. Focus stays in the field, which carries
567
+ `aria-autocomplete="list"`, `aria-haspopup="listbox"`, and, while the list is open,
568
+ `aria-controls` and `aria-activedescendant`. A polite live region says how many options there
569
+ are. `PromptInputMessages` gains three optional strings: `suggestions(count)`,
570
+ `loadingSuggestions` and `noSuggestions`. The list opens above the composer, or below it when the
571
+ viewport has more room below, at the composer's width at every width. It is drawn in the
572
+ composer's root, so the composer's container must not clip it. The types are `PromptTrigger` and
573
+ `PromptTriggerOption`.
574
+
575
+ A composer focused on mount by `autoFocus` now has its caret at the end of its prompt in React,
576
+ as it already had in the other vocabularies.
577
+
578
+ `promptToken(text, caret, triggers)` and `promptPick(text, token, caret, insertion)` are new
579
+ exports of the engine, and of every foundation, which re-exports the engine: the token the caret
580
+ is in, and the text and caret a pick leaves. The types are `PromptToken` and
581
+ `PromptTokenTrigger`.
582
+
583
+ The SwiftUI and Compose contracts carry `triggers`, `PMPromptTrigger` and
584
+ `PMPromptTriggerOption`, and neither rendering draws a list: an `@` or a `/` stays text in the
585
+ prompt on iOS and Android.
586
+
587
+ - 9f8c97f: `rating` is a new icon role: one mark of a score. It draws lucide's `star`, and on Apple and
588
+ Android platforms the `star` symbol. It shares the glyph with `favorite`, as `close` and
589
+ `clear` share theirs: marking a thing to keep is not scoring it, and either can change glyph
590
+ without the other. `IconRole` includes it and every foundation's `Icon` draws it. The icon
591
+ rule no longer rewrites an import of the star glyph, because two roles draw it: it reports the
592
+ import and names both. Rating draws it.
593
+ - 9f8c97f: `Rating` is a new member in every web vocabulary: a score out of a few marks, five stars by
594
+ default, that a reader sets ("Rate this answer") or reads ("Average rating: 4.3 out of 5").
595
+
596
+ Set, it is a radio group with one radio per mark, named for the value it sets ("3 stars").
597
+ `value`, `defaultValue` and `onChange` are a whole number from 1 to `max`, and `null` for no
598
+ rating. A press on the chosen mark clears it, unless the rating is required (`aria-required`,
599
+ which FormField sets). The arrows move and choose, following the document's direction, Home
600
+ and End choose the first and the last mark, and the arrows stop at the ends. `name` posts the
601
+ value. Shown (`readOnly`), it is one image named by a sentence, and it draws any value to one
602
+ decimal place, with the mark the fraction lands in part filled. `max` is 2 to 10, `size` is the
603
+ marks' icon size, and `messages` with `locale` writes the marks' names and the sentence. Filled
604
+ and empty marks differ in shape, a solid star against an outline.
605
+
606
+ It is not RadioGroup, whose options are labelled rows, and not Meter, which measures against a
607
+ limit. Thumbs up and down under a reply are two pressed Buttons.
608
+
609
+ Its model is new in the engine, and so in every foundation, which re-exports it: `ratingModel`
610
+ (the marks, their fills and names, and the shown sentence), `ratingPress` (the clear rule),
611
+ `ratingStep` and `roveRating` (the keys), `ratingMax` and `RATING_DEFAULT_MAX`, with the types
612
+ `RatingModel`, `RatingMark`, `RatingFill`, `RatingOptions`, `RatingWords` and
613
+ `RatingKeyEvent`.
614
+
615
+ The SwiftUI and Compose renderings are not written yet. `Rating` is in both platforms' pending
616
+ lists, and both contracts are generated.
617
+
618
+ - 96daa65: `record` is a new icon role: start a recording of the reader's voice. It draws lucide's `mic`,
619
+ and on Apple and Android platforms the `mic` symbol. `IconRole` includes it, every foundation's
620
+ `Icon` draws it, and the icon rule's fix names it for an import of the microphone glyph.
621
+ RecordButton draws it at rest.
622
+ - 0936316: `TableOfContents` is a new member in every web vocabulary: the list of links to the sections of
623
+ one long page ("On this page"), with the section the reader is in marked. It takes `label` (the
624
+ landmark's name, drawn above the list), `items` (`{ id, label, level? }`, where `id` is the id of
625
+ the section's element in the document and `level: 2` draws a subsection one step in, in a list
626
+ inside its section's item) and `onCurrentChange`, called with the current section's id or
627
+ `null`. Each item is a real `<a href="#id">`; the current one carries `aria-current="location"`
628
+ and the selection treatment SectionNav gives its current item.
629
+
630
+ The current section is the last one whose top has reached a line a quarter of the way down the
631
+ page that scrolls around the sections, or the last section when the page is scrolled to its end.
632
+ A click marks its item at once, holds the mark while the browser scrolls to the section, and
633
+ moves focus to the section, which takes `tabindex="-1"` only while it has focus. An item whose
634
+ section is not in the document is drawn and never marked. The member does not scroll and does
635
+ not stay in view on its own: the page's CSS owns `scroll-behavior`, and the app places the list.
636
+
637
+ It is not SectionNav, whose items are pages the router marks.
638
+
639
+ `watchSections(owner, ids, report)` and `jumpToSection(owner, id, event)` are new exports of the
640
+ engine, and of every foundation, which re-exports the engine, with `SECTION_LINE` (0.25), the
641
+ line's place as a fraction of the page's height. Every framework's TableOfContents follows the
642
+ page with them.
643
+
644
+ The SwiftUI and Compose renderings are not written yet. `TableOfContents` is in both platforms'
645
+ pending lists, and both contracts are generated, with the item's shape.
646
+
647
+ - b88e331: The theme is readable as data. `readThemeValues(element?)` in `@polymorph/engine` returns what
648
+ an element resolves a pairing's tokens to, as the values a JavaScript API takes: a colour role
649
+ as `#rrggbb` (or `rgba()` when translucent) and as channels, a space step, a radius and a control
650
+ height in pixels, a type step, a font slot, a duration in milliseconds, the colour mode the
651
+ element is drawn in and the document's reading direction. A reading is a snapshot: it keeps each
652
+ value, the mode and the direction as it first read them. An element that is not in the document
653
+ reads as the document root.
654
+
655
+ `watchTheme(listener)` calls back when the system, palette, mode, density, motion temperament,
656
+ contrast preference or direction changes, when an element enters or leaves an inverse tone, and
657
+ when a pairing's sheet is installed, installed again or removed. A tone or a mode that a member
658
+ writes for its own variant does not call back. `themeVersion()` grows with each call back and
659
+ when `watchTheme` takes its first listener, so a store that keeps a reading knows when to take
660
+ another. `UNTHEMED_VALUES` is the reading a server render gets: every colour the empty string and
661
+ every number 0.
662
+
663
+ Each foundation wraps these as `useThemeValues`: a hook in React, a `ShallowRef` in Vue, a
664
+ `current` getter in Svelte, an accessor in Solid and a signal in Angular. It is for another
665
+ library's component that cannot be styled through CSS, such as a map, a canvas grid or a code
666
+ editor, inside a `<ThirdParty>` boundary (`docs/rules.md`). A value is read where the framework
667
+ renders or in an effect. In React, Vue and Solid the render that hydrates a server's markup gets
668
+ the server's empty values, and the component gets the document's once it has hydrated. React's
669
+ hook takes a ref, reads the ref's element after each commit of the component, and renders the
670
+ component again when the element is another one. Svelte's `current` is a new reading each time it
671
+ is read outside an effect. Outside a component, Vue's follows the theme in an effect scope and
672
+ Solid's under a root.
673
+
674
+ `@polymorph/engine/runtime` also exports `cssVarName` and `MORE_CONTRAST_QUERY`. Nothing is
675
+ renamed or removed.
676
+
677
+ - 00bce31: `Tour` is a new member in every web vocabulary: a short walk through the parts of a page, one
678
+ step at a time, that a reader goes through once and can leave at any step. It takes `steps`,
679
+ where a `TourStep` is `{ id, target?, title, body, side? }`. A step names the part it points at
680
+ by the `name` of a `Tour.Target`, which the application puts around that part and which adds no
681
+ box (`display: contents`). A step with no `target`, or whose target is not drawn when it opens,
682
+ is drawn centred.
683
+
684
+ The application opens the tour (`open`, `defaultOpen`) and records that it was seen: the member
685
+ stores nothing, and `onEnd(reason)` says why the reader ended it, `finished` from the last
686
+ step's Done or `dismissed` from Escape or the close control. The step is `step`, `defaultStep`
687
+ and `onStepChange`. The words it writes itself are in `messages` (`next`, `previous`, `done`,
688
+ `close`, `position`), with English defaults.
689
+
690
+ Each step's panel is a modal dialog, named by the step's title and described by its body and
691
+ its position ("Step 2 of 3"). Focus moves to the panel when each step opens and returns to where
692
+ it was when the tour ends. The rest of the page is hidden from assistive technology and takes no
693
+ presses, and the target is cut out of the scrim. The page keeps its scroll: the target is
694
+ scrolled into view when its step opens, and the panel and the cut-out follow it.
695
+
696
+ The engine, and every foundation, which re-exports it, has five new exports for it:
697
+ `tourTarget(name)` finds a step's target, `tourTargetRect(element)` measures the boxes inside
698
+ it, `revealTourTarget(element)` scrolls it into view, `tourViewport()` is the window's size, and
699
+ `tourPlacement(target, box, viewport, side)` places a panel beside a rectangle and inside the
700
+ window. The types are `TourPlacement`, `TourRect`, `TourSide` and `TourSize`, and the attribute
701
+ a target carries is `TOUR_TARGET_ATTRIBUTE`.
702
+
703
+ - 59658db: `Treemap` is a new chart member in every web vocabulary: parts of a whole as rectangles that
704
+ tile the plot, each with an area proportional to its value, such as storage by kind or tickets
705
+ by team and channel. It takes `label` and `items`, where a `TreemapItem` is
706
+ `{ key, label, value, children? }`, and the tier's `format`, `size`, `locale`, `tooltip`,
707
+ `onSelect`, `loading` and `messages`.
708
+
709
+ The layout is squarified, largest first from the inline start, and the same items and size
710
+ always give the same tiles. An item with `children` is a group, drawn as the sum of its
711
+ children; two levels are drawn, and deeper items are summed into the second with a dev
712
+ warning. With groups, each group takes a chart slot and its items its colour, with a legend of
713
+ the groups and a wider gap between them; with one level every tile is one colour. An item with
714
+ no positive value takes no area: the twin lists it and the summary counts it. A tile shows its
715
+ label and value on a plate of the surface colour, and only where both fit; the tooltip, the
716
+ live region and the twin name every item.
717
+
718
+ `squarify`, `treemapModel`, `treemapReadout` and `treemapSelection` are new exports of
719
+ `@polymorph/engine/charts`, and of every foundation, which re-exports it, with the types
720
+ `TreemapItem`, `TreemapInput`, `TreemapModel`, `TreemapPlot`, `TreemapTile`, `TreemapPlate`,
721
+ `TreemapLeaf` and `TreemapRect`.
722
+
723
+ `ChartMessages` has three new keys, with English defaults in `DEFAULT_CHART_MESSAGES`:
724
+ `treemapSummary`, `groupColumn` and `itemColumn`. A host that spreads the defaults is
725
+ unaffected. A host that writes its own whole catalog adds the three keys.
726
+
727
+ On iOS, `PMChartMessages` takes the same three, and `PMSpecDefault.chartMessages` gives their
728
+ English. `Treemap` is adapted on iOS, drawn with SwiftUI shapes because Swift Charts has no mark
729
+ that tiles a box by area; its rendering is not written yet, so it is in the pending list, and
730
+ its contract is generated. Android marks it absent, with `Table`, as it does every chart member.
731
+
732
+ - 4902f58: The colour mode is readable and followable. `readMode()` in `@polymorph/engine/runtime` (and the
733
+ engine's root) returns `{ preference, mode }`: the preference, `light`, `dark` or `system`, and
734
+ the mode it resolves to. It returns the same object until one of the two changes.
735
+ `watchMode(listener)` calls back after each `setMode`, from any caller, and each time the
736
+ operating system's mode changes while `system` is applied. `SERVER_MODE` is the reading a server
737
+ render gets, `system` and `light`, because a server stores no preference.
738
+
739
+ Each foundation wraps these as `useMode`: a hook in React, a `ShallowRef` in Vue, a `current`
740
+ getter in Svelte, an accessor in Solid and a signal in Angular. An application's Menu or command
741
+ palette reads the preference from it to mark the current choice, and sets the mode with
742
+ `setMode`, which every foundation already re-exports. In React, Vue and Solid the render that
743
+ hydrates a server's markup gets `SERVER_MODE`, and the component reads the document once it has
744
+ hydrated.
745
+
746
+ `getModePreference()` now returns the preference the last `setMode` applied to the document, and
747
+ the stored one before any call. It used to read storage each time, so it answered `system` where
748
+ storage refuses writes, and another tab's choice where one had stored it, while the document wore
749
+ something else. `teardownTheme()` also forgets the applied preference. Nothing is renamed or
750
+ removed.
751
+
752
+ - Updated dependencies [6d714a7]
753
+ - Updated dependencies [28aeda0]
754
+ - Updated dependencies [f918ed3]
755
+ - Updated dependencies [b209e98]
756
+ - Updated dependencies [51e8566]
757
+ - Updated dependencies [e708348]
758
+ - Updated dependencies [f69f55e]
759
+ - Updated dependencies [766b5fd]
760
+ - Updated dependencies [982e684]
761
+ - Updated dependencies [2ffb66b]
762
+ - Updated dependencies [d9713d4]
763
+ - Updated dependencies [49ab024]
764
+ - Updated dependencies [b9e5208]
765
+ - Updated dependencies [3dc5f0f]
766
+ - Updated dependencies [9f8c97f]
767
+ - Updated dependencies [9f8c97f]
768
+ - Updated dependencies [96daa65]
769
+ - Updated dependencies [3b0b47f]
770
+ - Updated dependencies [0936316]
771
+ - Updated dependencies [b88e331]
772
+ - Updated dependencies [00bce31]
773
+ - Updated dependencies [59658db]
774
+ - Updated dependencies [4902f58]
775
+ - @polymorph/engine@1.0.12
776
+
777
+ ## 1.0.10
778
+
779
+ ### Patch Changes
780
+
781
+ - cb0d0a3: Members follow a right-to-left document. With `dir="rtl"` on `<html>` or `<body>`, every member built on Radix or Zag now takes that direction: its root says `dir="rtl"`, and the arrow keys, a Slider's track, a submenu's side and a Tabs strip turn with the page. Before, those members wrote `dir="ltr"` on their root and ran left to right inside a right-to-left page. A member already on the page follows a change to the attribute. There is no new prop, and a left-to-right page renders as it did.
782
+
783
+ Each foundation exports `useDirection`, which returns the document's direction and keeps it current, and `@polymorph/engine` exports `readDirection` and `watchDirection` beneath it.
784
+
785
+ The page-transition indicator's right-to-left rule now reads `dir` instead of `:dir()`, which the published build's minifier had rewritten as a list of languages.
786
+
787
+ - Updated dependencies [7019d6f]
788
+ - Updated dependencies [cb0d0a3]
789
+ - @polymorph/engine@1.0.10
790
+
791
+ ## 1.0.9
792
+
793
+ ### Patch Changes
794
+
795
+ - @polymorph/engine@1.0.9
796
+
797
+ ## 1.0.8
798
+
799
+ ### Patch Changes
800
+
801
+ - 820c836: Every package now carries the release's version, and the release tag is `v` and that version.
802
+ Until this release each package kept its own number, so one release installed the engine at one
803
+ version, the foundations at another and the tag named a third. From this release on, pin every
804
+ `@polymorph/*` package you install at the same version, and check the native packages out at the
805
+ tag of that version.
806
+
807
+ This package's version jumps to the release's number. The jump carries no change of its own: the
808
+ versions it skips were never published.
809
+
810
+ - Updated dependencies [820c836]
811
+ - Updated dependencies [e1c80b3]
812
+ - @polymorph/engine@1.0.8
813
+
814
+ ## 1.0.3
815
+
816
+ ### Patch Changes
817
+
818
+ - Updated dependencies [22f607b]
819
+ - @polymorph/engine@1.0.6
820
+
821
+ ## 1.0.2
822
+
823
+ ### Patch Changes
824
+
825
+ - 1b900d8: CursorPagination has a "Load more" form, and RelativeTime writes the moment itself as well as the distance from now.
826
+
827
+ **`CursorPagination mode="append"` is "Load more".** It draws one `outline` Button, "Load more", that calls `onNext`; the app adds the window it fetches below the ones on screen. While `pending` the Button is busy and ignores presses. When `hasNext` turns false after a press, the list has run out: the Button leaves and an end line says "No more to load" through a status region, so a screen reader hears it. The form remembers that it asked for a window and does not read `hasPrevious`, so pass your query library's flags as they are. A list with no next window that the reader has not paged renders nothing, as one window does in the default form. `position` is what is on screen in your words ("50 shown"). In a DataTable, set the pager's `pending` while the next rows load, not the table's `loading`, which replaces the rows with skeletons. A hand-built "Load more" can be replaced with `<CursorPagination mode="append" hasPrevious={false} hasNext={hasNextPage} pending={isFetchingNextPage} onNext={fetchNextPage} />`; a list started again under a new query takes a new pager (`key={query}`).
828
+
829
+ In React the props are a union on `mode`: the default form still requires `onPrevious`, so every pager written before stays valid, and the append form takes none, because it has no previous direction. In Vue, Svelte, Solid and Angular `onPrevious` is an optional event, and the default form warns in development when `hasPrevious` has no `onPrevious`.
830
+
831
+ `CursorPaginationMessages` takes two optional words, `more` and `end`; an app that localizes the pager passes them, and the append form warns in development when `messages` leaves them out. Every web framework's CursorPagination takes `mode`, and so do `PMCursorPagination` on iOS and Android.
832
+
833
+ The Svelte foundation's `Held` takes `presses`, and the Angular foundation exports `pressOnce`: a states fixture entry presses a control once it is in the document, as the append form's "the list ran out" entry presses "Load more". An app has no use for either.
834
+
835
+ `@polymorph/recipes`' `structure/cursor-pagination.module.css` lays `.pagination` out as a column (`display: inline-flex; flex-direction: column`), so the append form's end line takes a line of its own under the row; the default form's one row looks as it did. It adds `.end`, the end line, in the position's type and colour. A vendored CursorPagination takes both with the recipe.
836
+
837
+ **`RelativeTime mode="absolute"` and `mode="both"`.** `absolute` writes the moment with `Intl.DateTimeFormat` in the member's `locale`: the medium date and the short time ("Aug 4, 2026, 2:05 PM"), or with `format="long"` the long date. An instant is written in the time zone of whatever renders the member: the reader's in a browser, the server's under server rendering or in a React server component. An app that renders on a server and must show the reader's zone renders the absolute forms in the browser, from a client component once it has mounted. A calendar date (`2026-08-04`) is the date alone, the same day everywhere. `both` writes the moment and the distance joined by `messages.both`, by default the moment, then the distance in parentheses ("Aug 4, 2026, 2:05 PM (2h ago)"); a localized app passes `messages={{ both: (moment, distance) => … }}` from its catalog, so its locale orders and punctuates the two. The default stays `relative`. Replace a hand-formatted timestamp in JSX with the member, which also writes the moment in `dateTime`.
838
+
839
+ **`relativeTimePhrase` takes `mode` and `messages`.** `relativeTimePhrase(value, { locale, numeric, format, mode, messages })` from `@polymorph/engine`, which every foundation re-exports, returns the text RelativeTime renders for those props, or `null` for a value that is not a moment. Use it where a member takes app-formatted text, such as Timeline's `time`, so the words match RelativeTime's ([design/components/relative-time.md](../design/components/relative-time.md)).
840
+
841
+ **On iOS and Android**, `PMRelativeTimeProps` gains `messages`, the same `both`. **On Android**, `PMRelativeTimeWords` gains `absolute(moment, long, locale)`, which an app implements to write the moment with the platform's formatter in the reader's zone. Without it the member writes Material 3's medium date and an instant's 24-hour time in UTC, said as UTC, because the member module reaches no time zone. The words are `PMStrings.relativeUtc`, a default only Android's `PMStrings` declares, so iOS's string catalog does not carry it; an app translates it through `LocalPMStrings`.
842
+
843
+ - Updated dependencies [1b900d8]
844
+ - Updated dependencies [1b900d8]
845
+ - Updated dependencies [1b900d8]
846
+ - @polymorph/engine@1.0.5
847
+
848
+ ## 1.0.1
849
+
850
+ ### Patch Changes
851
+
852
+ - 700e130: Two new packages ship the vocabulary for Angular 22: `@polymorph/angular`, the foundation (the engine re-exported, a Zag adapter driven by signals with the `Spread` directive that writes a machine's props onto an element, the member context with its `listen` and `afterRender`, the slot directives, the icon gateway, `Icon`, the presence and control-ref primitives, the toast store and the page-transition convention), and `@polymorph/angular-ui`, the members, published as `@metamorph-labs/polymorph-angular` and `@metamorph-labs/polymorph-angular-ui`. Each member is a standalone component generated from its framework-neutral description: its value props are signal inputs of the React prop's name (`aria-label` included), each `onFoo` prop is the output `foo`, `children` is its default content and each node prop a named slot (`slot="footer"`), each render prop takes an `ng-template`, and it renders the same DOM with the same recipes from `@polymorph/recipes`. A member's host element (`<pm-button>`) draws no box and carries no attribute but its `display: contents` style; a compound part that is a list's item or a table's section, row or cell is that element (`<tr pmTableRow>`). `design/frameworks/angular.json` says which members the Angular vocabulary ships: every member but ImageEditor, whose entry says why.
853
+
854
+ Install them under their workspace names as npm aliases, beside `@angular/core@^22` (`docs/consuming.md`). Both ship partially compiled code, one flat module per entry point as the Angular package format does (`dist/fesm2022/`), which the application's Angular CLI, or Analog's Vite plugin, links to the Angular it runs. Each member's recipe is compiled into its component's styles, which Angular adds to the page when the member first renders; the base layer ships as `@polymorph/angular-ui/base.css`, which the application lists among its global styles.
855
+
856
+ Every type alias `@polymorph/react-ui` exports (`BadgeTone`, `TooltipSide`, `ControlSize`, `IconRole` and the rest) is exported by the vocabulary's entry under the same name, and the foundation's types with it, so a screen the emitter writes for this framework compiles against the vocabulary alone; the few React types the vocabulary cannot carry are listed with their reasons as `UNEXPORTED_TYPES` in `packages/shells/src/common.ts`.
857
+
858
+ - Updated dependencies [700e130]
859
+ - @polymorph/engine@1.0.4