@sudobility/building_blocks 0.0.21 → 0.0.22

package/README.md

@@ -1,6 +1,6 @@
 # @sudobility/building_blocks
 
-Higher-level shared UI building blocks for Sudobility apps. These components integrate with authentication, wallet connection, i18n, and routing.
+Higher-level shared UI building blocks for Sudobility apps. These components integrate with authentication, wallet connection, i18n, routing, and analytics tracking.
 
 ## Installation
 
@@ -11,18 +11,18 @@ bun add @sudobility/building_blocks
 ## Peer Dependencies
 
 Required:
-- `@sudobility/components`
-- `@sudobility/design`
-- `@heroicons/react`
+- `@sudobility/components` - Base UI components
+- `@sudobility/design` - Design tokens and styling
+- `@heroicons/react` - Icon library
 - `react` (^18.0.0 || ^19.0.0)
-- `class-variance-authority`
-- `clsx`
-- `tailwind-merge`
+- `class-variance-authority`, `clsx`, `tailwind-merge` - Styling utilities
 
 Optional (for specific features):
 - `@sudobility/auth-components` - For Firebase auth integration
 - `@sudobility/web3-components` - For wallet connection
 - `@sudobility/devops-components` - For status indicator
+- `@sudobility/subscription-components` - For pricing/subscription pages
+- `@sudobility/types` - For Theme, FontSize enums
 
 ## Components
 
@@ -137,6 +137,7 @@ import { SystemStatusIndicator } from '@sudobility/devops-components';
     { label: 'Privacy', href: '/privacy' },
     { label: 'Terms', href: '/terms' },
   ]}
+  onTrack={handleAnalytics}
   sticky
 />
 ```
@@ -172,6 +173,7 @@ import { AppFooterForHomePage } from '@sudobility/building_blocks';
   version="1.0.0"
   companyName="Sudobility Inc."
   description="Building the future of web3 communication"
+  onTrack={handleAnalytics}
 />
 ```
 
@@ -197,6 +199,112 @@ import { AppPageLayout, AppTopBarWithFirebaseAuth, AppFooter } from '@sudobility
 </AppPageLayout>
 ```
 
+### Settings Components
+
+#### GlobalSettingsPage
+Master-detail settings page with extensible sections.
+
+```tsx
+import { GlobalSettingsPage } from '@sudobility/building_blocks';
+
+<GlobalSettingsPage
+  theme={theme}
+  fontSize={fontSize}
+  onThemeChange={setTheme}
+  onFontSizeChange={setFontSize}
+  additionalSections={[
+    {
+      id: 'notifications',
+      icon: BellIcon,
+      label: 'Notifications',
+      description: 'Manage notification preferences',
+      content: <NotificationSettings />,
+    },
+  ]}
+  onTrack={handleAnalytics}
+/>
+```
+
+### Subscription Components
+
+#### AppPricingPage
+Public pricing page for displaying subscription options.
+
+```tsx
+import { AppPricingPage } from '@sudobility/building_blocks';
+
+<AppPricingPage
+  products={subscriptionProducts}
+  isAuthenticated={isLoggedIn}
+  hasActiveSubscription={hasSubscription}
+  currentProductIdentifier={currentPlan}
+  labels={pricingLabels}
+  formatters={pricingFormatters}
+  entitlementMap={packageToEntitlement}
+  entitlementLevels={entitlementHierarchy}
+  onPlanClick={(planId) => handlePlanSelection(planId)}
+  onFreePlanClick={() => navigate('/signup')}
+  onTrack={handleAnalytics}
+/>
+```
+
+### Page Components
+
+#### AppTextPage
+Markdown/HTML content page for static content.
+
+```tsx
+import { AppTextPage } from '@sudobility/building_blocks';
+
+<AppTextPage
+  title="Privacy Policy"
+  content={markdownContent}
+  lastUpdated="2024-01-01"
+/>
+```
+
+#### AppSitemapPage
+SEO-friendly sitemap page.
+
+```tsx
+import { AppSitemapPage } from '@sudobility/building_blocks';
+
+<AppSitemapPage
+  sections={sitemapSections}
+  LinkComponent={LocalizedLink}
+/>
+```
+
+## Analytics Tracking
+
+All major components support optional analytics tracking via the `onTrack` callback:
+
+```tsx
+import type { AnalyticsTrackingParams } from '@sudobility/building_blocks';
+
+const handleAnalytics = (params: AnalyticsTrackingParams) => {
+  // params.eventType: 'button_click' | 'link_click' | 'settings_change' | 'subscription_action'
+  // params.componentName: 'AppFooter' | 'GlobalSettingsPage' | 'AppPricingPage'
+  // params.label: 'footer_link_clicked' | 'theme_changed' | 'plan_clicked'
+  // params.params: { link_href, theme, plan_identifier, ... }
+
+  analytics.track(params.label, {
+    component: params.componentName,
+    ...params.params,
+  });
+};
+
+<AppFooter onTrack={handleAnalytics} {...props} />
+<GlobalSettingsPage onTrack={handleAnalytics} {...props} />
+<AppPricingPage onTrack={handleAnalytics} {...props} />
+```
+
+**Components with analytics support:**
+- `AppFooter` - tracks link clicks
+- `AppFooterForHomePage` - tracks link clicks with section info
+- `GlobalSettingsPage` - tracks theme/font changes, section navigation
+- `AppPricingPage` - tracks plan clicks, billing period changes
+
 ## Constants
 
 ### Default Languages
@@ -207,13 +315,47 @@ import { DEFAULT_LANGUAGES } from '@sudobility/building_blocks';
 // ['en', 'ar', 'de', 'es', 'fr', 'it', 'ja', 'ko', 'pt', 'ru', 'sv', 'th', 'uk', 'vi', 'zh', 'zh-hant']
 ```
 
+## TypeScript Types
+
+All props interfaces and utility types are exported:
+
+```tsx
+import type {
+  // Component Props
+  AppTopBarProps,
+  AppFooterProps,
+  AppFooterForHomePageProps,
+  GlobalSettingsPageProps,
+  AppPricingPageProps,
+
+  // Configuration Types
+  MenuItemConfig,
+  LogoConfig,
+  FooterLinkSection,
+  SocialLinksConfig,
+  StatusIndicatorConfig,
+  ShareConfig,
+
+  // Analytics
+  AnalyticsTrackingParams,
+  AnalyticsEventType,
+
+  // Layout
+  MaxWidth,
+  ContentPadding,
+  BackgroundVariant,
+} from '@sudobility/building_blocks';
+```
+
 ## Features
 
 - **Responsive**: All components support mobile with hamburger menu
 - **Dark Mode**: Full dark mode support via Tailwind CSS
 - **i18n Ready**: Language selector with 16 default languages
 - **Flexible Auth**: Support for Firebase auth or wallet connection
+- **Analytics Ready**: Optional tracking callbacks for all user interactions
 - **Customizable**: All components accept custom classNames and Link components
+- **Tree-shakeable**: ESM only, optimized for modern bundlers
 
 ## License
 

package/dist/components/footer/app-footer-for-home-page.d.ts

@@ -1,5 +1,5 @@
 import React, { type ComponentType } from 'react';
-import type { StatusIndicatorConfig, LinkComponentProps, FooterLinkSection as FooterLinkSectionConfig, SocialLinksConfig } from '../../types';
+import type { StatusIndicatorConfig, LinkComponentProps, FooterLinkSection as FooterLinkSectionConfig, SocialLinksConfig, AnalyticsTrackingParams } from '../../types';
 import type { SystemStatusIndicatorProps } from './app-footer';
 export interface AppFooterForHomePageProps {
     /** App logo configuration */
@@ -40,6 +40,8 @@ export interface AppFooterForHomePageProps {
     className?: string;
     /** Number of columns for link grid (default: auto based on section count) */
     gridColumns?: 2 | 3 | 4 | 5;
+    /** Optional analytics tracking callback */
+    onTrack?: (params: AnalyticsTrackingParams) => void;
 }
 /**
  * AppFooterForHomePage - Full footer for home/landing pages.

package/dist/components/footer/app-footer.d.ts

@@ -1,5 +1,5 @@
 import React, { type ComponentType } from 'react';
-import type { StatusIndicatorConfig, LinkComponentProps, FooterLinkItem } from '../../types';
+import type { StatusIndicatorConfig, LinkComponentProps, FooterLinkItem, AnalyticsTrackingParams } from '../../types';
 /**
  * Props for the SystemStatusIndicator component from @sudobility/devops-components.
  */
@@ -39,6 +39,8 @@ export interface AppFooterProps {
     isNetworkOnline?: boolean;
     /** Custom className */
     className?: string;
+    /** Optional analytics tracking callback */
+    onTrack?: (params: AnalyticsTrackingParams) => void;
 }
 /**
  * AppFooter - Compact footer for app pages.

package/dist/components/settings/global-settings-page.d.ts

@@ -1,5 +1,6 @@
 import React, { type ReactNode, type ComponentType } from 'react';
 import { Theme, FontSize } from './appearance-settings';
+import type { AnalyticsTrackingParams } from '../../types';
 /**
  * Configuration for a settings section in the navigation.
  */
@@ -54,6 +55,8 @@ export interface GlobalSettingsPageProps {
     className?: string;
     /** Whether to show the info box in appearance settings */
     showAppearanceInfoBox?: boolean;
+    /** Optional analytics tracking callback */
+    onTrack?: (params: AnalyticsTrackingParams) => void;
 }
 /**
  * GlobalSettingsPage - A reusable settings page with master-detail layout.

package/dist/components/subscription/AppPricingPage.d.ts

@@ -2,6 +2,7 @@
  * @fileoverview App Pricing Page
  * @description Public pricing page for displaying subscription options
  */
+import type { AnalyticsTrackingParams } from '../../types';
 /** Product from subscription provider */
 export interface PricingProduct {
     identifier: string;
@@ -76,6 +77,8 @@ export interface AppPricingPageProps {
     faqItems?: FAQItem[];
     /** Optional className for the container */
     className?: string;
+    /** Optional analytics tracking callback */
+    onTrack?: (params: AnalyticsTrackingParams) => void;
 }
 /**
  * Public pricing page for displaying subscription options.
@@ -83,4 +86,4 @@ export interface AppPricingPageProps {
  * - Authenticated on free: Free tile shows "Current Plan" badge (no CTA), paid tiles show "Upgrade"
  * - Authenticated with subscription: Current plan shows badge (no CTA), higher tiers show "Upgrade"
  */
-export declare function AppPricingPage({ products, isAuthenticated, hasActiveSubscription, currentProductIdentifier, labels, formatters, entitlementMap, entitlementLevels, onPlanClick, onFreePlanClick, faqItems, className, }: AppPricingPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppPricingPage({ products, isAuthenticated, hasActiveSubscription, currentProductIdentifier, labels, formatters, entitlementMap, entitlementLevels, onPlanClick, onFreePlanClick, faqItems, className, onTrack, }: AppPricingPageProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/subscription/AppSubscriptionsPage.d.ts

@@ -3,6 +3,7 @@
  * @description Page for managing app subscriptions and viewing rate limits
  */
 import type { RateLimitsConfigData } from '@sudobility/types';
+import type { AnalyticsTrackingParams } from '../../types';
 /** Product from subscription provider */
 export interface SubscriptionProduct {
     identifier: string;
@@ -26,8 +27,10 @@ export interface SubscriptionContextValue {
     currentSubscription: CurrentSubscription | null;
     isLoading: boolean;
     error: string | null;
-    purchase: (productId: string) => Promise<boolean>;
-    restore: () => Promise<boolean>;
+    /** Purchase a subscription product. subscriptionUserId identifies which user/entity the subscription is for. */
+    purchase: (productId: string, subscriptionUserId?: string) => Promise<boolean>;
+    /** Restore purchases. subscriptionUserId identifies which user/entity to restore for. */
+    restore: (subscriptionUserId?: string) => Promise<boolean>;
     clearError: () => void;
 }
 /** All localized labels for the subscription page */
@@ -107,8 +110,10 @@ export interface AppSubscriptionsPageProps {
     onError?: (title: string, message: string) => void;
     /** Called on warning */
     onWarning?: (title: string, message: string) => void;
+    /** Optional analytics tracking callback */
+    onTrack?: (params: AnalyticsTrackingParams) => void;
 }
 /**
  * Page for managing app subscriptions.
  */
-export declare function AppSubscriptionsPage({ subscription, rateLimitsConfig, labels, formatters, packageEntitlementMap, onPurchaseSuccess, onRestoreSuccess, onError, onWarning, }: AppSubscriptionsPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppSubscriptionsPage({ subscription, rateLimitsConfig, subscriptionUserId, labels, formatters, packageEntitlementMap, onPurchaseSuccess, onRestoreSuccess, onError, onWarning, onTrack, }: AppSubscriptionsPageProps): import("react/jsx-runtime").JSX.Element;