[Feature] Add a Trk component for easier analytics tagging

[titouanmathis]

Summary

A generic, declarative component to standardize analytics tracking in @studiometa/ui projects. Compatible with GTM/dataLayer, GA4, Segment, and custom backends.

API

Basic Usage (data-on:* syntax)

 <!-- Click tracking -->
 <button
   data-component="Trk"
   data-on:click='{"event": "cta_click", "location": "header"}'>
   Subscribe
 </button>

 <!-- Page load data (ecommerce, user info) -->
 <div
   data-component="Trk"
   data-on:mounted='{"event": "view_item_list", "ecommerce": {"items": [...]}}'
   hidden>
 </div>

 <!-- Impression tracking (IntersectionObserver) -->
 <div
   data-component="Trk"
   data-on:view.once='{"event": "product_impression", "id": "123"}'>
   Product Card
 </div>

Event Modifiers (same as Action)

Modifier	Effect
.prevent	event.preventDefault()
.stop	event.stopPropagation()
.once	Track only once
.passive	Passive event listener
.capture	Capture phase
.debounce / .debounce500	Debounce (default 300ms)
.throttle / .throttle200	Throttle (default 16ms)

Hierarchical Context

 <section
   data-component="TrkContext"
   data-option-data='{"page_type": "product", "product_id": "123"}'>

   <button
     data-component="Trk"
     data-on:click='{"action": "add_to_cart"}'>
     Add to Cart
   </button>
   <!-- Dispatches: { page_type: "product", product_id: "123", action: "add_to_cart" } -->
 </section>

Custom Events

Works with any Custom Event emitted by other scripts:

 <!-- Listen to custom event -->
 <third-party-form
   data-component="Trk"
   data-on:form-submitted.detail='{"event": "form_submitted"}'>
 </third-party-form>
 <!-- Merges event.detail into tracking data -->

 <!-- Or pick specific fields with $detail.* syntax -->
 <third-party-form
   data-component="Trk"
   data-on:form-submitted='{"event": "form_submitted", "email": "$detail.email"}'>
 </third-party-form>

Custom Dispatcher

 import { setTrkDispatcher } from '@studiometa/ui';

 // Default is window.dataLayer.push (GTM)
 setTrkDispatcher((data, event) => {
   gtag('event', data.event, data);
 });

Supported Events

• DOM events: click, submit, change, input, focus, blur, scroll, etc.
• Special events:
  • mounted - Dispatch on component mount (page load data)
  • view - IntersectionObserver-based impression tracking

Consent (GDPR)

Handled at GTM/Axeptio level. Trk just pushes to dataLayer[]. GTM fires tags based on consent triggers.

Benefits

1. No custom JS required - Fully declarative in HTML/Twig
2. No inline scripts - mounted event replaces <script> blocks
3. Consistent API - One component for all tracking
4. Built-in modifiers - .once, .debounce, .throttle

---

Sources

notes.md
task_plan.md

[antoine4livre]

@titouanmathis It would be the only component with an abbreviation as component name. Why not call it Track or Layer or DataLayer ?

[titouanmathis]

Proposed design for Track

Following the discussion on #497 and #504, here is a consolidated design that merges the strengths of both PRs and resolves the open concerns (JSON-in-attributes vs Liquid, the Action data-on:* collision, Shopify coupling, hierarchical context). A new PR will implement this and supersede #497 and #504.

The design mirrors the repo's existing AbstractFigure → Figure / FigureShopify / FigureTwicpics pattern: a provider-agnostic core with provider variants selected declaratively by component name.

Component set

Component	Role
AbstractTrack	Provider-agnostic core: event grammar, payload sources, context merge, view/mounted/DOM-event orchestration. Declares the dispatch(data, event?) seam (the analog of FigureShopify.formatSrc).
Track extends AbstractTrack	Generic variant → window.dataLayer.push() (GTM).
TrackShopify extends AbstractTrack	Shopify variant → Shopify.analytics.publish(name, data). Overrides only the seam.
TrackContext	Container providing context inherited by descendant Tracks, merged up the ancestor chain. Provider-agnostic.

Each is a separate export the consumer registers (like Figure/index.ts). The provider is chosen in markup — data-component="TrackShopify" vs "Track" — with no global dispatcher and no Shopify code in the generic class.

TrackContext — container, dual data source, merged from ancestors

Context data comes from either or both:

• <script data-ref="context" type="application/json"> — rich payloads, Liquid-safe (element text, so no attribute-quote hazard);
• data-option-context='{…}' — simple/flat cases.

Within one context the attribute overrides the script (inline/most-specific wins). Across the tree, context is merged recursively up the ancestors (nearer wins), resolved with $closest('TrackContext'):

const REPLACE = (_dst: unknown[], src: unknown[]) => src; // arrays replace, not concat

class TrackContext extends Base {
  static config = { name: 'TrackContext', refs: ['context'], options: { context: Object } };

  get scriptData() {
    const el = this.$refs.context;
    try { return el ? JSON.parse(el.textContent ?? '{}') : {}; }
    catch { this.$warn('Invalid TrackContext <script> JSON'); return {}; }
  }
  get attrData() {
    try { return this.$options.context ?? {}; }            // OptionsManager JSON.parse throws on bad JSON
    catch { this.$warn('Invalid data-option-context JSON'); return {}; }
  }
  get ownData() { return deepmerge(this.scriptData, this.attrData, { arrayMerge: REPLACE }); }
  get context(): Record<string, unknown> {
    const parent = this.$closest<TrackContext>('TrackContext');
    return parent ? deepmerge(parent.context, this.ownData, { arrayMerge: REPLACE }) : this.ownData;
  }
}

Track — event grammar + dual payload + inherited context

• Events: data-track:<event>[.modifier…] — multiple per element; view (impression, IntersectionObserver), mounted, and any DOM event; modifiers .once/.prevent/.stop/.debounce/.throttle/… (from [Feature] Add Track component for declarative analytics tracking #497).
• Payload, two sources (both optional): a shared <script data-ref="payload" type="application/json"> and the per-event attribute value data-track:click='{…}'.
• Dispatched payload for an event, deep-merged, most-specific wins:

class AbstractTrack extends Base {
  static config = { name: 'AbstractTrack', refs: ['payload'], options: { /* … */ } };

  get context() { return this.$closest<TrackContext>('TrackContext')?.context ?? {}; }

  payloadFor(eventAttrData: object) {
    return deepmerge.all(
      [this.context, this.scriptPayload ?? {}, eventAttrData ?? {}],
      { arrayMerge: REPLACE },
    );
  }
  dispatch(_data: Record<string, unknown>, _event?: Event) { /* seam — no-op in abstract */ }
}

class Track extends AbstractTrack {
  static config = { ...AbstractTrack.config, name: 'Track' };
  dispatch(data) { (window.dataLayer ??= []).push(data); }
}

class TrackShopify extends AbstractTrack {
  static config = { ...AbstractTrack.config, name: 'TrackShopify' };
  dispatch(data) {
    if (typeof window.Shopify?.analytics?.publish !== 'function')
      return this.$warn('Shopify.analytics.publish unavailable');
    window.Shopify.analytics.publish(data.event, data); // called bound, not detached
  }
}

Worked example (Shopify + Liquid)

<section data-component="TrackContext">
  <script data-ref="context" type="application/json">
    { "page_type": "product", "currency": {{ cart.currency.iso_code | json }} }
  </script>

  <div data-component="TrackContext" data-option-context='{"list":"pdp-upsell"}'>
    <script data-ref="context" type="application/json">
      { "item": { "id": {{ product.id | json }}, "name": {{ product.title | json }} } }
    </script>

    {# impression: the card is its own tracked element #}
    <article data-component="TrackShopify" data-track:view.once='{"event":"my_app:view_item"}'>
      {# click: the button is its own tracked element #}
      <button data-component="TrackShopify" data-track:click='{"event":"my_app:add_to_cart"}'>
        Add to cart
      </button>
    </article>
  </div>
</section>

The add-to-cart click dispatches:

Shopify.analytics.publish("my_app:add_to_cart", {
  page_type: "product", currency: "EUR", list: "pdp-upsell",
  item: { id: 123, name: "…" }, event: "my_app:add_to_cart"
})

Merge precedence (most-specific wins)

inheritedContext (ancestors, outer→inner) → scriptPayload → eventAttributePayload. Arrays replace (not concat) so a GA4 ecommerce.items list from an event overrides one from context instead of accumulating.

DOM/HTML constraints honored

• JSON in an attribute must be single-quoted and breaks on an apostrophe in the data under Liquid (Shopify doesn't autoescape attribute output) → rich data uses <script>; the attribute forms are documented as the simple / Twig-friendly path.
• A <script type="application/json"> block cannot contain the literal </script> → document the {{ value | json | replace: '</', '<\/' }} guard.
• A <script> cannot be a DOM ancestor → TrackContext is a container, the script is its data-ref child.
• The data block is inert: not rendered, not in the accessibility tree.
• Payloads are visible in the DOM → never embed PII; resolve sensitive values in JS; TrackShopify should honour customerPrivacy consent before publishing.
• No collision with Action — data-track:* is disjoint from Action's data-on:* matcher.

Decisions

1. Attribute overrides <script> within a component (inline wins).
2. Event-name key stays event (GTM dataLayer triggers on it; TrackShopify uses its value as the publish name). Shopify event values should be namespaced (my_app:event_name, per Shopify docs).
3. Arrays replace on merge.
4. view and mounted are reserved pseudo-events (IntersectionObserver / lifecycle); neither is a real DOM event, so collision risk is negligible.
5. One canonical data-option-context (no alias).

Known constraints / follow-ups

• Bundle: a variant off a rich AbstractTrack pulls in the whole core, so it can't reach Add Track component #504's ~429 B footprint; keep AbstractTrack lean and make heavy features ($detail.* templating, the full modifier grammar) opt-in modules rather than base methods.
• Native events bind to $el and fire for the whole subtree with event.target = the deepest node; a target-selector modifier may be added if per-descendant clicks are needed.
• Context is resolved at dispatch time; a Track firing mounted before its ancestor TrackContext has mounted would see empty context — resolution should tolerate mount order (e.g. resolve on the next frame for the mounted event).
• $warn only logs when data-option-log is set; malformed option JSON throws in OptionsManager before the component can warn — consider a dev-only console.error for unparseable payloads.