@umituz/web-dashboard 4.7.0 → 5.0.0

package/src/domains/permissions/PermissionsContext.tsx

@@ -1,20 +1,12 @@
-/**
- * Permissions context — provides the matrix + active role and a
- * `can(permission)` helper bound to them. Guard components
- * (<RequirePermission>, <Can>) consume this context.
- */
-
 import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
 import { Lock } from "lucide-react";
-import { useT } from "../../i18n";
+import { useT } from "@umituz/web-localization/react";
 import { hasPermission } from "./hasPermission";
 import { PERMISSIONS_KEYS } from "./utils/i18nKeys";
 import type { Permission, PermissionMatrix, RoleKey } from "./types";
 
 export interface PermissionsProviderProps {
-  /** Role x permission matrix. */
   matrix: PermissionMatrix;
-  /** Active user's role. */
   role: RoleKey | null | undefined;
   children: ReactNode;
 }
@@ -57,7 +49,6 @@ export const usePermissions = (): PermissionsContextValue => {
   return context;
 };
 
-/** Default lock screen rendered by RequirePermission when denied. */
 const ForbiddenFallback = () => {
   const t = useT();
   return (
@@ -72,17 +63,11 @@ const ForbiddenFallback = () => {
 };
 
 export interface RequirePermissionProps {
-  /** Permission required to render the children. */
   permission: Permission;
   children: ReactNode;
-  /** Rendered instead of the default lock screen when denied. */
   fallback?: ReactNode;
 }
 
-/**
- * Page-level permission gate — renders the fallback (lock screen by
- * default) instead of the children when `can(permission)` is false.
- */
 export const RequirePermission = ({
   permission,
   children,
@@ -95,7 +80,6 @@ export const RequirePermission = ({
 
 export interface CanProps extends RequirePermissionProps {}
 
-/** Declarative twin of RequirePermission for inline use. */
 export const Can = ({ permission, children, fallback }: CanProps) => (
   <RequirePermission permission={permission} fallback={fallback}>
     {children}

package/src/domains/permissions/utils/i18nKeys.ts

@@ -1,8 +1,3 @@
-/**
- * Permission domain i18n keys — the documented string contract.
- * Hosts translate these via <DashboardI18nProvider t={...}>.
- */
-
 export const PERMISSIONS_KEYS = {
   forbidden: {
     title: "permissions.forbidden.title",

package/src/domains/session/DemoLogin.tsx

@@ -1,18 +1,10 @@
-/**
- * DemoLogin — one-click demo entry (fleet pattern: log in as a demo
- * persona without a password). Controlled: the click delegates to
- * `onDemo` (typically `session.demoLogin`); the label defaults to
- * the i18n catalog.
- */
-
 import { UserRound } from "lucide-react";
-import { Button } from "../../primitives";
-import { useT } from "../../i18n";
+import { Button } from "@umituz/web-design-system/atoms";
+import { useT } from "@umituz/web-localization/react";
 import { SESSION_KEYS } from "./utils/i18nKeys";
 
 export interface DemoLoginProps {
   onDemo: (userId: string) => void | Promise<void>;
-  /** Demo user id to log in as. */
   userId: string;
   label?: string;
   variant?: "default" | "outline" | "ghost";

package/src/domains/session/OrgSwitcher.tsx

@@ -1,15 +1,7 @@
-/**
- * OrgSwitcher — tenant switcher trigger + dropdown.
- *
- * Controlled component: tenants and the active id come in as props,
- * switches are delegated via onSwitch. Styled entirely with existing
- * udb-* classes (profile button, avatar, menu).
- */
-
 import { useState } from "react";
 import { Building2, Check, ChevronDown } from "lucide-react";
-import { cn } from "../../primitives";
-import { useT } from "../../i18n";
+import { cn } from "@umituz/web-design-system/utils/cn";
+import { useT } from "@umituz/web-localization/react";
 import { SESSION_KEYS } from "./utils/i18nKeys";
 import type { Tenant } from "./types";
 

package/src/domains/settings/components/AuditLogList.tsx

@@ -1,21 +1,12 @@
-/**
- * AuditLogList — admin skeleton for the audit trail screen.
- * Entries arrive as props; the list is display-only.
- */
-
 import { ScrollText } from "lucide-react";
-import { useT } from "../../../i18n";
+import { useT } from "@umituz/web-localization/react";
 import { SETTINGS_ADMIN_KEYS } from "../utils/i18nKeys";
 
 export interface AuditEntry {
   id: string;
-  /** Who performed the action. */
   actor: string;
-  /** What happened, e.g. "role.changed". */
   action: string;
-  /** Optional target of the action (user, invoice...). */
   target?: string;
-  /** ISO timestamp. */
   at: string;
 }
 

package/src/domains/settings/components/PermissionMatrixScreen.tsx

@@ -1,11 +1,5 @@
-/**
- * PermissionMatrixScreen — admin skeleton rendering the role x
- * permission matrix. Read-only by default; pass `onToggle` to make
- * cells interactive (delegated — persistence is the host's job).
- */
-
 import { Check, Minus } from "lucide-react";
-import { cn } from "../../../primitives";
+import { cn } from "@umituz/web-design-system/utils/cn";
 import { hasPermission } from "../../permissions/hasPermission";
 import type {
   Permission,
@@ -16,7 +10,6 @@ import type {
 export interface PermissionMatrixScreenProps {
   matrix: PermissionMatrix;
   roles: RoleInfo[];
-  /** Permission column keys, in display order. */
   permissions: Permission[];
   onToggle?: (role: string, permission: Permission, granted: boolean) => void;
 }

package/src/domains/settings/components/SettingsLayout.tsx

@@ -1,28 +1,15 @@
 import { useEffect, useState } from "react";
 import { Outlet, useLocation, useNavigate } from "react-router-dom";
-import { Skeleton, Button } from "../../../primitives";
+import { Skeleton, Button } from "@umituz/web-design-system/atoms";
 import { ChevronLeft, Menu } from "lucide-react";
 import { SettingsSection } from "./SettingsSection";
 import type { SettingsConfig } from "../types/settings";
 
 interface SettingsLayoutProps {
-  /** Settings configuration */
   config: SettingsConfig;
-  /**
-   * Artificial route-transition skeleton duration in ms (default: 0 = off).
-   * Content renders immediately by default; set > 0 only if you want
-   * a skeleton to mask route swaps.
-   */
   routeTransitionMs?: number;
 }
 
-/**
- * Settings Layout Component
- *
- * Main layout wrapper for settings pages.
- * Provides sidebar navigation and content area. Styling is entirely
- * `udb-settings*` classes from the package stylesheet.
- */
 export const SettingsLayout = ({
   config,
   routeTransitionMs = 0,
@@ -33,9 +20,6 @@ export const SettingsLayout = ({
   const [mobileOpen, setMobileOpen] = useState(false);
   const [loading, setLoading] = useState(routeTransitionMs > 0);
 
-  // Optional route-change skeleton. Cleanup is essential: setTimeout must be
-  // cancelled on unmount/route change. With routeTransitionMs = 0 (default)
-  // no artificial delay is applied at all.
   useEffect(() => {
     if (routeTransitionMs <= 0) {
       setLoading(false);
@@ -78,7 +62,6 @@ export const SettingsLayout = ({
 
   return (
     <div className="udb-root udb-settings">
-      {/* Desktop Sidebar */}
       <aside className={`udb-settings__sidebar${collapsed ? " udb-settings__sidebar--collapsed" : ""}`}>
         {renderSidebarHeader(() => setCollapsed((prev) => !prev), false)}
         <nav className="udb-settings__nav">
@@ -94,7 +77,6 @@ export const SettingsLayout = ({
         </nav>
       </aside>
 
-      {/* Mobile Menu Overlay */}
       {mobileOpen && (
         <div className="udb-settings__mobile">
           <div
@@ -118,9 +100,7 @@ export const SettingsLayout = ({
         </div>
       )}
 
-      {/* Main Content Area */}
       <div className="udb-settings__main">
-        {/* Mobile Header */}
         <header className="udb-settings__mobile-header">
           <div className="udb-settings__mobile-lead">
             <Button

package/src/domains/settings/components/SettingsSection.tsx

@@ -1,27 +1,16 @@
 import { useMemo } from "react";
 import { Link } from "react-router-dom";
 import { ChevronRight } from "lucide-react";
-import { cn } from "../../../primitives";
+import { cn } from "@umituz/web-design-system/utils/cn";
 import type { SettingsSection as SettingsSectionType } from "../types/settings";
 
 interface SettingsSectionProps {
-  /** Section configuration */
   section: SettingsSectionType;
-  /** Current path */
   currentPath?: string;
-  /** On navigate callback */
   onNavigate?: (path: string) => void;
-  /** Collapsed state */
   collapsed?: boolean;
 }
 
-/**
- * Settings Section Component
- *
- * Displays a section of settings items.
- * Items without a path and without an onClick handler are hidden
- * (an empty interactive element violates a11y and is dead code).
- */
 export const SettingsSection = ({
   section,
   currentPath,
@@ -48,7 +37,6 @@ export const SettingsSection = ({
           const isActive = currentPath === item.path;
           const hasNavigation = Boolean(item.path) || Boolean(item.onClick);
 
-          // Skip rendering items that have neither a path nor a click handler.
           if (!hasNavigation) {
             return null;
           }

package/src/domains/settings/components/UserManagementTable.tsx

@@ -1,11 +1,5 @@
-/**
- * UserManagementTable — admin skeleton for the users screen.
- * Config-driven: rows and role catalog come in as props, role
- * changes delegate out.
- */
-
 import { DataTable, type Column } from "@umituz/web-design-system/organisms";
-import { useT } from "../../../i18n";
+import { useT } from "@umituz/web-localization/react";
 import { SETTINGS_ADMIN_KEYS } from "../utils/i18nKeys";
 import type { RoleKey, RoleInfo } from "../../permissions/types";
 
@@ -20,7 +14,6 @@ export interface ManagedUser {
 export interface UserManagementTableProps {
   users: ManagedUser[];
   roles: RoleInfo[];
-  /** Provide to render an editable role select per row. */
   onRoleChange?: (userId: string, role: RoleKey) => void;
 }
 

package/src/domains/settings/utils/i18nKeys.ts

@@ -1,9 +1,3 @@
-/**
- * Settings domain i18n keys (admin skeleton screens) — the
- * documented string contract. Column titles and role labels come
- * from props; only empty/denied states fall back to these keys.
- */
-
 export const SETTINGS_ADMIN_KEYS = {
   users: {
     empty: "settings.users.empty",

package/src/index.ts

@@ -1,13 +1,3 @@
-/**
- * @umituz/web-dashboard
- *
- * Dashboard Layout System - Customizable, themeable dashboard layouts
- * with comprehensive analytics services and config-based architecture.
- *
- * @version 3.0.0
- */
-
-// Core domains with complete public API
 export * from './domains/layouts';
 export * from './domains/settings';
 export * from './domains/calendar';
@@ -21,7 +11,6 @@ export {
   type User,
 } from './domains/auth';
 
-// Analytics with conflict resolution
 export {
   useAnalytics,
   MetricCard,
@@ -46,7 +35,6 @@ export {
   roundTo,
   generateColor,
   generateChartColors,
-  // Types
   type Metric,
   type TimeSeriesData,
   type ChartData,
@@ -66,13 +54,10 @@ export {
   type AnalyticsExportOptions,
 } from './domains/analytics';
 
-// Calendar
 export {
   useCalendar,
   calendarService,
-  // Services
   CalendarService,
-  // Utils
   getWeekDates,
   getMonthDays,
   isDateInRange,
@@ -80,8 +65,8 @@ export {
   isSameDay,
   getViewRange,
   generateTimeSlots,
-  // Types
   type ContentItem,
+  DEFAULT_CALENDAR_CONFIG,
   type CalendarEvent,
   type CalendarFilter,
   type CalendarConfig,
@@ -93,10 +78,8 @@ export {
   type ICalendarService,
 } from './domains/calendar';
 
-// Config with renamed exports to avoid conflicts
 export {
   DEFAULT_DASHBOARD_CONFIG,
-  DEFAULT_CALENDAR_CONFIG,
   type AnalyticsServiceType,
   type ExportFormat as DashboardExportFormat,
   type AnalyticsConfig as DashboardAnalyticsConfig,
@@ -104,4 +87,4 @@ export {
   type ChartsConfig,
   type PerformanceConfig as DashboardPerformanceConfig,
   type DashboardConfig as DashboardConfigType,
-} from './domain/config';
+} from './config';

package/src/styles/dashboard.contract.test.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const css = readFileSync(new URL("./dashboard.css", import.meta.url), "utf8");
+
+const defined = new Set([...css.matchAll(/(--udb-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+const used = new Set([...css.matchAll(/var\((--udb-[a-z0-9-]+)\)/g)].map((m) => m[1]));
+
+describe("dashboard stylesheet contract", () => {
+  it("defines every --udb variable it uses", () => {
+    expect([...used].filter((v) => !defined.has(v))).toEqual([]);
+  });
+
+  it("imports the design-system stylesheet", () => {
+    expect(css).toContain('@import "@umituz/web-design-system/styles.css";');
+  });
+
+  it("carries no legacy --u-* tokens", () => {
+    expect(css.match(/--u-[a-z0-9-]+/g) ?? []).toEqual([]);
+  });
+
+  it("reads only design-system variables that exist or are documented optional slots", () => {
+    const optional = new Set([
+      "--color-primary-hover",
+      "--color-primary-soft",
+      "--color-destructive-hover",
+      "--color-destructive-soft",
+      "--color-success-soft",
+      "--color-warning-soft",
+    ]);
+    const dsCss = readFileSync(
+      new URL("../../node_modules/@umituz/web-design-system/dist/styles.css", import.meta.url),
+      "utf8",
+    );
+    const dsDefined = new Set([...dsCss.matchAll(/(--[a-z][a-z0-9-]*)\s*:/g)].map((m) => m[1]));
+    const read = new Set([...css.matchAll(/var\((--[a-z][a-z0-9-]*)[,)]/g)].map((m) => m[1]));
+    const missing = [...read].filter(
+      (v) => !v.startsWith("--udb-") && !dsDefined.has(v) && !optional.has(v),
+    );
+    expect(missing).toEqual([]);
+  });
+});