Add Analytics package (#46)

* Add Analytics package

Created a new analytics package with a manager to handle tracking of events and page views. The package includes a default provider that can be switched out and uses a NullAnalyticsService if no provider is registered. Additional types, scripts, and package configuration are also provided to support development.

* Add marketing components for UI package

Introduced new React components under "marketing" for the UI package. These include 'Pill', 'GradientSecondaryText', 'Hero', 'CtaButton', 'FeatureCard', 'FeatureGrid', 'FeatureShowcase', 'GradientText', 'Header', and 'SecondaryHero'. Updated 'package.json' to export these components. Replaced the implementation of 'Home', 'SiteHeader', and 'SiteFooter' with these components for cleaner code and better reusability.

packages/analytics/README.md

@@ -0,0 +1,10 @@
+# Analytics - @kit/analytics
+
+@kit/analytics Package provides a simple and consistent API for tracking analytics events in web applications.
+
+## Overview
+
+This version of the `@kit/analytics` package uses classes internally for structure and encapsulation, but exposes a functional API for ease of use and consistency with Makerkit's style.
+
+## Implementation
+

packages/analytics/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kit/analytics",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "clean": "git clean -xdf .turbo node_modules",
+    "format": "prettier --check \"**/*.{ts,tsx}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "prettier": "@kit/prettier-config",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@kit/eslint-config": "workspace:*",
+    "@kit/prettier-config": "workspace:*",
+    "@kit/tailwind-config": "workspace:*",
+    "@kit/tsconfig": "workspace:*"
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@kit/eslint-config/base",
+      "@kit/eslint-config/react"
+    ]
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  }
+}

packages/analytics/src/analytics-manager.ts

@@ -0,0 +1,72 @@
+import { NullAnalyticsService } from './null-analytics-service';
+import {
+  AnalyticsManager,
+  AnalyticsService,
+  CreateAnalyticsManagerOptions,
+} from './types';
+
+/**
+ * Creates an analytics manager that can be used to track page views and events. The manager is initialized with a
+ * default provider and can be switched to a different provider at any time. The manager will use a NullAnalyticsService
+ * if the provider is not registered.
+ * @param options
+ */
+export function createAnalyticsManager<T extends string, Config extends object>(
+  options: CreateAnalyticsManagerOptions<T, Config>,
+): AnalyticsManager {
+  let activeService: AnalyticsService = NullAnalyticsService;
+
+  const getActiveService = (): AnalyticsService => {
+    if (activeService === NullAnalyticsService) {
+      console.warn(
+        'Analytics service not initialized. Using NullAnalyticsService.',
+      );
+    }
+
+    return activeService;
+  };
+
+  const initialize = (provider: T, config: Config) => {
+    const factory = options.providers[provider];
+
+    if (!factory) {
+      console.error(
+        `Analytics provider '${provider}' not registered. Using NullAnalyticsService.`,
+      );
+
+      activeService = NullAnalyticsService;
+      return;
+    }
+
+    activeService = factory(config);
+    activeService.initialize();
+  };
+
+  // Initialize with the default provider
+  initialize(options.defaultProvider, {} as Config);
+
+  return {
+    identify: (userId: string, traits?: Record<string, string>) => {
+      return getActiveService().identify(userId, traits);
+    },
+
+    /**
+     * Track a page view with the given URL.
+     * @param url
+     */
+    trackPageView: (url: string) => {
+      return getActiveService().trackPageView(url);
+    },
+    /**
+     * Track an event with the given name and properties.
+     * @param eventName
+     * @param eventProperties
+     */
+    trackEvent: (
+      eventName: string,
+      eventProperties?: Record<string, string | string[]>,
+    ) => {
+      return getActiveService().trackEvent(eventName, eventProperties);
+    },
+  };
+}

packages/analytics/src/index.ts

@@ -0,0 +1,10 @@
+import { createAnalyticsManager } from './analytics-manager';
+import { NullAnalyticsService } from './null-analytics-service';
+import type { AnalyticsManager } from './types';
+
+export const analytics: AnalyticsManager = createAnalyticsManager({
+  defaultProvider: 'null',
+  providers: {
+    null: () => NullAnalyticsService,
+  },
+});

packages/analytics/src/null-analytics-service.ts

@@ -0,0 +1,16 @@
+import { AnalyticsService } from './types';
+
+const noop = () => {
+  // do nothing - this is to prevent errors when the analytics service is not initialized
+};
+
+/**
+ * Null analytics service that does nothing. It is initialized with a noop function. This is useful for testing or when
+ * the user is calling analytics methods before the analytics service is initialized.
+ */
+export const NullAnalyticsService: AnalyticsService = {
+  initialize: noop,
+  trackPageView: noop,
+  trackEvent: noop,
+  identify: noop,
+};

packages/analytics/src/types.ts

@@ -0,0 +1,32 @@
+interface TrackEvent {
+  trackEvent(
+    eventName: string,
+    eventProperties?: Record<string, string | string[]>,
+  ): void;
+}
+
+interface TrackPageView {
+  trackPageView(url: string): void;
+}
+
+interface Identify {
+  identify(userId: string, traits?: Record<string, string>): void;
+}
+
+export interface AnalyticsService extends TrackPageView, TrackEvent, Identify {
+  initialize(): void;
+}
+
+export type AnalyticsProviderFactory<Config extends object> = (
+  config: Config,
+) => AnalyticsService;
+
+export interface CreateAnalyticsManagerOptions<
+  T extends string,
+  Config extends object,
+> {
+  defaultProvider: T;
+  providers: Record<T, AnalyticsProviderFactory<Config>>;
+}
+
+export interface AnalyticsManager extends TrackPageView, TrackEvent, Identify {}

packages/analytics/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@kit/tsconfig/base.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+  },
+  "include": ["*.ts", "src"],
+  "exclude": ["node_modules"]
+}