@rightxt/tracker-vue

Overview

RXT Tracker adds a track with markers for source elements matched by ordered CSS selector rules. The Vue 3.5+ component owns the rendered track; a private Core Projection integration measures source content, groups markers, handles activation, and observes changes.

Configure the component through props, receive notifications through Vue emits, and use an exposed template-ref handle for runtime state and explicit synchronization.

Installation, artifacts and debug model

pnpm add @rightxt/tracker-vue

Vue is an external peer with range >=3.5 <4. Core is a regular dependency and remains external in the built adapter.

The root resolves to dist/rxt-tracker-vue.mjs with dist/index.d.ts declarations. There is one normal ESM adapter entry, no package-local /debug ESM path, and no standalone/global browser bundle or standalone debug JavaScript. Debug behavior comes from neutral external Core condition selection; see Debug and diagnostics.

Quick start

Tracker is a normal Vue component. The same props, emits, update-identity, and exposed-handle contracts apply when using <script setup>, the Options API, or another standard Vue component authoring style.

<script lang="ts">
import { defineComponent, shallowRef } from 'vue';
import { Tracker, type TrackerProps } from '@rightxt/tracker-vue';
import '@rightxt/tracker-vue/style.css';

export default defineComponent({
  name: 'ArticleTracker',
  components: { Tracker },
  setup() {
    const options = shallowRef<TrackerProps['options']>({
      a11y: { enabled: true, keyboard: true },
    });
    const rules = shallowRef<TrackerProps['rules']>([{ selector: '.article-section', label: (element) => element.textContent }]);

    function showIndividualMarkers() {
      options.value = { ...options.value, clustering: { enabled: false } };
    }

    function handleMarkerActivate(payload: { selector: string }) {
      console.log(payload.selector);
    }

    return { options, rules, showIndividualMarkers, handleMarkerActivate };
  },
});
</script>

<template>
  <button type="button" @click="showIndividualMarkers">Show individual markers</button>
  <main>
    <h1>Article</h1>
    <h2 class="article-section">Introduction</h2>
    <p>Your article content goes here.</p>
    <h2 class="article-section">Details</h2>
  </main>
  <Tracker :options="options" :rules="rules" @marker-activate="handleMarkerActivate" />
</template>

The shallow refs preserve top-level identities until replacement. The article is outside Tracker; default source scope finds it in the component root's document body. Vue owns teardown.

Component model and concepts

A source element is a matched DOM element. A rule selects sources and defines labels, presentation, scrolling, and focus. A marker represents one source position; a cluster groups nearby markers with a primary marker. The track represents the scroll range; its viewport indicator represents the visible portion. Logical selection is distinct from browser focus.

Tracker is the RxtTracker Vue component. It renders a .rxtt root without an extra wrapper, with .rxtt__viewport, .rxtt__markers, and .rxtt__marker descendants. Vue owns this DOM. Source and scroll roots select what is tracked; they do not move the component's output.

The complete prop surface is:

The seven emits are separate from these four props. Default slots/content do not define sourceRoot; default and named slots are not forwarded as tracked content. The component uses inheritAttrs: false and does not forward fallthrough attributes or classes to .rxtt. Use options/rules and reachable CSS. There is no Tracker render-target or renderHost prop; Vue Teleport is not a substitute for the package's realm requirements.

Configuration

Supply whole options and whole rules values. There is no patch-style options API, incremental rule API, or declarative { render: false } escape. An own options.rules key throws native TypeError; rules belong only to the separate prop.

Vue's adapter uses shallow/reference identity gating, not deep watch semantics. Mutating options.a11y.label inside the same options object or editing the same rules array in place is not a supported declarative update signal. Assign a new object or new rules array. Omitted option leaves reset to replacement defaults; omitted rules resolve to the empty list.

The tables below cover all 36 option leaves. Every field is optional; structural containers are not additional leaves. Known own undefined values inside configuration and unknown fields reject. Null is valid only where explicitly listed. Normal configuration rejects any diagnostic, including warnings, without partially accepting that candidate.

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

The complete replacement must have a valid accessibility combination. Set both fields consistently when disabling keyboard accessibility. Logical selection is separate from browser focus; preserve visible focus and selected-item styling in custom output.

Diagnostics

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: an Element source searches descendants, not itself, and queries do not automatically enter shadow trees or iframes. 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.

Normal declarative configuration rejects diagnostic-bearing rule replacement. 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 declarative replacement to silently accept only the valid portion. Validation and recovery and activation behavior provide the detailed contracts.

Build the desired complete list and supply a new rules array; [] clears it. Function-valued labels and targets remain synchronous JavaScript callbacks. There is no separate rule mutation method on the exposed handle.

Lifecycle and reconciliation

Setup and mounting

One Projection runtime is created and initial options/rules are validated during component setup(). In onMounted(), the adapter installs seven event mappings and mounts if the render root exists and both root props are non-null. Initial Core synchronization is synchronous inside mount; initial synchronization notifications are staged until initial Projection state has committed.

DOM mounting belongs to the browser onMounted() lifecycle. Runtime creation in setup is distinct from measured, mounted geometry; do not use handle synchronization before mount.

Shallow post-flush updates and recovery

A shallow watch with flush: 'post' observes options, rules, sourceRoot, and scrollRoot identities. With unchanged roots, new configuration identities cause complete configuration replacement and flush pending Projection work while mounted. The flush completes before reconciliation returns, but Vue owns the subsequent DOM patch and browser paint timing.

For a root change, the current mount unmounts first, changed configuration is committed, and the new mount is attempted. Either null root leaves the same integration alive but unmounted, with its shell hidden and non-interactive. Later valid roots can remount it. Stats and marker-key history persist within that same runtime; current mounted records are rebuilt.

A failed root mount does not restore the old mount. A valid replacement configuration can remain committed before the new mount fails. There is no multi-operation adapter rollback restoring the previous configuration and roots together. Static validation precedes side effects, so an invalid static configuration does not partially replace committed runtime configuration.

A failed remount may leave the same integration alive and unmounted. Correct the root props with valid new identities to recover that component generation. This recovery does not require creating a fresh runtime.

Component teardown

onBeforeUnmount() removes event mappings and synchronously destroys the runtime. Cleanup errors can propagate through Vue lifecycle handling as an error or AggregateError. A later component setup creates a fresh runtime.

Capture the handle or whenRuntimeDestroyed() Promise before Vue clears the template ref. The Promise is stable for the captured generation and resolves after terminal cleanup attempts even if cleanup throws. The adapter has no special KeepAlive/deactivation lifecycle contract; ordinary rerenders and explicit root changes do not imply support for arbitrary temporary detachment.

Events

The component declares exactly seven emits. Each forwards the unchanged Core payload synchronously through the current Vue emit channel:

Activation emits notify after Core behavior; listener return values cannot cancel scrolling, focus, or activation. Disabling activation suppresses those semantic actions/notifications; drag capability is independent. Sync emits describe a Core transaction, not a Vue DOM patch, browser layout, or paint. Metrics-dependent timing can be null.

Tracker-owned payload containers are frozen; source Elements and native Events are borrowed. Warning details is a borrowed live graph, not a deeply frozen retained diagnostic copy. Copy values needed for application history.

Vue owns listener dispatch, sibling/array ordering, and its listener error handling. The adapter does not cache individual listeners: it uses the current emit channel. If a synchronous failure escapes emit(), the adapter catches and host-reports it through globalThis.reportError() or a microtask-throw fallback. That escaped failure is kept out of Core integration-event-handler-error diagnostics and integration-handler error stats.

The adapter does not await or inspect listener returns. Vue observes rejected listener Promises according to its runtime configuration; catch asynchronous work explicitly when a controlled application reporting path is needed.

There is no destroy emit, generic error emit, mount emit, or unmount emit. Use whenRuntimeDestroyed() on the captured handle for terminal completion.

Exposed handle

A normal template ref is populated by Vue's lifecycle. Give Tracker a template ref and retain the exposed TrackerHandle before unmount when needed:

<script lang="ts">
import { defineComponent, shallowRef } from 'vue';
import { Tracker, type TrackerHandle } from '@rightxt/tracker-vue';
import '@rightxt/tracker-vue/style.css';

export default defineComponent({
  components: { Tracker },
  setup() {
    const tracker = shallowRef<TrackerHandle | null>(null);

    function refreshTrackedContent() {
      if (tracker.value?.getState() === 'mounted') {
        tracker.value.refresh();
      }
    }

    return { tracker, refreshTrackedContent };
  },
});
</script>

<template>
  <button type="button" @click="refreshTrackedContent">Refresh tracked content</button>
  <Tracker ref="tracker" />
</template>

This handle exposes exactly six methods:

Stats include render/rule/marker/cluster/observer counters, warning/error totals and last entries, timing, and optional debug metadata. diagnostics.metrics gates timing only. Reset also zeros current counters without clearing rendered records or configuration. The underlying stats reference gives field detail.

There are no snapshots (getSnapshot()/subscribeSnapshot()), options/rules getters (getOptions()/getRules()), Core event subscriptions (on()/off()), render-root getter, boolean lifecycle getters, render()/requestRender() aliases, or consumer destroy(). The exposed handle does not provide the Core integration, Projection facade, or advanced trace. Vue teardown owns terminal destruction; retained handle functions continue to target their original generation.

Observation and manual refresh

A normal Vue rerender with unchanged options/rules/root identities is not a generic Core synchronization request. External source DOM/layout changes use configured mutation, resize, scroll, and interval updates or explicit refresh(). Use requestRefresh() for scheduled/coalesced synchronization while mounted.

CSS/CSSOM-only geometry changes may require explicit refresh. Disabling automatic sources shifts their synchronization responsibility to the caller; disabling scroll updates also stops automatic viewport synchronization. Initial mounting and accepted declarative configuration updates still synchronize. See updates and refresh for observer target resolution and scheduling.

Environments

Documents and containers

The actual Vue-owned .rxtt ownerDocument/Window defines the active realm. With roots omitted, source scope is that document's body and scrolling uses its Window. Page-scroller element aliases also select window mode.

An HTMLElement scrollRoot selects one authoritative element scroll range; omitted sourceRoot then resolves to the scroll element. Explicit sources must satisfy same-document and scroll-subtree constraints. Relevant descendant scrolling is separately observed for invalidation; it does not add independently represented scroll ranges. Output stays at the component's render location. Place the track beside the container and follow the supported geometry/CSS profile in environments.

Use null roots while DOM refs are unavailable. The shell remains hidden and non-interactive while the same runtime is unmounted; valid/undefined roots can mount it again.

Use a connected scroll container in a standards-mode document with a positive client extent along the represented axis. Supported container displays are block, flow-root, flex, inline-flex, grid, inline-grid, and inline-block; represented-axis overflow must be auto, scroll, or hidden. Active scroll snap, reverse flex/wrap that reverses that axis, and replaced/form-control elements are outside the supported profile. A zero current scroll range is valid. Overlay alignment, transforms, zoom, and surrounding layout remain application responsibilities.

Shadow DOM

Open ShadowRoot source scope is supported. Selectors do not automatically pierce shadow boundaries. Output can live in a shadow tree when Vue actually renders Tracker there; install package/theme CSS in that scope and keep all roots in the same active document.

Same-origin iframes and Teleport

The safe form is a Vue application/render root genuinely created in the child document/realm, with Tracker and source/scroll roots there. Load package CSS in that child document. A parent-document Tracker cannot target child source/scroll roots; mixed roots reject with ERR_TRACKER_REALM_MISMATCH.

Parent-realm Vue Teleport into a child iframe is not fully realm-safe for this adapter. Item registration checks ambient-realm instanceof HTMLElement; child elements can fail that check, making selection registration/selected-attribute behavior unreliable. There is no custom Tracker render-target prop or cross-origin bridge.

After navigation, recreate the iframe-local component with fresh document/root identities. The adapter does not watch render-root ownerDocument changes, so stale roots or Teleport relocation alone do not establish a fresh realm lifecycle.

Styling

Import @rightxt/tracker-vue/style.css before application theme CSS. JavaScript does not inject the canonical stylesheet. The stylesheet must reach the actual .rxtt scope. Global CSS is a reliable default; arbitrary parent scoped CSS does not automatically style all Tracker internals. Use Vue's appropriate deep/global styling reach when using scoped styles. Fallthrough classes/attributes are not forwarded.

Use options.cssVariables, rule marker.cssVariables, supported attributes, and reachable CSS. Committed root strings remain unchanged; standard Projection root output trims nonblank strings and omits blank/whitespace-only values. Vue adds no second normalization pass. Item/rule style maps follow the Vue item style path; do not apply the root trim/drop guarantee to every item map.

Renderer-owned geometry and data-rxtt-* metadata are not application configuration or business identifiers. data-rxtt-drag="true" denotes enabled drag capability, not an active drag session. Preserve focus and selected-item styling. Shadow trees and child documents require CSS in their own scope.

The styling reference documents all 33 root variables, 17 rule variables, and service metadata. The Theme Builder source entry provides theme exploration.

Debug and diagnostics

Neutral external Core entries keep the Vue API independent of Core build selection. A resolver activating Core's development condition composes debug Core, which may add debug metadata to getStats(). Vue development mode alone does not replace external Core resolution. There is no Vue-local debug JavaScript artifact. getTrackerDebugTrace() is not exposed; the underlying Projection integration stays private.

Use options.diagnostics.output for diagnostic sinks and the warning emit for warning notifications. diagnostics.warnings controls only fallback console.warn, not the configured sink, warning stats/events, or errors. Metrics controls timing only.

Core configuration/lifecycle errors can propagate through setup, prop reconciliation, lifecycle hooks, and handle methods. Their classes/codes are preserved but not re-exported by this package. Examples include TrackerConfigurationError, TrackerLifecycleError, ERR_TRACKER_INVALID_CONTEXT, ERR_TRACKER_DESTROYED, and ERR_TRACKER_REALM_MISMATCH where applicable. Native TypeError for options.rules and cleanup AggregateError are additional boundaries; no Vue-local stable error-code family is exposed.

Vue dispatch/error handling owns listener failures. Exceptions escaping emits are caught and host-reported by the adapter rather than counted as Core integration-handler failures. This listener boundary is separate from configuration/lifecycle error propagation. The runtime diagnostics reference adds channel detail without exposing snapshots or trace through the Vue handle.

Demos and further documentation

These links open repository source documentation:

• Vue playground: component setup and interactive configuration.
• Vue container scenario: positioning the track beside an element scroller.
• Vue events scenario: emits and synchronization timing.
• Environments, updates and refresh, rules and marker behavior, and styling: supplementary workflow and field detail.