A Modern Approach to Loosely Coupled UI Components

1
export interface SdkServices {
2
  analytics: AnalyticsSdk
3
  experiments: ExperimentsSdk
4
  router: RouterSdk
5
  http: HttpSdk
6
  state: StateSdk
7
}

1
export interface AnalyticsSdk {
2
  /**
3
   * Track a custom event
4
   */
5
  track(event: string, properties?: Record<string, unknown>): void
6

7
  /**
8
   * Track a page view
9
   */
10
  trackPageView(page: string, properties?: Record<string, unknown>): void
11

12
  /**
13
   * Track component impression (visibility)
14
   */
15
  trackImpression(componentId: string, properties?: Record<string, unknown>): void
16

17
  /**
18
   * Identify a user for analytics
19
   */
20
  identify(userId: string, traits?: Record<string, unknown>): void
21
}

1
export interface ExperimentsSdk {
2
  /**
3
   * Get the variant for an experiment
4
   * @returns variant name or null if not enrolled
5
   */
6
  getVariant(experimentId: string): string | null
7

8
  /**
9
   * Check if a feature flag is enabled
10
   */
11
  isFeatureEnabled(featureFlag: string): boolean
12

13
  /**
14
   * Track that user was exposed to an experiment
15
   */
16
  trackExposure(experimentId: string, variant: string): void
17
}

1
export interface RouterSdk {
2
  /**
3
   * Navigate to a new URL (adds to history)
4
   */
5
  push(path: string): void
6

7
  /**
8
   * Replace current URL (no history entry)
9
   */
10
  replace(path: string): void
11

12
  /**
13
   * Go back in history
14
   */
15
  back(): void
16

17
  /**
18
   * Prefetch a route for faster navigation
19
   */
20
  prefetch(path: string): void
21

22
  /**
23
   * Current pathname
24
   */
25
  pathname: string
26

27
  /**
28
   * Current query parameters
29
   */
30
  query: Record<string, string | string[]>
31
}

1
export interface HttpSdk {
2
  get<T>(url: string, options?: RequestOptions): Promise<T>
3
  post<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>
4
  put<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>
5
  delete<T>(url: string, options?: RequestOptions): Promise<T>
6
}
7

8
export interface RequestOptions {
9
  headers?: Record<string, string>
10
  signal?: AbortSignal
11
  cache?: RequestCache
12
}

1
export interface StateSdk {
2
  /**
3
   * Get current state for a key
4
   */
5
  getState<T>(key: string): T | undefined
6

7
  /**
8
   * Set state for a key
9
   */
10
  setState<T>(key: string, value: T): void
11

12
  /**
13
   * Subscribe to state changes
14
   * @returns unsubscribe function
15
   */
16
  subscribe<T>(key: string, callback: (value: T) => void): () => void
17
}

1
import { createContext, useContext, type FC, type PropsWithChildren } from 'react';
2
import type { SdkServices } from './sdk.types';
3

4
const SdkContext = createContext<SdkServices | null>(null);
5

6
export const useSdk = (): SdkServices => {
7
  const ctx = useContext(SdkContext);
8
  if (!ctx) {
9
    throw new Error('useSdk must be used within SdkProvider');
10
  }
11
  return ctx;
12
};
13

14
export interface SdkProviderProps {
15
  services: SdkServices;
16
}
17

18
export const SdkProvider: FC<PropsWithChildren<SdkProviderProps>> = ({
19
  children,
20
  services,
21
}) => (
22
  <SdkContext.Provider value={services}>
23
    {children}
24
  </SdkContext.Provider>
25
);

1
import { useSdk } from "../core/sdk.provider"
2
import type { AnalyticsSdk } from "./analytics.types"
3

4
export const useAnalytics = (): AnalyticsSdk => {
5
  const sdk = useSdk()
6
  return sdk.analytics
7
}

1
import { useEffect } from "react"
2
import { useSdk } from "../core/sdk.provider"
3

4
export const useExperiment = (experimentId: string): string | null => {
5
  const { experiments } = useSdk()
6
  const variant = experiments.getVariant(experimentId)
7

8
  useEffect(() => {
9
    if (variant !== null) {
10
      experiments.trackExposure(experimentId, variant)
11
    }
12
  }, [experimentId, variant, experiments])
13

14
  return variant
15
}
16

17
export const useFeatureFlag = (flagName: string): boolean => {
18
  const { experiments } = useSdk()
19
  return experiments.isFeatureEnabled(flagName)
20
}

1
import type { FC, PropsWithChildren } from "react"
2

3
/**
4
 * A Block component - business-aware building block
5
 */
6
export type BlockComponent<TProps = object> = FC<TProps>
7

8
/**
9
 * A Block View - pure presentational, no side effects
10
 */
11
export type BlockView<TProps = object> = FC<TProps>
12

13
/**
14
 * Block with children
15
 */
16
export type BlockWithChildren<TProps = object> = FC<PropsWithChildren<TProps>>
17

18
/**
19
 * Standard hook result for data-fetching blocks
20
 */
21
export interface BlockHookResult<TData, TActions = object> {
22
  data: TData | null
23
  isLoading: boolean
24
  error: Error | null
25
  actions: TActions
26
}
27

28
/**
29
 * Props for analytics tracking (optional on all blocks)
30
 */
31
export interface TrackingProps {
32
  /** Unique identifier for analytics */
33
  trackingId?: string
34
  /** Additional tracking data */
35
  trackingData?: Record<string, unknown>
36
}

1
import type { ComponentType, ReactNode } from "react"
2

3
/**
4
 * Base BFF widget payload structure
5
 */
6
export interface WidgetPayload<TData = unknown> {
7
  /** Unique widget instance ID */
8
  id: string
9
  /** Widget type identifier (matches registry key) */
10
  type: string
11
  /** Widget-specific data from BFF */
12
  data: TData
13
  /** Optional pagination info */
14
  pagination?: WidgetPagination
15
}
16

17
export interface WidgetPagination {
18
  cursor: string | null
19
  hasMore: boolean
20
  pageSize: number
21
}
22

23
/**
24
 * Widget component type
25
 */
26
export type WidgetComponent<TData = unknown> = ComponentType<{
27
  payload: WidgetPayload<TData>
28
}>
29

30
/**
31
 * Widget view - pure render layer
32
 */
33
export type WidgetView<TProps = object> = ComponentType<TProps>
34

35
/**
36
 * Widget hook result with pagination support
37
 */
38
export interface WidgetHookResult<TData> {
39
  data: TData | null
40
  isLoading: boolean
41
  error: Error | null
42
  pagination: {
43
    loadMore: () => Promise<void>
44
    hasMore: boolean
45
    isLoadingMore: boolean
46
  } | null
47
}

1
import type { ComponentType, ReactNode } from "react"
2
import type { WidgetPayload } from "@widgets/types"
3

4
/**
5
 * Configuration for a registered widget
6
 */
7
export interface WidgetConfig {
8
  /** The widget component to render */
9
  component: ComponentType<{ payload: WidgetPayload }>
10

11
  /** Optional custom error boundary */
12
  errorBoundary?: ComponentType<{
13
    children: ReactNode
14
    fallback?: ReactNode
15
    onError?: (error: Error) => void
16
  }>
17

18
  /** Optional suspense fallback (loading state) */
19
  suspenseFallback?: ReactNode
20

21
  /** Optional skeleton component for loading */
22
  skeleton?: ComponentType
23

24
  /** Whether to wrap in error boundary (default: true) */
25
  withErrorBoundary?: boolean
26

27
  /** Whether to wrap in suspense (default: true) */
28
  withSuspense?: boolean
29
}
30

31
/**
32
 * Widget registry - maps widget type IDs to configurations
33
 */
34
export type WidgetRegistry = Record<string, WidgetConfig>

1
import type { TrackingProps, BlockHookResult } from "../blocks.types"
2

3
export interface AddToCartButtonProps extends TrackingProps {
4
  sku: string
5
  quantity?: number
6
  variant?: "primary" | "secondary" | "ghost"
7
  size?: "sm" | "md" | "lg"
8
  disabled?: boolean
9
  onSuccess?: () => void
10
  onError?: (error: Error) => void
11
}
12

13
export interface AddToCartViewProps {
14
  onAdd: () => void
15
  isLoading: boolean
16
  error: string | null
17
  variant: "primary" | "secondary" | "ghost"
18
  size: "sm" | "md" | "lg"
19
  disabled: boolean
20
}
21

22
export interface AddToCartActions {
23
  addToCart: () => Promise<void>
24
  reset: () => void
25
}
26

27
export type UseAddToCartResult = BlockHookResult<{ cartId: string }, AddToCartActions>

1
import { useState, useCallback } from "react"
2
import { useAnalytics, useHttpClient } from "@sdk"
3
import type { UseAddToCartResult } from "./add-to-cart-button.types"
4

5
export const useAddToCart = (
6
  sku: string,
7
  quantity: number = 1,
8
  callbacks?: { onSuccess?: () => void; onError?: (error: Error) => void },
9
): UseAddToCartResult => {
10
  const analytics = useAnalytics()
11
  const http = useHttpClient()
12

13
  const [isLoading, setIsLoading] = useState(false)
14
  const [error, setError] = useState<Error | null>(null)
15
  const [data, setData] = useState<{ cartId: string } | null>(null)
16

17
  const addToCart = useCallback(async (): Promise<void> => {
18
    setIsLoading(true)
19
    setError(null)
20

21
    try {
22
      const response = await http.post<{ cartId: string }>("/api/cart/add", {
23
        sku,
24
        quantity,
25
      })
26

27
      setData(response)
28
      analytics.track("add_to_cart", { sku, quantity, cartId: response.cartId })
29
      callbacks?.onSuccess?.()
30
    } catch (e) {
31
      const error = e instanceof Error ? e : new Error("Failed to add to cart")
32
      setError(error)
33
      analytics.track("add_to_cart_error", { sku, error: error.message })
34
      callbacks?.onError?.(error)
35
      throw error
36
    } finally {
37
      setIsLoading(false)
38
    }
39
  }, [sku, quantity, http, analytics, callbacks])
40

41
  const reset = useCallback((): void => {
42
    setError(null)
43
    setData(null)
44
  }, [])
45

46
  return {
47
    data,
48
    isLoading,
49
    error,
50
    actions: { addToCart, reset },
51
  }
52
}

1
import type { FC } from 'react';
2
import { Button, Spinner, Text, Stack } from '@company-name/design-system';
3
import type { AddToCartViewProps } from './add-to-cart-button.types';
4

5
export const AddToCartButtonView: FC<AddToCartViewProps> = ({
6
  onAdd,
7
  isLoading,
8
  error,
9
  variant,
10
  size,
11
  disabled,
12
}) => (
13
  <Stack gap="xs">
14
    <Button
15
      variant={variant}
16
      size={size}
17
      onClick={onAdd}
18
      disabled={disabled || isLoading}
19
      aria-busy={isLoading}
20
      aria-describedby={error ? 'add-to-cart-error' : undefined}
21
    >
22
      {isLoading ? (
23
        <>
24
          <Spinner size="sm" aria-hidden />
25
          <span>Adding...</span>
26
        </>
27
      ) : (
28
        'Add to Cart'
29
      )}
30
    </Button>
31

32
    {error && (
33
      <Text id="add-to-cart-error" color="error" size="sm" role="alert">
34
        {error}
35
      </Text>
36
    )}
37
  </Stack>
38
);

1
import type { FC } from 'react';
2
import { useAddToCart } from './add-to-cart-button.hooks';
3
import { AddToCartButtonView } from './add-to-cart-button.view';
4
import type { AddToCartButtonProps } from './add-to-cart-button.types';
5

6
export const AddToCartButton: FC<AddToCartButtonProps> = ({
7
  sku,
8
  quantity = 1,
9
  variant = 'primary',
10
  size = 'md',
11
  disabled = false,
12
  onSuccess,
13
  onError,
14
}) => {
15
  const { isLoading, error, actions } = useAddToCart(sku, quantity, {
16
    onSuccess,
17
    onError
18
  });
19

20
  return (
21
    <AddToCartButtonView
22
      onAdd={actions.addToCart}
23
      isLoading={isLoading}
24
      error={error?.message ?? null}
25
      variant={variant}
26
      size={size}
27
      disabled={disabled}
28
    />
29
  );
30
};

1
export { AddToCartButton } from "./add-to-cart-button.component"
2
export { AddToCartButtonView } from "./add-to-cart-button.view"
3
export { useAddToCart } from "./add-to-cart-button.hooks"
4
export type { AddToCartButtonProps, AddToCartViewProps } from "./add-to-cart-button.types"

1
import type { WidgetPayload, WidgetHookResult } from "../types"
2

3
export interface ProductCarouselData {
4
  title: string
5
  subtitle?: string
6
  products: ProductItem[]
7
}
8

9
export interface ProductItem {
10
  id: string
11
  sku: string
12
  name: string
13
  price: number
14
  originalPrice?: number
15
  imageUrl: string
16
  rating?: number
17
  reviewCount?: number
18
}
19

20
export type ProductCarouselPayload = WidgetPayload<ProductCarouselData>
21

22
export interface ProductCarouselViewProps {
23
  title: string
24
  subtitle?: string
25
  products: ProductItem[]
26
  onLoadMore?: () => void
27
  hasMore: boolean
28
  isLoadingMore: boolean
29
}
30

31
export type UseProductCarouselResult = WidgetHookResult<ProductCarouselData>

1
import { useState, useCallback, useEffect } from "react"
2
import { useAnalytics, useHttpClient } from "@sdk"
3
import type { ProductCarouselPayload, UseProductCarouselResult } from "./product-carousel.types"
4

5
export const useProductCarousel = (payload: ProductCarouselPayload): UseProductCarouselResult => {
6
  const analytics = useAnalytics()
7
  const http = useHttpClient()
8

9
  const [data, setData] = useState(payload.data)
10
  const [isLoading, setIsLoading] = useState(false)
11
  const [isLoadingMore, setIsLoadingMore] = useState(false)
12
  const [error, setError] = useState<Error | null>(null)
13
  const [cursor, setCursor] = useState(payload.pagination?.cursor ?? null)
14
  const [hasMore, setHasMore] = useState(payload.pagination?.hasMore ?? false)
15

16
  // Track impression when widget becomes visible
17
  useEffect(() => {
18
    analytics.trackImpression(payload.id, {
19
      widgetType: payload.type,
20
      productCount: data.products.length,
21
    })
22
  }, [payload.id, payload.type, analytics, data.products.length])
23

24
  const loadMore = useCallback(async (): Promise<void> => {
25
    if (!hasMore || isLoadingMore) return
26

27
    setIsLoadingMore(true)
28

29
    try {
30
      const response = await http.get<{
31
        products: ProductItem[]
32
        cursor: string | null
33
        hasMore: boolean
34
      }>(`/api/widgets/${payload.id}/paginate?cursor=${cursor}`)
35

36
      setData((prev) => ({
37
        ...prev,
38
        products: [...prev.products, ...response.products],
39
      }))
40
      setCursor(response.cursor)
41
      setHasMore(response.hasMore)
42

43
      analytics.track("widget_load_more", {
44
        widgetId: payload.id,
45
        itemsLoaded: response.products.length,
46
      })
47
    } catch (e) {
48
      setError(e instanceof Error ? e : new Error("Failed to load more"))
49
    } finally {
50
      setIsLoadingMore(false)
51
    }
52
  }, [payload.id, cursor, hasMore, isLoadingMore, http, analytics])
53

54
  return {
55
    data,
56
    isLoading,
57
    error,
58
    pagination: payload.pagination ? { loadMore, hasMore, isLoadingMore } : null,
59
  }
60
}

1
import type { FC } from 'react';
2
import { Section, Carousel, Button, Skeleton } from '@company-name/design-system';
3
import { ProductCard } from '@blocks/product-card';
4
import type { ProductCarouselViewProps } from './product-carousel.types';
5

6
export const ProductCarouselView: FC<ProductCarouselViewProps> = ({
7
  title,
8
  subtitle,
9
  products,
10
  onLoadMore,
11
  hasMore,
12
  isLoadingMore,
13
}) => (
14
  <Section>
15
    <Section.Header>
16
      <Section.Title>{title}</Section.Title>
17
      {subtitle && <Section.Subtitle>{subtitle}</Section.Subtitle>}
18
    </Section.Header>
19

20
    <Carousel itemsPerView={{ base: 2, md: 3, lg: 4 }}>
21
      {products.map((product) => (
22
        <Carousel.Item key={product.id}>
23
          <ProductCard
24
            productId={product.id}
25
            sku={product.sku}
26
            name={product.name}
27
            price={product.price}
28
            originalPrice={product.originalPrice}
29
            imageUrl={product.imageUrl}
30
            rating={product.rating}
31
            reviewCount={product.reviewCount}
32
          />
33
        </Carousel.Item>
34
      ))}
35

36
      {isLoadingMore && (
37
        <Carousel.Item>
38
          <Skeleton variant="product-card" />
39
        </Carousel.Item>
40
      )}
41
    </Carousel>
42

43
    {hasMore && onLoadMore && (
44
      <Section.Footer>
45
        <Button
46
          variant="ghost"
47
          onClick={onLoadMore}
48
          loading={isLoadingMore}
49
        >
50
          Load More
51
        </Button>
52
      </Section.Footer>
53
    )}
54
  </Section>
55
);

1
import type { FC } from 'react';
2
import { useProductCarousel } from './product-carousel.hooks';
3
import { ProductCarouselView } from './product-carousel.view';
4
import type { ProductCarouselPayload } from './product-carousel.types';
5

6
interface ProductCarouselWidgetProps {
7
  payload: ProductCarouselPayload;
8
}
9

10
export const ProductCarouselWidget: FC<ProductCarouselWidgetProps> = ({ payload }) => {
11
  const { data, error, pagination } = useProductCarousel(payload);
12

13
  if (error) {
14
    // Let error boundary handle this
15
    throw error;
16
  }
17

18
  if (!data) {
19
    return null;
20
  }
21

22
  return (
23
    <ProductCarouselView
24
      title={data.title}
25
      subtitle={data.subtitle}
26
      products={data.products}
27
      onLoadMore={pagination?.loadMore}
28
      hasMore={pagination?.hasMore ?? false}
29
      isLoadingMore={pagination?.isLoadingMore ?? false}
30
    />
31
  );
32
};

1
import { lazy } from "react"
2
import type { WidgetRegistry } from "./registry.types"
3

4
export const homeRegistry: WidgetRegistry = {
5
  HERO_BANNER: {
6
    component: lazy(() => import("@widgets/hero-banner").then((m) => ({ default: m.HeroBannerWidget }))),
7
    withErrorBoundary: true,
8
    withSuspense: true,
9
  },
10

11
  PRODUCT_CAROUSEL: {
12
    component: lazy(() => import("@widgets/product-carousel").then((m) => ({ default: m.ProductCarouselWidget }))),
13
    withErrorBoundary: true,
14
    withSuspense: true,
15
  },
16

17
  CATEGORY_GRID: {
18
    component: lazy(() => import("@widgets/category-grid").then((m) => ({ default: m.CategoryGridWidget }))),
19
  },
20

21
  PROMOTIONAL_BANNER: {
22
    component: lazy(() => import("@widgets/promotional-banner").then((m) => ({ default: m.PromotionalBannerWidget }))),
23
  },
24

25
  NEWSLETTER_SIGNUP: {
26
    component: lazy(() => import("@widgets/newsletter-signup").then((m) => ({ default: m.NewsletterSignupWidget }))),
27
    withErrorBoundary: false, // Non-critical widget
28
  },
29
}