@artstorefronts/arthelper-nav 0.1.0-alpha.5 → 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
 
@@ -190,23 +202,12 @@ Peer dependencies (from `package.json` — install these yourself, they are not
 }
 ```
 
-> **Getting a change released.** There is no tag and no manual release step: bump the
-> version in `packages/nav/package.json` in the PR that changes the package, and merging
-> to `develop` publishes it. CI publishes only when that version is absent from the
-> registry, and a PR that changes the published surface while leaving the version alone
-> fails its own check — so a change cannot quietly land without reaching you.
->
-> **Testing an unreleased change.** Link the workspace, or use a path dependency:
->
-> ```bash
-> cd packages/nav && yarn link
-> cd ../../../<satellite> && yarn link @artstorefronts/arthelper-nav
-> ```
->
-> `react` and `react-dom` are peer dependencies, so make sure the satellite's bundler
-> resolves a single copy of React — a linked package pulling in its own is the usual
-> cause of the duplicate-React hooks error. `npm pack` plus installing the tarball avoids
-> that failure mode entirely and resolves more like the real thing.
+> **Need a change to the bar itself?** Its look, layout and behaviour ship in this package
+> rather than being configurable — see [Theming and the wordmark](#theming-and-the-wordmark)
+> — so changing them means a new release. Ask the ArtHelper team; releases are automatic and
+> quick. What you _can_ change without one is which apps appear, in what order and pointing
+> where: that lives in the config row, editable from ArtHelper's admin screen and picked up
+> on next load.
 
 ## Minimal mounting example
 
@@ -317,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.css

@@ -77,10 +77,12 @@
    * the wordmark changing typeface as you move between apps, and any family without a
    * real 600 gets faux-bolded on top.
    *
-   * `-webkit-font-smoothing` is pinned for the same reason: a host that sets
-   * `antialiased` on its body thins the bar's text on macOS, so the same 600 weight
-   * looks lighter in that app than the next. `auto` is the default the design was
-   * approved against.
+   * Both smoothing properties are pinned for the same reason: a host that sets
+   * `antialiased` on its body thins the bar's text on macOS, so the same 600 weight looks
+   * lighter in that app than the next. town-square does exactly that — `<body
+   * className="antialiased">` — and Tailwind's utility sets BOTH `-webkit-font-smoothing`
+   * and `-moz-osx-font-smoothing`, so countering only the webkit half leaves Firefox still
+   * inheriting `grayscale`. `auto` is the default the design was approved against.
    *
    * Set on every root the package renders — the bar, the docked trigger (which lives in
    * the host's own header) and the fixed mobile panel — because only the first of those
@@ -95,6 +97,7 @@
     Arial,
     sans-serif;
   -webkit-font-smoothing: auto;
+  -moz-osx-font-smoothing: auto;
   color: var(--ahsuite-label);
   isolation: isolate;
   visibility: visible;
@@ -388,6 +391,7 @@ span.ahsuite-row {
     Arial,
     sans-serif;
   -webkit-font-smoothing: auto;
+  -moz-osx-font-smoothing: auto;
   flex: 0 0 auto;
 }
 
@@ -466,6 +470,7 @@ span.ahsuite-row {
     Arial,
     sans-serif;
   -webkit-font-smoothing: auto;
+  -moz-osx-font-smoothing: auto;
 }
 
 .ahsuite-panel-head {

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.5",
+  "version": "0.1.0-alpha.7",
   "description": "The ArtHelper suite navigation bar — a config-driven, cross-origin app switcher.",
   "license": "ISC",
   "type": "module",