@buildinams/core 0.3.0 → 0.4.0

package/dist/tracking/dom/index.d.ts

@@ -0,0 +1,320 @@
+import { l as Clicked, d as EventCatalog, m as EcommerceOccurrences, j as EcommerceShapes, n as ShapeLeaf, F as FormUsed, P as PageViewed, o as Scrolled, V as VideoPlayed } from '../../define-events-CxZjoUlG.js';
+export { p as PageType } from '../../define-events-CxZjoUlG.js';
+import { S as Subscribe } from '../../listeners-DkU-vBPa.js';
+
+/** The data, or a function that builds it when a plugin first reads it, e.g. when the element becomes visible. */
+type TrackValue<Data> = Data | (() => Data);
+
+declare const ROLE = "data-track";
+type AutoTrackKind = "links" | "forms";
+
+/** What a plugin reports, as the watcher's listeners receive it. */
+type DomEvent<Name extends string = string, Payload extends object = object, Source extends Element | undefined = Element | undefined> = undefined extends Source ? {
+    name: Name;
+    payload: Payload;
+} : {
+    name: Name;
+    payload: Payload;
+    element: Source;
+};
+declare const plugin: unique symbol;
+/**
+ * Created by `pageViews()`, `ecommerce()`, `clicks()`, `videos()`, `forms()` or `scroll()`, and passed to
+ * `createDomWatcher()`. Its type says what it reports, and the fields, data and `auto` kinds `track()` takes.
+ */
+type DomPlugin<Event extends DomEvent = DomEvent, Attributes extends object = object, Data extends object = object, Auto extends AutoTrackKind = AutoTrackKind> = {
+    readonly [plugin]?: {
+        event: Event;
+        attributes: Attributes;
+        data: Data;
+        auto: Auto;
+    };
+};
+/** A plugin's own `data-track-<field>` attributes, each a string. */
+type CustomFields = Record<string, string>;
+
+/**
+ * Plugin for `createDomWatcher()`: `clicked` for links and buttons with `track({ click })`, and links inside
+ * `track({ auto: "links" })`, with `location` from the nearest `track({ location })`. `Fields` are the project's own
+ * fields of `click`, also in the payload.
+ *
+ * @example
+ * ```ts
+ * clicks<{ cta: string }>();
+ * ```
+ */
+declare const clicks: <Fields extends CustomFields = Record<never, never>>() => DomPlugin<{
+    name: "clicked";
+    payload: Clicked & Partial<Fields>;
+    element: Element;
+}, {
+    click: {
+        id?: string;
+    } & Fields;
+    location: {
+        name: string;
+    };
+}, Record<never, never>, "links">;
+
+/** What `track()` returns to spread on the element. */
+type TrackProps = {
+    [ROLE]?: string;
+} & {
+    [name: `${typeof ROLE}-${string}`]: string;
+};
+
+type DomWatcherOptions = {
+    /** Where the plugins watch for markup and events. Defaults to `document`. */
+    root?: Document | Element;
+};
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
+type Brand<Plugin> = NonNullable<Plugin extends DomPlugin ? Plugin[keyof Plugin] : never>;
+/** What the plugins report, as the watcher's listeners receive it. */
+type DomEventOf<Plugins extends readonly DomPlugin[]> = Brand<Plugins[number]>["event"];
+type AttributesOf<Plugins extends readonly DomPlugin[]> = UnionToIntersection<Brand<Plugins[number]>["attributes"]>;
+type DataOf<Plugins extends readonly DomPlugin[]> = UnionToIntersection<Brand<Plugins[number]>["data"]>;
+type AutoOf<Plugins extends readonly DomPlugin[]> = Brand<Plugins[number]>["auto"];
+/** Payloads of the plugins' events, by name. */
+type EventMapOf<Event extends {
+    name: string;
+    payload: object;
+}> = {
+    [E in Event as E["name"]]: E["payload"];
+};
+/** What `track()` takes: per type, its fields, or `true` when they're all optional, and data for `ecommerce()`. */
+type TrackSpec<Plugins extends readonly DomPlugin[]> = {
+    [T in keyof AttributesOf<Plugins>]?: Record<never, never> extends AttributesOf<Plugins>[T] ? AttributesOf<Plugins>[T] | true : AttributesOf<Plugins>[T];
+} & {
+    [R in keyof DataOf<Plugins>]?: TrackValue<DataOf<Plugins>[R]> | undefined;
+} & ([AutoOf<Plugins>] extends [never] ? unknown : {
+    auto?: AutoOf<Plugins> | readonly [AutoOf<Plugins>, ...AutoOf<Plugins>[]] | false;
+});
+type Tracked<Spec, Data> = [keyof Spec & keyof Data] extends [never] ? TrackProps : TrackProps & {
+    ref: (element: Element | null) => void;
+};
+type DomWatcher<Plugins extends readonly DomPlugin[]> = {
+    /**
+     * Props to spread on an element, so the plugins track it. Each key is a type, written in `data-track`, with its fields
+     * as `data-track-<field>` attributes, so server components and CMS markup can write them too. Only the types of the
+     * watcher's plugins:
+     *
+     * - `pageView`: `pageViewed` when the element appears, with `pageViews()`. Put it on each page's root.
+     * - `click`: `clicked` for this button or link, with `clicks()`. Buttons always need it.
+     * - `location`: `location` on every `clicked` inside it, with `clicks()`. Reports nothing by itself.
+     * - `auto`: tracks every link (`"links"`) or form (`"forms"`) inside it, with `clicks()` and `forms()`; `false` turns
+     *   it off for a subtree. The nearest one decides.
+     * - `video`: video events for this `<video>` or the videos inside it, with `videos()`.
+     * - `form`: `formStarted` and `formSubmitted` for this form, with `forms()`.
+     * - `scroll`: `scrolled` as the visitor scrolls through this element, with `scroll()`.
+     *
+     * The project's item, list or promotion, for `ecommerce()`, come with a `ref`, which sets the data on the element
+     * once it mounts, so it stays out of the HTML. Without data, e.g. while a quick view is closed, the element isn't
+     * tracked as one.
+     *
+     * - `viewItem`: `itemViewed` when visible, once per URL for each product. On a product page.
+     * - `quickView`: `itemViewed` each time it becomes visible. On a quick view.
+     * - `promotion`: `promotionViewed` when visible, `promotionSelected` for clicks inside it.
+     * - `list`: places the items inside it in the list.
+     * - `item`: `itemsViewed` when visible, batched per list, `itemSelected` for clicks inside it.
+     *
+     * Data can be a function, built when the plugin first reads it, e.g. when the element becomes visible; once read, a
+     * new function from a later render is built to compare it, so keep it stable where building is costly. An element
+     * with its own ref needs a ref that calls both. Without a framework, call `ref` with the element: it also adds or
+     * removes the data's types.
+     *
+     * @example
+     * ```tsx
+     * <main {...track({ pageView: { pageType: "product" } })}>
+     * <footer {...track({ auto: "links", location: { name: "footer" } })}>
+     * <section {...track({ promotion: { id: "summer" }, location: { name: "hero" } })}>
+     * ```
+     */
+    track: <Spec extends TrackSpec<Plugins>>(spec: Spec & Record<Exclude<keyof Spec, keyof TrackSpec<Plugins>>, never>) => Tracked<Spec, DataOf<Plugins>>;
+    /**
+     * Hands what the plugins report to `listener`: every event, or only those named. Pass the watcher to
+     * `createAnalytics()`'s `sources` instead to track them. The first subscription starts the plugins in the browser,
+     * and the last one to unsubscribe stops them. What they report while starting, e.g. a server-rendered page's view,
+     * reaches every subscription made in the same task.
+     */
+    subscribe: Subscribe<DomEventOf<Plugins>>;
+    /** Catalog entries for what the plugins report, to spread into `defineEvents()`. */
+    events: EventCatalog<EventMapOf<DomEventOf<Plugins>>>;
+    /**
+     * Tells the plugins a new page is shown, for a router that tracks page views itself instead of `pageViews()`. Views
+     * pending from the previous page are emitted, and what stays in view counts again.
+     */
+    newPage: () => void;
+    /** Emits the views `ecommerce()` batches, e.g. right before tracking an event that must come after them. */
+    flush: () => void;
+};
+/**
+ * Watches markup with the plugins you pass and reports what happens, so call sites only need the watcher's `track()`.
+ * Creating it does nothing, so server components can import it; the first `subscribe()` starts it in the browser:
+ *
+ * - `pageViews()`: `pageViewed` for `track({ pageView })`.
+ * - `ecommerce()`: `itemViewed`, `itemsViewed`, `itemSelected`, `promotionViewed` and `promotionSelected` for
+ *   `track({ viewItem | quickView | list | item | promotion })`.
+ * - `clicks()`: `clicked` for links and buttons with `track({ click })`, and links inside `track({ auto: "links" })`.
+ * - `videos()`: `videoStarted`, `videoProgressed` and `videoCompleted` for `track({ video })`.
+ * - `forms()`: `formStarted` and `formSubmitted` for `track({ form })`, and forms inside `track({ auto: "forms" })`.
+ * - `scroll()`: `scrolled` as `track({ scroll })` is scrolled into view, by default at 25, 50, 75 and 90%.
+ *
+ * The plugins decide which types `track()` takes, and with which fields and data. Nothing is tracked without its type
+ * in `data-track`, so a project decides what reaches analytics. Works with server-rendered and CMS markup, as it
+ * listens on the root instead of the elements.
+ *
+ * @example
+ * ```ts
+ * export const domWatcher = createDomWatcher([pageViews(), clicks<{ cta: string }>(), ecommerce<{ item: Item }>()]);
+ * export const { track } = domWatcher;
+ *
+ * export const events = defineEvents({ ...domWatcher.events });
+ * export const analytics = createAnalytics<EventsOf<typeof events>>({ events, sources: [domWatcher], consent });
+ * ```
+ */
+declare const createDomWatcher: <const Plugins extends readonly DomPlugin[]>(plugins: Plugins, { root: rootOption }?: DomWatcherOptions) => DomWatcher<Plugins>;
+
+type Occurrences = EcommerceOccurrences<EcommerceShapes>;
+/** The project's item, and its list and promotion when it has them. */
+type EcommerceInput = {
+    item: object;
+    list?: object;
+    promotion?: object;
+};
+type Complete<Shapes extends EcommerceInput> = {
+    item: Shapes["item"];
+    list: ShapeLeaf<Shapes, "list">;
+    promotion: ShapeLeaf<Shapes, "promotion">;
+};
+type EcommerceEvent<Shapes extends EcommerceInput> = {
+    [K in keyof Occurrences]: DomEvent<K, EcommerceOccurrences<Complete<Shapes>>[K], undefined>;
+}[keyof Occurrences];
+type EcommerceData<Shapes extends EcommerceInput> = {
+    viewItem: Shapes["item"];
+    quickView: Shapes["item"];
+    item: Shapes["item"];
+} & Pick<Complete<Shapes>, Extract<keyof Shapes, "list" | "promotion">>;
+type EcommerceOptions<Item = object> = {
+    /**
+     * Which product an item is, e.g. `({ product }) => product.id`, so a product page's `{ product, variant }` matches
+     * the `{ product }` of the card it was selected on, and counts as one view per product. Defaults to the item's JSON.
+     */
+    id?: (item: Item) => string;
+    /** Share of a promotion or item, or of the viewport for those taller than it, that counts as viewed. */
+    threshold?: number;
+    /**
+     * Milliseconds that views are collected for before they're tracked in the order they happened, with one
+     * `itemsViewed` per list.
+     */
+    batchDelay?: number;
+    /**
+     * Where the tab keeps the placements of the products last selected, so a product page loaded in full, e.g. on a
+     * multi-page site, gets the list it was selected from. Change it when the list's or promotion's shape changes. Default
+     * `"analytics-placements"`.
+     */
+    storageKey?: string;
+};
+/**
+ * Plugin for `createDomWatcher()`: views and selections of products, lists and promotions, with the data passed to the
+ * watcher's `track()`, placed by the markup around it:
+ *
+ * - `itemViewed` for `track({ viewItem })` when it becomes visible, and `track({ quickView })` each time it does.
+ * - `promotionViewed` and `promotionSelected` for `track({ promotion })`.
+ * - `itemsViewed` and `itemSelected` for `track({ item })`, inside `track({ list })`.
+ *
+ * Views are batched, and emitted before anything else the watcher emits. Leave out `list` or `promotion` when the
+ * project has none.
+ *
+ * @example
+ * ```ts
+ * ecommerce<{ item: { product: ProductFragment; variant?: VariantFragment }; list: List }>({
+ *   id: ({ product }) => product.id,
+ * });
+ * ```
+ */
+declare const ecommerce: <Shapes extends EcommerceInput>({ id, threshold, batchDelay, storageKey, }?: EcommerceOptions<Shapes["item"]>) => DomPlugin<EcommerceEvent<Shapes>, Record<never, never>, EcommerceData<Shapes>, never>;
+
+/**
+ * Plugin for `createDomWatcher()`: `formStarted` and `formSubmitted` for forms with `track({ form })` or inside
+ * `track({ auto: "forms" })`. Never field values. `Fields` are the project's own fields of `form`, also in
+ * the payload.
+ */
+declare const forms: <Fields extends CustomFields = Record<never, never>>() => DomPlugin<{
+    name: "formStarted";
+    payload: FormUsed & Partial<Fields>;
+    element: HTMLFormElement;
+} | {
+    name: "formSubmitted";
+    payload: FormUsed & {
+        formSubmitText?: string;
+    } & Partial<Fields>;
+    element: HTMLFormElement;
+}, {
+    form: {
+        id?: string;
+    } & Fields;
+}, Record<never, never>, "forms">;
+
+/**
+ * Plugin for `createDomWatcher()`: `pageViewed` for elements with `track({ pageView })` when they appear or are shown
+ * again, once per URL. `Fields` are the project's own fields of `pageView`, also in the payload.
+ *
+ * @example
+ * ```ts
+ * pageViews<{ section: string }>();
+ * ```
+ */
+declare const pageViews: <Fields extends CustomFields = Record<never, never>>() => DomPlugin<{
+    name: "pageViewed";
+    payload: PageViewed & Partial<Fields>;
+    element: Element;
+}, {
+    pageView: PageViewed & Fields;
+}, Record<never, never>, never>;
+
+type ScrollOptions = {
+    /** Percentages of the element scrolled into view that each report `scrolled` once per URL. */
+    thresholds?: readonly number[];
+};
+/**
+ * Plugin for `createDomWatcher()`: `scrolled` for elements with `track({ scroll })`, once per URL for each threshold
+ * (25, 50, 75 and 90%) of the element scrolled into view. Only after a scroll, also a restored scroll position, so an
+ * element that fits the viewport isn't tracked on load. Put it on the page's root for scroll depth, or on an article.
+ * `Fields` are the project's own fields of `scroll`, also in the payload.
+ */
+declare const scroll: <Fields extends CustomFields = Record<never, never>>({ thresholds, }?: ScrollOptions) => DomPlugin<{
+    name: "scrolled";
+    payload: Scrolled & Partial<Fields>;
+    element: Element;
+}, {
+    scroll: {
+        id?: string;
+    } & Fields;
+}, Record<never, never>, never>;
+
+/**
+ * Plugin for `createDomWatcher()`: `videoStarted`, `videoProgressed` (10, 25, 50 and 75%) and `videoCompleted` for
+ * `<video>` elements with, or inside, `track({ video })`, so decorative loops aren't tracked. `Fields` are the
+ * project's own fields of `video`, also in the payload.
+ */
+declare const videos: <Fields extends CustomFields = Record<never, never>>() => DomPlugin<{
+    name: "videoStarted";
+    payload: VideoPlayed & Partial<Fields>;
+    element: HTMLVideoElement;
+} | {
+    name: "videoProgressed";
+    payload: VideoPlayed & {
+        videoPercent: number;
+    } & Partial<Fields>;
+    element: HTMLVideoElement;
+} | {
+    name: "videoCompleted";
+    payload: VideoPlayed & Partial<Fields>;
+    element: HTMLVideoElement;
+}, {
+    video: {
+        title?: string;
+    } & Fields;
+}, Record<never, never>, never>;
+
+export { type DomPlugin, type DomWatcher, type DomWatcherOptions, type EcommerceOptions, type TrackProps, type TrackSpec, clicks, createDomWatcher, ecommerce, forms, pageViews, scroll, videos };