@nuskin/react-mysite-elements 1.3.0 → 1.4.0-po-dashboard.1

package/README.md

@@ -123,6 +123,100 @@ The main hero component for Mysite pages with advanced scroll behavior and respo
 [];
 ```
 
+### Shopping Dashboard Suite
+
+The Shopping Dashboard provides a complete analytics experience with overview widgets,
+full-detail views, and stateful in-page navigation.
+
+#### Highlights
+
+- Dashboard overview with stats cards and 4 widgets (Top Products, Sign-ups, Conversion Rate, Top Categories)
+- Full views for each widget with filtering, sorting, and pagination
+- History-state navigation between dashboard and full views (back/forward/refresh aware)
+- Loading skeletons and explicit empty/error states
+- Translation-ready text (`getTranslation` + key catalog)
+- Accessibility and test automation support with stable `data-testid` selectors
+- Responsive mobile/desktop rendering with performance-focused optimizations
+
+#### Main Exports
+
+- `ShoppingDashboard`
+- `MysiteDashboardWithNavigation`
+- `ProductOfferDashboard`
+- `PoDashboardWithNavigation`
+- `ProductsFullView`
+- `SignupsFullView`
+- `ConversionRateFullView`
+- `CategoriesFullView`
+- `TopPerformingOffersFullView`
+- `StatsCard`, `DashboardHeader`, `WidgetMenu`
+- `TopSellingProductsList`, `SignupsChart`, `ConversionRateChart`, `TopCategoriesPieChart`, `TopPerformingOffersPieChart`
+
+#### Quick Usage
+
+```tsx
+import React, { useState } from 'react';
+import {
+    MysiteDashboardWithNavigation,
+    mockStats,
+    mockTopProducts,
+    mockConversionData,
+    mockSignupData,
+    mockCategories,
+    mockOrders,
+    mockSignupDetails,
+} from '@nuskin/react-mysite-elements';
+
+export default function DashboardExample() {
+    const [dateRange, setDateRange] = useState('last30days');
+    const [market, setMarket] = useState('all');
+
+    return (
+        <MysiteDashboardWithNavigation
+            stats={mockStats}
+            topProducts={mockTopProducts}
+            conversionData={mockConversionData}
+            signupData={mockSignupData}
+            categories={mockCategories}
+            orders={mockOrders}
+            signups={mockSignupDetails}
+            dateRange={dateRange}
+            market={market}
+            onDateRangeChange={setDateRange}
+            onMarketChange={setMarket}
+        />
+    );
+}
+```
+
+#### Storybook
+
+Shopping Dashboard stories are available under the `ShoppingDashboard` group, including
+loading, error, navigation, and full-view scenarios.
+
+#### Product Offer Dashboard
+
+```tsx
+import {
+    PoDashboardWithNavigation,
+    mockProductOfferStats,
+    mockTopProducts,
+    mockConversionData,
+    mockTopOffers,
+} from '@nuskin/react-mysite-elements';
+
+export default function ProductOfferDashboardExample() {
+    return (
+        <PoDashboardWithNavigation
+            stats={mockProductOfferStats}
+            topProducts={mockTopProducts}
+            conversionData={mockConversionData}
+            topOffers={mockTopOffers}
+        />
+    );
+}
+```
+
 ## ✨ Advanced Features
 
 ### Intelligent Scroll Behavior
@@ -250,6 +344,36 @@ The component automatically detects and integrates with Nu Skin's external heade
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### Constitution Compliance (Required)
+
+All UI contributions must follow the repository constitution in
+`.specify/memory/constitution.md`.
+
+Core non-negotiable rules:
+
+- No inline CSS in production components (`style={{}}`, inline `sx`, runtime `.style` mutation)
+- Styled component definitions must live in dedicated `*.styled.tsx` files, not inside component files
+- No hardcoded user-visible strings in component code (use translation keys)
+- Accessibility-first implementation (ADA/WCAG aligned)
+- Mobile and desktop viewport validation for changed flows
+- Stable `data-testid` selectors for critical interactions
+
+PR validation checklist:
+
+- [ ] UI styles are in stylesheet/styled-component files only
+- [ ] Styled components are defined in `*.styled.tsx` files, not inline in component files
+- [ ] All user-facing text is sourced from translation files
+- [ ] Keyboard and semantic accessibility checks were completed
+- [ ] Mobile and desktop behavior was validated
+- [ ] Critical interactive elements include `data-testid`
+
+Recommended verification commands:
+
+```bash
+npx jest --testPathPattern="shopping-dashboard" --no-coverage
+npx tsc --noEmit --project tsconfig.json
+```
+
 ### Commit Convention
 
 We use [Conventional Commits](https://www.conventionalcommits.org/) for semantic versioning:

package/dist/common/icon/icons/SocialMediaIcons.styled.d.ts

@@ -0,0 +1,5 @@
+export declare const StyledButton: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void | import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material").Theme> & {
+    brandColor: string;
+}, {}, {}>;

package/dist/common/index.d.ts

@@ -2,3 +2,4 @@ export * from './card';
 export * from './carousel';
 export * from './headers';
 export * from './Nav-Category-Navigation';
+export * from './shopping-dashboard';

package/dist/common/shopping-dashboard/MysiteDashboardWithNavigation.d.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import type { DashboardStats, TopProduct, ConversionDataPoint, SignupDataPoint, CategoryRevenue, OrderHistory, SignupDetail, DateRangeOption, MarketOption, ProductSortOption, SignupViewOption, ConversionFilterOption, CategorySortOption, FullViewWidgetType } from './types.d';
+export type MysiteDashboardView = 'dashboard' | FullViewWidgetType;
+export interface MysiteDashboardHistoryLocation {
+    readonly pathname?: string;
+    readonly search?: string;
+    readonly hash?: string;
+    readonly state?: unknown;
+}
+export interface MysiteDashboardHistoryAdapter {
+    readonly location?: MysiteDashboardHistoryLocation;
+    push(location: MysiteDashboardHistoryLocation): void;
+    replace(location: MysiteDashboardHistoryLocation): void;
+    goBack(): void;
+    listen(listener: (location: MysiteDashboardHistoryLocation, action: string) => void): () => void;
+}
+export interface MysiteDashboardWithNavigationProps {
+    readonly stats?: DashboardStats | null;
+    readonly topProducts?: TopProduct[];
+    readonly conversionData?: ConversionDataPoint[];
+    readonly signupData?: SignupDataPoint[];
+    readonly categories?: CategoryRevenue[];
+    readonly orders?: OrderHistory[];
+    readonly signups?: SignupDetail[];
+    readonly isLoading?: boolean;
+    readonly error?: string | null;
+    readonly shopTitle?: string;
+    readonly className?: string;
+    readonly initialDateRange?: DateRangeOption;
+    readonly initialMarket?: MarketOption;
+    readonly initialProductSort?: ProductSortOption;
+    readonly initialSignupView?: SignupViewOption;
+    readonly initialConversionFilter?: ConversionFilterOption;
+    readonly initialCategorySort?: CategorySortOption;
+    readonly historyAdapter?: MysiteDashboardHistoryAdapter;
+    readonly historyStateKey?: string;
+    readonly resetToDashboardOnMount?: boolean;
+    readonly onDateRangeChange?: (range: DateRangeOption) => void;
+    readonly onMarketChange?: (market: MarketOption) => void;
+    readonly onProductSortChange?: (sort: ProductSortOption) => void;
+    readonly onSignupViewChange?: (view: SignupViewOption) => void;
+    readonly onConversionFilterChange?: (filter: ConversionFilterOption) => void;
+    readonly onCategorySortChange?: (sort: CategorySortOption) => void;
+    readonly onViewChange?: (view: MysiteDashboardView) => void;
+}
+export declare const MysiteDashboardWithNavigation: React.FC<MysiteDashboardWithNavigationProps>;
+export default MysiteDashboardWithNavigation;

package/dist/common/shopping-dashboard/PoDashboardWithNavigation.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { PoDashboardWithNavigationProps } from './types.d';
+/**
+ * PoDashboardWithNavigation
+ *
+ * Stateful navigation wrapper for the Product Offer Dashboard.
+ * Manages dashboard/full-view switching with browser history integration,
+ * filter state ownership, and back navigation.
+ *
+ * Follows the same pattern as MysiteDashboardWithNavigation but for the
+ * Product Offer Dashboard with reduced view types (no signups/categories).
+ */
+export declare const PoDashboardWithNavigation: React.FC<PoDashboardWithNavigationProps>;
+export default PoDashboardWithNavigation;

package/dist/common/shopping-dashboard/ProductOfferDashboard.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { ProductOfferDashboardProps } from './types.d';
+/**
+ * ProductOfferDashboard Main Container Component
+ *
+ * Orchestrates all dashboard widgets for the Product Offer Performance view.
+ * Pure presentational - receives all data via props.
+ * The consuming application is responsible for data fetching and state management.
+ *
+ * Layout (desktop):
+ *   - Top row: Conversion Rate chart (left) | Total Revenue + Offers Purchased stacked (right)
+ *   - Bottom row: Top Selling Products (left) | Top Performing Offers donut (right)
+ */
+export declare const ProductOfferDashboard: React.FC<ProductOfferDashboardProps>;
+export default ProductOfferDashboard;

package/dist/common/shopping-dashboard/ProductOfferDashboard.styled.d.ts

@@ -0,0 +1,20 @@
+export declare const PoDashboardContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const TopChartsRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const StatsCardStack: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const BottomChartsRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const ErrorContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/common/shopping-dashboard/ShoppingDashboard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { DashboardStats, TopProduct, ConversionDataPoint, SignupDataPoint, CategoryRevenue, DateRangeOption, MarketOption, ProductSortOption, SignupViewOption, ConversionFilterOption, CategorySortOption } from './types.d';
+export interface ShoppingDashboardProps {
+    readonly stats?: DashboardStats | null;
+    readonly topProducts?: TopProduct[];
+    readonly conversionData?: ConversionDataPoint[];
+    readonly signupData?: SignupDataPoint[];
+    readonly categories?: CategoryRevenue[];
+    readonly isLoading?: boolean;
+    readonly error?: string | null;
+    readonly shopTitle?: string;
+    readonly className?: string;
+    readonly dateRange?: DateRangeOption;
+    readonly market?: MarketOption;
+    readonly productSort?: ProductSortOption;
+    readonly signupView?: SignupViewOption;
+    readonly conversionFilter?: ConversionFilterOption;
+    readonly categorySort?: CategorySortOption;
+    readonly onDateRangeChange?: (range: DateRangeOption) => void;
+    readonly onMarketChange?: (market: MarketOption) => void;
+    readonly onProductSortChange?: (sort: ProductSortOption) => void;
+    readonly onSignupViewChange?: (view: SignupViewOption) => void;
+    readonly onConversionFilterChange?: (filter: ConversionFilterOption) => void;
+    readonly onCategorySortChange?: (sort: CategorySortOption) => void;
+    readonly onProductsTitleClick?: () => void;
+    readonly onConversionTitleClick?: () => void;
+    readonly onSignupsTitleClick?: () => void;
+    readonly onCategoriesToTitleClick?: () => void;
+}
+/**
+ * ShoppingDashboard Main Container Component
+ *
+ * Orchestrates all dashboard widgets. Pure presentational - receives all data via props.
+ * The consuming application is responsible for data fetching and state management.
+ */
+export declare const ShoppingDashboard: React.FC<ShoppingDashboardProps>;
+export default ShoppingDashboard;

package/dist/common/shopping-dashboard/ShoppingDashboard.styled.d.ts

@@ -0,0 +1,20 @@
+export declare const DashboardContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const StatsRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const WidgetContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const TwoColumnGrid: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const ErrorContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/common/shopping-dashboard/TranslationKeys/ProductOfferDashboardTranslationKeys.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Translation Keys for the Product Offer Dashboard
+ *
+ * All user-visible strings must use these keys with fallback text.
+ * Follow the same { key, fallback } pattern as ShoppingDashboardTranslationKeys.
+ */
+type TranslationEntry = {
+    readonly key: string;
+    readonly fallback: string;
+};
+export declare const ProductOfferDashboardTranslationKeys: {
+    readonly title: {
+        readonly key: "productOfferDashboard.title";
+        readonly fallback: "Performance Overview";
+    };
+    readonly error: {
+        readonly key: "productOfferDashboard.error";
+        readonly fallback: "Failed to load dashboard data. Please try again.";
+    };
+    readonly stats: {
+        readonly revenue: {
+            readonly key: "productOfferDashboard.stats.revenue";
+            readonly fallback: "Total Revenue";
+        };
+        readonly offersPurchased: {
+            readonly key: "productOfferDashboard.stats.offersPurchased";
+            readonly fallback: "Offers Purchased";
+        };
+        readonly conversionRate: {
+            readonly key: "productOfferDashboard.stats.conversionRate";
+            readonly fallback: "Conversion Rate";
+        };
+        readonly trendUp: {
+            readonly key: "productOfferDashboard.stats.trendUp";
+            readonly fallback: "Trending up";
+        };
+        readonly trendDown: {
+            readonly key: "productOfferDashboard.stats.trendDown";
+            readonly fallback: "Trending down";
+        };
+        readonly trendNeutral: {
+            readonly key: "productOfferDashboard.stats.trendNeutral";
+            readonly fallback: "No change";
+        };
+        readonly comparedTo: {
+            readonly key: "productOfferDashboard.stats.comparedTo";
+            readonly fallback: "compared to this time last month";
+        };
+    };
+    readonly filter: {
+        readonly dateRange: {
+            readonly label: {
+                readonly key: "productOfferDashboard.filter.dateRange.label";
+                readonly fallback: "Date Range";
+            };
+            readonly last7days: {
+                readonly key: "productOfferDashboard.filter.dateRange.last7days";
+                readonly fallback: "Last 7 Days";
+            };
+            readonly last30days: {
+                readonly key: "productOfferDashboard.filter.dateRange.last30days";
+                readonly fallback: "Last 30 Days";
+            };
+            readonly last90days: {
+                readonly key: "productOfferDashboard.filter.dateRange.last90days";
+                readonly fallback: "Last 90 Days";
+            };
+            readonly thisMonth: {
+                readonly key: "productOfferDashboard.filter.dateRange.thisMonth";
+                readonly fallback: "This Month";
+            };
+        };
+        readonly market: {
+            readonly label: {
+                readonly key: "productOfferDashboard.filter.market.label";
+                readonly fallback: "Market";
+            };
+            readonly all: {
+                readonly key: "productOfferDashboard.filter.market.all";
+                readonly fallback: "All Markets";
+            };
+        };
+        readonly offerSort: {
+            readonly byRevenue: {
+                readonly key: "productOfferDashboard.filter.offerSort.byRevenue";
+                readonly fallback: "Revenue";
+            };
+            readonly byUnits: {
+                readonly key: "productOfferDashboard.filter.offerSort.byUnits";
+                readonly fallback: "Units";
+            };
+        };
+        readonly productSort: {
+            readonly byUnits: {
+                readonly key: "productOfferDashboard.filter.productSort.byUnits";
+                readonly fallback: "Units";
+            };
+            readonly byRevenue: {
+                readonly key: "productOfferDashboard.filter.productSort.byRevenue";
+                readonly fallback: "Revenue";
+            };
+            readonly byVolume: {
+                readonly key: "productOfferDashboard.filter.productSort.byVolume";
+                readonly fallback: "Volume";
+            };
+        };
+        readonly conversionFilter: {
+            readonly overall: {
+                readonly key: "productOfferDashboard.filter.conversionFilter.overall";
+                readonly fallback: "Overall";
+            };
+        };
+    };
+    readonly widget: {
+        readonly topProducts: {
+            readonly title: {
+                readonly key: "productOfferDashboard.widget.topProducts.title";
+                readonly fallback: "Top Selling Products";
+            };
+            readonly emptyState: {
+                readonly key: "productOfferDashboard.widget.topProducts.emptyState";
+                readonly fallback: "No products data available";
+            };
+        };
+        readonly conversionRate: {
+            readonly title: {
+                readonly key: "productOfferDashboard.widget.conversionRate.title";
+                readonly fallback: "Conversion Rate";
+            };
+            readonly subtitle: {
+                readonly key: "productOfferDashboard.widget.conversionRate.subtitle";
+                readonly fallback: "Orders ÷ Site visits";
+            };
+        };
+        readonly topPerformingOffers: {
+            readonly title: {
+                readonly key: "productOfferDashboard.widget.topPerformingOffers.title";
+                readonly fallback: "Top Performing Offers";
+            };
+            readonly totalRevenue: {
+                readonly key: "productOfferDashboard.widget.topPerformingOffers.totalRevenue";
+                readonly fallback: "Total revenue";
+            };
+            readonly emptyState: {
+                readonly key: "productOfferDashboard.widget.topPerformingOffers.emptyState";
+                readonly fallback: "No offers data available";
+            };
+        };
+        readonly menu: {
+            readonly fullView: {
+                readonly key: "productOfferDashboard.widget.menu.fullView";
+                readonly fallback: "Full View";
+            };
+        };
+    };
+    readonly navigation: {
+        readonly back: {
+            readonly key: "productOfferDashboard.navigation.back";
+            readonly fallback: "Back to Dashboard";
+        };
+    };
+    readonly ariaLabel: {
+        readonly dashboard: {
+            readonly key: "productOfferDashboard.ariaLabel.dashboard";
+            readonly fallback: "Product Offer Performance Dashboard";
+        };
+        readonly statsCard: {
+            readonly key: "productOfferDashboard.ariaLabel.statsCard";
+            readonly fallback: "Performance metric";
+        };
+        readonly conversionChart: {
+            readonly key: "productOfferDashboard.ariaLabel.conversionChart";
+            readonly fallback: "Conversion rate chart";
+        };
+        readonly topProducts: {
+            readonly key: "productOfferDashboard.ariaLabel.topProducts";
+            readonly fallback: "Top selling products";
+        };
+        readonly topOffers: {
+            readonly key: "productOfferDashboard.ariaLabel.topOffers";
+            readonly fallback: "Top performing offers chart";
+        };
+        readonly widgetMenu: {
+            readonly key: "productOfferDashboard.ariaLabel.widgetMenu";
+            readonly fallback: "Widget options menu";
+        };
+        readonly filterDateRange: {
+            readonly key: "productOfferDashboard.ariaLabel.filterDateRange";
+            readonly fallback: "Filter by date range";
+        };
+        readonly filterMarket: {
+            readonly key: "productOfferDashboard.ariaLabel.filterMarket";
+            readonly fallback: "Filter by market";
+        };
+        readonly backButton: {
+            readonly key: "productOfferDashboard.ariaLabel.backButton";
+            readonly fallback: "Back to dashboard overview";
+        };
+    };
+    readonly fullView: {
+        readonly topOffers: {
+            readonly title: {
+                readonly key: "productOfferDashboard.fullView.topOffers.title";
+                readonly fallback: "Top Performing Offers";
+            };
+            readonly columnName: {
+                readonly key: "productOfferDashboard.fullView.topOffers.columnName";
+                readonly fallback: "Offer Name";
+            };
+            readonly columnRevenue: {
+                readonly key: "productOfferDashboard.fullView.topOffers.columnRevenue";
+                readonly fallback: "Revenue";
+            };
+            readonly columnPercentage: {
+                readonly key: "productOfferDashboard.fullView.topOffers.columnPercentage";
+                readonly fallback: "Share";
+            };
+            readonly columnTrend: {
+                readonly key: "productOfferDashboard.fullView.topOffers.columnTrend";
+                readonly fallback: "Trend";
+            };
+        };
+    };
+    readonly defaults: {
+        readonly trendZero: {
+            readonly key: "productOfferDashboard.defaults.trendZero";
+            readonly fallback: "+0%";
+        };
+        readonly noData: {
+            readonly key: "productOfferDashboard.defaults.noData";
+            readonly fallback: "--";
+        };
+    };
+};
+/**
+ * Get translation text from a translation entry.
+ * Currently returns the fallback text. When an i18n provider is integrated,
+ * this function will use the key to look up the translated string.
+ */
+export declare function getTranslation(entry: TranslationEntry): string;
+export {};