Skip to content

Ore 3.0 Migration ​

Ore 3.0 reduces overlapping component, ID, binding, and testing APIs. It also makes context identity and keyed-list failures explicit.

Register components with define() ​

createComponent() has been removed. Keep registration in the module or browser bootstrap that owns the tag.

ts
// Before
const MyCard = createComponent({ setup: () => html`<slot></slot>` });
customElements.define('my-card', MyCard);

// After
define('my-card', { setup: () => html`<slot></slot>` });

Use createId() ​

createStableId() and resetStableIdCounter() have been removed. createId() now provides the collision-resistant behavior.

ts
// Before
const labelId = createStableId('label');

// After
const labelId = createId('label');

Test isolation resets Ore's internal ID counter through cleanup() or install(afterEach). Application code cannot reset IDs.

Bind explicit ARIA attributes ​

The separate aria binding map has been removed. Put complete aria-* names in attr.

ts
// Before
bind({ aria: { expanded: isOpen, controls: panelId } }, { target: trigger });

// After
bind({ attr: { 'aria-expanded': isOpen, 'aria-controls': panelId } }, { target: trigger });

Update host binding types ​

ReflectConfig is now AttributeBindings. Replace HostBindFn with typeof bind when a callable type is needed.

Treat context descriptions as labels ​

createContext(description) now requires a description and returns a unique key on every call. Reuse the exported key object; do not recreate a context from its description.

ts
// context.ts
export const ThemeContext = createContext<Theme>('Theme');

// provider.ts and consumer.ts
import { ThemeContext } from './context';

Use the active host for useField() ​

FormFieldOptions.el has been removed. Call useField() during the form-associated component's setup; it always attaches internals to the active host.

ts
useField({ value, disabled });

Pass one validity signal to useField() ​

The split validity + validationMessage options are replaced by a single validity: Readable<FormFieldValidity | null> where FormFieldValidity = { flags, message }. The platform's setValidity() contract couples flags and message (flags without a non-empty message throw); one input makes a desynced pair unrepresentable.

ts
// Before
useField({
  validationMessage: computed(() => (isBlank() ? 'Required.' : '')),
  validity: computed(() => (isBlank() ? { valueMissing: true } : null)),
  value,
});

// After
useField({
  validity: computed(() => (isBlank() ? { flags: { valueMissing: true }, message: 'Required.' } : null)),
  value,
});

Install the form-internals polyfill from assay ​

The jsdom ElementInternals/FormData/<form>.reset() polyfill moved out of @vielzeug/ore/testing into @vielzeug/assay, and install() lost its options object. Suites that test form-associated components install it directly:

ts
// Before
install(afterEach, { formInternals: true });

// After
import { installFormInternalsPolyfill } from '@vielzeug/assay';

install(afterEach);
installFormInternalsPolyfill();

Type union props with prop.oneOf() ​

prop.string() and prop.number() no longer accept a type parameter: a generic on a runtime parser was a claim the attribute path could not keep (a raw attribute value could violate any union). Union-valued props use prop.oneOf(allowed, defaultValue?), which enforces the set at runtime (parse falls back to the default outside the set) and accepts string or number members.

ts
// Before
size: prop.string<'sm' | 'md' | 'lg'>(),
elevation: prop.number<0 | 1 | 2>(),

// After
const SIZES = ['sm', 'md', 'lg'] as const;
const ELEVATIONS = [0, 1, 2] as const;

size: prop.oneOf(SIZES),
elevation: prop.oneOf(ELEVATIONS),

prop.oneOf()'s default is now optional: omit it for an optional prop that resolves to undefined when the attribute is absent.

Replace live() with model() ​

live() and LiveBinding have been removed. model(signal) is the one form-control binding: it writes both ways and keeps live()'s stale-write guard. Pass get to transform the written-back value and event to choose the write-back event. model() can only drive a plain value/checked attribute binding; the boolean (?checked=) form throws, so ?checked=${live(x)} becomes checked=${model(x)}.

ts
// Before
<input value=${live(query)} @input=${(e) => (query.value = e.target.value)} />

// After
<input value=${model(query)} />

New template syntax ​

  • .prop=${value} binds an element property explicitly (structured values: arrays, objects, callbacks). Prototype-polluting names (__proto__, constructor, prototype) throw at compile time.
  • Event modifiers @event.stop, .prevent, .once, .capture replace manual stopPropagation()/preventDefault() boilerplate and listener options. An unknown modifier throws at compile time.
  • indeterminate=${signal} on a checkbox binds the property-only indeterminate state (no attribute exists, so none is written).
  • each() reconciliation is transactional: when a render throws, entries created during the failed pass are rolled back and the last good list stays on screen (reported via ore:error, phase 'each-reconcile').

Replace removed testing conveniences ​

Use the underlying operation directly:

RemovedReplacement
debugFlush()flush({ logger: console.debug })
mountComponent(tag, definition, options)define(tag, definition) followed by mount(tag, options), or inline mount(setup, options)
mock(tag, template)customElements.define() with a minimal test element
resetOreForTests()cleanup() or install(afterEach)
walkFlatTree()walkFlatTree() from @vielzeug/assay

Account for keyed-list recovery ​

each() now keeps numeric and string keys distinct. A duplicate-key update reports ore:error and leaves the last valid DOM in place instead of clearing the list.

Disconnect teardown runs one microtask later ​

Cleanup no longer runs synchronously inside disconnectedCallback(). Ore schedules it for the next microtask and cancels it when the same element reconnects before then: a same-turn node move (reparenting, an insertBefore relocation) now preserves the component's scope, state, style sheets, and mounted DOM. setup(), onMounted(), and onCleanup() do not run for a move.

ts
// Same-turn move: no dispose, no re-setup: the same signals and DOM nodes survive.
target.appendChild(el);

el.remove();
await Promise.resolve(); // disconnect cleanup lands here now

Tests that asserted synchronous teardown after remove()/dispose() need one microtask (or await flush() from @vielzeug/ore/testing). A reconnection that happens after teardown is a full remount, exactly as before.

each() no longer moves reused nodes ​

When surviving items keep their relative order (prepend, append, interleaved inserts, content replacement), each() relocates only the new items; reused nodes are never removed and re-inserted. New items are also built detached and inserted once, instead of connecting at the end of the list and connecting again at their final position.

Code or tests that relied on reused items being re-inserted (mutation counters, disconnect/reconnect counts, or animations restarted by re-insertion) will see fewer mutations. Components inside list items now keep their state across list updates that do not reorder them.

Render each html result once ​

HTMLResult is now an opaque, single-use value: its mount() method is no longer public, and rendering the same result twice throws OreApiError. Previously a second render silently showed nothing, and interpolating one result twice attached its listeners twice. Build a fresh result for each rendering.

ts
// Before
const icon = html`<svg>...</svg>`;
html`${icon}${icon}`;
html`${() => (open.value ? icon : null)}`;

// After
const icon = () => html`<svg>...</svg>`;
html`${icon()}${icon()}`;
html`${() => (open.value ? icon() : null)}`;

Await teardown after renderHook dispose() ​

renderHook() now runs its setup inside a real generated component instead of a simulated context, so hooks behave exactly as in define(), including onFormReset() and, with the new { formAssociated: true } option, useField(). As with mount().dispose(), cleanups now run one microtask after dispose() or cleanup().

ts
// Before
dispose();
expect(cleanupSpy).toHaveBeenCalled();

// After
dispose();
await Promise.resolve();
expect(cleanupSpy).toHaveBeenCalled();

Call watchEffect() only during setup ​

watchEffect() now throws OreApiError outside setup. Previously it silently created an effect with no owner, which never stopped unless you kept and called its disposer. For reactive work outside a component, use @vielzeug/ripple's effect() and dispose it yourself. bind() with an explicit target still works outside setup and returns its disposer.

ts
// Before (outside setup)
const stop = watchEffect(() => console.log(count.value));

// After
const handle = effect(() => console.log(count.value));
const stop = () => handle.dispose();

Omit the define() generic to infer props ​

define(tag, { props, setup }) now infers prop types from props; setup(props) was previously typed as an empty object without an explicit generic. Explicit define<Props>() still works and still requires a definition for every key in Props. No migration is required.

Review the Usage Guide and API Reference for the current contracts.