@repobit/dex-store-elements 1.7.2 → 2.0.0

package/dist/src/core/actions.js

@@ -0,0 +1,47 @@
+export const BD_ACTION_REQUEST_EVENT = 'bd-action-request';
+let bdTransitionSeq = 0;
+export function createBdTransition(detail, originNode) {
+    return {
+        seq: ++bdTransitionSeq,
+        command: detail.command,
+        originNode,
+        createdAt: Date.now()
+    };
+}
+export function dispatchBdActionRequest(eventTarget, detail) {
+    return eventTarget.dispatchEvent(new CustomEvent(BD_ACTION_REQUEST_EVENT, {
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+        detail
+    }));
+}
+export function isBdActionRequestEvent(event) {
+    if (event.type !== BD_ACTION_REQUEST_EVENT) {
+        return false;
+    }
+    const detail = event.detail;
+    return (typeof detail === 'object' &&
+        detail !== null &&
+        'command' in detail);
+}
+/**
+ * Pulls the optional `eventId` off the command carried by a transition.
+ *
+ * `eventId` is set on the action element via `data-store-event-id="…"` and
+ * is the matching key for the `ignore-events="…"` attribute on `bd-*`
+ * provider elements. Returns `undefined` for commands that did not declare
+ * one.
+ */
+export function getCommandEventId(command) {
+    return command.kind === 'set-action'
+        ? command.action.eventId
+        : command.update.eventId;
+}
+/**
+ * Convenience wrapper around {@link getCommandEventId} for transitions.
+ */
+export function getTransitionEventId(transition) {
+    return getCommandEventId(transition.command);
+}
+//# sourceMappingURL=actions.js.map

package/dist/src/core/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../../src/core/actions.ts"],"names":[],"mappings":"AA6CA,MAAM,CAAC,MAAM,uBAAuB,GAClC,mBAA4B,CAAC;AAY/B,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB,MAAM,UAAU,kBAAkB,CAChC,MAA6B,EAC7B,UAA+B;IAE/B,OAAO;QACL,GAAG,EAAQ,EAAE,eAAe;QAC5B,OAAO,EAAI,MAAM,CAAC,OAAO;QACzB,UAAU;QACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,WAAwB,EACxB,MAA6B;IAE7B,OAAO,WAAW,CAAC,aAAa,CAC9B,IAAI,WAAW,CACb,uBAAuB,EACvB;QACE,OAAO,EAAK,IAAI;QAChB,QAAQ,EAAI,IAAI;QAChB,UAAU,EAAE,IAAI;QAChB,MAAM;KACP,CACF,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAY;IAEZ,IAAI,KAAK,CAAC,IAAI,KAAK,uBAAuB,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAI,KAA8B,CAAC,MAAM,CAAC;IAEtD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,SAAS,IAAI,MAAM,CACpB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAwB;IAExB,OAAO,OAAO,CAAC,IAAI,KAAK,YAAY;QAClC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO;QACxB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAwB;IAExB,OAAO,iBAAiB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["export type UpdateByDelta = Readonly<{\n  type       : 'devices' | 'subscription';\n  delta      : number | 'next' | 'prev';\n  min?       : number;\n  max?       : number;\n  useAsValue?: boolean;\n  /**\n   * Optional identifier for the action source element\n   * (`data-store-event-id`). Consumers filter against this id via the\n   * `ignore-events` attribute on `bd-*` provider elements.\n   */\n  eventId?   : string;\n}>;\n\nexport type Action = Readonly<{\n  id?          : string;\n  campaign?    : string;\n  bundle?      : boolean;\n  devices?     : number;\n  subscription?: number;\n  /**\n   * Optional identifier for the action source element\n   * (`data-store-event-id`). Consumers filter against this id via the\n   * `ignore-events` attribute on `bd-*` provider elements.\n   */\n  eventId?     : string;\n}>;\n\nexport type BdActionCommand =\n  | Readonly<{\n    kind  : 'update-by-delta';\n    update: UpdateByDelta;\n  }>\n  | Readonly<{\n    kind  : 'set-action';\n    action: Action;\n  }>;\n\nexport type BdTransition = Readonly<{\n  seq        : number;\n  command    : BdActionCommand;\n  originNode?: EventTarget | null;\n  createdAt  : number;\n}>;\n\nexport const BD_ACTION_REQUEST_EVENT =\n  'bd-action-request' as const;\n\nexport type BdActionRequestDetail = Readonly<{\n  command: BdActionCommand;\n}>;\n\ndeclare global {\n  interface HTMLElementEventMap {\n    [BD_ACTION_REQUEST_EVENT]: CustomEvent<BdActionRequestDetail>;\n  }\n}\n\nlet bdTransitionSeq = 0;\n\nexport function createBdTransition(\n  detail: BdActionRequestDetail,\n  originNode?: EventTarget | null\n): BdTransition {\n  return {\n    seq      : ++bdTransitionSeq,\n    command  : detail.command,\n    originNode,\n    createdAt: Date.now()\n  };\n}\n\nexport function dispatchBdActionRequest(\n  eventTarget: EventTarget,\n  detail: BdActionRequestDetail\n): boolean {\n  return eventTarget.dispatchEvent(\n    new CustomEvent<BdActionRequestDetail>(\n      BD_ACTION_REQUEST_EVENT,\n      {\n        bubbles   : true,\n        composed  : true,\n        cancelable: true,\n        detail\n      }\n    )\n  );\n}\n\nexport function isBdActionRequestEvent(\n  event: Event\n): event is CustomEvent<BdActionRequestDetail> {\n  if (event.type !== BD_ACTION_REQUEST_EVENT) {\n    return false;\n  }\n\n  const detail = (event as CustomEvent<unknown>).detail;\n\n  return (\n    typeof detail === 'object' &&\n    detail !== null &&\n    'command' in detail\n  );\n}\n\n/**\n * Pulls the optional `eventId` off the command carried by a transition.\n *\n * `eventId` is set on the action element via `data-store-event-id=\"…\"` and\n * is the matching key for the `ignore-events=\"…\"` attribute on `bd-*`\n * provider elements. Returns `undefined` for commands that did not declare\n * one.\n */\nexport function getCommandEventId(\n  command: BdActionCommand\n): string | undefined {\n  return command.kind === 'set-action'\n    ? command.action.eventId\n    : command.update.eventId;\n}\n\n/**\n * Convenience wrapper around {@link getCommandEventId} for transitions.\n */\nexport function getTransitionEventId(\n  transition: BdTransition\n): string | undefined {\n  return getCommandEventId(transition.command);\n}\n"]}

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;
+}