@umituz/web-dashboard 6.1.0 → 6.2.0

package/README.md

@@ -1,32 +1,14 @@
 # @umituz/web-dashboard
 
-Installable app skeleton for SaaS dashboards: layouts, auth, analytics, a
-content calendar, and a permissions/session/module registry. Every domain is
-an independent entry point — import only what your app uses. UI atoms and
-design tokens come from [@umituz/web-design-system](https://github.com/umituz/web-design-system);
+Installable app skeleton for SaaS dashboards: layouts, analytics, a content
+calendar, a product onboarding flow, and a permissions/module registry. Every
+domain is an independent entry point — import only what your app uses. UI
+atoms and design tokens come from [@umituz/web-design-system](https://github.com/umituz/web-design-system);
 translations from [@umituz/web-localization](https://github.com/umituz/web-localization).
 
 The package is **source-distributed** (published as raw TypeScript in `src/`).
 Your bundler compiles it alongside your app; no prebuilt bundle ships.
 
-## What changed in v5 (major)
-
-- **No more local primitives.** The `./primitives` entry point is gone;
-  components import `@umituz/web-design-system` directly. Hosts that need
-  `Button`/`Input`/`Checkbox`/`Skeleton`/`cn` import them from the design
-  system.
-- **No more `--u-*` token layer.** `tokens.css` is deleted. The `udb-*`
-  stylesheet consumes the design-system variables (`--color-*`, `--radius-*`,
-  `--font-*`, `--shadow-*`) directly; dashboard-specific knobs (typography
-  scale, sidebar geometry) are `--udb-*` custom properties defined in
-  `styles.css` itself.
-- **No more local i18n copy.** The `./i18n` entry point is gone; `useT` now
-  comes from `@umituz/web-localization/react` (`I18nProvider` there replaces
-  `DashboardI18nProvider`, same `t` signature).
-- **No bundled dark preset.** Dark mode follows the design system: hosts set
-  dark values on the DS variables under `[data-theme="dark"]` / `.dark`
-  (see the design system's `bridge.css` contract).
-
 ## Installation
 
 ```bash
@@ -34,9 +16,10 @@ npm install @umituz/web-dashboard
 import "@umituz/web-dashboard/styles.css";
 ```
 
-Peers: `react` + `react-dom` (^18 or ^19) and `react-router-dom` (^6 or ^7).
-Runtime deps: `@umituz/web-design-system`, `@umituz/web-localization`,
-`lucide-react`. Nothing else.
+Peers: `react` + `react-dom` (^18 or ^19), `react-router-dom` (^6 or ^7),
+and `framer-motion` (^12, onboarding animations only).
+Runtime deps: `@umituz/web-design-system` (^4.9),
+`@umituz/web-localization`, `lucide-react`.
 
 ### Tailwind hosts
 
@@ -51,18 +34,20 @@ reads its variables, so theming has exactly one path: set the DS variables.
 Vanilla-CSS hosts define `--app-*` slots via the design system's `bridge.css`;
 Tailwind hosts override `--color-*` from their own `@theme`. Dashboard-only
 knobs (`--udb-font-size-*`, `--udb-space-*`, `--udb-sidebar-*`,
-`--udb-header-height`, `--udb-border-strong`, `--udb-radius-pill`) can be overridden anywhere in the cascade.
+`--udb-header-height`, `--udb-border-strong`, `--udb-radius-pill`) can be
+overridden anywhere in the cascade. Dark mode follows the design system:
+hosts set dark values on the DS variables under `[data-theme="dark"]` /
+`.dark`.
 
 ## Entry points
 
 ```bash
-@umituz/web-dashboard/styles.css    # component stylesheet (udb-* BEM)
+@umituz/web-dashboard/styles.css    # component stylesheet (udb-* BEM, incl. udb-onb-*)
 @umituz/web-dashboard/permissions   # PermissionMatrix, hasPermission, guards
-@umituz/web-dashboard/session       # AuthAdapter, SessionProvider, OrgSwitcher, DemoLogin
 @umituz/web-dashboard/modules       # DashboardModule, buildRoutes, buildNav
 @umituz/web-dashboard/layouts       # DashboardLayout, DashboardSidebar, DashboardHeader
 @umituz/web-dashboard/settings      # SettingsLayout, admin skeletons (users, matrix, audit)
-@umituz/web-dashboard/auth          # Login/Register/Forgot/Reset forms, AuthLayout
+@umituz/web-dashboard/onboarding    # OnboardingFlow + 14 screens, persistence, analytics
 @umituz/web-dashboard/analytics     # AnalyticsLayout, SVG AnalyticsChart, services
 @umituz/web-dashboard/calendar      # useCalendar, CalendarService (injected DB)
 @umituz/web-dashboard/config        # dashboard config helpers
@@ -70,28 +55,23 @@ knobs (`--udb-font-size-*`, `--udb-space-*`, `--udb-sidebar-*`,
 ```
 
 Each domain also exposes `components`, `hooks`, `utils`, `types`
-sub-entries (and `services` for analytics/calendar). The v4 modules
-(`permissions`, `session`, `modules`) are **deep-entry only** — they are not
-re-exported from the root, so router-less hosts never pull router code in
-transitively.
+sub-entries (and `services` for analytics/calendar). The modules
+(`permissions`, `modules`, `onboarding`) are **deep-entry only** — they are
+not re-exported from the root, so router-less hosts never pull router code
+in transitively.
 
 ## The composition
 
-A host app assembles the skeleton from four seams:
+A host app assembles the skeleton from its seams:
 
 ```tsx
 import { I18nProvider } from "@umituz/web-localization/react";
-import { SessionProvider, createInMemoryAuthAdapter } from "@umituz/web-dashboard/session";
 import { PermissionsProvider } from "@umituz/web-dashboard/permissions";
 
-const adapter = createInMemoryAuthAdapter({ users: DEMO_USERS });
-
 <I18nProvider t={i18n.t}>
-  <SessionProvider adapter={adapter}>
-    <PermissionsProvider matrix={ROLE_PERMISSIONS} role={user?.role}>
-      <App />
-    </PermissionsProvider>
-  </SessionProvider>
+  <PermissionsProvider matrix={ROLE_PERMISSIONS} role={user?.role}>
+    <App />
+  </PermissionsProvider>
 </I18nProvider>
 ```
 
@@ -128,12 +108,31 @@ Matrix grants are `"*"` (everything), `"sales.*"` (module wildcard) or exact
 strings. `<RequirePermission permission>` guards pages (lock screen
 fallback); `<Can>` is its inline twin.
 
-### Session
+### Onboarding
+
+`OnboardingFlow` runs a declarative screen list (`welcome`, `goal-question`,
+`pain-points`, `social-proof`, `tinder-cards`, `personalized-solution`,
+`comparison`, `preferences`, `permission-priming`, `processing`,
+`app-demo`, `value-delivery`, `account-gate`, `paywall`) with progress
+persistence, resume, analytics events and an error boundary:
+
+```tsx
+import { OnboardingFlow, healthOnboardingTemplate } from "@umituz/web-dashboard/onboarding";
+
+<OnboardingIntlProvider labels={myLabels}>
+  <OnboardingFlow config={healthOnboardingTemplate({ onComplete })} />
+</OnboardingIntlProvider>
+```
 
-Hosts adapt their auth to `AuthAdapter` (`login`/`logout`/`current`;
-`listTenants`/`demoLogin` optional). `useSession()` exposes user, tenants,
-active tenant, status + `switchTenant`. `OrgSwitcher` renders the tenant
-dropdown; `DemoLogin` the one-click demo entry.
+Screen selection logic ships as pure functions (`calc`, `predicates`,
+`validation` entry blocks), option/question UI as design-system molecules
+(`OptionCard`) and atoms (`Button`, `Progress`, `Spinner`). Styles are the
+`udb-onb-*` block inside `styles.css`; transitions use `framer-motion`.
+Templates: `healthOnboardingTemplate`, `artOnboardingTemplate`,
+`videoOnboardingTemplate`, `platformOnboardingTemplate` (plus
+`withDefaultDemo` for demo fallbacks). Labels localize through
+`OnboardingIntlProvider`; `defaultOnboardingLabels` lists every overridable
+string.
 
 ### Calendar
 
@@ -167,22 +166,18 @@ import { I18nProvider } from "@umituz/web-localization/react";
 
 Interpolation uses the standard `{{placeholder}}` syntax. Without a
 provider, `useT()` falls back to `defaultT`, which humanizes keys
-(`auth.login.welcomeBack` → "Welcome back") so a bare install still renders
+(`analytics.chart.title` → "Chart title") so a bare install still renders
 readably. The per-domain key catalogs are the string contract:
 
 ```ts
-import { AUTH_KEYS } from "@umituz/web-dashboard/auth";
 import { ANALYTICS_KEYS } from "@umituz/web-dashboard/analytics";
 import { SETTINGS_ADMIN_KEYS } from "@umituz/web-dashboard/settings/utils";
 import { PERMISSIONS_KEYS } from "@umituz/web-dashboard/permissions";
-import { SESSION_KEYS } from "@umituz/web-dashboard/session";
 ```
 
 ## Platform compatibility
 
 - React 18 and 19, react-router-dom 6 and 7
-- `generateResetToken` requires `crypto.getRandomValues` (all modern browsers,
-  Node ≥ 19) and **throws** rather than falling back to an insecure PRNG
 - Rendering targets the DOM; React Native is not supported
 
 ## Development
@@ -195,27 +190,6 @@ npm test            # vitest unit tests (pure utils + module builders)
 npm run test:watch
 ```
 
-## Migration: 4.x → 5.0
-
-1. `@umituz/web-dashboard/primitives` → import `Button`/`Input`/`Checkbox`/
-   `Skeleton` from `@umituz/web-design-system/atoms` and `cn` from
-   `@umituz/web-design-system/utils/cn`.
-2. `@umituz/web-dashboard/i18n` → `DashboardI18nProvider` becomes
-   `I18nProvider` from `@umituz/web-localization/react`; `useT`, `defaultT`
-   and `TranslateFn` come from the same entry point.
-3. `@umituz/web-dashboard/tokens.css` → drop the import; `styles.css` is the
-   only stylesheet. Migrate `--u-*` overrides to the DS variables
-   (`--u-color-primary` → `--color-primary`, `--u-color-surface` →
-   `--color-card`, `--u-color-bg` → `--color-background`, `--u-color-text` →
-   `--color-foreground`, `--u-color-muted` → `--color-muted-foreground`,
-   `--u-color-surface-muted` → `--color-muted`, `--u-color-danger` →
-   `--color-destructive`) and dashboard knobs to their `--udb-*` names
-   (`--u-font-size-*` → `--udb-font-size-*`, `--u-color-border-strong` →
-   `--udb-border-strong`, `--u-sidebar-*` → `--udb-sidebar-*`, `--u-space-*` →
-   `--udb-space-*`).
-4. Dark mode: replace `data-udb-theme="dark"` with the design-system
-   convention (`[data-theme="dark"]` / `.dark` + dark DS variable values).
-
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "6.1.0",
-  "description": "Installable app skeleton for the fleet — layouts, analytics (dependency-free SVG charts), calendar, onboarding flow, i18n via @umituz/web-localization, permissions/module registry; udb-* stylesheet on design-system tokens (auth lives in @umituz/web-auth)",
+  "version": "6.2.0",
+  "description": "Installable app skeleton for the fleet — layouts, analytics (dependency-free SVG charts), calendar, onboarding flow, i18n via @umituz/web-localization, permissions/module registry; udb-* stylesheet on design-system tokens",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -38,8 +38,7 @@
     "./config": "./src/config/index.ts",
     "./package.json": "./package.json",
     "./charts": "./src/domains/charts/index.ts",
-    "./onboarding": "./src/domains/onboarding/index.ts",
-    "./onboarding.css": "./src/domains/onboarding/onboarding.css"
+    "./onboarding": "./src/domains/onboarding/index.ts"
   },
   "files": [
     "src",
@@ -61,12 +60,9 @@
     "framer-motion": "^12.0.0"
   },
   "dependencies": {
-    "@umituz/web-design-system": "^4.8.1",
+    "@umituz/web-design-system": "^4.9.0",
     "lucide-react": "^0.577.0",
-    "@umituz/web-localization": "^1.2.1",
-    "@radix-ui/react-progress": "^1.1.7",
-    "clsx": "^2.1.1",
-    "tailwind-merge": "^3.5.0"
+    "@umituz/web-localization": "^1.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",

package/src/config/DashboardConfig.ts

@@ -1,92 +1,45 @@
-/**
- * Dashboard Configuration
- * Config-based dashboard system
- */
-
 import type { ChartType } from '../domains/analytics/types/analytics';
 
-/**
- * Analytics service types
- */
 export type AnalyticsServiceType = 'traffic' | 'cohort' | 'funnel' | 'growth' | 'performance';
 
-/**
- * Export format
- */
 export type ExportFormat = 'pdf' | 'excel' | 'csv' | 'json';
 
-/**
- * Analytics configuration
- */
 export interface AnalyticsConfig {
-  /** Enable analytics */
-  enabled?: boolean;
-  /** Analytics services to include */
-  services?: AnalyticsServiceType[];
-  /** Real-time updates */
-  realtime?: boolean;
-  /** Export configuration */
-  export?: {
+    enabled?: boolean;
+    services?: AnalyticsServiceType[];
+    realtime?: boolean;
+    export?: {
     enabled?: boolean;
     formats?: ExportFormat[];
   };
 }
 
-/**
- * Data refresh configuration
- */
 export interface DataConfig {
-  /** Refresh interval in milliseconds */
-  refreshInterval?: number;
-  /** Cache duration in milliseconds */
-  cacheDuration?: number;
-  /** Retry attempts for failed requests */
-  retryAttempts?: number;
+    refreshInterval?: number;
+    cacheDuration?: number;
+    retryAttempts?: number;
 }
 
-/**
- * Charts configuration
- */
 export interface ChartsConfig {
-  /** Default chart type */
-  defaultType?: ChartType;
-  /** Chart theme */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Enable animations */
-  animations?: boolean;
-  /** Color palette */
-  colors?: string[];
+    defaultType?: ChartType;
+    theme?: 'light' | 'dark' | 'auto';
+    animations?: boolean;
+    colors?: string[];
 }
 
-/**
- * Performance configuration
- */
 export interface PerformanceConfig {
-  /** Enable lazy loading */
-  lazyLoad?: boolean;
-  /** Enable virtual scrolling */
-  virtualScrolling?: boolean;
-  /** Pagination size */
-  paginationSize?: number;
+    lazyLoad?: boolean;
+    virtualScrolling?: boolean;
+    paginationSize?: number;
 }
 
-/**
- * Dashboard configuration
- */
 export interface DashboardConfig {
-  /** Analytics configuration */
-  analytics?: AnalyticsConfig;
-  /** Data configuration */
-  data?: DataConfig;
-  /** Charts configuration */
-  charts?: ChartsConfig;
-  /** Performance configuration */
-  performance?: PerformanceConfig;
+    analytics?: AnalyticsConfig;
+    data?: DataConfig;
+    charts?: ChartsConfig;
+    performance?: PerformanceConfig;
 }
 
-/**
- * Default dashboard configuration
- */
 export const DEFAULT_DASHBOARD_CONFIG: DashboardConfig = {
   analytics: {
     enabled: true,
@@ -98,9 +51,7 @@ export const DEFAULT_DASHBOARD_CONFIG: DashboardConfig = {
     },
   },
   data: {
-    refreshInterval: 30000, // 30 seconds
-    cacheDuration: 300000, // 5 minutes
-    retryAttempts: 3,
+    refreshInterval: 30000,     cacheDuration: 300000,     retryAttempts: 3,
   },
   charts: {
     defaultType: 'line',

package/src/domains/analytics/components/index.ts

@@ -1,9 +1,3 @@
-/**
- * Analytics Components
- *
- * Export all analytics components
- */
-
 export { MetricCard } from "./MetricCard";
 export { AnalyticsChart } from "./AnalyticsChart";
 export { AnalyticsCard } from "./AnalyticsCard";

package/src/domains/analytics/hooks/index.ts

@@ -1,9 +1,3 @@
-/**
- * Analytics Hooks
- *
- * Export all analytics hooks
- */
-
 export { useAnalytics, createStubAnalyticsApiClient } from "./useAnalytics";
 export type {
   AnalyticsApiClient,

package/src/domains/analytics/hooks/useAnalytics.ts

@@ -1,11 +1,3 @@
-/**
- * useAnalytics
- *
- * Pure state + side-effect container. Mock data, commented-out
- * fetch calls, and Math.random()-driven time series are gone.
- * All persistence is delegated to the injected `apiClient`.
- */
-
 import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import type {
   KPIs,
@@ -14,10 +6,6 @@ import type {
   AnalyticsExportOptions,
 } from "../types/analytics";
 
-/**
- * API client contract. Replace `loadAnalytics` with a real fetch wrapper
- * and `exportAnalytics` with a server-side exporter.
- */
 export interface AnalyticsApiClient {
   loadAnalytics: (range: DateRangeValue) => Promise<AnalyticsDataPayload>;
   exportAnalytics: (payload: AnalyticsDataPayload, options: AnalyticsExportOptions) => Promise<Blob>;
@@ -30,8 +18,7 @@ export interface AnalyticsDataPayload {
 
 export interface UseAnalyticsOptions {
   initialDateRange?: DateRangeValue;
-  /** Auto-refresh interval in ms (0 to disable) */
-  refreshInterval?: number;
+    refreshInterval?: number;
   apiClient: AnalyticsApiClient;
 }
 
@@ -83,12 +70,7 @@ export function useAnalytics(options: UseAnalyticsOptions): UseAnalyticsReturn {
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  /**
-   * Refs track the latest request so an in-flight call can't be
-   * overridden by a slower one (e.g. user changes the range while
-   * the previous fetch is still resolving).
-   */
-  const requestIdRef = useRef(0);
+    const requestIdRef = useRef(0);
 
   const refresh = useCallback(async () => {
     const requestId = ++requestIdRef.current;

package/src/domains/analytics/index.ts

@@ -1,10 +1,3 @@
-/**
- * Analytics Domain
- *
- * Main entry point for analytics domain
- */
-
-// Components
 export {
   MetricCard,
   AnalyticsChart,
@@ -12,7 +5,6 @@ export {
   AnalyticsLayout,
 } from "./components";
 
-// Hooks
 export {
   useAnalytics,
   createStubAnalyticsApiClient,
@@ -24,7 +16,6 @@ export type {
   UseAnalyticsReturn,
 } from "./hooks";
 
-// Utils
 export {
   formatNumber,
   formatPercentage,
@@ -47,7 +38,6 @@ export {
   ANALYTICS_KEYS,
 } from "./utils";
 
-// Types
 export type {
   Metric,
   TimeSeriesData,

package/src/domains/analytics/services/AnalyticsEngineService.ts

@@ -1,10 +1,3 @@
-/**
- * Analytics Engine Service
- *
- * Advanced analytics operations including cohort analysis, funnel analysis,
- * user segmentation, behavior prediction, and conversion path analysis.
- */
-
 import type {
   CohortAnalysis,
   FunnelData,
@@ -59,10 +52,6 @@ export interface ActivityItem {
   timestamp: string | Date;
 }
 
-/**
- * Numeric metric keys supported by segment aggregation.
- * Constrained to a string union to avoid `any` lookups at runtime.
- */
 type NumericUserMetric =
   | 'session_duration'
   | 'pages_per_session'
@@ -79,37 +68,18 @@ const isUserMetric = (key: string): key is NumericUserMetric =>
     'last_login_days',
   ].includes(key);
 
-/**
- * Safe numeric accessor for a UserData field.
- * Returns 0 when the field is missing or not a number, instead of forcing a cast.
- */
 const getNumericMetric = (user: UserData, key: NumericUserMetric): number => {
   const value = user[key];
   return typeof value === 'number' ? value : 0;
 };
 
-/**
- * Segmentation thresholds (in days since last login).
- */
 const SEGMENT_THRESHOLDS = {
   activeDays: 7,
   moderateDays: 30,
 } as const;
 
-/**
- * Analytics Engine Service
- *
- * Pure-functional service for advanced analytics calculations.
- * Stateless and testable: instantiate with `new AnalyticsEngineService()`.
- */
 export class AnalyticsEngineService {
-  /**
-   * Calculate cohort retention analysis
-   *
-   * @param data - User data with signup and activity dates
-   * @returns Cohort analysis with retention rates
-   */
-  public calculateRetention(data: UserData[]): CohortAnalysis[] {
+    public calculateRetention(data: UserData[]): CohortAnalysis[] {
     const cohorts: Map<string, UserData[]> = new Map();
 
     data.forEach((user) => {
@@ -156,13 +126,7 @@ export class AnalyticsEngineService {
     return cohortAnalysis;
   }
 
-  /**
-   * Analyze conversion paths
-   *
-   * @param data - Conversion data with paths and values
-   * @returns Conversion path analysis
-   */
-  public analyzeConversionPaths(data: ConversionData[]): ConversionPath[] {
+    public analyzeConversionPaths(data: ConversionData[]): ConversionPath[] {
     const paths: Map<string, { count: number; value: number }> = new Map();
     let totalConversions = 0;
 
@@ -194,14 +158,7 @@ export class AnalyticsEngineService {
       .sort((a, b) => b.conversions - a.conversions);
   }
 
-  /**
-   * Calculate funnel analysis
-   *
-   * @param data - Funnel data with step indicators
-   * @param steps - Funnel step names
-   * @returns Funnel analysis data
-   */
-  public calculateFunnel(data: FunnelItem[], steps: string[]): FunnelData {
+    public calculateFunnel(data: FunnelItem[], steps: string[]): FunnelData {
     let previousCount = data.length;
     const funnelSteps = steps.map((step, index) => {
       const stepCount = data.filter((item) => Boolean(item[step])).length;
@@ -233,13 +190,7 @@ export class AnalyticsEngineService {
     };
   }
 
-  /**
-   * Generate activity heatmap
-   *
-   * @param data - Activity data with timestamps
-   * @returns Heatmap data by day and hour (Monday-first)
-   */
-  public generateActivityHeatmap(data: ActivityItem[]): HeatmapData[] {
+    public generateActivityHeatmap(data: ActivityItem[]): HeatmapData[] {
     const heatmap: HeatmapData[] = [];
     const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const;
 
@@ -247,8 +198,7 @@ export class AnalyticsEngineService {
       for (let hour = 0; hour < 24; hour++) {
         const count = data.filter((item) => {
           const d = new Date(item.timestamp);
-          // getDay() is Sunday-based (0=Sun..6=Sat); convert to Monday-first index
-          const mondayFirst = (d.getDay() + 6) % 7;
+                    const mondayFirst = (d.getDay() + 6) % 7;
           return mondayFirst === day && d.getHours() === hour;
         }).length;
 
@@ -258,13 +208,7 @@ export class AnalyticsEngineService {
     return heatmap;
   }
 
-  /**
-   * Segment users by behavior
-   *
-   * @param data - User data
-   * @returns User segments
-   */
-  public segmentUsers(data: UserData[]): UserSegment[] {
+    public segmentUsers(data: UserData[]): UserSegment[] {
     const defineSegment = (
       name: string,
       filter: (u: UserData) => boolean,
@@ -311,14 +255,7 @@ export class AnalyticsEngineService {
     ];
   }
 
-  /**
-   * Predict user behavior
-   *
-   * @param user - Target user
-   * @param historicalData - Historical user data
-   * @returns Behavior prediction
-   */
-  public predictUserBehavior(
+    public predictUserBehavior(
     user: UserData,
     historicalData: UserData[],
   ): UserBehaviorPrediction {
@@ -360,8 +297,4 @@ export class AnalyticsEngineService {
   }
 }
 
-/**
- * Default instance for convenience.
- * The class is also exported so consumers can instantiate a fresh one for tests.
- */
 export const analyticsEngineService = new AnalyticsEngineService();