@artstorefronts/arthelper-nav 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -67,8 +67,20 @@ is obviously this app, stop and ask — an id is added by an operator, not by yo
    Without this, a user who collapsed the bar gets an expanded bar in the first byte and a
    56px jump after hydration.
 
-6. **Optionally pass `onAppClick`** to emit your own analytics. The package imports no
-   analytics library, and one callback covers both the desktop tiles and the mobile dropdown.
+6. **Pass `onAppClick`** so this app's clicks reach the fleet-wide chart. The package ships
+   no analytics SDK — transport, identity and consent stay with you — but it does export the
+   event's shape, so use it rather than hand-writing the payload:
+
+   ```ts
+   import { suiteNavClickEvent } from '@artstorefronts/arthelper-nav';
+
+   onAppClick={(args) => yourTracker.track(...suiteNavClickEvent(args, '<this-app-id>'))}
+   ```
+
+   Hand-writing it is how a satellite ends up sending `app_id` instead of `target_app_id`,
+   which does not fail — it silently splits the chart. One callback covers both the desktop
+   tiles and the mobile dropdown. If your tracker batches, flush on the way out: a tile is a
+   real cross-app `<a href>`, so the document is replaced and a queued batch dies with it.
 
 ## `configUrl` — the mistake to avoid
 
@@ -306,23 +318,37 @@ This is the same derivation both in-monorepo hosts (`client/`, `town-square/`) u
 
 ## `onAppClick`: the analytics seam
 
-The package imports no analytics library of any kind. `onAppClick` is the one hook
-through which a host wires its own analytics — it fires immediately before navigation,
-from **both** the desktop tile row and the mobile dropdown, so one callback covers both
-surfaces:
+`onAppClick` fires immediately before navigation, from one shared handler behind both the
+desktop tile row and the mobile dropdown — so it covers both surfaces and cannot
+double-fire.
+
+**The package ships no analytics SDK, deliberately.** Bundling one would run a second
+instance alongside yours, racing it on device id and session, and would emit without your
+identity or consent handling — producing clicks that cannot be joined to users. Transport,
+identity and consent are yours.
+
+What the package does own is the event's shape, because that is the part that drifts:
 
 ```ts
+import { suiteNavClickEvent } from '@artstorefronts/arthelper-nav';
+
 <NavProvider
-  activeAppId="my-app"
   configUrl={NAV_CONFIG_URL}
-  onAppClick={({ app, activeAppId, collapsed }) => {
-    myAnalytics.track('suite_nav_app_clicked', { targetAppId: app.id, activeAppId, collapsed });
-  }}
+  activeAppId="art-books"
+  onAppClick={(args) => amplitude.track(...suiteNavClickEvent(args, 'art_books'))}
 >
 ```
 
-Navigation itself happens via a real `<a href>` the browser follows natively —
-`onAppClick` never intercepts or prevents it.
+It returns a `[name, properties]` pair, so the two cannot be paired wrongly. Properties are
+`target_app_id` (the app clicked — the dimension click-throughs group on), `source_app`
+(this app, passed in because hosts sharing a product surface share an `activeAppId` and so
+cannot be told apart by it), and `collapsed`.
+
+`SUITE_NAV_CLICK_EVENT` is exported too if your tracker needs the name separately.
+
+**If your tracker batches, flush on the way out.** A tile is a real cross-app `<a href>`, so
+the document is replaced and a queued batch dies with it — both ArtHelper hosts use their
+tracker's on-exit variant for exactly this reason.
 
 ## SSR and the collapsed cookie
 

package/dist/analytics.d.ts

@@ -0,0 +1,42 @@
+import type { NavAppClickArgs } from './types.js';
+/**
+ * The one spelling of the suite bar's click event.
+ *
+ * The package deliberately ships no analytics SDK. Bundling one would run a second
+ * instance alongside the host's — racing it on device id and session — and would emit
+ * without the host's identity or consent handling, producing clicks that cannot be joined
+ * to users. Transport, identity and consent stay with the host; only the event's shape
+ * lives here.
+ *
+ * What that leaves is a drift risk, and it is the whole reason this helper exists: a
+ * satellite that hand-writes `app_id` instead of `target_app_id`, or renames the event,
+ * silently splits the fleet-wide chart rather than failing. Name and properties travel
+ * together as one value so the two cannot be paired wrongly.
+ */
+declare const SUITE_NAV_CLICK_EVENT = "suite_nav_app_clicked";
+type SuiteNavClickProperties<TSource extends string> = {
+    /** Catalog id of the app that was clicked — the dimension click-throughs group on. */
+    target_app_id: string;
+    /**
+     * Which host emitted the click. Passed in rather than read off `activeAppId`, because
+     * hosts that are one product surface share an id — ArtHelper's client and town-square
+     * both declare `home`, so `activeAppId` cannot tell them apart.
+     */
+    source_app: TSource;
+    /** Whether the bar was collapsed at click time. */
+    collapsed: boolean;
+};
+/**
+ * Builds the event as a `[name, properties]` pair, ready to spread into a tracker:
+ *
+ * ```ts
+ * onAppClick={(args) => amplitude.track(...suiteNavClickEvent(args, 'art_books'))}
+ * ```
+ *
+ * `TSource` is generic so the literal survives: a host whose tracker types `source_app` as
+ * a union of known apps still typechecks, which a widened `string` would not.
+ */
+declare function suiteNavClickEvent<TSource extends string>(args: NavAppClickArgs, sourceApp: TSource): [typeof SUITE_NAV_CLICK_EVENT, SuiteNavClickProperties<TSource>];
+export { SUITE_NAV_CLICK_EVENT, suiteNavClickEvent };
+export type { SuiteNavClickProperties };
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,qBAAqB,0BAA0B,CAAC;AAKtD,KAAK,uBAAuB,CAAC,OAAO,SAAS,MAAM,IAAI;IACrD,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;GASG;AACH,iBAAS,kBAAkB,CAAC,OAAO,SAAS,MAAM,EAChD,IAAI,EAAE,eAAe,EACrB,SAAS,EAAE,OAAO,GACjB,CAAC,OAAO,qBAAqB,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAElE;AAED,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,CAAC"}

package/dist/analytics.js

@@ -0,0 +1,30 @@
+/**
+ * The one spelling of the suite bar's click event.
+ *
+ * The package deliberately ships no analytics SDK. Bundling one would run a second
+ * instance alongside the host's — racing it on device id and session — and would emit
+ * without the host's identity or consent handling, producing clicks that cannot be joined
+ * to users. Transport, identity and consent stay with the host; only the event's shape
+ * lives here.
+ *
+ * What that leaves is a drift risk, and it is the whole reason this helper exists: a
+ * satellite that hand-writes `app_id` instead of `target_app_id`, or renames the event,
+ * silently splits the fleet-wide chart rather than failing. Name and properties travel
+ * together as one value so the two cannot be paired wrongly.
+ */
+const SUITE_NAV_CLICK_EVENT = 'suite_nav_app_clicked';
+/**
+ * Builds the event as a `[name, properties]` pair, ready to spread into a tracker:
+ *
+ * ```ts
+ * onAppClick={(args) => amplitude.track(...suiteNavClickEvent(args, 'art_books'))}
+ * ```
+ *
+ * `TSource` is generic so the literal survives: a host whose tracker types `source_app` as
+ * a union of known apps still typechecks, which a widened `string` would not.
+ */
+function suiteNavClickEvent(args, sourceApp) {
+    return [SUITE_NAV_CLICK_EVENT, { target_app_id: args.app.id, source_app: sourceApp, collapsed: args.collapsed }];
+}
+export { SUITE_NAV_CLICK_EVENT, suiteNavClickEvent };
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAkBtD;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CACzB,IAAqB,EACrB,SAAkB;IAElB,OAAO,CAAC,qBAAqB,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;AACnH,CAAC;AAED,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { SUITE_NAV_CLICK_EVENT, suiteNavClickEvent } from './analytics.js';
 export { useNav } from './context.js';
 export { COLLAPSED_COOKIE } from './cookie.js';
 export { FALLBACK_CONFIG } from './fallback.js';
@@ -5,6 +6,7 @@ export { NavBar } from './nav-bar.js';
 export { NavTrigger } from './nav-trigger.js';
 export { NavProvider } from './provider.js';
 export { resolveApps } from './resolve.js';
+export type { SuiteNavClickProperties } from './analytics.js';
 export type { NavContextValue } from './context.js';
 export type { NavBarProps } from './nav-bar.js';
 export type { NavTriggerProps } from './nav-trigger.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { SUITE_NAV_CLICK_EVENT, suiteNavClickEvent } from './analytics.js';
 export { useNav } from './context.js';
 export { COLLAPSED_COOKIE } from './cookie.js';
 export { FALLBACK_CONFIG } from './fallback.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artstorefronts/arthelper-nav",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "The ArtHelper suite navigation bar — a config-driven, cross-origin app switcher.",
   "license": "ISC",
   "type": "module",