@buildinams/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { S as SetStateAction, A as AnyObject } from './state-BnfG-Qk9.js';
 export { a as AnyFunction, B as BivariantCallback, E as EmptyObject, L as LooseObject, b as SetState } from './state-BnfG-Qk9.js';
-import clsx from 'clsx';
+import { ClassValue } from 'clsx';
 import { ImageProps } from 'next/image';
 
 declare const IS_DEVELOPMENT: boolean;
@@ -147,7 +147,7 @@ declare const transform: (value: number, originRange: [number, number], targetRa
  */
 declare const round: (value: number, decimalPlaces?: number) => number;
 
-declare const mergeClassNames: (...classNames: clsx.ClassValue[]) => string;
+declare const mergeClassNames: (...classNames: ClassValue[]) => string;
 
 /**
  * Detects if the device has touch capabilities.

package/dist/index.js

@@ -1,3 +1,66 @@
-export { IS_BUILD, IS_DEVELOPMENT, IS_IN_BROWSER, applyState, clamp, defaultValue, hasOwnProperty, identity, invariant, isApple, isHTMLElement, isInArray, isMac, isObject, isTouchDevice, isTruthy, mergeClassNames, notEmpty, removeUndefinedValues, round, shallowEqual, transform, wrap } from './chunk-SIU7SKJK.js';
+export { shallowEqual } from './chunk-LL3VTFNY.js';
+export { applyState, defaultValue, hasOwnProperty, invariant, isHTMLElement, isInArray, isObject, isTruthy, notEmpty } from './chunk-OS2T6P2T.js';
+import { IS_IN_BROWSER } from './chunk-GQVN2ECX.js';
+export { IS_BUILD, IS_DEVELOPMENT, IS_IN_BROWSER } from './chunk-GQVN2ECX.js';
+import clsx from 'clsx';
+
+// src/functions/identity.ts
+function identity(value) {
+  return value;
+}
+
+// src/functions/math.ts
+var wrap = (value, [min, max]) => {
+  const range = max - min + 1;
+  return ((value - min) % range + range) % range + min;
+};
+var clamp = (value, [min, max]) => {
+  return Math.min(Math.max(value, min), max);
+};
+var transform = (value, originRange, targetRange) => {
+  const [oMin, oMax] = originRange;
+  const [tMin, tMax] = targetRange;
+  const ratio = (value - oMin) / (oMax - oMin);
+  const transformedValue = tMin + ratio * (tMax - tMin);
+  return transformedValue;
+};
+var round = (value, decimalPlaces = 0) => {
+  const factor = Math.pow(10, decimalPlaces);
+  return Math.round((value + Number.EPSILON) * factor) / factor;
+};
+var mergeClassNames = (...classNames) => {
+  try {
+    return clsx(...classNames);
+  } catch (error) {
+    throw new Error(
+      "mergeClassNames: Invalid input provided. Ensure all class names are strings, undefined, or null."
+    );
+  }
+};
+
+// src/functions/platform.ts
+var isTouchDevice = () => {
+  return IS_IN_BROWSER && !!navigator.maxTouchPoints;
+};
+var isApple = () => {
+  if (!IS_IN_BROWSER) return false;
+  return /mac|iphone|ipad|ipod/i.test(navigator.platform);
+};
+var isMac = () => {
+  return IS_IN_BROWSER && navigator.platform.startsWith("Mac") && !isTouchDevice();
+};
+
+// src/functions/remove-undefined-values.ts
+function removeUndefinedValues(obj) {
+  const result = {};
+  for (const key in obj) {
+    if (obj[key] !== void 0) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+export { clamp, identity, isApple, isMac, isTouchDevice, mergeClassNames, removeUndefinedValues, round, transform, wrap };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"version":3,"sources":["../src/functions/identity.ts","../src/functions/math.ts","../src/functions/merge-class-names.ts","../src/functions/platform.ts","../src/functions/remove-undefined-values.ts"],"names":[],"mappings":";;;;;;;AAGO,SAAS,SAAY,KAAA,EAAU;AACrC,EAAA,OAAO,KAAA;AACR;;;ACQO,IAAM,OAAO,CAAC,KAAA,EAAe,CAAC,GAAA,EAAK,GAAG,CAAA,KAAkC;AAC9E,EAAA,MAAM,KAAA,GAAQ,MAAM,GAAA,GAAM,CAAA;AAC1B,EAAA,OAAA,CAAA,CAAW,KAAA,GAAQ,GAAA,IAAO,KAAA,GAAS,KAAA,IAAS,KAAA,GAAS,GAAA;AACtD;AAgBO,IAAM,QAAQ,CACpB,KAAA,EACA,CAAC,GAAA,EAAK,GAAG,CAAA,KACL;AACJ,EAAA,OAAO,KAAK,GAAA,CAAI,IAAA,CAAK,IAAI,KAAA,EAAO,GAAG,GAAG,GAAG,CAAA;AAC1C;AAcO,IAAM,SAAA,GAAY,CACxB,KAAA,EACA,WAAA,EACA,WAAA,KACI;AACJ,EAAA,MAAM,CAAC,IAAA,EAAM,IAAI,CAAA,GAAI,WAAA;AACrB,EAAA,MAAM,CAAC,IAAA,EAAM,IAAI,CAAA,GAAI,WAAA;AAErB,EAAA,MAAM,KAAA,GAAA,CAAS,KAAA,GAAQ,IAAA,KAAS,IAAA,GAAO,IAAA,CAAA;AACvC,EAAA,MAAM,gBAAA,GAAmB,IAAA,GAAO,KAAA,IAAS,IAAA,GAAO,IAAA,CAAA;AAEhD,EAAA,OAAO,gBAAA;AACR;AAQO,IAAM,KAAA,GAAQ,CAAC,KAAA,EAAe,aAAA,GAAwB,CAAA,KAAM;AAClE,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,EAAA,EAAI,aAAa,CAAA;AACzC,EAAA,OAAO,KAAK,KAAA,CAAA,CAAO,KAAA,GAAQ,MAAA,CAAO,OAAA,IAAW,MAAM,CAAA,GAAI,MAAA;AACxD;ACxEA,IAAM,eAAA,GAAkB,IAAI,UAAA,KAA6B;AACxD,EAAA,IAAI;AACH,IAAA,OAAO,IAAA,CAAK,GAAG,UAAU,CAAA;AAAA,EAC1B,SAAS,KAAA,EAAO;AACf,IAAA,MAAM,IAAI,KAAA;AAAA,MACT;AAAA,KACD;AAAA,EACD;AACD;;;ACLO,IAAM,gBAAgB,MAAM;AAClC,EAAA,OAAO,aAAA,IAAiB,CAAC,CAAC,SAAA,CAAU,cAAA;AACrC;AAKO,IAAM,UAAU,MAAM;AAC5B,EAAA,IAAI,CAAC,eAAe,OAAO,KAAA;AAC3B,EAAA,OAAO,uBAAA,CAAwB,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAA;AACvD;AAKO,IAAM,QAAQ,MAAM;AAC1B,EAAA,OACC,iBAAiB,SAAA,CAAU,QAAA,CAAS,WAAW,KAAK,CAAA,IAAK,CAAC,aAAA,EAAc;AAE1E;;;ACnBO,SAAS,sBAA2C,GAAA,EAAQ;AAClE,EAAA,MAAM,SAAS,EAAC;AAChB,EAAA,KAAA,MAAW,OAAO,GAAA,EAAK;AACtB,IAAA,IAAI,GAAA,CAAI,GAAG,CAAA,KAAM,MAAA,EAAW;AAC3B,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,GAAA,CAAI,GAAG,CAAA;AAAA,IACtB;AAAA,EACD;AACA,EAAA,OAAO,MAAA;AACR","file":"index.js","sourcesContent":["/**\n * Returns the same argument.\n */\nexport function identity<T>(value: T) {\n\treturn value;\n}\n","/**\n * Wraps a number within a specified range.\n * @param value - The number to wrap.\n * @param min - The minimum value of the range (inclusive).\n * @param max - The maximum value of the range (inclusive).\n * @returns The wrapped number within the range [min, max].\n *\n * @example\n * wrap(5, [0, 3]); // Returns 1\n * wrap(-1, [0, 3]); // Returns 2\n * wrap(-3, [0, 3]); // Returns 1\n * wrap(7, [0, 3]); // Returns 3\n */\nexport const wrap = (value: number, [min, max]: [min: number, max: number]) => {\n\tconst range = max - min + 1;\n\treturn ((((value - min) % range) + range) % range) + min;\n};\n\n/**\n * Limits a value between a specified range.\n * @param value - The number to limit.\n * @param min - The minimum value of the range (inclusive).\n * @param max - The maximum value of the range (inclusive).\n * @returns The wrapped number within the range [min, max].\n *\n * @example\n * clamp(2, [0, 3]); // Returns 2\n * clamp(5, [0, 3]); // Returns 3\n * clamp(-1, [0, 3]); // Returns 0\n * clamp(-3, [0, 3]); // Returns 0\n * clamp(7, [0, 3]); // Returns 3\n */\nexport const clamp = (\n\tvalue: number,\n\t[min, max]: [min: number, max: number],\n) => {\n\treturn Math.min(Math.max(value, min), max);\n};\n\n/**\n * Maps a number from one range to another.\n * @param value The number to map.\n * @param originRange The original range of the number.\n * @param targetRange The target range to map the number to.\n * @returns The mapped number within the target range.\n *\n * @example\n * transform(5, [0, 10], [0, 100]); // Returns 50\n * transform(0.5, [0, 1], [0, 10]); // Returns 5\n * transform(-5, [-10, 0], [0, 100]); // Returns 50\n */\nexport const transform = (\n\tvalue: number,\n\toriginRange: [number, number],\n\ttargetRange: [number, number],\n) => {\n\tconst [oMin, oMax] = originRange;\n\tconst [tMin, tMax] = targetRange;\n\n\tconst ratio = (value - oMin) / (oMax - oMin);\n\tconst transformedValue = tMin + ratio * (tMax - tMin);\n\n\treturn transformedValue;\n};\n\n/**\n * Rounds a number to a specified number of decimal places.\n * @param value - The number to round.\n * @param decimalPlaces - The number of decimal places to round to. (default is 0)\n * @returns The rounded number.\n */\nexport const round = (value: number, decimalPlaces: number = 0) => {\n\tconst factor = Math.pow(10, decimalPlaces);\n\treturn Math.round((value + Number.EPSILON) * factor) / factor;\n};\n","import clsx, { type ClassValue } from \"clsx\";\n\nconst mergeClassNames = (...classNames: ClassValue[]) => {\n\ttry {\n\t\treturn clsx(...classNames);\n\t} catch (error) {\n\t\tthrow new Error(\n\t\t\t\"mergeClassNames: Invalid input provided. Ensure all class names are strings, undefined, or null.\",\n\t\t);\n\t}\n};\n\n// Name isn't very memorable, so we export it in this file to alias it\nexport { mergeClassNames };\n","import { IS_IN_BROWSER } from \"src/config\";\n\n/**\n * Detects if the device has touch capabilities.\n */\nexport const isTouchDevice = () => {\n\treturn IS_IN_BROWSER && !!navigator.maxTouchPoints;\n};\n\n/**\n * Detects Apple device.\n */\nexport const isApple = () => {\n\tif (!IS_IN_BROWSER) return false;\n\treturn /mac|iphone|ipad|ipod/i.test(navigator.platform);\n};\n\n/**\n * Detects Mac computer.\n */\nexport const isMac = () => {\n\treturn (\n\t\tIS_IN_BROWSER && navigator.platform.startsWith(\"Mac\") && !isTouchDevice()\n\t);\n};\n","import type { AnyObject } from \"../types\";\n\n/**\n * Removes undefined values from an object.\n */\nexport function removeUndefinedValues<T extends AnyObject>(obj: T) {\n\tconst result = {} as T;\n\tfor (const key in obj) {\n\t\tif (obj[key] !== undefined) {\n\t\t\tresult[key] = obj[key];\n\t\t}\n\t}\n\treturn result;\n}\n"]}

package/dist/listeners-DkU-vBPa.d.ts

@@ -0,0 +1,15 @@
+type Named = {
+    name: string;
+};
+/**
+ * Subscribes `listener` to every event, or only to those named. A listener that throws is logged, so it doesn't break
+ * the others. Returns a function that unsubscribes. Does nothing on the server.
+ */
+type Subscribe<Event extends Named> = {
+    (listener: (event: Event) => void): () => void;
+    <Name extends Event["name"]>(names: Name | readonly Name[], listener: (event: Extract<Event, {
+        name: Name;
+    }>) => void): () => void;
+};
+
+export type { Subscribe as S };

package/dist/navigation/index.d.ts

@@ -1,4 +1,4 @@
-import { S as Schema } from '../schema-iy92gbTC.js';
+import { S as Schema } from '../schema-CfQvhbuU.js';
 
 /** @deprecated use `Schema` directly */
 type HrefSchema<State = never> = {

package/dist/navigation/index.js

@@ -1,4 +1,4 @@
-import { createStringSchema } from '../chunk-IAAQVL6M.js';
+import { createStringSchema } from '../chunk-FJ7SNQQI.js';
 
 // src/navigation/href-schema.ts
 var hrefToUrl = (href) => new URL(href, "http://localhost");

package/dist/schema/index.d.ts

@@ -1,10 +1,10 @@
-import { S as Schema } from '../schema-iy92gbTC.js';
-export { b as SchemaSerialized, a as SchemaState, c as createSchema } from '../schema-iy92gbTC.js';
+import { S as Schema } from '../schema-CfQvhbuU.js';
+export { c as SchemaSerializableState, b as SchemaSerialized, a as SchemaState, d as createSchema } from '../schema-CfQvhbuU.js';
 
-type StringSchema<State = never> = {
-    parse: Schema<State, string>["parse"];
-    stringify: Schema<State, string>["serialize"];
-    parseStringify: Schema<State, string>["parserialize"];
+type StringSchema<State = never, SerializableState = State> = {
+    parse: Schema<State, string, SerializableState>["parse"];
+    stringify: Schema<State, string, SerializableState>["serialize"];
+    parseStringify: Schema<State, string, SerializableState>["parserialize"];
 };
 /**
  * Helper function to create a `StringSchema` which converts between strings and state objects.
@@ -13,7 +13,7 @@ type StringSchema<State = never> = {
  * - `parse`: A function that takes a string and returns the corresponding state object.
  * - `stringify`: A function that takes a state object and returns a string that represents the given state.
  */
-declare const createStringSchema: <S = never>(template: Omit<StringSchema<S>, "parseStringify">) => StringSchema<S>;
+declare const createStringSchema: <State = never, SerializableState = State>(template: Omit<StringSchema<State, SerializableState>, "parseStringify">) => StringSchema<State, SerializableState>;
 
 /**
  * Utility schema for parsing and stringifying href strings into structured state objects that include the pathname and URL search parameters.
@@ -30,7 +30,7 @@ declare const createStringSchema: <S = never>(template: Omit<StringSchema<S>, "p
  *   parse: (href) => {
  *    const { searchParams } = hrefSchema.parse(href);
  *    return {
- *     page: parseInt(searchParams.get("page"), 10) || 1,
+ *     page: parseInt(searchParams.get("page") || "1", 10),
  *     _href: href,
  *    }
  *   },
@@ -40,14 +40,21 @@ declare const createStringSchema: <S = never>(template: Omit<StringSchema<S>, "p
  *    if (state.page > 1) {
  *     searchParams.set("page", state.page.toString());
  *    }
- *    return hrefSchema.serialize({ pathname, searchParams });
+ *
+ *    // note that `searchParams` are optional for serialization
+ *    return hrefSchema.stringify({ pathname, searchParams });
  *   }
  * });
  * ```
  */
 declare const hrefSchema: StringSchema<{
     pathname: string;
+    hash: string;
     searchParams: URLSearchParams;
+}, {
+    pathname: string;
+    hash?: string;
+    searchParams?: URLSearchParams;
 }>;
 
 export { Schema, type StringSchema, createStringSchema, hrefSchema };

package/dist/schema/index.js

@@ -1,3 +1,3 @@
-export { createSchema, createStringSchema, hrefSchema } from '../chunk-IAAQVL6M.js';
+export { createSchema, createStringSchema, hrefSchema } from '../chunk-FJ7SNQQI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/schema-CfQvhbuU.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Defines the schema for parsing and stringifying states to and from primitive values.
+ *
+ * The `Schema` type is a generic type that takes:
+ * - `State`: A state object type.
+ * - `Serialized`: The raw value type
+ * - `SerializableState?`: (optional) A (partial) state object type that can be used for serialization. Defaults to `State` if not provided.
+ *
+ * It returns the following methods:
+ * - `parse`: A function that takes a raw value and returns the corresponding state object.
+ * - `serialize`: A function that takes a (serializable) state object and returns a raw value that represents the given state.
+ * - `parserialize`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.
+ *
+ * @see createSchema for a helper function to create a `Schema` from simpler parsing and serializing functions.
+ */
+type Schema<State = any, Serialized = any, SerializableState = State> = {
+    /** Parse a raw value into the state shape */
+    parse: (value: Serialized) => State;
+    /** Serialize a state shape into a raw value */
+    serialize: (state: SerializableState) => Serialized;
+    /** Compute a new serialized value based on a given serialized value and a reducer of the current state. */
+    parserialize: (value: Serialized, next: (state: State) => SerializableState) => Serialized;
+};
+/**
+ * A utility type to extract the state shape from a given `Schema`.
+ */
+type SchemaState<T extends Schema> = T extends Schema<infer U> ? U : never;
+/**
+ * A utility type to extract the serialized value type from a given `Schema`.
+ */
+type SchemaSerialized<T extends Schema> = T extends Schema<any, infer U> ? U : never;
+/**
+ * A utility type to extract the serializable state shape from a given `Schema`.
+ */
+type SchemaSerializableState<T extends Schema> = T extends Schema<any, any, infer U> ? U : never;
+/**
+ * Low-level helper function to create a basic `Schema` that receives the config for converting between serialized values and state objects.
+ *
+ * The template requires two methods:
+ * - `parse`: A method that takes a serialized value and returns the corresponding state object.
+ * - `serialize`: A method that takes a state object and returns a serialized value that represents the given state.
+ *
+ * The `parserialize` method is automatically implemented based on the provided `parse` and `serialize` methods, allowing you to compute a new serialized value based on an existing serialized value and a reducer function for the state.
+ *
+ * @example
+ * ```ts
+ * import { createSchema } from "@buildinams/core/schema";
+ *
+ * const numberSchema = createSchema<
+ *   number, // State
+ *   string // Serialized
+ * >({
+ *   parse: (value) => parseInt(value, 10),
+ *   serialize: (state) => state.toString(),
+ * });
+ *
+ * const result = numberSchema.parserialize("42", (state) => state + 1);
+ * console.log(result); // "43"
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createSchema } from "@buildinams/core/schema";
+ *
+ * const hrefSchema: createSchema<
+ *   { pathname: string, searchParams: URLSearchParams },
+ *   string,
+ *   { pathname: string, searchParams?: URLSearchParams } // SerializableState allows to define different state used for serialization, in this case making searchParams optional to allow for more flexible stringification logic
+ * >({
+ *  parse: (href) => {
+ *    const [pathname = "", search = ""] = href.split("?");
+ *    return {
+ *     pathname,
+ *     searchParams: new URLSearchParams(search),
+ *    };
+ *  },
+ *  serialize: (serializableState) => {
+ *    if (!serializableState.searchParams) return serializableState.pathname;
+ *    const paramsString = serializableState.searchParams.toString();
+ *    return serializableState.pathname + (paramsString ? `?${paramsString}` : "");
+ *  },
+ * })
+ * ```
+ */
+declare const createSchema: <State = never, Serialized = never, SerializableState = State>(template: Omit<Schema<State, Serialized, SerializableState>, "parserialize">) => Schema<State, Serialized, SerializableState>;
+
+export { type Schema as S, type SchemaState as a, type SchemaSerialized as b, type SchemaSerializableState as c, createSchema as d };

package/dist/store/index.js

@@ -1,4 +1,4 @@
-import { hasOwnProperty, defaultValue, applyState, invariant } from '../chunk-SIU7SKJK.js';
+import { hasOwnProperty, defaultValue, applyState, invariant } from '../chunk-OS2T6P2T.js';
 
 // src/store/dom.ts
 function getDocument(node) {

package/dist/tracking/cart/index.d.ts

@@ -0,0 +1,74 @@
+import { q as CartOccurrences, d as EventCatalog } from '../../define-events-CxZjoUlG.js';
+import { S as Subscribe } from '../../listeners-DkU-vBPa.js';
+
+/** A line in a `CartSnapshot`. */
+type CartLine<Item> = {
+    /** Stable for the line's lifetime, e.g. Shopify's cart line id. Lines are matched by it. */
+    id: string;
+    quantity: number;
+    /** Unit price, after discounts. */
+    price: number;
+    /** The project's data for the line, e.g. its product and variant. */
+    item: Item;
+};
+/** The cart as the server confirmed it. */
+type CartSnapshot<Item> = {
+    id: string;
+    /** ISO 4217, e.g. `"EUR"`. */
+    currency: string;
+    lines: CartLine<Item>[];
+};
+/** What `createCartChanges()` reports, as its listeners receive it. */
+type CartEvent<Item> = {
+    [K in keyof CartOccurrences<Item>]: {
+        name: K;
+        payload: CartOccurrences<Item>[K];
+    };
+}[keyof CartOccurrences<Item>];
+type CartChanges<Item> = {
+    /**
+     * Reports what changed since the last confirmed cart: `addedToCart` for new lines and higher quantities,
+     * `removedFromCart` for removed lines and lower quantities. Pass `null` while there's no cart, so the first lines
+     * of a new one count as added. Pass only carts the server confirmed, not optimistic ones. The last cart passed
+     * before the first `subscribe()` is held until then, e.g. from a child component's effect, which runs before its
+     * parent's. Does nothing on the server.
+     */
+    setCart: (cart: CartSnapshot<Item> | null) => void;
+    /**
+     * Hands what `setCart()` reports to `listener`: every event, or only those named. Pass it to `createAnalytics()`'s
+     * `sources` instead to track them.
+     */
+    subscribe: Subscribe<CartEvent<Item>>;
+    /** Catalog entries for what it reports, to spread into `defineEvents()`. */
+    events: EventCatalog<CartOccurrences<Item>>;
+};
+type CartChangesOptions = {
+    /**
+     * Where the last confirmed cart is kept, so other tabs and later page loads don't track it again. Change it when the
+     * item's shape changes, so items stored before don't reach the mappings. Default `"analytics-cart"`.
+     */
+    storageKey?: string;
+};
+/**
+ * Reports `addedToCart` and `removedFromCart` to its listeners by comparing confirmed carts, so add and remove
+ * buttons, quantity pickers and cart drawers don't each have to. `Item` is the project's cart line item. One per page;
+ * pass it every cart the server confirms.
+ *
+ * The first cart on a page load counts as the starting point, unless the last confirmed cart is stored from an
+ * earlier page, e.g. after a form that adds to the cart and redirects. A cart another tab already tracked isn't
+ * tracked again. See `docs/analytics.md`.
+ *
+ * @example
+ * ```ts
+ * export const cartChanges = createCartChanges<CartItem>();
+ *
+ * export const events = defineEvents({ ...cartChanges.events });
+ * export const analytics = createAnalytics<EventsOf<typeof events>>({ events, sources: [cartChanges], consent });
+ *
+ * // Wherever a confirmed cart arrives, e.g. a server action's response, as `CartSnapshot<CartItem>`:
+ * cartChanges.setCart(toCartSnapshot(cart));
+ * ```
+ */
+declare const createCartChanges: <Item>({ storageKey, }?: CartChangesOptions) => CartChanges<Item>;
+
+export { type CartChanges, type CartChangesOptions, type CartLine, type CartSnapshot, createCartChanges };

package/dist/tracking/cart/index.js

@@ -0,0 +1,118 @@
+import { createListeners } from '../../chunk-M3HNM5HC.js';
+import { shape } from '../../chunk-G2BKC4BU.js';
+
+// src/tracking/cart/cart-changes.ts
+var EMPTY = { id: null, lines: [] };
+var toKey = ({ id, lines }) => JSON.stringify([id, lines.map((line) => [line.id, line.quantity]).sort()]);
+var isLine = (line) => {
+  if (typeof line !== "object" || line === null) return false;
+  const { id, quantity, price } = line;
+  return typeof id === "string" && typeof quantity === "number" && typeof price === "number" && "item" in line;
+};
+var read = (key) => {
+  try {
+    const value = localStorage.getItem(key);
+    const stored = value ? JSON.parse(value) : void 0;
+    if (!stored || !(typeof stored.id === "string" || stored.id === null) || !Array.isArray(stored.lines) || !stored.lines.every(isLine)) {
+      return void 0;
+    }
+    return stored;
+  } catch {
+    return void 0;
+  }
+};
+var write = (key, value) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+};
+var toPayload = (currency, changes) => {
+  const items = changes.map(([{ item, price }, quantity]) => ({
+    item,
+    quantity,
+    price
+  }));
+  return {
+    currency,
+    value: items.reduce(
+      (total, { price, quantity }) => total + price * quantity,
+      0
+    ),
+    items
+  };
+};
+var createCartChanges = ({
+  storageKey = "analytics-cart"
+} = {}) => {
+  let previous;
+  let held;
+  let isReplaying = false;
+  const listeners = createListeners({
+    start: () => {
+      if (!held) return;
+      isReplaying = true;
+      queueMicrotask(() => {
+        isReplaying = false;
+        if (!held || !listeners.hasListeners()) return;
+        const { cart } = held;
+        held = void 0;
+        track(cart);
+      });
+    }
+  });
+  const { emit } = listeners;
+  const track = (cart) => {
+    const current = cart ? { id: cart.id, lines: cart.lines } : EMPTY;
+    const stored = read(storageKey);
+    const isTracked = stored && toKey(stored) === toKey(current);
+    const from = previous ?? stored;
+    previous = current;
+    write(storageKey, current);
+    if (!cart || isTracked || !from) return;
+    const before = from.id === cart.id ? from.lines : [];
+    const quantities = new Map(before.map((line) => [line.id, line.quantity]));
+    const added = [];
+    const removed = [];
+    for (const line of cart.lines) {
+      const delta = line.quantity - (quantities.get(line.id) ?? 0);
+      if (delta > 0) added.push([line, delta]);
+      if (delta < 0) removed.push([line, -delta]);
+    }
+    const remaining = new Set(cart.lines.map((line) => line.id));
+    for (const line of before) {
+      if (!remaining.has(line.id)) removed.push([line, line.quantity]);
+    }
+    if (removed.length > 0) {
+      emit({
+        name: "removedFromCart",
+        payload: toPayload(cart.currency, removed)
+      });
+    }
+    if (added.length > 0) {
+      emit({ name: "addedToCart", payload: toPayload(cart.currency, added) });
+    }
+  };
+  return {
+    setCart: (cart) => {
+      if (typeof window === "undefined") return;
+      if (listeners.hasListeners() && !isReplaying) track(cart);
+      else held = { cart };
+    },
+    subscribe: listeners.subscribe,
+    events: {
+      addedToCart: {
+        description: "Lines were added to the cart, or their quantity increased.",
+        payload: shape()
+      },
+      removedFromCart: {
+        description: "Lines were removed from the cart, or their quantity decreased.",
+        payload: shape()
+      }
+    }
+  };
+};
+
+export { createCartChanges };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/tracking/cart/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/tracking/cart/cart-changes.ts"],"names":[],"mappings":";;;;AA4DA,IAAM,QAAgB,EAAE,EAAA,EAAI,IAAA,EAAM,KAAA,EAAO,EAAC,EAAE;AAG5C,IAAM,KAAA,GAAQ,CAAC,EAAE,EAAA,EAAI,OAAM,KAC1B,IAAA,CAAK,SAAA,CAAU,CAAC,EAAA,EAAI,KAAA,CAAM,IAAI,CAAC,IAAA,KAAS,CAAC,IAAA,CAAK,EAAA,EAAI,IAAA,CAAK,QAAQ,CAAC,CAAA,CAAE,IAAA,EAAM,CAAC,CAAA;AAE1E,IAAM,MAAA,GAAS,CAAC,IAAA,KAA6C;AAC5D,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,KAAS,MAAM,OAAO,KAAA;AACtD,EAAA,MAAM,EAAE,EAAA,EAAI,QAAA,EAAU,KAAA,EAAM,GAAI,IAAA;AAChC,EAAA,OACC,OAAO,OAAO,QAAA,IACd,OAAO,aAAa,QAAA,IACpB,OAAO,KAAA,KAAU,QAAA,IACjB,MAAA,IAAU,IAAA;AAEZ,CAAA;AAGA,IAAM,IAAA,GAAO,CAAC,GAAA,KAAoC;AACjD,EAAA,IAAI;AACH,IAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AACtC,IAAA,MAAM,MAAA,GAAS,KAAA,GAAS,IAAA,CAAK,KAAA,CAAM,KAAK,CAAA,GAAwB,KAAA,CAAA;AAChE,IAAA,IACC,CAAC,UACD,EAAE,OAAO,OAAO,EAAA,KAAO,QAAA,IAAY,OAAO,EAAA,KAAO,IAAA,CAAA,IACjD,CAAC,KAAA,CAAM,OAAA,CAAQ,OAAO,KAAK,CAAA,IAC3B,CAAC,MAAA,CAAO,KAAA,CAAM,KAAA,CAAM,MAAM,CAAA,EACzB;AACD,MAAA,OAAO,KAAA,CAAA;AAAA,IACR;AACA,IAAA,OAAO,MAAA;AAAA,EACR,CAAA,CAAA,MAAQ;AACP,IAAA,OAAO,MAAA;AAAA,EACR;AACD,CAAA;AAEA,IAAM,KAAA,GAAQ,CAAC,GAAA,EAAa,KAAA,KAAkB;AAC7C,EAAA,IAAI;AACH,IAAA,YAAA,CAAa,OAAA,CAAQ,GAAA,EAAK,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AAAA,EAChD,CAAA,CAAA,MAAQ;AAAA,EAER;AACD,CAAA;AAEA,IAAM,SAAA,GAAY,CACjB,QAAA,EACA,OAAA,KAC0C;AAC1C,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAC,EAAE,IAAA,EAAM,KAAA,EAAM,EAAG,QAAQ,CAAA,MAAO;AAAA,IAC3D,IAAA;AAAA,IACA,QAAA;AAAA,IACA;AAAA,GACD,CAAE,CAAA;AACF,EAAA,OAAO;AAAA,IACN,QAAA;AAAA,IACA,OAAO,KAAA,CAAM,MAAA;AAAA,MACZ,CAAC,KAAA,EAAO,EAAE,OAAO,QAAA,EAAS,KAAM,QAAQ,KAAA,GAAQ,QAAA;AAAA,MAChD;AAAA,KACD;AAAA,IACA;AAAA,GACD;AACD,CAAA;AAsBO,IAAM,oBAAoB,CAAO;AAAA,EACvC,UAAA,GAAa;AACd,CAAA,GAAwB,EAAC,KAAyB;AACjD,EAAA,IAAI,QAAA;AACJ,EAAA,IAAI,IAAA;AACJ,EAAA,IAAI,WAAA,GAAc,KAAA;AAElB,EAAA,MAAM,YAAY,eAAA,CAAiC;AAAA,IAClD,OAAO,MAAM;AACZ,MAAA,IAAI,CAAC,IAAA,EAAM;AACX,MAAA,WAAA,GAAc,IAAA;AAEd,MAAA,cAAA,CAAe,MAAM;AACpB,QAAA,WAAA,GAAc,KAAA;AACd,QAAA,IAAI,CAAC,IAAA,IAAQ,CAAC,SAAA,CAAU,cAAa,EAAG;AACxC,QAAA,MAAM,EAAE,MAAK,GAAI,IAAA;AACjB,QAAA,IAAA,GAAO,MAAA;AACP,QAAA,KAAA,CAAM,IAAI,CAAA;AAAA,MACX,CAAC,CAAA;AAAA,IACF;AAAA,GACA,CAAA;AACD,EAAA,MAAM,EAAE,MAAK,GAAI,SAAA;AAEjB,EAAA,MAAM,KAAA,GAAQ,CAAC,IAAA,KAAoC;AAClD,IAAA,MAAM,OAAA,GAAkB,OAAO,EAAE,EAAA,EAAI,KAAK,EAAA,EAAI,KAAA,EAAO,IAAA,CAAK,KAAA,EAAM,GAAI,KAAA;AACpE,IAAA,MAAM,MAAA,GAAS,KAAK,UAAU,CAAA;AAE9B,IAAA,MAAM,YAAY,MAAA,IAAU,KAAA,CAAM,MAAM,CAAA,KAAM,MAAM,OAAO,CAAA;AAC3D,IAAA,MAAM,OAAO,QAAA,IAAY,MAAA;AACzB,IAAA,QAAA,GAAW,OAAA;AACX,IAAA,KAAA,CAAM,YAAY,OAAO,CAAA;AACzB,IAAA,IAAI,CAAC,IAAA,IAAQ,SAAA,IAAa,CAAC,IAAA,EAAM;AAGjC,IAAA,MAAM,SAAU,IAAA,CAAK,EAAA,KAAO,KAAK,EAAA,GAAK,IAAA,CAAK,QAAQ,EAAC;AACpD,IAAA,MAAM,UAAA,GAAa,IAAI,GAAA,CAAI,MAAA,CAAO,GAAA,CAAI,CAAC,IAAA,KAAS,CAAC,IAAA,CAAK,EAAA,EAAI,IAAA,CAAK,QAAQ,CAAC,CAAC,CAAA;AACzE,IAAA,MAAM,QAAoC,EAAC;AAC3C,IAAA,MAAM,UAAsC,EAAC;AAC7C,IAAA,KAAA,MAAW,IAAA,IAAQ,KAAK,KAAA,EAAO;AAC9B,MAAA,MAAM,QAAQ,IAAA,CAAK,QAAA,IAAY,WAAW,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,IAAK,CAAA,CAAA;AAC1D,MAAA,IAAI,QAAQ,CAAA,EAAG,KAAA,CAAM,KAAK,CAAC,IAAA,EAAM,KAAK,CAAC,CAAA;AACvC,MAAA,IAAI,KAAA,GAAQ,GAAG,OAAA,CAAQ,IAAA,CAAK,CAAC,IAAA,EAAM,CAAC,KAAK,CAAC,CAAA;AAAA,IAC3C;AACA,IAAA,MAAM,SAAA,GAAY,IAAI,GAAA,CAAI,IAAA,CAAK,KAAA,CAAM,IAAI,CAAC,IAAA,KAAS,IAAA,CAAK,EAAE,CAAC,CAAA;AAC3D,IAAA,KAAA,MAAW,QAAQ,MAAA,EAAQ;AAC1B,MAAA,IAAI,CAAC,SAAA,CAAU,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,EAAG,OAAA,CAAQ,IAAA,CAAK,CAAC,IAAA,EAAM,IAAA,CAAK,QAAQ,CAAC,CAAA;AAAA,IAChE;AAEA,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACvB,MAAA,IAAA,CAAK;AAAA,QACJ,IAAA,EAAM,iBAAA;AAAA,QACN,OAAA,EAAS,SAAA,CAAU,IAAA,CAAK,QAAA,EAAU,OAAO;AAAA,OACzC,CAAA;AAAA,IACF;AACA,IAAA,IAAI,KAAA,CAAM,SAAS,CAAA,EAAG;AACrB,MAAA,IAAA,CAAK,EAAE,MAAM,aAAA,EAAe,OAAA,EAAS,UAAU,IAAA,CAAK,QAAA,EAAU,KAAK,CAAA,EAAG,CAAA;AAAA,IACvE;AAAA,EACD,CAAA;AAEA,EAAA,OAAO;AAAA,IACN,OAAA,EAAS,CAAC,IAAA,KAAS;AAClB,MAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,MAAA,IAAI,UAAU,YAAA,EAAa,IAAK,CAAC,WAAA,QAAmB,IAAI,CAAA;AAAA,WACnD,IAAA,GAAO,EAAE,IAAA,EAAK;AAAA,IACpB,CAAA;AAAA,IACA,WAAW,SAAA,CAAU,SAAA;AAAA,IACrB,MAAA,EAAQ;AAAA,MACP,WAAA,EAAa;AAAA,QACZ,WAAA,EACC,4DAAA;AAAA,QACD,SAAS,KAAA;AAAM,OAChB;AAAA,MACA,eAAA,EAAiB;AAAA,QAChB,WAAA,EACC,gEAAA;AAAA,QACD,SAAS,KAAA;AAAM;AAChB;AACD,GACD;AACD","file":"index.js","sourcesContent":["import { type EventCatalog, shape } from \"../../analytics/define-events\";\nimport { createListeners, type Subscribe } from \"../listeners\";\nimport type { CartOccurrences } from \"../occurrences\";\n\n/** A line in a `CartSnapshot`. */\nexport type CartLine<Item> = {\n\t/** Stable for the line's lifetime, e.g. Shopify's cart line id. Lines are matched by it. */\n\tid: string;\n\tquantity: number;\n\t/** Unit price, after discounts. */\n\tprice: number;\n\t/** The project's data for the line, e.g. its product and variant. */\n\titem: Item;\n};\n\n/** The cart as the server confirmed it. */\nexport type CartSnapshot<Item> = {\n\tid: string;\n\t/** ISO 4217, e.g. `\"EUR\"`. */\n\tcurrency: string;\n\tlines: CartLine<Item>[];\n};\n\n/** What `createCartChanges()` reports, as its listeners receive it. */\nexport type CartEvent<Item> = {\n\t[K in keyof CartOccurrences<Item>]: {\n\t\tname: K;\n\t\tpayload: CartOccurrences<Item>[K];\n\t};\n}[keyof CartOccurrences<Item>];\n\nexport type CartChanges<Item> = {\n\t/**\n\t * Reports what changed since the last confirmed cart: `addedToCart` for new lines and higher quantities,\n\t * `removedFromCart` for removed lines and lower quantities. Pass `null` while there's no cart, so the first lines\n\t * of a new one count as added. Pass only carts the server confirmed, not optimistic ones. The last cart passed\n\t * before the first `subscribe()` is held until then, e.g. from a child component's effect, which runs before its\n\t * parent's. Does nothing on the server.\n\t */\n\tsetCart: (cart: CartSnapshot<Item> | null) => void;\n\t/**\n\t * Hands what `setCart()` reports to `listener`: every event, or only those named. Pass it to `createAnalytics()`'s\n\t * `sources` instead to track them.\n\t */\n\tsubscribe: Subscribe<CartEvent<Item>>;\n\t/** Catalog entries for what it reports, to spread into `defineEvents()`. */\n\tevents: EventCatalog<CartOccurrences<Item>>;\n};\n\nexport type CartChangesOptions = {\n\t/**\n\t * Where the last confirmed cart is kept, so other tabs and later page loads don't track it again. Change it when the\n\t * item's shape changes, so items stored before don't reach the mappings. Default `\"analytics-cart\"`.\n\t */\n\tstorageKey?: string;\n};\n\n/** What's kept between page loads: the cart, or `id: null` for no cart. */\ntype Stored = { id: string | null; lines: CartLine<unknown>[] };\n\nconst EMPTY: Stored = { id: null, lines: [] };\n\n// Quantities by line, so an equal cart reads as already tracked, whatever else changed on it.\nconst toKey = ({ id, lines }: Stored) =>\n\tJSON.stringify([id, lines.map((line) => [line.id, line.quantity]).sort()]);\n\nconst isLine = (line: unknown): line is CartLine<unknown> => {\n\tif (typeof line !== \"object\" || line === null) return false;\n\tconst { id, quantity, price } = line as Partial<CartLine<unknown>>;\n\treturn (\n\t\ttypeof id === \"string\" &&\n\t\ttypeof quantity === \"number\" &&\n\t\ttypeof price === \"number\" &&\n\t\t\"item\" in line\n\t);\n};\n\n// Written by an earlier deploy too, so a cart in another shape is ignored rather than tracked.\nconst read = (key: string): Stored | undefined => {\n\ttry {\n\t\tconst value = localStorage.getItem(key);\n\t\tconst stored = value ? (JSON.parse(value) as Partial<Stored>) : undefined;\n\t\tif (\n\t\t\t!stored ||\n\t\t\t!(typeof stored.id === \"string\" || stored.id === null) ||\n\t\t\t!Array.isArray(stored.lines) ||\n\t\t\t!stored.lines.every(isLine)\n\t\t) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn stored as Stored;\n\t} catch {\n\t\treturn undefined;\n\t}\n};\n\nconst write = (key: string, value: Stored) => {\n\ttry {\n\t\tlocalStorage.setItem(key, JSON.stringify(value));\n\t} catch {\n\t\t// Storage blocked or full: only this page's changes are deduplicated.\n\t}\n};\n\nconst toPayload = <Item>(\n\tcurrency: string,\n\tchanges: [CartLine<Item>, number][],\n): CartOccurrences<Item>[\"addedToCart\"] => {\n\tconst items = changes.map(([{ item, price }, quantity]) => ({\n\t\titem,\n\t\tquantity,\n\t\tprice,\n\t}));\n\treturn {\n\t\tcurrency,\n\t\tvalue: items.reduce(\n\t\t\t(total, { price, quantity }) => total + price * quantity,\n\t\t\t0,\n\t\t),\n\t\titems,\n\t};\n};\n\n/**\n * Reports `addedToCart` and `removedFromCart` to its listeners by comparing confirmed carts, so add and remove\n * buttons, quantity pickers and cart drawers don't each have to. `Item` is the project's cart line item. One per page;\n * pass it every cart the server confirms.\n *\n * The first cart on a page load counts as the starting point, unless the last confirmed cart is stored from an\n * earlier page, e.g. after a form that adds to the cart and redirects. A cart another tab already tracked isn't\n * tracked again. See `docs/analytics.md`.\n *\n * @example\n * ```ts\n * export const cartChanges = createCartChanges<CartItem>();\n *\n * export const events = defineEvents({ ...cartChanges.events });\n * export const analytics = createAnalytics<EventsOf<typeof events>>({ events, sources: [cartChanges], consent });\n *\n * // Wherever a confirmed cart arrives, e.g. a server action's response, as `CartSnapshot<CartItem>`:\n * cartChanges.setCart(toCartSnapshot(cart));\n * ```\n */\nexport const createCartChanges = <Item>({\n\tstorageKey = \"analytics-cart\",\n}: CartChangesOptions = {}): CartChanges<Item> => {\n\tlet previous: Stored | undefined;\n\tlet held: { cart: CartSnapshot<Item> | null } | undefined;\n\tlet isReplaying = false;\n\n\tconst listeners = createListeners<CartEvent<Item>>({\n\t\tstart: () => {\n\t\t\tif (!held) return;\n\t\t\tisReplaying = true;\n\t\t\t// So every subscription made in the same task receives it, as reporting it marks it tracked.\n\t\t\tqueueMicrotask(() => {\n\t\t\t\tisReplaying = false;\n\t\t\t\tif (!held || !listeners.hasListeners()) return;\n\t\t\t\tconst { cart } = held;\n\t\t\t\theld = undefined;\n\t\t\t\ttrack(cart);\n\t\t\t});\n\t\t},\n\t});\n\tconst { emit } = listeners;\n\n\tconst track = (cart: CartSnapshot<Item> | null) => {\n\t\tconst current: Stored = cart ? { id: cart.id, lines: cart.lines } : EMPTY;\n\t\tconst stored = read(storageKey);\n\t\t// Another tab or page load tracked it already.\n\t\tconst isTracked = stored && toKey(stored) === toKey(current);\n\t\tconst from = previous ?? stored;\n\t\tprevious = current;\n\t\twrite(storageKey, current);\n\t\tif (!cart || isTracked || !from) return;\n\n\t\t// Stored under this key, so with its item.\n\t\tconst before = (from.id === cart.id ? from.lines : []) as CartLine<Item>[];\n\t\tconst quantities = new Map(before.map((line) => [line.id, line.quantity]));\n\t\tconst added: [CartLine<Item>, number][] = [];\n\t\tconst removed: [CartLine<Item>, number][] = [];\n\t\tfor (const line of cart.lines) {\n\t\t\tconst delta = line.quantity - (quantities.get(line.id) ?? 0);\n\t\t\tif (delta > 0) added.push([line, delta]);\n\t\t\tif (delta < 0) removed.push([line, -delta]);\n\t\t}\n\t\tconst remaining = new Set(cart.lines.map((line) => line.id));\n\t\tfor (const line of before) {\n\t\t\tif (!remaining.has(line.id)) removed.push([line, line.quantity]);\n\t\t}\n\n\t\tif (removed.length > 0) {\n\t\t\temit({\n\t\t\t\tname: \"removedFromCart\",\n\t\t\t\tpayload: toPayload(cart.currency, removed),\n\t\t\t});\n\t\t}\n\t\tif (added.length > 0) {\n\t\t\temit({ name: \"addedToCart\", payload: toPayload(cart.currency, added) });\n\t\t}\n\t};\n\n\treturn {\n\t\tsetCart: (cart) => {\n\t\t\tif (typeof window === \"undefined\") return;\n\t\t\tif (listeners.hasListeners() && !isReplaying) track(cart);\n\t\t\telse held = { cart };\n\t\t},\n\t\tsubscribe: listeners.subscribe,\n\t\tevents: {\n\t\t\taddedToCart: {\n\t\t\t\tdescription:\n\t\t\t\t\t\"Lines were added to the cart, or their quantity increased.\",\n\t\t\t\tpayload: shape(),\n\t\t\t},\n\t\t\tremovedFromCart: {\n\t\t\t\tdescription:\n\t\t\t\t\t\"Lines were removed from the cart, or their quantity decreased.\",\n\t\t\t\tpayload: shape(),\n\t\t\t},\n\t\t},\n\t};\n};\n"]}