@repobit/dex-store-elements 1.7.3 → 2.0.1

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

@@ -0,0 +1,179 @@
+import type { BdComputeScan } from '../compute/compute.scan.js';
+import type { ProductOption } from '@repobit/dex-store';
+import { LitElement, type PropertyValues, type TemplateResult } from 'lit';
+export declare const BD_NODE_REGISTER_EVENT: "bd-node-register";
+export declare const BD_NODE_TRACK_WORK_EVENT: "bd-node-track-work";
+/**
+ * String brand used as a fallback in case instanceof is not enough.
+ * For example, this can help if the package is bundled more than once.
+ */
+export declare const BD_NODE_ELEMENT_BRAND: "__bdNodeElement__";
+export interface BdNodeRegisterEventDetail {
+    node: BdNodeElement;
+}
+export interface BdNodeTrackWorkEventDetail<T = unknown> {
+    key: unknown;
+    work: PromiseLike<T>;
+}
+export declare function dispatchBdNodeTrackWork<T>(target: EventTarget, key: unknown, work: PromiseLike<T>): boolean;
+declare global {
+    interface HTMLElementEventMap {
+        [BD_NODE_REGISTER_EVENT]: CustomEvent<BdNodeRegisterEventDetail>;
+        [BD_NODE_TRACK_WORK_EVENT]: CustomEvent<BdNodeTrackWorkEventDetail>;
+    }
+}
+export declare function isBdNodeElement(value: unknown): value is BdNodeElement;
+/**
+ * Base class for all bd-* nodes.
+ *
+ * Responsibilities:
+ * - discovers the nearest logical BdNodeElement parent;
+ * - keeps a set of logical BdNodeElement children;
+ * - tracks local async work;
+ * - makes updateComplete wait for the whole logical subtree;
+ * - owns the set of native action elements in its logical subtree
+ *   (topology), fed incrementally by BdActionElementAdapter announcements.
+ *
+ * It does NOT know about:
+ * - product ids;
+ * - price clients;
+ * - scope;
+ * - @consume / @provide;
+ * - binding data attributes.
+ *
+ * Those belong in BdScopedElement, controllers, or concrete nodes.
+ */
+export declare abstract class BdNodeElement extends LitElement {
+    readonly [BD_NODE_ELEMENT_BRAND] = true;
+    topologyBoundary: boolean;
+    private readonly _bdChildren;
+    private _bdParent?;
+    /**
+     * Latest local work per key.
+     *
+     * If the same key is tracked again, the new promise replaces the old one.
+     * This is important for @lit/task-like flows where old work can be aborted
+     * or made obsolete by newer args.
+     */
+    private readonly _localWork;
+    private _childrenRevision;
+    private readonly _childrenRevisionWaiters;
+    private _workRevision;
+    private readonly _workRevisionWaiters;
+    private readonly _actionTopology;
+    /**
+     * Default render for infrastructure bd-* nodes.
+     *
+     * Subclasses can override this if they need their own template.
+     */
+    protected render(): TemplateResult;
+    protected willUpdate(changedProperties: PropertyValues<this>): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected get bdParent(): BdNodeElement | undefined;
+    protected get bdChildren(): ReadonlySet<BdNodeElement>;
+    /**
+     * Revision that changes whenever the set of action elements anywhere in this
+     * node's logical subtree changes. Use this as a compute input.
+     */
+    get actionTopologyRevision(): number;
+    /**
+     * Action elements owned directly by this node (not descendants).
+     */
+    get localActionElements(): readonly HTMLElement[];
+    /**
+     * All action elements reachable from this node, unioned across the logical
+     * bd subtree. Walks the bd tree (tiny), not arbitrary DOM.
+     */
+    collectActionElements(): HTMLElement[];
+    /**
+     * Collected compute declarations for action elements reachable from this
+     * node. These are owned by topology so compute does not rescan DOM actions.
+     */
+    collectActionScans(): BdComputeScan[];
+    /**
+     * Resolved option seeds reachable from this node, unioned across the logical
+     * bd subtree. Each option carries its product via option.getProduct().
+     */
+    collectOptionSeeds(): ProductOption[];
+    protected setLocalOptionSeed(option: ProductOption | undefined): void;
+    protected get hasLocalWork(): boolean;
+    protected get localWorkCount(): number;
+    /**
+     * Promise that resolves when all CURRENT local work is complete.
+     *
+     * This is intentionally separate from updateComplete.
+     *
+     * localComplete:
+     *   current node async work only
+     *
+     * updateComplete:
+     *   current node + local work + logical children
+     *
+     * Loops while a newer `trackLocalWork` replaces tracked work
+     * (`_awaitCurrentLocalWorkComplete` returns `false` on revision
+     * change). The mirror of `getUpdateComplete`'s contract — a
+     * single `await` cannot catch the replacement because the
+     * replacement bumps `_workRevision` and clears the existing
+     * slot, so the earlier await's "all stable" signal is no
+     * longer trustworthy.
+     */
+    protected get localComplete(): Promise<void>;
+    private _awaitLocalCompleteLoop;
+    /**
+     * Tracks local async work.
+     *
+     * Use this from Task / BdResolveController:
+     *
+     *   task: (args, context) => {
+     *     const work = this.resolveAndPublish(args, context.signal);
+     *     return this.trackLocalWork(this._workKey, work);
+     *   }
+     *
+     * Important:
+     * - the promise should include resolve + commit/publish;
+     * - do not await this.updateComplete inside this promise;
+     * - old work with the same key is replaced by newer work.
+     */
+    trackLocalWork<T>(key: unknown, work: PromiseLike<T>): Promise<T>;
+    /**
+     * Hook for subclasses that need to react when a logical child is adopted.
+     */
+    protected onBdChildConnected(_child: BdNodeElement): void;
+    /**
+     * Hook for subclasses that need to react when a logical child is removed.
+     */
+    protected onBdChildDisconnected(_child: BdNodeElement): void;
+    /**
+     * This is the important part.
+     *
+     * Awaiting updateComplete on any bd node means:
+     *
+     *   1. this element's Lit update is complete;
+     *   2. this element's local async work is complete;
+     *   3. any update caused by local work / publishScope is complete;
+     *   4. all logical bd children are updateComplete;
+     *   5. the tree did not change while we were waiting.
+     */
+    protected getUpdateComplete(): Promise<boolean>;
+    private _registerWithNearestBdParent;
+    private readonly _onBdNodeRegister;
+    private readonly _onBdNodeTrackWork;
+    private _adoptBdChild;
+    private _removeBdChild;
+    private _clearBdChildren;
+    /**
+     * Fallback adoption for already-upgraded descendants in light DOM.
+     *
+     * This does not cross arbitrary shadow roots. The event-based registration
+     * handles the composed/shadow case.
+     */
+    private _adoptExistingLightDomBdChildren;
+    private _isNearestLightDomBdParentOf;
+    private _awaitCurrentLocalWorkComplete;
+    private _awaitCurrentBdChildrenComplete;
+    private _createChildrenRevisionWait;
+    private _createWorkRevisionWait;
+    private _bumpChildrenRevision;
+    private _bumpWorkRevision;
+}