@fluid-topics/ft-wc-utils 2.0.31 → 2.0.32

package/build/ScopedRegistryLitElement.js

@@ -1,5 +1,6 @@
 import { LitElement } from "lit";
 import { adoptStyles } from "@lit/reactive-element/css-tag.js";
+import { customElement } from "./decorators";
 /**
  * Typescript would not let us use the mixin directly when upgrading Lit from 2.2.8 to 2.7.2
  *
@@ -30,6 +31,8 @@ export class ScopedRegistryLitElement extends LitElement {
         Object.entries(definitions).forEach(([tagName, klass]) => this.defineScopedElement(tagName, klass));
     }
     static defineScopedElement(tagName, klass) {
+        // eslint-disable-next-line ft/custom-elements
+        customElement(tagName)(klass);
         if (this.canDefineScopedElement(tagName)) {
             this.registry.define(tagName, klass);
         }

package/build/ft-analytics-action.mixin.d.ts

@@ -0,0 +1,62 @@
+import { LitElement } from "lit";
+import { Constructor } from "./generic-types";
+export type FtAnalyticsActionEventDetail = {
+    eventName: string;
+    actionType: string;
+    componentType: string;
+    componentId: string;
+    data?: Record<string, unknown>;
+};
+export declare class FtAnalyticsActionEvent extends CustomEvent<FtAnalyticsActionEventDetail> {
+    constructor(detail: FtAnalyticsActionEventDetail);
+}
+declare global {
+    interface DocumentEventMap {
+        "ft-analytics-action": FtAnalyticsActionEvent;
+    }
+    interface HTMLElementEventMap {
+        "ft-analytics-action": FtAnalyticsActionEvent;
+    }
+}
+export interface withAnalyticsInterface<Actions extends Record<string, unknown>> {
+    configuredAnalyticsActions: Partial<Record<keyof Actions, {
+        eventName: string;
+    }>>;
+    emitAnalyticsAction(actionType: keyof Actions, data?: Record<string, unknown>): void;
+}
+export type withAnalyticsType<T extends Constructor<LitElement>, Actions extends Record<string, unknown>> = T & Constructor<withAnalyticsInterface<Actions>> & {
+    readonly analyticsActions: Actions;
+};
+/**
+ * Mixin that enables a web component to participate in the analytics emitter model.
+ *
+ * Each component declares the analytics actions it can emit by passing an action map
+ * to the mixin factory. The map's keys are action types and the values carry a UI
+ * label used by the page designer for design-time discovery:
+ *
+ *     const analyticsActions = {
+ *         "clicked": { label: "Button clicked" },
+ *         "submitted": { label: "Form submitted" },
+ *     }
+ *     export class FtFoo extends withAnalytics(FtLitElement, analyticsActions) { … }
+ *
+ * Applying the mixin adds:
+ * - `static readonly analyticsActions`: the action map, exposed on the class for
+ *   design-time discovery (e.g. the page designer's GrapesJS trait reads
+ *   `el.constructor.analyticsActions` to render one row per available action type).
+ * - `configuredAnalyticsActions`: per-instance mapping of action type → `{ eventName }`,
+ *   set via the `configuredAnalyticsActions` attribute (JSON string). Written by the
+ *   page designer's analytics-events trait when a user enables tracking for a row.
+ * - `emitAnalyticsAction(actionType, data?)`: dispatches an `ft-analytics-action` custom
+ *   event (bubbles, composed) only when the given action type has a non-empty
+ *   `eventName` mapping in `configuredAnalyticsActions`.
+ *
+ *   The optional `data` payload is a placeholder for per-interaction context (e.g. the
+ *   clicked button's label, the submitted query, the selected option). It is currently
+ *   carried on the event detail but not forwarded to the analytics backend — reserved
+ *   for when `FtCustomTriggerEvent` gains a field for per-event properties.
+ *
+ * Composition: a parent component can re-expose its child's actions by
+ * spreading them into its own action map.
+ */
+export declare function withAnalytics<TBase extends Constructor<LitElement>, Actions extends Record<string, unknown>>(Base: TBase, analyticsActions: Actions): withAnalyticsType<TBase, Actions>;

package/build/ft-analytics-action.mixin.js

@@ -0,0 +1,72 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { jsonProperty } from "./decorators";
+export class FtAnalyticsActionEvent extends CustomEvent {
+    constructor(detail) {
+        super("ft-analytics-action", { composed: true, bubbles: true, detail });
+    }
+}
+/**
+ * Mixin that enables a web component to participate in the analytics emitter model.
+ *
+ * Each component declares the analytics actions it can emit by passing an action map
+ * to the mixin factory. The map's keys are action types and the values carry a UI
+ * label used by the page designer for design-time discovery:
+ *
+ *     const analyticsActions = {
+ *         "clicked": { label: "Button clicked" },
+ *         "submitted": { label: "Form submitted" },
+ *     }
+ *     export class FtFoo extends withAnalytics(FtLitElement, analyticsActions) { … }
+ *
+ * Applying the mixin adds:
+ * - `static readonly analyticsActions`: the action map, exposed on the class for
+ *   design-time discovery (e.g. the page designer's GrapesJS trait reads
+ *   `el.constructor.analyticsActions` to render one row per available action type).
+ * - `configuredAnalyticsActions`: per-instance mapping of action type → `{ eventName }`,
+ *   set via the `configuredAnalyticsActions` attribute (JSON string). Written by the
+ *   page designer's analytics-events trait when a user enables tracking for a row.
+ * - `emitAnalyticsAction(actionType, data?)`: dispatches an `ft-analytics-action` custom
+ *   event (bubbles, composed) only when the given action type has a non-empty
+ *   `eventName` mapping in `configuredAnalyticsActions`.
+ *
+ *   The optional `data` payload is a placeholder for per-interaction context (e.g. the
+ *   clicked button's label, the submitted query, the selected option). It is currently
+ *   carried on the event detail but not forwarded to the analytics backend — reserved
+ *   for when `FtCustomTriggerEvent` gains a field for per-event properties.
+ *
+ * Composition: a parent component can re-expose its child's actions by
+ * spreading them into its own action map.
+ */
+export function withAnalytics(Base, analyticsActions) {
+    class FtAnalyticsAware extends Base {
+        constructor() {
+            super(...arguments);
+            this.configuredAnalyticsActions = {};
+        }
+        emitAnalyticsAction(actionType, data) {
+            var _a, _b;
+            const eventName = (_b = (_a = this.configuredAnalyticsActions) === null || _a === void 0 ? void 0 : _a[actionType]) === null || _b === void 0 ? void 0 : _b.eventName;
+            if (!eventName) {
+                return;
+            }
+            const action = analyticsActions[actionType];
+            this.dispatchEvent(new FtAnalyticsActionEvent({
+                eventName,
+                actionType: actionType,
+                componentType: this.tagName.toLowerCase(),
+                componentId: this.id || (action === null || action === void 0 ? void 0 : action.defaultComponentId) || this.tagName.toLowerCase(),
+                data,
+            }));
+        }
+    }
+    FtAnalyticsAware.analyticsActions = analyticsActions;
+    __decorate([
+        jsonProperty({})
+    ], FtAnalyticsAware.prototype, "configuredAnalyticsActions", void 0);
+    return FtAnalyticsAware;
+}