@metamorph-labs/polymorph-elements 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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,359 @@
1
+ # @polymorph/elements
2
+
3
+ ## 1.0.16
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [2f0ddd2]
8
+ - @polymorph/engine@1.0.16
9
+ - @polymorph/solid@1.0.16
10
+ - @polymorph/recipes@1.0.16
11
+
12
+ ## 1.0.15
13
+
14
+ ### Patch Changes
15
+
16
+ - @polymorph/engine@1.0.15
17
+ - @polymorph/recipes@1.0.15
18
+ - @polymorph/solid@1.0.15
19
+
20
+ ## 1.0.14
21
+
22
+ ### Patch Changes
23
+
24
+ - 9b60a94: **`ScatterChart` reports nothing where it draws no point.** A row whose x, y or bubble value is
25
+ `null` draws no point for that series. The arrow keys still reach that position, and the live
26
+ region still says it, but Enter, Space and a click there no longer call `onSelect`. Before, they
27
+ called it with `{ index, key, datum }` for a point the plot did not draw. An agent does not list
28
+ such a position among the chart's `items`, and its `choose` refuses one. The engine's
29
+ `scatterChartSelection` returns `null` there, as `heatmapSelection` does at an absent cell.
30
+
31
+ **`BarChart` reports nothing at a walked bar that is not drawn.** With the reading walked to one
32
+ series (Up and Down) at a band where that series' value is `null`, Enter, Space or a click called
33
+ `onSelect` for a bar the plot does not draw. `barChartSelection` returns `null` there. A whole-band
34
+ reading reports the band as before.
35
+
36
+ **An agent action names the list it chooses among.** The agent fence's grammar has an optional
37
+ clause, `action <name> <id|ids> among <state> …`, which names the `choices` state whose choices
38
+ the argument names. A handle's action may carry it (`{ argument: 'id', among: 'series', run }`),
39
+ and so may a description's `agent` block, which every renderer hands to `agentMember` as written.
40
+ With `among`, the bridge checks the value, and whether a choice is marked destructive, against
41
+ that state's choices only, and refuses an id of another list with `invalid-value`. The snapshot
42
+ lists it beside the argument (`{ name: 'toggle', argument: 'id', among: 'series' }`). Without it
43
+ nothing changes, and no existing fence, handle or description changes meaning.
44
+
45
+ - `pnpm registry` fails on `among` on an action that takes no id, on `among` naming a state that
46
+ is not one of the fence's `choices` states, and on an `id` or `ids` action with no `among` in a
47
+ fence that declares more than one `choices` state.
48
+ - The staleness law holds the React member's and the description's `among` to the fence's.
49
+ - The agent conformance law draws an action's probe from the state it chooses among, checks that
50
+ the snapshot lists the same `among`, and checks that an id of another `choices` state is
51
+ refused and changes nothing.
52
+
53
+ **An agent hides and shows a chart's series with its legend.** `AreaChart`, `BarChart`,
54
+ `LineChart`, `RadarChart` and `ScatterChart` draw a legend whose keys hide and show a series. An
55
+ agent now reads them as two states and runs one action, in every web framework:
56
+
57
+ - `series` lists the legend's keys in the legend's order, each `{ id, label }`: the id is the
58
+ series' `key`, and the label is what its key says. `hidden` lists the ids of the series now
59
+ hidden. A chart with one series draws no legend, so both are empty there.
60
+ - `toggle` takes the id of one of `series` (`among series`) and presses its key with the key's own
61
+ click, as a person does, so the chart refits its domains as it does for a person.
62
+ - `choose` takes the id of one of `items` (`among items`), so a series' id is refused there, and
63
+ a mark's id is refused by `toggle`.
64
+ - Such a chart is listed for an agent while a person has something to operate in it: `onSelect`,
65
+ or a legend. A chart with a legend and no `onSelect` is listed now, with `items` empty and
66
+ `choose` refused, where before it registered nothing. `DonutChart` and `Treemap` draw a legend
67
+ that only labels, so nothing changes for them.
68
+
69
+ The engine exports `chartSeries`, `chartHiddenSeries` and `toggleChartSeries`, which read a
70
+ chart's legend keys from its element and press one, for every renderer, and the types
71
+ `ChartSeriesChoice` and `ChartLegendSeries`; each web framework's foundation re-exports them.
72
+
73
+ **An agent brushes a range on a `LineChart` or an `AreaChart`.** A chart with `onBrushEnd` on an
74
+ x it brushes (`time` or `linear` for `LineChart`, `time` for `AreaChart`) has a brush, and an agent
75
+ now reads and uses it through the machine a person's keys drive:
76
+
77
+ - `range-start` and `range-end` are the range a person sees drawn, in rows, the unit `position`
78
+ uses: the row the range was begun on and the row it ends on, or `null` while there is none.
79
+ - `brush` takes the row the range ends on, presses Shift and the arrow toward it once per row,
80
+ as a person does, and commits with Enter, so `onBrushEnd` receives what a person's committed
81
+ range reports. The range starts where a person's would: at the start of a range a person has
82
+ begun, else at the reading position, which `read` sets, else at an end of the chart.
83
+ - A chart without a brush lists both states as `null`, and `brush` throws, saying why. A number
84
+ that is not a row, and a range of one row, are refused too.
85
+ - A chart with a brush is listed for an agent with no `onSelect` and no legend.
86
+
87
+ The engine exports `chartRange` and `brushChartRange`, and the types `ChartRange` and
88
+ `ChartRangeSource`; each web framework's foundation re-exports them. `LineChart` and `AreaChart`
89
+ have a states fixture entry `brushable`.
90
+
91
+ - Updated dependencies [9b60a94]
92
+ - @polymorph/engine@1.0.14
93
+ - @polymorph/solid@1.0.14
94
+ - @polymorph/recipes@1.0.14
95
+
96
+ ## 1.0.13
97
+
98
+ ### Patch Changes
99
+
100
+ - d84171d: An agent on a running page can read and operate the mounted members through an API, instead of
101
+ clicking or reading screenshots. A member's spec declares what an agent may read and do in an
102
+ `## Agent` section, and nothing else grants access. The bridge is opt-in: a page that does not
103
+ import `@polymorph/engine/agent` does not ship it. `docs/agents.md` describes the bridge for an
104
+ application and the section for a member's author.
105
+
106
+ **The bridge.**
107
+
108
+ `@polymorph/engine/agent` is a new entry point. `createAgentBridge({ confirm, policy, settleMs })`
109
+ returns a bridge with `snapshot()`, `query({ name, text, member })`, `act(steps)`,
110
+ `subscribe(listener)`, `acting` and `dispose()`.
111
+
112
+ - An action the spec does not declare is refused, and the error lists the actions that are
113
+ allowed.
114
+ - A secret value is reported as `{ secret: true }`, and so is any value that holds the text of a
115
+ password field.
116
+ - An action of a destructive instance runs only after `confirm` resolves true. Without a
117
+ `confirm`, it is refused.
118
+ - A policy can hide a member or deny an action. It cannot add either.
119
+ - A member is listed only while its element is in the document, so a closed Dialog, Drawer,
120
+ Popover or ConfirmDialog is not listed, and a step on it answers `unknown-member`. A member in
121
+ content marked `hidden` is not listed either, so a closed panel a renderer keeps in the
122
+ document gives an agent what a removed one does. A step that removes its member's element
123
+ still reports what changed.
124
+ - Each member carries `description`, the text of the elements its control names with
125
+ `aria-describedby`, such as a field's hint and error, when there is any. `query`'s `text`
126
+ matches it. A member that holds a secret, or a password field, gives none.
127
+ - A step that succeeds dispatches `polymorph:agentchange`, bubbling, on the element its member
128
+ names after the step, else on the one it named before if that is still in the document, else
129
+ on the document, with `detail: { id, member, action, changed, source: 'agent' }`, and
130
+ `bridge.acting` is true while its action runs, so a handler can tell an agent's change from a
131
+ person's.
132
+ - `agentTools(bridge)` returns the bridge as three tools, `polymorph_snapshot`,
133
+ `polymorph_query` and `polymorph_act`, for an application's own agent.
134
+ `registerWebMCP(bridge)` registers them with the browser's WebMCP API on
135
+ `document.modelContext` or `navigator.modelContext` and returns the function that unregisters
136
+ them. Where the API is absent it does nothing.
137
+
138
+ **Registration.**
139
+
140
+ `agentMember(handle)`, `agentFill(element, text)` and `agentPress(element)` are new exports of
141
+ `@polymorph/engine` and of every foundation, with the types `AgentHandle`, `AgentAction`,
142
+ `AgentArgumentType` and `AgentArgumentValues`. A member registers a handle while it is mounted.
143
+ `useAgentMember(handle)` in `@polymorph/react` registers a React member on mount, removes it on
144
+ unmount and calls the latest render's closures; `useAgentMember(handle, { unless })` registers
145
+ nothing while `unless` is true. The engine and every foundation also export
146
+ what several renderers share: `menuChoices`, `chooseMenuEntry`, `menubarChoices` and
147
+ `chooseMenubarEntry`; `railDestinations`, `currentRailDestination` and `goToRailDestination`,
148
+ which read an AppShell's destinations from its navigation in the document and press one, with
149
+ the types `RailClasses` and `RailDestination`; `listItems`, `currentListItem` and
150
+ `chooseListItem`, which read a List's items from its list in the document and press one, with
151
+ the type `ListItemChoice`; `jsonTreeBranches`, `jsonTreeExpanded` and `setJsonTreeBranch`, which
152
+ read a JsonTree's branches from its toggles by their JSON Pointer and press one, with the type
153
+ `JsonTreeBranch`; `chartMarks`, `chartPosition`, `readChartPosition` and `chooseChartMark`,
154
+ which read a window of at most `CHART_MARK_CAP` of a chart's marks through its reading, read and
155
+ move the reading's position, and pick a mark as Enter does, with the types `ChartMarkChoice`,
156
+ `ChartMarkReading` and `ChartMarkSource`; a
157
+ Table's sortable headers and its sort
158
+ (`tableSortColumns`, `tableSort`, `pressTableSort`); the notices of the toast store and an answer to
159
+ one (`toastNotices`, `toastDetails`, `dismissToastNotice`, `actOnToastNotice`); and the readers of
160
+ the text an agent sets on a date or duration field (`agentDate`, `agentDateTime`, `agentTime`,
161
+ `agentMonth`, `agentDateRange`, `agentDuration`).
162
+
163
+ A handle may give `withholds`, the element or elements whose registered members are not an
164
+ agent's. The bridge lists, matches and runs none of them, the policy cannot list them, and the
165
+ member is listed in their place. A member that holds a secret withholds its own element.
166
+
167
+ A custom element of `@polymorph/elements-ui` renders its Solid member, so the member inside it
168
+ registers too, and a page that builds the elements with a bundler creates a bridge as any
169
+ application does. A page with no build loads the bridge with `loadAgentBridge`, which
170
+ `polymorph.js` and `polymorph-all.js` export: it resolves to `@polymorph/engine/agent`, built with
171
+ the elements so it reads the registry they write to, and `polymorph.js` fetches it as a chunk of
172
+ its own on the first call.
173
+
174
+ **Registering before the bridge loads.**
175
+
176
+ `@polymorph/engine/webmcp` is a new entry point, an addition that changes no existing one, and
177
+ holds none of the bridge. `registerWebMCPOnCall(load, options)` registers the three tools with the
178
+ browser's WebMCP API at once, and on the first call of any of them calls `load`, a dynamic import
179
+ of `@polymorph/engine/agent`, once, and creates the bridge with `options`. A load that fails
180
+ resolves the call to `{ error: { code: 'failed', message } }`, and the next call loads again.
181
+ `applyAgentSetting(value)` and `AGENT_ATTRIBUTE` (`data-agent`) do what a page's agent setting
182
+ says: nothing without one, `on-call` as `registerWebMCPOnCall`, and `eager`, which loads the
183
+ bridge at once; another value warns, and without a WebMCP API neither registers nor loads
184
+ anything. `agentTools` and the new registration read one list of the tools' names, titles,
185
+ descriptions, schemas and hints.
186
+
187
+ One registration of the tools stands on a page at a time. While one does, a second
188
+ `registerWebMCP`, a `registerWebMCPOnCall` or a page's setting registers nothing and warns in the
189
+ console, where before the browser refused the second registration's names without a word.
190
+
191
+ A page with no build states `<html data-agent="on-call">` or `data-agent="eager"` and writes no
192
+ script: `polymorph.js` and `polymorph-all.js` read it as they load. `polymorph init --framework
193
+ elements` names the setting in the app's `AGENTS.md`, and its example page states none.
194
+
195
+ **The members.**
196
+
197
+ These members register, in every web vocabulary. Their props, markup and defaults are
198
+ unchanged. The system card lists each one's actions and states.
199
+
200
+ - Controls: Button, AvatarButton, ProviderButton, RecordButton, SplitButton, Link, Input,
201
+ Textarea, SearchInput, NumberInput, PhoneInput, PasswordInput, OTPInput, TagInput, InlineEdit,
202
+ ColorInput, Select, Combobox, MultiSelect, TreeSelect, Checkbox, CheckboxGroup, RadioGroup,
203
+ ChoiceCard, SegmentedControl, ModeSwitch, Switch, Slider, Rating, Calendar, DatePicker,
204
+ DateRangePicker, MonthInput, TimeInput, DurationInput, FileUpload and ImageEditor. A Button
205
+ reads `pressed` as `aria-pressed` says it, and as `null` on a Button that is not a toggle, and
206
+ `expanded` as `aria-expanded` says it, and as `null` on a Button that discloses nothing.
207
+ - Overlays: Dialog, ConfirmDialog, Drawer, Popover, Lightbox, Tour, Menu, ContextMenu, Menubar,
208
+ Command, Tabs and Toast. Toast registers on its viewport, which reads the notices on screen
209
+ and dismisses one or runs its action through the toast store.
210
+ - Structure: Accordion, Collapsible, Alert, Banner, Pagination, CursorPagination, Table,
211
+ DataTable, Tree, Stepper, Carousel, FilterBar, SectionNav, TableOfContents, Breadcrumbs, List
212
+ and AudioPlayer. A Table reads its own sortable headers, and its `sort` presses a header's
213
+ control once, so its caller decides the order; the Table a DataTable draws registers nothing. A
214
+ List reads the items that navigate or are picked from its list, with the current one, and its
215
+ `choose` presses an item's link or button, so `onSelect`, `onNavigate` or the browser takes it
216
+ as a person's press; an item that is only read is not a choice.
217
+ A Card with `href` registers its stretched link, which an agent presses as a person clicks
218
+ it, and ErrorSummary lists its errors and follows one to its field with `choose`, reading its
219
+ links with List's `listItems`. A JsonTree reads its open branches and the branches a reader can
220
+ see, each by the JSON Pointer of its value, and its `expand` and `collapse` press a branch's
221
+ toggle.
222
+ - Layout: SplitPane reads its divider's position in percent, as `aria-valuenow` reports it, and
223
+ its `set` moves the divider within the bounds its floors give and commits, as a key press does.
224
+ - Charts: AreaChart, BarChart, DonutChart, FunnelChart, Heatmap, Histogram, LineChart,
225
+ RadarChart, ScatterChart and Treemap, while they have `onSelect`. `items` lists the marks the
226
+ keys reach, labelled with what the live region says there, at most `CHART_MARK_CAP` of them:
227
+ the whole positions around the reading position. `position`, which the figure shows as
228
+ `data-position`, and `count` say where the reading is and how many positions the chart has,
229
+ `read` moves the reading as Left and Right do, and `choose` moves it to a listed mark and
230
+ activates it as Enter does, so `onSelect` receives a person's payload. A chart without
231
+ `onSelect` registers nothing, and Sparkline, which takes none, never does.
232
+ - Conversation: PromptInput, ChatThread, ToolCall, ReasoningDisclosure, AttachmentChip,
233
+ ArtifactPane and ApprovalCard. AppShell registers too: an agent collapses and expands its rail,
234
+ opens and closes its drawer below the breakpoint, reads the application's destinations from
235
+ its navigation, with the current one, and goes to one by pressing its NavItem, so `onNavigate`
236
+ or the browser takes it as a person's press.
237
+
238
+ What an agent is not given:
239
+
240
+ - A password and a one-time code are secret, and no action writes them. PasswordInput's reveal
241
+ toggle is not an agent's.
242
+ - No action confirms for a person. ConfirmDialog declares `cancel` only and withholds its
243
+ confirm Button, its phrase field and the Dialog it draws. ApprovalCard declares no action and
244
+ withholds its Buttons.
245
+ - A Button with `tone="danger"`, and a `danger`-toned entry of a Menu, ContextMenu, Menubar or
246
+ SplitButton, asks a person to confirm.
247
+ - RecordButton lets an agent stop a recording and never start one. FileUpload lets an agent
248
+ remove or retry a file and never add one. AudioPlayer and ImageEditor are read only.
249
+ - CopyButton, Tooltip, HoverCard and FormField give an agent nothing, and each spec says why.
250
+ Plan and ChatMessage are not registered, so they stay server components.
251
+ Citation and SourceList are not registered either: each of their links opens a new tab,
252
+ which an agent's press cannot open, and their words are on the page.
253
+ - The Popover ColorInput draws for its picker registers nothing, and ColorInput withholds its
254
+ panel, so an agent sees one ColorInput.
255
+
256
+ A React member that passed `value` or `defaultValue` straight to its substrate now holds the
257
+ value itself and keeps the substrate controlled, controlled when the prop is given, so an
258
+ agent's action and a person's reach the same handler in both forms: Checkbox, Switch,
259
+ RadioGroup, SegmentedControl, ChoiceCard, Select, Slider, Tabs, ReasoningDisclosure and
260
+ ToolCall. A native `form.reset()` now resets a Checkbox row's state attribute too.
261
+
262
+ **The tooling.**
263
+
264
+ - `@polymorph/registry`: each member carries an `agent` field, the statements of its spec's
265
+ `agent` fence, or `null` for a member agents cannot see. `@polymorph/registry/agent` exports
266
+ the grammar, in which a `number` state reads `null` while the member holds none, as an `id`
267
+ state does, and an action may say `presses <part>`, the part whose element it presses with the
268
+ element's own click. The coverage law fails on a control or an overlay whose spec has no decided
269
+ `## Agent` section, and the staleness law on a fence the code does not match.
270
+ - `@polymorph/shells`: a description takes an `agent` block (`on` or `element`, `state`,
271
+ `actions`, `secret`, `destructive`, `withholds`), which each renderer writes as a mount effect
272
+ that registers the instance. A compound part may give the block instead, which registers under
273
+ its member's name (Toast's viewport). A member that lends its identity reads the element the member it
274
+ lends to hands back, as `borrowed`; the Solid foundation exports `BORROWED` and
275
+ `BorrowedHolder`, and the Angular foundation `BORROWED`, `BorrowedHolder`, `handBack`,
276
+ `borrowedHolder`, `lenderHolder` and `KEEPS_HOLDER`.
277
+ - `@polymorph/conformance`: the runner executes every statement of an agent fence against every
278
+ renderer, with a bridge installed; `agentConformanceLaw` holds a shell's fences, and
279
+ `conformanceLaw` calls it. `WINDOW_SIZES` lists the fixture entries the runner mounts at a
280
+ window size other than the default, through the harness's new `viewport`, so an action that
281
+ exists only below a breakpoint is checked there.
282
+ - `@polymorph/engine/testing` exports `agentRegistrations()`, every registered member's id, name
283
+ and elements, withheld ones included.
284
+ - `pnpm new:member` writes the `## Agent` section with a placeholder the coverage law refuses.
285
+
286
+ - 56e7665: `@polymorph/elements` and `@polymorph/elements-ui` are new packages: the vocabulary as custom
287
+ elements, for a page written in HTML with no build, a server-rendered template, or a page htmx or
288
+ Turbo swaps. Each member is an element, `poly-` and its kebab name (`<poly-button>`,
289
+ `<poly-tabs-content>`), that renders the generated Solid member into itself in the light DOM. The
290
+ elements are a distribution of the Solid rendering, with its recipes and its behaviour, and add no
291
+ decision of their own. They are published as `@metamorph-labs/polymorph-elements` and
292
+ `@metamorph-labs/polymorph-elements-ui`, and `design/frameworks/elements.json` says which members
293
+ they ship.
294
+
295
+ A prop is an attribute in kebab case and a property in camel case: a boolean is present or
296
+ `"false"`, data is a JSON attribute, a date or a time is ISO 8601 text, and a function, a render
297
+ prop or a ref is a property set from script. A node prop is a child with `slot="name"`, and
298
+ `<template slot="name">` gives text or several nodes. A child added to the element after it
299
+ renders joins its slot, and `element.removeChild(child)` takes one out of its slot, wherever the
300
+ member drew it; replacing every child renders the member again. A callback is the event `poly-<name>`
301
+ (`poly-change`, `poly-open-change`), whose `detail` is its first argument; it bubbles, and a
302
+ listener can hand the member a promise with `event.waitUntil`. A controlled prop follows the
303
+ reader: after its change event the element sets its own property, unless a listener calls
304
+ `preventDefault()`. A member that asks whether its event is heard learns it from a listener added
305
+ to its element, or from `listens="name"`.
306
+
307
+ An element draws no box: while it renders its member it carries the custom state `poly-host`, and
308
+ `:state(poly-host)` is `display: contents`. A table's section, row and cell and a list's item are replaced in the
309
+ document by the element they render. The elements need Chrome 125, Safari 17.4 or Firefox 126.
310
+ Rendering is client-only, and the elements are not form-associated: each member's own input posts.
311
+ `restore()` puts back the markup a page wrote before a page snapshot (`turbo:before-cache`,
312
+ `htmx:beforeHistorySave`).
313
+
314
+ A page with no build links `polymorph.css` and a theme sheet, runs `prepaint.js` first in
315
+ `<head>`, and loads `polymorph.js` as a module script: it defines every tag at once and loads each
316
+ member's code, a chunk of its own, the first time one of its elements renders, so a page with one
317
+ Button loads Button and what it composes. `polymorph-all.js` loads every element in one file. Both
318
+ export `restore`, `toast` and `loadAgentBridge` for the page's own module script, and read
319
+ `<html data-agent>` as they load: without it nothing more is fetched; `on-call` registers the agent
320
+ bridge's tools with the browser's WebMCP API and fetches the bridge on the first call, and
321
+ `eager` fetches it at load (`docs/agents.md`). `polymorph.css` holds the base
322
+ layer, every recipe with the forms that reach through an element, Icon's stylesheet, the host rule,
323
+ and rules for an element that has not rendered: a closed overlay's content stays hidden, and a
324
+ table's and a list's parts lay out as the elements they render. The files are in
325
+ `@polymorph/elements-ui/dist/cdn/`, with a theme sheet per house pairing (`themes/<system>.css`).
326
+ No public URL serves them, so `polymorph init --framework elements` copies them into the app's
327
+ static directory with a theme sheet and an example page (`docs/consuming.md`). The files report an
328
+ attribute an element cannot read, and each member's own warnings, in the console on every page,
329
+ because nothing lints a page written in HTML.
330
+
331
+ An app with a build imports one element's module (`@polymorph/elements-ui/controls/Button`) or
332
+ every element (`@polymorph/elements-ui`). Each element's module brings its Solid member compiled
333
+ with its recipe, and the base layer, Icon's stylesheet and the host rules through
334
+ `@polymorph/elements`; Solid, Zag and the Solid foundation are dependencies, one copy each.
335
+
336
+ A prop named as a method every element inherits has no property, so the method keeps working on
337
+ the element, and its attribute sets it: Diff's `before` and `after` are attributes, and
338
+ `diff.before(node)` is `ChildNode.before()`. A controlled prop the page never set leaves the member
339
+ uncontrolled. `defineLazy` defines a tag before its member's code is loaded, and
340
+ `@polymorph/elements/loader` holds what a page that defines every tag at once loads first.
341
+ `@polymorph/elements/temporal` holds the codecs that read a date or a time, which the module of
342
+ each member with one gives `define`, so the date library loads only with such a member. On a page
343
+ that loads a member's code when one of its elements first renders, the property of a date or a
344
+ time set before that code has loaded reads `undefined` until it has.
345
+
346
+ - Updated dependencies [d84171d]
347
+ - Updated dependencies [508275a]
348
+ - Updated dependencies [5334be0]
349
+ - Updated dependencies [73837b5]
350
+ - Updated dependencies [4dc0747]
351
+ - Updated dependencies [a4dc653]
352
+ - Updated dependencies [bcbaa92]
353
+ - Updated dependencies [2da1598]
354
+ - Updated dependencies [56e7665]
355
+ - Updated dependencies [ac64e4c]
356
+ - Updated dependencies [709d7b3]
357
+ - @polymorph/engine@1.0.13
358
+ - @polymorph/solid@1.0.13
359
+ - @polymorph/recipes@1.0.13
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Metamorph, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,73 @@
1
- # Temporary Holding Version
1
+ # @polymorph/elements
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The foundation of the elements: what every `poly-*` custom element shares. An element renders its
4
+ generated Solid member ([`@polymorph/solid-ui`](../solid-ui/README.md)) into itself, in the light
5
+ DOM, so the elements are a distribution of the Solid rendering and make no decision of their own.
6
+ [`@polymorph/elements-ui`](../elements-ui/README.md) holds the elements themselves, and
7
+ [docs/shells.md](../../docs/shells.md#the-elements-foundation-polymorphelements) says what this
8
+ package does for them.
9
+
10
+ ## What it contains
11
+
12
+ - `src/element.ts`: `PolyElement`, the element base class, `define`, which turns a definition and a
13
+ Solid member (and, for a member with a date or a time prop, the temporal codecs) into a custom
14
+ element, `defineLazy`, which defines the tag before its member's code
15
+ is loaded, and `restore`, which puts back the markup a page wrote. The base class takes the
16
+ element's children into the member's slots, renders the elements of a document in document
17
+ order once their code has loaded, follows a swap of its children, dispatches each callback as a
18
+ `poly-*` event, and replaces a table's or a list's part with the element it renders. A prop
19
+ named as a method every element inherits (Diff's `before` and `after`) has no property, so the
20
+ method keeps working, and its attribute sets it (`inheritedMethod`).
21
+ - `src/loader.ts`: what a page with no build loads first: `defineAll`, which defines every tag at
22
+ once, each loading its member's code the first time one of its elements renders, with
23
+ `restore` and `toast`. It defines no element itself.
24
+ - `src/definition.ts`: what a definition is (`ElementDefinition`, `Codec`), and the names: `poly-`
25
+ and the kebab name of a member, a part and an event (`tagOf`, `eventOf`), a prop's attribute
26
+ and property, a slot's attribute.
27
+ - `src/codecs.ts`: how an attribute's text reads into a prop (`decode`): text, a number, presence,
28
+ JSON, a union of literals, and ISO 8601 dates and times as the engine's values; a property's
29
+ value as the member takes it (`coerce`), and the attribute text that reads back as a value
30
+ (`encode`). It is for a script or a tool that reads values itself.
31
+ - `src/attributes.ts`: the same codecs as the element reads its attributes through. It imports no
32
+ date type, and reads a date or a time through the temporal codecs it is given, so the date
33
+ library loads only with a member that takes a date or a time.
34
+ - `src/temporal.ts`: the temporal codecs (`time`, `date`, `range`), which read ISO 8601 text as
35
+ `@internationalized/date`'s values through the engine. The definition module of each member with
36
+ a date or a time prop imports them and gives them to `define`.
37
+ - `src/events.ts`: `PolymorphEvent`, a `CustomEvent` with `waitUntil(promise)`.
38
+ - `src/fixture.ts`: the element-form states fixture's types, and `listen` and `holding`, which its
39
+ `setup` uses.
40
+ - `src/host.css`: `:state(poly-host):not([hidden]) { display: contents }`, the rule that makes an
41
+ element draw no box while it renders its member.
42
+ - `src/pending.css`: the rules for an element that has not rendered its member, generated by
43
+ `pnpm shells`: a closed overlay's content stays hidden, and a table's and a list's parts lay out
44
+ as the elements that replace them. Never edit it by hand.
45
+ - `src/icon/Icon.ts`: `<poly-icon>`, generated by `pnpm shells`. Never edit it by hand.
46
+ - `src/index.ts`: the entry, which imports the base layer (`@polymorph/recipes/base.css`), the
47
+ host rule and the pending rules, so every element brings them, and re-exports the engine whole
48
+ (`@polymorph/engine`, its charts, Markdown and QR subpaths), the Solid foundation's toast store,
49
+ and the types the React vocabulary exports beside its members.
50
+
51
+ While an element renders its member it carries the custom state `poly-host`, so the elements need
52
+ Chrome 125, Safari 17.4 or Firefox 126. An element is not form-associated: each member's own input
53
+ posts.
54
+
55
+ ## Entry points
56
+
57
+ | Import | In-repo (`exports`) |
58
+ | --- | --- |
59
+ | `@polymorph/elements` | `src/index.ts` |
60
+ | `@polymorph/elements/codecs` | `src/codecs.ts` |
61
+ | `@polymorph/elements/definition` | `src/definition.ts` |
62
+ | `@polymorph/elements/icon` | `src/icon/Icon.ts` |
63
+ | `@polymorph/elements/loader` | `src/loader.ts` |
64
+ | `@polymorph/elements/temporal` | `src/temporal.ts` |
65
+ | `@polymorph/elements/host.css` | `src/host.css` |
66
+ | `@polymorph/elements/pending.css` | `src/pending.css` |
67
+
68
+ The published build (`pnpm build:packages`, `vite.build.config.ts`) writes one module per source
69
+ module to `dist/`, with the two stylesheets beside them; its index also imports Icon's stylesheet,
70
+ `@polymorph/solid/style.css`. Solid, the Solid foundation, the engine and the recipes are external.
71
+ It depends on `@polymorph/engine`, `@polymorph/recipes`, `@polymorph/solid` and `solid-js`, as
72
+ dependencies, because a page has no Solid of its own. It is published as
73
+ `@metamorph-labs/polymorph-elements`.
@@ -0,0 +1,59 @@
1
+ //#region src/attributes.ts
2
+ var e = class extends Error {
3
+ name = "Unreadable";
4
+ }, t = (e) => typeof e == "object" && "temporal" in e;
5
+ function n(t) {
6
+ let n = Number(t);
7
+ if (t.trim() === "" || Number.isNaN(n)) throw new e(`"${t}" is not a number`);
8
+ return n;
9
+ }
10
+ function r(i, a, o) {
11
+ if (a !== null) {
12
+ if (i === "string") return a;
13
+ if (i === "boolean") return a !== "false";
14
+ if (i === "number") return n(a);
15
+ if (i !== "property") {
16
+ if (i === "json") try {
17
+ return JSON.parse(a);
18
+ } catch {
19
+ throw new e(`"${a.length > 60 ? `${a.slice(0, 60)}…` : a}" is not JSON`);
20
+ }
21
+ if (i === "set") {
22
+ let t = r("json", a);
23
+ if (!Array.isArray(t)) throw new e(`"${a}" is not a JSON array of a set's members`);
24
+ return new Set(t);
25
+ }
26
+ if (t(i)) {
27
+ if (o === void 0) throw new e(`"${a}" is read through the temporal codecs, which were not given (@polymorph/elements/temporal)`);
28
+ return o[i.temporal](a);
29
+ }
30
+ for (let e of i.union) if (String(e) === a) return e;
31
+ if (i.boolean === !0 && (a === "" || a === "true" || a === "false")) return a !== "false";
32
+ if (i.json === !0 && /^\s*[[{]/.test(a)) return r("json", a);
33
+ if (i.number === !0 && a.trim() !== "" && !Number.isNaN(Number(a))) return Number(a);
34
+ if (i.string === !0) return a;
35
+ if (i.boolean === !0) return !0;
36
+ if (i.json === !0) return r("json", a);
37
+ throw new e(`"${a}" is none of ${i.union.map((e) => String(e)).join(", ")}`);
38
+ }
39
+ }
40
+ }
41
+ function i(e, n, i) {
42
+ return typeof n == "string" && t(e) ? r(e, n, i) : e === "set" && Array.isArray(n) ? new Set(n) : n;
43
+ }
44
+ function a(n, r) {
45
+ if (r == null) return null;
46
+ if (n === "property") throw new e("a prop set from script only has no attribute");
47
+ if (typeof r == "boolean") return r ? "" : "false";
48
+ if (typeof r == "string" || typeof r == "number") return String(r);
49
+ if (r instanceof Set) return JSON.stringify([...r]);
50
+ if (t(n)) {
51
+ let e = r;
52
+ return n.temporal === "range" ? `${String(e.start)}/${String(e.end)}` : String(r);
53
+ }
54
+ return JSON.stringify(r);
55
+ }
56
+ //#endregion
57
+ export { e as Unreadable, i as coerce, r as decode, a as encode, t as readsTemporal };
58
+
59
+ //# sourceMappingURL=attributes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"attributes.js","names":[],"sources":["../src/attributes.ts"],"sourcesContent":["import type { CalendarDate, CalendarDateTime, Time } from '@polymorph/engine'\n\nimport type { Codec } from './definition'\n\n/**\n * How an attribute's text becomes a prop's value (`Codec`, `definition.ts`),\n * as the element reads it.\n *\n * An absent attribute is `undefined`, so the member's default applies. A\n * boolean is true when the attribute is present with any value but `\"false\"`,\n * which is how HTML turns off a boolean whose default is true\n * (`dismissible=\"false\"`). Text a codec cannot read throws `Unreadable`,\n * which the element reports and reads as `undefined`.\n *\n * A date or a time is read through the temporal codecs (`temporal.ts`), which\n * the caller passes in. This module imports no date type at run time, so the\n * date library loads only with a member that takes a date or a time: that\n * member's definition module gives the temporal codecs to `define`.\n * `codecs.ts` passes them on every call, for a script that reads values itself.\n */\n\n/** Text an attribute's codec cannot read. */\nexport class Unreadable extends Error {\n override name = 'Unreadable'\n}\n\n/** How the temporal codecs read ISO 8601 text, by the kind each reads (`temporal.ts`). */\nexport interface TemporalCodecs {\n /** `09:30`, `09:30:15` as a `Time`. */\n readonly time: (text: string) => Time\n /** `2026-07-15` as a `CalendarDate`, and `2026-07-15T09:30` as a `CalendarDateTime`. */\n readonly date: (text: string) => CalendarDate | CalendarDateTime\n /** `2026-07-01/2026-07-15` as the range a range picker takes: two days, start first. */\n readonly range: (text: string) => { start: CalendarDate; end: CalendarDate }\n}\n\n/** Whether a codec reads a date or a time. */\nexport const readsTemporal = (\n codec: Codec,\n): codec is Extract<Codec, { readonly temporal: unknown }> =>\n typeof codec === 'object' && 'temporal' in codec\n\n/** A number written as text: a decimal, an exponent, or `Infinity`. */\nfunction number(text: string): number {\n const value = Number(text)\n if (text.trim() === '' || Number.isNaN(value)) throw new Unreadable(`\"${text}\" is not a number`)\n return value\n}\n\n/**\n * An attribute's text as the prop's value. A date or a time is read through\n * `temporal`; without it, a temporal codec's text is `Unreadable`.\n */\nexport function decode(codec: Codec, text: string | null, temporal?: TemporalCodecs): unknown {\n if (text === null) return undefined\n if (codec === 'string') return text\n if (codec === 'boolean') return text !== 'false'\n if (codec === 'number') return number(text)\n if (codec === 'property') return undefined\n if (codec === 'json') {\n try {\n return JSON.parse(text) as unknown\n } catch {\n throw new Unreadable(`\"${text.length > 60 ? `${text.slice(0, 60)}…` : text}\" is not JSON`)\n }\n }\n if (codec === 'set') {\n const members = decode('json', text)\n if (!Array.isArray(members)) {\n throw new Unreadable(`\"${text}\" is not a JSON array of a set's members`)\n }\n return new Set(members)\n }\n if (readsTemporal(codec)) {\n if (temporal === undefined) {\n throw new Unreadable(\n `\"${text}\" is read through the temporal codecs, which were not given (@polymorph/elements/temporal)`,\n )\n }\n return temporal[codec.temporal](text)\n }\n for (const literal of codec.union) if (String(literal) === text) return literal\n if (codec.boolean === true && (text === '' || text === 'true' || text === 'false')) {\n return text !== 'false'\n }\n if (codec.json === true && /^\\s*[[{]/.test(text)) return decode('json', text)\n if (codec.number === true && text.trim() !== '' && !Number.isNaN(Number(text))) {\n return Number(text)\n }\n if (codec.string === true) return text\n if (codec.boolean === true) return true\n if (codec.json === true) return decode('json', text)\n throw new Unreadable(\n `\"${text}\" is none of ${codec.union.map((value) => String(value)).join(', ')}`,\n )\n}\n\n/**\n * A value set through a property, as the member takes it: a temporal prop\n * set to its ISO text reads it as its attribute would, through `temporal`,\n * and a set prop set to an array is the set of its items. Any other value is\n * the member's as it is.\n */\nexport function coerce(codec: Codec, value: unknown, temporal?: TemporalCodecs): unknown {\n if (typeof value === 'string' && readsTemporal(codec)) return decode(codec, value, temporal)\n if (codec === 'set' && Array.isArray(value)) return new Set(value)\n return value\n}\n\n/**\n * The attribute text that reads back as a value (`decode`'s inverse), for a\n * prop set by its attribute alone: `null` for no attribute, which reads as the\n * prop left out. A prop set from script only has no text.\n */\nexport function encode(codec: Codec, value: unknown): string | null {\n if (value === undefined || value === null) return null\n if (codec === 'property') throw new Unreadable('a prop set from script only has no attribute')\n if (typeof value === 'boolean') return value ? '' : 'false'\n if (typeof value === 'string' || typeof value === 'number') return String(value)\n if (value instanceof Set) return JSON.stringify([...value])\n if (readsTemporal(codec)) {\n const range = value as { start?: unknown; end?: unknown }\n return codec.temporal === 'range'\n ? `${String(range.start)}/${String(range.end)}`\n : String(value)\n }\n return JSON.stringify(value)\n}\n"],"mappings":";AAsBA,IAAa,IAAb,cAAgC,MAAM;CACpC,OAAgB;AAClB,GAaa,KACX,MAEA,OAAO,KAAU,YAAY,cAAc;AAG7C,SAAS,EAAO,GAAsB;CACpC,IAAM,IAAQ,OAAO,CAAI;CACzB,IAAI,EAAK,KAAK,MAAM,MAAM,OAAO,MAAM,CAAK,GAAG,MAAM,IAAI,EAAW,IAAI,EAAK,kBAAkB;CAC/F,OAAO;AACT;AAMA,SAAgB,EAAO,GAAc,GAAqB,GAAoC;CACxF,UAAS,MACb;MAAI,MAAU,UAAU,OAAO;EAC/B,IAAI,MAAU,WAAW,OAAO,MAAS;EACzC,IAAI,MAAU,UAAU,OAAO,EAAO,CAAI;EACtC,UAAU,YACd;OAAI,MAAU,QACZ,IAAI;IACF,OAAO,KAAK,MAAM,CAAI;GACxB,QAAQ;IACN,MAAM,IAAI,EAAW,IAAI,EAAK,SAAS,KAAK,GAAG,EAAK,MAAM,GAAG,EAAE,EAAE,KAAK,EAAK,cAAc;GAC3F;GAEF,IAAI,MAAU,OAAO;IACnB,IAAM,IAAU,EAAO,QAAQ,CAAI;IACnC,IAAI,CAAC,MAAM,QAAQ,CAAO,GACxB,MAAM,IAAI,EAAW,IAAI,EAAK,yCAAyC;IAEzE,OAAO,IAAI,IAAI,CAAO;GACxB;GACA,IAAI,EAAc,CAAK,GAAG;IACxB,IAAI,MAAa,KAAA,GACf,MAAM,IAAI,EACR,IAAI,EAAK,2FACX;IAEF,OAAO,EAAS,EAAM,SAAS,CAAC,CAAI;GACtC;GACA,KAAK,IAAM,KAAW,EAAM,OAAO,IAAI,OAAO,CAAO,MAAM,GAAM,OAAO;GACxE,IAAI,EAAM,YAAY,OAAS,MAAS,MAAM,MAAS,UAAU,MAAS,UACxE,OAAO,MAAS;GAElB,IAAI,EAAM,SAAS,MAAQ,WAAW,KAAK,CAAI,GAAG,OAAO,EAAO,QAAQ,CAAI;GAC5E,IAAI,EAAM,WAAW,MAAQ,EAAK,KAAK,MAAM,MAAM,CAAC,OAAO,MAAM,OAAO,CAAI,CAAC,GAC3E,OAAO,OAAO,CAAI;GAEpB,IAAI,EAAM,WAAW,IAAM,OAAO;GAClC,IAAI,EAAM,YAAY,IAAM,OAAO;GACnC,IAAI,EAAM,SAAS,IAAM,OAAO,EAAO,QAAQ,CAAI;GACnD,MAAM,IAAI,EACR,IAAI,EAAK,eAAe,EAAM,MAAM,KAAK,MAAU,OAAO,CAAK,CAAC,CAAC,CAAC,KAAK,IAAI,GAC7E;EA9BE;CAT6B;AAwCjC;AAQA,SAAgB,EAAO,GAAc,GAAgB,GAAoC;CAGvF,OAFI,OAAO,KAAU,YAAY,EAAc,CAAK,IAAU,EAAO,GAAO,GAAO,CAAQ,IACvF,MAAU,SAAS,MAAM,QAAQ,CAAK,IAAU,IAAI,IAAI,CAAK,IAC1D;AACT;AAOA,SAAgB,EAAO,GAAc,GAA+B;CAClE,IAAI,KAAiC,MAAM,OAAO;CAClD,IAAI,MAAU,YAAY,MAAM,IAAI,EAAW,8CAA8C;CAC7F,IAAI,OAAO,KAAU,WAAW,OAAO,IAAQ,KAAK;CACpD,IAAI,OAAO,KAAU,YAAY,OAAO,KAAU,UAAU,OAAO,OAAO,CAAK;CAC/E,IAAI,aAAiB,KAAK,OAAO,KAAK,UAAU,CAAC,GAAG,CAAK,CAAC;CAC1D,IAAI,EAAc,CAAK,GAAG;EACxB,IAAM,IAAQ;EACd,OAAO,EAAM,aAAa,UACtB,GAAG,OAAO,EAAM,KAAK,EAAE,GAAG,OAAO,EAAM,GAAG,MAC1C,OAAO,CAAK;CAClB;CACA,OAAO,KAAK,UAAU,CAAK;AAC7B"}
package/dist/codecs.js ADDED
@@ -0,0 +1,13 @@
1
+ import { Unreadable as e, coerce as t, decode as n, encode as r } from "./attributes.js";
2
+ import { temporal as i } from "./temporal.js";
3
+ //#region src/codecs.ts
4
+ function a(e, t) {
5
+ return n(e, t, i);
6
+ }
7
+ function o(e, n) {
8
+ return t(e, n, i);
9
+ }
10
+ //#endregion
11
+ export { e as Unreadable, o as coerce, a as decode, r as encode };
12
+
13
+ //# sourceMappingURL=codecs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codecs.js","names":[],"sources":["../src/codecs.ts"],"sourcesContent":["import { coerce as coerceThrough, decode as decodeThrough, type TemporalCodecs } from './attributes'\nimport type { Codec } from './definition'\nimport { temporal } from './temporal'\n\n/**\n * How an attribute's text becomes a prop's value (`@polymorph/elements/codecs`),\n * for a script and a tool that read or write values themselves: every codec,\n * the temporal ones included (`Codec`, `definition.ts`).\n *\n * An absent attribute is `undefined`, so the member's default applies. A\n * boolean is true when the attribute is present with any value but `\"false\"`.\n * Text a codec cannot read throws `Unreadable`.\n *\n * The element does not read through this module. It reads through\n * `attributes.ts`, which imports no date type, and is given the temporal\n * codecs by the definition module of a member that takes a date or a time.\n */\n\nexport { encode, Unreadable } from './attributes'\nexport type { TemporalCodecs }\n\n/** An attribute's text as the prop's value, a date or a time included. */\nexport function decode(codec: Codec, text: string | null): unknown {\n return decodeThrough(codec, text, temporal)\n}\n\n/**\n * A value set through a property, as the member takes it: a temporal prop\n * set to its ISO text reads it as its attribute would, and a set prop set to\n * an array is the set of its items. Any other value is the member's as it is.\n */\nexport function coerce(codec: Codec, value: unknown): unknown {\n return coerceThrough(codec, value, temporal)\n}\n"],"mappings":";;;AAsBA,SAAgB,EAAO,GAAc,GAA8B;CACjE,OAAO,EAAc,GAAO,GAAM,CAAQ;AAC5C;AAOA,SAAgB,EAAO,GAAc,GAAyB;CAC5D,OAAO,EAAc,GAAO,GAAO,CAAQ;AAC7C"}
@@ -0,0 +1,6 @@
1
+ //#region src/definition.ts
2
+ var e = "poly-", t = (e) => e.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase(), n = (e) => e.replace(/-([a-z])/g, (e, t) => t.toUpperCase()), r = (n) => `${e}${t(n)}`, i = (e) => /^(aria|data)-/.test(e) ? e : t(e), a = (e) => n(e), o = (n) => `${e}${t(n.slice(2))}`, s = (e) => e === "children" ? "" : t(e);
3
+ //#endregion
4
+ export { e as PREFIX, i as attributeOf, n as camel, o as eventOf, t as kebab, a as propertyOf, s as slotOf, r as tagOf };
5
+
6
+ //# sourceMappingURL=definition.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"definition.js","names":[],"sources":["../src/definition.ts"],"sourcesContent":["/**\n * What an element is, as `pnpm shells` writes it for each member and part\n * (`packages/elements-ui/src/definitions.ts`): its tag, the member it renders,\n * how each attribute reads into a prop, the events it dispatches, the slots\n * its children fill, and which of its parts its member renders in its place.\n *\n * A definition is data. The foundation's `define` turns one and a Solid\n * member into a custom element.\n */\n\n/** The prefix of every tag and every event the elements write. */\nexport const PREFIX = 'poly-'\n\n/**\n * How an attribute's text reads into a prop:\n *\n * - `string`, `number`, `boolean`: the text, a number, or presence (`\"false\"` is false);\n * - `json`: data, parsed from JSON (arrays, objects, named data types);\n * - `set`: a set, read from a JSON array of its members (`[\"a\",\"b\"]`);\n * - `{ union }`: a union, read as the literal it names, and otherwise by its\n * open members: `boolean` (presence, `\"false\"`), `json` (text that opens\n * an array or an object), `number`, then `string`;\n * - `{ temporal }`: an ISO 8601 date or time, read as the engine's value:\n * `time` reads `09:30` as a `Time`; `date` reads `2026-07-15` as a\n * `CalendarDate` and `2026-07-15T09:30` as a `CalendarDateTime`; `range`\n * reads `2026-07-01/2026-07-15` as a range of two dates;\n * - `property`: no attribute; a function or a ref, set from script.\n */\nexport type Codec =\n | 'string'\n | 'number'\n | 'boolean'\n | 'json'\n | 'set'\n | 'property'\n | { readonly temporal: 'time' | 'date' | 'range' }\n | {\n readonly union: readonly (string | number)[]\n readonly string?: true\n readonly number?: true\n readonly boolean?: true\n readonly json?: true\n }\n\n/** An event a member emits, as the element dispatches it. */\nexport interface ElementEvent {\n /** The event's type: `poly-` and the event's kebab name (`poly-open-change`). */\n readonly type: string\n /**\n * The member reads whether its caller handles the event (`listening`), so\n * the element hands it the handler only while a listener is added or the\n * `listens` attribute names the event. Any other event is always handed.\n */\n readonly listened?: true\n}\n\n/**\n * A callback a JSON value's objects require (`onSelect` on a Menu's items),\n * which the element completes on each object that has none: the completed\n * callback dispatches `type` on the element, with the object and its index\n * in its list as `detail` (`{ item, index }`), and `value` when the member\n * passes the callback a value (a checkbox entry's `checked`).\n */\nexport interface ElementCallback {\n /** The fields the objects are reached through, dotted; `''` is the value itself or its items. */\n readonly at: string\n /** The callback's name on each object: `onSelect`. */\n readonly name: string\n /** The event it dispatches: `poly-select`. */\n readonly type: string\n /**\n * The values the object's literal fields hold for its type to require the\n * callback, `null` for a field left out: a Menu's item takes `onSelect`\n * where `kind` is `'item'` or absent, and a checkbox entry does not.\n */\n readonly where?: readonly { readonly field: string; readonly is: readonly (string | null)[] }[]\n}\n\n/** One element: a member or a public part of one. */\nexport interface ElementDefinition {\n /** The tag: `poly-button`, `poly-tabs-content`. */\n readonly tag: string\n /** The member or part it renders, by its component's name: `Button`, `TabsContent`. */\n readonly member: string\n /** Each value prop, by its React name, with the codec its attribute reads through. */\n readonly props: Readonly<Record<string, Codec>>\n /** Each event prop, by its React name (`onOpenChange`), with the event it dispatches. */\n readonly events: Readonly<Record<string, ElementEvent>>\n /** The node props its children fill, by their React names: `children` and the named slots. */\n readonly slots: readonly string[]\n /**\n * The node fields of an object prop, by the prop's React name: children\n * whose `slot` names the prop and the field (`slot=\"topbar.leading\"`) fill\n * the field of the object the prop reads.\n */\n readonly fields?: Readonly<Record<string, readonly string[]>>\n /** The callbacks the element completes in a JSON prop's objects, by the prop's React name. */\n readonly callbacks?: Readonly<Record<string, readonly ElementCallback[]>>\n /**\n * The controlled props, each with the event that reports its change\n * (`open` with `onOpenChange`). After the change event, unless a listener\n * cancels it, the element sets the prop to the value the event carries.\n */\n readonly controlled?: Readonly<Record<string, string>>\n /**\n * A part whose rendering takes its element's place: a table's section, row\n * or cell, a list's item. Its member renders the part's root where the\n * element was, and the element stays the part's controller.\n */\n readonly structural?: true\n /** A public part's member, by its tag: the element it renders inside (`poly-table`). */\n readonly within?: string\n /** The slots the member renders only inside a portal, which stay hidden before the element is defined. */\n readonly overlays?: readonly string[]\n}\n\n/** A kebab-case prop name as its camel-case property: `aria-label` is `ariaLabel`. */\nexport type PropertyName<Name extends string> = Name extends `${infer Head}-${infer Tail}`\n ? `${Head}${Capitalize<PropertyName<Tail>>}`\n : Name\n\n/** The properties of a member's element: each prop named, by its property name, with its type. */\nexport type ElementProperties<Props, Names extends keyof Props & string> = {\n [Name in Names as PropertyName<Name>]: Props[Name]\n}\n\n/** A name in kebab case: `iconOnly` is `icon-only`, `QRCode` is `qr-code`. */\nexport const kebab = (name: string): string =>\n name\n .replace(/([a-z0-9])([A-Z])/g, '$1-$2')\n .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')\n .toLowerCase()\n\n/** A kebab-case name in camel case: `aria-label` is `ariaLabel`. */\nexport const camel = (name: string): string =>\n name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())\n\n/** The tag of a member or part, by its component's name: `TabsContent` is `poly-tabs-content`. */\nexport const tagOf = (component: string): string => `${PREFIX}${kebab(component)}`\n\n/** The attribute a prop reads from: its kebab name, and an `aria-*` or `data-*` name as it is. */\nexport const attributeOf = (prop: string): string =>\n /^(aria|data)-/.test(prop) ? prop : kebab(prop)\n\n/** The property a prop is set through: its camel name (`ariaLabel`, `iconOnly`). */\nexport const propertyOf = (prop: string): string => camel(prop)\n\n/** The event type an event prop dispatches: `onOpenChange` is `poly-open-change`. */\nexport const eventOf = (prop: string): string => `${PREFIX}${kebab(prop.slice(2))}`\n\n/** The slot attribute a node prop is written with: `secondaryAction` is `secondary-action`. */\nexport const slotOf = (prop: string): string => (prop === 'children' ? '' : kebab(prop))\n"],"mappings":";AAWA,IAAa,IAAS,SAoHT,KAAS,MACpB,EACG,QAAQ,sBAAsB,OAAO,CAAC,CACtC,QAAQ,wBAAwB,OAAO,CAAC,CACxC,YAAY,GAGJ,KAAS,MACpB,EAAK,QAAQ,cAAc,GAAG,MAAmB,EAAO,YAAY,CAAC,GAG1D,KAAS,MAA8B,GAAG,IAAS,EAAM,CAAS,KAGlE,KAAe,MAC1B,gBAAgB,KAAK,CAAI,IAAI,IAAO,EAAM,CAAI,GAGnC,KAAc,MAAyB,EAAM,CAAI,GAGjD,KAAW,MAAyB,GAAG,IAAS,EAAM,EAAK,MAAM,CAAC,CAAC,KAGnE,KAAU,MAA0B,MAAS,aAAa,KAAK,EAAM,CAAI"}