@vielzeug/codex 26.11.0 → 26.11.2

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 (8) hide show
  1. package/data/catalog.json +45 -44
  2. package/data/llms-full.txt +3 -3
  3. package/data/llms.txt +1 -1
  4. package/data/manifest.json +1 -1
  5. package/data/packages/refine.json +2 -2
  6. package/data/refine.json +345 -96
  7. package/data/search.json +3 -3
  8. package/package.json +2 -2
package/data/catalog.json CHANGED
@@ -35,7 +35,7 @@
35
35
  "rune"
36
36
  ],
37
37
  "slug": "archive",
38
- "version": "26.10.22"
38
+ "version": "26.11.1"
39
39
  },
40
40
  {
41
41
  "availableDocPages": [
@@ -108,7 +108,7 @@
108
108
  "coins"
109
109
  ],
110
110
  "slug": "arsenal",
111
- "version": "26.10.22"
111
+ "version": "26.11.1"
112
112
  },
113
113
  {
114
114
  "availableDocPages": [
@@ -160,7 +160,7 @@
160
160
  "refine"
161
161
  ],
162
162
  "slug": "assay",
163
- "version": "26.10.22"
163
+ "version": "26.11.1"
164
164
  },
165
165
  {
166
166
  "availableDocPages": [
@@ -199,7 +199,7 @@
199
199
  "vault"
200
200
  ],
201
201
  "slug": "beacon",
202
- "version": "26.10.22"
202
+ "version": "26.11.1"
203
203
  },
204
204
  {
205
205
  "availableDocPages": [
@@ -241,7 +241,7 @@
241
241
  "ward"
242
242
  ],
243
243
  "slug": "clockwork",
244
- "version": "26.10.22"
244
+ "version": "26.11.1"
245
245
  },
246
246
  {
247
247
  "availableDocPages": [
@@ -273,7 +273,7 @@
273
273
  "refine"
274
274
  ],
275
275
  "slug": "codex",
276
- "version": "26.10.22"
276
+ "version": "26.11.1"
277
277
  },
278
278
  {
279
279
  "availableDocPages": [
@@ -343,7 +343,7 @@
343
343
  "spell"
344
344
  ],
345
345
  "slug": "coins",
346
- "version": "26.10.22"
346
+ "version": "26.11.1"
347
347
  },
348
348
  {
349
349
  "availableDocPages": [
@@ -384,7 +384,7 @@
384
384
  "rune"
385
385
  ],
386
386
  "slug": "conduit",
387
- "version": "26.10.22"
387
+ "version": "26.11.1"
388
388
  },
389
389
  {
390
390
  "availableDocPages": [
@@ -426,7 +426,7 @@
426
426
  "postmaster"
427
427
  ],
428
428
  "slug": "courier",
429
- "version": "26.10.22"
429
+ "version": "26.11.1"
430
430
  },
431
431
  {
432
432
  "availableDocPages": [
@@ -472,7 +472,7 @@
472
472
  "refine"
473
473
  ],
474
474
  "slug": "dnd",
475
- "version": "26.10.22"
475
+ "version": "26.11.1"
476
476
  },
477
477
  {
478
478
  "availableDocPages": [
@@ -514,7 +514,7 @@
514
514
  "herald"
515
515
  ],
516
516
  "slug": "familiar",
517
- "version": "26.10.22"
517
+ "version": "26.11.1"
518
518
  },
519
519
  {
520
520
  "availableDocPages": [
@@ -581,7 +581,7 @@
581
581
  "courier"
582
582
  ],
583
583
  "slug": "flux",
584
- "version": "26.10.22"
584
+ "version": "26.11.1"
585
585
  },
586
586
  {
587
587
  "availableDocPages": [
@@ -621,7 +621,7 @@
621
621
  "ore"
622
622
  ],
623
623
  "slug": "focus",
624
- "version": "26.10.22"
624
+ "version": "26.11.1"
625
625
  },
626
626
  {
627
627
  "availableDocPages": [
@@ -662,7 +662,7 @@
662
662
  "assay"
663
663
  ],
664
664
  "slug": "forge",
665
- "version": "26.10.22"
665
+ "version": "26.11.1"
666
666
  },
667
667
  {
668
668
  "availableDocPages": [
@@ -700,7 +700,7 @@
700
700
  "keymap"
701
701
  ],
702
702
  "slug": "gesture",
703
- "version": "26.10.22"
703
+ "version": "26.11.1"
704
704
  },
705
705
  {
706
706
  "availableDocPages": [
@@ -744,7 +744,7 @@
744
744
  "familiar"
745
745
  ],
746
746
  "slug": "herald",
747
- "version": "26.10.22"
747
+ "version": "26.11.1"
748
748
  },
749
749
  {
750
750
  "availableDocPages": [
@@ -787,7 +787,7 @@
787
787
  "tempo"
788
788
  ],
789
789
  "slug": "illusionist",
790
- "version": "26.10.22"
790
+ "version": "26.11.1"
791
791
  },
792
792
  {
793
793
  "availableDocPages": [
@@ -832,7 +832,7 @@
832
832
  "ore"
833
833
  ],
834
834
  "slug": "keymap",
835
- "version": "26.10.22"
835
+ "version": "26.11.1"
836
836
  },
837
837
  {
838
838
  "availableDocPages": [
@@ -879,7 +879,7 @@
879
879
  "vault"
880
880
  ],
881
881
  "slug": "ledger",
882
- "version": "26.10.22"
882
+ "version": "26.11.1"
883
883
  },
884
884
  {
885
885
  "availableDocPages": [
@@ -925,7 +925,7 @@
925
925
  "courier"
926
926
  ],
927
927
  "slug": "lingua",
928
- "version": "26.10.22"
928
+ "version": "26.11.1"
929
929
  },
930
930
  {
931
931
  "availableDocPages": [
@@ -963,7 +963,7 @@
963
963
  "herald"
964
964
  ],
965
965
  "slug": "mesh",
966
- "version": "26.10.22"
966
+ "version": "26.11.1"
967
967
  },
968
968
  {
969
969
  "availableDocPages": [
@@ -1000,7 +1000,7 @@
1000
1000
  "ore"
1001
1001
  ],
1002
1002
  "slug": "necromancer",
1003
- "version": "26.10.22"
1003
+ "version": "26.11.1"
1004
1004
  },
1005
1005
  {
1006
1006
  "availableDocPages": [
@@ -1040,7 +1040,7 @@
1040
1040
  "prism"
1041
1041
  ],
1042
1042
  "slug": "orbit",
1043
- "version": "26.10.22"
1043
+ "version": "26.11.1"
1044
1044
  },
1045
1045
  {
1046
1046
  "availableDocPages": [
@@ -1105,7 +1105,7 @@
1105
1105
  "orbit"
1106
1106
  ],
1107
1107
  "slug": "ore",
1108
- "version": "26.10.22"
1108
+ "version": "26.11.1"
1109
1109
  },
1110
1110
  {
1111
1111
  "availableDocPages": [
@@ -1149,7 +1149,7 @@
1149
1149
  "ripple"
1150
1150
  ],
1151
1151
  "slug": "postmaster",
1152
- "version": "26.10.22"
1152
+ "version": "26.11.1"
1153
1153
  },
1154
1154
  {
1155
1155
  "availableDocPages": [
@@ -1190,7 +1190,7 @@
1190
1190
  "orbit"
1191
1191
  ],
1192
1192
  "slug": "prism",
1193
- "version": "26.10.22"
1193
+ "version": "26.11.1"
1194
1194
  },
1195
1195
  {
1196
1196
  "availableDocPages": [
@@ -1254,7 +1254,7 @@
1254
1254
  "clockwork"
1255
1255
  ],
1256
1256
  "slug": "pulse",
1257
- "version": "26.10.22"
1257
+ "version": "26.11.1"
1258
1258
  },
1259
1259
  {
1260
1260
  "availableDocPages": [
@@ -1298,6 +1298,7 @@
1298
1298
  "ore-datagrid",
1299
1299
  "ore-date-picker",
1300
1300
  "ore-dialog",
1301
+ "ore-dock",
1301
1302
  "ore-drawer",
1302
1303
  "ore-file-input",
1303
1304
  "ore-grid",
@@ -1376,7 +1377,7 @@
1376
1377
  "keymap"
1377
1378
  ],
1378
1379
  "slug": "refine",
1379
- "version": "26.10.22"
1380
+ "version": "26.11.1"
1380
1381
  },
1381
1382
  {
1382
1383
  "availableDocPages": [
@@ -1421,7 +1422,7 @@
1421
1422
  "ledger"
1422
1423
  ],
1423
1424
  "slug": "ripple",
1424
- "version": "26.10.22"
1425
+ "version": "26.11.1"
1425
1426
  },
1426
1427
  {
1427
1428
  "availableDocPages": [
@@ -1475,7 +1476,7 @@
1475
1476
  "familiar"
1476
1477
  ],
1477
1478
  "slug": "rune",
1478
- "version": "26.10.22"
1479
+ "version": "26.11.1"
1479
1480
  },
1480
1481
  {
1481
1482
  "availableDocPages": [
@@ -1516,7 +1517,7 @@
1516
1517
  "refine"
1517
1518
  ],
1518
1519
  "slug": "sandbox",
1519
- "version": "26.10.22"
1520
+ "version": "26.11.1"
1520
1521
  },
1521
1522
  {
1522
1523
  "availableDocPages": [
@@ -1567,7 +1568,7 @@
1567
1568
  "ripple"
1568
1569
  ],
1569
1570
  "slug": "scout",
1570
- "version": "26.10.22"
1571
+ "version": "26.11.1"
1571
1572
  },
1572
1573
  {
1573
1574
  "availableDocPages": [
@@ -1620,7 +1621,7 @@
1620
1621
  "refine"
1621
1622
  ],
1622
1623
  "slug": "scroll",
1623
- "version": "26.10.22"
1624
+ "version": "26.11.1"
1624
1625
  },
1625
1626
  {
1626
1627
  "availableDocPages": [
@@ -1667,7 +1668,7 @@
1667
1668
  "gesture"
1668
1669
  ],
1669
1670
  "slug": "sentinel",
1670
- "version": "26.10.22"
1671
+ "version": "26.11.1"
1671
1672
  },
1672
1673
  {
1673
1674
  "availableDocPages": [
@@ -1707,7 +1708,7 @@
1707
1708
  "refine"
1708
1709
  ],
1709
1710
  "slug": "sigil",
1710
- "version": "26.10.22"
1711
+ "version": "26.11.1"
1711
1712
  },
1712
1713
  {
1713
1714
  "availableDocPages": [
@@ -1752,7 +1753,7 @@
1752
1753
  "wayfinder"
1753
1754
  ],
1754
1755
  "slug": "sourcerer",
1755
- "version": "26.10.22"
1756
+ "version": "26.11.1"
1756
1757
  },
1757
1758
  {
1758
1759
  "availableDocPages": [
@@ -1811,7 +1812,7 @@
1811
1812
  "vault"
1812
1813
  ],
1813
1814
  "slug": "spell",
1814
- "version": "26.10.22"
1815
+ "version": "26.11.1"
1815
1816
  },
1816
1817
  {
1817
1818
  "availableDocPages": [
@@ -1852,7 +1853,7 @@
1852
1853
  "ripple"
1853
1854
  ],
1854
1855
  "slug": "tandem",
1855
- "version": "26.10.22"
1856
+ "version": "26.11.1"
1856
1857
  },
1857
1858
  {
1858
1859
  "availableDocPages": [
@@ -1896,7 +1897,7 @@
1896
1897
  "herald"
1897
1898
  ],
1898
1899
  "slug": "tavern",
1899
- "version": "26.10.22"
1900
+ "version": "26.11.1"
1900
1901
  },
1901
1902
  {
1902
1903
  "availableDocPages": [
@@ -1964,7 +1965,7 @@
1964
1965
  "vault"
1965
1966
  ],
1966
1967
  "slug": "tempo",
1967
- "version": "26.10.22"
1968
+ "version": "26.11.1"
1968
1969
  },
1969
1970
  {
1970
1971
  "availableDocPages": [
@@ -2015,7 +2016,7 @@
2015
2016
  "ripple"
2016
2017
  ],
2017
2018
  "slug": "vault",
2018
- "version": "26.10.22"
2019
+ "version": "26.11.1"
2019
2020
  },
2020
2021
  {
2021
2022
  "availableDocPages": [
@@ -2061,7 +2062,7 @@
2061
2062
  "refine"
2062
2063
  ],
2063
2064
  "slug": "ward",
2064
- "version": "26.10.22"
2065
+ "version": "26.11.1"
2065
2066
  },
2066
2067
  {
2067
2068
  "availableDocPages": [
@@ -2115,8 +2116,8 @@
2115
2116
  "herald"
2116
2117
  ],
2117
2118
  "slug": "wayfinder",
2118
- "version": "26.10.22"
2119
+ "version": "26.11.1"
2119
2120
  }
2120
2121
  ],
2121
- "version": "26.10.22"
2122
+ "version": "26.11.1"
2122
2123
  }
package/data/llms-full.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Vielzeug: Full Documentation
2
2
 
3
- > Complete documentation for 43 packages. Version: 26.10.22
3
+ > Complete documentation for 43 packages. Version: 26.11.1
4
4
 
5
5
  ---
6
6
 
@@ -21799,7 +21799,7 @@ Each entry below is a component with its own documentation page and registration
21799
21799
 
21800
21800
  **Inputs:** `ore-button`, `ore-calendar`, `ore-checkbox`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
21801
21801
 
21802
- **Layout:** `ore-box`, `ore-grid`, `ore-navbar`, `ore-separator`, `ore-sidebar`
21802
+ **Layout:** `ore-box`, `ore-dock`, `ore-grid`, `ore-navbar`, `ore-separator`, `ore-sidebar`
21803
21803
 
21804
21804
  **Navigation:** `ore-breadcrumb`, `ore-navigation-menu`, `ore-pagination`, `ore-stepper`, `ore-tabs`
21805
21805
 
@@ -21941,7 +21941,7 @@ import type { OreButtonProps } from '@vielzeug/refine/button';
21941
21941
  | Content | `accordion`, `avatar`, `card`, `carousel`, `chat-message`, `chat-panel`, `code-window`, `copy-command`, `icon`, `keyboard-key`, `list`, `marquee`, `qr-code`, `rank-list`, `speech-player`, `speed-reading`, `stats`, `table`, `text` |
21942
21942
  | Feedback | `alert`, `async`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `skeleton`, `toast`, `typing-indicator` |
21943
21943
  | Inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `qr-scanner`, `query-bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |
21944
- | Layout | `box`, `grid`, `navbar`, `separator`, `sidebar` |
21944
+ | Layout | `box`, `dock`, `grid`, `navbar`, `separator`, `sidebar` |
21945
21945
  | Navigation | `breadcrumb`, `navigation-menu`, `pagination`, `stepper`, `tabs` |
21946
21946
  | Overlay | `command-palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |
21947
21947
 
package/data/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Vielzeug
2
2
 
3
- > 43 focused TypeScript packages. Version: 26.10.22
3
+ > 43 focused TypeScript packages. Version: 26.11.1
4
4
 
5
5
  Install any package independently: `pnpm add @vielzeug/<name>`
6
6
 
package/data/manifest.json CHANGED
@@ -4,5 +4,5 @@
4
4
  "refine": "refine.json",
5
5
  "schemaVersion": 1,
6
6
  "search": "search.json",
7
- "version": "26.10.22"
7
+ "version": "26.11.1"
8
8
  }
package/data/packages/refine.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "apiSource": "/**\n * Refine components register through their explicit component entry points.\n *\n * Keeping the package root free of registration side effects makes dependency\n * ownership and bundle contents obvious to application code.\n */\n\nexport { RefineError } from './errors';\nexport type { IconAttributes, IconDefinition, IconElement } from './icons';\nexport { registerIcons } from './icons';\nexport { eventFieldChecked, eventFieldValue } from './inputs/shared/native-field-event';\nexport { getMotionMode, MOTION_MODES, type MotionMode, setMotionMode } from './motion';\nexport type { Reflow, ReflowOptions } from './reflow';\nexport { animateReflow } from './reflow';\n",
3
3
  "docs": {
4
- "index": "---\ntitle: 'Refine: Web component library'\ndescription: Accessible, themeable web components built with Ore for framework and vanilla DOM apps.\npackage: refine\ncategory: ui-components\nkeywords: [web-components, accessible, themeable, ui, components, design-system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n [\n ore-accordion,\n ore-accordion-item,\n ore-alert,\n ore-async,\n ore-avatar,\n ore-avatar-group,\n ore-badge,\n ore-box,\n ore-breadcrumb,\n ore-breadcrumb-item,\n ore-button,\n ore-button-group,\n ore-calendar,\n ore-card,\n ore-carousel,\n ore-carousel-slide,\n ore-chat-message,\n ore-checkbox,\n ore-checkbox-group,\n ore-chip,\n ore-code-window,\n ore-column,\n ore-combobox,\n ore-combobox-option,\n ore-command-palette,\n ore-command-palette-item,\n ore-cookie-banner,\n ore-copy-command,\n ore-counter,\n ore-datagrid,\n ore-date-picker,\n ore-dialog,\n ore-drawer,\n ore-file-input,\n ore-grid,\n ore-grid-item,\n ore-icon,\n ore-input,\n ore-keyboard-key,\n ore-keyboard-shortcut,\n ore-list,\n ore-list-item,\n ore-marquee,\n ore-menu,\n ore-menu-item,\n ore-menu-separator,\n ore-message-composer,\n ore-navbar,\n ore-navbar-item,\n ore-navigation-menu,\n ore-navigation-menu-item,\n ore-navigation-menu-panel,\n ore-number-input,\n ore-otp-input,\n ore-pagination,\n ore-password-strength,\n ore-popover,\n ore-progress,\n ore-qr-code,\n ore-qr-scanner,\n ore-query-bar,\n ore-radio,\n ore-radio-group,\n ore-rating,\n ore-select,\n ore-separator,\n ore-sidebar,\n ore-sidebar-group,\n ore-sidebar-item,\n ore-skeleton,\n ore-slider,\n ore-speech-player,\n ore-speed-reading,\n ore-spotlight,\n ore-stats,\n ore-step,\n ore-stepper,\n ore-switch,\n ore-tab-item,\n ore-tab-panel,\n ore-table,\n ore-tabs,\n ore-td,\n ore-text,\n ore-th,\n ore-tr,\n ore-textarea,\n ore-time-picker,\n ore-toast,\n ore-tooltip,\n ore-tour,\n ore-typing-indicator,\n ]\nenvironments: [browser]\n---\n\n<!-- markdownlint-disable MD025 MD033 MD060 -->\n\n<PackageHero package=\"refine\" />\n\n## Why Refine?\n\nEvery project needs UI primitives. Refine provides accessible web components that work natively anywhere HTML is rendered, no framework required.\n\n```html\n<!-- Before: roll your own button with ARIA -->\n<button class=\"btn btn-primary\" role=\"button\" aria-pressed=\"false\" tabindex=\"0\">\n <span class=\"btn-spinner\" aria-hidden=\"true\"></span>\n Save\n</button>\n\n<!-- After: Refine -->\n<ore-button variant=\"solid\" color=\"primary\" loading>Save</ore-button>\n```\n\n| Feature | Refine | Shoelace | Material Web |\n| ------------------ | ------------------------------------------- | ------------------------------------------ | ------------------------------------------ |\n| Bundle size | <PackageInfo package=\"refine\" type=\"size\" /> | ~145 kB | ~200 kB |\n| Built with | Ore | Lit | Lit |\n| Runtime dependencies | Vielzeug UI primitives; Lucide only for the opt-in full-library registrar | Lit + utilities | Lit + Material foundations |\n| Accessible | WCAG AA | WCAG AA | WCAG AA |\n| Framework agnostic | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> |\n\n<div class=\"decision-callout\">\n\n**Use Refine when** you want accessible web components that match the Vielzeug design system without a heavy framework dependency.\n\n**Consider Shoelace or Material Web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## Installation\n\n::: code-group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## Quick Start\n\n```ts\n// 1. Import global styles once\nimport '@vielzeug/refine/fouc.css'; // Hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // Tokens, animations, cascade layers\n\n// 2. Register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore-button variant=\"solid\" color=\"primary\">Save</ore-button>\n<ore-input label=\"Email\" type=\"email\" required></ore-input>\n<ore-card padding=\"lg\">\n <span slot=\"header\">Account</span>\n <p>Card content goes here.</p>\n</ore-card>\n```\n\n```ts\n```\n\n### CDN / Vanilla HTML\n\nUse the self-contained IIFE bundle to load Refine directly from a CDN in any HTML page: no build step required:\n\n```html\n<!-- 1. Styles -->\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<!-- 2. All components (IIFE: registers global Refine namespace) -->\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nFor bundler-based projects that still want a CDN URL, use the ESM bundle via an import map:\n\n```html\n<script type=\"importmap\">\n {\n \"imports\": {\n \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n }\n }\n</script>\n\n<script type=\"module\">\n import '@vielzeug/refine/button';\n import '@vielzeug/refine/input';\n</script>\n```\n\n### Package Entry Points\n\n| Import | Purpose |\n| ------------------------ | ----------------------------------------- |\n| `@vielzeug/refine/fouc.css` | FOUC suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | Global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | Optional browser-default reset (includes FOUC suppression) |\n\nComponent registration happens through side-effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### Components\n\nEach entry below is a component with its own documentation page and registration subpath. Sub-element tags (`ore-accordion-item`, `ore-tab-item`, `ore-avatar-group`, and the rest) are documented on their parent's page and registered with it.\n\n**Content:** `ore-accordion`, `ore-avatar`, `ore-card`, `ore-carousel`, `ore-chat-message`, `ore-chat-panel`, `ore-code-window`, `ore-copy-command`, `ore-icon`, `ore-keyboard-key`, `ore-list`, `ore-marquee`, `ore-qr-code`, `ore-rank-list`, `ore-speech-player`, `ore-speed-reading`, `ore-stats`, `ore-table`, `ore-text`\n\n**Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-cookie-banner`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`, `ore-typing-indicator`\n\n**Inputs:** `ore-button`, `ore-calendar`, `ore-checkbox`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`\n\n**Layout:** `ore-box`, `ore-grid`, `ore-navbar`, `ore-separator`, `ore-sidebar`\n\n**Navigation:** `ore-breadcrumb`, `ore-navigation-menu`, `ore-pagination`, `ore-stepper`, `ore-tabs`\n\n**Overlay:** `ore-command-palette`, `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-spotlight`, `ore-tooltip`, `ore-tour`\n\n## Component portfolio\n\nRefine keeps one public package and classifies components by composition level rather than stability. All listed components remain supported and tested.\n\n- **Foundations**: buttons, inputs, selection controls, accordions, dialogs, menus, tooltips, layout primitives, and feedback indicators. Start here when building an application-specific interface.\n- **Composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. These package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n- **Presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. Use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nClassification guides discovery and bundle selection. It is not a reason to remove working components or move them into unstable packages; per-component subpath imports remain the tree-shaking boundary.\n\n## Features\n\n<div class=\"features-grid\">\n\n- **Accessible**: keyboard navigation, ARIA wiring, and focus management across interactive components\n- **Themeable**: global tokens plus component-level CSS custom properties\n- **Motion-safe**: every animation routes through duration tokens and honors Motion Mode (`setMotionMode`) with a reduced-motion floor\n- **Framework agnostic**: works anywhere HTML can be rendered\n- **Tree-shakeable**: import only the component entry points you register\n- **Comprehensive surface**: inputs, content, navigation, feedback, layout, and overlay primitives\n- **Native form integration**: form-associated controls submit values, validate supported required constraints, and reset with their form\n- **Typed framework declarations**: DOM, React, and Vue tags derive from the component property contracts\n\n</div>\n\n### Prerequisites\n\n- Browser runtime with Custom Elements support.\n- Import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n- For SSR, render placeholders server-side and hydrate components only on the client.\n\n## Documentation\n\n<div class=\"doc-links\">\n\n- [Usage Guide](./usage.md)\n- [API Reference](./api.md)\n- [Animation & Motion](./animation.md)\n- [Migration Guide](./migration.md)\n\n</div>\n\n## See Also\n\n<div class=\"see-also\">\n\n- [Ore](/ore/): Web component runtime that powers Refine\n- [Orbit](/orbit/): Floating UI positioning used in Refine's overlays\n- [Forge](/forge/): Form state management for use with Refine inputs\n- [Keymap](/keymap/): Keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<!-- markdownlint-enable MD025 MD033 MD060 -->\n",
5
- "api": "---\ntitle: 'Refine: API Reference'\ndescription: Published component, stylesheet, framework type, and error entry points for @vielzeug/refine.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `@vielzeug/refine/<component>` | Register one custom element and export its public types | Sync | Importing a type alone does not register the element |\n| `@vielzeug/refine/tokens.css` | Load required theme tokens, animations, and cascade layers | CSS | Import once before components render |\n| `@vielzeug/refine/fouc.css` | Hide unregistered `ore-*` elements until upgrade | CSS | Load before first paint |\n| `@vielzeug/refine/styles/preflight.css` | Apply the optional browser reset | CSS | The reset affects global elements |\n| `@vielzeug/refine/frameworks/elements` | Register typed DOM tag mappings | Types only | Import for side effects in TypeScript |\n| `@vielzeug/refine/frameworks/react` | Register typed React JSX elements | Types only | Does not provide runtime wrappers |\n| `@vielzeug/refine/frameworks/vue` | Register typed Vue global components | Types only | Does not install a Vue plugin |\n| `@vielzeug/refine/theme` | `createThemeController()`: light/dark/system document theme | Sync | Does not persist the preference or set an accent color |\n| `eventFieldValue()` / `eventFieldChecked()` | Read a form control's value/checked from `event.currentTarget` | Sync | Exported from the package root; guards non-field targets |\n| `animateReflow()` | Token-driven FLIP reflow for keyed lists | Async (next frame) | Exported from the package root; elements need stable keys or it correctly does nothing |\n| `setMotionMode()` / `getMotionMode()` | Read/write the `data-motion` attribute on `<html>` | Sync | Exported from the package root; an unknown mode throws `RangeError` |\n| `RefineError` | Base class for package-defined public errors | Sync | Component configuration warnings do not throw this error |\n\n## Package Entry Point\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/refine` | Export `registerIcons`, icon definition types, `RefineError`, `animateReflow`, the motion-mode functions, and the field readers without registering components |\n| `@vielzeug/refine/<component>` | Register one component and export its tag constant, props, events, and related types |\n| `@vielzeug/refine/theme` | `createThemeController()` and its theme types |\n| `@vielzeug/refine/tokens.css` | Required global design contract |\n| `@vielzeug/refine/fouc.css` | Optional pre-upgrade visibility rule |\n| `@vielzeug/refine/styles/*` | Focused theme, animation, layer, and preflight stylesheets |\n| `@vielzeug/refine/frameworks/*` | TypeScript augmentations for DOM, React, and Vue |\n\n## Icon Registration and Adapters\n\n`registerIcons(icons: Readonly<Record<string, IconDefinition>>): void` is available from `@vielzeug/refine/icons`, `@vielzeug/refine`, and `@vielzeug/refine/icon`. The common `icons` entry and root remain free of component registration side effects.\n\n`IconDefinition`, `IconElement`, and `IconAttributes` are exported from all three entries. Shared definition and registration modules live in `src/icons/`, alongside adapters and internal SVG helpers/defaults. Definitions contain a numeric `viewBox` tuple, optional presentation attributes, and recursive SVG children; they do not require a provider identity. Invalid registrations throw the root-exported `RefineError` atomically.\n\n| Entry | Export | Purpose |\n| --- | --- | --- |\n| `@vielzeug/refine/icons` | `registerIcons`, `IconDefinition`, `IconElement`, `IconAttributes` | Common library-neutral registration and definition API |\n| `@vielzeug/refine/icons/lucide` | `lucideIcons`, `LucideIconData` | Pure adapter for selected structural Lucide SVG data |\n| `@vielzeug/refine/icons/lucide/all` | Side-effect registration | Explicitly register the full installed Lucide library |\n| `@vielzeug/refine/icons/heroicons` | `heroiconsIcons`, `IconifyIcon` | Convert a caller-named map of individual Heroicons Iconify data |\n| `@vielzeug/refine/icons/tabler` | `tablerIcons`, `IconifyIcon` | Convert a caller-named map of individual Tabler Iconify data |\n| `@vielzeug/refine/icons/mdi` | `mdiIcons`, `IconifyIcon` | Convert a caller-named map of individual MDI Iconify data |\n| `@vielzeug/refine/icons/iconify` | `iconifyIcon`, `iconifyIcons` | Convert individual Iconify data or selected/complete collections |\n| `@vielzeug/refine/icons/iconify` | `IconifyIcon`, `IconifyAlias`, `IconifyCollection`, `IconifyTransform` | Structural data types; no Iconify dependency required |\n\nLucide is an optional peer, not a mandatory dependency. Only `icons/lucide/all` requires an installed `lucide` package; consumers selecting that entry declare it themselves. The structural `icons/lucide` adapter accepts supplied data without importing Lucide.\n\nThe standalone IIFE exposes `registerIcons`, `lucideIcons`, `heroiconsIcons`, `tablerIcons`, `mdiIcons`, `iconifyIcon`, and `iconifyIcons` under `Refine.components.content`. Neither the IIFE nor component entries import Lucide. Iconify conversion drops provider `class` metadata, validates finite numeric offsets and positive finite dimensions before transforms, and retains the strict SVG allowlist. See the [icon reference](./components/icon.md) for presentation overrides, local SVG ID rewriting, supported families, and licenses.\n\nThe three family adapters share this signature:\n\n```ts\nheroiconsIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\ntablerIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\nmdiIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\n```\n\nEach accepts individual Iconify SVG data, preserves input keys without adding a namespace, and returns definitions without registering them. They require `DOMParser`, preserve each icon's geometry/presentation/transforms, and throw `RefineError` for invalid Iconify data. They do not accept React/Vue components, collection JSON, or raw SVG path strings. Use `iconifyIcons(collection, names?)` for collections and alias resolution.\n\n## Styles\n\n```ts\nimport '@vielzeug/refine/fouc.css';\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n`tokens.css` is required. It defines tokens, animations, and cascade-layer order without resetting global elements. `preflight.css` is optional and includes FOUC suppression.\n\n| Import path | Purpose |\n| --- | --- |\n| `@vielzeug/refine/fouc.css` | FOUC suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | Tokens, animation helpers, and cascade layers |\n| `@vielzeug/refine/styles/theme.css` | Theme token declarations |\n| `@vielzeug/refine/styles/animation.css` | Animation helpers |\n| `@vielzeug/refine/styles/layers.css` | Cascade layer declarations |\n| `@vielzeug/refine/styles/preflight.css` | Optional browser reset and FOUC suppression |\n\n## Components\n\nEach component uses one registration and type entry point:\n\n```ts\nimport '@vielzeug/refine/button';\nimport type { OreButtonProps } from '@vielzeug/refine/button';\n```\n\n| Area | Components |\n| --- | --- |\n| Content | `accordion`, `avatar`, `card`, `carousel`, `chat-message`, `chat-panel`, `code-window`, `copy-command`, `icon`, `keyboard-key`, `list`, `marquee`, `qr-code`, `rank-list`, `speech-player`, `speed-reading`, `stats`, `table`, `text` |\n| Feedback | `alert`, `async`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `skeleton`, `toast`, `typing-indicator` |\n| Inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `qr-scanner`, `query-bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |\n| Layout | `box`, `grid`, `navbar`, `separator`, `sidebar` |\n| Navigation | `breadcrumb`, `navigation-menu`, `pagination`, `stepper`, `tabs` |\n| Overlay | `command-palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |\n\nEach row lists the entry points that own a documentation page. Sub-element entries (`accordion-item`, `tab-item`, `avatar-group`, `list-item`, `step`, and the rest) are documented on their parent's page and share its category.\n\nEach component page lists its attributes, JavaScript properties, events, slots, parts, and CSS custom properties.\n\nThe [`query-bar`](./components/query-bar.md) entry also exports `QueryState`, `QueryTokenDef`, `QueryQuickFilter`, `QueryBarLabels`, and pure grammar helpers. Vocabulary entries default to single selection; `selection: 'multiple'` allows distinct values for the same key. `anyLabel` customizes the unrestricted single-selection choice, such as “Default order” for sorting. Options accept an optional `icon` (registered `ore-icon` name), displayed beside their labels in the drawer. `tokenValues(state, key)` reads all values, `removeToken(state, token)` removes an exact pair, and `clearTokens(state, key)` clears a group. Its unified field contains applied filters, with a compact secondary row for filter entry, quick toggles, and a `toolbar-end` slot for application content such as a result count. Drawer selection uses the same state and vocabulary as typed suggestions. Pending edits block incidental backdrop/swipe dismissal; explicit Cancel, Close, and Escape discard them. Search-hidden selections remain visible in a summary.\n\n## Framework Types\n\n```ts\nimport type {} from '@vielzeug/refine/frameworks/elements';\nimport type {} from '@vielzeug/refine/frameworks/react';\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\nThe declarations cover every supported tag and derive component properties from Refine's authoritative `HTMLElementTagNameMap`. They provide types only; component registration still uses component subpaths.\n\n## Events and Form Controls\n\nForm controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. Read the property from `event.currentTarget`.\n\nFinite-choice properties use Ore's `prop.oneOf()` parsing: values outside a component's documented options resolve to\nthe declared default, or `undefined` when no default is declared.\n\nForm-associated controls participate in native form submission, validity checks, and reset. A named control's value\nis available through `new FormData(form)`, and supported `required` constraints affect `form.checkValidity()`,\n`form.reportValidity()`, and submit blocking. The `error` property renders and announces feedback; it does not by\nitself set native constraint validity.\n\nStateful overlays expose controlled `open`, optional `default-open`, and an `open-change` custom event with `{ open, reason }` detail. Component pages define additional detail fields and reasons.\n\n## Utilities\n\n### `createThemeController(options?)`\n\n```ts\nimport { createThemeController } from '@vielzeug/refine/theme';\n\nconst theme = createThemeController(); // starts in 'system' mode\ntheme.setPreference('dark');\ntheme.dispose();\n```\n\nOwns the light/dark/system theme for the document: a reactive `preference` signal, the effective `resolved` mode (`'dark' | 'light'` after resolving `system` against the OS), and the DOM application `styles/theme.css` expects: the `.dark` class plus the `color-scheme` property on the root element, so every `light-dark()` token resolves to the right branch. While in `system` mode the controller tracks the OS `prefers-color-scheme` via sentinel's `createMediaQuery`.\n\nThe controller does **not** persist the preference or expose an accent color: those are consumer concerns (wire `watch(controller.preference, save)` for persistence; set `--color-primary-hue` yourself). Options: `initial` (starting preference, default `'system'`), `root` (element carrying the classes, default `document.documentElement`), `target` (window whose `matchMedia` backs `system`). The handle is disposable: `dispose()`, `disposed`, `disposalSignal`, `[Symbol.dispose]`.\n\n### `eventFieldValue(event)` / `eventFieldChecked(event)`\n\n```ts\nimport { eventFieldChecked, eventFieldValue } from '@vielzeug/refine';\n\ninput.addEventListener('input', (event) => {\n const value = eventFieldValue(event); // string | undefined: never a blind cast\n});\n```\n\nGuarded readers for the standard `input`/`change` event pattern above: they read `value`/`checked` from `event.currentTarget` only when the target actually carries it, so a handler wired to the wrong element yields `undefined`/`false` instead of a crash or a lie. Exported from the package root, which registers no components.\n\n---\n\n### `animateReflow(host, signal, options)`\n\n```ts\nimport { animateReflow } from '@vielzeug/refine';\n\nconst reflow = animateReflow(list, abortController.signal, {\n elements: () => [...list.querySelectorAll('li')],\n getKey: (item) => item.dataset.id,\n});\nreflow.run(() => renderItems(nextItems));\n```\n\nToken-driven FLIP reflow for keyed lists: captures the current layout, runs `mutate`, then animates the tracked elements into their new positions on the next frame. The same helper the DataGrid, command palette, and toast stack use.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `host` | `HTMLElement` | Element whose computed style carries the timing tokens |\n| `signal` | `AbortSignal` | Aborting cancels in-flight animations |\n| `options.elements` | `() => HTMLElement[]` | Tracked elements, read live on both sides of the mutation |\n| `options.getKey` | `(el) => string \\| undefined` | Stable identity per element; all-or-nothing |\n| `options.durationToken` | `string?` | Duration token, default `'--duration-200'` |\n| `options.easingToken` | `string?` | Easing token, default `'--ease-move'` |\n| `options.stagger` | `number?` | Per-element delay in ms, default `0` |\n\n**Returns** a `Reflow` handle with one method: `run(mutate)` (sync; the animation is fire-and-forget). Timing is read from the tokens at animation time, so Motion Mode reduction skips the reflow instead of playing it instantly. Every path that cannot animate (no elements, missing keys, zeroed tokens, aborted signal, no Web Animations API) still runs `mutate` exactly once and never throws. See [Animation & Motion → List Reflow](./animation#list-reflow-animatereflow) for behavior details.\n\n---\n\n### `setMotionMode(mode)` / `getMotionMode()`\n\n```ts\nimport { getMotionMode, setMotionMode } from '@vielzeug/refine';\n\nsetMotionMode('reduced'); // returns the applied mode\n```\n\nRead/write the `data-motion` attribute on `<html>` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). An unknown mode throws `RangeError`. The attribute drives the token layer: see [Animation & Motion → Motion Mode](./animation#motion-mode).\n\n## Types\n\nComponent props follow the `Ore<Component>Props` naming pattern. Event maps follow `Ore<Component>Events`. Import both from the component subpath that owns them.\n\n`RefineElementMap`, `RefineReactIntrinsicElements`, and `RefineVueGlobalComponents` are exported from their respective `frameworks/*` type entry points.\n\nThe package root also exports `Reflow` (the `run()` handle), `ReflowOptions` (its options object), and `MotionMode` (`'full' | 'reduced' | 'system'`).\n\n## Errors\n\n### `RefineError`\n\n```ts\nclass RefineError extends Error {\n constructor(message: string, opts?: ErrorOptions);\n}\n```\n\nBase class for public Refine errors. It preserves `cause` through `ErrorOptions`.\n",
4
+ "index": "---\ntitle: 'Refine: Web component library'\ndescription: Accessible, themeable web components built with Ore for framework and vanilla DOM apps.\npackage: refine\ncategory: ui-components\nkeywords: [web-components, accessible, themeable, ui, components, design-system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n [\n ore-accordion,\n ore-accordion-item,\n ore-alert,\n ore-async,\n ore-avatar,\n ore-avatar-group,\n ore-badge,\n ore-box,\n ore-breadcrumb,\n ore-breadcrumb-item,\n ore-button,\n ore-button-group,\n ore-calendar,\n ore-card,\n ore-carousel,\n ore-carousel-slide,\n ore-chat-message,\n ore-checkbox,\n ore-checkbox-group,\n ore-chip,\n ore-code-window,\n ore-column,\n ore-combobox,\n ore-combobox-option,\n ore-command-palette,\n ore-command-palette-item,\n ore-cookie-banner,\n ore-copy-command,\n ore-counter,\n ore-datagrid,\n ore-date-picker,\n ore-dialog,\n ore-dock,\n ore-drawer,\n ore-file-input,\n ore-grid,\n ore-grid-item,\n ore-icon,\n ore-input,\n ore-keyboard-key,\n ore-keyboard-shortcut,\n ore-list,\n ore-list-item,\n ore-marquee,\n ore-menu,\n ore-menu-item,\n ore-menu-separator,\n ore-message-composer,\n ore-navbar,\n ore-navbar-item,\n ore-navigation-menu,\n ore-navigation-menu-item,\n ore-navigation-menu-panel,\n ore-number-input,\n ore-otp-input,\n ore-pagination,\n ore-password-strength,\n ore-popover,\n ore-progress,\n ore-qr-code,\n ore-qr-scanner,\n ore-query-bar,\n ore-radio,\n ore-radio-group,\n ore-rating,\n ore-select,\n ore-separator,\n ore-sidebar,\n ore-sidebar-group,\n ore-sidebar-item,\n ore-skeleton,\n ore-slider,\n ore-speech-player,\n ore-speed-reading,\n ore-spotlight,\n ore-stats,\n ore-step,\n ore-stepper,\n ore-switch,\n ore-tab-item,\n ore-tab-panel,\n ore-table,\n ore-tabs,\n ore-td,\n ore-text,\n ore-th,\n ore-tr,\n ore-textarea,\n ore-time-picker,\n ore-toast,\n ore-tooltip,\n ore-tour,\n ore-typing-indicator,\n ]\nenvironments: [browser]\n---\n\n<!-- markdownlint-disable MD025 MD033 MD060 -->\n\n<PackageHero package=\"refine\" />\n\n## Why Refine?\n\nEvery project needs UI primitives. Refine provides accessible web components that work natively anywhere HTML is rendered, no framework required.\n\n```html\n<!-- Before: roll your own button with ARIA -->\n<button class=\"btn btn-primary\" role=\"button\" aria-pressed=\"false\" tabindex=\"0\">\n <span class=\"btn-spinner\" aria-hidden=\"true\"></span>\n Save\n</button>\n\n<!-- After: Refine -->\n<ore-button variant=\"solid\" color=\"primary\" loading>Save</ore-button>\n```\n\n| Feature | Refine | Shoelace | Material Web |\n| ------------------ | ------------------------------------------- | ------------------------------------------ | ------------------------------------------ |\n| Bundle size | <PackageInfo package=\"refine\" type=\"size\" /> | ~145 kB | ~200 kB |\n| Built with | Ore | Lit | Lit |\n| Runtime dependencies | Vielzeug UI primitives; Lucide only for the opt-in full-library registrar | Lit + utilities | Lit + Material foundations |\n| Accessible | WCAG AA | WCAG AA | WCAG AA |\n| Framework agnostic | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> |\n\n<div class=\"decision-callout\">\n\n**Use Refine when** you want accessible web components that match the Vielzeug design system without a heavy framework dependency.\n\n**Consider Shoelace or Material Web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## Installation\n\n::: code-group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## Quick Start\n\n```ts\n// 1. Import global styles once\nimport '@vielzeug/refine/fouc.css'; // Hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // Tokens, animations, cascade layers\n\n// 2. Register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore-button variant=\"solid\" color=\"primary\">Save</ore-button>\n<ore-input label=\"Email\" type=\"email\" required></ore-input>\n<ore-card padding=\"lg\">\n <span slot=\"header\">Account</span>\n <p>Card content goes here.</p>\n</ore-card>\n```\n\n```ts\n```\n\n### CDN / Vanilla HTML\n\nUse the self-contained IIFE bundle to load Refine directly from a CDN in any HTML page: no build step required:\n\n```html\n<!-- 1. Styles -->\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<!-- 2. All components (IIFE: registers global Refine namespace) -->\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nFor bundler-based projects that still want a CDN URL, use the ESM bundle via an import map:\n\n```html\n<script type=\"importmap\">\n {\n \"imports\": {\n \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n }\n }\n</script>\n\n<script type=\"module\">\n import '@vielzeug/refine/button';\n import '@vielzeug/refine/input';\n</script>\n```\n\n### Package Entry Points\n\n| Import | Purpose |\n| ------------------------ | ----------------------------------------- |\n| `@vielzeug/refine/fouc.css` | FOUC suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | Global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | Optional browser-default reset (includes FOUC suppression) |\n\nComponent registration happens through side-effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### Components\n\nEach entry below is a component with its own documentation page and registration subpath. Sub-element tags (`ore-accordion-item`, `ore-tab-item`, `ore-avatar-group`, and the rest) are documented on their parent's page and registered with it.\n\n**Content:** `ore-accordion`, `ore-avatar`, `ore-card`, `ore-carousel`, `ore-chat-message`, `ore-chat-panel`, `ore-code-window`, `ore-copy-command`, `ore-icon`, `ore-keyboard-key`, `ore-list`, `ore-marquee`, `ore-qr-code`, `ore-rank-list`, `ore-speech-player`, `ore-speed-reading`, `ore-stats`, `ore-table`, `ore-text`\n\n**Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-cookie-banner`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`, `ore-typing-indicator`\n\n**Inputs:** `ore-button`, `ore-calendar`, `ore-checkbox`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`\n\n**Layout:** `ore-box`, `ore-dock`, `ore-grid`, `ore-navbar`, `ore-separator`, `ore-sidebar`\n\n**Navigation:** `ore-breadcrumb`, `ore-navigation-menu`, `ore-pagination`, `ore-stepper`, `ore-tabs`\n\n**Overlay:** `ore-command-palette`, `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-spotlight`, `ore-tooltip`, `ore-tour`\n\n## Component portfolio\n\nRefine keeps one public package and classifies components by composition level rather than stability. All listed components remain supported and tested.\n\n- **Foundations**: buttons, inputs, selection controls, accordions, dialogs, menus, tooltips, layout primitives, and feedback indicators. Start here when building an application-specific interface.\n- **Composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. These package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n- **Presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. Use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nClassification guides discovery and bundle selection. It is not a reason to remove working components or move them into unstable packages; per-component subpath imports remain the tree-shaking boundary.\n\n## Features\n\n<div class=\"features-grid\">\n\n- **Accessible**: keyboard navigation, ARIA wiring, and focus management across interactive components\n- **Themeable**: global tokens plus component-level CSS custom properties\n- **Motion-safe**: every animation routes through duration tokens and honors Motion Mode (`setMotionMode`) with a reduced-motion floor\n- **Framework agnostic**: works anywhere HTML can be rendered\n- **Tree-shakeable**: import only the component entry points you register\n- **Comprehensive surface**: inputs, content, navigation, feedback, layout, and overlay primitives\n- **Native form integration**: form-associated controls submit values, validate supported required constraints, and reset with their form\n- **Typed framework declarations**: DOM, React, and Vue tags derive from the component property contracts\n\n</div>\n\n### Prerequisites\n\n- Browser runtime with Custom Elements support.\n- Import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n- For SSR, render placeholders server-side and hydrate components only on the client.\n\n## Documentation\n\n<div class=\"doc-links\">\n\n- [Usage Guide](./usage.md)\n- [API Reference](./api.md)\n- [Animation & Motion](./animation.md)\n- [Migration Guide](./migration.md)\n\n</div>\n\n## See Also\n\n<div class=\"see-also\">\n\n- [Ore](/ore/): Web component runtime that powers Refine\n- [Orbit](/orbit/): Floating UI positioning used in Refine's overlays\n- [Forge](/forge/): Form state management for use with Refine inputs\n- [Keymap](/keymap/): Keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<!-- markdownlint-enable MD025 MD033 MD060 -->\n",
5
+ "api": "---\ntitle: 'Refine: API Reference'\ndescription: Published component, stylesheet, framework type, and error entry points for @vielzeug/refine.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `@vielzeug/refine/<component>` | Register one custom element and export its public types | Sync | Importing a type alone does not register the element |\n| `@vielzeug/refine/tokens.css` | Load required theme tokens, animations, and cascade layers | CSS | Import once before components render |\n| `@vielzeug/refine/fouc.css` | Hide unregistered `ore-*` elements until upgrade | CSS | Load before first paint |\n| `@vielzeug/refine/styles/preflight.css` | Apply the optional browser reset | CSS | The reset affects global elements |\n| `@vielzeug/refine/frameworks/elements` | Register typed DOM tag mappings | Types only | Import for side effects in TypeScript |\n| `@vielzeug/refine/frameworks/react` | Register typed React JSX elements | Types only | Does not provide runtime wrappers |\n| `@vielzeug/refine/frameworks/vue` | Register typed Vue global components | Types only | Does not install a Vue plugin |\n| `@vielzeug/refine/theme` | `createThemeController()`: light/dark/system document theme | Sync | Does not persist the preference or set an accent color |\n| `eventFieldValue()` / `eventFieldChecked()` | Read a form control's value/checked from `event.currentTarget` | Sync | Exported from the package root; guards non-field targets |\n| `animateReflow()` | Token-driven FLIP reflow for keyed lists | Async (next frame) | Exported from the package root; elements need stable keys or it correctly does nothing |\n| `setMotionMode()` / `getMotionMode()` | Read/write the `data-motion` attribute on `<html>` | Sync | Exported from the package root; an unknown mode throws `RangeError` |\n| `RefineError` | Base class for package-defined public errors | Sync | Component configuration warnings do not throw this error |\n\n## Package Entry Point\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/refine` | Export `registerIcons`, icon definition types, `RefineError`, `animateReflow`, the motion-mode functions, and the field readers without registering components |\n| `@vielzeug/refine/<component>` | Register one component and export its tag constant, props, events, and related types |\n| `@vielzeug/refine/theme` | `createThemeController()` and its theme types |\n| `@vielzeug/refine/tokens.css` | Required global design contract |\n| `@vielzeug/refine/fouc.css` | Optional pre-upgrade visibility rule |\n| `@vielzeug/refine/styles/*` | Focused theme, animation, layer, and preflight stylesheets |\n| `@vielzeug/refine/frameworks/*` | TypeScript augmentations for DOM, React, and Vue |\n\n## Icon Registration and Adapters\n\n`registerIcons(icons: Readonly<Record<string, IconDefinition>>): void` is available from `@vielzeug/refine/icons`, `@vielzeug/refine`, and `@vielzeug/refine/icon`. The common `icons` entry and root remain free of component registration side effects.\n\n`IconDefinition`, `IconElement`, and `IconAttributes` are exported from all three entries. Shared definition and registration modules live in `src/icons/`, alongside adapters and internal SVG helpers/defaults. Definitions contain a numeric `viewBox` tuple, optional presentation attributes, and recursive SVG children; they do not require a provider identity. Invalid registrations throw the root-exported `RefineError` atomically.\n\n| Entry | Export | Purpose |\n| --- | --- | --- |\n| `@vielzeug/refine/icons` | `registerIcons`, `IconDefinition`, `IconElement`, `IconAttributes` | Common library-neutral registration and definition API |\n| `@vielzeug/refine/icons/lucide` | `lucideIcons`, `LucideIconData` | Pure adapter for selected structural Lucide SVG data |\n| `@vielzeug/refine/icons/lucide/all` | Side-effect registration | Explicitly register the full installed Lucide library |\n| `@vielzeug/refine/icons/heroicons` | `heroiconsIcons`, `IconifyIcon` | Convert a caller-named map of individual Heroicons Iconify data |\n| `@vielzeug/refine/icons/tabler` | `tablerIcons`, `IconifyIcon` | Convert a caller-named map of individual Tabler Iconify data |\n| `@vielzeug/refine/icons/mdi` | `mdiIcons`, `IconifyIcon` | Convert a caller-named map of individual MDI Iconify data |\n| `@vielzeug/refine/icons/iconify` | `iconifyIcon`, `iconifyIcons` | Convert individual Iconify data or selected/complete collections |\n| `@vielzeug/refine/icons/iconify` | `IconifyIcon`, `IconifyAlias`, `IconifyCollection`, `IconifyTransform` | Structural data types; no Iconify dependency required |\n\nLucide is an optional peer, not a mandatory dependency. Only `icons/lucide/all` requires an installed `lucide` package; consumers selecting that entry declare it themselves. The structural `icons/lucide` adapter accepts supplied data without importing Lucide.\n\nThe standalone IIFE exposes `registerIcons`, `lucideIcons`, `heroiconsIcons`, `tablerIcons`, `mdiIcons`, `iconifyIcon`, and `iconifyIcons` under `Refine.components.content`. Neither the IIFE nor component entries import Lucide. Iconify conversion drops provider `class` metadata, validates finite numeric offsets and positive finite dimensions before transforms, and retains the strict SVG allowlist. See the [icon reference](./components/icon.md) for presentation overrides, local SVG ID rewriting, supported families, and licenses.\n\nThe three family adapters share this signature:\n\n```ts\nheroiconsIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\ntablerIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\nmdiIcons(icons: Readonly<Record<string, IconifyIcon>>): Record<string, IconDefinition>;\n```\n\nEach accepts individual Iconify SVG data, preserves input keys without adding a namespace, and returns definitions without registering them. They require `DOMParser`, preserve each icon's geometry/presentation/transforms, and throw `RefineError` for invalid Iconify data. They do not accept React/Vue components, collection JSON, or raw SVG path strings. Use `iconifyIcons(collection, names?)` for collections and alias resolution.\n\n## Styles\n\n```ts\nimport '@vielzeug/refine/fouc.css';\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n`tokens.css` is required. It defines tokens, animations, and cascade-layer order without resetting global elements. `preflight.css` is optional and includes FOUC suppression.\n\n| Import path | Purpose |\n| --- | --- |\n| `@vielzeug/refine/fouc.css` | FOUC suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | Tokens, animation helpers, and cascade layers |\n| `@vielzeug/refine/styles/theme.css` | Theme token declarations |\n| `@vielzeug/refine/styles/animation.css` | Animation helpers |\n| `@vielzeug/refine/styles/layers.css` | Cascade layer declarations |\n| `@vielzeug/refine/styles/preflight.css` | Optional browser reset and FOUC suppression |\n\n## Components\n\nEach component uses one registration and type entry point:\n\n```ts\nimport '@vielzeug/refine/button';\nimport type { OreButtonProps } from '@vielzeug/refine/button';\n```\n\n| Area | Components |\n| --- | --- |\n| Content | `accordion`, `avatar`, `card`, `carousel`, `chat-message`, `chat-panel`, `code-window`, `copy-command`, `icon`, `keyboard-key`, `list`, `marquee`, `qr-code`, `rank-list`, `speech-player`, `speed-reading`, `stats`, `table`, `text` |\n| Feedback | `alert`, `async`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `skeleton`, `toast`, `typing-indicator` |\n| Inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `qr-scanner`, `query-bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |\n| Layout | `box`, `dock`, `grid`, `navbar`, `separator`, `sidebar` |\n| Navigation | `breadcrumb`, `navigation-menu`, `pagination`, `stepper`, `tabs` |\n| Overlay | `command-palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |\n\nEach row lists the entry points that own a documentation page. Sub-element entries (`accordion-item`, `tab-item`, `avatar-group`, `list-item`, `step`, and the rest) are documented on their parent's page and share its category.\n\nEach component page lists its attributes, JavaScript properties, events, slots, parts, and CSS custom properties.\n\nThe [`query-bar`](./components/query-bar.md) entry also exports `QueryState`, `QueryTokenDef`, `QueryQuickFilter`, `QueryBarLabels`, and pure grammar helpers. Vocabulary entries default to single selection; `selection: 'multiple'` allows distinct values for the same key. `anyLabel` customizes the unrestricted single-selection choice, such as “Default order” for sorting. Options accept an optional `icon` (registered `ore-icon` name), displayed beside their labels in the drawer. `tokenValues(state, key)` reads all values, `removeToken(state, token)` removes an exact pair, and `clearTokens(state, key)` clears a group. Its unified field contains applied filters, with a compact secondary row for filter entry, quick toggles, and a `toolbar-end` slot for application content such as a result count. Drawer selection uses the same state and vocabulary as typed suggestions. Pending edits block incidental backdrop/swipe dismissal; explicit Cancel, Close, and Escape discard them. Search-hidden selections remain visible in a summary.\n\n## Framework Types\n\n```ts\nimport type {} from '@vielzeug/refine/frameworks/elements';\nimport type {} from '@vielzeug/refine/frameworks/react';\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\nThe declarations cover every supported tag and derive component properties from Refine's authoritative `HTMLElementTagNameMap`. They provide types only; component registration still uses component subpaths.\n\n## Events and Form Controls\n\nForm controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. Read the property from `event.currentTarget`.\n\nFinite-choice properties use Ore's `prop.oneOf()` parsing: values outside a component's documented options resolve to\nthe declared default, or `undefined` when no default is declared.\n\nForm-associated controls participate in native form submission, validity checks, and reset. A named control's value\nis available through `new FormData(form)`, and supported `required` constraints affect `form.checkValidity()`,\n`form.reportValidity()`, and submit blocking. The `error` property renders and announces feedback; it does not by\nitself set native constraint validity.\n\nStateful overlays expose controlled `open`, optional `default-open`, and an `open-change` custom event with `{ open, reason }` detail. Component pages define additional detail fields and reasons.\n\n## Utilities\n\n### `createThemeController(options?)`\n\n```ts\nimport { createThemeController } from '@vielzeug/refine/theme';\n\nconst theme = createThemeController(); // starts in 'system' mode\ntheme.setPreference('dark');\ntheme.dispose();\n```\n\nOwns the light/dark/system theme for the document: a reactive `preference` signal, the effective `resolved` mode (`'dark' | 'light'` after resolving `system` against the OS), and the DOM application `styles/theme.css` expects: the `.dark` class plus the `color-scheme` property on the root element, so every `light-dark()` token resolves to the right branch. While in `system` mode the controller tracks the OS `prefers-color-scheme` via sentinel's `createMediaQuery`.\n\nThe controller does **not** persist the preference or expose an accent color: those are consumer concerns (wire `watch(controller.preference, save)` for persistence; set `--color-primary-hue` yourself). Options: `initial` (starting preference, default `'system'`), `root` (element carrying the classes, default `document.documentElement`), `target` (window whose `matchMedia` backs `system`). The handle is disposable: `dispose()`, `disposed`, `disposalSignal`, `[Symbol.dispose]`.\n\n### `eventFieldValue(event)` / `eventFieldChecked(event)`\n\n```ts\nimport { eventFieldChecked, eventFieldValue } from '@vielzeug/refine';\n\ninput.addEventListener('input', (event) => {\n const value = eventFieldValue(event); // string | undefined: never a blind cast\n});\n```\n\nGuarded readers for the standard `input`/`change` event pattern above: they read `value`/`checked` from `event.currentTarget` only when the target actually carries it, so a handler wired to the wrong element yields `undefined`/`false` instead of a crash or a lie. Exported from the package root, which registers no components.\n\n---\n\n### `animateReflow(host, signal, options)`\n\n```ts\nimport { animateReflow } from '@vielzeug/refine';\n\nconst reflow = animateReflow(list, abortController.signal, {\n elements: () => [...list.querySelectorAll('li')],\n getKey: (item) => item.dataset.id,\n});\nreflow.run(() => renderItems(nextItems));\n```\n\nToken-driven FLIP reflow for keyed lists: captures the current layout, runs `mutate`, then animates the tracked elements into their new positions on the next frame. The same helper the DataGrid, command palette, and toast stack use.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `host` | `HTMLElement` | Element whose computed style carries the timing tokens |\n| `signal` | `AbortSignal` | Aborting cancels in-flight animations |\n| `options.elements` | `() => HTMLElement[]` | Tracked elements, read live on both sides of the mutation |\n| `options.getKey` | `(el) => string \\| undefined` | Stable identity per element; all-or-nothing |\n| `options.durationToken` | `string?` | Duration token, default `'--duration-200'` |\n| `options.easingToken` | `string?` | Easing token, default `'--ease-move'` |\n| `options.stagger` | `number?` | Per-element delay in ms, default `0` |\n\n**Returns** a `Reflow` handle with one method: `run(mutate)` (sync; the animation is fire-and-forget). Timing is read from the tokens at animation time, so Motion Mode reduction skips the reflow instead of playing it instantly. Every path that cannot animate (no elements, missing keys, zeroed tokens, aborted signal, no Web Animations API) still runs `mutate` exactly once and never throws. See [Animation & Motion → List Reflow](./animation#list-reflow-animatereflow) for behavior details.\n\n---\n\n### `setMotionMode(mode)` / `getMotionMode()`\n\n```ts\nimport { getMotionMode, setMotionMode } from '@vielzeug/refine';\n\nsetMotionMode('reduced'); // returns the applied mode\n```\n\nRead/write the `data-motion` attribute on `<html>` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). An unknown mode throws `RangeError`. The attribute drives the token layer: see [Animation & Motion → Motion Mode](./animation#motion-mode).\n\n## Types\n\nComponent props follow the `Ore<Component>Props` naming pattern. Event maps follow `Ore<Component>Events`. Import both from the component subpath that owns them.\n\n`RefineElementMap`, `RefineReactIntrinsicElements`, and `RefineVueGlobalComponents` are exported from their respective `frameworks/*` type entry points.\n\nThe package root also exports `Reflow` (the `run()` handle), `ReflowOptions` (its options object), and `MotionMode` (`'full' | 'reduced' | 'system'`).\n\n## Errors\n\n### `RefineError`\n\n```ts\nclass RefineError extends Error {\n constructor(message: string, opts?: ErrorOptions);\n}\n```\n\nBase class for public Refine errors. It preserves `cause` through `ErrorOptions`.\n",
6
6
  "usage": "---\ntitle: 'Refine: Usage Guide'\ndescription: Register Refine components, configure properties, handle events, compose slots, and integrate frameworks.\n---\n\n[[toc]]\n\n## Basic Usage\n\nLoad the global design contract once, then register only the components used by the page.\n\n```ts\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/dialog';\n\nconst input = document.querySelector('ore-input');\nconst save = document.querySelector('ore-button');\n\nif (!(input instanceof HTMLElement) || !(save instanceof HTMLElement)) {\n throw new Error('Expected Refine controls');\n}\n\nsave.addEventListener('click', () => {\n console.log((input as HTMLElement & { value: string }).value);\n});\n```\n\nAdd the browser reset only when the application owns global element styling:\n\n```ts\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n## Choose an Icon Library\n\nRefine includes only its internal component icons. Register application icons before mounting them: use `registerIcons` and neutral `IconDefinition` data from `@vielzeug/refine/icons`, the pure `@vielzeug/refine/icons/lucide` adapter for selected Lucide icons, or `@vielzeug/refine/icons/iconify` for local Heroicons, Tabler, and Material Design Icons data. Keep importing the component from `@vielzeug/refine/icon`. Lucide is an optional peer: install `lucide` yourself only when choosing its data or `@vielzeug/refine/icons/lucide/all`; core and structural adapters do not require it. The [icon reference](./components/icon.md) covers imports, licenses, and presentation behavior.\n\nFor selected individual Iconify data, use `heroiconsIcons`, `tablerIcons`, or `mdiIcons` from `@vielzeug/refine/icons/heroicons`, `/tabler`, or `/mdi`. For example, `registerIcons(heroiconsIcons({ Search, Home }))` preserves your app keys. Install the matching `@iconify-icons/<family>` data package yourself; these helpers do not accept framework components. Keep `iconifyIcons` for collection JSON and aliases.\n\n## Set Attributes and Properties\n\nUse attributes for serializable HTML state.\n\n```html\n<ore-button variant=\"outline\" color=\"secondary\" size=\"lg\" disabled>\n Save changes\n</ore-button>\n```\n\nUse JavaScript properties for arrays, objects, callbacks, and controlled state.\n\n```ts\nimport '@vielzeug/refine/datagrid';\nimport type { OreDataGridProps } from '@vielzeug/refine/datagrid';\n\nconst grid = document.querySelector('ore-datagrid') as HTMLElement & OreDataGridProps;\ngrid.columns = [\n { key: 'name', label: 'Name', sortable: true },\n { key: 'role', label: 'Role' },\n];\ngrid.rows = [\n { id: '1', name: 'Ada', role: 'Admin' },\n { id: '2', name: 'Linus', role: 'Editor' },\n];\n```\n\nEnumerated properties such as `variant`, `size`, and `color` accept the values listed on each component's reference\npage. An unsupported value resolves to the property's declared default (or `undefined` when it has no default).\n\nIn an Ore template, `model()` can bind a Refine field's `value` to a Ripple signal and write user input back:\n\n```ts\nimport { signal } from '@vielzeug/ripple';\nimport { html, model } from '@vielzeug/ore';\nimport '@vielzeug/refine/input';\n\nconst email = signal('');\nconst field = html`<ore-input label=\"Email\" type=\"email\" value=${model(email)} />`;\n```\n\n## Handle Events\n\nForm controls dispatch standard `input` and `change` events. Read their current property from `event.currentTarget`.\n\n```ts\nconst input = document.querySelector('ore-input');\ninput?.addEventListener('input', (event) => {\n const target = event.currentTarget as HTMLElement & { value: string };\n console.log(target.value);\n});\n```\n\nCustom events use kebab-case names and typed detail objects.\n\n```ts\nimport type { OreDialogEvents } from '@vielzeug/refine/dialog';\n\nconst dialog = document.querySelector('ore-dialog');\ndialog?.addEventListener('open-change', (event: CustomEvent<OreDialogEvents['open-change']>) => {\n console.log(event.detail.open, event.detail.reason);\n});\n```\n\n## Native Form Validation\n\nRefine's form-associated controls integrate with native form submission, `FormData`, validity checks, and reset.\nUse `required` for a required-value constraint; setting `error` displays and announces feedback but does not, by\nitself, invalidate the form.\n\n```html\n<form id=\"profile-form\">\n <ore-input name=\"email\" type=\"email\" label=\"Email\" required></ore-input>\n <ore-select name=\"role\" label=\"Role\" required>\n <option value=\"\">Choose a role…</option>\n <option value=\"editor\">Editor</option>\n <option value=\"admin\">Admin</option>\n </ore-select>\n <ore-button type=\"submit\">Save</ore-button>\n</form>\n\n<script type=\"module\">\n import '@vielzeug/refine/input';\n import '@vielzeug/refine/select';\n import '@vielzeug/refine/button';\n\n const form = document.querySelector('#profile-form');\n form.addEventListener('submit', (event) => {\n event.preventDefault();\n console.log(new FormData(form).get('email'));\n });\n</script>\n```\n\nThe browser runs native validation before dispatching `submit`. Call `form.reportValidity()` to show validation\nfeedback directly, or `form.checkValidity()` for a boolean check without the browser's validation UI.\n\n## Compose Slots\n\nDefault slots hold primary content. Named slots identify component-owned regions.\n\n```html\n<ore-card>\n <span slot=\"header\">Account</span>\n <p>Profile settings</p>\n <div slot=\"footer\">\n <ore-button variant=\"ghost\">Cancel</ore-button>\n <ore-button>Save</ore-button>\n </div>\n</ore-card>\n```\n\nInput components commonly expose `prefix`, `suffix`, `label`, `helper`, and `error` slots. Each component reference lists its supported slots.\n\n## Load TypeScript Framework Declarations\n\nImport the declaration matching the framework once in an application type entry point.\n\n::: code-group\n\n```ts [DOM]\nimport type {} from '@vielzeug/refine/frameworks/elements';\n```\n\n```ts [React]\nimport type {} from '@vielzeug/refine/frameworks/react';\n```\n\n```ts [Vue]\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\n:::\n\nThese entry points provide typed tags and component properties. They do not register components or install runtime adapters.\n\n## Framework Integration\n\nRefine elements use native DOM properties, events, and slots. Frameworks differ only in how they forward custom-element properties and events.\n\n::: code-group\n\n```tsx [React 19]\nimport '@vielzeug/refine/button';\n\nexport function SaveButton() {\n return <ore-button variant=\"solid\">Save</ore-button>;\n}\n```\n\n```vue [Vue 3]\n<script setup lang=\"ts\">\nimport '@vielzeug/refine/button';\n</script>\n\n<template>\n <ore-button variant=\"solid\">Save</ore-button>\n</template>\n```\n\n```svelte [Svelte]\n<script lang=\"ts\">\n import '@vielzeug/refine/button';\n</script>\n\n<ore-button variant=\"solid\">Save</ore-button>\n```\n\n:::\n\nSee [Framework Integration](./frameworks.md) for custom events, controlled properties, SSR guards, and framework-specific configuration.\n\n## Working with Other Vielzeug Libraries\n\n### Ore\n\nUse Ore when authoring a custom element that composes Refine components.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { define, html } from '@vielzeug/ore';\n\ndefine('save-panel', {\n setup() {\n return html`<ore-button @click=${() => console.log('save')}>Save</ore-button>`;\n },\n});\n```\n\n### Ripple\n\nUse Ripple to drive component properties from application state.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { effect, signal } from '@vielzeug/ripple';\n\nconst loading = signal(false);\nconst button = document.querySelector('ore-button') as HTMLElement & { loading?: boolean };\nconst loadingEffect = effect(() => {\n button.loading = loading.value;\n});\n\nloadingEffect.dispose();\n```\n\n### Necromancer\n\nUse Necromancer directly when you need animation handles, groups, or explicit keyframes. Refine's [`animateReflow`](./animation#list-reflow-animatereflow) is the token-driven wrapper over its FLIP primitive and is enough for keyed lists that reflow.\n\n## Best Practices\n\n- **Import** `tokens.css` once before rendering components.\n- **Register** components through explicit subpaths.\n- **Set** structured data and callbacks as JavaScript properties.\n- **Read** form state from the event target instead of custom event payloads.\n- **Provide** accessible labels for icon-only controls.\n- **Use** component reference pages for supported slots, parts, and CSS properties.\n- **Dispose** application-owned Ripple effects and service handles.\n- **Guard** DOM-dependent component registration during SSR.\n- **Working with AI agents?** Install the `vielzeug` skill (`npx -y @vielzeug/codex skills install`) so agents reach for Refine components and tokens instead of custom widgets: see the [Codex usage guide](../codex/usage.md#agent-skill).\n"
7
7
  },
8
8
  "examples": [],
package/data/refine.json CHANGED
@@ -1238,6 +1238,61 @@
1238
1238
  ],
1239
1239
  "description": "Convert caller-named individual `@iconify-icons/tabler` data, not native Tabler framework components.\nPreserves app keys and SVG presentation; requires DOMParser. No imports or registration of icon sets."
1240
1240
  },
1241
+ {
1242
+ "kind": "function",
1243
+ "name": "listen",
1244
+ "return": {
1245
+ "type": {
1246
+ "text": "(() => void)"
1247
+ }
1248
+ },
1249
+ "parameters": [
1250
+ {
1251
+ "name": "el",
1252
+ "type": {
1253
+ "text": "EventTarget | null | undefined"
1254
+ }
1255
+ },
1256
+ {
1257
+ "name": "name",
1258
+ "type": {
1259
+ "text": "string"
1260
+ }
1261
+ },
1262
+ {
1263
+ "name": "handler",
1264
+ "type": {
1265
+ "text": "(e: E) => void"
1266
+ }
1267
+ },
1268
+ {
1269
+ "name": "options",
1270
+ "optional": true,
1271
+ "type": {
1272
+ "text": "AddEventListenerOptions"
1273
+ }
1274
+ }
1275
+ ],
1276
+ "description": "Subscribe to an event and return its teardown. Returns a no-op for a missing\ntarget so callers can pass an optional element without branching."
1277
+ },
1278
+ {
1279
+ "kind": "function",
1280
+ "name": "findScrollContainer",
1281
+ "return": {
1282
+ "type": {
1283
+ "text": "HTMLElement | null"
1284
+ }
1285
+ },
1286
+ "parameters": [
1287
+ {
1288
+ "name": "start",
1289
+ "type": {
1290
+ "text": "HTMLElement"
1291
+ }
1292
+ }
1293
+ ],
1294
+ "description": "The nearest scrollable ancestor, so a component pinned to the viewport can\nlisten for the scroll that actually moves it: a bar inside a scrolling panel\nnever sees a `window` scroll event."
1295
+ },
1241
1296
  {
1242
1297
  "kind": "function",
1243
1298
  "name": "parseMaxWidthPx",
@@ -11158,6 +11213,165 @@
11158
11213
  }
11159
11214
  ]
11160
11215
  },
11216
+ {
11217
+ "kind": "variable",
11218
+ "name": "DOCK_PHONE_QUERY",
11219
+ "type": {
11220
+ "text": "string"
11221
+ },
11222
+ "default": "'(width < 640px)'",
11223
+ "description": "The viewport width below which a dock trades its full-width bar for the phone tool row. The\nbar's own stylesheet keys this same query; it is exported for a consumer that renders alongside\nthe bar and has to switch its own layout on the same line the bar does."
11224
+ },
11225
+ {
11226
+ "kind": "variable",
11227
+ "name": "DOCK_TAG",
11228
+ "type": {
11229
+ "text": "'ore-dock'"
11230
+ },
11231
+ "default": "'ore-dock'",
11232
+ "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\n\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\n\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nBy default, a phone row with one action zone hugs its content: `start` aligns to the leading\nedge, `commit` to the trailing edge, and tools to the middle. A lone `center` stays in the row.\nMultiple action zones and attached tools fill the row. `mobile-layout=\"full\"` always fills it;\n`mobile-layout=\"compact\"` always hugs and centers it. Above the phone width every bar is a\nfull-width strip.\n\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\n\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\n\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written."
11233
+ },
11234
+ {
11235
+ "kind": "class",
11236
+ "name": "OreDockElement",
11237
+ "tagName": "ore-dock",
11238
+ "customElement": true,
11239
+ "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nBy default, a phone row with one action zone hugs its content: `start` aligns to the leading\nedge, `commit` to the trailing edge, and tools to the middle. A lone `center` stays in the row.\nMultiple action zones and attached tools fill the row. `mobile-layout=\"full\"` always fills it;\n`mobile-layout=\"compact\"` always hugs and centers it. Above the phone width every bar is a\nfull-width strip.\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written.",
11240
+ "summary": "",
11241
+ "attributes": [
11242
+ {
11243
+ "name": "side",
11244
+ "type": {
11245
+ "text": "'top' | 'bottom'"
11246
+ },
11247
+ "description": "Edge to pin to: 'top' | 'bottom' (default)"
11248
+ },
11249
+ {
11250
+ "name": "sticky",
11251
+ "type": {
11252
+ "text": "boolean"
11253
+ },
11254
+ "description": "Pin to the edge while the container scrolls (default true)"
11255
+ },
11256
+ {
11257
+ "name": "attached",
11258
+ "type": {
11259
+ "text": "boolean"
11260
+ },
11261
+ "description": "Fuse the tool row into one segmented capsule"
11262
+ },
11263
+ {
11264
+ "name": "mobile-layout",
11265
+ "type": {
11266
+ "text": "'full' | 'compact'"
11267
+ },
11268
+ "description": "Phone sizing: 'auto' (default) | 'full' | 'compact'"
11269
+ },
11270
+ {
11271
+ "name": "label",
11272
+ "type": {
11273
+ "text": "string"
11274
+ },
11275
+ "description": "Accessible name for the toolbar landmark"
11276
+ }
11277
+ ],
11278
+ "slots": [
11279
+ {
11280
+ "name": "",
11281
+ "description": "The tool row, between the flanks"
11282
+ },
11283
+ {
11284
+ "name": "start",
11285
+ "description": "Leading flank (a back action)"
11286
+ },
11287
+ {
11288
+ "name": "center",
11289
+ "description": "The middle place: may carry a non-action such as a clock"
11290
+ },
11291
+ {
11292
+ "name": "commit",
11293
+ "description": "Trailing flank (the commit action)"
11294
+ }
11295
+ ],
11296
+ "cssParts": [
11297
+ {
11298
+ "name": "bar",
11299
+ "description": "The bar itself."
11300
+ },
11301
+ {
11302
+ "name": "start",
11303
+ "description": "Leading flank."
11304
+ },
11305
+ {
11306
+ "name": "center",
11307
+ "description": "Middle place."
11308
+ },
11309
+ {
11310
+ "name": "tools",
11311
+ "description": "Tool row."
11312
+ },
11313
+ {
11314
+ "name": "commit",
11315
+ "description": "Trailing flank."
11316
+ }
11317
+ ],
11318
+ "cssProperties": [
11319
+ {
11320
+ "name": "--dock-bg",
11321
+ "description": "Bar fill. Defaults to the translucent canvas token"
11322
+ },
11323
+ {
11324
+ "name": "--dock-color",
11325
+ "description": "Bar ink"
11326
+ },
11327
+ {
11328
+ "name": "--dock-border-color",
11329
+ "description": "Hairline shown while the bar is pinned, and the pill's border"
11330
+ },
11331
+ {
11332
+ "name": "--dock-blur",
11333
+ "description": "Blur radius behind the bar. Set `0` to drop it"
11334
+ },
11335
+ {
11336
+ "name": "--dock-radius",
11337
+ "description": "Bar corner radius, used by the pinned phone pill"
11338
+ },
11339
+ {
11340
+ "name": "--dock-offset",
11341
+ "description": "Inset from the viewport's edges"
11342
+ },
11343
+ {
11344
+ "name": "--dock-gap",
11345
+ "description": "Gap between the bar's places, above the phone width"
11346
+ },
11347
+ {
11348
+ "name": "--dock-tool-gap",
11349
+ "description": "Gap between the tools in the row"
11350
+ },
11351
+ {
11352
+ "name": "--dock-padding",
11353
+ "description": "Bar padding, before the safe-area inset"
11354
+ },
11355
+ {
11356
+ "name": "--dock-z-index",
11357
+ "description": "Stacking order of the bar"
11358
+ },
11359
+ {
11360
+ "name": "--dock-tool-flex",
11361
+ "description": "`flex` for each tool in `attached` mode. Defaults to `1 1 0`"
11362
+ },
11363
+ {
11364
+ "name": "--dock-tool-radius",
11365
+ "description": "Corner radius of a fused capsule's ends"
11366
+ }
11367
+ ],
11368
+ "demos": [
11369
+ {
11370
+ "url": "",
11371
+ "description": "```html\n<ore-dock>\n <ore-button slot=\"start\" icon-only label=\"Back\">\n <ore-icon name=\"arrow-left\"></ore-icon>\n </ore-button>\n <ore-button>Share</ore-button>\n <ore-button slot=\"commit\" color=\"primary\">Done</ore-button>\n</ore-dock>\n<!-- A list page's verbs, fused into one capsule -->\n<ore-dock attached>\n <ore-button>Import</ore-button>\n <ore-button color=\"primary\">New</ore-button>\n</ore-dock>\n```"
11372
+ }
11373
+ ]
11374
+ },
11161
11375
  {
11162
11376
  "kind": "variable",
11163
11377
  "name": "GRID_TAG",
@@ -14213,106 +14427,16 @@
14213
14427
  },
14214
14428
  {
14215
14429
  "kind": "variable",
14216
- "name": "MENU_ITEM_TAG",
14430
+ "name": "MENU_LAYOUTS",
14217
14431
  "type": {
14218
- "text": "'ore-menu-item'"
14432
+ "text": "['grid', 'list']"
14219
14433
  },
14220
- "default": "'ore-menu-item'",
14221
- "description": "A selectable action item used inside `<ore-menu>`."
14434
+ "default": "['grid', 'list']"
14222
14435
  },
14223
14436
  {
14224
- "kind": "class",
14225
- "name": "OreMenuItemElement",
14226
- "tagName": "ore-menu-item",
14227
- "customElement": true,
14228
- "description": "A selectable action item used inside `<ore-menu>`.",
14229
- "summary": "",
14230
- "attributes": [
14231
- {
14232
- "name": "checked",
14233
- "type": {
14234
- "text": "boolean"
14235
- },
14236
- "description": "Checked state for `checkbox` and `radio` item types"
14237
- },
14238
- {
14239
- "name": "disabled",
14240
- "type": {
14241
- "text": "boolean"
14242
- },
14243
- "description": "Disables selection and pointer interaction"
14244
- },
14245
- {
14246
- "name": "type",
14247
- "type": {
14248
- "text": "'checkbox'|'radio'"
14249
- },
14250
- "description": "Optional checkable menu item mode"
14251
- },
14252
- {
14253
- "name": "value",
14254
- "type": {
14255
- "text": "string"
14256
- },
14257
- "description": "Value emitted by parent menu on selection"
14258
- }
14259
- ],
14260
- "slots": [
14261
- {
14262
- "name": "",
14263
- "description": "Item label/content"
14264
- },
14265
- {
14266
- "name": "icon",
14267
- "description": "Optional leading icon content"
14268
- }
14269
- ],
14270
- "cssParts": [
14271
- {
14272
- "name": "item",
14273
- "description": "Root item container element."
14274
- },
14275
- {
14276
- "name": "item-label",
14277
- "description": "Label text container."
14278
- },
14279
- {
14280
- "name": "icon-slot",
14281
- "description": "Leading icon slot container."
14282
- }
14283
- ],
14284
- "cssProperties": [
14285
- {
14286
- "name": "--menu-item-hover-bg",
14287
- "description": "Background on hover"
14288
- },
14289
- {
14290
- "name": "--menu-item-focus-color",
14291
- "description": "Text color when keyboard-focused"
14292
- },
14293
- {
14294
- "name": "--menu-item-focus-bg",
14295
- "description": "Background when keyboard-focused"
14296
- },
14297
- {
14298
- "name": "--menu-item-selection-bg",
14299
- "description": "Background for checkbox/radio items (unselected)"
14300
- },
14301
- {
14302
- "name": "--menu-item-checked-color",
14303
- "description": "Text color when checked"
14304
- },
14305
- {
14306
- "name": "--menu-item-checked-bg",
14307
- "description": "Background when checked"
14308
- }
14309
- ],
14310
- "demos": [
14311
- {
14312
- "url": "",
14313
- "description": "```html\n<ore-menu-item value=\"edit\">Edit</ore-menu-item>\n<ore-menu-item value=\"delete\" disabled>Delete</ore-menu-item>\n<ore-menu-item type=\"checkbox\" value=\"wrap\" checked>Word wrap</ore-menu-item>\n<ore-menu-item type=\"radio\" value=\"left\">Align left</ore-menu-item>\n```"
14314
- }
14315
- ]
14437
+ "kind": "variable",
14438
+ "name": "MENU_CTX",
14439
+ "description": "Shared context propagated from `ore-menu` to its slotted `ore-menu-item` children."
14316
14440
  },
14317
14441
  {
14318
14442
  "kind": "variable",
@@ -14375,6 +14499,20 @@
14375
14499
  },
14376
14500
  "description": "Initial uncontrolled open state"
14377
14501
  },
14502
+ {
14503
+ "name": "layout",
14504
+ "type": {
14505
+ "text": "string"
14506
+ },
14507
+ "description": "Panel layout: 'list' (default) | 'grid'"
14508
+ },
14509
+ {
14510
+ "name": "columns",
14511
+ "type": {
14512
+ "text": "number"
14513
+ },
14514
+ "description": "Columns per row in `grid` layout (default 3)"
14515
+ },
14378
14516
  {
14379
14517
  "name": "placement",
14380
14518
  "type": {
@@ -14451,6 +14589,14 @@
14451
14589
  {
14452
14590
  "name": "--menu-panel-radius",
14453
14591
  "description": "Border radius of the floating panel"
14592
+ },
14593
+ {
14594
+ "name": "--menu-panel-width",
14595
+ "description": "Panel width in `grid` layout. Defaults to a phone-safe cap"
14596
+ },
14597
+ {
14598
+ "name": "--menu-panel-gap",
14599
+ "description": "Gap between grid cards"
14454
14600
  }
14455
14601
  ],
14456
14602
  "demos": [
@@ -14460,6 +14606,109 @@
14460
14606
  }
14461
14607
  ]
14462
14608
  },
14609
+ {
14610
+ "kind": "variable",
14611
+ "name": "MENU_ITEM_TAG",
14612
+ "type": {
14613
+ "text": "'ore-menu-item'"
14614
+ },
14615
+ "default": "'ore-menu-item'",
14616
+ "description": "A selectable action item used inside `<ore-menu>`."
14617
+ },
14618
+ {
14619
+ "kind": "class",
14620
+ "name": "OreMenuItemElement",
14621
+ "tagName": "ore-menu-item",
14622
+ "customElement": true,
14623
+ "description": "A selectable action item used inside `<ore-menu>`.",
14624
+ "summary": "",
14625
+ "attributes": [
14626
+ {
14627
+ "name": "checked",
14628
+ "type": {
14629
+ "text": "boolean"
14630
+ },
14631
+ "description": "Checked state for `checkbox` and `radio` item types"
14632
+ },
14633
+ {
14634
+ "name": "disabled",
14635
+ "type": {
14636
+ "text": "boolean"
14637
+ },
14638
+ "description": "Disables selection and pointer interaction"
14639
+ },
14640
+ {
14641
+ "name": "type",
14642
+ "type": {
14643
+ "text": "'checkbox'|'radio'"
14644
+ },
14645
+ "description": "Optional checkable menu item mode"
14646
+ },
14647
+ {
14648
+ "name": "value",
14649
+ "type": {
14650
+ "text": "string"
14651
+ },
14652
+ "description": "Value emitted by parent menu on selection"
14653
+ }
14654
+ ],
14655
+ "slots": [
14656
+ {
14657
+ "name": "",
14658
+ "description": "Item label/content"
14659
+ },
14660
+ {
14661
+ "name": "icon",
14662
+ "description": "Optional leading icon content"
14663
+ }
14664
+ ],
14665
+ "cssParts": [
14666
+ {
14667
+ "name": "item",
14668
+ "description": "Root item container element."
14669
+ },
14670
+ {
14671
+ "name": "item-label",
14672
+ "description": "Label text container."
14673
+ },
14674
+ {
14675
+ "name": "icon-slot",
14676
+ "description": "Leading icon slot container."
14677
+ }
14678
+ ],
14679
+ "cssProperties": [
14680
+ {
14681
+ "name": "--menu-item-hover-bg",
14682
+ "description": "Background on hover"
14683
+ },
14684
+ {
14685
+ "name": "--menu-item-focus-color",
14686
+ "description": "Text color when keyboard-focused"
14687
+ },
14688
+ {
14689
+ "name": "--menu-item-focus-bg",
14690
+ "description": "Background when keyboard-focused"
14691
+ },
14692
+ {
14693
+ "name": "--menu-item-selection-bg",
14694
+ "description": "Background for checkbox/radio items (unselected)"
14695
+ },
14696
+ {
14697
+ "name": "--menu-item-checked-color",
14698
+ "description": "Text color when checked"
14699
+ },
14700
+ {
14701
+ "name": "--menu-item-checked-bg",
14702
+ "description": "Background when checked"
14703
+ }
14704
+ ],
14705
+ "demos": [
14706
+ {
14707
+ "url": "",
14708
+ "description": "```html\n<ore-menu-item value=\"edit\">Edit</ore-menu-item>\n<ore-menu-item value=\"delete\" disabled>Delete</ore-menu-item>\n<ore-menu-item type=\"checkbox\" value=\"wrap\" checked>Word wrap</ore-menu-item>\n<ore-menu-item type=\"radio\" value=\"left\">Align left</ore-menu-item>\n```"
14709
+ }
14710
+ ]
14711
+ },
14463
14712
  {
14464
14713
  "kind": "variable",
14465
14714
  "name": "POPOVER_TAG",
package/data/search.json CHANGED
@@ -1056,12 +1056,12 @@
1056
1056
  "category": "ui components",
1057
1057
  "description": "accessible, themeable web components built with ore for framework and vanilla dom apps.",
1058
1058
  "docs": {
1059
- "index": " \ntitle: 'refine: web component library'\ndescription: accessible, themeable web components built with ore for framework and vanilla dom apps.\npackage: refine\ncategory: ui components\nkeywords: [web components, accessible, themeable, ui, components, design system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n [\n ore accordion,\n ore accordion item,\n ore alert,\n ore async,\n ore avatar,\n ore avatar group,\n ore badge,\n ore box,\n ore breadcrumb,\n ore breadcrumb item,\n ore button,\n ore button group,\n ore calendar,\n ore card,\n ore carousel,\n ore carousel slide,\n ore chat message,\n ore checkbox,\n ore checkbox group,\n ore chip,\n ore code window,\n ore column,\n ore combobox,\n ore combobox option,\n ore command palette,\n ore command palette item,\n ore cookie banner,\n ore copy command,\n ore counter,\n ore datagrid,\n ore date picker,\n ore dialog,\n ore drawer,\n ore file input,\n ore grid,\n ore grid item,\n ore icon,\n ore input,\n ore keyboard key,\n ore keyboard shortcut,\n ore list,\n ore list item,\n ore marquee,\n ore menu,\n ore menu item,\n ore menu separator,\n ore message composer,\n ore navbar,\n ore navbar item,\n ore navigation menu,\n ore navigation menu item,\n ore navigation menu panel,\n ore number input,\n ore otp input,\n ore pagination,\n ore password strength,\n ore popover,\n ore progress,\n ore qr code,\n ore qr scanner,\n ore query bar,\n ore radio,\n ore radio group,\n ore rating,\n ore select,\n ore separator,\n ore sidebar,\n ore sidebar group,\n ore sidebar item,\n ore skeleton,\n ore slider,\n ore speech player,\n ore speed reading,\n ore spotlight,\n ore stats,\n ore step,\n ore stepper,\n ore switch,\n ore tab item,\n ore tab panel,\n ore table,\n ore tabs,\n ore td,\n ore text,\n ore th,\n ore tr,\n ore textarea,\n ore time picker,\n ore toast,\n ore tooltip,\n ore tour,\n ore typing indicator,\n ]\nenvironments: [browser]\n \n\n<! markdownlint disable md025 md033 md060 >\n\n<packagehero package=\"refine\" />\n\n## why refine?\n\nevery project needs ui primitives. refine provides accessible web components that work natively anywhere html is rendered, no framework required.\n\n```html\n<! before: roll your own button with aria >\n<button class=\"btn btn primary\" role=\"button\" aria pressed=\"false\" tabindex=\"0\">\n <span class=\"btn spinner\" aria hidden=\"true\"></span>\n save\n</button>\n\n<! after: refine >\n<ore button variant=\"solid\" color=\"primary\" loading>save</ore button>\n```\n\n| feature | refine | shoelace | material web |\n| | | | |\n| bundle size | <packageinfo package=\"refine\" type=\"size\" /> | ~145 kb | ~200 kb |\n| built with | ore | lit | lit |\n| runtime dependencies | vielzeug ui primitives; lucide only for the opt in full library registrar | lit + utilities | lit + material foundations |\n| accessible | wcag aa | wcag aa | wcag aa |\n| framework agnostic | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> |\n\n<div class=\"decision callout\">\n\n**use refine when** you want accessible web components that match the vielzeug design system without a heavy framework dependency.\n\n**consider shoelace or material web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## quick start\n\n```ts\n// 1. import global styles once\nimport '@vielzeug/refine/fouc.css'; // hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // tokens, animations, cascade layers\n\n// 2. register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore button variant=\"solid\" color=\"primary\">save</ore button>\n<ore input label=\"email\" type=\"email\" required></ore input>\n<ore card padding=\"lg\">\n <span slot=\"header\">account</span>\n <p>card content goes here.</p>\n</ore card>\n```\n\n```ts\n```\n\n### cdn / vanilla html\n\nuse the self contained iife bundle to load refine directly from a cdn in any html page: no build step required:\n\n```html\n<! 1. styles >\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<! 2. all components (iife: registers global refine namespace) >\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nfor bundler based projects that still want a cdn url, use the esm bundle via an import map:\n\n```html\n<script type=\"importmap\">\n {\n \"imports\": {\n \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n }\n }\n</script>\n\n<script type=\"module\">\n import '@vielzeug/refine/button';\n import '@vielzeug/refine/input';\n</script>\n```\n\n### package entry points\n\n| import | purpose |\n| | |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | optional browser default reset (includes fouc suppression) |\n\ncomponent registration happens through side effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### components\n\neach entry below is a component with its own documentation page and registration subpath. sub element tags (`ore accordion item`, `ore tab item`, `ore avatar group`, and the rest) are documented on their parent's page and registered with it.\n\n**content:** `ore accordion`, `ore avatar`, `ore card`, `ore carousel`, `ore chat message`, `ore chat panel`, `ore code window`, `ore copy command`, `ore icon`, `ore keyboard key`, `ore list`, `ore marquee`, `ore qr code`, `ore rank list`, `ore speech player`, `ore speed reading`, `ore stats`, `ore table`, `ore text`\n\n**feedback:** `ore alert`, `ore async`, `ore badge`, `ore chip`, `ore cookie banner`, `ore password strength`, `ore progress`, `ore skeleton`, `ore toast`, `ore typing indicator`\n\n**inputs:** `ore button`, `ore calendar`, `ore checkbox`, `ore combobox`, `ore counter`, `ore datagrid`, `ore date picker`, `ore file input`, `ore input`, `ore message composer`, `ore number input`, `ore otp input`, `ore qr scanner`, `ore query bar`, `ore radio`, `ore rating`, `ore select`, `ore slider`, `ore switch`, `ore textarea`, `ore time picker`\n\n**layout:** `ore box`, `ore grid`, `ore navbar`, `ore separator`, `ore sidebar`\n\n**navigation:** `ore breadcrumb`, `ore navigation menu`, `ore pagination`, `ore stepper`, `ore tabs`\n\n**overlay:** `ore command palette`, `ore dialog`, `ore drawer`, `ore menu`, `ore popover`, `ore spotlight`, `ore tooltip`, `ore tour`\n\n## component portfolio\n\nrefine keeps one public package and classifies components by composition level rather than stability. all listed components remain supported and tested.\n\n **foundations**: buttons, inputs, selection controls, accordions, dialogs, menus, tooltips, layout primitives, and feedback indicators. start here when building an application specific interface.\n **composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. these package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n **presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nclassification guides discovery and bundle selection. it is not a reason to remove working components or move them into unstable packages; per component subpath imports remain the tree shaking boundary.\n\n## features\n\n<div class=\"features grid\">\n\n **accessible**: keyboard navigation, aria wiring, and focus management across interactive components\n **themeable**: global tokens plus component level css custom properties\n **motion safe**: every animation routes through duration tokens and honors motion mode (`setmotionmode`) with a reduced motion floor\n **framework agnostic**: works anywhere html can be rendered\n **tree shakeable**: import only the component entry points you register\n **comprehensive surface**: inputs, content, navigation, feedback, layout, and overlay primitives\n **native form integration**: form associated controls submit values, validate supported required constraints, and reset with their form\n **typed framework declarations**: dom, react, and vue tags derive from the component property contracts\n\n</div>\n\n### prerequisites\n\n browser runtime with custom elements support.\n import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n for ssr, render placeholders server side and hydrate components only on the client.\n\n## documentation\n\n<div class=\"doc links\">\n\n [usage guide](./usage.md)\n [api reference](./api.md)\n [animation & motion](./animation.md)\n [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n [ore](/ore/): web component runtime that powers refine\n [orbit](/orbit/): floating ui positioning used in refine's overlays\n [forge](/forge/): form state management for use with refine inputs\n [keymap](/keymap/): keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<! markdownlint enable md025 md033 md060 >\n",
1060
- "api": " \ntitle: 'refine: api reference'\ndescription: published component, stylesheet, framework type, and error entry points for @vielzeug/refine.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `@vielzeug/refine/<component>` | register one custom element and export its public types | sync | importing a type alone does not register the element |\n| `@vielzeug/refine/tokens.css` | load required theme tokens, animations, and cascade layers | css | import once before components render |\n| `@vielzeug/refine/fouc.css` | hide unregistered `ore *` elements until upgrade | css | load before first paint |\n| `@vielzeug/refine/styles/preflight.css` | apply the optional browser reset | css | the reset affects global elements |\n| `@vielzeug/refine/frameworks/elements` | register typed dom tag mappings | types only | import for side effects in typescript |\n| `@vielzeug/refine/frameworks/react` | register typed react jsx elements | types only | does not provide runtime wrappers |\n| `@vielzeug/refine/frameworks/vue` | register typed vue global components | types only | does not install a vue plugin |\n| `@vielzeug/refine/theme` | `createthemecontroller()`: light/dark/system document theme | sync | does not persist the preference or set an accent color |\n| `eventfieldvalue()` / `eventfieldchecked()` | read a form control's value/checked from `event.currenttarget` | sync | exported from the package root; guards non field targets |\n| `animatereflow()` | token driven flip reflow for keyed lists | async (next frame) | exported from the package root; elements need stable keys or it correctly does nothing |\n| `setmotionmode()` / `getmotionmode()` | read/write the `data motion` attribute on `<html>` | sync | exported from the package root; an unknown mode throws `rangeerror` |\n| `refineerror` | base class for package defined public errors | sync | component configuration warnings do not throw this error |\n\n## package entry point\n\n| import | purpose |\n| | |\n| `@vielzeug/refine` | export `registericons`, icon definition types, `refineerror`, `animatereflow`, the motion mode functions, and the field readers without registering components |\n| `@vielzeug/refine/<component>` | register one component and export its tag constant, props, events, and related types |\n| `@vielzeug/refine/theme` | `createthemecontroller()` and its theme types |\n| `@vielzeug/refine/tokens.css` | required global design contract |\n| `@vielzeug/refine/fouc.css` | optional pre upgrade visibility rule |\n| `@vielzeug/refine/styles/*` | focused theme, animation, layer, and preflight stylesheets |\n| `@vielzeug/refine/frameworks/*` | typescript augmentations for dom, react, and vue |\n\n## icon registration and adapters\n\n`registericons(icons: readonly<record<string, icondefinition>>): void` is available from `@vielzeug/refine/icons`, `@vielzeug/refine`, and `@vielzeug/refine/icon`. the common `icons` entry and root remain free of component registration side effects.\n\n`icondefinition`, `iconelement`, and `iconattributes` are exported from all three entries. shared definition and registration modules live in `src/icons/`, alongside adapters and internal svg helpers/defaults. definitions contain a numeric `viewbox` tuple, optional presentation attributes, and recursive svg children; they do not require a provider identity. invalid registrations throw the root exported `refineerror` atomically.\n\n| entry | export | purpose |\n| | | |\n| `@vielzeug/refine/icons` | `registericons`, `icondefinition`, `iconelement`, `iconattributes` | common library neutral registration and definition api |\n| `@vielzeug/refine/icons/lucide` | `lucideicons`, `lucideicondata` | pure adapter for selected structural lucide svg data |\n| `@vielzeug/refine/icons/lucide/all` | side effect registration | explicitly register the full installed lucide library |\n| `@vielzeug/refine/icons/heroicons` | `heroiconsicons`, `iconifyicon` | convert a caller named map of individual heroicons iconify data |\n| `@vielzeug/refine/icons/tabler` | `tablericons`, `iconifyicon` | convert a caller named map of individual tabler iconify data |\n| `@vielzeug/refine/icons/mdi` | `mdiicons`, `iconifyicon` | convert a caller named map of individual mdi iconify data |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyicons` | convert individual iconify data or selected/complete collections |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyalias`, `iconifycollection`, `iconifytransform` | structural data types; no iconify dependency required |\n\nlucide is an optional peer, not a mandatory dependency. only `icons/lucide/all` requires an installed `lucide` package; consumers selecting that entry declare it themselves. the structural `icons/lucide` adapter accepts supplied data without importing lucide.\n\nthe standalone iife exposes `registericons`, `lucideicons`, `heroiconsicons`, `tablericons`, `mdiicons`, `iconifyicon`, and `iconifyicons` under `refine.components.content`. neither the iife nor component entries import lucide. iconify conversion drops provider `class` metadata, validates finite numeric offsets and positive finite dimensions before transforms, and retains the strict svg allowlist. see the [icon reference](./components/icon.md) for presentation overrides, local svg id rewriting, supported families, and licenses.\n\nthe three family adapters share this signature:\n\n```ts\nheroiconsicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\ntablericons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\nmdiicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\n```\n\neach accepts individual iconify svg data, preserves input keys without adding a namespace, and returns definitions without registering them. they require `domparser`, preserve each icon's geometry/presentation/transforms, and throw `refineerror` for invalid iconify data. they do not accept react/vue components, collection json, or raw svg path strings. use `iconifyicons(collection, names?)` for collections and alias resolution.\n\n## styles\n\n```ts\nimport '@vielzeug/refine/fouc.css';\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n`tokens.css` is required. it defines tokens, animations, and cascade layer order without resetting global elements. `preflight.css` is optional and includes fouc suppression.\n\n| import path | purpose |\n| | |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | tokens, animation helpers, and cascade layers |\n| `@vielzeug/refine/styles/theme.css` | theme token declarations |\n| `@vielzeug/refine/styles/animation.css` | animation helpers |\n| `@vielzeug/refine/styles/layers.css` | cascade layer declarations |\n| `@vielzeug/refine/styles/preflight.css` | optional browser reset and fouc suppression |\n\n## components\n\neach component uses one registration and type entry point:\n\n```ts\nimport '@vielzeug/refine/button';\nimport type { orebuttonprops } from '@vielzeug/refine/button';\n```\n\n| area | components |\n| | |\n| content | `accordion`, `avatar`, `card`, `carousel`, `chat message`, `chat panel`, `code window`, `copy command`, `icon`, `keyboard key`, `list`, `marquee`, `qr code`, `rank list`, `speech player`, `speed reading`, `stats`, `table`, `text` |\n| feedback | `alert`, `async`, `badge`, `chip`, `cookie banner`, `password strength`, `progress`, `skeleton`, `toast`, `typing indicator` |\n| inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date picker`, `file input`, `input`, `message composer`, `number input`, `otp input`, `qr scanner`, `query bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time picker` |\n| layout | `box`, `grid`, `navbar`, `separator`, `sidebar` |\n| navigation | `breadcrumb`, `navigation menu`, `pagination`, `stepper`, `tabs` |\n| overlay | `command palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |\n\neach row lists the entry points that own a documentation page. sub element entries (`accordion item`, `tab item`, `avatar group`, `list item`, `step`, and the rest) are documented on their parent's page and share its category.\n\neach component page lists its attributes, javascript properties, events, slots, parts, and css custom properties.\n\nthe [`query bar`](./components/query bar.md) entry also exports `querystate`, `querytokendef`, `queryquickfilter`, `querybarlabels`, and pure grammar helpers. vocabulary entries default to single selection; `selection: 'multiple'` allows distinct values for the same key. `anylabel` customizes the unrestricted single selection choice, such as “default order” for sorting. options accept an optional `icon` (registered `ore icon` name), displayed beside their labels in the drawer. `tokenvalues(state, key)` reads all values, `removetoken(state, token)` removes an exact pair, and `cleartokens(state, key)` clears a group. its unified field contains applied filters, with a compact secondary row for filter entry, quick toggles, and a `toolbar end` slot for application content such as a result count. drawer selection uses the same state and vocabulary as typed suggestions. pending edits block incidental backdrop/swipe dismissal; explicit cancel, close, and escape discard them. search hidden selections remain visible in a summary.\n\n## framework types\n\n```ts\nimport type {} from '@vielzeug/refine/frameworks/elements';\nimport type {} from '@vielzeug/refine/frameworks/react';\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\nthe declarations cover every supported tag and derive component properties from refine's authoritative `htmlelementtagnamemap`. they provide types only; component registration still uses component subpaths.\n\n## events and form controls\n\nform controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. read the property from `event.currenttarget`.\n\nfinite choice properties use ore's `prop.oneof()` parsing: values outside a component's documented options resolve to\nthe declared default, or `undefined` when no default is declared.\n\nform associated controls participate in native form submission, validity checks, and reset. a named control's value\nis available through `new formdata(form)`, and supported `required` constraints affect `form.checkvalidity()`,\n`form.reportvalidity()`, and submit blocking. the `error` property renders and announces feedback; it does not by\nitself set native constraint validity.\n\nstateful overlays expose controlled `open`, optional `default open`, and an `open change` custom event with `{ open, reason }` detail. component pages define additional detail fields and reasons.\n\n## utilities\n\n### `createthemecontroller(options?)`\n\n```ts\nimport { createthemecontroller } from '@vielzeug/refine/theme';\n\nconst theme = createthemecontroller(); // starts in 'system' mode\ntheme.setpreference('dark');\ntheme.dispose();\n```\n\nowns the light/dark/system theme for the document: a reactive `preference` signal, the effective `resolved` mode (`'dark' | 'light'` after resolving `system` against the os), and the dom application `styles/theme.css` expects: the `.dark` class plus the `color scheme` property on the root element, so every `light dark()` token resolves to the right branch. while in `system` mode the controller tracks the os `prefers color scheme` via sentinel's `createmediaquery`.\n\nthe controller does **not** persist the preference or expose an accent color: those are consumer concerns (wire `watch(controller.preference, save)` for persistence; set ` color primary hue` yourself). options: `initial` (starting preference, default `'system'`), `root` (element carrying the classes, default `document.documentelement`), `target` (window whose `matchmedia` backs `system`). the handle is disposable: `dispose()`, `disposed`, `disposalsignal`, `[symbol.dispose]`.\n\n### `eventfieldvalue(event)` / `eventfieldchecked(event)`\n\n```ts\nimport { eventfieldchecked, eventfieldvalue } from '@vielzeug/refine';\n\ninput.addeventlistener('input', (event) => {\n const value = eventfieldvalue(event); // string | undefined: never a blind cast\n});\n```\n\nguarded readers for the standard `input`/`change` event pattern above: they read `value`/`checked` from `event.currenttarget` only when the target actually carries it, so a handler wired to the wrong element yields `undefined`/`false` instead of a crash or a lie. exported from the package root, which registers no components.\n\n \n\n### `animatereflow(host, signal, options)`\n\n```ts\nimport { animatereflow } from '@vielzeug/refine';\n\nconst reflow = animatereflow(list, abortcontroller.signal, {\n elements: () => [...list.queryselectorall('li')],\n getkey: (item) => item.dataset.id,\n});\nreflow.run(() => renderitems(nextitems));\n```\n\ntoken driven flip reflow for keyed lists: captures the current layout, runs `mutate`, then animates the tracked elements into their new positions on the next frame. the same helper the datagrid, command palette, and toast stack use.\n\n| parameter | type | description |\n| | | |\n| `host` | `htmlelement` | element whose computed style carries the timing tokens |\n| `signal` | `abortsignal` | aborting cancels in flight animations |\n| `options.elements` | `() => htmlelement[]` | tracked elements, read live on both sides of the mutation |\n| `options.getkey` | `(el) => string \\| undefined` | stable identity per element; all or nothing |\n| `options.durationtoken` | `string?` | duration token, default `' duration 200'` |\n| `options.easingtoken` | `string?` | easing token, default `' ease move'` |\n| `options.stagger` | `number?` | per element delay in ms, default `0` |\n\n**returns** a `reflow` handle with one method: `run(mutate)` (sync; the animation is fire and forget). timing is read from the tokens at animation time, so motion mode reduction skips the reflow instead of playing it instantly. every path that cannot animate (no elements, missing keys, zeroed tokens, aborted signal, no web animations api) still runs `mutate` exactly once and never throws. see [animation & motion → list reflow](./animation#list reflow animatereflow) for behavior details.\n\n \n\n### `setmotionmode(mode)` / `getmotionmode()`\n\n```ts\nimport { getmotionmode, setmotionmode } from '@vielzeug/refine';\n\nsetmotionmode('reduced'); // returns the applied mode\n```\n\nread/write the `data motion` attribute on `<html>` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). an unknown mode throws `rangeerror`. the attribute drives the token layer: see [animation & motion → motion mode](./animation#motion mode).\n\n## types\n\ncomponent props follow the `ore<component>props` naming pattern. event maps follow `ore<component>events`. import both from the component subpath that owns them.\n\n`refineelementmap`, `refinereactintrinsicelements`, and `refinevueglobalcomponents` are exported from their respective `frameworks/*` type entry points.\n\nthe package root also exports `reflow` (the `run()` handle), `reflowoptions` (its options object), and `motionmode` (`'full' | 'reduced' | 'system'`).\n\n## errors\n\n### `refineerror`\n\n```ts\nclass refineerror extends error {\n constructor(message: string, opts?: erroroptions);\n}\n```\n\nbase class for public refine errors. it preserves `cause` through `erroroptions`.\n",
1059
+ "index": " \ntitle: 'refine: web component library'\ndescription: accessible, themeable web components built with ore for framework and vanilla dom apps.\npackage: refine\ncategory: ui components\nkeywords: [web components, accessible, themeable, ui, components, design system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n [\n ore accordion,\n ore accordion item,\n ore alert,\n ore async,\n ore avatar,\n ore avatar group,\n ore badge,\n ore box,\n ore breadcrumb,\n ore breadcrumb item,\n ore button,\n ore button group,\n ore calendar,\n ore card,\n ore carousel,\n ore carousel slide,\n ore chat message,\n ore checkbox,\n ore checkbox group,\n ore chip,\n ore code window,\n ore column,\n ore combobox,\n ore combobox option,\n ore command palette,\n ore command palette item,\n ore cookie banner,\n ore copy command,\n ore counter,\n ore datagrid,\n ore date picker,\n ore dialog,\n ore dock,\n ore drawer,\n ore file input,\n ore grid,\n ore grid item,\n ore icon,\n ore input,\n ore keyboard key,\n ore keyboard shortcut,\n ore list,\n ore list item,\n ore marquee,\n ore menu,\n ore menu item,\n ore menu separator,\n ore message composer,\n ore navbar,\n ore navbar item,\n ore navigation menu,\n ore navigation menu item,\n ore navigation menu panel,\n ore number input,\n ore otp input,\n ore pagination,\n ore password strength,\n ore popover,\n ore progress,\n ore qr code,\n ore qr scanner,\n ore query bar,\n ore radio,\n ore radio group,\n ore rating,\n ore select,\n ore separator,\n ore sidebar,\n ore sidebar group,\n ore sidebar item,\n ore skeleton,\n ore slider,\n ore speech player,\n ore speed reading,\n ore spotlight,\n ore stats,\n ore step,\n ore stepper,\n ore switch,\n ore tab item,\n ore tab panel,\n ore table,\n ore tabs,\n ore td,\n ore text,\n ore th,\n ore tr,\n ore textarea,\n ore time picker,\n ore toast,\n ore tooltip,\n ore tour,\n ore typing indicator,\n ]\nenvironments: [browser]\n \n\n<! markdownlint disable md025 md033 md060 >\n\n<packagehero package=\"refine\" />\n\n## why refine?\n\nevery project needs ui primitives. refine provides accessible web components that work natively anywhere html is rendered, no framework required.\n\n```html\n<! before: roll your own button with aria >\n<button class=\"btn btn primary\" role=\"button\" aria pressed=\"false\" tabindex=\"0\">\n <span class=\"btn spinner\" aria hidden=\"true\"></span>\n save\n</button>\n\n<! after: refine >\n<ore button variant=\"solid\" color=\"primary\" loading>save</ore button>\n```\n\n| feature | refine | shoelace | material web |\n| | | | |\n| bundle size | <packageinfo package=\"refine\" type=\"size\" /> | ~145 kb | ~200 kb |\n| built with | ore | lit | lit |\n| runtime dependencies | vielzeug ui primitives; lucide only for the opt in full library registrar | lit + utilities | lit + material foundations |\n| accessible | wcag aa | wcag aa | wcag aa |\n| framework agnostic | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> |\n\n<div class=\"decision callout\">\n\n**use refine when** you want accessible web components that match the vielzeug design system without a heavy framework dependency.\n\n**consider shoelace or material web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## quick start\n\n```ts\n// 1. import global styles once\nimport '@vielzeug/refine/fouc.css'; // hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // tokens, animations, cascade layers\n\n// 2. register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore button variant=\"solid\" color=\"primary\">save</ore button>\n<ore input label=\"email\" type=\"email\" required></ore input>\n<ore card padding=\"lg\">\n <span slot=\"header\">account</span>\n <p>card content goes here.</p>\n</ore card>\n```\n\n```ts\n```\n\n### cdn / vanilla html\n\nuse the self contained iife bundle to load refine directly from a cdn in any html page: no build step required:\n\n```html\n<! 1. styles >\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<! 2. all components (iife: registers global refine namespace) >\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nfor bundler based projects that still want a cdn url, use the esm bundle via an import map:\n\n```html\n<script type=\"importmap\">\n {\n \"imports\": {\n \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n }\n }\n</script>\n\n<script type=\"module\">\n import '@vielzeug/refine/button';\n import '@vielzeug/refine/input';\n</script>\n```\n\n### package entry points\n\n| import | purpose |\n| | |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | optional browser default reset (includes fouc suppression) |\n\ncomponent registration happens through side effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### components\n\neach entry below is a component with its own documentation page and registration subpath. sub element tags (`ore accordion item`, `ore tab item`, `ore avatar group`, and the rest) are documented on their parent's page and registered with it.\n\n**content:** `ore accordion`, `ore avatar`, `ore card`, `ore carousel`, `ore chat message`, `ore chat panel`, `ore code window`, `ore copy command`, `ore icon`, `ore keyboard key`, `ore list`, `ore marquee`, `ore qr code`, `ore rank list`, `ore speech player`, `ore speed reading`, `ore stats`, `ore table`, `ore text`\n\n**feedback:** `ore alert`, `ore async`, `ore badge`, `ore chip`, `ore cookie banner`, `ore password strength`, `ore progress`, `ore skeleton`, `ore toast`, `ore typing indicator`\n\n**inputs:** `ore button`, `ore calendar`, `ore checkbox`, `ore combobox`, `ore counter`, `ore datagrid`, `ore date picker`, `ore file input`, `ore input`, `ore message composer`, `ore number input`, `ore otp input`, `ore qr scanner`, `ore query bar`, `ore radio`, `ore rating`, `ore select`, `ore slider`, `ore switch`, `ore textarea`, `ore time picker`\n\n**layout:** `ore box`, `ore dock`, `ore grid`, `ore navbar`, `ore separator`, `ore sidebar`\n\n**navigation:** `ore breadcrumb`, `ore navigation menu`, `ore pagination`, `ore stepper`, `ore tabs`\n\n**overlay:** `ore command palette`, `ore dialog`, `ore drawer`, `ore menu`, `ore popover`, `ore spotlight`, `ore tooltip`, `ore tour`\n\n## component portfolio\n\nrefine keeps one public package and classifies components by composition level rather than stability. all listed components remain supported and tested.\n\n **foundations**: buttons, inputs, selection controls, accordions, dialogs, menus, tooltips, layout primitives, and feedback indicators. start here when building an application specific interface.\n **composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. these package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n **presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nclassification guides discovery and bundle selection. it is not a reason to remove working components or move them into unstable packages; per component subpath imports remain the tree shaking boundary.\n\n## features\n\n<div class=\"features grid\">\n\n **accessible**: keyboard navigation, aria wiring, and focus management across interactive components\n **themeable**: global tokens plus component level css custom properties\n **motion safe**: every animation routes through duration tokens and honors motion mode (`setmotionmode`) with a reduced motion floor\n **framework agnostic**: works anywhere html can be rendered\n **tree shakeable**: import only the component entry points you register\n **comprehensive surface**: inputs, content, navigation, feedback, layout, and overlay primitives\n **native form integration**: form associated controls submit values, validate supported required constraints, and reset with their form\n **typed framework declarations**: dom, react, and vue tags derive from the component property contracts\n\n</div>\n\n### prerequisites\n\n browser runtime with custom elements support.\n import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n for ssr, render placeholders server side and hydrate components only on the client.\n\n## documentation\n\n<div class=\"doc links\">\n\n [usage guide](./usage.md)\n [api reference](./api.md)\n [animation & motion](./animation.md)\n [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n [ore](/ore/): web component runtime that powers refine\n [orbit](/orbit/): floating ui positioning used in refine's overlays\n [forge](/forge/): form state management for use with refine inputs\n [keymap](/keymap/): keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<! markdownlint enable md025 md033 md060 >\n",
1060
+ "api": " \ntitle: 'refine: api reference'\ndescription: published component, stylesheet, framework type, and error entry points for @vielzeug/refine.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `@vielzeug/refine/<component>` | register one custom element and export its public types | sync | importing a type alone does not register the element |\n| `@vielzeug/refine/tokens.css` | load required theme tokens, animations, and cascade layers | css | import once before components render |\n| `@vielzeug/refine/fouc.css` | hide unregistered `ore *` elements until upgrade | css | load before first paint |\n| `@vielzeug/refine/styles/preflight.css` | apply the optional browser reset | css | the reset affects global elements |\n| `@vielzeug/refine/frameworks/elements` | register typed dom tag mappings | types only | import for side effects in typescript |\n| `@vielzeug/refine/frameworks/react` | register typed react jsx elements | types only | does not provide runtime wrappers |\n| `@vielzeug/refine/frameworks/vue` | register typed vue global components | types only | does not install a vue plugin |\n| `@vielzeug/refine/theme` | `createthemecontroller()`: light/dark/system document theme | sync | does not persist the preference or set an accent color |\n| `eventfieldvalue()` / `eventfieldchecked()` | read a form control's value/checked from `event.currenttarget` | sync | exported from the package root; guards non field targets |\n| `animatereflow()` | token driven flip reflow for keyed lists | async (next frame) | exported from the package root; elements need stable keys or it correctly does nothing |\n| `setmotionmode()` / `getmotionmode()` | read/write the `data motion` attribute on `<html>` | sync | exported from the package root; an unknown mode throws `rangeerror` |\n| `refineerror` | base class for package defined public errors | sync | component configuration warnings do not throw this error |\n\n## package entry point\n\n| import | purpose |\n| | |\n| `@vielzeug/refine` | export `registericons`, icon definition types, `refineerror`, `animatereflow`, the motion mode functions, and the field readers without registering components |\n| `@vielzeug/refine/<component>` | register one component and export its tag constant, props, events, and related types |\n| `@vielzeug/refine/theme` | `createthemecontroller()` and its theme types |\n| `@vielzeug/refine/tokens.css` | required global design contract |\n| `@vielzeug/refine/fouc.css` | optional pre upgrade visibility rule |\n| `@vielzeug/refine/styles/*` | focused theme, animation, layer, and preflight stylesheets |\n| `@vielzeug/refine/frameworks/*` | typescript augmentations for dom, react, and vue |\n\n## icon registration and adapters\n\n`registericons(icons: readonly<record<string, icondefinition>>): void` is available from `@vielzeug/refine/icons`, `@vielzeug/refine`, and `@vielzeug/refine/icon`. the common `icons` entry and root remain free of component registration side effects.\n\n`icondefinition`, `iconelement`, and `iconattributes` are exported from all three entries. shared definition and registration modules live in `src/icons/`, alongside adapters and internal svg helpers/defaults. definitions contain a numeric `viewbox` tuple, optional presentation attributes, and recursive svg children; they do not require a provider identity. invalid registrations throw the root exported `refineerror` atomically.\n\n| entry | export | purpose |\n| | | |\n| `@vielzeug/refine/icons` | `registericons`, `icondefinition`, `iconelement`, `iconattributes` | common library neutral registration and definition api |\n| `@vielzeug/refine/icons/lucide` | `lucideicons`, `lucideicondata` | pure adapter for selected structural lucide svg data |\n| `@vielzeug/refine/icons/lucide/all` | side effect registration | explicitly register the full installed lucide library |\n| `@vielzeug/refine/icons/heroicons` | `heroiconsicons`, `iconifyicon` | convert a caller named map of individual heroicons iconify data |\n| `@vielzeug/refine/icons/tabler` | `tablericons`, `iconifyicon` | convert a caller named map of individual tabler iconify data |\n| `@vielzeug/refine/icons/mdi` | `mdiicons`, `iconifyicon` | convert a caller named map of individual mdi iconify data |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyicons` | convert individual iconify data or selected/complete collections |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyalias`, `iconifycollection`, `iconifytransform` | structural data types; no iconify dependency required |\n\nlucide is an optional peer, not a mandatory dependency. only `icons/lucide/all` requires an installed `lucide` package; consumers selecting that entry declare it themselves. the structural `icons/lucide` adapter accepts supplied data without importing lucide.\n\nthe standalone iife exposes `registericons`, `lucideicons`, `heroiconsicons`, `tablericons`, `mdiicons`, `iconifyicon`, and `iconifyicons` under `refine.components.content`. neither the iife nor component entries import lucide. iconify conversion drops provider `class` metadata, validates finite numeric offsets and positive finite dimensions before transforms, and retains the strict svg allowlist. see the [icon reference](./components/icon.md) for presentation overrides, local svg id rewriting, supported families, and licenses.\n\nthe three family adapters share this signature:\n\n```ts\nheroiconsicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\ntablericons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\nmdiicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\n```\n\neach accepts individual iconify svg data, preserves input keys without adding a namespace, and returns definitions without registering them. they require `domparser`, preserve each icon's geometry/presentation/transforms, and throw `refineerror` for invalid iconify data. they do not accept react/vue components, collection json, or raw svg path strings. use `iconifyicons(collection, names?)` for collections and alias resolution.\n\n## styles\n\n```ts\nimport '@vielzeug/refine/fouc.css';\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n`tokens.css` is required. it defines tokens, animations, and cascade layer order without resetting global elements. `preflight.css` is optional and includes fouc suppression.\n\n| import path | purpose |\n| | |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | tokens, animation helpers, and cascade layers |\n| `@vielzeug/refine/styles/theme.css` | theme token declarations |\n| `@vielzeug/refine/styles/animation.css` | animation helpers |\n| `@vielzeug/refine/styles/layers.css` | cascade layer declarations |\n| `@vielzeug/refine/styles/preflight.css` | optional browser reset and fouc suppression |\n\n## components\n\neach component uses one registration and type entry point:\n\n```ts\nimport '@vielzeug/refine/button';\nimport type { orebuttonprops } from '@vielzeug/refine/button';\n```\n\n| area | components |\n| | |\n| content | `accordion`, `avatar`, `card`, `carousel`, `chat message`, `chat panel`, `code window`, `copy command`, `icon`, `keyboard key`, `list`, `marquee`, `qr code`, `rank list`, `speech player`, `speed reading`, `stats`, `table`, `text` |\n| feedback | `alert`, `async`, `badge`, `chip`, `cookie banner`, `password strength`, `progress`, `skeleton`, `toast`, `typing indicator` |\n| inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date picker`, `file input`, `input`, `message composer`, `number input`, `otp input`, `qr scanner`, `query bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time picker` |\n| layout | `box`, `dock`, `grid`, `navbar`, `separator`, `sidebar` |\n| navigation | `breadcrumb`, `navigation menu`, `pagination`, `stepper`, `tabs` |\n| overlay | `command palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |\n\neach row lists the entry points that own a documentation page. sub element entries (`accordion item`, `tab item`, `avatar group`, `list item`, `step`, and the rest) are documented on their parent's page and share its category.\n\neach component page lists its attributes, javascript properties, events, slots, parts, and css custom properties.\n\nthe [`query bar`](./components/query bar.md) entry also exports `querystate`, `querytokendef`, `queryquickfilter`, `querybarlabels`, and pure grammar helpers. vocabulary entries default to single selection; `selection: 'multiple'` allows distinct values for the same key. `anylabel` customizes the unrestricted single selection choice, such as “default order” for sorting. options accept an optional `icon` (registered `ore icon` name), displayed beside their labels in the drawer. `tokenvalues(state, key)` reads all values, `removetoken(state, token)` removes an exact pair, and `cleartokens(state, key)` clears a group. its unified field contains applied filters, with a compact secondary row for filter entry, quick toggles, and a `toolbar end` slot for application content such as a result count. drawer selection uses the same state and vocabulary as typed suggestions. pending edits block incidental backdrop/swipe dismissal; explicit cancel, close, and escape discard them. search hidden selections remain visible in a summary.\n\n## framework types\n\n```ts\nimport type {} from '@vielzeug/refine/frameworks/elements';\nimport type {} from '@vielzeug/refine/frameworks/react';\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\nthe declarations cover every supported tag and derive component properties from refine's authoritative `htmlelementtagnamemap`. they provide types only; component registration still uses component subpaths.\n\n## events and form controls\n\nform controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. read the property from `event.currenttarget`.\n\nfinite choice properties use ore's `prop.oneof()` parsing: values outside a component's documented options resolve to\nthe declared default, or `undefined` when no default is declared.\n\nform associated controls participate in native form submission, validity checks, and reset. a named control's value\nis available through `new formdata(form)`, and supported `required` constraints affect `form.checkvalidity()`,\n`form.reportvalidity()`, and submit blocking. the `error` property renders and announces feedback; it does not by\nitself set native constraint validity.\n\nstateful overlays expose controlled `open`, optional `default open`, and an `open change` custom event with `{ open, reason }` detail. component pages define additional detail fields and reasons.\n\n## utilities\n\n### `createthemecontroller(options?)`\n\n```ts\nimport { createthemecontroller } from '@vielzeug/refine/theme';\n\nconst theme = createthemecontroller(); // starts in 'system' mode\ntheme.setpreference('dark');\ntheme.dispose();\n```\n\nowns the light/dark/system theme for the document: a reactive `preference` signal, the effective `resolved` mode (`'dark' | 'light'` after resolving `system` against the os), and the dom application `styles/theme.css` expects: the `.dark` class plus the `color scheme` property on the root element, so every `light dark()` token resolves to the right branch. while in `system` mode the controller tracks the os `prefers color scheme` via sentinel's `createmediaquery`.\n\nthe controller does **not** persist the preference or expose an accent color: those are consumer concerns (wire `watch(controller.preference, save)` for persistence; set ` color primary hue` yourself). options: `initial` (starting preference, default `'system'`), `root` (element carrying the classes, default `document.documentelement`), `target` (window whose `matchmedia` backs `system`). the handle is disposable: `dispose()`, `disposed`, `disposalsignal`, `[symbol.dispose]`.\n\n### `eventfieldvalue(event)` / `eventfieldchecked(event)`\n\n```ts\nimport { eventfieldchecked, eventfieldvalue } from '@vielzeug/refine';\n\ninput.addeventlistener('input', (event) => {\n const value = eventfieldvalue(event); // string | undefined: never a blind cast\n});\n```\n\nguarded readers for the standard `input`/`change` event pattern above: they read `value`/`checked` from `event.currenttarget` only when the target actually carries it, so a handler wired to the wrong element yields `undefined`/`false` instead of a crash or a lie. exported from the package root, which registers no components.\n\n \n\n### `animatereflow(host, signal, options)`\n\n```ts\nimport { animatereflow } from '@vielzeug/refine';\n\nconst reflow = animatereflow(list, abortcontroller.signal, {\n elements: () => [...list.queryselectorall('li')],\n getkey: (item) => item.dataset.id,\n});\nreflow.run(() => renderitems(nextitems));\n```\n\ntoken driven flip reflow for keyed lists: captures the current layout, runs `mutate`, then animates the tracked elements into their new positions on the next frame. the same helper the datagrid, command palette, and toast stack use.\n\n| parameter | type | description |\n| | | |\n| `host` | `htmlelement` | element whose computed style carries the timing tokens |\n| `signal` | `abortsignal` | aborting cancels in flight animations |\n| `options.elements` | `() => htmlelement[]` | tracked elements, read live on both sides of the mutation |\n| `options.getkey` | `(el) => string \\| undefined` | stable identity per element; all or nothing |\n| `options.durationtoken` | `string?` | duration token, default `' duration 200'` |\n| `options.easingtoken` | `string?` | easing token, default `' ease move'` |\n| `options.stagger` | `number?` | per element delay in ms, default `0` |\n\n**returns** a `reflow` handle with one method: `run(mutate)` (sync; the animation is fire and forget). timing is read from the tokens at animation time, so motion mode reduction skips the reflow instead of playing it instantly. every path that cannot animate (no elements, missing keys, zeroed tokens, aborted signal, no web animations api) still runs `mutate` exactly once and never throws. see [animation & motion → list reflow](./animation#list reflow animatereflow) for behavior details.\n\n \n\n### `setmotionmode(mode)` / `getmotionmode()`\n\n```ts\nimport { getmotionmode, setmotionmode } from '@vielzeug/refine';\n\nsetmotionmode('reduced'); // returns the applied mode\n```\n\nread/write the `data motion` attribute on `<html>` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). an unknown mode throws `rangeerror`. the attribute drives the token layer: see [animation & motion → motion mode](./animation#motion mode).\n\n## types\n\ncomponent props follow the `ore<component>props` naming pattern. event maps follow `ore<component>events`. import both from the component subpath that owns them.\n\n`refineelementmap`, `refinereactintrinsicelements`, and `refinevueglobalcomponents` are exported from their respective `frameworks/*` type entry points.\n\nthe package root also exports `reflow` (the `run()` handle), `reflowoptions` (its options object), and `motionmode` (`'full' | 'reduced' | 'system'`).\n\n## errors\n\n### `refineerror`\n\n```ts\nclass refineerror extends error {\n constructor(message: string, opts?: erroroptions);\n}\n```\n\nbase class for public refine errors. it preserves `cause` through `erroroptions`.\n",
1061
1061
  "usage": " \ntitle: 'refine: usage guide'\ndescription: register refine components, configure properties, handle events, compose slots, and integrate frameworks.\n \n\n[[toc]]\n\n## basic usage\n\nload the global design contract once, then register only the components used by the page.\n\n```ts\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/dialog';\n\nconst input = document.queryselector('ore input');\nconst save = document.queryselector('ore button');\n\nif (!(input instanceof htmlelement) || !(save instanceof htmlelement)) {\n throw new error('expected refine controls');\n}\n\nsave.addeventlistener('click', () => {\n console.log((input as htmlelement & { value: string }).value);\n});\n```\n\nadd the browser reset only when the application owns global element styling:\n\n```ts\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n## choose an icon library\n\nrefine includes only its internal component icons. register application icons before mounting them: use `registericons` and neutral `icondefinition` data from `@vielzeug/refine/icons`, the pure `@vielzeug/refine/icons/lucide` adapter for selected lucide icons, or `@vielzeug/refine/icons/iconify` for local heroicons, tabler, and material design icons data. keep importing the component from `@vielzeug/refine/icon`. lucide is an optional peer: install `lucide` yourself only when choosing its data or `@vielzeug/refine/icons/lucide/all`; core and structural adapters do not require it. the [icon reference](./components/icon.md) covers imports, licenses, and presentation behavior.\n\nfor selected individual iconify data, use `heroiconsicons`, `tablericons`, or `mdiicons` from `@vielzeug/refine/icons/heroicons`, `/tabler`, or `/mdi`. for example, `registericons(heroiconsicons({ search, home }))` preserves your app keys. install the matching `@iconify icons/<family>` data package yourself; these helpers do not accept framework components. keep `iconifyicons` for collection json and aliases.\n\n## set attributes and properties\n\nuse attributes for serializable html state.\n\n```html\n<ore button variant=\"outline\" color=\"secondary\" size=\"lg\" disabled>\n save changes\n</ore button>\n```\n\nuse javascript properties for arrays, objects, callbacks, and controlled state.\n\n```ts\nimport '@vielzeug/refine/datagrid';\nimport type { oredatagridprops } from '@vielzeug/refine/datagrid';\n\nconst grid = document.queryselector('ore datagrid') as htmlelement & oredatagridprops;\ngrid.columns = [\n { key: 'name', label: 'name', sortable: true },\n { key: 'role', label: 'role' },\n];\ngrid.rows = [\n { id: '1', name: 'ada', role: 'admin' },\n { id: '2', name: 'linus', role: 'editor' },\n];\n```\n\nenumerated properties such as `variant`, `size`, and `color` accept the values listed on each component's reference\npage. an unsupported value resolves to the property's declared default (or `undefined` when it has no default).\n\nin an ore template, `model()` can bind a refine field's `value` to a ripple signal and write user input back:\n\n```ts\nimport { signal } from '@vielzeug/ripple';\nimport { html, model } from '@vielzeug/ore';\nimport '@vielzeug/refine/input';\n\nconst email = signal('');\nconst field = html`<ore input label=\"email\" type=\"email\" value=${model(email)} />`;\n```\n\n## handle events\n\nform controls dispatch standard `input` and `change` events. read their current property from `event.currenttarget`.\n\n```ts\nconst input = document.queryselector('ore input');\ninput?.addeventlistener('input', (event) => {\n const target = event.currenttarget as htmlelement & { value: string };\n console.log(target.value);\n});\n```\n\ncustom events use kebab case names and typed detail objects.\n\n```ts\nimport type { oredialogevents } from '@vielzeug/refine/dialog';\n\nconst dialog = document.queryselector('ore dialog');\ndialog?.addeventlistener('open change', (event: customevent<oredialogevents['open change']>) => {\n console.log(event.detail.open, event.detail.reason);\n});\n```\n\n## native form validation\n\nrefine's form associated controls integrate with native form submission, `formdata`, validity checks, and reset.\nuse `required` for a required value constraint; setting `error` displays and announces feedback but does not, by\nitself, invalidate the form.\n\n```html\n<form id=\"profile form\">\n <ore input name=\"email\" type=\"email\" label=\"email\" required></ore input>\n <ore select name=\"role\" label=\"role\" required>\n <option value=\"\">choose a role…</option>\n <option value=\"editor\">editor</option>\n <option value=\"admin\">admin</option>\n </ore select>\n <ore button type=\"submit\">save</ore button>\n</form>\n\n<script type=\"module\">\n import '@vielzeug/refine/input';\n import '@vielzeug/refine/select';\n import '@vielzeug/refine/button';\n\n const form = document.queryselector('#profile form');\n form.addeventlistener('submit', (event) => {\n event.preventdefault();\n console.log(new formdata(form).get('email'));\n });\n</script>\n```\n\nthe browser runs native validation before dispatching `submit`. call `form.reportvalidity()` to show validation\nfeedback directly, or `form.checkvalidity()` for a boolean check without the browser's validation ui.\n\n## compose slots\n\ndefault slots hold primary content. named slots identify component owned regions.\n\n```html\n<ore card>\n <span slot=\"header\">account</span>\n <p>profile settings</p>\n <div slot=\"footer\">\n <ore button variant=\"ghost\">cancel</ore button>\n <ore button>save</ore button>\n </div>\n</ore card>\n```\n\ninput components commonly expose `prefix`, `suffix`, `label`, `helper`, and `error` slots. each component reference lists its supported slots.\n\n## load typescript framework declarations\n\nimport the declaration matching the framework once in an application type entry point.\n\n::: code group\n\n```ts [dom]\nimport type {} from '@vielzeug/refine/frameworks/elements';\n```\n\n```ts [react]\nimport type {} from '@vielzeug/refine/frameworks/react';\n```\n\n```ts [vue]\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\n:::\n\nthese entry points provide typed tags and component properties. they do not register components or install runtime adapters.\n\n## framework integration\n\nrefine elements use native dom properties, events, and slots. frameworks differ only in how they forward custom element properties and events.\n\n::: code group\n\n```tsx [react 19]\nimport '@vielzeug/refine/button';\n\nexport function savebutton() {\n return <ore button variant=\"solid\">save</ore button>;\n}\n```\n\n```vue [vue 3]\n<script setup lang=\"ts\">\nimport '@vielzeug/refine/button';\n</script>\n\n<template>\n <ore button variant=\"solid\">save</ore button>\n</template>\n```\n\n```svelte [svelte]\n<script lang=\"ts\">\n import '@vielzeug/refine/button';\n</script>\n\n<ore button variant=\"solid\">save</ore button>\n```\n\n:::\n\nsee [framework integration](./frameworks.md) for custom events, controlled properties, ssr guards, and framework specific configuration.\n\n## working with other vielzeug libraries\n\n### ore\n\nuse ore when authoring a custom element that composes refine components.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { define, html } from '@vielzeug/ore';\n\ndefine('save panel', {\n setup() {\n return html`<ore button @click=${() => console.log('save')}>save</ore button>`;\n },\n});\n```\n\n### ripple\n\nuse ripple to drive component properties from application state.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { effect, signal } from '@vielzeug/ripple';\n\nconst loading = signal(false);\nconst button = document.queryselector('ore button') as htmlelement & { loading?: boolean };\nconst loadingeffect = effect(() => {\n button.loading = loading.value;\n});\n\nloadingeffect.dispose();\n```\n\n### necromancer\n\nuse necromancer directly when you need animation handles, groups, or explicit keyframes. refine's [`animatereflow`](./animation#list reflow animatereflow) is the token driven wrapper over its flip primitive and is enough for keyed lists that reflow.\n\n## best practices\n\n **import** `tokens.css` once before rendering components.\n **register** components through explicit subpaths.\n **set** structured data and callbacks as javascript properties.\n **read** form state from the event target instead of custom event payloads.\n **provide** accessible labels for icon only controls.\n **use** component reference pages for supported slots, parts, and css properties.\n **dispose** application owned ripple effects and service handles.\n **guard** dom dependent component registration during ssr.\n **working with ai agents?** install the `vielzeug` skill (`npx y @vielzeug/codex skills install`) so agents reach for refine components and tokens instead of custom widgets: see the [codex usage guide](../codex/usage.md#agent skill).\n"
1062
1062
  },
1063
1063
  "examples": [],
1064
- "exports": "ore accordion ore accordion item ore alert ore async ore avatar ore avatar group ore badge ore box ore breadcrumb ore breadcrumb item ore button ore button group ore calendar ore card ore carousel ore carousel slide ore chat message ore checkbox ore checkbox group ore chip ore code window ore column ore combobox ore combobox option ore command palette ore command palette item ore cookie banner ore copy command ore counter ore datagrid ore date picker ore dialog ore drawer ore file input ore grid ore grid item ore icon ore input ore keyboard key ore keyboard shortcut ore list ore list item ore marquee ore menu ore menu item ore menu separator ore message composer ore navbar ore navbar item ore navigation menu ore navigation menu item ore navigation menu panel ore number input ore otp input ore pagination ore password strength ore popover ore progress ore qr code ore qr scanner ore query bar ore radio ore radio group ore rating ore select ore separator ore sidebar ore sidebar group ore sidebar item ore skeleton ore slider ore speech player ore speed reading ore spotlight ore stats ore step ore stepper ore switch ore tab item ore tab panel ore table ore tabs ore td ore text ore th ore tr ore textarea ore time picker ore toast ore tooltip ore tour ore typing indicator",
1064
+ "exports": "ore accordion ore accordion item ore alert ore async ore avatar ore avatar group ore badge ore box ore breadcrumb ore breadcrumb item ore button ore button group ore calendar ore card ore carousel ore carousel slide ore chat message ore checkbox ore checkbox group ore chip ore code window ore column ore combobox ore combobox option ore command palette ore command palette item ore cookie banner ore copy command ore counter ore datagrid ore date picker ore dialog ore dock ore drawer ore file input ore grid ore grid item ore icon ore input ore keyboard key ore keyboard shortcut ore list ore list item ore marquee ore menu ore menu item ore menu separator ore message composer ore navbar ore navbar item ore navigation menu ore navigation menu item ore navigation menu panel ore number input ore otp input ore pagination ore password strength ore popover ore progress ore qr code ore qr scanner ore query bar ore radio ore radio group ore rating ore select ore separator ore sidebar ore sidebar group ore sidebar item ore skeleton ore slider ore speech player ore speed reading ore spotlight ore stats ore step ore stepper ore switch ore tab item ore tab panel ore table ore tabs ore td ore text ore th ore tr ore textarea ore time picker ore toast ore tooltip ore tour ore typing indicator",
1065
1065
  "keywords": "web components accessible themeable ui components design system",
1066
1066
  "name": "@vielzeug/refine",
1067
1067
  "related": "ore orbit forge keymap",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vielzeug/codex",
3
- "version": "26.11.0",
3
+ "version": "26.11.2",
4
4
  "description": "MCP server exposing all Vielzeug docs to AI clients",
5
5
  "repository": {
6
6
  "type": "git",
@@ -63,7 +63,7 @@
63
63
  },
64
64
  "devDependencies": {
65
65
  "@types/node": "^26.6.5",
66
- "@vielzeug/refine": "26.11.0",
66
+ "@vielzeug/refine": "26.11.2",
67
67
  "typescript": "^6.0.3",
68
68
  "vitest": "^5.0.5"
69
69
  }