Lime Web Components API Documentation - v6.24.0
    Preparing search index...

    Interface ContextRegistryAlpha

    Central place for ambient context: registration, DOM-walked provider lookup, direct key lookup, reactive subscription, and scope construction.

    This package only describes the contract; the actual behavior is supplied by an implementation, reached through the platform service contextRegistry.

    What the API does, by area:

    • Registration. register declares a context key once at bootstrap and accepts an optional session-wide fallback. list enumerates registered keys.
    • Per-host providers. provide attaches a value source to a host element. Two copies of the same component in different parts of the page each get their own value without interfering.
    • Pull (snapshot reads). get returns the resolved value once. Used by rule evaluation and any caller that wants a value on demand.
    • Push (reactive subscription). * | subscribe delivers the current value immediately and again on every change. Used by reactive consumers that drive component re-renders without polling.
    • Scope construction. scope binds a host plus optional overrides into a ContextScope that answers get(key) repeatedly. Used by rule evaluation, command guards, filter predicates, and anything else that wants a pre-bound view of ContextMap.

    Each key resolves in order from most specific to least: the closest DOM ancestor that registered a value through provide wins first, then a session-wide fallback registered through register. If neither answers, the resolved value is undefined.

    Snapshot read

    const registry = platform.get(PlatformServiceName.ContextRegistry);
    const user = registry.get('user', this.host);

    Reactive subscription

    const stop = registry.subscribe('user', this.host, (user) => {
        this.user = user;
    });

    Building a scope

    const scope = registry.scope({ host: this.host });
    const user = scope.get('user');
    interface ContextRegistry {
        get<K extends keyof ContextMap>(
            key: K,
            host?: HTMLElement,
        ): ContextMap[K];
        list(): ContextMetadata<keyof ContextMap>[];
        provide<K extends keyof ContextMap>(
            key: K,
            host: HTMLElement,
            getter: () => ContextMap[K],
        ): ContextProviderHandle;
        register<K extends keyof ContextMap>(
            metadata: ContextMetadata<K>,
            fallback?: () => ContextMap[K],
        ): void;
        scope(options?: ContextScopeOptions): ContextScope;
        subscribe<K extends keyof ContextMap>(
            key: K,
            host: HTMLElement,
            listener: (value: ContextMap[K]) => void,
        ): () => void;
    }
    Index

    Methods

    get list provide register scope subscribe

    Methods

    • Alpha

      Snapshot read of a context value.

      Resolves key against the DOM ancestors of host first, then the session-wide fallback. Returns undefined when no provider answers.

      Type Parameters

      Parameters

      • key: K

        The context to resolve.

      • Optionalhost: HTMLElement

        Element to start the ancestor walk from. When omitted, only the session-wide fallback is consulted.

      Returns ContextMap[K]

      The resolved value, or undefined when no provider answers.

    • Alpha

      Attach a value source for a context key to a host element. Typically called during a component's lifetime.

      When something later resolves key against a host that is a descendant of this element, the closest ancestor that registered a provider wins.

      Reactive providers call notify() on the returned handle when their underlying value changes. Non-reactive providers ignore notify and only call teardown() on disconnect.

      Type Parameters

      • K extends keyof ContextMap

        The context id. Pinning it to a known key makes getter's return type match the key's value type.

      Parameters

      • key: K

        The context this provider answers.

      • host: HTMLElement

        Element to attach the provider to.

      • getter: () => ContextMap[K]

        Returns the current value. Called every time a walk hits this provider, so keep it cheap. May return undefined when no value is currently available; the walk then continues to the next provider.

      Returns ContextProviderHandle

      A handle exposing teardown and notify. Call teardown from disconnectedCallback (or equivalent) to detach the provider.

    • Alpha

      Declare that a context key exists. Called once per key at bootstrap.

      The optional fallback is a session-wide value source, used when no DOM ancestor has supplied a value. Good for keys that are the same for the whole session, like the current user or device.

      Compare with provide, which supplies a value scoped to a specific host element.

      Type Parameters

      • K extends keyof ContextMap

        The context id. Tying it to a known key makes the fallback's return type match the key's value type.

      Parameters

      • metadata: ContextMetadata<K>

        Metadata for the key (id, label, description).

      • Optionalfallback: () => ContextMap[K]

        Optional session-wide value source. May return undefined when no value is currently available; treated the same as no fallback being registered.

      Returns void

    • Alpha

      Build a ContextScope, a host-bound typed view that resolves ContextMap keys on demand. The only supported way to construct one.

      • Pass host to walk the DOM from there. Typical for components.
      • Pass with to hand in fixed values. Typical for tests and headless code.
      • Pass both to walk the DOM with overrides for specific context keys.
      • Pass nothing for an empty scope where every get returns undefined.

      Rules are one consumer of ContextScope (a rule predicate reads from one), but command guards, filter predicates, and anything else that wants "bind a host plus overrides once, then read keys repeatedly" builds a scope the same way.

      Parameters

      Returns ContextScope

      A new scope.

    • Alpha

      Subscribe to changes of a context value.

      The listener fires immediately with the current value and again whenever the resolved value changes. The immediate fire is synchronous, the listener is invoked before subscribe returns. Returns a teardown function to stop the subscription.

      Reactive providers signal changes through notify. A subscription also re-evaluates when providers are added or removed along the ancestor chain.

      Type Parameters

      Parameters

      • key: K

        The context to observe.

      • host: HTMLElement

        Element to anchor the subscription to. Pass undefined to only consult the session-wide fallback.

      • listener: (value: ContextMap[K]) => void

        Called immediately with the current value and again on every change.

      Returns () => void

      Teardown function to stop the subscription.

    Settings

    Member Visibility

    On This Page

    Methods