@sudobility/building_blocks 0.0.18 → 0.0.22

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.18",
+  "version": "0.0.22",
   "description": "Higher-level shared UI building blocks for Sudobility apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
   "peerDependencies": {
     "@heroicons/react": "^2.0.0",
     "@sudobility/components": "^4.0.134",
-    "@sudobility/design": "^1.1.17",
+    "@sudobility/design": "^1.1.18",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
     "react": "^18.0.0 || ^19.0.0",
@@ -65,9 +65,9 @@
     "@eslint/js": "^9.38.0",
     "@heroicons/react": "^2.2.0",
     "@sudobility/components": "^4.0.134",
-    "@sudobility/design": "^1.1.17",
+    "@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",

package/dist/components/pages/app-privacy-policy-page.d.ts

@@ -1,137 +0,0 @@
-import React, { type ReactNode, type ComponentType } from 'react';
-/**
- * Configuration for a content section with a list
- */
-export interface PrivacySectionWithList {
-    /** Section title */
-    title: string;
-    /** Optional description before the list */
-    description?: string;
-    /** List items */
-    items: string[];
-}
-/**
- * Configuration for a content section with paragraph text
- */
-export interface PrivacySectionWithContent {
-    /** Section title */
-    title: string;
-    /** Paragraph content */
-    content: string;
-}
-/**
- * Configuration for a subsection (h3 level)
- */
-export interface PrivacySubsection {
-    /** Subsection title */
-    title: string;
-    /** List items */
-    items: string[];
-}
-/**
- * Contact information configuration
- */
-export interface PrivacyContactInfo {
-    /** Email label (e.g., "Email:") */
-    emailLabel: string;
-    /** Email address */
-    email: string;
-    /** Website label (e.g., "Website:") */
-    websiteLabel: string;
-    /** Website URL */
-    websiteUrl: string;
-    /** Data Protection Officer label */
-    dpoLabel: string;
-    /** DPO email */
-    dpoEmail: string;
-    /** GDPR section title */
-    gdprTitle: string;
-    /** GDPR section content */
-    gdprContent: string;
-}
-/**
- * All text content for the privacy policy page
- */
-export interface PrivacyPolicyPageText {
-    /** Page heading */
-    heading: string;
-    /** Last updated label */
-    lastUpdatedLabel: string;
-    /** Introduction section */
-    introduction: PrivacySectionWithContent;
-    /** Information We Collect section */
-    informationWeCollect: {
-        title: string;
-        youProvide: PrivacySubsection;
-        automatic: PrivacySubsection;
-    };
-    /** How We Use Your Information section */
-    howWeUse: PrivacySectionWithList;
-    /** Information Sharing section */
-    informationSharing: PrivacySectionWithList;
-    /** Data Security section */
-    dataSecurity: PrivacySectionWithList;
-    /** Data Retention section */
-    dataRetention: PrivacySectionWithContent;
-    /** Your Privacy Rights section */
-    privacyRights: PrivacySectionWithList;
-    /** Web3 Considerations section (optional) */
-    web3Considerations?: PrivacySectionWithList;
-    /** International Transfers section */
-    internationalTransfers: PrivacySectionWithContent;
-    /** Children's Privacy section */
-    childrensPrivacy: PrivacySectionWithContent;
-    /** Cookies section */
-    cookies: PrivacySectionWithContent;
-    /** Changes to Policy section */
-    changes: PrivacySectionWithContent;
-    /** Contact section */
-    contact: {
-        title: string;
-        description: string;
-        info: PrivacyContactInfo;
-    };
-}
-/**
- * Props for AppPrivacyPolicyPage component
- */
-export interface AppPrivacyPolicyPageProps {
-    /** All text content (must be provided by consumer) */
-    text: PrivacyPolicyPageText;
-    /** Current date for "last updated" display */
-    lastUpdatedDate?: string;
-    /** Optional wrapper component for the page layout */
-    PageWrapper?: ComponentType<{
-        children: ReactNode;
-    }>;
-    /** Optional className for the container */
-    className?: string;
-}
-/**
- * AppPrivacyPolicyPage - A reusable privacy policy page component
- *
- * Displays a comprehensive privacy policy with:
- * - Standard legal sections
- * - Optional Web3-specific considerations
- * - Contact information with GDPR notice
- *
- * All text content must be provided by the consumer app.
- *
- * @example
- * ```tsx
- * <AppPrivacyPolicyPage
- *   text={{
- *     heading: "Privacy Policy",
- *     lastUpdatedLabel: "Last updated",
- *     introduction: {
- *       title: "Introduction",
- *       content: "We respect your privacy..."
- *     },
- *     // ... other sections
- *   }}
- *   lastUpdatedDate="January 1, 2025"
- * />
- * ```
- */
-export declare const AppPrivacyPolicyPage: React.FC<AppPrivacyPolicyPageProps>;
-export default AppPrivacyPolicyPage;

package/dist/components/pages/app-terms-of-service-page.d.ts

@@ -1,107 +0,0 @@
-import React, { type ReactNode, type ComponentType } from 'react';
-/**
- * Configuration for a section with paragraph content
- */
-export interface TermsSectionWithContent {
-    /** Section title */
-    title: string;
-    /** Paragraph content (can include HTML for links) */
-    content: string;
-    /** Whether content contains HTML that should be rendered */
-    isHtml?: boolean;
-}
-/**
- * Configuration for a section with a list
- */
-export interface TermsSectionWithList {
-    /** Section title */
-    title: string;
-    /** Optional description before the list */
-    description?: string;
-    /** List items */
-    items: string[];
-    /** Optional additional content after the list */
-    additionalContent?: string;
-}
-/**
- * Contact information configuration
- */
-export interface TermsContactInfo {
-    /** Email label (e.g., "Email:") */
-    emailLabel: string;
-    /** Email address */
-    email: string;
-    /** Website label (e.g., "Website:") */
-    websiteLabel: string;
-    /** Website URL */
-    websiteUrl: string;
-}
-/**
- * All text content for the terms of service page
- */
-export interface TermsOfServicePageText {
-    /** Page title */
-    title: string;
-    /** Last updated text (with placeholder for date) */
-    lastUpdated: string;
-    /** All sections in order */
-    sections: Array<TermsSectionWithContent | TermsSectionWithList>;
-    /** Contact information */
-    contact: {
-        /** Section title */
-        title: string;
-        /** Section description */
-        description: string;
-        /** Whether description contains HTML */
-        isHtml?: boolean;
-        /** Contact details */
-        info: TermsContactInfo;
-    };
-}
-/**
- * Props for AppTermsOfServicePage component
- */
-export interface AppTermsOfServicePageProps {
-    /** All text content (must be provided by consumer) */
-    text: TermsOfServicePageText;
-    /** Current date for "last updated" display */
-    lastUpdatedDate?: string;
-    /** Optional wrapper component for the page layout */
-    PageWrapper?: ComponentType<{
-        children: ReactNode;
-    }>;
-    /** Optional className for the container */
-    className?: string;
-}
-/**
- * AppTermsOfServicePage - A reusable terms of service page component
- *
- * Displays a comprehensive terms of service document with:
- * - Flexible section structure (content or list-based)
- * - Contact information
- * - Support for HTML content in specific sections
- *
- * All text content must be provided by the consumer app.
- *
- * @example
- * ```tsx
- * <AppTermsOfServicePage
- *   text={{
- *     title: "Terms of Service",
- *     lastUpdated: "Last updated: {{date}}",
- *     sections: [
- *       { title: "Acceptance", content: "By using..." },
- *       { title: "User Responsibilities", items: ["Item 1", "Item 2"] }
- *     ],
- *     contact: {
- *       title: "Contact",
- *       description: "Questions?",
- *       info: { emailLabel: "Email:", email: "support@example.com", ... }
- *     }
- *   }}
- *   lastUpdatedDate="January 1, 2025"
- * />
- * ```
- */
-export declare const AppTermsOfServicePage: React.FC<AppTermsOfServicePageProps>;
-export default AppTermsOfServicePage;