@tetherto/dev-websites-core 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # `@tetherto/dev-websites-core`
 
-Shared CMS, SEO, i18n, utils, and UI primitives for WDK / QVAC websites.
+Shared CMS, SEO, i18n, utils, UI, and analytics primitives for WDK / QVAC / PEAR / MDK websites.
 
 | Import | Contents |
 | --- | --- |
@@ -8,6 +8,7 @@ Shared CMS, SEO, i18n, utils, and UI primitives for WDK / QVAC websites.
 | `@tetherto/dev-websites-core/seo` | `createMetadataFactory`, `getSiteUrl`, `getOgBackgroundDataUrl` |
 | `@tetherto/dev-websites-core/i18n` | `Languages` / `LanguageLabel` |
 | `@tetherto/dev-websites-core/utils` | `createLogger`, `toPlainValue`, `stripShikiPreBackground` |
+| `@tetherto/dev-websites-core/analytics` | `GtmLoader`, `createTrackedLink` (optional `@next/third-parties` peer) |
 | `@tetherto/dev-websites-core/ui` | UI primitives (`Button`, `Dialog`, `Pagination`, `Tooltip`, …) + `cn` |
 | `@tetherto/dev-websites-core/ui/a11y` | `focusRingClassName`, `VisuallyHidden` |
 | `@tetherto/dev-websites-core/ui/carousel` | `Carousel` (+ optional `embla-carousel-react` peer) |
@@ -50,6 +51,24 @@ rm -rf node_modules/@tetherto/dev-websites-core && npm install @tetherto/dev-web
 Do **not** import `@tetherto/dev-websites-core/cms` from Client Components — it includes Node-only
 modules (`fs`, Payload, S3). Prefer domain subpaths over the root barrel.
 
+### Analytics
+
+```ts
+import { GtmLoader, createTrackedLink } from '@tetherto/dev-websites-core/analytics'
+import { Link } from '@/i18n/navigation'
+import { analytics } from '@/lib/analytics'
+
+// Delay GTM until window.load (optional `@next/third-parties` peer)
+<GtmLoader gtmId={gtmId} />
+
+// App owns Link + event catalog; core owns click wiring
+export const TrackedLink = createTrackedLink(Link, {
+  docsClicked: analytics.docsClicked,
+  getStartedClicked: analytics.getStartedClicked,
+  externalLinkClicked: analytics.externalLinkClicked,
+})
+```
+
 ### UI theming
 
 One **Tailwind theme contract** for all sites (same utility names). Defaults are

package/dist/analytics/GtmLoader.d.mts

@@ -0,0 +1,14 @@
+//#region src/analytics/GtmLoader.d.ts
+type GtmLoaderProps = {
+  gtmId: string;
+};
+/**
+ * Wraps `@next/third-parties` `GoogleTagManager` and delays mounting it until
+ * the page has fully loaded (`window.load`). The Next.js helper itself uses
+ * `next/script` with `afterInteractive`, which would otherwise inject GTM
+ * during hydration and contribute to TBT.
+ */
+declare function GtmLoader({ gtmId }: GtmLoaderProps): import("react").JSX.Element | null;
+//#endregion
+export { GtmLoader, GtmLoaderProps };
+//# sourceMappingURL=GtmLoader.d.mts.map

package/dist/analytics/GtmLoader.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GtmLoader.d.mts","names":[],"sources":["../../src/analytics/GtmLoader.tsx"],"mappings":";KAKY;EACV;;;;;;;;iBASc,YAAY,SAAS,iCAAc,IAAA"}

package/dist/analytics/GtmLoader.mjs

@@ -0,0 +1,30 @@
+"use client";
+import { GoogleTagManager } from "@next/third-parties/google";
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/analytics/GtmLoader.tsx
+/**
+* Wraps `@next/third-parties` `GoogleTagManager` and delays mounting it until
+* the page has fully loaded (`window.load`). The Next.js helper itself uses
+* `next/script` with `afterInteractive`, which would otherwise inject GTM
+* during hydration and contribute to TBT.
+*/
+function GtmLoader({ gtmId }) {
+	const [ready, setReady] = useState(false);
+	useEffect(() => {
+		if (!gtmId) return;
+		const onLoad = () => setReady(true);
+		if (document.readyState === "complete") {
+			const id = window.setTimeout(onLoad, 0);
+			return () => window.clearTimeout(id);
+		}
+		window.addEventListener("load", onLoad, { once: true });
+		return () => window.removeEventListener("load", onLoad);
+	}, [gtmId]);
+	if (!ready) return null;
+	return /* @__PURE__ */ jsx(GoogleTagManager, { gtmId });
+}
+//#endregion
+export { GtmLoader };
+
+//# sourceMappingURL=GtmLoader.mjs.map

package/dist/analytics/GtmLoader.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"GtmLoader.mjs","names":[],"sources":["../../src/analytics/GtmLoader.tsx"],"sourcesContent":["'use client'\n\nimport { GoogleTagManager } from '@next/third-parties/google'\nimport { useEffect, useState } from 'react'\n\nexport type GtmLoaderProps = {\n  gtmId: string\n}\n\n/**\n * Wraps `@next/third-parties` `GoogleTagManager` and delays mounting it until\n * the page has fully loaded (`window.load`). The Next.js helper itself uses\n * `next/script` with `afterInteractive`, which would otherwise inject GTM\n * during hydration and contribute to TBT.\n */\nexport function GtmLoader({ gtmId }: GtmLoaderProps) {\n  const [ready, setReady] = useState(false)\n\n  useEffect(() => {\n    if (!gtmId) return\n\n    const onLoad = () => setReady(true)\n\n    if (document.readyState === 'complete') {\n      // Defer one tick so this doesn't fire a synchronous setState during the\n      // effect (and to give the browser a frame to settle after `load`).\n      const id = window.setTimeout(onLoad, 0)\n      return () => window.clearTimeout(id)\n    }\n\n    window.addEventListener('load', onLoad, { once: true })\n    return () => window.removeEventListener('load', onLoad)\n  }, [gtmId])\n\n  if (!ready) return null\n  return <GoogleTagManager gtmId={gtmId} />\n}\n"],"mappings":";;;;;;;;;;;AAeA,SAAgB,UAAU,EAAE,SAAyB;CACnD,MAAM,CAAC,OAAO,YAAY,SAAS,KAAK;CAExC,gBAAgB;EACd,IAAI,CAAC,OAAO;EAEZ,MAAM,eAAe,SAAS,IAAI;EAElC,IAAI,SAAS,eAAe,YAAY;GAGtC,MAAM,KAAK,OAAO,WAAW,QAAQ,CAAC;GACtC,aAAa,OAAO,aAAa,EAAE;EACrC;EAEA,OAAO,iBAAiB,QAAQ,QAAQ,EAAE,MAAM,KAAK,CAAC;EACtD,aAAa,OAAO,oBAAoB,QAAQ,MAAM;CACxD,GAAG,CAAC,KAAK,CAAC;CAEV,IAAI,CAAC,OAAO,OAAO;CACnB,OAAO,oBAAC,kBAAD,EAAyB,MAAQ,CAAA;AAC1C"}

package/dist/analytics/createTrackedLink.d.mts

@@ -0,0 +1,46 @@
+import { ComponentPropsWithoutRef, ElementType, ReactElement } from "react";
+//#region src/analytics/createTrackedLink.d.ts
+/**
+ * Discriminated tracking props. Apps keep tight `Section` / destination unions;
+ * pass them as generics to `createTrackedLink`.
+ */
+type CreateTrackedEvent<TSection extends string, TDestination extends string> = {
+  event?: never;
+  section?: never;
+  destination?: never;
+} | {
+  event: 'docs_clicked';
+  section: TSection;
+  destination?: string;
+} | {
+  event: 'get_started_clicked';
+  section: TSection;
+  destination?: never;
+} | {
+  event: 'external_link_clicked';
+  section: TSection;
+  destination: TDestination;
+};
+type TrackedCapture<TSection extends string, TDestination extends string> = {
+  docsClicked: (p: {
+    section: TSection;
+    destination?: string;
+  }) => void;
+  getStartedClicked: (p: {
+    section: TSection;
+  }) => void;
+  externalLinkClicked: (p: {
+    destination: TDestination;
+    section: TSection;
+  }) => void;
+};
+/**
+ * Builds a site `TrackedLink` that wraps the app's Link (`next-intl` navigation
+ * Link or `next/link`) and fires the provided capture callbacks.
+ *
+ * Routing and event catalogs stay in the app — core only owns the click wiring.
+ */
+declare function createTrackedLink<TLink extends ElementType, TSection extends string = string, TDestination extends string = string>(Link: TLink, capture: TrackedCapture<TSection, TDestination>): (props: ComponentPropsWithoutRef<TLink> & CreateTrackedEvent<TSection, TDestination>) => ReactElement;
+//#endregion
+export { CreateTrackedEvent, type CreateTrackedEvent as TrackedEvent, TrackedCapture, createTrackedLink };
+//# sourceMappingURL=createTrackedLink.d.mts.map

package/dist/analytics/createTrackedLink.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTrackedLink.d.mts","names":[],"sources":["../../src/analytics/createTrackedLink.tsx"],"mappings":";;;;;;KAcY,mBAAmB,yBAAyB;EAClD;EAAe;EAAiB;;EAChC;EAAuB,SAAS;EAAU;;EAC1C;EAA8B,SAAS;EAAU;;EAEjD;EACA,SAAS;EACT,aAAa;;KAGP,eAAe,yBAAyB;EAClD,cAAc;IAAK,SAAS;IAAU;;EACtC,oBAAoB;IAAK,SAAS;;EAClC,sBAAsB;IAAK,aAAa;IAAc,SAAS;;;;;;;;;iBASjD,kBACd,cAAc,aACd,kCACA,sCACA,MAAM,OAAO,SAAS,eAAe,UAAU,iBAsCxB,OAAK,yBAAA,SAAA,mBAAA,UAAA,kBAAuB"}

package/dist/analytics/createTrackedLink.mjs

@@ -0,0 +1,36 @@
+"use client";
+import { createElement } from "react";
+//#region src/analytics/createTrackedLink.tsx
+/**
+* Builds a site `TrackedLink` that wraps the app's Link (`next-intl` navigation
+* Link or `next/link`) and fires the provided capture callbacks.
+*
+* Routing and event catalogs stay in the app — core only owns the click wiring.
+*/
+function createTrackedLink(Link, capture) {
+	function TrackedLink(props) {
+		const { event, section, destination, onClick, href, ...rest } = props;
+		const handleClick = (e) => {
+			if (event === "docs_clicked" && section) capture.docsClicked({
+				section,
+				destination: destination ?? String(href)
+			});
+			else if (event === "get_started_clicked" && section) capture.getStartedClicked({ section });
+			else if (event === "external_link_clicked" && section && destination) capture.externalLinkClicked({
+				section,
+				destination
+			});
+			onClick?.(e);
+		};
+		return createElement(Link, {
+			...rest,
+			href,
+			onClick: handleClick
+		});
+	}
+	return TrackedLink;
+}
+//#endregion
+export { createTrackedLink };
+
+//# sourceMappingURL=createTrackedLink.mjs.map

package/dist/analytics/createTrackedLink.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTrackedLink.mjs","names":[],"sources":["../../src/analytics/createTrackedLink.tsx"],"sourcesContent":["'use client'\n\nimport {\n  createElement,\n  type ComponentPropsWithoutRef,\n  type ElementType,\n  type MouseEvent,\n  type ReactElement,\n} from 'react'\n\n/**\n * Discriminated tracking props. Apps keep tight `Section` / destination unions;\n * pass them as generics to `createTrackedLink`.\n */\nexport type CreateTrackedEvent<TSection extends string, TDestination extends string> =\n  | { event?: never; section?: never; destination?: never }\n  | { event: 'docs_clicked'; section: TSection; destination?: string }\n  | { event: 'get_started_clicked'; section: TSection; destination?: never }\n  | {\n      event: 'external_link_clicked'\n      section: TSection\n      destination: TDestination\n    }\n\nexport type TrackedCapture<TSection extends string, TDestination extends string> = {\n  docsClicked: (p: { section: TSection; destination?: string }) => void\n  getStartedClicked: (p: { section: TSection }) => void\n  externalLinkClicked: (p: { destination: TDestination; section: TSection }) => void\n}\n\n/**\n * Builds a site `TrackedLink` that wraps the app's Link (`next-intl` navigation\n * Link or `next/link`) and fires the provided capture callbacks.\n *\n * Routing and event catalogs stay in the app — core only owns the click wiring.\n */\nexport function createTrackedLink<\n  TLink extends ElementType,\n  TSection extends string = string,\n  TDestination extends string = string,\n>(Link: TLink, capture: TrackedCapture<TSection, TDestination>) {\n  type LinkProps = ComponentPropsWithoutRef<TLink>\n  type TrackedEvent = CreateTrackedEvent<TSection, TDestination>\n  type TrackedLinkProps = LinkProps & TrackedEvent\n\n  function TrackedLink(props: TrackedLinkProps): ReactElement {\n    const { event, section, destination, onClick, href, ...rest } = props as TrackedLinkProps & {\n      event?: TrackedEvent['event']\n      section?: TSection\n      destination?: string\n      onClick?: (e: MouseEvent<HTMLAnchorElement>) => void\n      href?: unknown\n    }\n\n    const handleClick = (e: MouseEvent<HTMLAnchorElement>) => {\n      if (event === 'docs_clicked' && section) {\n        capture.docsClicked({\n          section,\n          destination: (destination as string | undefined) ?? String(href),\n        })\n      } else if (event === 'get_started_clicked' && section) {\n        capture.getStartedClicked({ section })\n      } else if (event === 'external_link_clicked' && section && destination) {\n        capture.externalLinkClicked({\n          section,\n          destination: destination as TDestination,\n        })\n      }\n      onClick?.(e)\n    }\n\n    return createElement(Link, {\n      ...(rest as LinkProps),\n      href,\n      onClick: handleClick,\n    } as LinkProps)\n  }\n\n  return TrackedLink as (props: TrackedLinkProps) => ReactElement\n}\n\nexport type { CreateTrackedEvent as TrackedEvent }\n"],"mappings":";;;;;;;;;AAoCA,SAAgB,kBAId,MAAa,SAAiD;CAK9D,SAAS,YAAY,OAAuC;EAC1D,MAAM,EAAE,OAAO,SAAS,aAAa,SAAS,MAAM,GAAG,SAAS;EAQhE,MAAM,eAAe,MAAqC;GACxD,IAAI,UAAU,kBAAkB,SAC9B,QAAQ,YAAY;IAClB;IACA,aAAc,eAAsC,OAAO,IAAI;GACjE,CAAC;QACI,IAAI,UAAU,yBAAyB,SAC5C,QAAQ,kBAAkB,EAAE,QAAQ,CAAC;QAChC,IAAI,UAAU,2BAA2B,WAAW,aACzD,QAAQ,oBAAoB;IAC1B;IACa;GACf,CAAC;GAEH,UAAU,CAAC;EACb;EAEA,OAAO,cAAc,MAAM;GACzB,GAAI;GACJ;GACA,SAAS;EACX,CAAc;CAChB;CAEA,OAAO;AACT"}

package/dist/analytics/index.d.mts

@@ -0,0 +1,3 @@
+import { GtmLoader, GtmLoaderProps } from "./GtmLoader.mjs";
+import { CreateTrackedEvent, TrackedCapture, createTrackedLink } from "./createTrackedLink.mjs";
+export { type CreateTrackedEvent, GtmLoader, type GtmLoaderProps, type TrackedCapture, type CreateTrackedEvent as TrackedEvent, createTrackedLink };

package/dist/analytics/index.mjs

@@ -0,0 +1,3 @@
+import { GtmLoader } from "./GtmLoader.mjs";
+import { createTrackedLink } from "./createTrackedLink.mjs";
+export { GtmLoader, createTrackedLink };

package/dist/ui/components/Badge/Badge.d.mts

@@ -2,7 +2,7 @@ import { HTMLAttributes } from "react";
 import { VariantProps } from "class-variance-authority";
 //#region src/ui/components/Badge/Badge.d.ts
 declare const badgeVariants: (props?: ({
-  variant?: "status" | "active" | "inactive" | null | undefined;
+  variant?: "active" | "inactive" | "status" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 type BadgeProps = HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants> & {
   asChild?: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tetherto/dev-websites-core",
-  "version": "0.3.0",
-  "description": "Shared CMS, SEO, i18n, utils, and UI primitives for the WDK / QVAC websites.",
+  "version": "0.3.1",
+  "description": "Shared CMS, SEO, i18n, utils, UI, and analytics primitives for the WDK / QVAC / PEAR / MDK websites.",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
@@ -43,6 +43,11 @@
       "import": "./dist/utils/index.mjs",
       "default": "./dist/utils/index.mjs"
     },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.mts",
+      "import": "./dist/analytics/index.mjs",
+      "default": "./dist/analytics/index.mjs"
+    },
     "./ui": {
       "types": "./dist/ui/index.d.mts",
       "import": "./dist/ui/index.mjs",
@@ -83,6 +88,7 @@
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.0.0",
+    "@next/third-parties": ">=15",
     "@payloadcms/richtext-lexical": "^3.85.1",
     "@payloadcms/storage-s3": "^3.85.1",
     "@radix-ui/react-dialog": "^1.1.0",
@@ -101,6 +107,9 @@
     "tailwind-merge": "^3.0.0"
   },
   "peerDependenciesMeta": {
+    "@next/third-parties": {
+      "optional": true
+    },
     "embla-carousel-react": {
       "optional": true
     },
@@ -111,6 +120,7 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.787.0",
     "@eslint/js": "^9.39.0",
+    "@next/third-parties": "^16.3.2",
     "@payloadcms/richtext-lexical": "3.88.0",
     "@payloadcms/storage-s3": "3.88.0",
     "@radix-ui/react-dialog": "^1.1.15",