Scopes

Hierarchical shared state from parent to descendants without prop drilling.

import { html, atom, scope, getParentScope, x } from 'mates';

class CounterScope {
  count = atom(0);
  increment() { this.count.set(n => n + 1); }
}

// Parent — register once in the outer function
const App = () => {
  scope(CounterScope);
  return () => html`${x(Child)}`;
};

// Descendant — retrieve nearest ancestor instance
const Child = () => {
  const counter = getParentScope(CounterScope);
  return () => html`
    <button @click=${counter.increment}>${counter.count()}</button>
  `;
};

// Built-in app chrome — import { utils } from 'mates' (after renderApp)
// utils.pathAtom(); utils.lsStore; utils.themeAtom;

Overview

Scopes share reactive state from a parent component to any descendant — at any depth — without prop drilling. The parent calls scope(ScopeClass) to instantiate and register a class; descendants call getParentScope(ScopeClass) to retrieve the nearest ancestor instance. Internally, retrieval bubbles a CustomEvent up the DOM tree.

Define atoms and mutation methods on the scope class. Methods are automatically bound so they can be passed as event handlers without losing this. An optional setup(propsFn) on the class receives the host component’s props function and can register lifecycle hooks (onMount, onCleanup, etc.).

App-wide utilities (router atoms, fetch client, storage bags, theme/title) live on the built-in MatesUtils store. Read them with utils (or useUtils()) — do not import those atoms as globals.

vs React Context

Aspect	Mates scope	Notes
Provide	`scope(Class)`	Instantiates the class on the host; available to all descendants.
Consume	`getParentScope(Class)`	Nearest ancestor match; throws if missing — no default value API.
Shape	Class instance	Atoms + methods on the instance; direct method calls instead of dispatch/reducers.

Both Display and Controls call getParentScope(CounterScope) — they both receive the same instance created by App's scope(CounterScope). Changes in Controls instantly reflect in Display, with no props passed between them.

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

// Define a scope class — atoms and methods live here

class CounterScope {

count = atom(0);

label = atom('Clicks');

increment() { this.count.set(n => n + 1); }

reset() { this.count.set(0); }

}

// Child component — reads from parent's scope

const Display = () => {

const counter = getParentScope(CounterScope);

return () => html`

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

<span class="label m-t-5">${counter.label()}</span>

</div>

};

// Another child — also reads from parent's scope

const Controls = () => {

const counter = getParentScope(CounterScope);

return () => html`

<button class="btn-ghost" @click=${counter.reset}>Reset</button>

</div>

};

// Parent — creates the scope

const App = () => {

const counter = scope(CounterScope); // creates scope in outer fn

Nested scopes shadow the parent

A child that calls scope(ThemeScope) creates a new instance. Descendants under that child see the nested instance; siblings under App still see the parent.

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

class ThemeScope {

accent = atom('teal');

setAccent(c) { this.accent.set(c); }

}

const Swatch = () => {

const theme = getParentScope(ThemeScope);

return () => html`

<div class="card card-body p-10 center"

style="border-color:${theme.accent()}">

<span class="label">accent=${theme.accent()}</span>

</div>

};

// Child provider — shadows parent's ThemeScope for its descendants

const NestedPanel = () => {

const theme = scope(ThemeScope); // fresh instance for this subtree

theme.accent.set('coral');

return () => html`

<p class="muted m-t-5">Nested scope (coral)</p>

${x(Swatch)}

</div>

};

const App = () => {

const theme = scope(ThemeScope);

return () => html`

<button class="btn-primary" @click=${() => theme.setAccent('teal')}>teal</button>

<button @click=${() => theme.setAccent('violet')}>violet</button>

API — scope, getParentScope & utils

import { scope, getParentScope, utils } from 'mates'

Prop / Option	Type	Default	Description
`scope(ScopeClass)`*	`InstanceType`	—	Instantiates ScopeClass (atoms allowed as class fields), optionally runs setup(propsFn), and registers the instance on the host element for all descendants. Must be called in the outer (setup) function. Returns the instance.
`getParentScope(ScopeClass)`*	`InstanceType`	—	Retrieves the nearest ancestor scope of the given class by bubbling a DOM event up the tree. Throws if no matching provider is found. Call in the consumer’s outer function.
`getScope(ScopeClass)`	`InstanceType`	—	Alias for getParentScope — same nearest-ancestor lookup.
`utils`	`MatesUtils`	—	Window proxy to the app MatesUtils store (router, fetch, storage, theme, title). Created by renderApp. Full member table: /docs/state/use-utils.
`useUtils()`	`MatesUtils`	—	Same store as utils. Outer-only. Prefer utils outside components.

ScopeClass shape

Prop / Option	Type	Default	Description
`atoms (class fields)`	`AtomType`	—	Declare reactive state as atom() class fields (including derived atom(() => …)). They are shared reactively across every component that reads the scope.
`methods`	`() => void`	—	Mutation methods on the class are auto-bound — safe to pass directly as event handlers without .bind(). Prefer methods over reaching into atoms from distant call sites.
`setup(propsFn)`	`void`	—	Optional lifecycle hook on the class. Receives the host component’s props function. Can register onMount / onCleanup. Must be synchronous — async setup is not awaited.

Built-in MatesUtils (via utils) — summary

Prop / Option	Type	Default	Description
`pathAtom / qsAtom / hashAtom / paramsAtom`	`atoms`	—	Router URL state and matched route params. See /docs/state/use-utils and router docs.
`fetchClient / intercept*`	`FetchClient`	—	Scoped HTTP client and interceptor hooks shared across the app tree.
`lsStore / ssStore`	`StorageAtomType`	—	Shared storage bags — dedicated page /docs/state/storage.
`themeAtom / titleAtom`	`atoms`	—	Theme and document.title — dedicated page /docs/state/theme-title.

Overview

vs React Context

Sharing state across child components

Nested scopes shadow the parent