@rightxt/tracker-element

Overview

A standards-based Custom Element adapter for RXT Tracker. Place <rxt-tracker> in your document, configure options and ordered selector rules with JavaScript, and let DOM connection manage its runtime. It uses Core Projection internally; consumers use the Element API documented here.

The adapter owns only its generated .rxtt subtree. Application children and host DOM state remain caller-owned. It creates no private ShadowRoot.

Installation and registration

pnpm add @rightxt/tracker-element

The named/default class also exists in the type namespace. TrackerElementOptions describes the full option surface below; rules remain a separate method channel. Root ESM does not auto-register. Root plus /register uses the same ESM constructor; both keep neutral Core external. There is no Element /debug ESM entry.

Registration choices

Import /register for convenience, or call the no-argument defineTrackerElement() from the root entry. The helper:

• Returns null when customElements is unavailable.
• Registers and returns TrackerElement when the default tag is free.
• Returns the existing class idempotently when that same constructor owns the tag.
• Throws a plain Error when a different constructor owns rxt-tracker.

Manual platform registration with the exported class is also possible as an alternative, for example customElements.define('app-content-tracker', TrackerElement) in a registry where that constructor is not already registered. The helper only targets the default name.

Choose one registration build per CustomElementRegistry. Independent ESM/standalone or production/debug standalone copies have different constructor identities and can collide for the same default tag. Standalone scripts auto-register; do not load both to switch debug behavior in an already-registered registry. Serve the selected standalone file with the separate rxt-tracker.css asset from the installed package's dist output. Hosted production assets are also available directly from a CDN; see the CDN guide.

There is no custom pre-upgrade property replay shim. Define/upgrade the element before assigning sourceRoot/scrollRoot; assignments made on an unresolved unknown element are not a supported configuration workflow. Native registration/upgrade rules still apply.

Quick start

Run after the document body and headings exist. This uses a bundler supporting CSS imports and configures the upgraded host before connecting it:

import '@rightxt/tracker-element/register';
import '@rightxt/tracker-element/style.css';

const tracker = document.createElement('rxt-tracker');
tracker.replaceConfiguration({
  options: { placement: 'right', a11y: { enabled: true, keyboard: true } },
  rules: [{ selector: 'h2', label: (element) => element.textContent }],
});
document.body.append(tracker);

// On view removal: tracker.remove();
// Re-appending the host later creates a fresh runtime with the stored configuration.

There is no host destroy() call. Removing/disconnecting the host retires its current runtime; the host itself remains reusable. You can also declare <rxt-tracker></rxt-tracker> in markup and configure the upgraded element through the same JS methods.

Configuration model

There are zero observed/configuration attributes. Options/rules are not JSON attributes, root-selector attributes, or declarative child rules. There is no options/rules property channel or attribute/property precedence model. Ordinary host id/class/hidden/aria/data attributes retain their DOM meaning; generated .rxtt service attributes are output, not host configuration.

Configure behavior with replaceOptions(), patchOptions(), replaceRules(), or replaceConfiguration(). Functions, DOM roots, rule objects, and diagnostics sinks remain normal JavaScript values. A disconnected host starts with default options and an empty rules list, and has no runtime or owned root.

Root properties

These are mount context, not option leaves:

A connected host may own a .rxtt and a live unmounted runtime while either property is null. Setting valid roots or undefined can mount it again. With a current runtime, root setters can preflight and throw synchronously; accepted changes transactionally remount the same integration, restoring prior value/mount on a rejected update according to that transaction.

Disconnected assignments are stored without runtime mount validation. A foreign or otherwise invalid identity therefore need not throw at assignment: validation can fail later on connection and use lifecycle diagnostic reporting. If initial connection failed and left no runtime, correcting roots on the still-connected host can establish a fresh runtime. The connected lifecycle explains the different failure boundaries.

Configuration

All 36 option leaves below are accepted through JavaScript methods; TrackerElementOptions is the full shared options surface with no Element-only leaves. Every field is optional. Root properties above are not options and have their own null/undefined semantics.

Track geometry and placement

Presentation

Application attributes support role, supported data-*, and supported aria-* names. role requires a nonempty trimmed string; other supported non-null values serialize to strings. class, style, id, tabindex, title, event-handler/framework-special names, and data-rxtt-* are reserved. Use the dedicated class/title/CSS options. Global and per-rule presentation composition is defined in the rule guide.

Clustering

Automatic updates

Each family is independently enabled. Delays/debounces use milliseconds. Observer target callbacks are synchronous functions returning arrays; a bare array is not the configuration type.

Target context contains observerType, sourceRoot, scrollRoot, scrollMode, renderRoot, document, window, defaultTargets, and reason. reason describes connection/reconnection; defaultTargets supplies fresh runtime defaults. Results are deduplicated. Mutation accepts Nodes; resize requires Elements and allows the integration's own render root. Callbacks may inspect the active DOM but must return synchronously and must not mutate the same Tracker during resolution. See observation targets.

The seven native mutation controls are separate configurable leaves:

The effective configuration must enable child-list, attributes, or character data. An all-disabled effective configuration rejects; turn off updates.mutation.enabled to disable the source instead.

Interaction

Accessibility

Patch validation includes inherited values: disabling a11y.enabled while an inherited a11y.keyboard remains true rejects. Change both together when disabling keyboard accessibility. Logical selection is separate from browser focus; preserve visible focus and selected-item styling in custom output.

Diagnostics

Applying option changes

Normal changes are strict and atomic. Any validation diagnostic, including a warning, rejects the candidate without partial acceptance. Known own undefined values and unknown configuration fields reject. Omit a field to use replacement defaults or patch inheritance; null is supported only by its specific field contract. Root-property null/undefined behavior is separate.

replaceOptions(options, params?) resolves omitted fields from defaults and preserves rules. patchOptions(options, params?) deep-merges from stored committed options. replaceConfiguration({ options, rules }, params?) requires both own channels and replaces them atomically. Disconnected methods validate/store values for the next connection. Connected methods use coordinated configuration replacement and normally flush pending Projection work before returning; { render: false } stores/commits without requesting/flushing that visual work. Accepted reentrant calls may defer, with call-time validation still applied. See configuration settlement.

Rules

Rules are processed in priority order. selector is required, trimmed, nonempty, and unique after normalization. The first matching rule owns an overlapping source element. Selector queries follow the source scope; DOM-dependent syntax is validated against the actual source at mount/mounted update boundaries.

The tables cover all 12 rule leaves. marker, scroll, and focus are containers; scroll and focus also accept boolean shorthands.

Selection, labels, and presentation

For a cluster, the primary spatial marker supplies rule presentation. Global/rule classes combine, attributes override or suppress, and rule title policy overrides the global flag. See rules and marker behavior.

Scroll and focus

Boolean scroll/focus shorthands toggle their enabled value while retaining other defaults. Target selectors search source descendants, then the containing ShadowRoot when present, then the owner document. Invalid targets, selector failures, or throwing target callbacks yield no usable target for that phase and diagnostics. Callbacks must return synchronously and must not mutate the same Tracker while resolving.

Strict normal mutations reject diagnostic-bearing rules. Pure rule validation removes invalid rule-marker CSS names/entries from its recovered candidate, keeps valid entries, and reports diagnostics. This sanitation does not allow a normal mutation to silently accept only the valid portion. Validation and recovery and activation behavior provide the detailed contracts.

Replacing the rule list

Rules start empty. Supply a complete array through replaceRules(rules, params?) or the rules channel of replaceConfiguration(). Pass [] to clear it. There is no rules property/attribute, JSON channel, child-rule syntax, addRule(), removeRuleByIndex(), or removeRuleBySelector() on Element.

Connected replacements use the same default flush or { render: false } behavior as options; disconnected replacements store the list for the next runtime generation. Function-valued labels/targets retain their JavaScript identity. For incremental application edits, build the desired complete list and replace it.

Connected lifecycle and configuration settlement

Connection, root changes, and disconnection

DOM connection/disconnection drives connectedCallback() and disconnectedCallback(); callers should not invoke them. There is no public mount/unmount, host destroy/dispose, or terminal host state. Disconnect is reversible at host level even though its runtime generation is terminally destroyed. A destroy CustomEvent describes that retired generation and does not prevent reconnection.

Connection/mount failure is contained by the browser lifecycle boundary: rollback/root cleanup is attempted and element-lifecycle-error is reported through diagnostics output or fallback console. Do not expect the DOM append caller to receive the original synchronous Core mount exception.

Connected configuration timing

An accepted mutation validates/captures values, enters adapter/Core coordination, stores package-owned configuration, replaces the current Projection configuration, and flushes pending render work when mounted unless params.render === false. The normal uncontended connected call therefore returns after required pending Projection work has been flushed, which is different from merely scheduling an update. It is not a browser paint guarantee.

With { render: false }, required work remains dirty for later manual synchronization. With no runtime, validated configuration is stored for the next generation. Public-event reentrant changes may queue until the active operation exits; an immediate void return is not proof that deferred work already completed. Invalid call-time values can still throw before acceptance.

Adoption

Connected adoptedCallback() remounts the same current Projection integration against the moved root in the destination ownerDocument: unmount the old mount generation, then mount in the destination realm. Only omitted roots use destination defaults; explicit sourceRoot/scrollRoot properties persist and must be valid there. Adoption failure is lifecycle-reported and leaves that integration unmounted until corrected.

This connected-adoption path differs from actual disconnect/reconnect. Use browser lifecycle naturally; do not call callbacks as consumer APIs.

Events

Listen on the host with native addEventListener() / removeEventListener(). All eight adapter-dispatched CustomEvents have bubbles: false, composed: false, cancelable: false; observe the host itself, not document/ancestor delegation. event.detail is the unchanged semantic payload.

function onMarkerActivate(event) {
  console.log(event.detail.selector, event.detail.key);
}
tracker.addEventListener('marker:activate', onMarkerActivate);
// Later: tracker.removeEventListener('marker:activate', onMarkerActivate);

Delivery is synchronous. Activation behavior already happened before the outer event, so return values or outer preventDefault() cannot cancel it. Sync events describe Core synchronization rather than browser paint. There is no generic error, mount, or unmount event. Typed EventTarget overloads narrow detail by event name; the package does not expose a separate event-map type import.

DOM EventTarget owns duplicate identity/capture, once, AbortSignal, and removal behavior. There is no Vanilla-style registration-owner layer. Consumer listener exceptions follow the browser error channel and are not converted by Element into Core handler diagnostic stats; returned Promises are not awaited. Catch asynchronous listener work explicitly.

Tracker-owned payload containers are frozen, while source Elements and native Events are borrowed. Warning details is an open borrowed graph, not a frozen/sanitized retained copy. Host listeners survive disconnect/reconnect. A deferred destroy notification from a retired generation still describes only that generation, even if a replacement is already connected. See the Element events example.

Imperative and read state

The ten adapter methods below are distinct from the two root properties and native EventTarget operations:

The four mutation methods accept params.render, defaulting to true, with the connected flush/disconnected storage behavior described above. These methods do not accept constructor-style partial configuration in place of a complete replacement envelope.

The public root properties are sourceRoot and scrollRoot. addEventListener() and removeEventListener() are the class's two typed EventTarget overrides, retaining native semantics. The three browser-owned lifecycle callbacks are connectedCallback, disconnectedCallback, and adoptedCallback; they are not normal consumer control methods. No configuration attributes are observed, and there is no attributeChangedCallback configuration surface.

There is no snapshot read/subscription, host terminal destroy/dispose, current-root getter intended as adapter API, lifecycle state facade, or exposed Core Projection integration. Element does not expose getSnapshot(), subscribeSnapshot(), getTrackerDebugTrace(), flushRender(), or incremental rule methods.

Stats contain render/rule/marker/cluster/observer counters, warning/error totals and last entries, last-render timing, and optional debug data. Standalone stats clones are detached and not frozen. Counters update independently of diagnostics.metrics; the flag gates timing. Reset clears counters, including current counts, without clearing configuration or rendered records. Disconnect discards generation-scoped stats; reconnect starts fresh. The runtime diagnostics reference explains the underlying stats shape; its snapshot/trace APIs are not Element APIs.

Environments

Page and element containers

The host ownerDocument and its owned Projection root select the active realm. Omitted scrollRoot uses page/window mode; active-document body/documentElement/scrollingElement aliases also select page scrolling. An omitted sourceRoot uses the body in window mode or the scroll element in element mode. Source queries match descendants for an Element root, not the source itself.

For a supported HTMLElement scroll container, set same-document roots before connecting to avoid intermediate remounts:

// tracker is defined/upgraded and currently disconnected.
tracker.scrollRoot = document.querySelector('.scroller');
tracker.sourceRoot = tracker.scrollRoot;
document.querySelector('.tracker-overlay').append(tracker);

The scroll element must satisfy the supported geometry/CSS profile. The host's physical output location is application-controlled; source/scroll properties do not relocate it. One runtime represents one authoritative scroll range. See environments for the full profile and containment rules.

Shadow DOM

An explicit open ShadowRoot can be the source scope. Separately, the host itself can live inside a user-managed ShadowRoot. Output always remains a Light DOM .rxtt child of <rxt-tracker>; the adapter creates no own ShadowRoot and cannot use one as its actual render root. Install stylesheet/theme in the scope containing that output. Choosing a shadow source does not move the host or cross nested shadow boundaries automatically. See Element Shadow DOM.

Same-origin iframe and adoption

A parent-document <rxt-tracker> cannot target child-document source/scroll objects: the host/render root owns the realm. Safe child-document use requires registration and the actual host in the child document, matching child roots, and child-document CSS. There is no cross-origin bridge or mixed-document marker projection.

Navigation replaces document identities. Use appropriate fresh child objects/host lifecycle after load; old roots do not retarget automatically. Connected adoption uses the same current integration in the destination realm, with defaults only for omitted roots and revalidation of persistent explicit roots. A foreign disconnected assignment may fail only at connection, while a connected live-runtime setter can throw immediately.

Styling

Import @rightxt/tracker-element/style.css before application theme CSS. JavaScript injects no stylesheet. CSS/theme must reach the actual .rxtt output scope, including a user ShadowRoot containing the host or an iframe document.

The public theme contains 33 root Tracker variables, including 17 rule-marker-compatible variables, plus valid application-owned custom properties. Global/rule classes combine; rule attributes override or suppress inherited attributes; a cluster uses its primary marker's presentation. Preserve service hooks and use configuration rather than editing generated metadata.

Data attributes describe orientation, placement, scroll mode, geometry, item kind/count/key/selection, and drag capability. data-rxtt-drag="true" indicates capability enabled, not a current drag session. Renderer-owned keys and reserved data-rxtt-* attributes are not application configuration channels.

Element uses Projection root normalization: accepted root strings remain unchanged in committed/read state, while rendered root output trims nonblank strings and omits blank/whitespace-only values. Rule/item style maps are a separate output scope and must not be assumed to pass through that same root normalization. Empty output can expose the remaining CSS cascade; it is not a forced reset of inherited styles.

The styling reference gives complete variable/class/attribute details. Theme Builder source opens the tool's repository entry for editing/previewing themes and exporting application overrides. Tool output supplements canonical CSS; the styling reference defines the contract.

Debug and diagnostics

Root ESM and /register compose neutral external Core resolution. Enable Core's development condition consistently for debug instrumentation; there is no Element /debug ESM entry. For standalone use, choose rxt-tracker-element.js or rxt-tracker-element.debug.js. Both auto-register and expose window.RXTTrackerElement; do not load independent constructors for the same default tag in one registry.

While a debug-capable runtime exists, getStats() can include a debug branch. Advanced trace is not exposed: the host is not the private Core integration required by getTrackerDebugTrace(). Disconnected stats remain null even when the selected build supports debug.

diagnostics.output accepts independent optional warn/error callbacks receiving code, message, and optional details. Null clears the caller-owned sink. Runtime warnings update stats, use the configured warn method or console fallback, then dispatch the warning CustomEvent. diagnostics.warnings controls only fallback console.warn; output.warn, warning stats/events, and runtime errors remain active. A configured error method replaces runtime console.error fallback for that severity. Runtime sink failures are contained; the sink is not disposed by the adapter/runtime.

Retained runtime diagnostic metadata is sanitized; immediate sink/event details can contain borrowed live objects. Strict validation diagnostics, runtime warning/error output, and thrown exceptions are separate channels. Native TypeError/AggregateError and TrackerConfigurationError/TrackerLifecycleError with stable codes may propagate from imperative methods or connected setters. Core error classes are not re-exported by this package. No generic error CustomEvent exists.

Browser lifecycle reactions have a different boundary: connection/adoption/remount failures are contained and reported as element-lifecycle-error through configured output.error or fallback console.error, after attempted rollback/cleanup. Do not rely on append/adoption callers receiving the Core mount exception. Disconnected root assignments can defer validation to that lifecycle path; connected setters can instead preflight and throw to their caller. DOM listener exceptions remain browser EventTarget failures and do not become Core handler-error stats.

Demos and further documentation

These absolute repository links open current source materials and public guides:

• Element playground — registration, JS configuration, and connected behavior.
• Element Shadow DOM and Element events.
• Environments — containers, shadow scopes, and document identity.
• Updates and refresh — four automatic sources and manual synchronization. CSS/CSSOM-only changes may require render/requestRender; disabling relevant sources leaves external changes to the caller. Resize targets affect ResizeObserver, not Window resize.
• Rules and marker behavior and styling reference.