@umituz/web-dashboard 3.2.4 → 4.1.0

package/README.md

@@ -1,32 +1,246 @@
 # @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.
+- **Styling is shipped, not assumed.** Import `@umituz/web-dashboard/styles.css`
+  once; all components use `udb-*` BEM classes.
+- **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.
+
+## What changed in 4.1
+
+- **The design system is back — for real this time.** 4.0 dropped
+  `@umituz/web-design-system` entirely; 4.1 makes it a runtime dependency
+  again and actually renders it:
+  - `./primitives` (`Button`, `Input`, `Checkbox`, `Skeleton`, `cn`) are thin
+    adapters that **delegate to the DS components** — the dashboard prop API
+    is unchanged, call sites need zero edits.
+  - `UserManagementTable` renders the DS `DataTable`; `MetricCard` composes
+    the DS `MetricCard`; `AnalyticsCard` is built on DS `Card` primitives.
+  - `styles.css` imports `@umituz/web-design-system/styles.css` transitively
+    (Tailwind v4 precompiled) — hosts still import only the dashboard
+    stylesheet.
+- **`--u-*` tokens are now bridges.** `tokens.css` maps every color/radius/
+  shadow token to the DS `--color-*`/`--radius-*` variables (with the old
+  literal as fallback). Override either side; dark mode (`data-udb-theme="dark"`)
+  now sets DS variables and the bridge flows through.
+- **Primitive base CSS is gone from `dashboard.css`.** Only dashboard-owned
+  modifiers remain (`udb-btn__spinner`, `udb-input--error/--with-toggle`,
+  `udb-skeleton--*`, `udb-card--sm/--lg`, `udb-table` for the permission
+  matrix); bases come from the DS stylesheet.
+- **Peer footprint**: pulling the dashboard in transitively installs the DS's
+  Radix UI peers (npm 7+ handles this automatically; only imported components
+  end up in the bundle).
 
 ## Installation
 
 ```bash
 npm install @umituz/web-dashboard
+import "@umituz/web-dashboard/styles.css";
 ```
 
-## Usage
+Peers: `react` + `react-dom` (^18 or ^19) and `react-router-dom` (^6 or ^7).
+Runtime deps: `@umituz/web-design-system` + `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
+
+`tokens.css` bridges every `--u-*` token to a design-system variable
+(`--u-color-primary: var(--color-primary, #2563eb)`), so you can theme two
+ways: override the `--u-*` bridge heads, or set the DS `--color-*`/`--radius-*`
+variables (e.g. from your own Tailwind `@theme`). Dark mode is host-driven:
+put `data-udb-theme="dark"` on any ancestor — the dashboard dark block sets
+the DS variables and both layers switch together.
 
-```typescript
-import { useAnalytics } from '@umituz/web-dashboard';
+## Entry points
 
-function Dashboard() {
-  const { data, loading } = useAnalytics();
-  // ...
-}
+```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>
+```
+
+### One module list → routes + nav + guards
+
+```tsx
+import { buildRoutes, buildNav } from "@umituz/web-dashboard/modules";
+import { usePermissions } from "@umituz/web-dashboard/permissions";
+
+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 /> },
+];
+
+// 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";
+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.4",
-  "description": "Dashboard Layout System - Comprehensive analytics, calendar, customizable layouts, and config-based architecture",
+  "version": "4.1.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,22 @@
   "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"
+    "@umituz/web-design-system": "^4.0.2",
+    "lucide-react": "^0.577.0"
   },
   "devDependencies": {
+    "@types/node": "^22.20.5",
     "@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 +112,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,28 @@
 /**
- * Analytics Card Component
- *
- * Configurable analytics card with chart or metrics
+ * Analytics Card — chart/metric container on the design-system Card.
+ * Size modifiers ("sm"/"lg") are dashboard-owned padding overrides.
  */
 
 import { Loader2, AlertCircle } from "lucide-react";
-import { cn } from "@umituz/web-design-system/utils";
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from "@umituz/web-design-system/organisms";
+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,59 +34,47 @@ 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" />
+      <Card className={cn(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>
+      </Card>
     );
   }
 
   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>
+      <Card className={cn(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>
+      </Card>
     );
   }
 
   return (
-    <div className={cn("bg-background border border-border rounded-xl", sizeClasses[size], className)}>
-      {/* Header */}
+    <Card className={cn(SURFACE_CLASS[size], className)}>
       {(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>
-      )}
-
-      {/* Chart */}
-      {chart && <AnalyticsChart config={chart} />}
-
-      {/* Metrics */}
-      {metrics && metrics.length > 0 && (
-        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-          {metrics.map((metric) => (
-            <MetricCard key={metric.id} metric={metric} size="sm" />
-          ))}
-        </div>
+        <CardHeader>
+          {title && <CardTitle>{title}</CardTitle>}
+          {description && <CardDescription>{description}</CardDescription>}
+        </CardHeader>
       )}
-
-      {/* Custom Content */}
-      {children}
-    </div>
+      <CardContent>
+        {chart && <AnalyticsChart config={chart} />}
+        {metrics && metrics.length > 0 && (
+          <div className="udb-analytics-card__metrics">
+            {metrics.map((metric) => (
+              <MetricCard key={metric.id} metric={metric} size="sm" />
+            ))}
+          </div>
+        )}
+        {children}
+      </CardContent>
+    </Card>
   );
 };