From 431a0b45c5110d5f0251a5a1f6dd38d81d17f42f Mon Sep 17 00:00:00 2001
From: Dan Grebb <dan@dgrebb.com>
Date: Sat, 6 Jan 2024 20:57:47 -0500
Subject: [PATCH 1/2] feat: add custom pageview property support

- adds `pageview-props` script src segment
- adds various types and guards for Plausible-enforced property limits
- defends against `svelte-preprocess` [issue with shorthand `{src}` attribute](sveltejs/svelte-preprocess#604) (#12)
- updates README
- updates configuration/npm scripts for prettier@3
---
 .prettierrc                       |  1 -
 README.md                         | 38 ++++++++++--
 package.json                      |  4 +-
 src/lib/PlausibleAnalytics.svelte | 76 +++++++++++++++++++++++-
 src/lib/guards.ts                 | 96 +++++++++++++++++++++++++++++++
 5 files changed, 206 insertions(+), 9 deletions(-)
 create mode 100644 src/lib/guards.ts

diff --git a/.prettierrc b/.prettierrc
index a77fdde..9573023 100644
--- a/.prettierrc
+++ b/.prettierrc
@@ -4,6 +4,5 @@
 	"trailingComma": "none",
 	"printWidth": 100,
 	"plugins": ["prettier-plugin-svelte"],
-	"pluginSearchDirs": ["."],
 	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
 }
diff --git a/README.md b/README.md
index 86a1017..bbd479c 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ npm i --save-dev @accuser/svelte-plausible-analytics
 
 ## Examples
 
-Add Plausible Analytics to the root layout to track page views.
+### Add Plausible Analytics to the root layout to track page views.
 
 ```svelte
 <script>
@@ -25,7 +25,37 @@ Add Plausible Analytics to the root layout to track page views.
 <slot />
 ```
 
-Track analytics events:
+### Add custom properties to page views:
+
+```svelte
+<script>
+  import { page } from "$app/stores";
+  import { PlausibleAnalytics } from '@accuser/svelte-plausible-analytics';
+
+  $: ({ id: route } = $page?.route); // beware duplicate plausible calls
+</script>
+
+  <PlausibleAnalytics
+      enabled={true}
+      pageviewProps={{
+        route,
+        willNotBeIncluded: false,
+        message: `a template literal containing a ${dynamicValue}`,
+        testingFilter: "test-some-scenario",
+        "hyphenated-property": "filter value",
+      }}
+  />
+
+<slot />
+```
+
+Set custom properties in the `pageviewProps` Svelte prop on the `<PlausibleAnalytics />` component. *Beware hydration race conditions and take note when `<PlausibleAnalytics />` is mounted. Especially with SSG.*
+
+The Plausible-required `event-` prefix can be omitted. Eg. `<PlausibleAnalytics pageviewProps={{"my-fancy-prop": "a value"}} />` becomes `<script src="https://plausible.io/js/script.pageview-props.js" event-my-fancy-prop"="a value"></script>`.
+
+*Note*: as per the [Plausible documentation](https://plausible.io/docs/custom-props/introduction#limits), up to 30 custom properties can be included alongside a pageview by adding multiple attributes. There is also a 300/2000 character limit on each property `key` and `value`, respectively.
+
+### Track analytics events:
 
 ```svelte
 <script>
@@ -37,7 +67,7 @@ Track analytics events:
 <button on:click={login('Button')}>Click to login!</button>
 ```
 
-Track custom events:
+### Track custom events:
 
 ```svelte
 <script>
@@ -55,4 +85,4 @@ Matthew Gibbons - [@accuser](https://github.com/accuser)
 
 Jeffrey Palmer - [@JeffreyPalmer](https://github.com/JeffreyPalmer)
 
-Dan Grebb - [@dgrebb](https://github.com/dgrebb)
+Dan Grebb - [@dgrebb](https://github.com/dgrebb)
\ No newline at end of file
diff --git a/package.json b/package.json
index 1fb5ce4..1831a3f 100644
--- a/package.json
+++ b/package.json
@@ -41,8 +41,8 @@
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"test:unit": "vitest",
-		"lint": "prettier --plugin-search-dir . --check . && eslint .",
-		"format": "prettier --plugin-search-dir . --write ."
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write ."
 	},
 	"exports": {
 		".": {
diff --git a/src/lib/PlausibleAnalytics.svelte b/src/lib/PlausibleAnalytics.svelte
index 13870dd..564d9a9 100644
--- a/src/lib/PlausibleAnalytics.svelte
+++ b/src/lib/PlausibleAnalytics.svelte
@@ -7,6 +7,19 @@
 		plausible: PlausibleTracker;
 	}
 
+	/**
+	 * Type definition for properties that can be sent as part of a page view event to Plausible.
+	 * These properties can be of type boolean, number, or string.
+	 */
+	export type PageviewProp = boolean | number | string;
+
+	/**
+	 * Type definition for pageview properties.
+	 * Can be either a boolean or an array containing a record with keys of type number or string,
+	 * and values of type boolean, number, or string.
+	 */
+	export type PageviewProps = { [key: number | string]: PageviewProp } | boolean;
+
 	declare let window: PlausibleWindow;
 
 	const plausible: PlausibleTracker = (event, options) => window.plausible(event, options);
@@ -85,14 +98,67 @@
 	 */
 	export let outboundLinks = false;
 
+	/**
+	 * Holds the pageview properties to be used in the application.
+	 * The properties can be used for filtering in the Plausible dashboard. The pageview properties
+	 * are subject to certain limitations:
+	 * - Limited to 30 total custom properties per event.
+	 * - Limited to 300 characters per property name.
+	 * - Limited to 2000 characters per property value.
+	 *
+	 * @link https://plausible.io/docs/guided-tour#filtering for dashboard filtering by custom property details.
+	 * @defaultValue `false` Indicates no custom properties by default.
+	 */
+	export let pageviewProps: PageviewProps = false;
+
+	/**
+	 * Function references for property validation guards.
+	 * These are dynamically imported during development for validation purposes.
+	 */
+	let isCustomPropsLimit: Function, isCustomPropEntryLimit: Function;
+
+	/**
+	 * Sets the pageview properties as attributes on a given HTML script element.
+	 * This function is responsible for validating and applying the custom properties
+	 * defined in `pageviewProps` to the provided HTML element.
+	 *
+	 * @param {HTMLScriptElement} node - The HTML script element on which to set the attributes.
+	 */
+	const setPageviewProps: (node: HTMLScriptElement) => void = async (node) => {
+		// Early exit if pageviewProps is not defined or falsy.
+		if (!pageviewProps) return;
+
+		// In development mode, load validation guards dynamically and validate custom property limits.
+		if (dev) {
+			const guards = await import('./guards.js');
+			({ isCustomPropsLimit, isCustomPropEntryLimit } = guards);
+
+			// Validate the total number of custom properties against Plausible's limit.
+			isCustomPropsLimit(pageviewProps);
+		}
+
+		// Iterate over each key-value pair in pageviewProps to set them as attributes.
+		Object.entries(pageviewProps).forEach(([key, value]) => {
+			// In development mode, validate the length of property names and values.
+			if (dev) {
+				isCustomPropEntryLimit(300, key);
+				isCustomPropEntryLimit(2000, value);
+			}
+
+			// Set the attribute on the script node. Format: 'event-key'
+			node.setAttribute(`event-${key}`, String(value));
+		});
+	};
+
 	$: api = `${apiHost}/api/event`;
-	$: src = [
+	$: plausibleSrc = [
 		`${apiHost}/js/script`,
 		compat ? 'compat' : undefined,
 		fileDownloads ? 'file-downloads' : undefined,
 		hash ? 'hash' : undefined,
 		local ? 'local' : undefined,
 		outboundLinks ? 'outbound-links' : undefined,
+		pageviewProps ? 'pageview-props' : undefined,
 		'js'
 	]
 		.filter(Boolean)
@@ -101,7 +167,13 @@
 
 <svelte:head>
 	{#if enabled}
-		<script data-api={api} data-domain={domain.toString()} defer {src}></script>
+		<script
+			data-api={api}
+			data-domain={domain.toString()}
+			defer
+			src={plausibleSrc}
+			use:setPageviewProps
+		></script>
 		<script>
 			window.plausible =
 				window.plausible ||
diff --git a/src/lib/guards.ts b/src/lib/guards.ts
new file mode 100644
index 0000000..4490fae
--- /dev/null
+++ b/src/lib/guards.ts
@@ -0,0 +1,96 @@
+import { type PageviewProp, type PageviewProps } from './PlausibleAnalytics.svelte';
+
+/**
+ * Handles various value types and issues warnings if the values are not suitable for passing to Plausible.
+ * Specifically checks for DOMTokenList, HTMLInputElement, Array, RegExp, and Date instances,
+ * and warns about potential errors if these are not parsed as strings.
+ *
+ * @param {unknown} value - The value to be handled and checked.
+ * @returns {boolean} Returns true if the value is acceptable, otherwise throws an error.
+ * @throws {Error} Throws an error if the value is neither a number nor a string.
+ */
+export const handleEntry = function handleEntry(entry: unknown): boolean {
+	const typeName = Object.prototype.toString.call(entry).slice(8, -1);
+
+	const warn = (type: string) =>
+		console.warn(
+			`Warning: Passing ${type} to Plausible may result in error unless parsed as a string.`
+		);
+
+	switch (typeName) {
+		case 'DOMTokenList':
+		case 'HTMLInputElement':
+		case 'Array':
+		case 'RegExp':
+		case 'Date':
+			warn(typeName);
+			return true;
+
+		case 'String':
+		case 'Number':
+			return true;
+
+		default:
+			console.warn(
+				`Plausible Error: Custom property entry ${entry} is not a boolean, number, or string.`
+			);
+			return true;
+	}
+};
+
+/**
+ * Checks if the number of custom properties in a PageviewProps object exceeds a specified limit.
+ *
+ * @param {PageviewProps} props - The PageviewProps object to check.
+ * @returns {boolean} Returns true if the number of properties is within the limit, otherwise logs a warning.
+ */
+export const isCustomPropsLimit = function isCustomPropsLimit(
+	props: PageviewProps
+): props is PageviewProps {
+	const limit = 30;
+
+	if (typeof props === 'object' && Object.entries(props).length > limit) {
+		console.warn(
+			`Warning: Plausible only allows up to 30 custom properties per event. ${props.length} properties counted.`
+		);
+	}
+
+	return true;
+};
+
+/**
+ * Checks if the length of a custom property name or value exceeds a specified limit.
+ *
+ * @param {number} limit - The maximum allowed character length.
+ * @param {PageviewProp} entry - The custom property entry to check.
+ * @returns {boolean} Returns true if the entry's length does not exceed the limit,  otherwise logs a warning.
+ */
+export const isCustomPropEntryLimit = function isCustomPropEntryLimit(
+	limit: number,
+	entry: PageviewProp
+): entry is PageviewProp {
+	const asString = entry.toString();
+	const warning = (length: number) =>
+		`Warning: Plausible limits custom property ${
+			limit > 300 ? 'values' : 'names'
+		} to ${limit} characters. ${entry} is ${length} characters.`;
+
+	// No checks needed for boolean
+	if (typeof entry === 'boolean') return true;
+
+	// Check character length of number with `toString()`
+	if (typeof entry === 'number' && asString.length > limit) {
+		console.warn(warning(asString.length));
+		return true;
+	}
+
+	// Check for and warn if interface passed as prop name or value
+	handleEntry(entry);
+
+	if (asString.length > limit) {
+		console.warn(warning(asString.length));
+		return false;
+	}
+
+	return true;
+};

From 15ffd8660feb0e7b2d7a66722dfa88a5b289eb86 Mon Sep 17 00:00:00 2001
From: Dan Grebb <git@dgrebb.com>
Date: Wed, 28 Aug 2024 20:22:56 -0400
Subject: [PATCH 2/2] style: improve docs; return booleans always; throw
 `Error`s

---
 src/lib/PlausibleAnalytics.svelte | 15 ++++++++++++---
 src/lib/guards.ts                 | 30 +++++++++++++-----------------
 2 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/src/lib/PlausibleAnalytics.svelte b/src/lib/PlausibleAnalytics.svelte
index 564d9a9..b36fc27 100644
--- a/src/lib/PlausibleAnalytics.svelte
+++ b/src/lib/PlausibleAnalytics.svelte
@@ -131,18 +131,27 @@
 		// In development mode, load validation guards dynamically and validate custom property limits.
 		if (dev) {
 			const guards = await import('./guards.js');
+			const length = Object.entries(pageviewProps).length;
 			({ isCustomPropsLimit, isCustomPropEntryLimit } = guards);
 
 			// Validate the total number of custom properties against Plausible's limit.
-			isCustomPropsLimit(pageviewProps);
+			if (!isCustomPropsLimit(pageviewProps)) {
+				throw Error(
+					`Plausible Analytics has a limit of 30 custom properties per event. ${length} properties counted.`
+				);
+			}
 		}
 
 		// Iterate over each key-value pair in pageviewProps to set them as attributes.
 		Object.entries(pageviewProps).forEach(([key, value]) => {
 			// In development mode, validate the length of property names and values.
 			if (dev) {
-				isCustomPropEntryLimit(300, key);
-				isCustomPropEntryLimit(2000, value);
+				if (!isCustomPropEntryLimit(300, key)) {
+					throw Error(`Plausible Analytics limit custom property names to 300 characters.`);
+				}
+				if (!isCustomPropEntryLimit(2000, value)) {
+					throw Error(`Plausible Analytics limit custom property values to 3000 characters.`);
+				};
 			}
 
 			// Set the attribute on the script node. Format: 'event-key'
diff --git a/src/lib/guards.ts b/src/lib/guards.ts
index 4490fae..2860ba9 100644
--- a/src/lib/guards.ts
+++ b/src/lib/guards.ts
@@ -4,6 +4,7 @@ import { type PageviewProp, type PageviewProps } from './PlausibleAnalytics.svel
  * Handles various value types and issues warnings if the values are not suitable for passing to Plausible.
  * Specifically checks for DOMTokenList, HTMLInputElement, Array, RegExp, and Date instances,
  * and warns about potential errors if these are not parsed as strings.
+ * @see {@link https://plausible.io/docs/custom-props/introduction#accepted-values}
  *
  * @param {unknown} value - The value to be handled and checked.
  * @returns {boolean} Returns true if the value is acceptable, otherwise throws an error.
@@ -34,25 +35,25 @@ export const handleEntry = function handleEntry(entry: unknown): boolean {
 			console.warn(
 				`Plausible Error: Custom property entry ${entry} is not a boolean, number, or string.`
 			);
-			return true;
+			return false;
 	}
 };
 
 /**
  * Checks if the number of custom properties in a PageviewProps object exceeds a specified limit.
+ * @see {@link https://plausible.io/docs/custom-props/introduction#limits}
  *
  * @param {PageviewProps} props - The PageviewProps object to check.
- * @returns {boolean} Returns true if the number of properties is within the limit, otherwise logs a warning.
+ * @returns {boolean} Returns true if the number of properties is within the limit, otherwise returns false and logs an error.
  */
 export const isCustomPropsLimit = function isCustomPropsLimit(
 	props: PageviewProps
 ): props is PageviewProps {
 	const limit = 30;
+	const length = Object.entries(props).length;
 
-	if (typeof props === 'object' && Object.entries(props).length > limit) {
-		console.warn(
-			`Warning: Plausible only allows up to 30 custom properties per event. ${props.length} properties counted.`
-		);
+	if (typeof props === 'object' && length > limit) {
+		return false;
 	}
 
 	return true;
@@ -60,7 +61,8 @@ export const isCustomPropsLimit = function isCustomPropsLimit(
 
 /**
  * Checks if the length of a custom property name or value exceeds a specified limit.
- *
+ * @see {@link https://plausible.io/docs/custom-props/introduction#limits}
+ * 
  * @param {number} limit - The maximum allowed character length.
  * @param {PageviewProp} entry - The custom property entry to check.
  * @returns {boolean} Returns true if the entry's length does not exceed the limit,  otherwise logs a warning.
@@ -70,25 +72,19 @@ export const isCustomPropEntryLimit = function isCustomPropEntryLimit(
 	entry: PageviewProp
 ): entry is PageviewProp {
 	const asString = entry.toString();
-	const warning = (length: number) =>
-		`Warning: Plausible limits custom property ${
-			limit > 300 ? 'values' : 'names'
-		} to ${limit} characters. ${entry} is ${length} characters.`;
 
-	// No checks needed for boolean
+	// No limit checks needed for boolean
 	if (typeof entry === 'boolean') return true;
 
 	// Check character length of number with `toString()`
 	if (typeof entry === 'number' && asString.length > limit) {
-		console.warn(warning(asString.length));
-		return true;
+		return false;
 	}
 
-	// Check for and warn if interface passed as prop name or value
-	handleEntry(entry);
+	// Error if DOM node passed as prop name or value
+	if (!handleEntry(entry)) return false;
 
 	if (asString.length > limit) {
-		console.warn(warning(asString.length));
 		return false;
 	}