@sudobility/building_blocks 0.0.21 → 0.0.23

package/dist/types.d.ts

@@ -1,7 +1,31 @@
+/**
+ * @fileoverview Type definitions for @sudobility/building_blocks
+ *
+ * @ai-context This file contains all TypeScript interfaces and types used across
+ * the building_blocks component library. Types are organized by domain:
+ * - Navigation (MenuItemConfig, LogoConfig, BreadcrumbItem)
+ * - Footer (FooterLinkItem, FooterLinkSection, SocialLinksConfig)
+ * - Layout (MaxWidth, ContentPadding, BackgroundVariant)
+ * - Analytics (AnalyticsEventType, AnalyticsTrackingParams)
+ *
+ * @ai-pattern All interfaces use JSDoc comments with property descriptions.
+ * Optional properties are marked with `?` suffix.
+ */
 import type { ComponentType, ReactNode } from 'react';
 export type { LanguageConfig } from './constants/languages';
 /**
  * Menu item configuration for AppTopBar navigation.
+ *
+ * @ai-context Used by AppTopBar, AppTopBarWithFirebaseAuth, AppTopBarWithWallet
+ * @ai-usage Pass an array of these to the `menuItems` prop
+ *
+ * @example
+ * ```tsx
+ * const menuItems: MenuItemConfig[] = [
+ *   { id: 'docs', label: 'Docs', icon: DocumentTextIcon, href: '/docs' },
+ *   { id: 'settings', label: 'Settings', icon: Cog6ToothIcon, href: '/settings', show: isLoggedIn },
+ * ];
+ * ```
  */
 export interface MenuItemConfig {
     /** Unique identifier for the menu item */
@@ -131,3 +155,93 @@ export type ContentPadding = 'none' | 'sm' | 'md' | 'lg';
  * Background variant options.
  */
 export type BackgroundVariant = 'default' | 'white' | 'gradient';
+/**
+ * Analytics tracking event types for building blocks components.
+ *
+ * @ai-context These event types categorize user interactions for analytics.
+ * Each component uses specific event types based on its functionality.
+ *
+ * @ai-pattern Components call `onTrack` with these event types:
+ * - AppFooter, AppFooterForHomePage: 'link_click'
+ * - GlobalSettingsPage: 'settings_change'
+ * - AppPricingPage: 'subscription_action'
+ */
+export type AnalyticsEventType = 
+/** User clicked a button (e.g., CTA, submit) */
+'button_click'
+/** User clicked a navigation link */
+ | 'link_click'
+/** User navigated to a different section/page */
+ | 'navigation'
+/** User changed a setting (theme, font size, etc.) */
+ | 'settings_change'
+/** User interacted with subscription/pricing (plan click, billing change) */
+ | 'subscription_action'
+/** Page was viewed (typically tracked by router, not components) */
+ | 'page_view';
+/**
+ * Analytics tracking parameters passed to onTrack callbacks.
+ *
+ * @ai-context This is the standard payload for all analytics events from
+ * building_blocks components. The consuming app maps these to their
+ * analytics provider (Firebase, Mixpanel, Segment, etc.).
+ *
+ * @ai-usage
+ * ```tsx
+ * const handleTrack = (params: AnalyticsTrackingParams) => {
+ *   firebase.analytics().logEvent(params.label, {
+ *     component: params.componentName,
+ *     event_type: params.eventType,
+ *     ...params.params,
+ *   });
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example params from AppPricingPage
+ * {
+ *   eventType: 'subscription_action',
+ *   componentName: 'AppPricingPage',
+ *   label: 'plan_clicked',
+ *   params: { plan_identifier: 'pro_monthly', action_type: 'upgrade' }
+ * }
+ *
+ * // Example params from AppFooter
+ * {
+ *   eventType: 'link_click',
+ *   componentName: 'AppFooter',
+ *   label: 'footer_link_clicked',
+ *   params: { link_label: 'Privacy', link_href: '/privacy' }
+ * }
+ * ```
+ */
+export interface AnalyticsTrackingParams {
+    /** Type of event being tracked (categorizes the interaction) */
+    eventType: AnalyticsEventType;
+    /** Component name where the event originated (e.g., 'AppPricingPage') */
+    componentName: string;
+    /** Human-readable label for the action (e.g., 'plan_clicked', 'theme_changed') */
+    label: string;
+    /** Additional context-specific parameters (varies by component and action) */
+    params?: Record<string, unknown>;
+}
+/**
+ * Analytics tracking callback interface for components.
+ *
+ * @ai-context Components that support analytics accept an optional `onTrack` prop
+ * of type `(params: AnalyticsTrackingParams) => void`. This interface is provided
+ * for consumers who want to type their tracking implementation.
+ *
+ * @ai-pattern To add analytics to a component:
+ * 1. Add `onTrack?: (params: AnalyticsTrackingParams) => void` to props
+ * 2. Create a track helper: `const track = (label, params) => onTrack?.({...})`
+ * 3. Call `track()` on user interactions
+ */
+export interface AnalyticsTracker {
+    /**
+     * Track an analytics event.
+     * @param params The tracking parameters including event type, component, label, and custom params
+     */
+    onTrack: (params: AnalyticsTrackingParams) => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/building_blocks",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Higher-level shared UI building blocks for Sudobility apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,8 +33,8 @@
   },
   "peerDependencies": {
     "@heroicons/react": "^2.0.0",
-    "@sudobility/components": "^4.0.134",
-    "@sudobility/design": "^1.1.17",
+    "@sudobility/components": "^4.0.139",
+    "@sudobility/design": "^1.1.18",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
     "react": "^18.0.0 || ^19.0.0",
@@ -64,10 +64,10 @@
   "devDependencies": {
     "@eslint/js": "^9.38.0",
     "@heroicons/react": "^2.2.0",
-    "@sudobility/components": "^4.0.134",
-    "@sudobility/design": "^1.1.17",
+    "@sudobility/components": "^4.0.139",
+    "@sudobility/design": "^1.1.18",
     "@sudobility/subscription-components": "^1.0.13",
-    "@sudobility/types": "^1.9.43",
+    "@sudobility/types": "^1.9.44",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",