@se-studio/core-ui 1.34.0 → 1.35.0

package/ANALYTICS.md

@@ -81,14 +81,36 @@ Target names (same property names where the site already uses them):
 |-------|------|
 | `page_view` | Full and soft navigations |
 | `click` | Tracked UI clicks (`trackClick`) |
-| `form_view` | Form is shown (needed for conversion rate; not fired on sites yet) |
+| `form_view` | Form component mount (not viewport impression; see below) |
 | `form_start` | First interaction with a form field |
-| `form_submit` | Successful submit |
+| `form_submit` | Successful submit (HubSpot/API accept) |
 | `form_error` | Submit failed (validation or HubSpot/API error shown to the user) |
 | `video_play` | Video starts |
 
 Sites may add extra events. Do not rename or drop an existing site event only to converge. Policy: `docs/PHILOSOPHY.md` R7.5. Form failure handling: `@se-studio/hubspot` `docs/llms.md`.
 
+### Form analytics (non-PII)
+
+`useFormAnalytics` / `createFormAnalyticsSession` emit the four events through `useAnalytics().trackEvent`. Import them from `@se-studio/core-ui/form-analytics` (not the root `@se-studio/core-ui` barrel). `@se-studio/hubspot` `useHubspotSubmit` and `HubspotDynamicForm` emit only when you pass `formAnalytics={true}` (off by default so upgrades are a no-op).
+
+`form_view` fires **on mount**, not when the form enters the viewport. A form below the fold still counts as a view, so view-to-submit will sit close to page-view rates. That is v1; do not treat it as an impression rate. A visibility option can come later.
+
+Allowed parameters only:
+
+| Parameter | Meaning |
+|-----------|---------|
+| `form_id` | HubSpot form GUID or site form id. Identifier token (`SAFE_TOKEN`); digits-only ids pass validation. |
+| `form_name` | Form name (not a person name) |
+| `form_type` | e.g. `hubspot` |
+| `cms_entry_id` | Contentful entry id when the renderer passes it |
+| `step` | Multi-step index or id |
+| `error_code` | Token such as `hubspot_reject`, `too_fast`, `constraint` |
+| `error_category` | `validation` \| `api` \| `too_fast` \| `network` \| `redirect` |
+
+Never send field values, emails, names, phone numbers, or raw error messages. Payloads are allowlisted in `sanitizeFormAnalyticsProperties`. Custom site forms should import `useFormAnalytics` from `@se-studio/core-ui/form-analytics` instead of inventing their own event names.
+
+HubSpot / form packages must import from `@se-studio/core-ui/form-analytics` (slim entry: provider + form events, no Visual/Lottie). Do not re-export that module from the root `@se-studio/core-ui` barrel.
+
 ## Google Tag Manager (GTM)
 
 The `GoogleTagManagerAdapter` supports both GTM Container ID and GA4 Measurement ID.

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/core-ui
 
+## 1.35.0
+
+### Minor Changes
+
+- e746884: Add generic non-PII form analytics (`form_view`, `form_start`, `form_submit`, `form_error`) via `useAnalytics`. HubSpot forms do **not** emit these on upgrade; opt in with `formAnalytics={true}` on `HubspotDynamicForm` / `useHubspotSubmit` / `createHubspotFormExternalRenderer`. Import from `@se-studio/core-ui/form-analytics` only (not the root barrel). Payloads are allowlisted and never include field values or raw error text.
+
 ## 1.34.0
 
 ### Minor Changes

package/dist/analytics/form/createFormAnalyticsSession.d.ts

@@ -0,0 +1,36 @@
+import type { FormAnalyticsErrorInfo, FormAnalyticsTrackFn } from './formAnalyticsTypes';
+import { type FormAnalyticsIdentity } from './formAnalyticsTypes';
+export interface CreateFormAnalyticsSessionOptions {
+    identity: FormAnalyticsIdentity;
+    track: FormAnalyticsTrackFn;
+}
+export interface FormAnalyticsSession {
+    /** Fire `form_view` once for this form instance. */
+    markView: () => void;
+    /** Fire `form_start` once on first interaction. */
+    markStart: () => void;
+    /** Fire `form_submit` on successful accept (each success). */
+    markSubmit: () => void;
+    /**
+     * Fire `form_error`. Validation errors are deduped per attempt (multiple
+     * invalid fields on one submit → one event). API/network errors fire each time.
+     */
+    markError: (info?: FormAnalyticsErrorInfo) => void;
+    /**
+     * Snapshot for unit tests / debugging only.
+     */
+    getState: () => Readonly<FormAnalyticsSessionState>;
+}
+export interface FormAnalyticsSessionState {
+    viewed: boolean;
+    started: boolean;
+    submitCount: number;
+    errorCount: number;
+    validationErrorThisAttempt: boolean;
+}
+/**
+ * Pure form analytics session. Callers (hooks / HubSpot submit) translate DOM
+ * events into these methods. Never pass field values into `track`.
+ */
+export declare function createFormAnalyticsSession(options: CreateFormAnalyticsSessionOptions): FormAnalyticsSession;
+//# sourceMappingURL=createFormAnalyticsSession.d.ts.map

package/dist/analytics/form/createFormAnalyticsSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFormAnalyticsSession.d.ts","sourceRoot":"","sources":["../../../src/analytics/form/createFormAnalyticsSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGzF,MAAM,WAAW,iCAAiC;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,mDAAmD;IACnD,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACnD;;OAEG;IACH,QAAQ,EAAE,MAAM,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B,EAAE,OAAO,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iCAAiC,GACzC,oBAAoB,CAyDtB"}

package/dist/analytics/form/createFormAnalyticsSession.js

@@ -0,0 +1,62 @@
+import { FORM_ANALYTICS_EVENTS } from './formAnalyticsTypes';
+import { sanitizeFormAnalyticsProperties } from './sanitizeFormAnalyticsProperties';
+/**
+ * Pure form analytics session. Callers (hooks / HubSpot submit) translate DOM
+ * events into these methods. Never pass field values into `track`.
+ */
+export function createFormAnalyticsSession(options) {
+    const { identity, track } = options;
+    const state = {
+        viewed: false,
+        started: false,
+        submitCount: 0,
+        errorCount: 0,
+        validationErrorThisAttempt: false,
+    };
+    const emit = (event, extra) => {
+        const properties = sanitizeFormAnalyticsProperties({
+            ...identity,
+            ...extra,
+        });
+        track(event, properties);
+    };
+    return {
+        markView: () => {
+            if (state.viewed) {
+                return;
+            }
+            state.viewed = true;
+            emit(FORM_ANALYTICS_EVENTS.view);
+        },
+        markStart: () => {
+            if (state.started) {
+                state.validationErrorThisAttempt = false;
+                return;
+            }
+            state.started = true;
+            emit(FORM_ANALYTICS_EVENTS.start);
+        },
+        markSubmit: () => {
+            state.validationErrorThisAttempt = false;
+            state.submitCount += 1;
+            emit(FORM_ANALYTICS_EVENTS.submit);
+        },
+        markError: (info) => {
+            const category = info?.error_category;
+            if (category === 'validation') {
+                if (!state.started) {
+                    state.started = true;
+                    emit(FORM_ANALYTICS_EVENTS.start);
+                }
+                if (state.validationErrorThisAttempt) {
+                    return;
+                }
+                state.validationErrorThisAttempt = true;
+            }
+            state.errorCount += 1;
+            emit(FORM_ANALYTICS_EVENTS.error, info);
+        },
+        getState: () => state,
+    };
+}
+//# sourceMappingURL=createFormAnalyticsSession.js.map

package/dist/analytics/form/createFormAnalyticsSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFormAnalyticsSession.js","sourceRoot":"","sources":["../../../src/analytics/form/createFormAnalyticsSession.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAA8B,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AAiCpF;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA0C;IAE1C,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAEpC,MAAM,KAAK,GAA8B;QACvC,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,CAAC;QACb,0BAA0B,EAAE,KAAK;KAClC,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,KAA8B,EAAE,EAAE;QAC7D,MAAM,UAAU,GAAG,+BAA+B,CAAC;YACjD,GAAG,QAAQ;YACX,GAAG,KAAK;SACT,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3B,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE;YACb,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,SAAS,EAAE,GAAG,EAAE;YACd,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClB,KAAK,CAAC,0BAA0B,GAAG,KAAK,CAAC;gBACzC,OAAO;YACT,CAAC;YACD,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,UAAU,EAAE,GAAG,EAAE;YACf,KAAK,CAAC,0BAA0B,GAAG,KAAK,CAAC;YACzC,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;QACD,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAClB,MAAM,QAAQ,GAAG,IAAI,EAAE,cAAc,CAAC;YACtC,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;gBAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;oBACnB,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;oBACrB,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;gBACpC,CAAC;gBACD,IAAI,KAAK,CAAC,0BAA0B,EAAE,CAAC;oBACrC,OAAO;gBACT,CAAC;gBACD,KAAK,CAAC,0BAA0B,GAAG,IAAI,CAAC;YAC1C,CAAC;YACD,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;YACtB,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/analytics/form/formAnalyticsTypes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * First-party form lifecycle events fired via `trackEvent`.
+ * Sites map these names to GTM tags or HubSpot behavioural events.
+ *
+ * Payloads are non-PII: never field values, emails, names, phones, or free text.
+ */
+export declare const FORM_ANALYTICS_EVENTS: {
+    readonly view: 'form_view';
+    readonly start: 'form_start';
+    readonly submit: 'form_submit';
+    readonly error: 'form_error';
+};
+export type FormAnalyticsEventName = (typeof FORM_ANALYTICS_EVENTS)[keyof typeof FORM_ANALYTICS_EVENTS];
+export declare const FORM_ANALYTICS_EVENT_NAMES: readonly FormAnalyticsEventName[];
+/** Allowed payload keys — anything else is dropped before `trackEvent`. */
+export declare const FORM_ANALYTICS_ALLOWED_KEYS: readonly ['form_id', 'form_name', 'form_type', 'cms_entry_id', 'step', 'error_code', 'error_category'];
+export type FormAnalyticsAllowedKey = (typeof FORM_ANALYTICS_ALLOWED_KEYS)[number];
+/**
+ * Closed set of error categories. Do not pass visitor-facing or API error messages —
+ * those can echo field values.
+ */
+export declare const FORM_ERROR_CATEGORIES: {
+    readonly validation: 'validation';
+    readonly api: 'api';
+    readonly too_fast: 'too_fast';
+    readonly network: 'network';
+    readonly redirect: 'redirect';
+};
+export type FormErrorCategory = (typeof FORM_ERROR_CATEGORIES)[keyof typeof FORM_ERROR_CATEGORIES];
+export interface FormAnalyticsIdentity {
+    form_id?: string;
+    form_name?: string;
+    form_type?: string;
+    cms_entry_id?: string;
+    step?: string | number;
+}
+export interface FormAnalyticsErrorInfo {
+    error_code?: string;
+    error_category?: FormErrorCategory | string;
+}
+export type FormAnalyticsProperties = FormAnalyticsIdentity & FormAnalyticsErrorInfo;
+export type FormAnalyticsTrackFn = (event: string, properties: Record<string, unknown>) => void;
+//# sourceMappingURL=formAnalyticsTypes.d.ts.map

package/dist/analytics/form/formAnalyticsTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAnalyticsTypes.d.ts","sourceRoot":"","sources":["../../../src/analytics/form/formAnalyticsTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;aAChC,IAAI,EAAE,WAAW;aACjB,KAAK,EAAE,YAAY;aACnB,MAAM,EAAE,aAAa;aACrB,KAAK,EAAE,YAAY;CACX,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAC;AAErE,eAAO,MAAM,0BAA0B,EAAE,SAAS,sBAAsB,EAKvE,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,2BAA2B,YACtC,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,MAAM,EACN,YAAY,EACZ,gBAAgB,CACR,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnF;;;GAGG;AACH,eAAO,MAAM,qBAAqB;aAChC,UAAU,EAAE,YAAY;aACxB,GAAG,EAAE,KAAK;aACV,QAAQ,EAAE,UAAU;aACpB,OAAO,EAAE,SAAS;aAClB,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAC;AAEnG,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;CAC7C;AAED,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,GAAG,sBAAsB,CAAC;AAErF,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC"}

package/dist/analytics/form/formAnalyticsTypes.js

@@ -0,0 +1,40 @@
+/**
+ * First-party form lifecycle events fired via `trackEvent`.
+ * Sites map these names to GTM tags or HubSpot behavioural events.
+ *
+ * Payloads are non-PII: never field values, emails, names, phones, or free text.
+ */
+export const FORM_ANALYTICS_EVENTS = {
+    view: 'form_view',
+    start: 'form_start',
+    submit: 'form_submit',
+    error: 'form_error',
+};
+export const FORM_ANALYTICS_EVENT_NAMES = [
+    FORM_ANALYTICS_EVENTS.view,
+    FORM_ANALYTICS_EVENTS.start,
+    FORM_ANALYTICS_EVENTS.submit,
+    FORM_ANALYTICS_EVENTS.error,
+];
+/** Allowed payload keys — anything else is dropped before `trackEvent`. */
+export const FORM_ANALYTICS_ALLOWED_KEYS = [
+    'form_id',
+    'form_name',
+    'form_type',
+    'cms_entry_id',
+    'step',
+    'error_code',
+    'error_category',
+];
+/**
+ * Closed set of error categories. Do not pass visitor-facing or API error messages —
+ * those can echo field values.
+ */
+export const FORM_ERROR_CATEGORIES = {
+    validation: 'validation',
+    api: 'api',
+    too_fast: 'too_fast',
+    network: 'network',
+    redirect: 'redirect',
+};
+//# sourceMappingURL=formAnalyticsTypes.js.map

package/dist/analytics/form/formAnalyticsTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAnalyticsTypes.js","sourceRoot":"","sources":["../../../src/analytics/form/formAnalyticsTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;CACX,CAAC;AAKX,MAAM,CAAC,MAAM,0BAA0B,GAAsC;IAC3E,qBAAqB,CAAC,IAAI;IAC1B,qBAAqB,CAAC,KAAK;IAC3B,qBAAqB,CAAC,MAAM;IAC5B,qBAAqB,CAAC,KAAK;CAC5B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,SAAS;IACT,WAAW;IACX,WAAW;IACX,cAAc;IACd,MAAM;IACN,YAAY;IACZ,gBAAgB;CACR,CAAC;AAIX;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,UAAU,EAAE,YAAY;IACxB,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/analytics/form/index.d.ts

@@ -0,0 +1,5 @@
+export { type CreateFormAnalyticsSessionOptions, createFormAnalyticsSession, type FormAnalyticsSession, type FormAnalyticsSessionState, } from './createFormAnalyticsSession';
+export { FORM_ANALYTICS_ALLOWED_KEYS, FORM_ANALYTICS_EVENT_NAMES, FORM_ANALYTICS_EVENTS, FORM_ERROR_CATEGORIES, type FormAnalyticsAllowedKey, type FormAnalyticsErrorInfo, type FormAnalyticsEventName, type FormAnalyticsIdentity, type FormAnalyticsProperties, type FormAnalyticsTrackFn, type FormErrorCategory, } from './formAnalyticsTypes';
+export { sanitizeFormAnalyticsProperties } from './sanitizeFormAnalyticsProperties';
+export { type UseFormAnalyticsOptions, useFormAnalytics } from './useFormAnalytics';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/form/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analytics/form/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iCAAiC,EACtC,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/analytics/form/index.js

@@ -0,0 +1,5 @@
+export { createFormAnalyticsSession, } from './createFormAnalyticsSession';
+export { FORM_ANALYTICS_ALLOWED_KEYS, FORM_ANALYTICS_EVENT_NAMES, FORM_ANALYTICS_EVENTS, FORM_ERROR_CATEGORIES, } from './formAnalyticsTypes';
+export { sanitizeFormAnalyticsProperties } from './sanitizeFormAnalyticsProperties';
+export { useFormAnalytics } from './useFormAnalytics';
+//# sourceMappingURL=index.js.map

package/dist/analytics/form/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analytics/form/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,0BAA0B,GAG3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,GAQtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAgC,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/analytics/form/sanitizeFormAnalyticsProperties.d.ts

@@ -0,0 +1,9 @@
+import { type FormAnalyticsProperties } from './formAnalyticsTypes';
+/**
+ * Whitelist form analytics payloads. Drops unknown keys, nested objects, arrays,
+ * and unconstrained free text. Email/phone heuristics apply to `form_name` only;
+ * `form_id`, `cms_entry_id`, and `error_code` use the identifier token pattern
+ * so HubSpot UUIDs and digits-only ids are not dropped.
+ */
+export declare function sanitizeFormAnalyticsProperties(properties: FormAnalyticsProperties | Record<string, unknown>): Record<string, string | number>;
+//# sourceMappingURL=sanitizeFormAnalyticsProperties.d.ts.map

package/dist/analytics/form/sanitizeFormAnalyticsProperties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeFormAnalyticsProperties.d.ts","sourceRoot":"","sources":["../../../src/analytics/form/sanitizeFormAnalyticsProperties.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AA4C9B;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAqBjC"}

package/dist/analytics/form/sanitizeFormAnalyticsProperties.js

@@ -0,0 +1,62 @@
+import { FORM_ANALYTICS_ALLOWED_KEYS, FORM_ERROR_CATEGORIES, } from './formAnalyticsTypes';
+const ERROR_CATEGORY_SET = new Set(Object.values(FORM_ERROR_CATEGORIES));
+/** Identifier-like tokens: HubSpot GUIDs, Contentful ids, snake_case codes. */
+const SAFE_TOKEN = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,99}$/;
+const MAX_STRING_LENGTH = 100;
+function looksLikeEmail(value) {
+    return value.includes('@');
+}
+function looksLikePhone(value) {
+    const digits = value.replace(/\D/g, '');
+    return digits.length >= 7 && digits.length / value.replace(/\s/g, '').length >= 0.6;
+}
+function sanitizeString(key, raw) {
+    const trimmed = raw.trim().slice(0, MAX_STRING_LENGTH);
+    if (!trimmed) {
+        return undefined;
+    }
+    if (key === 'form_name') {
+        if (looksLikeEmail(trimmed) || looksLikePhone(trimmed)) {
+            return undefined;
+        }
+        return trimmed;
+    }
+    if (key === 'error_category') {
+        return ERROR_CATEGORY_SET.has(trimmed) ? trimmed : undefined;
+    }
+    if (key === 'error_code' ||
+        key === 'form_id' ||
+        key === 'form_type' ||
+        key === 'cms_entry_id' ||
+        key === 'step') {
+        return SAFE_TOKEN.test(trimmed) ? trimmed : undefined;
+    }
+    return undefined;
+}
+/**
+ * Whitelist form analytics payloads. Drops unknown keys, nested objects, arrays,
+ * and unconstrained free text. Email/phone heuristics apply to `form_name` only;
+ * `form_id`, `cms_entry_id`, and `error_code` use the identifier token pattern
+ * so HubSpot UUIDs and digits-only ids are not dropped.
+ */
+export function sanitizeFormAnalyticsProperties(properties) {
+    const out = {};
+    for (const key of FORM_ANALYTICS_ALLOWED_KEYS) {
+        const value = properties[key];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (typeof value === 'number' && Number.isFinite(value) && key === 'step') {
+            out[key] = value;
+            continue;
+        }
+        if (typeof value === 'string') {
+            const sanitized = sanitizeString(key, value);
+            if (sanitized !== undefined) {
+                out[key] = sanitized;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=sanitizeFormAnalyticsProperties.js.map

package/dist/analytics/form/sanitizeFormAnalyticsProperties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeFormAnalyticsProperties.js","sourceRoot":"","sources":["../../../src/analytics/form/sanitizeFormAnalyticsProperties.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,GAGtB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAEjF,+EAA+E;AAC/E,MAAM,UAAU,GAAG,oCAAoC,CAAC;AAExD,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC;AACtF,CAAC;AAED,SAAS,cAAc,CAAC,GAA4B,EAAE,GAAW;IAC/D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QACxB,IAAI,cAAc,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;YACvD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,GAAG,KAAK,gBAAgB,EAAE,CAAC;QAC7B,OAAO,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,CAAC;IACD,IACE,GAAG,KAAK,YAAY;QACpB,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,WAAW;QACnB,GAAG,KAAK,cAAc;QACtB,GAAG,KAAK,MAAM,EACd,CAAC;QACD,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,UAA6D;IAE7D,MAAM,GAAG,GAAoC,EAAE,CAAC;IAEhD,KAAK,MAAM,GAAG,IAAI,2BAA2B,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC1E,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC7C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/analytics/form/useFormAnalytics.d.ts

@@ -0,0 +1,13 @@
+import { type FormAnalyticsSession } from './createFormAnalyticsSession';
+import type { FormAnalyticsIdentity } from './formAnalyticsTypes';
+export interface UseFormAnalyticsOptions {
+    identity: FormAnalyticsIdentity;
+    /** When false, no events are emitted. Default true. */
+    enabled?: boolean;
+}
+/**
+ * Binds a form analytics session to `useAnalytics().trackEvent`.
+ * Fires `form_view` once on mount when enabled (not on viewport impression).
+ */
+export declare function useFormAnalytics({ identity, enabled, }: UseFormAnalyticsOptions): FormAnalyticsSession;
+//# sourceMappingURL=useFormAnalytics.d.ts.map

package/dist/analytics/form/useFormAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFormAnalytics.d.ts","sourceRoot":"","sources":["../../../src/analytics/form/useFormAnalytics.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAA0B,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE1F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,OAAc,GACf,EAAE,uBAAuB,GAAG,oBAAoB,CAsEhD"}

package/dist/analytics/form/useFormAnalytics.js

@@ -0,0 +1,67 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+import { useAnalytics } from '../useAnalytics';
+import { createFormAnalyticsSession, } from './createFormAnalyticsSession';
+/**
+ * Binds a form analytics session to `useAnalytics().trackEvent`.
+ * Fires `form_view` once on mount when enabled (not on viewport impression).
+ */
+export function useFormAnalytics({ identity, enabled = true, }) {
+    const { trackEvent } = useAnalytics();
+    const trackEventRef = useRef(trackEvent);
+    trackEventRef.current = trackEvent;
+    const sessionRef = useRef(null);
+    const formId = identity.form_id ?? '';
+    const formName = identity.form_name ?? '';
+    const formType = identity.form_type ?? '';
+    const cmsEntryId = identity.cms_entry_id ?? '';
+    const step = identity.step ?? '';
+    useEffect(() => {
+        if (!enabled) {
+            sessionRef.current = null;
+            return;
+        }
+        const session = createFormAnalyticsSession({
+            identity: {
+                form_id: formId || undefined,
+                form_name: formName || undefined,
+                form_type: formType || undefined,
+                cms_entry_id: cmsEntryId || undefined,
+                step: step === '' ? undefined : step,
+            },
+            track: (event, properties) => {
+                trackEventRef.current(event, properties);
+            },
+        });
+        sessionRef.current = session;
+        session.markView();
+        return () => {
+            if (sessionRef.current === session) {
+                sessionRef.current = null;
+            }
+        };
+    }, [enabled, formId, formName, formType, cmsEntryId, step]);
+    const markView = useCallback(() => {
+        sessionRef.current?.markView();
+    }, []);
+    const markStart = useCallback(() => {
+        sessionRef.current?.markStart();
+    }, []);
+    const markSubmit = useCallback(() => {
+        sessionRef.current?.markSubmit();
+    }, []);
+    const markError = useCallback((info) => {
+        sessionRef.current?.markError(info);
+    }, []);
+    const getState = useCallback(() => {
+        return (sessionRef.current?.getState() ?? {
+            viewed: false,
+            started: false,
+            submitCount: 0,
+            errorCount: 0,
+            validationErrorThisAttempt: false,
+        });
+    }, []);
+    return { markView, markStart, markSubmit, markError, getState };
+}
+//# sourceMappingURL=useFormAnalytics.js.map

package/dist/analytics/form/useFormAnalytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFormAnalytics.js","sourceRoot":"","sources":["../../../src/analytics/form/useFormAnalytics.ts"],"names":[],"mappings":"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"}

package/dist/analytics/formAnalyticsEntry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Slim client-safe entry for form lifecycle analytics.
+ * Import from `@se-studio/core-ui/form-analytics` in HubSpot/forms so the
+ * main `core-ui` barrel (Visual / Lottie) is not pulled into the form graph.
+ */
+export { AnalyticsProvider, useAnalyticsContext } from './AnalyticsProvider';
+export { type CreateFormAnalyticsSessionOptions, createFormAnalyticsSession, FORM_ANALYTICS_ALLOWED_KEYS, FORM_ANALYTICS_EVENT_NAMES, FORM_ANALYTICS_EVENTS, FORM_ERROR_CATEGORIES, type FormAnalyticsAllowedKey, type FormAnalyticsErrorInfo, type FormAnalyticsEventName, type FormAnalyticsIdentity, type FormAnalyticsProperties, type FormAnalyticsSession, type FormAnalyticsSessionState, type FormAnalyticsTrackFn, type FormErrorCategory, sanitizeFormAnalyticsProperties, type UseFormAnalyticsOptions, useFormAnalytics, } from './form';
+export type { AnalyticsAdapter, ClickTrackingProperties, PageTrackingProperties } from './types';
+export { useAnalytics } from './useAnalytics';
+//# sourceMappingURL=formAnalyticsEntry.d.ts.map

package/dist/analytics/formAnalyticsEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAnalyticsEntry.d.ts","sourceRoot":"","sources":["../../src/analytics/formAnalyticsEntry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,KAAK,iCAAiC,EACtC,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,+BAA+B,EAC/B,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/analytics/formAnalyticsEntry.js

@@ -0,0 +1,9 @@
+/**
+ * Slim client-safe entry for form lifecycle analytics.
+ * Import from `@se-studio/core-ui/form-analytics` in HubSpot/forms so the
+ * main `core-ui` barrel (Visual / Lottie) is not pulled into the form graph.
+ */
+export { AnalyticsProvider, useAnalyticsContext } from './AnalyticsProvider';
+export { createFormAnalyticsSession, FORM_ANALYTICS_ALLOWED_KEYS, FORM_ANALYTICS_EVENT_NAMES, FORM_ANALYTICS_EVENTS, FORM_ERROR_CATEGORIES, sanitizeFormAnalyticsProperties, useFormAnalytics, } from './form';
+export { useAnalytics } from './useAnalytics';
+//# sourceMappingURL=formAnalyticsEntry.js.map

package/dist/analytics/formAnalyticsEntry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAnalyticsEntry.js","sourceRoot":"","sources":["../../src/analytics/formAnalyticsEntry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAEL,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EAUrB,+BAA+B,EAE/B,gBAAgB,GACjB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/docs/PACKAGE_EXPORT_BOUNDARIES.md

@@ -11,6 +11,7 @@ Next.js App Router mixes **Server Components** and **Client Components** (`'use
 | Entry | Who may import | Contents |
 |-------|----------------|----------|
 | `@se-studio/core-ui` | **Everyone** — `'use client'` files, server components, registrations | React UI, hooks, `cn`, CMS renderers, registration helpers, shared types |
+| `@se-studio/core-ui/form-analytics` | **Client-safe** — HubSpot forms and custom forms | `useFormAnalytics`, `FORM_ANALYTICS_EVENTS`, `AnalyticsProvider` (no Visual/Lottie) |
 | `@se-studio/core-ui/server` | **Server only** — `import 'server-only'` at top | `createAppHelpers`, `createRouteHandlers`, `getRelated*`, `filterRelatedArticles`, `articleLinkToListCard`, listing structured-data helpers, etc. |
 | `@se-studio/core-ui/route-handlers` | **App route modules** (Node `fs`) | Discovery/guidelines/cms.txt/OG image handlers |
 

package/docs/llms.md

@@ -185,6 +185,12 @@ Interactive (non-autoplay) Vimeo and YouTube videos fire `trackEvent` with:
 
 Export `VIDEO_ENGAGEMENT_EVENTS` / `VIDEO_ENGAGEMENT_EVENT_NAMES` for GTM or HubSpot `eventNameMap`. Requires `analyticsContext` on the visual chain. Autoplay/background videos are not tracked.
 
+### Form analytics events
+
+`form_view` (once on **mount**, not viewport impression) · `form_start` (first interaction) · `form_submit` (success) · `form_error` (validation or API failure).
+
+Export `FORM_ANALYTICS_EVENTS` / `useFormAnalytics` / `sanitizeFormAnalyticsProperties` from `@se-studio/core-ui/form-analytics` only (not the root barrel). Payload keys: `form_id`, `form_name`, `form_type`, `cms_entry_id`, `step`, `error_code`, `error_category`. Never field values or raw error text. HubSpot forms emit these from `useHubspotSubmit` only when `formAnalytics={true}` (default off).
+
 ### Play button (YouTube / Vimeo)
 
 - Site-wide brand: wrap the app in `ExternalVideoPlayButtonProvider` with a custom icon (see Brightline / SE website / HopSkipDrive).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/core-ui",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Shared React UI component library with Tailwind CSS v4 for SE Studio applications",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
     "./agent-ready": {
       "types": "./dist/utils/agent-ready.d.ts",
       "import": "./dist/utils/agent-ready.js"
+    },
+    "./form-analytics": {
+      "types": "./dist/analytics/formAnalyticsEntry.d.ts",
+      "import": "./dist/analytics/formAnalyticsEntry.js"
     }
   },
   "files": [