Application API

new WildflowerJS(root, options?)

Creates a new WildflowerJS application instance. Typically not needed since a global wildflower instance is created automatically.

Parameters

• root HTMLElement | Document | string - Root element, document, or selector
• options Object - Configuration options (optional)

Options

Option	Type	Default	Description
debug	boolean	false	Enable debug logging
autoInit	boolean	true	Automatically scan and initialize components
errorHandling	'log' | 'throw' | 'silent'	'log'	What happens to an error thrown by your own code, which the framework catches so one handler cannot take the page down. log writes it to the console in every build, naming the component and the method. throw rethrows. silent discards it. A handler registered with onError() takes precedence over all three.
useWfPrefixOnly	boolean	false	Only process data-wf-* attributes

Example

// Most apps use the auto-created global instance
wildflower.component('my-component', { /* ... */ });

// Create custom instance (only if auto-init is disabled)
const app = new WildflowerJS('#app', {
    debug: true,
    errorHandling: 'throw'
});

wildflower.component(name, definition)

Register a component definition.

Parameters

• name string - Unique component name
• definition Object - Component configuration

Returns

WildflowerJS - The app instance (chainable)

Example

wildflower.component('my-component', {
    state: {
        message: 'Hello'
    },

    init() {
        console.log('Component initialized');
    },

    updateMessage() {
        this.message = 'Updated!';
    }
});

wildflower.getComponent(componentId)

Get a component instance by its ID.

Parameters

• componentId string - The component's unique ID

Returns

ComponentInstance | undefined

Example

const component = wildflower.getComponent('counter-1');
if (component) {
    console.log(component.state.count);
}

wildflower.getComponentsByType(name)

Get all instances of a component by type name.

Parameters

• name string - Component type name

Returns

ComponentInstance[]

Example

const counters = wildflower.getComponentsByType('counter');
counters.forEach(counter => {
    counter.state.count = 0;
});

wildflower.config(newOptions?)

Get or set framework configuration options at runtime. When called with an object, merges those options into the current configuration. Always returns the current configuration.

Parameters

• newOptions Object - Options to merge with current config (optional)

Returns

Object - A copy of the current configuration options

Example

// Get current config
const options = wildflower.config();

// Set config options
wildflower.config({ subscribeTimeout: 10000 });

wildflower.scan(scope?)

Manually scan a DOM scope for components to initialize. Useful after dynamically inserting HTML that contains component elements.

Parameters

• scope string | Element - Optional selector string or DOM element to limit scanning (defaults to document)

Returns

number - Count of newly initialized components

Example

// Scan entire document
wildflower.scan();

// Scan a specific container after inserting new HTML
container.innerHTML = '<div data-component="my-widget"></div>';
wildflower.scan(container);

wildflower.getComponentInstance(componentId)

Get a single component instance by its internal ID.

Parameters

• componentId string - The component's unique identifier

Returns

Object | undefined - The component instance, or undefined if not found

Example

const instance = wildflower.getComponentInstance('counter-1');
if (instance) {
    console.log(instance.element);
}

wildflower.hasComponentInstance(componentId)

Check whether a component instance exists by its ID.

Parameters

• componentId string - The component's unique identifier

Returns

boolean - True if the component instance exists

Example

if (wildflower.hasComponentInstance('counter-1')) {
    wildflower.destroyComponent('counter-1');
}

wildflower.destroyComponent(componentId)

Destroy a single component instance and clean up all its resources. Calls lifecycle hooks, destroys child components, removes store subscriptions, and cleans up event handlers.

Parameters

• componentId string - The unique identifier of the component to destroy

Returns

boolean - True if the component was found and destroyed, false otherwise

Example

const wasDestroyed = wildflower.destroyComponent('counter-1');
if (wasDestroyed) {
    console.log('Component cleaned up');
}

wildflower.unregister(name)

Unregister a component and/or store definition by name. Unlike destroyComponent (which tears down a single instance by id), this removes the registered definition itself: it destroys every live instance of that component and disposes their reactive resources, and/or disposes a store of that name, freeing the name to be registered again with a fresh definition.

Registration is otherwise first-write-wins: re-registering an existing name is silently skipped and the original definition is kept. To replace a definition, call unregister first. Primary uses are live-preview and hot-module-reload teardown, dynamic applications that swap components at runtime, and tests that need a clean registry between cases. A name can be both a component and a store; both are handled. (Re-registering a name with a different definition without unregistering first emits dev warning WF-215.)

Parameters

• name string - The component and/or store name to unregister

Returns

boolean - True if a component or a store was removed; false for an unknown name

Example

// Replace a component definition under the same name
wildflower.unregister('editor-panel');
wildflower.component('editor-panel', { /* new definition */ });

wildflower.setHtmlSanitizer(fn)

Set a custom sanitizer function for data-bind-html content. When configured, all HTML rendered via data-bind-html is passed through this function before being set as innerHTML.

Parameters

• fn Function | null - Sanitizer function that accepts an HTML string and returns a sanitized HTML string, or null to disable sanitization

Example

// Using DOMPurify
wildflower.setHtmlSanitizer(html => DOMPurify.sanitize(html));

// Disable sanitization
wildflower.setHtmlSanitizer(null);

wildflower.registerAdapter(tagName, config)

Register an adapter for a custom element or web component. Adapters tell WildflowerJS how to read/write values and listen for changes on non-standard elements, enabling data-model and data-bind integration.

Parameters

• tagName string - Custom element tag name (e.g., 'sl-input')
• config Object - Adapter configuration
  • config.prop string - JS property name for reading/writing the element's value (default: 'value')
  • config.event string - Event name fired when the element's value changes (default: 'input')

Example

// Shoelace input
wildflower.registerAdapter('sl-input', {
    prop: 'value',
    event: 'sl-input'
});

// Shoelace checkbox
wildflower.registerAdapter('sl-checkbox', {
    prop: 'checked',
    event: 'sl-change'
});

wildflower.getAdapter(tagName, element?)

Retrieve the registered adapter for a given tag name. If no adapter is registered and an element instance is provided, auto-detects a sensible default for custom elements based on their capabilities.

Parameters

• tagName string - Custom element tag name
• element HTMLElement - Optional element instance for auto-detection

Returns

Object | undefined - Adapter config ({ prop, event }), or undefined if no adapter found

Example

const adapter = wildflower.getAdapter('sl-input');
if (adapter) {
    console.log(adapter.prop);   // 'value'
    console.log(adapter.event);  // 'sl-input'
}

wildflower.inspect(componentName?)

Inspect the running application or a specific component type. Logs a structured summary to the console and returns the data for programmatic use.

Parameters

• componentName string - Optional. If provided, inspects all instances of that component type.

Returns

• No argument: { components, stores }, component counts and store state snapshots
• With component name: ComponentInstance[], array of matching instances

Example

// Full application summary
const app = wildflower.inspect();
app.stores.cart.total;       // 149.97
app.components['nav-bar'];   // 1

// Inspect a specific component type
const widgets = wildflower.inspect('kpi-widget');
widgets[0].element;          // the DOM element
widgets[0].context;          // the ContextProxy

wildflower.version

The framework version string, stamped from the package version at build time. Available in every tier and build, minified or not, from 1.5.1 onward. Useful in bug reports and for checking which release a page is running.

Example

wildflower.version;   // '1.5.1'

wildflower.destroy()

Completely destroy the framework instance and all components.

Example

// Clean up when done
wildflower.destroy();