Lazy Components

Code-split with async loaders passed to x() — resolveAsyncValue, unwrapModule, isXViewTemplate.

import { html, x, renderApp } from 'mates';
import type { LazyComponent } from 'mates';

// Async loader — same shape as: async () => import('./Heavy')
const loadHeavy: LazyComponent = async () => {
  await new Promise((r) => setTimeout(r, 200));
  return (_p) => () => html`<p>Heavy ready</p>`;
};

const App = () => () => html`
  ${x(loadHeavy)}  <!-- x() detects async, resolves, then mounts -->
`;

renderApp(App, document.getElementById('app'));

Overview

A lazy component is an async function (or Promise/thenable) that resolves to a Component — or a module with a default export that is a Component. Pass it to x() exactly like an eager component: x(async () => import('./Heavy'), props).

When x() receives an async loader, Mates calls isAsyncValue, tears down any currently mounted view immediately (so the old page does not linger), then resolveAsyncValue → unwrapModule and assigns the sync Component. While loading, the host renders empty.

isXViewTemplate(value) returns true for TemplateResults produced by x() / view() / template() (branded with a shared Symbol). Useful for SSR helpers and tooling that must distinguish component embeddings from plain html results.

Eager vs lazy vs manual atom swap

Pattern	API	When
Eager	`x(Comp, props)`	Default — component already in the bundle.
Lazy (built-in)	`x(async () => import(…), props)`	Code-split at the import boundary. Same API as eager `x()`.
Manual swap	atom + `x(Comp(), {})`	Store a resolved constructor yourself — fine for demos; prefer LazyComponent for real splits.
Router	`component: async () => import(…)`	Same lazy resolution path as `x()`.

Lazy load with x()

Click Load chart — x(loadChart) detects the async function, waits, unwraps { default: Chart }, then mounts with props. In production, use async () => import('./Chart').

import { html, atom, x, renderApp } from 'mates';

const Chart = (propsFn) => () => html`

<p class="m-0">Chart · ${propsFn().label}</p>

</div>

// Simulates: async () => import('./Chart')

const loadChart = async () => {

await new Promise((r) => setTimeout(r, 500));

return { default: Chart };

};

const App = () => {

const show = atom(false);

return () => html`

Load chart

</button>

${show()

? x(loadChart, { label: 'Revenue' })

: html`<p class="muted m-t-5">Not loaded yet</p>`}

</div>

};

renderApp(App, document.getElementById('app'));

Swap lazy views + isXViewTemplate

Switching A/B tears down the previous view immediately and starts a new resolve. isXViewTemplate(x(...)) is true — plain html`...` is false.

import { html, atom, x, renderApp, isXViewTemplate } from 'mates';

const A = () => () => html`<p class="m-0">Panel A</p>`;

const B = () => () => html`<p class="m-0">Panel B</p>`;

const loadA = async () => {

await new Promise((r) => setTimeout(r, 300));

return A;

};

const loadB = async () => {

await new Promise((r) => setTimeout(r, 300));

return B;

};

const App = () => {

const which = atom('a');

return () => {

const viewTpl = which() === 'a' ? x(loadA) : x(loadB);

return html`

<button @click=${() => which.set('a')}>A</button>

<button class="btn-primary" @click=${() => which.set('b')}>B</button>

</div>

isXViewTemplate: ${String(isXViewTemplate(viewTpl))}

</p>

${viewTpl}

</div>

};

renderApp(App, document.getElementById('app'));

API — Lazy components

import { x, isXViewTemplate, resolveAsyncValue, isAsyncValue, unwrapModule } from 'mates'

Prop / Option	Type	Default	Description
`x(async () => import('./M'), props?)`*	`TemplateResult`	—	Pass a LazyComponent (async function returning Component or { default: Component }). x() detects async, clears current content, resolves, unwraps, then mounts like an eager component.
`LazyComponent<T>`	`() => Promise \| { default: Component }>`	—	Type for async loaders. Also accepted in Router config component fields.
`ComponentType<T>`	`Component \| LazyComponent`	—	Union accepted by x() / view() — eager or lazy in one parameter type.
`isAsyncValue(val)`	`boolean`	—	True for AsyncFunction, Promise, or thenable. Used internally by x() before resolve.
`resolveAsyncValue(val)`	`Promise`	—	Normalizes AsyncFunction \| Promise \| thenable into a Promise. If val is a function, it is invoked; otherwise treated as already thenable.
`unwrapModule(module)`	`any`	—	Returns module.default if present, otherwise module. Applied after resolveAsyncValue so both default-export and direct-Component returns work.
`isXViewTemplate(value)`	`boolean`	—	True when value is a TemplateResult created by x() / view() / template(). False for plain html`…`, null, etc.

Lazy loading behaviour

Prop / Option	Type	Default	Description
`While pending`	`empty host`	—	Previous view is torn down immediately; content is cleared until resolve succeeds.
`On reject`	`error path`	—	Load errors go through the component error handler (onError / default error card).
`Stale resolve`	`ignored`	—	If a newer view was assigned before an older promise settled, the older result is dropped.