Context & x-provider

Lightweight DI with Context, useContext, and the x-provider custom element — vs scopes.

import { html, x, Context, useContext, renderApp } from 'mates';

// Module-level context key (typed token — not the value itself)
const ThemeCtx = new Context();

const Child = () => {
  // Outer only — needs an active host to bubble request-context
  const theme = useContext(ThemeCtx);
  return () => html`<p>Theme: ${theme}</p>`;
};

const App = () => () => html`
  <x-provider .context=${ThemeCtx} .value=${'dark'}>
    ${x(Child)}
  </x-provider>
`;

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

Overview

Context<T> is a lightweight token (new Context()) with a unique id. It does not hold the live value — the value lives on an ancestor <x-provider> via .context and .value properties.

useContext(ctx) must run with an active component host (typically the outer function). It dispatches a bubbling request-context event; the nearest matching x-provider stops propagation and resolves with its .value. Missing provider → null (no throw).

vs scopes: scopes (scope(Class) / getParentScope) are class instances with atoms and methods — preferred for shared reactive UI state. Context is better for simple value injection (theme string, config object, or an atom reference) without defining a class.

Context vs scopes

Aspect	Context + x-provider	scope()
Provide	`<x-provider .context .value>`	`scope(ScopeClass)` in outer function
Consume	`useContext(ctx)`	`getParentScope(Class)`
Missing provider	returns `null`	throws at runtime
Best for	Simple values / atom refs	Atoms + methods + optional setup()
Nesting	Closest provider wins	Child scope shadows parent for same class

Provide and consume

Badge inside x-provider reads 'dark'. The sibling Badge outside the provider gets null and shows 'none'.

import { html, x, Context, useContext, renderApp } from 'mates';

const ThemeCtx = new Context();

const Badge = () => {

const theme = useContext(ThemeCtx);

return () => html`

<span class="tag tag-soft">theme: ${theme ?? 'none'}</span>

};

const App = () => () => html`

<x-provider .context=${ThemeCtx} .value=${'dark'}>

${x(Badge)}

</x-provider>

${x(Badge)}

</div>

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

Share an atom via Context

Pass the atom itself as .value. Display and Controls both useContext(CountCtx) and read/write count() — reactive without a scope class.

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

const CountCtx = new Context();

const Display = () => {

const count = useContext(CountCtx);

return () => html`

<h1>${count()}</h1>

};

const Controls = () => {

const count = useContext(CountCtx);

return () => html`

<button class="btn-primary" @click=${() => count.set(n => n + 1)}>+1</button>

};

const App = () => {

const count = atom(0);

return () => html`

<x-provider .context=${CountCtx} .value=${count}>

${x(Display)}

${x(Controls)}

</div>

</x-provider>

</div>

};

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

API — Context, useContext, x-provider

import { Context, useContext } from 'mates'

Prop / Option	Type	Default	Description
`new Context<T>()`*	`Context`	—	Creates a typed context token with a unique id. Create once at module scope and share the same instance between providers and consumers.
`context.id`	`string`	—	Random id used by x-provider to match request-context events. Assigned on construction.
`useContext(context)`	`T \| null`	—	Bubbles request-context from the current host. Nearest x-provider with matching context.id resolves with its .value. Returns null if no provider. Requires an active component host.
`<x-provider>`	`HTMLElement`	—	Custom element (auto-registered). Listens for request-context while connected. Set .context and .value from the parent template.
`.context=${ctx}`	`Context`	—	Property — sets the provider element id to ctx.id so matching consumers resolve here.
`.value=${val}`	`T`	—	Property — the value returned to matching useContext calls. May be a primitive, object, or atom reference.

Nesting & matching

Prop / Option	Type	Default	Description
`Closest wins`	`DOM bubble`	—	The nearest ancestor x-provider with the same context id stops the event and resolves. Outer providers are shadowed for that token.
`Different Context instances`	`independent`	—	Two new Context() tokens never match each other — always share the same Context instance.