@vielzeug/codex 26.11.2 → 26.11.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/data/catalog.json +45 -44
- package/data/llms-full.txt +180 -111
- package/data/llms.txt +1 -1
- package/data/manifest.json +1 -1
- package/data/packages/codex.json +8 -9
- package/data/packages/necromancer.json +5 -5
- package/data/packages/refine.json +2 -2
- package/data/refine.json +395 -149
- package/data/search.json +12 -12
- package/dist/catalog.d.ts +14 -14
- package/dist/catalog.js +27 -14
- package/dist/catalog.js.map +1 -1
- package/dist/cli.js +3 -8
- package/dist/cli.js.map +1 -1
- package/dist/http.d.ts +3 -6
- package/dist/http.js +2 -12
- package/dist/http.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/refine-catalog.d.ts +3 -2
- package/dist/refine-catalog.js +7 -4
- package/dist/refine-catalog.js.map +1 -1
- package/dist/refine.d.ts +5 -10
- package/dist/refine.js +7 -10
- package/dist/refine.js.map +1 -1
- package/dist/server.d.ts +6 -7
- package/dist/server.js +6 -7
- package/dist/server.js.map +1 -1
- package/dist/snapshot.d.ts +5 -5
- package/dist/tools/refine.d.ts +0 -2
- package/dist/tools/refine.js +0 -4
- package/dist/tools/refine.js.map +1 -1
- package/dist/types.d.ts +78 -78
- package/package.json +2 -2
- package/skills/vielzeug/SKILL.md +15 -13
package/data/search.json
CHANGED
|
@@ -259,18 +259,18 @@
|
|
|
259
259
|
"category": "ai",
|
|
260
260
|
"description": "local mcp access to vielzeug documentation and package metadata.",
|
|
261
261
|
"docs": {
|
|
262
|
-
"index": " \ntitle: codex\ndescription: local mcp access to vielzeug documentation and package metadata.\npackage: codex\ncategory: ai\nkeywords: [mcp, docs, ai]\nrelated: [refine]\nexports: [loadsnapshot, snapshotcatalog, createmcpserver, starthttphost, stdioservertransport, catalogerror, codexerror]\nenvironments: [node]\n \n\n<packagehero package=\"codex\" />\n\n## why codex?\n\ncodex exposes current vielzeug catalog data through mcp without scanning source at request time.\n\n## installation\n\n```sh\npnpm add @vielzeug/codex\n```\n\n## quick start\n\n```sh\nnpx y @vielzeug/codex\n```\n\n## features\n\n `loadsnapshot` validates chunked snapshot metadata.\n `snapshotcatalog` loads package content only when requested.\n `createmcpserver` registers generic package tools; `/refine` adds component tools explicitly.\n root and `/refine` entry points publish typescript declarations.\n `starthttphost` enforces loopback binding plus localhost host and origin validation.\n\n## documentation\n\n [usage](./usage.md)\n [api](./api.md)\n [examples](./examples.md)\n [migration guide](./migration.md)\n\n## see also\n\n [refine](../refine/) provides component metadata bundled by codex.\n",
|
|
263
|
-
"api": " \ntitle: codex api\ndescription: snapshot, catalog, mcp server, and local http host apis.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `loadsnapshot` | read validated snapshot metadata | sync | content chunks load lazily |\n| `snapshotcatalog` | query package corpus | sync | construct from loaded snapshot |\n| `createmcpserver` | mcp adapter factory (generic tools) | sync | requires catalog and version |\n| `
|
|
264
|
-
"usage": " \ntitle: 'codex: usage guide'\ndescription: install, connect, develop, and debug the vielzeug mcp server.\n \n\n[[toc]]\n\n## basic usage\n\nrun local stdio server:\n\n```sh\nnpx y @vielzeug/codex\n```\n\nuse shipped `mcp setup.json` for machine readable generic configuration. client specific configuration must use its documented mcp format.\n\n## http mode\n\nhttp uses streamable http and binds loopback only:\n\n```sh\nnpx y @vielzeug/codex port=3100\ncurl http://127.0.0.1:3100/health\n```\n\nresponse includes snapshot version. runtime bind validation and host/origin allowlists restrict access to localhost; no remote host mode exists. programmatic `
|
|
262
|
+
"index": " \ntitle: codex\ndescription: local mcp access to vielzeug documentation and package metadata.\npackage: codex\ncategory: ai\nkeywords: [mcp, docs, ai]\nrelated: [refine]\nexports: [loadsnapshot, snapshotcatalog, createmcpserver, createmcpserverwithrefine, starthttphost, stdioservertransport, catalogerror, codexerror]\nenvironments: [node]\n \n\n<packagehero package=\"codex\" />\n\n## why codex?\n\ncodex exposes current vielzeug catalog data through mcp without scanning source at request time.\n\n## installation\n\n```sh\npnpm add @vielzeug/codex\n```\n\n## quick start\n\n```sh\nnpx y @vielzeug/codex\n```\n\n## features\n\n `loadsnapshot` validates chunked snapshot metadata.\n `snapshotcatalog` loads package content only when requested.\n `createmcpserver` registers generic package tools; `/refine` adds component tools explicitly.\n root and `/refine` entry points publish typescript declarations.\n `starthttphost` enforces loopback binding plus localhost host and origin validation.\n\n## documentation\n\n [usage](./usage.md)\n [api](./api.md)\n [examples](./examples.md)\n [migration guide](./migration.md)\n\n## see also\n\n [refine](../refine/) provides component metadata bundled by codex.\n",
|
|
263
|
+
"api": " \ntitle: codex api\ndescription: snapshot, catalog, mcp server, and local http host apis.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `loadsnapshot` | read validated snapshot metadata | sync | content chunks load lazily |\n| `snapshotcatalog` | query package corpus | sync | construct from loaded snapshot |\n| `createmcpserver` | mcp adapter factory (generic tools) | sync | requires catalog and version |\n| `createmcpserverwithrefine` | mcp adapter factory (all package and refine tools) | sync | import from `@vielzeug/codex/refine` |\n| `starthttphost` | loopback streamable http host | async | http remains local only |\n\n## package entry points\n\n| import | purpose |\n| | |\n| `@vielzeug/codex` | `catalog`, `snapshotcatalog`, `loadsnapshot`, mcp server, and http host |\n| `@vielzeug/codex/refine` | refine catalog and mcp server with component tools |\n\n## snapshot\n\n### `loadsnapshot`\n\n```ts\nloadsnapshot(snapshotroot?: string, options?: { validatecontents?: boolean }): loadedsnapshot;\n```\n\nloads catalog/search metadata and refine metadata. `snapshotroot` defaults to bundled `data/`. package content chunks stay lazy unless `validatecontents: true`, which validates every package content chunk during loading.\n\n### `snapshotcatalog`\n\n```ts\nnew snapshotcatalog(snapshot: loadedsnapshot)\n```\n\nprovides generic package lookup, docs/source/example/signature access, and deterministic search. use `snapshotrefinecatalog` from `/refine` when component methods are needed.\n\n \n\n## mcp\n\n### `createmcpserver`\n\n```ts\ncreatemcpserver(catalog: catalog, options: { version: string; debug?: boolean }): server;\n```\n\nregisters generic package tools over `catalog`. refine tools are opt in through `/refine`. the root also re exports `stdioservertransport` for connecting the server without a second package import.\n\n## refine tools (`@vielzeug/codex/refine`)\n\n### `createmcpserverwithrefine`\n\n```ts\ncreatemcpserverwithrefine(catalog: refinecatalog, options: { version: string; debug?: boolean }): server;\n```\n\ncreates a server with the general vielzeug package catalog tools and the additional `refine *` component tools.\n\n### `snapshotrefinecatalog`\n\n```ts\nnew snapshotrefinecatalog(snapshot: loadedsnapshot)\n```\n\nextends `snapshotcatalog` with `getcomponent()` and `listcomponents()`.\n\ncomponent declarations and their nested data use readonly typescript types.\n\n## http\n\n### `starthttphost`\n\n```ts\nstarthttphost(options: httphostoptions): promise<httphost>;\n```\n\nstarts streamable http on `127.0.0.1` by default. runtime validation accepts only `127.0.0.1` or `::1`; every request must also pass localhost host and origin checks. `createserver` must return a fresh, unconnected server with its request handlers registered.\n\n## types\n\n```ts\ninterface snapshotpointer {\n readonly directory: string;\n}\n\ninterface snapshotmanifest {\n readonly catalog: 'catalog.json';\n readonly contentdirectory: 'packages';\n readonly refine: 'refine.json' | null;\n readonly schemaversion: typeof snapshot_schema_version;\n readonly search: 'search.json';\n readonly version: string;\n}\n```\n\ndev snapshots use `snapshotpointer` (via `current.json`); published snapshots are static directories.\n\n```ts\ninterface loadedsnapshot {\n readonly catalog: catalogfile;\n readonly contentdirectory: string;\n readonly manifest: snapshotmanifest;\n readonly refinecomponents: readonly cemdeclaration[];\n readonly search: readonly searchrecord[];\n}\n```\n\n```ts\ninterface catalogfile {\n readonly packages: readonly packagemeta[];\n readonly version: string;\n}\n\ninterface searchrecord {\n readonly category: string;\n readonly description: string;\n readonly docs: readonly<partial<record<docpage, string>>>;\n readonly examples: readonly { readonly id: string; readonly text: string }[];\n readonly exports: string;\n readonly keywords: string;\n readonly name: string;\n readonly related: string;\n readonly slug: string;\n readonly source: string | null;\n}\n\ninterface packagemeta {\n readonly availabledocpages: readonly docpage[];\n readonly category: string;\n readonly description: string;\n readonly exampleids: readonly string[];\n readonly exports: readonly string[];\n readonly hassource: boolean;\n readonly keywords: readonly string[];\n readonly name: string;\n readonly related: readonly string[];\n readonly slug: string;\n readonly version: string;\n}\n\ninterface example {\n readonly code: string;\n readonly id: string;\n readonly name: string;\n}\n```\n\n```ts\ninterface catalog {\n getdocs(slug: string, page: docpage): string;\n getexample(slug: string, exampleid: string): example;\n getpackage(slug: string): packagemeta;\n getsource(slug: string): string;\n gettypesignature(slug: string, symbol: string): string;\n listexamples(slug: string): readonly pick<example, 'id' | 'name'>[];\n listpackages(): readonly packagemeta[];\n search(query: string): readonly searchhit[];\n}\n\ninterface refinecatalog extends catalog {\n getcomponent(tagname: string): cemdeclaration;\n listcomponents(): readonly cemdeclaration[];\n}\n\ninterface searchhit {\n readonly matchedexamples?: readonly string[];\n readonly matchedin: readonly ('docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source')[];\n readonly matchedpages?: readonly docpage[];\n readonly name: string;\n readonly slug: string;\n}\n```\n\ncatalog exposes semantic reads. it does not expose its cached content chunks.\n\n```ts\ninterface httphost {\n readonly disposalsignal: abortsignal;\n dispose(): promise<void>;\n readonly disposed: boolean;\n readonly host: string;\n readonly port: number;\n [symbol.asyncdispose](): promise<void>;\n}\n\ninterface httphostoptions {\n createserver: () => server;\n host?: '127.0.0.1' | '::1';\n port: number;\n version: string;\n}\n```\n\n```ts\nconst doc_pages = ['index', 'api', 'usage', 'examples'] as const;\ntype docpage = (typeof doc_pages)[number];\n\nconst snapshot_schema_version = 1 as const;\n```\n\ncem types and `refinecatalog` are exported from `/refine`.\n\n```ts\ninterface cemdeclaration {\n readonly attributes?: readonly cemattribute[];\n readonly cssparts?: readonly cemcsspart[];\n readonly cssproperties?: readonly cemcssproperty[];\n readonly description?: string;\n readonly events?: readonly cemevent[];\n readonly members?: readonly cemmember[];\n readonly name?: string;\n readonly slots?: readonly cemslot[];\n readonly superclass?: { readonly name: string; readonly package?: string };\n readonly tagname?: string;\n readonly [key: string]: unknown;\n}\n\ninterface cemattribute {\n readonly default?: string;\n readonly description?: string;\n readonly fieldname?: string;\n readonly name: string;\n readonly type?: { readonly text: string };\n}\n\ninterface cemcsspart {\n readonly description?: string;\n readonly name: string;\n}\n\ninterface cemcssproperty {\n readonly default?: string;\n readonly description?: string;\n readonly name: string;\n}\n\ninterface cemevent {\n readonly description?: string;\n readonly name: string;\n readonly type?: { readonly text: string };\n}\n\ninterface cemmember {\n readonly description?: string;\n readonly kind?: 'field' | 'method';\n readonly name: string;\n readonly type?: { readonly text: string };\n}\n\ninterface cemslot {\n readonly description?: string;\n readonly name: string;\n}\n```\n\n## errors\n\n`codexerror` signals malformed snapshots or host failures. `catalogerror` adds `invalid_arg`, `not_found`, or `unavailable` for expected tool failures.\n",
|
|
264
|
+
"usage": " \ntitle: 'codex: usage guide'\ndescription: install, connect, develop, and debug the vielzeug mcp server.\n \n\n[[toc]]\n\n## basic usage\n\nrun local stdio server:\n\n```sh\nnpx y @vielzeug/codex\n```\n\nuse shipped `mcp setup.json` for machine readable generic configuration. client specific configuration must use its documented mcp format.\n\n## http mode\n\nhttp uses streamable http and binds loopback only:\n\n```sh\nnpx y @vielzeug/codex port=3100\ncurl http://127.0.0.1:3100/health\n```\n\nresponse includes snapshot version. runtime bind validation and host/origin allowlists restrict access to localhost; no remote host mode exists. programmatic http hosting takes a `createserver` factory that returns a fresh, unconnected server with its request handlers registered. dispose the host asynchronously and observe `disposed` or `disposalsignal` when coordinating shutdown.\n\n## agent skill\n\ncodex ships a `vielzeug` agent skill: a `skill.md` that tells an ai agent working in *your* project to discover packages through the mcp tools instead of guessing, to use the owning `@vielzeug/*` package instead of hand rolling, and to build ui from refine components, tokens, and theme whenever `@vielzeug/refine` is installed. install it into the project:\n\n```sh\nnpx y @vielzeug/codex skills install\nnpx y @vielzeug/codex skills install target=.claude/skills\nnpx y @vielzeug/codex skills install force # overwrite an existing copy\n```\n\nwithout ` target`, the first existing directory among `.agents/skills`, `.github/skills`, and `.claude/skills` is used; when none exists, `.agents/skills` is created. the command refuses to overwrite an installed skill unless ` force` is passed. rerun after upgrading codex to pick up the current package list, which is generated from the published manifests. the skill pairs with the mcp server: its lookups (`get docs`, `refine get component`, `refine validate usage`, …) assume codex is connected, and it documents `node_modules` fallbacks for when it is not.\n\n## local development\n\nrequires node 22+ and root setup:\n\n```sh\npnpm setup\ncd packages/codex\npnpm test:unit\npnpm test:integration\npnpm dev\n```\n\n`test:unit` uses fixtures only. `test:integration` regenerates a current snapshot then checks real monorepo inputs.\n\n`pnpm dev` watches documentation and package inputs, atomically publishes snapshots, then restarts server when snapshot changes.\n\n## debugging\n\n```sh\npnpm dev\nnode src/cli.ts port=3100 debug\ncurl http://127.0.0.1:3100/health\n```\n\n` debug` logs tool durations and expected catalog errors to stderr. build `@vielzeug/refine` before generating snapshot when component metadata changes.\n\n## programmatic usage\n\n```ts\nimport { snapshotcatalog, stdioservertransport, createmcpserver, loadsnapshot } from '@vielzeug/codex';\n\nconst snapshot = loadsnapshot();\nconst catalog = new snapshotcatalog(snapshot);\nawait createmcpserver(catalog, { version: snapshot.manifest.version }).connect(new stdioservertransport());\n```\n\nto include refine component tools, create a server with the `@vielzeug/codex/refine` subpath:\n\n```ts\nimport { stdioservertransport, loadsnapshot } from '@vielzeug/codex';\nimport { createmcpserverwithrefine, snapshotrefinecatalog } from '@vielzeug/codex/refine';\n\nconst snapshot = loadsnapshot();\nconst catalog = new snapshotrefinecatalog(snapshot);\nconst server = createmcpserverwithrefine(catalog, { version: snapshot.manifest.version });\nawait server.connect(new stdioservertransport());\n```\n\n## best practices\n\n use `search packages` for capability discovery before loading broad source.\n use `get type signature` before loading full source.\n published package snapshots are static directories; local dev snapshots are immutable generations selected by `.dev/current.json`.\n pass `validatecontents: true` to `loadsnapshot()` for artifact verification; normal startup keeps package chunks lazy.\n return a fresh configured server from `starthttphost`'s `createserver` factory.\n keep http local. use stdio for normal client integration.\n run `pnpm test:unit` before `pnpm test:integration`.\n",
|
|
265
265
|
"examples": " \ntitle: 'codex: examples'\ndescription: practical mcp tool call examples for package discovery, docs lookup, and refine component queries.\n \n\n## examples\n\n [listing packages](./examples/listing packages.md)\n [searching packages](./examples/searching packages.md)\n [package metadata](./examples/package metadata.md)\n [reading docs](./examples/reading docs.md)\n [running repl examples](./examples/running repl examples.md)\n [looking up components](./examples/looking up components.md)\n [inspector](./examples/inspector.md)\n"
|
|
266
266
|
},
|
|
267
267
|
"examples": [],
|
|
268
|
-
"exports": "loadsnapshot snapshotcatalog createmcpserver starthttphost stdioservertransport catalogerror codexerror",
|
|
268
|
+
"exports": "loadsnapshot snapshotcatalog createmcpserver createmcpserverwithrefine starthttphost stdioservertransport catalogerror codexerror",
|
|
269
269
|
"keywords": "mcp docs ai",
|
|
270
270
|
"name": "@vielzeug/codex",
|
|
271
271
|
"related": "refine",
|
|
272
272
|
"slug": "codex",
|
|
273
|
-
"source": "/**\n * `@vielzeug/codex`: supported public contract.\n *\n * exposes the generic catalog, snapshot loader, errors, and server hosts.\n * refine catalog types and tools live behind `@vielzeug/codex/refine`.\n */\nexport { stdioservertransport } from '@modelcontextprotocol/server/stdio';\nexport { type catalog, catalogerror, type searchhit, snapshotcatalog } from './catalog.js';\nexport { codexerror } from './errors.js';\nexport { type httphost, type httphostoptions, starthttphost } from './http.js';\nexport { createmcpserver } from './server.js';\nexport { type loadedsnapshot, loadsnapshot } from './snapshot.js';\nexport type {\n docpage,\n example,\n
|
|
273
|
+
"source": "/**\n * `@vielzeug/codex`: supported public contract.\n *\n * exposes the generic catalog, snapshot loader, errors, and server hosts.\n * refine catalog types and tools live behind `@vielzeug/codex/refine`.\n */\nexport { stdioservertransport } from '@modelcontextprotocol/server/stdio';\nexport { type catalog, catalogerror, type searchhit, snapshotcatalog } from './catalog.js';\nexport { codexerror } from './errors.js';\nexport { type httphost, type httphostoptions, starthttphost } from './http.js';\nexport { createmcpserver } from './server.js';\nexport { type loadedsnapshot, loadsnapshot } from './snapshot.js';\nexport type {\n docpage,\n example,\n packagemeta,\n snapshotmanifest,\n} from './types.js';\n"
|
|
274
274
|
},
|
|
275
275
|
{
|
|
276
276
|
"category": "finance",
|
|
@@ -882,9 +882,9 @@
|
|
|
882
882
|
"category": "ui",
|
|
883
883
|
"description": "lifecycle owned web animations api primitives for native playback, groups, and additive flip transitions.",
|
|
884
884
|
"docs": {
|
|
885
|
-
"index": " \ntitle: 'necromancer: lifecycle owned dom animations'\ndescription: lifecycle owned web animations api primitives for native playback, groups, and additive flip transitions.\npackage: necromancer\ncategory: ui\nkeywords: [animation, web animations api, waapi, flip, stagger, reduced motion]\nrelated: [orbit, ore]\nexports: [animate, animateeach, capturelayout]\nenvironments: [browser]\n \n\n<! markdownlint disable md025 md033 md060 >\n\n<packagehero package=\"necromancer\" />\n\n## why necromancer?\n\nnative web animations api calls do not provide lifecycle ownership, reduced motion policy, grouped playback, or layout transitions. necromancer retains native keyframes and timing semantics while making ownership explicit for a component or dom feature.\n\n```ts\n// before\nconst animation = element.animate(keyframes, { duration: 180 });\nanimation.addeventlistener('cancel', removelisteners);\n\n// after\nconst animation = animate(element, keyframes, { duration: 180 });\nanimation.dispose();\n```\n\n| feature | native waapi | necromancer | motion one |\n| | | | |\n| bundle size | 0 b | <packageinfo package=\"necromancer\" type=\"size\" /> | ~18 kb |\n| root dependencies | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> |\n| lifecycle handle | manual | `dispose()` | library specific controls |\n| reduced motion | manual | `motion: 'system'` default | configuration required |\n| layout transitions | manual flip math | `capturelayout().animate()` | separate api |\n\n<div class=\"decision callout\">\n\n**use necromancer when** you need native browser animations with explicit cancellation, reduced motion behavior, staggered groups, or positional flip transitions.\n\n**consider css transitions when** a static style change needs no playback control, cleanup, or layout measurement.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/necromancer\n```\n\n```sh [npm]\nnpm install @vielzeug/necromancer\n```\n\n```sh [yarn]\nyarn add @vielzeug/necromancer\n```\n\n:::\n\n## quick start\n\nstart the animation after its dom element mounts and release it when its ui owner is removed.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst notice = document.createelement('p');\nnotice.textcontent = 'saved';\ndocument.body.append(notice);\n\nconst animation = animate(\n notice,\n [{ opacity: 0, transform: 'translatey(8px)' }, { opacity: 1, transform: 'translatey(0)' }],\n { duration: 180, easing: 'ease out' },\n);\n\nawait animation.result;\nanimation.dispose();\n```\n\n## features\n\n<div class=\"features grid\">\n\n `animate()`: native element animation with lifecycle ownership and direct native access\n `animateeach()`: group ownership with stable keyframe factories and `stagger`\n `capturelayout()`: one shot flip transition with additive `translate` (position) and `scale` (size)\n `motion`: `'system'` reduced motion support with
|
|
886
|
-
"api": " \ntitle: 'necromancer: api reference'\ndescription: api reference for @vielzeug/necromancer animation ownership, groups, reduced motion, and flip transitions.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `animate()` | animate one element | sync | omitted timing fields use native waapi behavior |\n| `animateeach()` | animate a unique element group | sync | non zero `stagger` needs numeric `delay` |\n| `capturelayout()` | capture positions and create a one shot flip transition | sync | capture before changing layout |\n| `shouldreducemotion()` | report whether a motion mode reduces visible movement | sync | `'system'` reads `prefers reduced motion`; false without `matchmedia` |\n| `necromancererror` | base package error | sync | use `instanceof necromancererror` to narrow unknown errors |\n\n## package entry point\n\n| import | purpose |\n| | |\n| `@vielzeug/necromancer` | animation functions, types, and errors |\n| `@vielzeug/necromancer/testing` | jsdom test fakes for `element.animate()` and `getboundingclientrect()` |\n\n## animation functions\n\n### `animate()`\n\n```ts\nfunction animate(element: element, keyframes: keyframes, options?: animateoptions): animationhandle;\n```\n\nstarts a lifecycle owned native web animation. native timing options, including an omitted or zero `duration`, are preserved.\n\n| parameter | type | description |\n| | | |\n| `element` | `element` | element animated through its native `animate()` method. |\n| `keyframes` | `keyframes` | native keyframe array or property indexed keyframes. |\n| `options` | `animateoptions` | native timing plus motion and cancellation ownership. |\n\n**returns:** an `animationhandle` with native playback access and explicit disposal.\n\n**example:**\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\nhandle.animation.pause();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n \n\n### `animateeach()`\n\n```ts\nfunction animateeach<elementtype extends element>(\n elements: iterable<elementtype>,\n keyframes: keyframes | keyframefactory<elementtype>,\n options?: animateeachoptions,\n): animationgroup;\n```\n\nstarts animations for unique elements in first seen order. necromancer resolves every keyframe factory before starting the first native animation.\n\n| parameter | type | description |\n| | | |\n| `elements` | `iterable<elementtype>` | elements animated once in first seen order. |\n| `keyframes` | `keyframes \\| keyframefactory<elementtype>` | shared keyframes or a subtype preserving factory. |\n| `options` | `animateeachoptions` | animation options plus a stagger interval. |\n\n**returns:** an `animationgroup` containing child handles and ordered results.\n\n**example:**\n\n```ts\nimport { animateeach } from '@vielzeug/necromancer';\n\nconst group = animateeach(document.queryselectorall<htmlelement>('.item'), [{ opacity: 0 }, { opacity: 1 }], {\n duration: 180,\n stagger: 30,\n});\nawait group.results;\n```\n\n### `shouldreducemotion()`\n\n```ts\nfunction shouldreducemotion(mode: motionmode): boolean;\n```\n\nreports whether the requested motion preference reduces visible movement: the same check `animate()` applies internally, exposed so hand rolled effects (scroll behavior, tweens) stay consistent with it. `'full'` is always `false`, `'reduced'` is always `true`, and `'system'` reads the `prefers reduced motion` media query (`false` where `matchmedia` is unavailable).\n\n```ts\nimport { shouldreducemotion } from '@vielzeug/necromancer';\n\nelement.scrollintoview({ behavior: shouldreducemotion('system') ? 'auto' : 'smooth' });\n```\n\n## layout functions\n\n### `capturelayout()`\n\n```ts\nfunction capturelayout<elementtype extends element>(\n elements: iterable<elementtype>,\n options?: layoutcaptureoptions<elementtype>,\n): layouttransition<elementtype>;\n```\n\ncaptures unique elements' positions and sizes and returns a one shot transition. rotation and other transforms are not captured or compensated.\n\n| parameter | type | description |\n| | | |\n| `elements` | `iterable<elementtype>` | elements measured before a layout change. |\n| `options` | `layoutcaptureoptions<elementtype>` | optional stable key mapping for replacement nodes. |\n\n**returns:** a `layouttransition<elementtype>` that measures committed layout once and creates an `animationgroup`.\n\n**example:**\n\n```ts\nimport { capturelayout } from '@vielzeug/necromancer';\n\nconst transition = capturelayout(beforeitems, {\n getkey: (element) => element.getattribute('data id')!,\n});\n\nrenderreordereditems();\n\nconst group = transition.animate({\n duration: 220,\n easing: 'ease out',\n elements: afteritems,\n});\n```\n\ncalling `animate()` twice on the same transition throws `necromancerconfigerror`.\n\n## types\n\n### `motionmode`\n\n```ts\ntype motionmode = 'full' | 'reduced' | 'system';\n```\n\n`'system'` is the default. reduced motion preserves the supplied keyframes while normalizing delay, duration, and end delay to `0`, and iterations to `1`.\n\n### `animationresult`\n\n```ts\ntype animationresult =\n | { readonly status: 'finished' }\n | { readonly status: 'reduced' }\n | { readonly reason?: unknown; readonly status: 'cancelled' };\n```\n\n`cancelled` describes native cancellation and includes its native rejection reason. a reason passed to `dispose()` or an abort signal takes precedence. the independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.\n\n### `animateoptions`\n\n```ts\ntype animateoptions = keyframeanimationoptions & {\n readonly motion?: motionmode;\n readonly signal?: abortsignal;\n};\n```\n\nnative timing fields pass through unchanged unless reduced motion normalizes timing. `signal` disposes the returned handle when aborted.\n\n### `animateeachoptions`\n\n```ts\ntype animateeachoptions = animateoptions & {\n readonly stagger?: number;\n};\n```\n\n`stagger` is a finite, non negative millisecond offset.\n\n### `layoutcaptureoptions`\n\n```ts\ninterface layoutcaptureoptions<elementtype extends element = element> {\n readonly getkey?: (element: elementtype) => string;\n}\n```\n\n`getkey` maps a captured element and its committed replacement to the same stable, non empty string. duplicate or empty keys throw `necromancerconfigerror`.\n\n### `layoutanimationoptions`\n\n```ts\ntype layoutanimationoptions<elementtype extends element = element> = animateeachoptions & {\n readonly elements?: iterable<elementtype>;\n};\n```\n\n`elements` is the collection in its committed layout. omit it to animate the same captured elements. with `getkey`, replacement elements animate from the positions of their captured predecessors. unmatched, removed, and newly entered elements are ignored.\n\n### `keyframes` and `keyframefactory`\n\n```ts\ntype keyframes = readonly keyframe[] | propertyindexedkeyframes;\ntype keyframefactory<elementtype extends element = element> = (\n element: elementtype,\n index: number,\n total: number,\n) => keyframes;\n```\n\naccepts a `readonly` array so a reusable `as const` keyframe list can be passed without a cast.\n\n### `animationhandle`\n\n```ts\ninterface animationhandle {\n readonly animation: animation;\n readonly result: promise<animationresult>;\n readonly disposed: boolean;\n dispose(reason?: unknown): void;\n [symbol.dispose](): void;\n}\n```\n\n| member | description |\n| | |\n| `animation` | owned native animation used for playback control. |\n| `result` | resolves with the first terminal outcome. |\n| `disposed` | reports explicit owner disposal. |\n| `dispose(reason?)` | cancels the animation and releases its abort listener. |\n| `[symbol.dispose]()` | delegates to `dispose()`. |\n\n### `animationgroup`\n\n```ts\ninterface animationgroup {\n readonly handles: readonly animationhandle[];\n readonly results: promise<readonly animationresult[]>;\n readonly disposed: boolean;\n dispose(reason?: unknown): void;\n [symbol.dispose](): void;\n}\n```\n\n| member | description |\n| | |\n| `handles` | child handles in input order. |\n| `results` | resolves with every child outcome in handle order. |\n| `disposed` | reports explicit group disposal. |\n| `dispose(reason?)` | disposes every child. |\n| `[symbol.dispose]()` | delegates to `dispose()`. |\n\n### `layouttransition`\n\n```ts\ninterface layouttransition<elementtype extends element = element> {\n animate(options?: layoutanimationoptions<elementtype>): animationgroup;\n}\n```\n\n| method | description |\n| | |\n| `animate(options?)` | measures committed elements and creates the one allowed layout animation group. |\n\n## errors\n\n| error | trigger |\n| | |\n| `necromancererror` | base class for package errors |\n| `necromancerconfigerror` | invalid stagger, incompatible delay, or reused layout transition |\n| `necromancerunsupportederror` | `element.animate()` is unavailable |\n\n## testing (`@vielzeug/necromancer/testing`)\n\njsdom (and most non browser dom environments) do not implement `element.animate()`. import these from the `/testing` sub path, not the root entry point.\n\n### `animationcall`\n\n```ts\ntype animationcall = {\n readonly animation: fakeanimation;\n readonly keyframes: keyframe[] | propertyindexedkeyframes;\n readonly options?: keyframeanimationoptions;\n};\n```\n\none recorded invocation of `element.prototype.animate` from `installfakeanimations()`.\n\n### `installfakeanimations()`\n\n```ts\nfunction installfakeanimations(): {\n readonly calls: readonly animationcall[];\n restore(): void;\n [symbol.dispose](): void;\n};\n```\n\nreplaces `element.prototype.animate` with a deterministic lifecycle fake for the duration of a test. `calls` records every invocation in order. call `restore()` or use an explicit resource management `using` declaration to put the original implementation back. the fake does not implement native playback controls such as `pause()` or `reverse()`.\n\n```ts\nimport { installfakeanimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installfakeanimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\n### `fakeanimation`\n\n```ts\nclass fakeanimation {\n cancelcallcount: number;\n finishcallcount: number;\n finished: promise<void>;\n cancel(): void;\n finish(): void;\n}\n```\n\na minimal `animation` stand in. `cancel()` rejects `finished` with an `aborterror`; `finish()` resolves it. `cancelcallcount`/`finishcallcount` track how many times each was called, in place of a test runner specific spy.\n\n### `createrect()`\n\n```ts\nfunction createrect(x: number, y: number, width?: number, height?: number): domrect;\n```\n\nbuilds a `domrect` for mocking `element.getboundingclientrect()` in `capturelayout()` tests. `width`/`height` default to `20`.\n",
|
|
887
|
-
"usage": " \ntitle: 'necromancer: usage guide'\ndescription: animate dom elements, coordinate groups, and create flip transitions with @vielzeug/necromancer.\n \n\n[[toc]]\n\n## basic usage\n\ncreate an animation after its element mounts, control playback through the native `animation`, and dispose its owner with the ui lifecycle.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(\n element,\n [{ opacity: 0, transform: 'translatey(8px)' }, { opacity: 1, transform: 'translatey(0)' }],\n { duration: 180, easing: 'ease out', fill: 'both' },\n);\n\nhandle.animation.reverse();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n`result` distinguishes natural completion
|
|
885
|
+
"index": " \ntitle: 'necromancer: lifecycle owned dom animations'\ndescription: lifecycle owned web animations api primitives for native playback, groups, and additive flip transitions.\npackage: necromancer\ncategory: ui\nkeywords: [animation, web animations api, waapi, flip, stagger, reduced motion]\nrelated: [orbit, ore]\nexports: [animate, animateeach, capturelayout]\nenvironments: [browser]\n \n\n<! markdownlint disable md025 md033 md060 >\n\n<packagehero package=\"necromancer\" />\n\n## why necromancer?\n\nnative web animations api calls do not provide lifecycle ownership, reduced motion policy, grouped playback, or layout transitions. necromancer retains native keyframes and timing semantics while making ownership explicit for a component or dom feature.\n\n```ts\n// before\nconst animation = element.animate(keyframes, { duration: 180 });\nanimation.addeventlistener('cancel', removelisteners);\n\n// after\nconst animation = animate(element, keyframes, { duration: 180 });\nanimation.dispose();\n```\n\n| feature | native waapi | necromancer | motion one |\n| | | | |\n| bundle size | 0 b | <packageinfo package=\"necromancer\" type=\"size\" /> | ~18 kb |\n| root dependencies | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> |\n| lifecycle handle | manual | `dispose()` | library specific controls |\n| reduced motion | manual | `motion: 'system'` default | configuration required |\n| layout transitions | manual flip math | `capturelayout().animate()` | separate api |\n\n<div class=\"decision callout\">\n\n**use necromancer when** you need native browser animations with explicit cancellation, reduced motion behavior, staggered groups, or positional flip transitions.\n\n**consider css transitions when** a static style change needs no playback control, cleanup, or layout measurement.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/necromancer\n```\n\n```sh [npm]\nnpm install @vielzeug/necromancer\n```\n\n```sh [yarn]\nyarn add @vielzeug/necromancer\n```\n\n:::\n\n## quick start\n\nstart the animation after its dom element mounts and release it when its ui owner is removed.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst notice = document.createelement('p');\nnotice.textcontent = 'saved';\ndocument.body.append(notice);\n\nconst animation = animate(\n notice,\n [{ opacity: 0, transform: 'translatey(8px)' }, { opacity: 1, transform: 'translatey(0)' }],\n { duration: 180, easing: 'ease out' },\n);\n\nawait animation.result;\nanimation.dispose();\n```\n\n## features\n\n<div class=\"features grid\">\n\n `animate()`: native element animation with lifecycle ownership and direct native access\n `animateeach()`: group ownership with stable keyframe factories and `stagger`\n `capturelayout()`: one shot flip transition with additive `translate` (position) and `scale` (size)\n `motion`: `'system'` reduced motion support with the same keyframes on instant timing\n native timing: omitted timing fields retain web animations api behavior\n `signal`: abort a handle from its parent lifecycle\n `dispose()`: idempotent cleanup with `[symbol.dispose]()`\n\n</div>\n\n## deliberate scope\n\nnecromancer owns explicit waapi keyframes. it does not generate css keyframes, observe css transitions, watch mutations, simulate springs, interpolate svg paths, or run a javascript tween loop. use css for declarative style changes and choose a dedicated tool when those capabilities are required.\n\n## documentation\n\n<div class=\"doc links\">\n\n [usage guide](./usage.md)\n [api reference](./api.md)\n [examples](./examples.md)\n [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n [orbit](/orbit/): position floating ui before animating its appearance.\n [ore](/ore/): own necromancer handles in a custom element's mount and disposal lifecycle.\n</div>\n\n<! markdownlint enable md025 md033 md060 >\n",
|
|
886
|
+
"api": " \ntitle: 'necromancer: api reference'\ndescription: api reference for @vielzeug/necromancer animation ownership, groups, reduced motion, and flip transitions.\n \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n| | | | |\n| `animate()` | animate one element | sync | omitted timing fields use native waapi behavior |\n| `animateeach()` | animate a unique element group | sync | non zero `stagger` needs numeric `delay` |\n| `capturelayout()` | capture positions and create a one shot flip transition | sync | capture before changing layout |\n| `shouldreducemotion()` | report whether a motion mode reduces visible movement | sync | `'system'` reads `prefers reduced motion`; false without `matchmedia` |\n| `necromancererror` | base package error | sync | use `instanceof necromancererror` to narrow unknown errors |\n\n## package entry point\n\n| import | purpose |\n| | |\n| `@vielzeug/necromancer` | animation functions, types, and errors |\n| `@vielzeug/necromancer/testing` | jsdom test fakes for `element.animate()` and `getboundingclientrect()` |\n\n## animation functions\n\n### `animate()`\n\n```ts\nfunction animate(element: element, keyframes: keyframes, options?: animateoptions): animationhandle;\n```\n\nstarts a lifecycle owned native web animation. native timing options, including an omitted or zero `duration`, are preserved.\n\n| parameter | type | description |\n| | | |\n| `element` | `element` | element animated through its native `animate()` method. |\n| `keyframes` | `keyframes` | native keyframe array or property indexed keyframes. |\n| `options` | `animateoptions` | native timing plus motion and cancellation ownership. |\n\n**returns:** an `animationhandle` with native playback access and explicit disposal.\n\n**example:**\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\nhandle.animation.pause();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n \n\n### `animateeach()`\n\n```ts\nfunction animateeach<elementtype extends element>(\n elements: iterable<elementtype>,\n keyframes: keyframes | keyframefactory<elementtype>,\n options?: animateeachoptions,\n): animationgroup;\n```\n\nstarts animations for unique elements in first seen order. necromancer resolves every keyframe factory before starting the first native animation.\n\n| parameter | type | description |\n| | | |\n| `elements` | `iterable<elementtype>` | elements animated once in first seen order. |\n| `keyframes` | `keyframes \\| keyframefactory<elementtype>` | shared keyframes or a subtype preserving factory. |\n| `options` | `animateeachoptions` | animation options plus a stagger interval. |\n\n**returns:** an `animationgroup` containing child handles and ordered results.\n\n**example:**\n\n```ts\nimport { animateeach } from '@vielzeug/necromancer';\n\nconst group = animateeach(document.queryselectorall<htmlelement>('.item'), [{ opacity: 0 }, { opacity: 1 }], {\n duration: 180,\n stagger: 30,\n});\nawait group.results;\n```\n\n### `shouldreducemotion()`\n\n```ts\nfunction shouldreducemotion(mode: motionmode): boolean;\n```\n\nreports whether the requested motion preference reduces visible movement: the same check `animate()` applies internally, exposed so hand rolled effects (scroll behavior, tweens) stay consistent with it. `'full'` is always `false`, `'reduced'` is always `true`, and `'system'` reads the `prefers reduced motion` media query (`false` where `matchmedia` is unavailable).\n\n```ts\nimport { shouldreducemotion } from '@vielzeug/necromancer';\n\nelement.scrollintoview({ behavior: shouldreducemotion('system') ? 'auto' : 'smooth' });\n```\n\n## layout functions\n\n### `capturelayout()`\n\n```ts\nfunction capturelayout<elementtype extends element>(\n elements: iterable<elementtype>,\n options?: layoutcaptureoptions<elementtype>,\n): layouttransition<elementtype>;\n```\n\ncaptures unique elements' positions and sizes and returns a one shot transition. rotation and other transforms are not captured or compensated.\n\n| parameter | type | description |\n| | | |\n| `elements` | `iterable<elementtype>` | elements measured before a layout change. |\n| `options` | `layoutcaptureoptions<elementtype>` | optional stable key mapping for replacement nodes. |\n\n**returns:** a `layouttransition<elementtype>` that measures committed layout once and creates an `animationgroup`.\n\n**example:**\n\n```ts\nimport { capturelayout } from '@vielzeug/necromancer';\n\nconst transition = capturelayout(beforeitems, {\n getkey: (element) => element.getattribute('data id')!,\n});\n\nrenderreordereditems();\n\nconst group = transition.animate({\n duration: 220,\n easing: 'ease out',\n elements: afteritems,\n});\n```\n\ncalling `animate()` twice on the same transition throws `necromancerconfigerror`.\n\n## types\n\n### `motionmode`\n\n```ts\ntype motionmode = 'full' | 'reduced' | 'system';\n```\n\n`'system'` is the default. reduced motion preserves the supplied keyframes while normalizing delay, duration, and end delay to `0`, and iterations to `1`.\n\n### `animationresult`\n\n```ts\ntype animationresult =\n | { readonly status: 'finished' }\n | { readonly reason?: unknown; readonly status: 'cancelled' };\n```\n\na reduced animation finishes: reduction is decided at call time and `shouldreducemotion()` answers it, so the result reports only what the caller could not know. `cancelled` carries the reason the animation was cancelled: the value passed to `dispose()`, the abort reason of the owning `signal`, or the native rejection reason when something outside necromancer cancelled the animation. a bare `dispose()` carries no reason. the independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.\n\n### `animateoptions`\n\n```ts\ntype animateoptions = keyframeanimationoptions & {\n readonly motion?: motionmode;\n readonly signal?: abortsignal;\n};\n```\n\nnative timing fields pass through unchanged unless reduced motion normalizes timing. `signal` disposes the returned handle when aborted.\n\n### `animateeachoptions`\n\n```ts\ntype animateeachoptions = animateoptions & {\n readonly stagger?: number;\n};\n```\n\n`stagger` is a finite, non negative millisecond offset.\n\n### `layoutcaptureoptions`\n\n```ts\ninterface layoutcaptureoptions<elementtype extends element = element> {\n readonly getkey?: (element: elementtype) => string;\n}\n```\n\n`getkey` maps a captured element and its committed replacement to the same stable, non empty string. duplicate or empty keys throw `necromancerconfigerror`.\n\n### `layoutanimationoptions`\n\n```ts\ntype layoutanimationoptions<elementtype extends element = element> = animateeachoptions & {\n readonly elements?: iterable<elementtype>;\n};\n```\n\n`elements` is the collection in its committed layout. omit it to animate the same captured elements. with `getkey`, replacement elements animate from the positions of their captured predecessors. unmatched, removed, and newly entered elements are ignored.\n\n### `keyframes` and `keyframefactory`\n\n```ts\ntype keyframes = readonly keyframe[] | propertyindexedkeyframes;\ntype keyframefactory<elementtype extends element = element> = (\n element: elementtype,\n index: number,\n total: number,\n) => keyframes;\n```\n\naccepts a `readonly` array so a reusable `as const` keyframe list can be passed without a cast.\n\n### `animationhandle`\n\n```ts\ninterface animationhandle {\n readonly animation: animation;\n readonly result: promise<animationresult>;\n readonly disposed: boolean;\n dispose(reason?: unknown): void;\n [symbol.dispose](): void;\n}\n```\n\n| member | description |\n| | |\n| `animation` | owned native animation used for playback control. |\n| `result` | resolves with the first terminal outcome. |\n| `disposed` | reports explicit owner disposal. |\n| `dispose(reason?)` | cancels the animation and releases its abort listener. |\n| `[symbol.dispose]()` | delegates to `dispose()`. |\n\n### `animationgroup`\n\n```ts\ninterface animationgroup {\n readonly handles: readonly animationhandle[];\n readonly results: promise<readonly animationresult[]>;\n readonly disposed: boolean;\n dispose(reason?: unknown): void;\n [symbol.dispose](): void;\n}\n```\n\n| member | description |\n| | |\n| `handles` | child handles in input order. |\n| `results` | resolves with every child outcome in handle order. |\n| `disposed` | reports explicit group disposal. |\n| `dispose(reason?)` | disposes every child. |\n| `[symbol.dispose]()` | delegates to `dispose()`. |\n\n### `layouttransition`\n\n```ts\ninterface layouttransition<elementtype extends element = element> {\n animate(options?: layoutanimationoptions<elementtype>): animationgroup;\n}\n```\n\n| method | description |\n| | |\n| `animate(options?)` | measures committed elements and creates the one allowed layout animation group. |\n\n## errors\n\n| error | trigger |\n| | |\n| `necromancererror` | base class for package errors |\n| `necromancerconfigerror` | invalid stagger, incompatible delay, or reused layout transition |\n| `necromancerunsupportederror` | `element.animate()` is unavailable |\n\n## testing (`@vielzeug/necromancer/testing`)\n\njsdom (and most non browser dom environments) do not implement `element.animate()`. import these from the `/testing` sub path, not the root entry point.\n\n### `animationcall`\n\n```ts\ntype animationcall = {\n readonly animation: fakeanimation;\n readonly keyframes: keyframe[] | propertyindexedkeyframes;\n readonly options?: keyframeanimationoptions;\n};\n```\n\none recorded invocation of `element.prototype.animate` from `installfakeanimations()`.\n\n### `installfakeanimations()`\n\n```ts\nfunction installfakeanimations(): {\n readonly calls: readonly animationcall[];\n restore(): void;\n [symbol.dispose](): void;\n};\n```\n\nreplaces `element.prototype.animate` with a deterministic lifecycle fake for the duration of a test. `calls` records every invocation in order. call `restore()` or use an explicit resource management `using` declaration to put the original implementation back. the fake does not implement native playback controls such as `pause()` or `reverse()`.\n\n```ts\nimport { installfakeanimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installfakeanimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\n### `fakeanimation`\n\n```ts\nclass fakeanimation {\n cancelcallcount: number;\n finishcallcount: number;\n finished: promise<void>;\n cancel(): void;\n finish(): void;\n}\n```\n\na minimal `animation` stand in. `cancel()` rejects `finished` with an `aborterror`; `finish()` resolves it. `cancelcallcount`/`finishcallcount` track how many times each was called, in place of a test runner specific spy.\n\n### `createrect()`\n\n```ts\nfunction createrect(x: number, y: number, width?: number, height?: number): domrect;\n```\n\nbuilds a `domrect` for mocking `element.getboundingclientrect()` in `capturelayout()` tests. `width`/`height` default to `20`.\n",
|
|
887
|
+
"usage": " \ntitle: 'necromancer: usage guide'\ndescription: animate dom elements, coordinate groups, and create flip transitions with @vielzeug/necromancer.\n \n\n[[toc]]\n\n## basic usage\n\ncreate an animation after its element mounts, control playback through the native `animation`, and dispose its owner with the ui lifecycle.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(\n element,\n [{ opacity: 0, transform: 'translatey(8px)' }, { opacity: 1, transform: 'translatey(0)' }],\n { duration: 180, easing: 'ease out', fill: 'both' },\n);\n\nhandle.animation.reverse();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n`result` distinguishes natural completion from cancellation. `disposed` reports only whether the owner was explicitly disposed.\n\nomitted timing fields retain native web animations api behavior. pass an explicit `duration` when the animation should run over time.\n\n## motion preferences\n\nuse `motion` to select how the animation responds to the operating system preference.\n\n```ts\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], {\n duration: 200,\n motion: 'system',\n});\n\nconst result = await handle.result;\n```\n\n`'system'` is the default and reduces movement when `prefers reduced motion: reduce` matches. `'full'` preserves the requested timing, while `'reduced'` always reduces it.\n\nreduced motion keeps the supplied keyframes but normalizes delay, duration, and end delay to zero and iterations to one. the animation finishes immediately, so its result is `{ status: 'finished' }`; call `shouldreducemotion()` with the same mode when your own code needs to know whether movement was reduced. `handle.animation` still represents the requested visual transition.\n\n## parent cancellation\n\npass a parent `abortsignal` to release an animation when its owning work is cancelled.\n\n```ts\nconst controller = new abortcontroller();\nconst handle = animate(element, [{ scale: 0.96 }, { scale: 1 }], {\n duration: 160,\n signal: controller.signal,\n});\n\ncontroller.abort('route changed');\nconst result = await handle.result;\n// { status: 'cancelled', reason: 'route changed' }\n```\n\nan already aborted signal throws its reason before an animation starts.\n\n## staggering a group\n\npass an iterable of elements to `animateeach()`. duplicate elements are animated once in first seen order.\n\n```ts\nimport { animateeach } from '@vielzeug/necromancer';\n\nconst group = animateeach(\n document.queryselectorall('.card'),\n (_card, index) => [\n { opacity: 0, transform: `translatey(${12 + index * 2}px)` },\n { opacity: 1, transform: 'translatey(0)' },\n ],\n { duration: 220, easing: 'ease out', stagger: 45 },\n);\n\nconst results = await group.results;\ngroup.dispose();\n```\n\na group owns child lifecycles only. `results` preserves every child result in handle order; use `group.handles` when native playback control is required.\n\n## serial application flow\n\njavascript control flow is the clearest way to express serial, conditional, or branching animations:\n\n```ts\nfor (const step of steps) {\n const handle = animate(step.element, step.keyframes, {\n ...step.options,\n signal: controller.signal,\n });\n const result = await handle.result;\n\n if (result.status === 'cancelled') break;\n}\n```\n\none parent `abortsignal` cancels the active step without introducing a separate timeline abstraction.\n\n## animating a reorder with flip\n\ncapture positions before changing layout, then animate through the returned one shot transition.\n\n```ts\nimport { capturelayout } from '@vielzeug/necromancer';\n\nconst transition = capturelayout(items);\nlist.prepend(items[2]!);\n\nconst group = transition.animate({ duration: 220, easing: 'ease out' });\nawait group.results;\ngroup.dispose();\n```\n\nthe transition only animates changed, connected elements and can be animated once. it additively composes the individual css `translate` and `scale` properties, preserving authored `transform`, `translate`, and `scale`. a resized element (for example a list item whose content changed) animates from its captured size as well as its captured position.\n\n### replacing rendered elements\n\nwhen a framework replaces list nodes rather than reorders the captured elements, give `capturelayout()` a stable key and pass the committed nodes to `animate()`. capture before updating state, then call `animate()` only after the renderer has committed the new dom.\n\n```ts\nconst transition = capturelayout(beforeitems, {\n getkey: (element) => element.getattribute('data id')!,\n});\n\nrenderreordereditems();\n\ntransition.animate({\n duration: 220,\n easing: 'ease out',\n elements: afteritems,\n});\n```\n\nkeys must be unique, non empty strings in both collections. items with no matching predecessor are not enter animations; animate those explicitly with `animate()` or `animateeach()`.\n\nfor sortable lists, dnd exposes its pre commit layout seam through `onbeforereorder`; see the [dnd optimistic reorder recipe](/dnd/examples/optimistic reorder with revert.md).\n\n## scope\n\nnecromancer creates and owns explicit web animations api work. it does not observe css authored transitions or animations, inject `@keyframes`, watch dom mutations, generate springs, interpolate svg geometry, or provide a javascript tween fallback. keep css as the owner of declarative component styling and use a dedicated charting or tweening tool when the animation needs capabilities beyond waapi keyframes.\n\n## testing\n\njsdom does not implement `element.animate()`, so lifecycle tests need a fake. `@vielzeug/necromancer/testing` has no test runner import and supports explicit resource management.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\nimport { installfakeanimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installfakeanimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\nuse `restore()` when `using` is unavailable. the lifecycle fake supports `finish()`, `cancel()`, and `finished`; use browser tests for native playback controls. use `createrect()` to mock `element.getboundingclientrect()` when testing code that calls `capturelayout()`.\n\n## framework integration\n\ncreate handles in a client mount lifecycle and dispose them during unmount. the same composition works with reactive effect systems: start the animation in the effect and return `handle.dispose()` as its cleanup.\n\n```tsx\nimport { useeffect, useref } from 'react';\nimport { animate } from '@vielzeug/necromancer';\n\nexport function notice() {\n const elementref = useref<htmldivelement>(null);\n\n useeffect(() => {\n const element = elementref.current;\n if (!element) return;\n\n const handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\n return () => handle.dispose();\n }, []);\n\n return <div ref={elementref}>saved</div>;\n}\n```\n\n## working with other vielzeug libraries\n\nuse dnd's `onbeforereorder` hook to capture item layout before a sortable commits its dom update. animate the captured transition after `onreorder`; see the [optimistic reorder recipe](/dnd/examples/optimistic reorder with revert.md).\n\n## best practices\n\n start animations only after their elements mount in the browser.\n set animation timing explicitly when native zero duration behavior is not intended.\n dispose each handle or group with its ui owner.\n use native `animation` objects for playback control.\n respect the default `'system'` motion setting unless movement is essential.\n use a parent `abortsignal` for cancellable application flow.\n keep `delay` numeric when combining it with non zero `stagger`.\n capture layout before mutation and animate each transition exactly once.\n",
|
|
888
888
|
"examples": " \ntitle: 'necromancer: examples'\ndescription: practical animation and flip layout recipes for @vielzeug/necromancer.\n \n\n## examples\n\n [animate on mount](./examples/animate on mount.md)\n [stagger a list](./examples/stagger a list.md)\n [animate a reorder](./examples/animate a reorder.md)\n\n"
|
|
889
889
|
},
|
|
890
890
|
"examples": [
|
|
@@ -894,11 +894,11 @@
|
|
|
894
894
|
},
|
|
895
895
|
{
|
|
896
896
|
"id": "lifecycle",
|
|
897
|
-
"text": "animate() lifecycle handle import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createelement('section')\npanel.style.csstext = 'display: grid; gap: 12px; max width: 320px; padding: 20px; border: 1px solid #cbd5e1; border radius: 12px; background: #fff;'\n\nconst card = document.createelement('div')\ncard.textcontent = 'lifecycle owned animation'\ncard.style.csstext = 'padding: 18px; border radius: 8px; color: #fff; background: #2563eb; font: 600 16px system ui;'\n\nconst replay = document.createelement('button')\nreplay.textcontent = 'replay animation'\n\nconst status = document.createelement('output')\nstatus.textcontent = 'ready'\n\npanel.append(card, replay, status)\ndocument.body.appendchild(panel)\n\nlet current\n\nfunction run() {\n current?.dispose('replayed')\n current = animate(\n card,\n [\n { opacity: 0, transform: 'translatey(14px) scale(.96)' },\n { opacity: 1, transform: 'translatey(0) scale(1)' },\n ],\n { duration: 280, easing: 'ease out', fill: 'both' },\n )\n status.textcontent = 'animating…'\n current.result.then((result) => {\n status.textcontent = result.status === 'finished' ? 'finished: handle remains disposable' :
|
|
897
|
+
"text": "animate() lifecycle handle import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createelement('section')\npanel.style.csstext = 'display: grid; gap: 12px; max width: 320px; padding: 20px; border: 1px solid #cbd5e1; border radius: 12px; background: #fff;'\n\nconst card = document.createelement('div')\ncard.textcontent = 'lifecycle owned animation'\ncard.style.csstext = 'padding: 18px; border radius: 8px; color: #fff; background: #2563eb; font: 600 16px system ui;'\n\nconst replay = document.createelement('button')\nreplay.textcontent = 'replay animation'\n\nconst status = document.createelement('output')\nstatus.textcontent = 'ready'\n\npanel.append(card, replay, status)\ndocument.body.appendchild(panel)\n\nlet current\n\nfunction run() {\n current?.dispose('replayed')\n current = animate(\n card,\n [\n { opacity: 0, transform: 'translatey(14px) scale(.96)' },\n { opacity: 1, transform: 'translatey(0) scale(1)' },\n ],\n { duration: 280, easing: 'ease out', fill: 'both' },\n )\n status.textcontent = 'animating…'\n current.result.then((result) => {\n status.textcontent = result.status === 'finished' ? 'finished: handle remains disposable' : 'cancelled'\n })\n}\n\nreplay.addeventlistener('click', run)\n"
|
|
898
898
|
},
|
|
899
899
|
{
|
|
900
900
|
"id": "reduced-motion",
|
|
901
|
-
"text": "motion reduced motion import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createelement('section')\npanel.style.csstext = 'display: grid; gap: 12px; max width: 320px; padding: 20px; border: 1px solid #cbd5e1; border radius: 12px; background: #fff;'\n\nconst card = document.createelement('div')\ncard.textcontent = 'motion preference'\ncard.style.csstext = 'padding: 18px; border radius: 8px; color: #fff; background: #7c3aed; font: 600 16px system ui;'\n\nconst systembutton = document.createelement('button')\nsystembutton.textcontent = 'animate with system preference'\n\nconst skipbutton = document.createelement('button')\nskipbutton.textcontent = 'use reduced motion'\n\nconst status = document.createelement('output')\nstatus.textcontent = 'choose a mode'\n\npanel.append(card, systembutton, skipbutton, status)\ndocument.body.appendchild(panel)\n\nfunction run(motion) {\n const handle = animate(\n card,\n [\n { opacity: 0, transform: 'translatex( 18px)' },\n { opacity: 1, transform: 'translatex(0)' },\n ],\n { duration: 320, easing: 'ease out', motion, fill: 'both' },\n )\n status.textcontent = 'running with motion: ' + motion\n handle.result.then((result) => {\n status.textcontent
|
|
901
|
+
"text": "motion reduced motion import { animate, shouldreducemotion } from '@vielzeug/necromancer'\n\nconst panel = document.createelement('section')\npanel.style.csstext = 'display: grid; gap: 12px; max width: 320px; padding: 20px; border: 1px solid #cbd5e1; border radius: 12px; background: #fff;'\n\nconst card = document.createelement('div')\ncard.textcontent = 'motion preference'\ncard.style.csstext = 'padding: 18px; border radius: 8px; color: #fff; background: #7c3aed; font: 600 16px system ui;'\n\nconst systembutton = document.createelement('button')\nsystembutton.textcontent = 'animate with system preference'\n\nconst skipbutton = document.createelement('button')\nskipbutton.textcontent = 'use reduced motion'\n\nconst status = document.createelement('output')\nstatus.textcontent = 'choose a mode'\n\npanel.append(card, systembutton, skipbutton, status)\ndocument.body.appendchild(panel)\n\nfunction run(motion) {\n const handle = animate(\n card,\n [\n { opacity: 0, transform: 'translatex( 18px)' },\n { opacity: 1, transform: 'translatex(0)' },\n ],\n { duration: 320, easing: 'ease out', motion, fill: 'both' },\n )\n status.textcontent = 'running with motion: ' + motion\n handle.result.then((result) => {\n status.textcontent =\n result.status === 'cancelled' ? 'cancelled' : shouldreducemotion(motion) ? 'finished with reduced timing' : 'finished'\n })\n}\n\nsystembutton.addeventlistener('click', () => run('system'))\nskipbutton.addeventlistener('click', () => run('reduced'))"
|
|
902
902
|
},
|
|
903
903
|
{
|
|
904
904
|
"id": "stagger",
|
|
@@ -1057,8 +1057,8 @@
|
|
|
1057
1057
|
"description": "accessible, themeable web components built with ore for framework and vanilla dom apps.",
|
|
1058
1058
|
"docs": {
|
|
1059
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
|
-
"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"
|
|
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| `@vielzeug/refine/blueprint` | `parseuiblueprint()`: validate a model authored ui document against a fixed registry | sync | pure contract only: it registers no components and renders nothing |\n| `@vielzeug/refine/blueprint/render` | `renderuiblueprint()`: render a validated document with registered components | sync | registers its thirteen components on import; rejects before touching the container |\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/blueprint` | on demand ui document contract: `parseuiblueprint()`, the node types, bounds, `ui_blueprint_registry`, and `ui_blueprint_json_schema` |\n| `@vielzeug/refine/blueprint/render` | `renderuiblueprint()` and the thirteen component tags it registers |\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## on demand ui documents\n\n`@vielzeug/refine/blueprint` is the trusted boundary for ui that a model writes. a harness asks a model to describe a small ui in json, and this contract decides whether that json may be rendered. it is data only: no code, no html, no callbacks, no styles, no urls. see [on demand ui documents](./on demand ui) for the full guide.\n\n```ts\nimport { parseuiblueprint, safeparseuiblueprint } from '@vielzeug/refine/blueprint';\n\nconst result = safeparseuiblueprint(json.parse(modeloutput)); // model output stays `unknown`\nif (!result.success) showerror(result.issues); // safe to display: field paths, no secrets\nelse rendervalidated(result.document);\n```\n\n| export | purpose |\n| | |\n| `ui_blueprint_version` | the only document version accepted (`1`) |\n| `parseuiblueprint(value)` | validate `unknown`. returns the document unchanged, or throws `uiblueprinterror`. nothing is repaired or partially accepted |\n| `safeparseuiblueprint(value)` | non throwing form: `{ success: true, document }` or `{ success: false, issues }` |\n| `uiblueprinterror` | `refineerror` subclass carrying `issues: readonly string[]`, each a field path such as `root.children[0].size` |\n| `ui_blueprint_components` | the thirteen accepted component names: `text`, `box`, `card`, `button`, `badge`, `separator`, `slider`, `switch`, `checkbox`, `number input`, `alert`, `progress`, `icon` |\n| `ui_blueprint_registry` | the same registry as data: element tag, child policy, attribute names, slot text fields, and accepted values per component |\n| `ui_blueprint_json_schema` | json schema (draft 2020 12) for the contract, for harnesses with structured output |\n| `blueprintdocument`, `blueprintnode`, and the node interfaces | typescript types for the document shape. every node accepts an optional bounded `id` through `blueprintnodemeta` |\n| `max_blueprint_nodes`, `max_blueprint_depth`, `max_blueprint_children`, `max_blueprint_text_length`, `max_blueprint_label_length`, `max_blueprint_number`, `max_blueprint_id_length` | document bounds, not user configurable |\n\n`@vielzeug/refine/blueprint` imports nothing but `refineerror`: it is pure, dom free, and safe to run in a model harness, a worker, or ci. it registers no components.\n\n`ui_blueprint_json_schema` constrains generation but cannot express the tree wide node and depth bounds, so runtime validation stays mandatory. treat the schema as a generation aid, never as the trust boundary.\n\n### `renderuiblueprint(container, value, options?)`\n\n```ts\nimport { renderuiblueprint } from '@vielzeug/refine/blueprint/render';\n\ntry {\n const { element, nodes } = renderuiblueprint(host, json.parse(modeloutput), { label: 'generated summary' });\n nodes.get('rate')?.addeventlistener('change', () => recalculate());\n} catch (error) {\n // the container is untouched: the previous preview is still on screen.\n}\n```\n\nvalidate `value`, then render it into `container` using only registry components. importing the entry registers those thirteen components, so no separate component imports are needed.\n\n| parameter | type | description |\n| | | |\n| `container` | `htmlelement` | element that receives the rendered tree |\n| `value` | `unknown` | untrusted model output. validated before anything is rendered |\n| `options.label` | `string?` | accessible name for a `role=\"group\"` wrapper. host owned: a document cannot set it |\n| `options.replace` | `boolean?` | clear the container first. default `true`; `false` appends |\n\n**returns** a `uiblueprintrenderresult`: `{ element, nodes }`, the rendered root and a `readonlymap<string, htmlelement>` keyed by each node's optional `id` so the host can wire behaviour to addressable controls. `id` is host facing metadata: the renderer never writes it to the dom. validation runs first, so a rejected document throws `uiblueprinterror` before the container is read or written: an invalid response can never partially render or erase a valid preview. text becomes a text node, never markup.\n\n### `createuiblueprintelement(node, owner?, nodes?)`\n\n```ts\nimport { createuiblueprintelement } from '@vielzeug/refine/blueprint/render';\n\nconst element = createuiblueprintelement(document.root, 'root', nodemap);\n```\n\nbuild one element for an already validated node. pass a `map` as `nodes` to collect every id tagged element it creates, including nested ones; `owner` labels the node's position in rejection messages. this is the component registry: adding a component means adding a rule in the contract and a case here, and nothing else. it throws `typeerror` for an unregistered node type, so a hand built node cannot bypass validation either. embedders that place nodes themselves use this; `renderuiblueprint()` is the normal entry point.\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\n### `uiblueprinterror`\n\n```ts\nclass uiblueprinterror extends refineerror {\n readonly issues: readonly string[];\n}\n```\n\nthrown by `parseuiblueprint()` and `renderuiblueprint()` for a rejected on demand ui document. every rejection is collected first, so `issues` lists all of them at once, each as a field path plus a plain reason (`root.children[0].size: expected one of sm, md, lg, received string.`). the messages name fields and allowed values, report a wrong typed value only as its *type*, and echo an accepted type value only as a truncated snippet, so they are safe to display to a user. see [on demand ui documents](./on demand ui).\n",
|
|
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 **rendering model authored ui?** validate it through the [on demand ui document contract](./on demand ui) instead of trusting model output; never build dom from unvalidated json.\n"
|
|
1062
1062
|
},
|
|
1063
1063
|
"examples": [],
|
|
1064
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",
|
package/dist/catalog.d.ts
CHANGED
|
@@ -1,41 +1,41 @@
|
|
|
1
1
|
import { CodexError } from './errors.js';
|
|
2
2
|
import { type LoadedSnapshot } from './snapshot.js';
|
|
3
|
-
import type { DocPage, Example,
|
|
3
|
+
import type { DocPage, Example, PackageMeta } from './types.js';
|
|
4
4
|
export type CatalogErrorCode = 'INVALID_ARG' | 'NOT_FOUND' | 'UNAVAILABLE';
|
|
5
5
|
export declare class CatalogError extends CodexError {
|
|
6
6
|
readonly code: CatalogErrorCode;
|
|
7
7
|
constructor(code: CatalogErrorCode, message: string);
|
|
8
8
|
}
|
|
9
9
|
export interface SearchHit {
|
|
10
|
-
matchedExamples?: string[];
|
|
11
|
-
matchedIn:
|
|
12
|
-
matchedPages?: DocPage[];
|
|
13
|
-
name: string;
|
|
14
|
-
slug: string;
|
|
10
|
+
readonly matchedExamples?: readonly string[];
|
|
11
|
+
readonly matchedIn: readonly ('docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source')[];
|
|
12
|
+
readonly matchedPages?: readonly DocPage[];
|
|
13
|
+
readonly name: string;
|
|
14
|
+
readonly slug: string;
|
|
15
15
|
}
|
|
16
16
|
export interface Catalog {
|
|
17
|
-
getContent(slug: string): PackageContent;
|
|
18
17
|
getDocs(slug: string, page: DocPage): string;
|
|
19
18
|
getExample(slug: string, exampleId: string): Example;
|
|
20
19
|
getPackage(slug: string): PackageMeta;
|
|
21
20
|
getSource(slug: string): string;
|
|
22
21
|
getTypeSignature(slug: string, symbol: string): string;
|
|
23
|
-
listExamples(slug: string):
|
|
24
|
-
listPackages(): PackageMeta[];
|
|
25
|
-
search(query: string): SearchHit[];
|
|
22
|
+
listExamples(slug: string): readonly Pick<Example, 'id' | 'name'>[];
|
|
23
|
+
listPackages(): readonly PackageMeta[];
|
|
24
|
+
search(query: string): readonly SearchHit[];
|
|
26
25
|
}
|
|
27
26
|
export declare class SnapshotCatalog implements Catalog {
|
|
28
27
|
private readonly bySlug;
|
|
29
28
|
private readonly contentCache;
|
|
30
29
|
private readonly snapshot;
|
|
31
30
|
constructor(snapshot: LoadedSnapshot);
|
|
31
|
+
private requirePackage;
|
|
32
32
|
getPackage(slug: string): PackageMeta;
|
|
33
|
-
|
|
34
|
-
listPackages(): PackageMeta[];
|
|
33
|
+
private readContent;
|
|
34
|
+
listPackages(): readonly PackageMeta[];
|
|
35
35
|
getDocs(slug: string, page: DocPage): string;
|
|
36
36
|
getSource(slug: string): string;
|
|
37
|
-
listExamples(slug: string):
|
|
37
|
+
listExamples(slug: string): readonly Pick<Example, 'id' | 'name'>[];
|
|
38
38
|
getExample(slug: string, exampleId: string): Example;
|
|
39
39
|
getTypeSignature(slug: string, symbol: string): string;
|
|
40
|
-
search(query: string): SearchHit[];
|
|
40
|
+
search(query: string): readonly SearchHit[];
|
|
41
41
|
}
|
package/dist/catalog.js
CHANGED
|
@@ -12,6 +12,16 @@ export class CatalogError extends CodexError {
|
|
|
12
12
|
function matches(haystack, terms) {
|
|
13
13
|
return terms.every((term) => haystack.includes(term));
|
|
14
14
|
}
|
|
15
|
+
function copyPackage(pkg) {
|
|
16
|
+
return {
|
|
17
|
+
...pkg,
|
|
18
|
+
availableDocPages: [...pkg.availableDocPages],
|
|
19
|
+
exampleIds: [...pkg.exampleIds],
|
|
20
|
+
exports: [...pkg.exports],
|
|
21
|
+
keywords: [...pkg.keywords],
|
|
22
|
+
related: [...pkg.related],
|
|
23
|
+
};
|
|
24
|
+
}
|
|
15
25
|
function searchRecord(record, query) {
|
|
16
26
|
const terms = query.toLowerCase().replaceAll('-', ' ').split(/\s+/).filter(Boolean);
|
|
17
27
|
if (terms.length === 0)
|
|
@@ -70,14 +80,17 @@ export class SnapshotCatalog {
|
|
|
70
80
|
this.snapshot = snapshot;
|
|
71
81
|
this.bySlug = new Map(snapshot.catalog.packages.map((pkg) => [pkg.slug, pkg]));
|
|
72
82
|
}
|
|
73
|
-
|
|
83
|
+
requirePackage(slug) {
|
|
74
84
|
const pkg = this.bySlug.get(slug);
|
|
75
85
|
if (!pkg)
|
|
76
86
|
throw new CatalogError('NOT_FOUND', `Package "${slug}" not found. Available slugs: ${[...this.bySlug.keys()].join(', ')}`);
|
|
77
87
|
return pkg;
|
|
78
88
|
}
|
|
79
|
-
|
|
80
|
-
this.
|
|
89
|
+
getPackage(slug) {
|
|
90
|
+
return copyPackage(this.requirePackage(slug));
|
|
91
|
+
}
|
|
92
|
+
readContent(slug) {
|
|
93
|
+
this.requirePackage(slug);
|
|
81
94
|
const cached = this.contentCache.get(slug);
|
|
82
95
|
if (cached)
|
|
83
96
|
return cached;
|
|
@@ -95,32 +108,32 @@ export class SnapshotCatalog {
|
|
|
95
108
|
return content;
|
|
96
109
|
}
|
|
97
110
|
listPackages() {
|
|
98
|
-
return [...this.bySlug.values()];
|
|
111
|
+
return [...this.bySlug.values()].map(copyPackage);
|
|
99
112
|
}
|
|
100
113
|
getDocs(slug, page) {
|
|
101
|
-
const content = this.
|
|
102
|
-
if (
|
|
103
|
-
throw new CatalogError('NOT_FOUND', `No "${page}" page for "${slug}". Available: ${this.
|
|
114
|
+
const content = this.readContent(slug).docs[page];
|
|
115
|
+
if (content === undefined)
|
|
116
|
+
throw new CatalogError('NOT_FOUND', `No "${page}" page for "${slug}". Available: ${this.requirePackage(slug).availableDocPages.join(', ') || 'none'}.`);
|
|
104
117
|
return content;
|
|
105
118
|
}
|
|
106
119
|
getSource(slug) {
|
|
107
|
-
const source = this.
|
|
108
|
-
if (
|
|
120
|
+
const source = this.readContent(slug).apiSource;
|
|
121
|
+
if (source === null)
|
|
109
122
|
throw new CatalogError('UNAVAILABLE', `Package "${slug}" has no bundled source.`);
|
|
110
123
|
return source;
|
|
111
124
|
}
|
|
112
125
|
listExamples(slug) {
|
|
113
|
-
return this.
|
|
126
|
+
return this.readContent(slug).examples.map(({ id, name }) => ({ id, name }));
|
|
114
127
|
}
|
|
115
128
|
getExample(slug, exampleId) {
|
|
116
|
-
const example = this.
|
|
129
|
+
const example = this.readContent(slug).examples.find((item) => item.id === exampleId);
|
|
117
130
|
if (!example)
|
|
118
131
|
throw new CatalogError('NOT_FOUND', `No example "${exampleId}" for "${slug}".`);
|
|
119
|
-
return example;
|
|
132
|
+
return { ...example };
|
|
120
133
|
}
|
|
121
134
|
getTypeSignature(slug, symbol) {
|
|
122
|
-
const signature = this.
|
|
123
|
-
if (
|
|
135
|
+
const signature = this.readContent(slug).typeSignatures[symbol];
|
|
136
|
+
if (signature === undefined)
|
|
124
137
|
throw new CatalogError('NOT_FOUND', `No exported symbol "${symbol}" for "${slug}".`);
|
|
125
138
|
return signature;
|
|
126
139
|
}
|
package/dist/catalog.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAuB,YAAY,EAAE,MAAM,eAAe,CAAC;AAKlE,MAAM,OAAO,YAAa,SAAQ,UAAU;IACjC,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;
|
|
1
|
+
{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}
|