@umituz/web-dashboard 3.2.2 → 4.0.0

package/README.md

@@ -1,32 +1,220 @@
 # @umituz/web-dashboard
 
-Comprehensive dashboard library with analytics, billing, calendar, and more.
+Installable app skeleton for SaaS dashboards: layouts, auth, onboarding,
+analytics, a content calendar, an i18n bridge, and a permissions/session/
+module registry. Every domain is an independent entry point — import only
+what your app uses. Camp-agnostic by construction: the package ships its
+own `udb-*` stylesheet driven by `--u-*` tokens, so it works identically in
+vanilla-CSS and Tailwind hosts.
 
-## Features
+The package is **source-distributed** (published as raw TypeScript in `src/`).
+Your bundler compiles it alongside your app; no prebuilt bundle ships.
 
-- Analytics dashboards with charts
-- Billing and subscription management
-- Calendar integration
-- User management
-- Real-time metrics
+## What changed in v4 (major)
+
+- **Billing moved to [@umituz/web-polar-payment](https://github.com/umituz/web-polar-payment)**
+  under the `./portal` entry point. The old `./billing*` entry points are gone.
+- **`@umituz/web-design-system` is no longer a dependency.** The primitives
+  (`Button`, `Input`, `Checkbox`, `Skeleton`, `cn`) live in `./primitives`.
+- **Styling is shipped, not assumed.** Import `@umituz/web-dashboard/styles.css`
+  (and optionally `tokens.css`) once; all components use `udb-*` BEM classes.
+  Tailwind, design-system tokens and utility classes are gone from the package.
+- **No i18n runtime.** `react-i18next` is out; hosts bridge their own `t` via
+  `<DashboardI18nProvider t={i18n.t}>` (see below). Without a provider,
+  keys humanize to readable English.
+- **No Firebase.** The calendar persists through the injected
+  `ICalendarDatabase` seam; `createInMemoryCalendarDatabase()` is the default.
+- **recharts is out.** `AnalyticsChart` renders line/area/bar/pie/donut as
+  dependency-free SVG with native `<title>` tooltips.
+- **New fleet modules**: `./permissions`, `./session`, `./modules` — the
+  texora/visora pattern (one module list drives routes + nav + guards) as
+  reusable building blocks.
 
 ## Installation
 
 ```bash
 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: `clsx` + `lucide-react`. Nothing else.
+
+### Tailwind hosts
+
+Every `udb-*` rule sets its own `box-sizing`/`background`/`border` explicitly,
+so preflight cannot leak in — but load order still matters with `*`-selector
+resets: import the package stylesheet **after** your base layer.
+
+### Theming & dark mode
+
+Override the `--u-*` custom properties (see `tokens.css` for the full list).
+Dark mode is host-driven: put `data-udb-theme="dark"` on any ancestor.
+
+## Entry points
+
+```bash
+@umituz/web-dashboard/styles.css    # component stylesheet (udb-* BEM)
+@umituz/web-dashboard/tokens.css    # --u-* custom properties only
+@umituz/web-dashboard/primitives    # Button, Input, Checkbox, Skeleton, cn
+@umituz/web-dashboard/i18n          # DashboardI18nProvider, useT, defaultT
+@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/onboarding    # OnboardingWizard + steps, useOnboarding
+@umituz/web-dashboard/auth          # Login/Register/Forgot/Reset forms, AuthLayout
+@umituz/web-dashboard/analytics     # AnalyticsLayout, SVG AnalyticsChart, services
+@umituz/web-dashboard/calendar      # useCalendar, CalendarService (injected DB)
+@umituz/web-dashboard/config        # dashboard config helpers
+```
+
+Each domain also exposes `components`, `hooks`, `utils`, `types`
+sub-entries (and `services` for analytics/calendar). The new 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.
+
+## The v4 composition
+
+A host app assembles the skeleton from four seams:
+
+```tsx
+import { DashboardI18nProvider } from "@umituz/web-dashboard/i18n";
+import { SessionProvider, createInMemoryAuthAdapter } from "@umituz/web-dashboard/session";
+import { PermissionsProvider } from "@umituz/web-dashboard/permissions";
+
+const adapter = createInMemoryAuthAdapter({ users: DEMO_USERS });
+
+<DashboardI18nProvider t={i18n.t}>
+  <SessionProvider adapter={adapter}>
+    <PermissionsProvider matrix={ROLE_PERMISSIONS} role={user?.role}>
+      <App />
+    </PermissionsProvider>
+  </SessionProvider>
+</DashboardI18nProvider>
 ```
 
-## Usage
+### One module list → routes + nav + guards
+
+```tsx
+import { buildRoutes, buildNav } from "@umituz/web-dashboard/modules";
+import { usePermissions } from "@umituz/web-dashboard/permissions";
 
-```typescript
-import { useAnalytics } from '@umituz/web-dashboard';
+const MODULES: DashboardModule[] = [
+  { path: "/dashboard", labelKey: "nav.dashboard", icon: LayoutDashboard,
+    navGroup: "nav.overview", order: 1, permission: "dashboard.view",
+    element: <DashboardPage /> },
+  { path: "/sales/:id", labelKey: "nav.salesDetail", icon: Circle,
+    navGroup: "nav.commercial", inNav: false, permission: "sales.view",
+    element: <SalesDetailPage /> },
+];
 
-function Dashboard() {
-  const { data, loading } = useAnalytics();
-  // ...
-}
+// routes: element pre-wrapped in <RequirePermission>
+const routes = buildRoutes(MODULES);            // -> <Route path key={...} {...route} />
+
+// nav: permission-filtered, grouped, ordered -> feed DashboardLayout config
+const { can } = usePermissions();
+const sidebarGroups = buildNav(MODULES, { can });
 ```
 
+Groups keep their first-appearance order in the list; `order` sorts items
+within a group; `inNav: false` hides detail routes from the sidebar.
+
+### Permissions
+
+`hasPermission(matrix, role, permission)` is pure and deny-by-default.
+Matrix grants are `"*"` (everything), `"sales.*"` (module wildcard) or exact
+strings. `<RequirePermission permission>` guards pages (lock screen
+fallback); `<Can>` is its inline twin.
+
+### Session
+
+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.
+
+### Calendar
+
+```tsx
+import { CalendarService, createInMemoryCalendarDatabase } from "@umituz/web-dashboard/calendar/services";
+
+// Bring your own backend:
+class MyDatabase implements ICalendarDatabase { /* ... */ }
+const service = new CalendarService(new MyDatabase());
+// or demo/test:
+const demo = new CalendarService(createInMemoryCalendarDatabase());
+```
+
+### Analytics
+
+`AnalyticsChart` consumes the same `ChartConfig` as v3 for
+line/area/bar/pie/donut. Tooltips are native SVG `<title>` elements;
+legends are color chips; unsupported types render an empty state.
+`useAnalytics` stays dependency-injected (`createStubAnalyticsApiClient`).
+
+## i18n contract
+
+Components render **i18n keys**, never English strings. Bridge your runtime
+once:
+
+```tsx
+import { DashboardI18nProvider } from "@umituz/web-dashboard/i18n";
+
+<DashboardI18nProvider t={i18n.t}>  {/* i18next's t — signature already matches */}
+```
+
+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
+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 { ONBOARDING_KEYS } from "@umituz/web-dashboard/onboarding";
+import { SETTINGS_ADMIN_KEYS } from "@umituz/web-dashboard/settings/utils/i18nKeys";
+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
+
+```bash
+npm install
+npm run lint        # eslint
+npm run typecheck   # tsc --noEmit
+npm test            # vitest unit tests (pure utils + module builders)
+npm run test:watch
+```
+
+CI runs lint + typecheck + test on every push/PR to `main`.
+
+## Migration: 3.x → 4.0
+
+1. Billing UI: switch imports to `@umituz/web-polar-payment/portal`.
+2. Design-system imports: use `@umituz/web-dashboard/primitives`
+   (`Button`/`Input`/`Checkbox`/`Skeleton` cover the used surface).
+3. Styling: import `styles.css` once; Tailwind utility classes no longer
+   exist inside the package. Config values that used to carry Tailwind
+   strings changed: `PlatformOption.color` is a plain CSS color string,
+   `PlanOption.badgeColor` became `badgeTone: "muted" | "primary" | "accent"`.
+4. i18n: wrap your app in `DashboardI18nProvider t={i18n.t}`; the
+   `react-i18next` peer is gone.
+5. Calendar: pass your own `ICalendarDatabase` (or the in-memory default);
+   the Firebase implementation was removed.
+6. v3.2.5 behavioral notes still apply (opt-in mock auth, route skeletons
+   off by default, `PerformanceService.startMonitoring()` explicit).
+
 ## License
 
 MIT

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "3.2.2",
-  "description": "Dashboard Layout System - Comprehensive analytics, calendar, customizable layouts, and config-based architecture",
+  "version": "4.0.0",
+  "description": "Installable app skeleton for the fleet — layouts, auth, onboarding, analytics (dependency-free SVG charts), calendar, i18n injection, permissions/session/module registry; ships its own udb-* stylesheet and --u-* tokens",
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     ".": "./src/index.ts",
+    "./styles.css": "./src/styles/dashboard.css",
+    "./tokens.css": "./src/styles/tokens.css",
+    "./primitives": "./src/primitives/index.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./permissions": "./src/domains/permissions/index.ts",
+    "./session": "./src/domains/session/index.ts",
+    "./modules": "./src/domains/modules/index.ts",
     "./layouts": "./src/domains/layouts/index.ts",
     "./layouts/components": "./src/domains/layouts/components/index.ts",
     "./layouts/hooks": "./src/domains/layouts/hooks/index.ts",
@@ -35,16 +45,11 @@
     "./analytics/types": "./src/domains/analytics/types/index.ts",
     "./analytics/services": "./src/domains/analytics/services/index.ts",
     "./calendar": "./src/domains/calendar/index.ts",
-    "./calendar/types": "./src/domains/calendar/types/calendar.types",
+    "./calendar/types": "./src/domains/calendar/types/calendar.types.ts",
     "./calendar/services": "./src/domains/calendar/services/index.ts",
     "./calendar/hooks": "./src/domains/calendar/hooks/index.ts",
     "./calendar/utils": "./src/domains/calendar/utils/index.ts",
     "./config": "./src/domain/config/index.ts",
-    "./billing": "./src/domains/billing/index.ts",
-    "./billing/components": "./src/domains/billing/components/index.ts",
-    "./billing/hooks": "./src/domains/billing/hooks/index.ts",
-    "./billing/utils": "./src/domains/billing/utils/index.ts",
-    "./billing/types": "./src/domains/billing/types/index.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -54,6 +59,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "version:patch": "npm version patch -m 'chore: release v%s'",
     "version:minor": "npm version minor -m 'chore: release v%s'",
     "version:major": "npm version major -m 'chore: release v%s'"
@@ -61,30 +68,21 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "react-router-dom": "^6.0.0 || ^7.0.0",
-    "firebase": "^10.0.0 || ^11.0.0 || ^12.0.0",
-    "@umituz/web-firebase": "^3.0.0",
-    "@umituz/web-polar-payment": "^1.0.20"
+    "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "dependencies": {
-    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.577.0",
-    "recharts": "^2.15.0",
-    "tailwind-merge": "^3.5.0"
+    "lucide-react": "^0.577.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.57.2",
     "@typescript-eslint/parser": "^8.57.2",
-    "@umituz/web-design-system": "^3.1.11",
-    "@umituz/web-firebase": "^3.6.0",
     "eslint": "^10.0.2",
-    "firebase": "^12.0.0",
-    "react-i18next": "^16.5.4",
     "react-router-dom": "^7.13.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1"
   },
   "keywords": [
     "dashboard",
@@ -113,13 +111,7 @@
     "metrics",
     "kpi",
     "visualization",
-    "recharts",
-    "billing",
-    "subscription",
-    "payment",
-    "invoices",
-    "pricing",
-    "plans",
+    "svg-charts",
     "react",
     "typescript",
     "components",

package/src/domains/analytics/components/AnalyticsCard.tsx

@@ -1,15 +1,24 @@
 /**
  * Analytics Card Component
  *
- * Configurable analytics card with chart or metrics
+ * Configurable analytics card with chart or metrics. Surface comes
+ * from the shared `udb-card` helper; size modifiers shrink/grow the
+ * padding ("full" shares the md default).
  */
 
 import { Loader2, AlertCircle } from "lucide-react";
-import { cn } from "@umituz/web-design-system/utils";
+import { cn } from "../../../primitives";
 import type { AnalyticsCardProps } from "../types/analytics";
 import { MetricCard } from "./MetricCard";
 import { AnalyticsChart } from "./AnalyticsChart";
 
+const SURFACE_CLASS = {
+  sm: 'udb-card--sm',
+  md: undefined,
+  lg: 'udb-card--lg',
+  full: undefined,
+} as const;
+
 export const AnalyticsCard = ({
   title,
   description,
@@ -21,18 +30,11 @@ export const AnalyticsCard = ({
   className,
   children,
 }: AnalyticsCardProps) => {
-  const sizeClasses = {
-    sm: "p-4",
-    md: "p-6",
-    lg: "p-8",
-    full: "p-6",
-  };
-
   if (loading) {
     return (
-      <div className={cn("bg-background border border-border rounded-xl", sizeClasses[size], className)}>
-        <div className="flex items-center justify-center h-48">
-          <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
+      <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
+        <div className="udb-analytics-card__status" role="status">
+          <Loader2 className="udb-spin udb-analytics-card__spinner" aria-hidden="true" />
         </div>
       </div>
     );
@@ -40,22 +42,22 @@ export const AnalyticsCard = ({
 
   if (error) {
     return (
-      <div className={cn("bg-background border border-border rounded-xl", sizeClasses[size], className)}>
-        <div className="flex items-center justify-center h-48 gap-3 text-destructive">
-          <AlertCircle className="h-5 w-5" />
-          <p className="text-sm">{error}</p>
+      <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
+        <div className="udb-analytics-card__status udb-analytics-card__status--error" role="alert">
+          <AlertCircle className="udb-analytics-card__error-icon" aria-hidden="true" />
+          <p className="udb-analytics-card__error-text">{error}</p>
         </div>
       </div>
     );
   }
 
   return (
-    <div className={cn("bg-background border border-border rounded-xl", sizeClasses[size], className)}>
+    <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
       {/* Header */}
       {(title || description) && (
-        <div className="mb-6">
-          {title && <h3 className="text-lg font-semibold text-foreground">{title}</h3>}
-          {description && <p className="text-sm text-muted-foreground mt-1">{description}</p>}
+        <div className="udb-analytics-card__header">
+          {title && <h3 className="udb-analytics-card__title">{title}</h3>}
+          {description && <p className="udb-analytics-card__description">{description}</p>}
         </div>
       )}
 
@@ -64,7 +66,7 @@ export const AnalyticsCard = ({
 
       {/* Metrics */}
       {metrics && metrics.length > 0 && (
-        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+        <div className="udb-analytics-card__metrics">
           {metrics.map((metric) => (
             <MetricCard key={metric.id} metric={metric} size="sm" />
           ))}