@se-studio/core-ui 1.0.13 → 1.0.15

package/README.md

@@ -87,6 +87,51 @@ In your Next.js app layout or root component:
 import '@se-studio/core-ui/styles';
 ```
 
+### Analytics Integration
+
+Core UI ships analytics primitives but intentionally does not select a vendor.
+Wrap your app with `AnalyticsProvider` and pass an adapter that implements the
+`AnalyticsAdapter` interface.
+
+```tsx
+import { AnalyticsProvider, ConsoleAnalyticsAdapter } from '@se-studio/core-ui';
+
+const analyticsAdapter = new ConsoleAnalyticsAdapter(); // example adapter
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  return <AnalyticsProvider adapter={analyticsAdapter}>{children}</AnalyticsProvider>;
+}
+```
+
+Use the `useAnalytics` hook anywhere within the provider to trigger events:
+
+```tsx
+import { useAnalytics } from '@se-studio/core-ui';
+
+export function NewsletterCta() {
+  const { trackClick } = useAnalytics();
+
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        trackClick('Button', 'Sign up', {
+          page_title: 'Home',
+          page_type: 'landing',
+          slug: 'home',
+        })
+      }
+    >
+      Sign up
+    </button>
+  );
+}
+```
+
+The provided `ConsoleAnalyticsAdapter` simply logs events for development and
+documentation purposes. Each project should supply an adapter that forwards
+events to its analytics platform of choice.
+
 ## Components
 
 ### CMS Infrastructure Components
@@ -278,20 +323,39 @@ const previewConfig = mergeCmsRendererConfig(
 );
 ```
 
-## API Exports
-
-### Component Configuration Types
-
-- `ComponentConfig<TComponent, TContext>` - Type-safe component configuration
-- `CollectionConfig<TCollection, TContext>` - Type-safe collection configuration
-- `CmsRendererConfig` - Complete renderer configuration type
-
-### Utility Functions
-
-- `buildPageMetadata(page)` - Generate Next.js metadata from page data
-- `handleCmsError(error)` - Error handling utility for CMS operations
-- `extractComponentInfo(component, config)` - Extract component rendering info
-- `extractCollectionInfo(collection, config)` - Extract collection rendering info
+## API Reference
+
+### Main Exports
+
+#### Components
+- **`CmsContent`** - Main component for rendering CMS content with automatic component mapping
+- **`CmsComponent`** - Renders individual CMS components with type-based routing
+- **`CmsCollection`** - Renders CMS collections (arrays of components)
+- **`Visual`** - Optimized image/video/animation component with Next.js Image integration
+- **`RTF`** - Renders Contentful rich text with support for embedded entries and assets
+- **`UnusedChecker`** - Development utility to detect unused CMS content types
+
+#### Hooks
+- **`useAnalytics`** - Hook for accessing analytics functions (trackEvent, trackPage, trackClick)
+- **`useClickTracking`** - Hook for tracking click events with analytics
+- **`useDocumentVisible`** - Hook for tracking document visibility
+
+#### Utilities
+- **`buildPageMetadata`** - Generates Next.js metadata object from CMS page model
+- **`handleCmsError`** - Error handling utility for CMS operations
+- **`extractComponentInfo`** - Extract specific component information fields
+- **`extractCollectionInfo`** - Extract specific collection information fields
+- **`extractPageContext`** - Extract specific page context fields
+- **`cn`** - Utility function for merging Tailwind CSS classes
+
+#### Types
+- **`CmsRendererConfig`** - Complete renderer configuration type
+- **`ComponentRenderer<T>`** - Type for component renderer functions
+- **`CollectionRenderer<T>`** - Type for collection renderer functions
+- **`ComponentConfig<T>`** - Type-safe component configuration
+- **`CollectionConfig<T>`** - Type-safe collection configuration
+
+For detailed JSDoc documentation on all exports, see the TypeScript declaration files (`.d.ts`) in the package.
 
 ## Advanced Usage
 

package/dist/CmsRendererConfig.d.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Any is allowed */
 import type { IContentContext } from '@se-studio/core-data-types';
 import type { React } from 'next/dist/server/route-modules/app-page/vendored/rsc/entrypoints';
 import type { CollectionMap, CollectionRenderer, EmbeddedCollectionMap } from './components/CmsCollection';
@@ -12,20 +13,141 @@ export type CmsRendererTypes = {
     ExternaComponentNameType: string;
     ExternalComponentType: any;
 };
+/**
+ * Configuration object that bundles all CMS renderer maps and display options.
+ * Create this once at the project level and pass it to CmsContent.
+ *
+ * This provides a clean, extensible API for configuring how CMS content is rendered,
+ * making it easy to add new renderer types without breaking existing code.
+ *
+ * @example Basic configuration
+ * ```tsx
+ * const rendererConfig = createCmsRendererConfig<MyProjectConfig>({
+ *   componentMap: {
+ *     "Hero": HeroComponent,
+ *     "CTA": CTAComponent,
+ *     "Content Block": ContentBlock,
+ *   },
+ *   collectionMap: {
+ *     "FAQs": FAQCollection,
+ *     "Related Articles": RelatedArticles,
+ *   },
+ *   showUnknownTypeErrors: process.env.NODE_ENV === 'development',
+ * });
+ * ```
+ *
+ * @example With all renderer types
+ * ```tsx
+ * const rendererConfig = createCmsRendererConfig<MyProjectConfig>({
+ *   componentMap: { ... },
+ *   collectionMap: { ... },
+ *   externalComponentMap: {
+ *     "Contact Form": ContactFormRenderer,
+ *     "Newsletter": NewsletterRenderer,
+ *   },
+ *   visualComponentRenderer: VisualRenderer,
+ *   internalLinkRenderer: InternalLinkRenderer,
+ *   showUnknownTypeErrors: true,
+ *   showRenderErrors: true,
+ * });
+ * ```
+ */
 export interface CmsRendererConfig<TConfig extends CmsRendererTypes = CmsRendererTypes> {
+    /**
+     * Map of component types to their renderers.
+     * Each key should match a ComponentType from your CMS configuration.
+     *
+     * @example
+     * ```tsx
+     * componentMap: {
+     *   "Hero": HeroComponent,
+     *   "CTA": CTAComponent,
+     * }
+     * ```
+     */
     componentMap: ComponentMap<TConfig['ComponentNameType'], TConfig['ComponentType']>;
     embeddedComponentMap: EmbeddedComponentMap<TConfig['ComponentNameType'], TConfig['ComponentType']>;
+    /**
+     * Map of collection types to their renderers.
+     * Each key should match a CollectionType from your CMS configuration.
+     *
+     * @example
+     * ```tsx
+     * collectionMap: {
+     *   "FAQs": FAQCollection,
+     *   "Related Articles": RelatedArticles,
+     * }
+     * ```
+     */
     collectionMap: CollectionMap<TConfig['CollectionNameType'], TConfig['CollectionType']>;
     embeddedCollectionMap: EmbeddedCollectionMap<TConfig['CollectionNameType'], TConfig['CollectionType']>;
+    /**
+     * Map of external component types to their renderers (optional).
+     * Use this for third-party integrations, forms, widgets, etc.
+     *
+     * @example
+     * ```tsx
+     * externalComponentMap: {
+     *   "Contact Form": ContactFormRenderer,
+     *   "Newsletter": NewsletterRenderer,
+     * }
+     * ```
+     */
     externalComponentMap: ExternalComponentMap<TConfig['ExternaComponentNameType'], TConfig['ExternalComponentType']>;
     embeddedExternalComponentMap: EmbeddedExternalComponentMap<TConfig['ExternaComponentNameType'], TConfig['ExternalComponentType']>;
+    /**
+     * Renderer for Visual content types (optional).
+     * Use this to define how images, videos, and other visual assets are rendered.
+     *
+     * @example
+     * ```tsx
+     * visualComponentRenderer: ({ information, contentContext }) => (
+     *   <VisualComponent visual={information} />
+     * )
+     * ```
+     */
     visualComponentRenderer: VisualComponentRenderer;
+    /**
+     * Renderer for Internal Link content types (optional).
+     * Use this to define how internal navigation links are rendered.
+     *
+     * @example
+     * ```tsx
+     * internalLinkRenderer: ({ information }) => (
+     *   <Link href={information.href}>{information.text}</Link>
+     * )
+     * ```
+     */
     internalLinkRenderer: InternalLinkRenderer;
+    /**
+     * Map of custom content types to their renderers (optional).
+     * Use this for project-specific content types that extend the base CMS content model.
+     *
+     * @example
+     * ```tsx
+     * customContentMap: {
+     *   "pricingPlan": PricingPlanRenderer,
+     *   "testimonial": TestimonialRenderer,
+     * }
+     * ```
+     */
     customContentMap?: Partial<Record<string, React.FC<{
         information: any;
         contentContext: IContentContext;
     }>>>;
+    /**
+     * Show error panels for unknown content types in development mode (default: false).
+     * When true, displays a visual warning when a component/collection type is not mapped.
+     *
+     * Recommended: Set to `process.env.NODE_ENV === 'development'`
+     */
     showUnknownTypeErrors: boolean;
+    /**
+     * Show error panels for rendering errors (default: false).
+     * When true, displays error details when a component throws during rendering.
+     *
+     * Recommended: Set to `process.env.NODE_ENV === 'development'`
+     */
     showRenderErrors: boolean;
     defaultComponentRenderer: ComponentRenderer<any>;
     defaultCollectionRenderer: CollectionRenderer<any>;

package/dist/CmsRendererConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CmsRendererConfig.d.ts","sourceRoot":"","sources":["../src/CmsRendererConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kEAAkE,CAAC;AAC9F,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,GAAG,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC;IACpB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,GAAG,CAAC;CAC5B,CAAC;AAyCF,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IAapF,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAEnF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,mBAAmB,CAAC,EAC5B,OAAO,CAAC,eAAe,CAAC,CACzB,CAAC;IAcF,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvF,qBAAqB,EAAE,qBAAqB,CAC1C,OAAO,CAAC,oBAAoB,CAAC,EAC7B,OAAO,CAAC,gBAAgB,CAAC,CAC1B,CAAC;IAcF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IACF,4BAA4B,EAAE,4BAA4B,CACxD,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IAaF,uBAAuB,EAAE,uBAAuB,CAAC;IAajD,oBAAoB,EAAE,oBAAoB,CAAC;IAc3C,gBAAgB,CAAC,EAAE,OAAO,CACxB,MAAM,CACJ,MAAM,EACN,KAAK,CAAC,EAAE,CAAC;QACP,WAAW,EAAE,GAAG,CAAC;QACjB,cAAc,EAAE,eAAe,CAAC;KACjC,CAAC,CACH,CACF,CAAC;IAQF,qBAAqB,EAAE,OAAO,CAAC;IAQ/B,gBAAgB,EAAE,OAAO,CAAC;IAE1B,wBAAwB,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACjD,yBAAyB,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACpD"}
+{"version":3,"file":"CmsRendererConfig.d.ts","sourceRoot":"","sources":["../src/CmsRendererConfig.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kEAAkE,CAAC;AAC9F,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,GAAG,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC;IACpB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,GAAG,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IACpF;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAEnF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,mBAAmB,CAAC,EAC5B,OAAO,CAAC,eAAe,CAAC,CACzB,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvF,qBAAqB,EAAE,qBAAqB,CAC1C,OAAO,CAAC,oBAAoB,CAAC,EAC7B,OAAO,CAAC,gBAAgB,CAAC,CAC1B,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IACF,4BAA4B,EAAE,4BAA4B,CACxD,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IAEF;;;;;;;;;;OAUG;IACH,uBAAuB,EAAE,uBAAuB,CAAC;IAEjD;;;;;;;;;;OAUG;IACH,oBAAoB,EAAE,oBAAoB,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CACxB,MAAM,CACJ,MAAM,EACN,KAAK,CAAC,EAAE,CAAC;QACP,WAAW,EAAE,GAAG,CAAC;QACjB,cAAc,EAAE,eAAe,CAAC;KACjC,CAAC,CACH,CACF,CAAC;IAEF;;;;;OAKG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B,wBAAwB,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACjD,yBAAyB,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACpD"}

package/dist/analytics/AnalyticsProvider.d.ts

@@ -0,0 +1,16 @@
+import type React from 'react';
+import type { AnalyticsAdapter } from './types';
+export interface AnalyticsProviderProps {
+    adapter: AnalyticsAdapter;
+    children: React.ReactNode;
+}
+/**
+ * Provider component that makes analytics adapter available to child components
+ */
+export declare function AnalyticsProvider({ adapter, children }: AnalyticsProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the analytics adapter from context
+ * @throws Error if used outside of AnalyticsProvider
+ */
+export declare function useAnalyticsContext(): AnalyticsAdapter;
+//# sourceMappingURL=AnalyticsProvider.d.ts.map

package/dist/analytics/AnalyticsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyticsProvider.d.ts","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIhD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,sBAAsB,2CAE9E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAMtD"}

package/dist/analytics/AnalyticsProvider.js

@@ -0,0 +1,22 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+const AnalyticsContext = createContext(null);
+/**
+ * Provider component that makes analytics adapter available to child components
+ */
+export function AnalyticsProvider({ adapter, children }) {
+    return _jsx(AnalyticsContext.Provider, { value: adapter, children: children });
+}
+/**
+ * Hook to access the analytics adapter from context
+ * @throws Error if used outside of AnalyticsProvider
+ */
+export function useAnalyticsContext() {
+    const adapter = useContext(AnalyticsContext);
+    if (!adapter) {
+        throw new Error('useAnalyticsContext must be used within an AnalyticsProvider');
+    }
+    return adapter;
+}
+//# sourceMappingURL=AnalyticsProvider.js.map

package/dist/analytics/AnalyticsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyticsProvider.js","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAGb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD,MAAM,gBAAgB,GAAG,aAAa,CAA0B,IAAI,CAAC,CAAC;AAOtE;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAA0B;IAC7E,OAAO,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YAAG,QAAQ,GAA6B,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.d.ts

@@ -0,0 +1,12 @@
+import type { AnalyticsAdapter, ClickTrackingProperties, PageTrackingProperties } from '../types';
+/**
+ * Console adapter used as the default/example implementation.
+ * Customer projects should provide their own adapter that satisfies `AnalyticsAdapter`.
+ */
+export declare class ConsoleAnalyticsAdapter implements AnalyticsAdapter {
+    private log;
+    trackEvent(event: string, properties: Record<string, unknown>): void;
+    trackPage(url: string, properties: PageTrackingProperties): void;
+    trackClick(properties: ClickTrackingProperties): void;
+}
+//# sourceMappingURL=ConsoleAnalyticsAdapter.d.ts.map

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleAnalyticsAdapter.d.ts","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElG;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,GAAG;IAKX,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI;IAIhE,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI;CAGtD"}

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.js

@@ -0,0 +1,21 @@
+'use client';
+/**
+ * Console adapter used as the default/example implementation.
+ * Customer projects should provide their own adapter that satisfies `AnalyticsAdapter`.
+ */
+export class ConsoleAnalyticsAdapter {
+    log(...args) {
+        // eslint-disable-next-line no-console -- intentional logging adapter
+        console.log('[Analytics]', ...args);
+    }
+    trackEvent(event, properties) {
+        this.log('event', event, properties);
+    }
+    trackPage(url, properties) {
+        this.log('page', { ...properties, url });
+    }
+    trackClick(properties) {
+        this.log('click', properties);
+    }
+}
+//# sourceMappingURL=ConsoleAnalyticsAdapter.js.map

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAIb;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IAC1B,GAAG,CAAC,GAAG,IAAe;QAC5B,qEAAqE;QACrE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,UAAU,CAAC,KAAa,EAAE,UAAmC;QAC3D,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,SAAS,CAAC,GAAW,EAAE,UAAkC;QACvD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU,CAAC,UAAmC;QAC5C,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/analytics/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export { ConsoleAnalyticsAdapter } from './ConsoleAnalyticsAdapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analytics/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/analytics/adapters/index.js

@@ -0,0 +1,2 @@
+export { ConsoleAnalyticsAdapter } from './ConsoleAnalyticsAdapter';
+//# sourceMappingURL=index.js.map

package/dist/analytics/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analytics/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,41 @@
+import type { IAnalyticsContext } from '@se-studio/core-data-types';
+/**
+ * Properties for tracking a click event
+ */
+export interface ClickTrackingProperties extends IAnalyticsContext {
+    componentType: string;
+    url: string;
+    targetUrl?: string;
+    linkText: string;
+    location?: string;
+}
+/**
+ * Properties for tracking a page view
+ */
+export interface PageTrackingProperties extends IAnalyticsContext {
+    url: string;
+    pathname: string;
+}
+/**
+ * Interface that analytics adapters must implement
+ */
+export interface AnalyticsAdapter {
+    /**
+     * Track a custom event
+     * @param event - Event name
+     * @param properties - Event properties
+     */
+    trackEvent(event: string, properties: Record<string, unknown>): void;
+    /**
+     * Track a page view
+     * @param url - Full URL of the page
+     * @param properties - Page properties
+     */
+    trackPage(url: string, properties: PageTrackingProperties): void;
+    /**
+     * Track a component click
+     * @param properties - Click tracking properties
+     */
+    trackClick(properties: ClickTrackingProperties): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAErE;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEjE;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAAC;CACvD"}

package/dist/analytics/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":""}

package/dist/analytics/useAnalytics.d.ts

@@ -0,0 +1,45 @@
+import type { IAnalyticsContext } from '@se-studio/core-data-types';
+/**
+ * Hook for accessing analytics functions.
+ *
+ * Provides a clean API for tracking events, pages, and clicks. Must be used
+ * within an AnalyticsProvider context.
+ *
+ * @returns Object with tracking functions:
+ * - `trackEvent` - Track custom events
+ * - `trackPage` - Track page views
+ * - `trackClick` - Track click interactions
+ *
+ * @throws {Error} If used outside of AnalyticsProvider
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useAnalytics } from '@se-studio/core-ui';
+ *
+ * function MyComponent() {
+ *   const { trackClick, trackPage } = useAnalytics();
+ *
+ *   useEffect(() => {
+ *     trackPage(window.location.href, window.location.pathname, {
+ *       page_title: 'Home',
+ *       page_type: 'landing',
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <button onClick={() => trackClick('Button', 'Sign up', { page_title: 'Home' })}>
+ *       Sign up
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAnalytics(): {
+    trackEvent: (event: string, properties: Record<string, unknown>) => void;
+    trackPage: (url: string, pathname: string, analyticsContext: IAnalyticsContext) => void;
+    trackClick: (componentType: string, linkText: string, analyticsContext: IAnalyticsContext, options?: {
+        targetUrl?: string;
+        location?: string;
+    }) => void;
+};
+//# sourceMappingURL=useAnalytics.d.ts.map

package/dist/analytics/useAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAKpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY;wBAIhB,MAAM,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;qBAO7C,MAAM,YAAY,MAAM,oBAAoB,iBAAiB;gCAalD,MAAM,YACX,MAAM,oBACE,iBAAiB,YACzB;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;EAqBN"}

package/dist/analytics/useAnalytics.js

@@ -0,0 +1,70 @@
+'use client';
+import { useCallback } from 'react';
+import { useAnalyticsContext } from './AnalyticsProvider';
+/**
+ * Hook for accessing analytics functions.
+ *
+ * Provides a clean API for tracking events, pages, and clicks. Must be used
+ * within an AnalyticsProvider context.
+ *
+ * @returns Object with tracking functions:
+ * - `trackEvent` - Track custom events
+ * - `trackPage` - Track page views
+ * - `trackClick` - Track click interactions
+ *
+ * @throws {Error} If used outside of AnalyticsProvider
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useAnalytics } from '@se-studio/core-ui';
+ *
+ * function MyComponent() {
+ *   const { trackClick, trackPage } = useAnalytics();
+ *
+ *   useEffect(() => {
+ *     trackPage(window.location.href, window.location.pathname, {
+ *       page_title: 'Home',
+ *       page_type: 'landing',
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <button onClick={() => trackClick('Button', 'Sign up', { page_title: 'Home' })}>
+ *       Sign up
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useAnalytics() {
+    const adapter = useAnalyticsContext();
+    const trackEvent = useCallback((event, properties) => {
+        adapter.trackEvent(event, properties);
+    }, [adapter]);
+    const trackPage = useCallback((url, pathname, analyticsContext) => {
+        const properties = {
+            url,
+            pathname,
+            ...analyticsContext,
+        };
+        adapter.trackPage(url, properties);
+    }, [adapter]);
+    const trackClick = useCallback((componentType, linkText, analyticsContext, options) => {
+        const url = typeof window !== 'undefined' ? window.location.href : '';
+        const properties = {
+            componentType,
+            url,
+            linkText,
+            location: options?.location,
+            targetUrl: options?.targetUrl,
+            ...analyticsContext,
+        };
+        adapter.trackClick(properties);
+    }, [adapter]);
+    return {
+        trackEvent,
+        trackPage,
+        trackClick,
+    };
+}
+//# sourceMappingURL=useAnalytics.js.map

package/dist/analytics/useAnalytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnalytics.js","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,KAAa,EAAE,UAAmC,EAAE,EAAE;QACrD,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACxC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,GAAW,EAAE,QAAgB,EAAE,gBAAmC,EAAE,EAAE;QACrE,MAAM,UAAU,GAA2B;YACzC,GAAG;YACH,QAAQ;YACR,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,CACE,aAAqB,EACrB,QAAgB,EAChB,gBAAmC,EACnC,OAGC,EACD,EAAE;QACF,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,MAAM,UAAU,GAA4B;YAC1C,aAAa;YACb,GAAG;YACH,QAAQ;YACR,QAAQ,EAAE,OAAO,EAAE,QAAQ;YAC3B,SAAS,EAAE,OAAO,EAAE,SAAS;YAC7B,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO;QACL,UAAU;QACV,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/components/ClientMonitor.d.ts

@@ -1,5 +1,6 @@
 interface ClientMonitorProps {
     defaultThreshold?: number;
+    enableDebug?: boolean;
 }
 export declare const ClientMonitor: React.FC<ClientMonitorProps>;
 export {};

package/dist/components/ClientMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientMonitor.d.ts","sourceRoot":"","sources":["../../src/components/ClientMonitor.tsx"],"names":[],"mappings":"AAmNA,UAAU,kBAAkB;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAatD,CAAC"}
+{"version":3,"file":"ClientMonitor.d.ts","sourceRoot":"","sources":["../../src/components/ClientMonitor.tsx"],"names":[],"mappings":"AAkbA,UAAU,kBAAkB;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAuBtD,CAAC"}