@repobit/dex-store-elements 1.7.2 → 2.0.0

package/dist/src/core/node.scope.d.ts

@@ -0,0 +1,374 @@
+import type { BdComputeResult } from '../compute/compute.expand.js';
+import { BdScope, type BdDataLayerFn, type BdScopeChangeFn, type BdScopeDeriveFn } from '../contexts/context.scope.js';
+import { BdComputeController } from '../controllers/controller.compute.js';
+import { type BdTransition } from '../core/actions.js';
+import type { EtaMutationBatchSchedule } from '../eta/types.js';
+import { type TemplateOptionContext, type TemplateProductContext, type TemplateStateContext } from '../renders/context.js';
+import type { Store } from '@repobit/dex-store';
+import type { PropertyValues } from 'lit';
+import { BdNodeElement } from './node.element.js';
+/**
+ * The shape templates see under a `BdScopedElement`.
+ *
+ * Mirrors the v1 `it.*` layout: `option` / `product` / `state` are flattened
+ * DTOs with pre-formatted strings, and `ctx` is an alias of `state`. Adding
+ * a new field here is a public surface change (every consumer can read it),
+ * so prefer extending `TemplateDslContext` and rebinding this snapshot
+ * rather than spreading the raw `BdScope` object.
+ *
+ * `derived` carries whatever object `scope.derived({...})` returned for the
+ * current scope — templates read derived properties as `<%= it.derived.foo
+ * %>`. `undefined` when the scope has no `derived` factory.
+ */
+export type BdScopedTemplateContext = {
+    store: Store | undefined;
+    product: TemplateProductContext | undefined;
+    option: TemplateOptionContext | undefined;
+    state: TemplateStateContext | undefined;
+    ctx: TemplateStateContext | undefined;
+    derived: Readonly<Record<string, unknown>> | undefined;
+};
+export declare abstract class BdScopedElement extends BdNodeElement {
+    #private;
+    private readonly scopedValueKeys;
+    protected computeResult?: BdComputeResult;
+    readonly compute: BdComputeController;
+    /**
+     * Owning boundary for the Eta template index.
+     *
+     * `BdScopedElement` IS the index root — every nested template
+     * is owned by the closest enclosing bd-* node, and that node
+     * in turn owns the controller that renders its subtree.
+     */
+    get root(): Element;
+    /**
+     * Eta template controller that renders the subtree against the
+     * current scope and compute result.
+     *
+     * Args trigger a re-render when the scope, the compute result,
+     * or the eta-enabled flag change. The render is gated on
+     * `isEtaEnabled` so a disabled scope does not flicker
+     * intermediate state.
+     *
+     * The context exposes **only** `store`, `product`, `option`,
+     * and `state` — exactly the fields templates are expected to
+     * reference. We do not spread the full scope, do not surface
+     * `$scope` / `$state` handles, and do not leak the transition
+     * object. New fields belong on `BdScope` plus an explicit
+     * binding here so the public template surface stays auditable.
+     *
+     * The boundary predicate uses raw tag names so nested
+     * `bd-context` / `bd-product` / `bd-option` nodes
+     * keep their own controllers and templates do not leak across
+     * scope boundaries. Tag-name checks are stable before custom
+     * element upgrade — `EtaTemplateControllerOptions.isBoundaryElement`
+     * MUST work on raw DOM shape.
+     */
+    readonly eta: import("../eta/controller.js").EtaTemplateController<readonly [scope: Readonly<Partial<{
+        store: Store;
+        product: import("@repobit/dex-store").Product;
+        option: import("@repobit/dex-store").ProductOption;
+        transition: BdTransition;
+        computeDisabled: boolean;
+        etaDisabled: boolean;
+        derived: BdScopeDeriveFn;
+        mutationBatchSchedule: EtaMutationBatchSchedule;
+        onScopeChange: BdScopeChangeFn;
+        dataLayer: BdDataLayerFn;
+    }>> | undefined, compute: Readonly<{
+        min: number;
+        max: number;
+        minFormatted: string;
+        maxFormatted: string;
+        scenarios: number;
+        price: import("../compute/compute.expand.js").BdComputeMonthlyRange;
+        discountedPrice: import("../compute/compute.expand.js").BdComputeMonthlyRange;
+        discount: import("../compute/compute.expand.js").BdComputeDiscountRange;
+    }> | undefined], BdScopedTemplateContext>;
+    etaDisabled: boolean;
+    protected get isEtaEnabled(): boolean;
+    computeDisabled: boolean;
+    protected parentScope?: BdScope;
+    protected providedScope?: BdScope;
+    protected get currentScope(): BdScope | undefined;
+    protected get isComputeEnabled(): boolean;
+    /**
+     * Comma-separated list of event ids to ignore.
+     *
+     * Pair with `data-store-event-id` on action elements: any transition
+     * whose command carries a matching `eventId` is dropped before it can
+     * drive this node (or any of its descendants, since the cascade is
+     * gated here).
+     *
+     * Example:
+     * ```html
+     * <button data-store-action
+     *         data-store-event-id="devicesBtn"
+     *         data-store-set-devices="25">25</button>
+     *
+     * <bd-option ignore-events="devicesBtn, subscriptionBtn">
+     *   ...
+     * </bd-option>
+     * ```
+     */
+    ignoreEvents?: string;
+    /**
+     * When set, this node only reacts to events originating inside its own
+     * subtree. Cascading transitions from `parentScope.transition` are
+     * dropped, mirroring v1's `<bd-state ignore-events-parent>` semantics.
+     *
+     * `<bd-context>` enables this by default (it is a hard event boundary).
+     */
+    ignoreEventsParent: boolean;
+    protected get ignoredEventIds(): ReadonlySet<string>;
+    /**
+     * Filter callback handed to each node's `BdActionResolveController`.
+     *
+     * Drops transitions whose `eventId` matches an entry in `ignore-events`,
+     * and — when `ignore-events-parent` is set — drops any cascade from a
+     * parent scope. Concrete nodes pass `filterTransition: (c) =>
+     * this._filterTransition(c)` into their controller config; the
+     * controller invokes this for both local `bd-action-request` events
+     * and inherited transitions.
+     */
+    protected _filterTransition(candidate: {
+        transition: BdTransition;
+        source: 'local' | 'parent';
+    }): boolean;
+    protected publishScope(nextScope: BdScope): BdScope;
+    private buildScopeChangeSnapshot;
+    /**
+     * Fires `onScopeChange` for compute-result-only transitions.
+     *
+     * `BdComputeController.onResult` writes `computeResult`, which
+     * is part of the published snapshot's `state`. Without this
+     * trigger, consumers watching the snapshot would miss compute
+     * state changes that are not accompanied by a scope publish
+     * or clear. Targeted invocation keeps the contract in one
+     * place: `publishScope()` and `clearScope()` keep their own
+     * paths; this helper handles the compute-only path.
+     *
+     * Idempotent: no-op when no scope has been published yet
+     * (the hook is not on any scope) or when the snapshot's
+     * `state` did not actually change (caller short-circuits via
+     * `Object.is` before calling).
+     */
+    private _fireOnScopeChangeForCompute;
+    private snapshotsEqual;
+    private scopeWithoutOwnedValues;
+    private updateScopedValueKeys;
+    private updateScopedValueKey;
+    protected clearScope(): void;
+    protected requireParentScope(): BdScope;
+    /**
+     * Single-pass overlay applied to every published scope.
+     *
+     * The pass runs in two phases:
+     *
+     * 1. **Sparse boolean flags** — `computeDisabled` and
+     *    `etaDisabled`. Reflected from `isComputeEnabled` /
+     *    `isEtaEnabled` (the inverse of "is enabled").
+     * 2. **Value overlays** — `derived` and
+     *    `mutationBatchSchedule`. Caller-supplied values win; the
+     *    per-instance property fills in when the caller did not
+     *    supply one.
+     *
+     * Both phases share the same lazy-allocation strategy: a new
+     * scope object is only created when at least one phase has a
+     * write to perform. A scope with nothing to merge is returned
+     * by reference, which lets `publishScope`'s `Object.is` check
+     * short-circuit the downstream `@provide` notification.
+     */
+    private applyScopedFlags;
+    /**
+     * Per-instance derived Eta context factory.
+     *
+     * Users supply this on any bd-* node (via constructor,
+     * attribute, or `instance.derived = fn`) to expose additional
+     * template bindings under the `derived` key. The factory
+     * receives `{ store, product, option }` and returns an object
+     * whose properties become available to templates as
+     * `<%= it.derived.<key> %>`.
+     *
+     * `publishScope` merges this property into the published scope
+     * automatically when the caller did not supply an explicit
+     * `derived` of its own — so a user just needs to assign
+     * `node.derived = fn` (or set the `derived` attribute) and
+     * the factory becomes part of the scope for free.
+     *
+     * Reactivity: the field is a Lit `@property`, so reassigning
+     * `this.derived = newFactory` triggers `requestUpdate()` and a
+     * re-publish via `willUpdate`. Method references declared
+     * once per instance are stable, so the `@lit/task` args
+     * comparison short-circuits re-renders for unrelated changes.
+     *
+     * `derived` is intended to be supplied by users at the call
+     * site, not declared on concrete node subclasses. Subclasses
+     * that need a static default can still assign it in their
+     * constructor; the merge step lets callers override.
+     *
+     * @example
+     *
+     * ```ts
+     * const product = document.createElement('bd-product');
+     * product.productId = 'acrobat-pro';
+     * product.derived = ({ product, option }) => ({
+     *   canBuy     : Boolean(product && option),
+     *   hasDiscount: Boolean(option?.discounted)
+     * });
+     * ```
+     *
+     * Or via plain JS (recommended — functions cannot be authored
+     * as attribute strings):
+     *
+     * ```ts
+     * const product = document.createElement('bd-product');
+     * product.productId = 'acrobat-pro';
+     * product.derived = ({ product, option }) => ({
+     *   canBuy     : Boolean(product && option),
+     *   hasDiscount: Boolean(option?.discounted)
+     * });
+     * ```
+     *
+     * The attribute mapping is intentionally omitted — Lit's
+     * default converter cannot turn a string into a typed
+     * function, so the property is JS-only. Hosts that want
+     * attribute-driven configuration should expose a wrapper
+     * attribute on their own subclass and assign `derived` from
+     * the wrapper's converter.
+     */
+    derived?: BdScopeDeriveFn;
+    /**
+     * Per-instance mutation batch schedule.
+     *
+    * Wired through the scope so descendants can read the same
+    * value via `parentScope.mutationBatchSchedule`. Existing Eta
+    * controllers receive a resolver callback, so flipping the
+    * schedule after connection affects future mutation flushes
+    * once the parent republishes its scope.
+     *
+     * Accepted via constructor / `instance.mutationBatchSchedule =
+     * 'idle'`. The attribute mapping is intentionally omitted
+     * because Lit's default converter is happy with the string
+     * union, but exposing it as an attribute would invite the
+     * same authoring pitfalls we deliberately avoid for
+     * `derived` (callers writing `schedule="animation-frame"`
+    * without realising the value is scope-driven rather than an
+    * imperative one-shot switch).
+     *
+     * @example
+     *
+     * ```ts
+     * const product = document.createElement('bd-product');
+     * product.productId = 'acrobat-pro';
+     * product.mutationBatchSchedule = 'microtask';
+     * ```
+     */
+    mutationBatchSchedule?: EtaMutationBatchSchedule;
+    /**
+     * Per-instance scope-change hook.
+     *
+     * Fired whenever this node's effective published scope changes
+     * — both when `publishScope(...)` produces a new normalized
+     * scope reference, and when `clearScope()` removes the
+     * scope. The hook receives a narrow snapshot exposing only
+     * `store`, `product`, `option`, and `state` — the four fields
+     * that drive template rendering. It does NOT receive the
+     * transition, the disabled flags, the derived factory, or the
+     * mutation batch schedule.
+     *
+     * Wired through `BdScope.onScopeChange` like `derived` and
+     * `mutationBatchSchedule`, so descendants can read the
+     * inherited hook from `parentScope.onScopeChange` and a child
+     * can override its ancestor's hook by assigning its own.
+     *
+     * Attribute mapping is intentionally omitted — functions
+     * cannot be represented as attribute strings, and a stale or
+     * stale-shaped `on-scope-change="..."` attribute would invite
+     * the same authoring pitfalls we deliberately avoid for
+     * `derived`. Configure via JS instead:
+     *
+     * @example
+     *
+     * ```ts
+     * const product = document.createElement('bd-product');
+     * product.productId = 'acrobat-pro';
+     * product.onScopeChange = ({ store, product, option, state }) => {
+     *   console.log('scope changed', { store, product, option, state });
+     * };
+     * ```
+     */
+    onScopeChange?: BdScopeChangeFn;
+    /**
+     * Inherited callback for option-load data-layer events.
+     * Configure it as a JavaScript property; functions are not
+     * represented as attributes.
+     */
+    dataLayer?: BdDataLayerFn;
+    /**
+     * Per-instance store reference.
+     *
+     * When set on any `BdScopedElement` subclass, the value is published
+     * into the scope context via `createBdStoreScope(this.store)` so
+     * descendants can consume it from `parentScope.store`. Setting it back
+     * to `undefined` calls `clearScope()` to remove the published scope;
+     * flipping from one store to another re-publishes the existing scope
+     * with the new reference.
+     *
+     * The store-property publish is intentionally additive — it does not
+     * replace the existing `BdActionResolveController` flow used by
+     * `bd-context`, `bd-product`, and `bd-option`. Those controllers
+     * capture their own transition for the action-request path; the store
+     * scope is purely a value-publish surface.
+     *
+     * @example
+     *
+     * ```ts
+     * const root = document.createElement('bd-context');
+     * root.store = myStore;
+     * // descendants under <bd-context> now see { store: myStore }
+     * // via parentScope.store.
+     *
+     * // Clear the published scope
+     * root.store = undefined;
+     * ```
+     *
+     * The attribute mapping is intentionally omitted — Lit's default
+     * converter cannot turn a string into a `Store` instance, and
+     * serializing a store to an attribute would defeat the point of
+     * holding it as a typed reference. Configure via JS instead, the
+     * same way `derived` and `onScopeChange` are configured.
+     */
+    store?: Store;
+    /**
+     * Publishes or clears the scope for a `store` property change.
+     *
+     * Single entry point for the three transitions `store` can drive:
+     *
+     * 1. `store` is `undefined` → `clearScope()` removes the published
+     *    scope and fires the `onScopeChange` hook with all-undefined
+     *    fields.
+     * 2. `store` is defined and a scope is already published →
+     *    re-publishes the existing scope with the new store reference
+     *    (the rest of the scope — `derived`, `mutationBatchSchedule`,
+     *    `onScopeChange`, flags — is preserved).
+     * 3. `store` is defined and no scope is published yet → publishes a
+     *    fresh `createBdStoreScope(this.store)` so the first descendant
+     *    read sees a non-undefined `parentScope.store`.
+     *
+     * Called from `willUpdate` whenever `changedProperties.has('store')`.
+     * Idempotent: re-publishing the same scope reference is a no-op for
+     * the `@provide` notification because `publishScope` already short-
+     * circuits on `Object.is(this.providedScope, normalizedScope)`.
+     */
+    protected publishStoreScope(): void;
+    protected willUpdate(changedProperties: PropertyValues<this>): void;
+}
+/**
+ * Parses the comma-separated `ignore-events` attribute into a set of ids.
+ *
+ * Empty entries are skipped so `"foo, ,bar"` produces `{ foo, bar }`.
+ * The function is exported so test code can compare against the same
+ * parsing rules the runtime uses.
+ */
+export declare function parseIgnoreEvents(value: string | undefined): ReadonlySet<string>;