@repobit/dex-store-elements 1.7.3 → 2.0.1

package/README.md

@@ -1,15 +1,17 @@
 # @repobit/dex-store-elements
 
-Lightweight HTML custom elements + attribute renderers for building dynamic pricing UIs on top of `@repobit/dex-store`.
+Reactive HTML custom elements + declarative attribute renderers for building dynamic pricing UIs on top of `@repobit/dex-store`.
 
-- Custom elements: `<bd-root>`, `<bd-product>`, `<bd-option>`, `<bd-state>`, `<bd-context>`
-- Unified attribute-based renderers (no framework required)
-- Eta templates for text/HTML and attributes
-- Single, merged data context across product, option and state
-- Extensible “derived” variables/functions you can compute and use anywhere
+- Custom elements: `<bd-product>`, `<bd-option>`, `<bd-context>` (a Lit-based, scope-providing node tree)
+- Declarative renderers via `data-store-*` attributes — no framework glue code
+- Eta templates for text and attributes with a unified DSL context
+- Compute layer (min/max over the reachable option space) feeds a flat state DTO into templates and the hide DSL
+- Composable event topology: ignore-list filtering via `data-store-event-id` + `ignore-events`
 
 ## Requirements
+
 - Node 18+
+- A browser (or jsdom for tests)
 
 ## Install
 
@@ -17,80 +19,315 @@ Lightweight HTML custom elements + attribute renderers for building dynamic pric
 npm i @repobit/dex-store-elements @repobit/dex-store
 ```
 
-Peer dependencies are resolved automatically by npm; no extra install command is required.
-
 ## Quick start
 
 ```html
-<!-- index.html -->
 <script type="module">
-  import { registerContextNodes, registerActionNodes, registerRenderNodes } from '@repobit/dex-store-elements';
+  import {
+    registerContextNodes,
+    registerActionNodes,
+    registerRenderNodes
+  } from '@repobit/dex-store-elements';
   import { Store } from '@repobit/dex-store';
 
-  window.addEventListener('DOMContentLoaded', async () => {
+  window.addEventListener('DOMContentLoaded', () => {
     registerContextNodes();
-    const root = document.querySelector('bd-root');
-    root.store = new Store({
-      locale: 'en-us',
+
+    const context = document.querySelector('bd-context');
+
+    context.store = new Store({
+      locale  : 'en-us',
       provider: { name: 'vlaicu' }
     });
 
     // Optional: analytics data layer callback
-    // Fires once per <bd-option> that sets `data-layer-event`
-    root.dataLayer = ({ option, event }) => {
-      // Example GTM-style push; adapt fields as needed
+    // Fires once per <bd-option> that declares `data-layer-event`.
+    context.dataLayer = ({ option, event }) => {
       window.dataLayer?.push({
         event,
         productId   : option.getProduct().getId(),
         campaign    : option.getProduct().getCampaign(),
-        variation   : option.getVariation(), // e.g. "5-12"
+        variation   : option.getVariation(),
         devices     : option.getDevices(),
         subscription: option.getSubscription(),
         price       : option.getDiscountedPrice({ currency: false })
       });
     };
 
-    // Optional: define derived values/functions for templates + hide DSL
-    root.derived = async ({ option }) => ({
+    // Optional: derived values/functions available in templates + hide DSL.
+    context.derived = async ({ option }) => ({
       mails: (p) => ((option?.getDevices?.() ?? 0) / p) * 100
     });
 
-    const disposeActions = registerActionNodes(root);
-    const disposeRenders = registerRenderNodes(root);
+    const disposeActions = registerActionNodes(context);
+    const disposeRenders = registerRenderNodes(context);
 
-    // Optional teardown (for SPA route changes/unmounts)
+    // Call disposers during teardown (SPA route changes, dynamic mounts).
     // disposeActions();
     // disposeRenders();
   });
 </script>
 
-<bd-root store-name="root">
-  <bd-product store-name="product" product-id="com.bitdefender.tsmd.v2">
+<bd-context>
+  <bd-product product-id="com.bitdefender.tsmd.v2">
     <bd-option devices="5" subscription="12" data-layer-event="info">
-      <!-- Attribute renderers (see below) -->
+      <!-- Attribute renderers -->
       <div data-store-render data-store-devices></div>
-      <div data-store-render data-store-subscription data-store-subscription-type="years"></div>
+      <div data-store-render
+           data-store-subscription
+           data-store-subscription-type="years"></div>
       <div data-store-render data-store-price="discounted || full"></div>
       <a data-store-render data-store-buy-link>Buy</a>
+
       <!-- Eta template (text) -->
       <p>Now at only {{= it.option.price.discounted }}!</p>
-      <!-- Eta template (attribute, implicit) -->
+
+      <!-- Eta template (implicit attribute) -->
       <div title="Devices {{= it.option.devices }}"></div>
-      <!-- Hide via DSL using merged context -->
-      <div data-store-render data-store-hide="!it.option.price.discounted">
-        Hidden when discounted price doesn't exists
+
+      <!-- Hide via DSL -->
+      <div data-store-render
+           data-store-hide="!it.option.price.discounted">
+        Hidden when no discounted price exists
       </div>
-      <!-- Actions -->
-      <button data-store-action data-store-set-devices="25">25 devices</button>
+
+      <!-- Action: emit a store event -->
+      <button data-store-action
+              data-store-set-devices="25"
+              data-store-event-id="devicesBtn">
+        25 devices
+      </button>
     </bd-option>
   </bd-product>
-</bd-root>
+</bd-context>
+```
+
+## Architecture in 30 seconds
+
+- `bd-context` publishes a `BdScope` (store, derived, dataLayer, batch schedule) and is a **hard event boundary** — events from outside it cannot drive descendants inside it.
+- `bd-product` consumes a scope, publishes `BdScope.product` (plus a normalised `option` field).
+- `bd-option` consumes a scope and publishes `BdScope.option` after resolving the option from `store + devices + subscription + action`.
+- `registerActionNodes(root)` attaches `BdActionElementAdapter`s to every element matching `[data-store-action]` (or that declares one of the `data-store-set-*` attributes). Adapters dispatch `bd-action-request` events on user interaction; the nearest `bd-*` ancestor catches them and drives its own scope.
+- `registerRenderNodes(root)` walks every `[data-store-render]` element and runs the matching attribute handler whenever an observed attribute changes.
+- Compute (`bd-compute`, opt-out via `compute-disabled`) reduces the reachable option space to a `BdComputeResult` with min/max formatted strings, available as `it.state.*` in templates.
+
+## Custom elements
+
+Only three elements are registered. `bd-root` / `bd-state` from v1 are intentionally gone — `bd-context` is the scope-publishing root.
+
+| Tag | Attributes | Notes |
+| --- | --- | --- |
+| `<bd-context>` | `ignore-events`, `ignore-events-parent` (always true), `eta-disabled`, `compute-disabled`, `topology-boundary` | Publishes `store`, `derived`, `dataLayer`, `mutationBatchSchedule`. |
+| `<bd-product product-id="…" campaign="…" bundle>` | all the above + `product-id`, `campaign`, `bundle` | Reflects `product-id`, `campaign`, `bundle`. |
+| `<bd-option devices="5" subscription="12" data-layer-event="info">` | all the above + `devices`, `subscription`, `data-layer-event` | Reflects `devices`, `subscription`. Fires `dataLayer` once on first load. |
+
+All three extend `BdScopedElement` and pick up every scope-related property (`ignore-events`, `ignore-events-parent`, `eta-disabled`, `compute-disabled`, `topology-boundary`).
+
+### Scope-related properties
+
+- `ignore-events="a, b, c"` — drop transitions whose `eventId` matches any of the comma-separated ids. Applies to this node **and** every descendant (the cascade is gated here).
+- `ignore-events-parent` (boolean) — drop cascades from the parent scope; only react to local DOM events. `bd-context` enables this by default.
+- `eta-disabled` / `compute-disabled` (boolean) — kill Eta rendering / compute for this subtree.
+- `topology-boundary` (boolean) — on `BdNodeElement`, marks a topology boundary for the action registry.
+
+## Render attributes
+
+Add `data-store-render` to any element you want re-rendered on scope changes. The matching handler is selected by the data attribute name.
+
+| Attribute | Tokens / values | Source |
+| --- | --- | --- |
+| `data-store-devices` | — | current `option.getDevices()` |
+| `data-store-subscription` | — | current `option.getSubscription()` |
+| `data-store-subscription-type` | `months` \| `years` | affects text formatting only |
+| `data-store-text-single` | label string | singular label |
+| `data-store-text-many` | label string | plural label |
+| `data-store-price` | `full`, `discounted`, `full-monthly`, `discounted-monthly` (supports `||` fallbacks) | current option |
+| `data-store-discount` | `value`, `percentage`, `value-monthly`, `percentage-monthly` (supports `||` fallbacks) | current option |
+| `data-store-context-price` | `min-full`, `max-full`, `min-discounted`, `max-discounted`, `min-full-monthly`, `max-full-monthly`, `min-discounted-monthly`, `max-discounted-monthly` | compute result |
+| `data-store-context-discount` | `min-value`, `max-value`, `min-percentage`, `max-percentage`, `min-value-monthly`, `max-value-monthly`, `min-percentage-monthly`, `max-percentage-monthly` | compute result |
+| `data-store-buy-link` | (optional trial duration, e.g. `"30 days"`) | buy URL, or trial URL when a duration is supplied |
+| `data-store-hide` | boolean expression in the DSL | hide the element when truthy |
+| `data-store-hide-type` | `display` (default) \| `opacity` \| `visibility` | how to hide |
+
+> `data-store-trial-link` is gone — use `data-store-buy-link="30 days"` to pick a trial URL by duration. Falls back to the regular buy URL when no trial is configured.
+
+## Hide DSL
+
+Boolean expression compiled once per change, evaluated against the unified context:
+
+```html
+<div data-store-render data-store-hide="!it.option.price.discounted">…</div>
+<div data-store-render data-store-hide="it.product.campaign === 'test'">…</div>
+<div data-store-render
+     data-store-hide="it.state.discount.percentage.min && !it.mails(10)">
+  …
+</div>
+```
+
+The expression runs against the same context the Eta templates see (see `DSL context reference` below). Numeric comparisons on prices are not portable — they're formatted strings and vary by currency. Devices and subscription remain numeric.
+
+## Eta templates
+
+The Eta context variable is `it` (Eta default). The available shape is identical to the hide DSL:
+
+- `it.option.*` (only inside `<bd-option>`)
+- `it.product.*` (only inside `<bd-product>`)
+- `it.state.*` / `it.ctx.*` (everywhere — `ctx` is an alias of `state`)
+- `it.derived.*` (whatever your `derived` factory returned — see below)
+- `it.store` (the raw `@repobit/dex-store` `Store`)
+
+Templates can appear in text content (`<p>…{{= it.option.price.discounted }}…</p>`) or implicitly in any attribute whose value contains `{{`.
+
+## Derived variables / functions
+
+```ts
+context.derived = async ({ store, product, option }) => ({
+  mails: (p) => ((option?.getDevices?.() ?? 0) / p) * 100,
+  // Nested overrides are merged into their slot:
+  option: { someVar: 'hello' }
+});
+```
+
+Read from templates as `{{= it.derived.mails(10) }}`. Read from the hide DSL as `it.derived.mails(10)`. The factory is async, called whenever the scope inputs change.
+
+`derived` lives in the **nested** `it.derived` slot (not merged into root) — this keeps store-provided fields distinct from user-provided ones. v1's root-merge behaviour is gone.
+
+## DSL context reference
+
+The shape exposed to both Eta templates and the hide DSL:
+
+```ts
+it = {
+  store,                              // raw Store | undefined
+  product: {                          // TemplateProductContext | undefined
+    id      : string,
+    campaign: string | undefined,
+    name    : string | undefined
+  },
+  option: {                           // TemplateOptionContext | undefined
+    price: {
+      full             : string,
+      discounted       : string | undefined,
+      fullMonthly      : string,
+      discountedMonthly: string | undefined
+    },
+    discount: {
+      percentage       : string,
+      percentageMonthly: string,
+      value            : string,
+      valueMonthly     : string
+    },
+    links: {
+      buy  : string | undefined,
+      trial: (trialDuration: string) => string | undefined
+    },
+    devices     : number,
+    subscription: number
+  },
+  state: {                            // TemplateStateContext | undefined
+    price: {
+      full: {
+        min: string, max: string,
+        monthly: { min: string, max: string }
+      },
+      discounted: {
+        min: string, max: string,
+        monthly: { min: string, max: string }
+      }
+    },
+    discount: {
+      percentage: {
+        min: string, max: string,
+        monthly: { min: string, max: string }
+      },
+      value: {
+        min: string, max: string,
+        monthly: { min: string, max: string }
+      }
+    },
+    scenarios: number
+  },
+  ctx,                                // alias of `state`
+  derived: Record<string, unknown>    // from `bd-context.derived`
+}
+```
+
+Notes
+- All price / discount values in the DSL are **formatted strings** (currency-aware). Don't perform numeric comparisons on them.
+- `it.ctx` is an alias of `it.state` for convenience.
+- `it.option.links.trial('30 days')` returns the trial URL for that duration, or `undefined` if no trial is configured.
+- `it.derived.*` is the user-defined overlay from `bd-context.derived`.
+
+## Data layer
+
+```ts
+context.dataLayer = ({ option, event }) => {
+  window.dataLayer?.push({
+    event,
+    productId: option.getProduct().getId(),
+    devices  : option.getDevices(),
+    // …
+  });
+};
+```
+
+- Fires once per `<bd-option>` instance (first successful load). Re-firing requires re-mounting the node.
+- `event` is the value of `data-layer-event` on the option element. Canonical values: `all`, `info`, `comparison`. Custom strings are accepted.
+
+## Actions
+
+```html
+<button data-store-action
+        data-store-set-devices="25"
+        data-store-event-id="devicesBtn">25 devices</button>
+
+<button data-store-action
+        data-store-set-type="devices"
+        data-store-set-delta="next"
+        data-store-set-min="1"
+        data-store-set-max="25">next</button>
 ```
 
-**Store Config**
-- `trialLinks` and `overrides` come from `@repobit/dex-store` and work transparently with these elements. You pass them when creating the `Store` and render trial links via `data-store-buy-link="30 days"` (trial duration as the attribute value) or rely on overridden option fields.
+| Attribute | Effect |
+| --- | --- |
+| `data-store-action` | Marks the element as an action source. |
+| `data-store-set-devices="N"` | Set devices = N. |
+| `data-store-set-subscription="N"` | Set subscription = N. |
+| `data-store-set-id="…"` | Switch the current product id. |
+| `data-store-set-campaign="…"` | Switch the campaign for the current product. |
+| `data-store-set-bundle` (boolean) | Toggle bundle inclusion. |
+| `data-store-set-type="devices\|subscription"` | Required for delta updates. |
+| `data-store-set-delta="next\|prev\|<number>"` | Move the option by N (or `next` / `prev`). |
+| `data-store-set-min`, `data-store-set-max` | Bounds for delta updates. |
+| `data-store-set-use-as-value` (boolean) | Treat `delta` as an absolute value rather than an increment. |
+| `data-store-event-id="…"` | Tag the source element so `ignore-events` on `bd-*` nodes can drop its events. |
+
+For `<input type="number|text">` and `<select>`, the adapter reads the current input value and dispatches a delta update. For `<input type="checkbox|radio">` it fires on click when `checked === true`.
+
+### Ignoring events on a subtree
+
+```html
+<bd-option ignore-events="devicesBtn, subscriptionBtn">
+  <!-- ignores events from any source tagged with one of those ids -->
+</bd-option>
+```
+
+`ignore-events` cascades — descendants inherit it. `data-store-event-id` is the matching tag on the source element. (`data-store-id` from v1 is gone.)
+
+## Registration and initialization
 
-Example advanced config when constructing the store:
+| Export | Purpose |
+| --- | --- |
+| `registerContextNodes()` | Register `<bd-context>`, `<bd-product>`, `<bd-option>` custom elements. Idempotent. |
+| `registerActionNodes(root)` | Attach `BdActionElementAdapter`s to every action element under `root`. Returns `() => void` to disconnect. |
+| `registerRenderNodes(root)` | Wire every `[data-store-render]` element under `root` to its attribute handler. Returns `() => void` to disconnect. |
+| `elementDefinitions` | `{ 'bd-context': ContextNode, 'bd-product': ProductNode, 'bd-option': OptionNode }` — for advanced consumers that want to register tags themselves. |
+
+The package is side-effect free; nothing is registered until you call `registerContextNodes()`.
+
+## Store config
+
+`trialLinks` and `overrides` come from `@repobit/dex-store` and work transparently with these elements. Configure them on the `Store` and render via attributes:
 
 ```ts
 import { Store } from '@repobit/dex-store';
@@ -99,36 +336,26 @@ const store = new Store({
   locale  : 'en-us',
   provider: { name: 'vlaicu' },
 
-  // Map productId -> campaign -> optionVariation -> trial URL
-  // productId is the final id after adaptor mapping (e.g. 'com.bitdefender.tsmd.v2').
-  // optionVariation key format: '<devices>-<subscription>' (e.g. '5-12').
+  // productAlias -> campaign -> optionVariation -> trialDays -> URL
+  // productAlias is the id after adaptor mapping.
+  // optionVariation key: '<devices>-<subscription>' (e.g. '5-12').
   trialLinks: {
     'com.bitdefender.tsmd.v2': {
       default: {
-        '5-12' : { '30 days': 'https://trial.example.com/default/5-12' },
-        '10-12': { '30 days': 'https://trial.example.com/default/10-12' }
-      },
-      PromoX: {
-        '5-12' : { '30 days': 'https://trial.example.com/promox/5-12' },
-        '10-12': { '30 days': 'https://trial.example.com/promox/10-12' }
+        '5-12': { '30 days': 'https://trial.example.com/default/5-12' }
       }
     }
   },
 
-  // Per-product overrides for campaign and/or options
-  // - Set/redirect campaign via `default.campaign` or `[campaign].campaign`
-  // - Merge option fields per variation; use `null` to remove an option
+  // Per-product overrides
   overrides: {
     'com.bitdefender.tsmd.v2': {
-      // Applies when no explicit campaign is requested
-      default: {
-        campaign: 'OvDefault'
-      },
+      default: { campaign: 'OvDefault' },
       PromoX: {
         campaign: 'PromoX',
         options : {
-          '5-12' : { discountedPrice: 49.99, buyLink: 'https://example.com/override/buy' },
-          '10-12': null // delete this variation
+          '5-12' : { discountedPrice: 49.99 },
+          '10-12': null  // delete this variation
         }
       }
     }
@@ -136,242 +363,40 @@ const store = new Store({
 });
 ```
 
-Notes
-- `overrides.options` merges into each option; you can update `buyLink`, `discountedPrice`, etc., or delete an entire variation with `null`.
-- Keys are resolved against the product alias returned by the provider. If you don't use id mappings, it's the id you pass in `<bd-product product-id="...">`.
-
-## Rendering model
-- Add `data-store-render` to any element you want updated by the pipeline.
-- A single binder subscribes to option, product and aggregated state contexts and renders attributes + Eta templates.
-- Scoping is natural: a node sees the nearest provider up the tree (e.g., `it.option.*` is only available inside `<bd-option>`).
-
-## Supported attributes
-
-- `data-store-devices`
-  - Renders option devices to text nodes, `<input>` value, or `<select>` options (adds `data-store-set-devices` on each option)
-  - Optional label helpers: `data-store-text-single="device"`, `data-store-text-many="devices"`
-
-- `data-store-subscription`
-  - Renders option subscription similarly; add `data-store-subscription-type="years|months"`
-  - Label helpers: `data-store-text-single`, `data-store-text-many`
-
-- `data-store-price`
-  - Allowed tokens: `full`, `discounted`, `full-monthly`, `discounted-monthly`
-  - Supports OR semantics via `||` to choose the first available variant:
-    - `data-store-price="discounted || full"`
-
-- `data-store-discount`
-  - Allowed tokens: `value`, `percentage`, `value-monthly`, `percentage-monthly`
-  - Supports `||` fallbacks
-
-- Aggregated state (min/max across options):
-  - `data-store-context-price` tokens: `min-full`, `max-full`, `min-full-monthly`, `max-full-monthly`, `min-discounted`, `max-discounted`, `min-discounted-monthly`, `max-discounted-monthly`
-  - `data-store-context-discount` tokens: `min-value`, `max-value`, `min-value-monthly`, `max-value-monthly`, `min-percentage`, `max-percentage`, `min-percentage-monthly`, `max-percentage-monthly`
-
-- Links
-  - `data-store-buy-link` sets anchor `href` and useful `data-*` attributes. Accepts an optional trial-duration value (e.g. `data-store-buy-link="30 days"`): when provided, the trial link for that duration is used if one is configured for the current variation, otherwise falls back to the regular buy link.
-
-- Hide DSL
-  - `data-store-hide="<boolean expression>"` with an optional `data-store-hide-type="display|opacity|visibility"`
-  - Expression is compiled and evaluated against the unified context:
-    - `it.option.*` current option data. Price- and discount-related fields are formatted strings (currency-aware). Do not rely on numeric math for prices; they vary by currency. Devices/subscription remain numeric.
-    - `it.product.*` id/campaign/name
-    - `it.state.*` aggregated min/max data (also available under `it.ctx`)
-    - any keys returned from your `root.derived`
-  - Examples:
-    - `data-store-hide="!it.option.price.discounted"` (hide when no discounted price)
-    - `data-store-hide="it.product.campaign === 'test'"`
-
-## Eta templates
-- Text/HTML: any element that is not a provider and doesn’t contain nested providers is treated as a whole-template; `innerHTML` is compiled once and morphed via nanomorph. This preserves existing DOM event listeners and state.
-- Attributes:
-  - Implicit: any attribute whose value contains `{{` is rendered via Eta
-- The Eta context variable is `it` (Eta default). It contains:
-  - `it.option.*` (inside `<bd-option>`)
-  - `it.product.*` (inside `<bd-product>`)
-  - `it.state.*` and `it.ctx.*` (inside any provider subtree)
-  - your derived overlay merged at top-level (see below)
-
-## Derived variables/functions
-- Provide a function at the root: `root.derived = async ({ option, product, state }) => ({ ... })`
-- The returned object is merged into the Eta/DSL context:
-  - Example: `({ mails: (p) => (option?.getDevices?.()/p)*100, option: { someVar: state.discount.value.min } })`
-  - Use it in Eta: `{{= it.mails(10) }}` or `{{= it.option.someVar }}`
-  - Use it in hide: `data-store-hide="it.mails(10) >= 50"`
-
-## DSL context reference
-The DSL and Eta contexts use Eta’s default variable name `it`. The following keys are available:
-
-- it.option
-  - price
-    - full: formatted full price (string)
-    - discounted: formatted discounted price (string)
-    - fullMonthly: formatted monthly full price (string)
-    - discountedMonthly: formatted monthly discounted price (string)
-  - discount
-    - value: formatted discount amount (string)
-    - percentage: formatted percentage discount with symbol (string)
-    - valueMonthly: formatted monthly discount amount (string)
-    - percentageMonthly: formatted monthly percentage with symbol (string)
-  - links
-    - buy: buy URL (string)
-    - trial: trial URL if available (string)
-  - devices: number
-  - subscription: number
-
-- it.product
-  - id: string
-  - campaign: string
-  - name: string
-
-- it.state (also available as `it.ctx`)
-  - price
-    - full
-      - min: formatted string
-      - max: formatted string
-      - monthly
-        - min: formatted string
-        - max: formatted string
-    - discounted
-      - min: formatted string
-      - max: formatted string
-      - monthly
-        - min: formatted string
-        - max: formatted string
-  - discount
-    - percentage
-      - min: formatted string
-      - max: formatted string
-      - monthly
-        - min: formatted string
-        - max: formatted string
-    - value
-      - min: formatted string
-      - max: formatted string
-      - monthly
-        - min: formatted string
-        - max: formatted string
-
-Notes
-- All price/discount values in the DSL are formatted strings (currency-aware). Do not perform numeric comparisons on them. Prefer truthiness checks (e.g., `!it.option.price.discounted`).
-- `it.ctx` is an alias of `it.state` for convenience.
-
-## Data Layer
-- Provide a function on `<bd-root>`: `root.dataLayer = ({ option, event }) => { ... }`.
-  - Called once per `<bd-option>` instance that declares `data-layer-event` (on first successful load).
-  - Safe if attached after the option loads; it still fires once when available.
-  - Intended for analytics (e.g., pushing to `window.dataLayer`).
-- Event name is set on each `<bd-option>` with `data-layer-event`.
-  - Canonical values: `all`, `info`, `comparison`. Any custom string is also accepted.
-- Payload shape passed to your callback:
-  - `event`: string event name.
-  - `option`: `ProductOption` from `@repobit/dex-store` with getters like `getProduct()`, `getVariation()`, `getDevices()`, `getSubscription()`, `getBuyLink()`, `getDiscountedPrice()`.
-
-Example:
+Render via attributes:
 
 ```html
-<script type="module">
-  import { registerContextNodes, registerActionNodes } from '@repobit/dex-store-elements';
-  import { Store } from '@repobit/dex-store';
-
-  window.addEventListener('DOMContentLoaded', async () => {
-    registerContextNodes();
-    const root = document.querySelector('bd-root');
-    root.store = new Store({ locale: 'en-us', provider: { name: 'vlaicu' } });
-
-    root.dataLayer = ({ option, event }) => {
-      window.dataLayer = window.dataLayer || [];
-      window.dataLayer.push({
-        event,
-        productId: option.getProduct().getId(),
-        campaign : option.getProduct().getCampaign(),
-        variation: option.getVariation(),
-        devices  : option.getDevices(),
-        subscription: option.getSubscription()
-      });
-    };
-
-    const disposeActions = registerActionNodes(root);
-
-    // Optional teardown (for SPA route changes/unmounts)
-    // disposeActions();
-  });
-</script>
-
-<bd-root store-name="root">
-  <bd-product store-name="product" product-id="com.bitdefender.tsmd.v2">
-    <bd-option devices="5" subscription="12" data-layer-event="info">
-      <!-- your UI here -->
-    </bd-option>
-  </bd-product>
-</bd-root>
+<a data-store-render data-store-buy-link>Buy</a>
+<a data-store-render data-store-buy-link="30 days">30-day trial</a>
 ```
 
-Behavior notes
-- Fires only once per `<bd-option>` instance (first load). Subsequent changes via actions or deltas do not trigger the callback again.
-- Set different `data-layer-event` values on different options if you need multiple distinct analytics events.
+## Caveats
 
-## Actions
-- Add `data-store-action` to elements to emit store events.
-  - Set absolute values: `data-store-set-devices`, `data-store-set-subscription`, `data-store-set-id`, `data-store-set-campaign`
-  - Update by delta/sequence: `data-store-set-type="devices|subscription"`, `data-store-set-delta="next|prev|<number>"`
-  - Source identifier: add `data-store-id="someId"` to tag the event's `storeId`. Providers with `ignore-events` that include `someId` will drop these events.
-- Initialize once per mount with:
-  - `import { registerActionNodes } from '@repobit/dex-store-elements'`
-  - `const disposeActions = registerActionNodes(root)`
-  - Call `disposeActions()` on teardown/unmount to disconnect observers.
+- Scoping: `it.option.*` is only available inside `<bd-option>`. `it.product.*` is only available inside `<bd-product>`. Everything else is available everywhere.
+- Nested providers: an inner `bd-context` / `bd-product` / `bd-option` renders its own subtree; templates inside it never see the outer scope's `option` (only the inner one).
+- Eta templates are scoped to non-provider elements — provider elements don't render text content as templates.
+- Compute (state min/max) only runs when at least one `bd-context` / `bd-product` / `bd-option` enables it (default: enabled). Disable with `compute-disabled` on a provider to skip the reduction for preview widgets.
 
-## Registration and initialization
-- Element registration:
-  - `import { registerContextNodes } from '@repobit/dex-store-elements'; registerContextNodes();`
-- Rendering: `import { registerRenderNodes } from '@repobit/dex-store-elements'`
-- Actions: `import { registerActionNodes } from '@repobit/dex-store-elements'`
-- `registerRenderNodes(root)` returns a disposer: `() => void`
-- `registerActionNodes(root)` returns a disposer: `() => void`
-- Call disposers during teardown/unmount in long-lived apps (SPA route changes, dynamic mounts).
-
-Note: The package is side-effect free; elements are registered only when `registerContextNodes()` is called.
-
-## State & event controls
-These attributes are available on `<bd-state>` and any element that extends it (`<bd-root>`, `<bd-product>`, `<bd-option>`).
-- `ignore-events="store-a, store-b"`
-  - Comma-separated list of action ids. Events whose source element has a matching `data-store-id` are ignored by this node (and its subtree). Works for both action and delta events.
-  - Coupling with `data-store-id` (on action elements):
-    - Example:
-      - `<button data-store-action data-store-id="devicesBtn" data-store-set-devices="25">` dispatches an event with `storeId: "devicesBtn"`.
-      - `<bd-option ignore-events="devicesBtn">` ignores that event while still accepting events from other buttons.
-    - You can list multiple ids: `ignore-events="devicesBtn, subscriptionBtn"`.
-- `ignore-events-parent`
-  - Ignores events received from ancestor providers and only reacts to DOM-bubbled events that originate within the current subtree.
-  - `<bd-context>` is a convenience element that defaults this behavior to enabled. It’s equivalent to `<bd-state ignore-events-parent>`.
-  - Example:
-    ```html
-    <bd-state store-name="outer">
-      <!-- Global action updates state here -->
-      <button data-store-action data-store-set-devices="25"></button>
-
-      <!-- Isolated island: only inner actions are observed -->
-      <bd-context store-name="island">
-        <button data-store-action data-store-set-devices="5"></button>
-      </bd-context>
-    </bd-state>
-    ```
-    In this setup, the inner `<bd-context>` ignores the outer button’s events.
-- `no-collect`
-  - Turns off automatic option collection for aggregated state. Set this when you want the node to work locally without contributing to shared min/max computations (e.g., for preview widgets).
+## TypeScript
 
-## Caveats
-- Scoping: attribute Eta and hide can only see contexts provided by ancestors. For example, `it.option.*` is only available inside `<bd-option>`.
-- Nested providers: inner providers render their own subtrees; outer nodes can still render attributes safely even when they contain nested providers.
+```ts
+import type {
+  ContextNode,
+  ProductNode,
+  OptionNode,
+  BdScope,
+  BdScopeDeriveFn
+} from '@repobit/dex-store-elements';
+
+import {
+  registerContextNodes,
+  registerActionNodes,
+  registerRenderNodes
+} from '@repobit/dex-store-elements';
+```
 
-## TypeScript
-- Custom element classes are exported from a dedicated entry for advanced use:
-  - `import { RootNode, ProductNode, OptionNode, StateNode } from '@repobit/dex-store-elements'`
-- The derived signature:
-  ```ts
-  import type { derivedContextType } from '@repobit/dex-store-elements/src/contexts/context.derived';
-  const derived: derivedContextType = async ({ option, product, state, store }) => ({ ... });
-  ```
+The custom element classes extend `BdScopedElement` and `BdNodeElement` (Lit `LitElement` subclasses). They are exported from the main entry.
 
 ## License
+
 ISC