bareui-context

A small scope-based library for providing values to deeply nested components without prop drilling.

This package is designed to fit BareUI’s rendering model: values can be provided once at a subtree boundary and read anywhere below that boundary, with support for nested overrides and multiple independent scopes in the same component tree.

Public API

createScope<T>()

Creates a new named scope.

createScope<T>(name: string)

Creates a new named scope with no default value.

createScope<T>(name: string, defaultValue: ScopeInput<T>)

Creates a new named scope with a default value.

provide()

provide() creates a subtree-local value. Nested calls to the same scope override outer values only within their own subtree.

read()

Returns the nearest value for the current scope at the current render position. If a value was provided as a getter, read() resolves it when accessed.

peek()

Returns the current value if one exists, otherwise returns undefined.

has()

Returns true when the current scope has a resolved value in the current subtree.

Usage examples

Example nesting

A scope is independent from every other scope.

The same scope can be nested, and the nearest provider wins:

ThemeContext.provide('dark', () => html`
    <div>
        ${ThemeContext.provide('light', () => html`
            <Toolbar /> <!-- reads 'light' -->
        `)}
        <StatusBar /> <!-- reads 'dark' -->
    </div>
`);

Multiple scopes can intersect in the same subtree without interfering with one another.

Example: theme, auth, and locale together

import { component, html } from 'bareui-core';
import { createScope } from 'bareui-context';

type User = {
    name: string;
};

const ThemeContext = createScope<'light' | 'dark'>('light');
const AuthContext = createScope<User | null>(null);
const LocaleContext = createScope<'en' | 'ro'>('en');

const Toolbar = component(() => {
    const theme = ThemeContext.read();
    const user = AuthContext.read();
    const locale = LocaleContext.read();

    return html`
        <button data-theme="${theme}" data-locale="${locale}">
            ${user ? `Hello, ${user.name}` : 'Sign in'}
        </button>
    `;
});

const StatusBar = component(() => {
    const theme = ThemeContext.read();
    const locale = LocaleContext.read();

    return html`
        <div data-theme="${theme}" data-locale="${locale}">
            Status bar
        </div>
    `;
});

const App = component(() => {
    const currentUser: User = { name: 'Cristi' };

    return AuthContext.provide(currentUser, () =>
        ThemeContext.provide('dark', () =>
            LocaleContext.provide('en', () => html`
                <main>
                    ${ThemeContext.provide('light', () => html`
                        <Toolbar /> <!-- reads theme = light, auth = currentUser, locale = en -->
                    `)}
                    <StatusBar /> <!-- reads theme = dark, auth = currentUser, locale = en -->
                </main>
            `)
        )
    );
});

Getter-based values

Getter-based values are useful when the scope should resolve lazily from reactive state or any derived source:

const ThemeContext = createScope<'light' | 'dark'>(() => state.theme);

ThemeContext.provide(() => state.theme, () => html`
    <Toolbar />
`);

If you need to store a function as the actual value, wrap it in an object because bare functions are treated as getters.

Safe reads

Use peek() or optional() when you do not want a missing scope to throw:

const user = AuthContext.peek();
if (user) {
    // ...
}

Use has() when you only need to know whether a value exists in the current tree:

if (AuthContext.has()) {
    const user = AuthContext.read();
}