@inspira-npm/events-react 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+
+import { AdClickProps, AdClickProps as AdClickProps$1, BrowserEventName, CLICK_ID_PARAM, CONSENT_CHANGE_EVENT, ClickRecordOptions, ConsentState, DEFAULT_CONSENT_COOKIE, EventName, EventProps, EventProps as EventProps$1, ImpressionEventName, ImpressionEventName as ImpressionEventName$1, ImpressionOptions, ImpressionOptions as ImpressionOptions$1, OutboundClickProps, OutboundClickProps as OutboundClickProps$1, Tracker, Tracker as Tracker$1, TrackerConfig, cookieConsent, createNoopTracker, createTracker, isClickId, parseConsentValue, readClickIdFromUrl, withClickId, withTrackingParams } from "@inspira-npm/events";
+import { ReactElement, ReactNode } from "react";
+interface EventsProviderProps {
+  /** Tracker creado con `createTracker` (a nivel de módulo, para que no cambie entre renders). */
+  tracker: Tracker$1;
+  children?: ReactNode;
+}
+/** Hace disponible `tracker` a los hooks de este paquete. */
+export declare function EventsProvider({ tracker, children }: EventsProviderProps): ReactElement;
+/** Tracker del `<EventsProvider>` más cercano. Sin provider devuelve un no-op (no rompe la página). */
+export declare function useTracker(): Tracker$1;
+/** `tracker.track` con identidad estable mientras el tracker no cambie (apto para deps). */
+export declare function useTrack(): Tracker$1["track"];
+/** Lo mínimo que se usa del evento: lo cumplen el `MouseEvent` de React y el del DOM. */
+interface AdClickEvent {
+  currentTarget: EventTarget | null;
+  button?: number;
+}
+interface AdClickHandlers {
+  /** La `url` tal cual: igual en servidor y cliente, así la hidratación no difiere. */
+  href: string;
+  onClick: (event: AdClickEvent) => void;
+  /** Click medio (abrir en otra pestaña) también cuenta como click. */
+  onAuxClick: (event: AdClickEvent) => void;
+}
+/**
+ * Props para el `<a>` de un ad: `<a {...useAdClick(props, url)}>`. Al hacer click registra
+ * `ad_click` y cambia el `href` del ancla a la URL con `?ipc=` antes de que el navegador navegue.
+ */
+export declare function useAdClick(props: AdClickProps$1, url: string): AdClickHandlers;
+/**
+ * En el sitio destino de un ad: guarda el `?ipc=` de la URL para atribuir la conversión.
+ * Va en un efecto porque lee `location` y el storage, que no existen en el servidor.
+ */
+export declare function useClickIdCapture(): void;
+/**
+ * Mide la impresión visible del elemento al que se asigna el ref devuelto:
+ * `<div ref={useImpression("ad_impression", props)}>`.
+ *
+ * `props` y `options` pueden ser literales nuevos en cada render: se comparan por valor.
+ */
+export declare function useImpression<N extends ImpressionEventName$1>(name: N, props: EventProps$1<N>, options?: ImpressionOptions$1): (el: Element | null) => void;
+/** Mismo contrato que en `useAdClick`. */
+type OutboundClickEvent = AdClickEvent;
+type OutboundClickHandlers = AdClickHandlers;
+/**
+ * Props para el `<a>` de un link o CTA medido hacia otro sitio o página (p. ej. el CTA de una
+ * landing que lleva al sitio principal): `<a {...useOutboundClick(props, url)}>`. Igual que
+ * `useAdClick`: el `href` del render es la URL tal cual y al hacer click registra
+ * `outbound_click` y reescribe el `href` con `?ipc=` antes de que el navegador navegue.
+ */
+export declare function useOutboundClick(props: OutboundClickProps$1, url: string): OutboundClickHandlers;
+export { type AdClickEvent, type AdClickHandlers, type AdClickProps, type BrowserEventName, CLICK_ID_PARAM, CONSENT_CHANGE_EVENT, type ClickRecordOptions, type ConsentState, DEFAULT_CONSENT_COOKIE, type EventName, type EventProps, type EventsProviderProps, type ImpressionEventName, type ImpressionOptions, type OutboundClickEvent, type OutboundClickHandlers, type OutboundClickProps, type Tracker, type TrackerConfig, cookieConsent, createNoopTracker, createTracker, isClickId, parseConsentValue, readClickIdFromUrl, withClickId, withTrackingParams };

package/dist/index.js

@@ -0,0 +1,124 @@
+"use client";
+import { CLICK_ID_PARAM, CONSENT_CHANGE_EVENT, DEFAULT_CONSENT_COOKIE, cookieConsent, createNoopTracker, createNoopTracker as createNoopTracker$1, createTracker, isClickId, parseConsentValue, readClickIdFromUrl, withClickId, withTrackingParams } from "@inspira-npm/events";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef } from "react";
+// src/provider.ts
+const TrackerContext = createContext(null);
+/** Hace disponible `tracker` a los hooks de este paquete. */
+function EventsProvider({ tracker, children }) {
+	return createElement(TrackerContext.Provider, { value: tracker }, children);
+}
+function isProduction() {
+	try {
+		return process.env.NODE_ENV === "production";
+	} catch {
+		return false;
+	}
+}
+let fallback = null;
+let warned = false;
+function missingProviderTracker() {
+	if (!warned && !isProduction()) {
+		warned = true;
+		console.warn("[inspira-events] Falta <EventsProvider>: los eventos de este árbol no se envían (tracker no-op).");
+	}
+	fallback ?? (fallback = createNoopTracker$1());
+	return fallback;
+}
+/** Tracker del `<EventsProvider>` más cercano. Sin provider devuelve un no-op (no rompe la página). */
+function useTracker() {
+	return useContext(TrackerContext) ?? missingProviderTracker();
+}
+/** `tracker.track` con identidad estable mientras el tracker no cambie (apto para deps). */
+function useTrack() {
+	const tracker = useTracker();
+	return useCallback((name, props) => tracker.track(name, props), [tracker]);
+}
+// src/tracked-link.ts
+/**
+* Base de `useAdClick` y `useOutboundClick`: en cada click llama a `trackClick` (que registra el
+* evento y devuelve la URL con `?ipc=`) y reescribe el `href` del `<a>` antes de que el navegador
+* navegue. `trackClick` debe ser estable (una función de módulo).
+*/
+function useTrackedLink(props, url, trackClick) {
+	const tracker = useTracker();
+	const propsKey = JSON.stringify(props);
+	const onClick = useCallback((event) => {
+		const href = trackClick(tracker, JSON.parse(propsKey), url);
+		const target = event.currentTarget;
+		if (typeof HTMLAnchorElement !== "undefined" && target instanceof HTMLAnchorElement) target.href = href;
+	}, [
+		tracker,
+		propsKey,
+		url,
+		trackClick
+	]);
+	const onAuxClick = useCallback((event) => {
+		if (event.button !== void 0 && event.button !== 1) return;
+		onClick(event);
+	}, [onClick]);
+	return useMemo(() => ({
+		href: url,
+		onClick,
+		onAuxClick
+	}), [
+		url,
+		onClick,
+		onAuxClick
+	]);
+}
+// src/use-ad-click.ts
+const trackAdClick = (tracker, props, url) => tracker.trackAdClick(props, url);
+/**
+* Props para el `<a>` de un ad: `<a {...useAdClick(props, url)}>`. Al hacer click registra
+* `ad_click` y cambia el `href` del ancla a la URL con `?ipc=` antes de que el navegador navegue.
+*/
+function useAdClick(props, url) {
+	return useTrackedLink(props, url, trackAdClick);
+}
+// src/use-click-id-capture.ts
+/**
+* En el sitio destino de un ad: guarda el `?ipc=` de la URL para atribuir la conversión.
+* Va en un efecto porque lee `location` y el storage, que no existen en el servidor.
+*/
+function useClickIdCapture() {
+	const tracker = useTracker();
+	useEffect(() => {
+		tracker.captureClickId();
+	}, [tracker]);
+}
+// src/use-impression.ts
+/**
+* Mide la impresión visible del elemento al que se asigna el ref devuelto:
+* `<div ref={useImpression("ad_impression", props)}>`.
+*
+* `props` y `options` pueden ser literales nuevos en cada render: se comparan por valor.
+*/
+function useImpression(name, props, options) {
+	const tracker = useTracker();
+	const propsKey = JSON.stringify(props);
+	const optionsKey = options ? JSON.stringify(options) : "";
+	const cleanupRef = useRef(null);
+	return useCallback((el) => {
+		cleanupRef.current?.();
+		cleanupRef.current = null;
+		if (!el) return;
+		cleanupRef.current = tracker.observeImpression(el, name, JSON.parse(propsKey), optionsKey ? JSON.parse(optionsKey) : void 0);
+	}, [
+		tracker,
+		name,
+		propsKey,
+		optionsKey
+	]);
+}
+// src/use-outbound-click.ts
+const trackOutboundClick = (tracker, props, url) => tracker.trackOutboundClick(props, url);
+/**
+* Props para el `<a>` de un link o CTA medido hacia otro sitio o página (p. ej. el CTA de una
+* landing que lleva al sitio principal): `<a {...useOutboundClick(props, url)}>`. Igual que
+* `useAdClick`: el `href` del render es la URL tal cual y al hacer click registra
+* `outbound_click` y reescribe el `href` con `?ipc=` antes de que el navegador navegue.
+*/
+function useOutboundClick(props, url) {
+	return useTrackedLink(props, url, trackOutboundClick);
+}
+export { CLICK_ID_PARAM, CONSENT_CHANGE_EVENT, DEFAULT_CONSENT_COOKIE, EventsProvider, cookieConsent, createNoopTracker, createTracker, isClickId, parseConsentValue, readClickIdFromUrl, useAdClick, useClickIdCapture, useImpression, useOutboundClick, useTrack, useTracker, withClickId, withTrackingParams };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@inspira-npm/events-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Provider y hooks de React para @inspira-npm/events.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@inspira-npm/events": "^0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.