• API Overview
• Package Entry Point
• Styles
• Components
• Framework Types
• Events and Form Controls
• Utilities
  • createThemeController(options?)
  • eventFieldValue(event) / eventFieldChecked(event)
• Types
• Errors
  • RefineError

API Overview

Symbol	Purpose	Execution mode	Common gotcha
@vielzeug/refine/<component>	Register one custom element and export its public types	Sync	Importing a type alone does not register the element
@vielzeug/refine/tokens.css	Load required theme tokens, animations, and cascade layers	CSS	Import once before components render
@vielzeug/refine/fouc.css	Hide unregistered ore-* elements until upgrade	CSS	Load before first paint
@vielzeug/refine/styles/preflight.css	Apply the optional browser reset	CSS	The reset affects global elements
@vielzeug/refine/frameworks/elements	Register typed DOM tag mappings	Types only	Import for side effects in TypeScript
@vielzeug/refine/frameworks/react	Register typed React JSX elements	Types only	Does not provide runtime wrappers
@vielzeug/refine/frameworks/vue	Register typed Vue global components	Types only	Does not install a Vue plugin
@vielzeug/refine/theme	createThemeController(): light/dark/system document theme	Sync	Does not persist the preference or set an accent color
eventFieldValue() / eventFieldChecked()	Read a form control's value/checked from event.currentTarget	Sync	Exported from the package root; guards non-field targets
RefineError	Base class for package-defined public errors	Sync	Component configuration warnings do not throw this error

Package Entry Point

Import	Purpose
@vielzeug/refine	Export RefineError and the eventFieldValue/eventFieldChecked field readers without registering components
@vielzeug/refine/<component>	Register one component and export its tag constant, props, events, and related types
@vielzeug/refine/theme	createThemeController() and its theme types
@vielzeug/refine/tokens.css	Required global design contract
@vielzeug/refine/fouc.css	Optional pre-upgrade visibility rule
@vielzeug/refine/styles/*	Focused theme, animation, layer, and preflight stylesheets
@vielzeug/refine/frameworks/*	TypeScript augmentations for DOM, React, and Vue

Styles

import '@vielzeug/refine/fouc.css';
import '@vielzeug/refine/tokens.css';
import '@vielzeug/refine/styles/preflight.css';

tokens.css is required. It defines tokens, animations, and cascade-layer order without resetting global elements. preflight.css is optional and includes FOUC suppression.

Import path	Purpose
@vielzeug/refine/fouc.css	FOUC suppression for unupgraded custom elements
@vielzeug/refine/tokens.css	Tokens, animation helpers, and cascade layers
@vielzeug/refine/styles/theme.css	Theme token declarations
@vielzeug/refine/styles/animation.css	Animation helpers
@vielzeug/refine/styles/layers.css	Cascade layer declarations
@vielzeug/refine/styles/preflight.css	Optional browser reset and FOUC suppression

Components

Each component uses one registration and type entry point:

import '@vielzeug/refine/button';
import type { OreButtonProps } from '@vielzeug/refine/button';

Area	Components
Content	avatar, avatar-group, breadcrumb, card, carousel, chat-message, code-window, copy-command, icon, keyboard-key, list, list-item, marquee, pagination, separator, speech-player, stats, step, stepper, table, text
Disclosure	accordion, accordion-item, tabs, tab-item, tab-panel
Feedback	alert, async, badge, chip, cookie-banner, password-strength, progress, skeleton, toast, typing-indicator
Inputs	button, button-group, calendar, checkbox, checkbox-group, combobox, counter, datagrid, date-picker, file-input, input, message-composer, number-input, otp-input, radio, radio-group, rating, select, slider, switch, textarea, time-picker
Layout	box, grid, grid-item, navbar, sidebar
Overlays	command-palette, dialog, drawer, menu, navigation-menu, popover, tooltip

Each component page lists its attributes, JavaScript properties, events, slots, parts, and CSS custom properties.

Framework Types

import type {} from '@vielzeug/refine/frameworks/elements';
import type {} from '@vielzeug/refine/frameworks/react';
import type {} from '@vielzeug/refine/frameworks/vue';

The declarations cover every supported tag and derive component properties from Refine's authoritative HTMLElementTagNameMap. They provide types only; component registration still uses component subpaths.

Events and Form Controls

Form controls expose .value or .checked and dispatch standard input and change events. Read the property from event.currentTarget.

Stateful 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.

Utilities

createThemeController(options?)

import { createThemeController } from '@vielzeug/refine/theme';

const theme = createThemeController(); // starts in 'system' mode
theme.setPreference('dark');
theme.dispose();

Owns 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.

The 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].

eventFieldValue(event) / eventFieldChecked(event)

import { eventFieldChecked, eventFieldValue } from '@vielzeug/refine';

input.addEventListener('input', (event) => {
  const value = eventFieldValue(event); // string | undefined: never a blind cast
});

Guarded 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.

Types

Component props follow the Ore<Component>Props naming pattern. Event maps follow Ore<Component>Events. Import both from the component subpath that owns them.

RefineElementMap, RefineReactIntrinsicElements, and RefineVueGlobalComponents are exported from their respective frameworks/* type entry points.

Errors

RefineError

class RefineError extends Error {
  constructor(message: string, opts?: ErrorOptions);
}

Base class for public Refine errors. It preserves cause through ErrorOptions.