@umituz/web-dashboard 6.0.0 → 6.2.0

package/src/domains/layouts/types/user.ts

@@ -1,37 +1,16 @@
-/**
- * Dashboard Types - User
- *
- * Type definitions for user profile
- */
-
 import type { ComponentType } from "react";
 
-/**
- * User profile info for header
- */
 export interface DashboardUser {
-  /** User ID */
-  id: string;
-  /** Display name */
-  name?: string;
-  /** Email address */
-  email?: string;
-  /** Avatar URL */
-  avatar?: string;
-  /** Whether user has mobile app access */
-  hasMobileApp?: boolean;
-  /** Whether user has web app access */
-  hasWebApp?: boolean;
+    id: string;
+    name?: string;
+    email?: string;
+    avatar?: string;
+    hasMobileApp?: boolean;
+    hasWebApp?: boolean;
 }
 
-/**
- * Navigation item for user menu
- */
 export interface UserNavMenuItem {
-  /** Display label */
-  label: string;
-  /** Icon component */
-  icon: ComponentType<{ className?: string }>;
-  /** Route path */
-  path: string;
+    label: string;
+    icon: ComponentType<{ className?: string }>;
+    path: string;
 }

package/src/domains/layouts/utils/dashboard.ts

@@ -1,16 +1,3 @@
-/**
- * Dashboard Utilities
- *
- * Utility functions for dashboard operations
- */
-
-/**
- * Format notification timestamp to relative time
- *
- * @param createdAt - Notification creation timestamp
- * @param t - i18n translation function
- * @returns Formatted time string
- */
 export function formatNotificationTime(
   createdAt: Date | string | number,
   t: (key: string, params?: Record<string, unknown>) => string
@@ -24,61 +11,35 @@ export function formatNotificationTime(
   return t("dashboard.activityFeed.times.daysAgo", { val: Math.floor(secs / 86400) });
 }
 
-/**
- * Check if a path is active
- *
- * @param currentPath - Current location pathname
- * @param targetPath - Target path to check
- * @returns True if paths match
- */
 export function isPathActive(currentPath: string, targetPath: string): boolean {
   return currentPath === targetPath;
 }
 
-/**
- * Get page title from sidebar configuration
- *
- * @param pathname - Current pathname
- * @param sidebarGroups - Sidebar groups configuration
- * @param extraTitleMap - Extra title mappings
- * @returns Page title or null
- */
 export function getPageTitle(
   pathname: string,
   sidebarGroups: Array<{ items: Array<{ path: string; label: string }> }>,
   extraTitleMap?: Record<string, string>
 ): string | null {
-  // Search in sidebar groups
-  for (const group of sidebarGroups) {
+    for (const group of sidebarGroups) {
     const item = group.items.find((i) => i.path === pathname);
     if (item) return item.label;
   }
 
-  // Search in extra title map
-  if (extraTitleMap?.[pathname]) {
+    if (extraTitleMap?.[pathname]) {
     return extraTitleMap[pathname];
   }
 
   return null;
 }
 
-/**
- * Filter sidebar items by app type and enabled status
- *
- * @param items - Sidebar items to filter
- * @param user - Current user object
- * @returns Filtered items
- */
 export function filterSidebarItems<T extends { enabled?: boolean; requiredApp?: "mobile" | "web" }>(
   items: T[],
   user?: { hasMobileApp?: boolean; hasWebApp?: boolean }
 ): T[] {
   return items.filter((item) => {
-    // Skip disabled items
-    if (item.enabled === false) return false;
+        if (item.enabled === false) return false;
 
-    // Skip items that require specific app types
-    if (!item.requiredApp) return true;
+        if (!item.requiredApp) return true;
     if (item.requiredApp === "mobile") return user?.hasMobileApp ?? false;
     if (item.requiredApp === "web") return user?.hasWebApp ?? false;
 
@@ -86,11 +47,6 @@ export function filterSidebarItems<T extends { enabled?: boolean; requiredApp?:
   });
 }
 
-/**
- * Generate notification ID
- *
- * @returns Unique notification ID
- */
 export function generateNotificationId(): string {
   return crypto.randomUUID();
 }

package/src/domains/layouts/utils/index.ts

@@ -1,7 +1,3 @@
-/**
- * Layout Utils Export
- */
-
 export {
   formatNotificationTime,
   isPathActive,

package/src/domains/modules/build.tsx

@@ -1,14 +1,3 @@
-/**
- * buildRoutes / buildNav — derive route configs and sidebar groups
- * from a single DashboardModule list.
- *
- * - buildRoutes wraps every permissioned module's element in
- *   <RequirePermission>, so hosts only map the result to <Route>.
- * - buildNav filters by the same permissions via `can`, hides
- *   inNav:false detail routes, groups by navGroup (first-appearance
- *   order) and sorts items by `order` (stable for ties).
- */
-
 import type { ReactNode } from "react";
 import type { SidebarGroup } from "../layouts/types";
 import { RequirePermission } from "../permissions";
@@ -33,8 +22,7 @@ export const buildRoutes = (modules: readonly DashboardModule[]): RouteConfig[]
   }));
 
 export interface BuildNavOptions {
-  /** Permission check, e.g. usePermissions().can. */
-  can: (permission: Permission) => boolean;
+    can: (permission: Permission) => boolean;
 }
 
 export const buildNav = (
@@ -45,9 +33,7 @@ export const buildNav = (
     .filter((module) => module.inNav !== false)
     .filter((module) => !module.permission || can(module.permission));
 
-  // Groups keep their first-appearance order in the module list;
-  // `order` sorts items within their group.
-  const grouped = new Map<string, DashboardModule[]>();
+      const grouped = new Map<string, DashboardModule[]>();
   for (const module of visible) {
     const items = grouped.get(module.navGroup) ?? [];
     items.push(module);

package/src/domains/modules/types.ts

@@ -1,29 +1,14 @@
-/**
- * Dashboard module model — the single source of truth a host app
- * registers once per module; routes and sidebar nav are both derived
- * from it (see build.ts). Generalizes the texora/visora pattern
- * where MODULE_ROUTES and NAV_GROUPS were hand-kept in sync.
- */
-
 import type { ReactNode } from "react";
 import type { LucideIcon } from "lucide-react";
 import type { Permission } from "../permissions/types";
 
 export interface DashboardModule {
-  /** Route path (may contain params, e.g. "/sales/:id"). */
-  path: string;
-  /** i18n key (or plain label) for nav + page headers. */
-  labelKey: string;
-  /** lucide-react icon for the nav item. */
-  icon: LucideIcon;
-  /** Nav group title key — modules with the same key land in one group. */
-  navGroup: string;
-  /** Page content; permission-guarded automatically when `permission` is set. */
-  element: ReactNode;
-  /** Permission required to see/use this module (optional). */
-  permission?: Permission;
-  /** Sort weight inside its nav group (lower first, default last). */
-  order?: number;
-  /** Include in the nav (default true — set false for detail routes). */
-  inNav?: boolean;
+    path: string;
+    labelKey: string;
+    icon: LucideIcon;
+    navGroup: string;
+    element: ReactNode;
+    permission?: Permission;
+    order?: number;
+    inNav?: boolean;
 }

package/src/domains/onboarding/calc/calc.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  computeProgressFraction,
+  computeProgressPercentage,
+  computeRemainingSteps,
+} from './progress-percentage';
+import {
+  advanceStepIndex,
+  clampStepIndex,
+  retreatStepIndex,
+} from './step-index-clamp';
+import {
+  didCrossLeftSwipeThreshold,
+  didCrossRightSwipeThreshold,
+  SWIPE_DECISION_THRESHOLD_PX,
+} from './swipe-gesture-curve';
+import {
+  clampValueToBounds,
+  resolveSliderBounds,
+  areSliderBoundsValid,
+} from './slider-value-bounds';
+import {
+  getDefaultStepDurationMs,
+  splitTotalDuration,
+} from './duration-equal-split';
+import { elapsedMillis } from './elapsed-millis';
+import { formatCountWithLocale } from './count-with-locale';
+import {
+  getCardEnterAnimate,
+  getCardEnterExit,
+  getCardEnterInitial,
+  getCardTransitionDurationMs,
+} from './card-stack-motion-curve';
+
+describe('progress-percentage (§22.1)', () => {
+  it('computes percentages without NaN or Infinity', () => {
+    expect(computeProgressPercentage(0, 5)).toBe(0);
+    expect(computeProgressPercentage(5, 5)).toBe(100);
+    expect(computeProgressPercentage(0, 0)).toBe(0);
+    expect(computeProgressPercentage(-1, 5)).toBe(0);
+    expect(computeProgressPercentage(10, 5)).toBe(100);
+    expect(Number.isFinite(computeProgressPercentage(3, 7))).toBe(true);
+  });
+
+  it('computes the 0..1 fraction', () => {
+    expect(computeProgressFraction(1, 4)).toBe(0.25);
+    expect(computeProgressFraction(0, 0)).toBe(0);
+  });
+
+  it('counts remaining steps including the current one', () => {
+    expect(computeRemainingSteps(0, 5)).toBe(5);
+    expect(computeRemainingSteps(3, 5)).toBe(2);
+    expect(computeRemainingSteps(9, 5)).toBe(0);
+    expect(computeRemainingSteps(0, 0)).toBe(0);
+  });
+});
+
+describe('step-index-clamp (§22.2)', () => {
+  it('clamps arbitrary indices into range', () => {
+    expect(clampStepIndex(0, 5)).toBe(0);
+    expect(clampStepIndex(4, 5)).toBe(4);
+    expect(clampStepIndex(10, 5)).toBe(4);
+    expect(clampStepIndex(-1, 5)).toBe(0);
+    expect(clampStepIndex(0, 0)).toBe(0);
+  });
+
+  it('advances without going past the last step', () => {
+    expect(advanceStepIndex(3, 5)).toBe(4);
+    expect(advanceStepIndex(4, 5)).toBe(4);
+    expect(advanceStepIndex(0, 0)).toBe(0);
+  });
+
+  it('retreats without going below the first step', () => {
+    expect(retreatStepIndex(0)).toBe(0);
+    expect(retreatStepIndex(3)).toBe(2);
+  });
+});
+
+describe('swipe-gesture-curve (§22.3)', () => {
+  it('registers right swipes only above the threshold', () => {
+    expect(didCrossRightSwipeThreshold(50)).toBe(false);
+    expect(didCrossRightSwipeThreshold(120)).toBe(false);     expect(didCrossRightSwipeThreshold(150)).toBe(true);
+  });
+
+  it('registers left swipes only below the negative threshold', () => {
+    expect(didCrossLeftSwipeThreshold(-50)).toBe(false);
+    expect(didCrossLeftSwipeThreshold(-150)).toBe(true);
+  });
+
+  it('exposes the threshold as a single named constant', () => {
+    expect(SWIPE_DECISION_THRESHOLD_PX).toBe(120);
+  });
+});
+
+describe('slider-value-bounds (§22.4)', () => {
+  it('clamps values into bounds', () => {
+    expect(clampValueToBounds(50, 0, 100, 'x')).toBe(50);
+    expect(clampValueToBounds(-5, 0, 100, 'x')).toBe(0);
+    expect(clampValueToBounds(200, 0, 100, 'x')).toBe(100);
+  });
+
+  it('surfaces min > max misconfigurations via console.error, value as-is', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+      expect(clampValueToBounds(50, 100, 10, 'mood')).toBe(50);
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toContain('mood');
+      expect(errorSpy.mock.calls[0][0]).toContain('min > max');
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it('resolves unset bounds to sensible defaults', () => {
+    expect(resolveSliderBounds(undefined, undefined)).toEqual({ min: 0, max: 100 });
+    expect(areSliderBoundsValid(0, 100)).toBe(true);
+    expect(areSliderBoundsValid(100, 10)).toBe(false);
+  });
+});
+
+describe('duration-equal-split (§22.5)', () => {
+  it('splits a total duration evenly', () => {
+    expect(splitTotalDuration(3000, 3)).toBe(1000);
+  });
+
+  it('falls back to the default per-step duration when unset or invalid', () => {
+    expect(splitTotalDuration(0, 3)).toBe(1500);
+    expect(splitTotalDuration(undefined, 3)).toBe(1500);
+    expect(getDefaultStepDurationMs()).toBe(1500);
+  });
+
+  it('never divides by zero', () => {
+    expect(splitTotalDuration(3000, 0)).toBe(3000);
+  });
+});
+
+describe('count-with-locale (§22.6)', () => {
+  it('formats counts for human display', () => {
+    expect(formatCountWithLocale(250000, 'en-US')).toBe('250,000');
+  });
+
+  it('formats with an explicit non-English locale', () => {
+    expect(formatCountWithLocale(250000, 'de-DE')).toBe('250.000');
+  });
+
+  it('maps non-finite input to "0"', () => {
+    expect(formatCountWithLocale(Number.NaN)).toBe('0');
+    expect(formatCountWithLocale(Number.POSITIVE_INFINITY)).toBe('0');
+  });
+});
+
+describe('elapsed-millis (§22.7)', () => {
+  it('returns the positive difference', () => {
+    const start = new Date('2026-01-01T10:00:00Z');
+    const end = new Date('2026-01-01T10:00:30Z');
+    expect(elapsedMillis(start, end)).toBe(30_000);
+  });
+
+  it('clamps negative differences to zero', () => {
+    const start = new Date('2026-01-01T10:00:30Z');
+    const end = new Date('2026-01-01T10:00:00Z');
+    expect(elapsedMillis(start, end)).toBe(0);
+  });
+});
+
+describe('card-stack-motion-curve', () => {
+  it('exposes consistent enter/exit states', () => {
+    expect(getCardEnterInitial()).toEqual({ opacity: 0, scale: 0.95 });
+    expect(getCardEnterAnimate()).toEqual({ opacity: 1, scale: 1 });
+    expect(getCardEnterExit()).toEqual({ opacity: 0, scale: 1.05 });
+    expect(getCardTransitionDurationMs()).toBeGreaterThan(0);
+  });
+});

package/src/domains/onboarding/calc/card-stack-motion-curve.ts

@@ -0,0 +1,27 @@
+const MOTION_ENTER_DURATION_MS = 250;
+const INITIAL_SCALE = 0.95;
+const STEADY_SCALE = 1;
+const EXIT_SCALE = 1.05;
+const HIDDEN_OPACITY = 0;
+const VISIBLE_OPACITY = 1;
+
+export interface CardMotionState {
+  readonly opacity: number;
+  readonly scale: number;
+}
+
+export function getCardEnterInitial(): CardMotionState {
+  return { opacity: HIDDEN_OPACITY, scale: INITIAL_SCALE };
+}
+
+export function getCardEnterAnimate(): CardMotionState {
+  return { opacity: VISIBLE_OPACITY, scale: STEADY_SCALE };
+}
+
+export function getCardEnterExit(): CardMotionState {
+  return { opacity: HIDDEN_OPACITY, scale: EXIT_SCALE };
+}
+
+export function getCardTransitionDurationMs(): number {
+  return MOTION_ENTER_DURATION_MS;
+}

package/src/domains/onboarding/calc/count-with-locale.ts

@@ -0,0 +1,8 @@
+export function formatCountWithLocale(value: number, locale?: string): string {
+  if (!Number.isFinite(value)) return '0';
+  try {
+    return value.toLocaleString(locale);
+  } catch {
+    return value.toLocaleString('en-US');
+  }
+}

package/src/domains/onboarding/calc/duration-equal-split.ts

@@ -0,0 +1,12 @@
+const DEFAULT_STEP_DURATION_MS = 1500;
+const MIN_PARTS = 1;
+
+export function splitTotalDuration(totalMs: number | undefined, parts: number): number {
+  if (totalMs === undefined || totalMs <= 0) return DEFAULT_STEP_DURATION_MS;
+  const safeParts = Math.max(MIN_PARTS, parts);
+  return totalMs / safeParts;
+}
+
+export function getDefaultStepDurationMs(): number {
+  return DEFAULT_STEP_DURATION_MS;
+}

package/src/domains/onboarding/calc/elapsed-millis.ts

@@ -0,0 +1,6 @@
+const ZERO_MS = 0;
+
+export function elapsedMillis(start: Date, end: Date): number {
+  const diff = end.getTime() - start.getTime();
+  return diff > ZERO_MS ? diff : ZERO_MS;
+}

package/src/domains/onboarding/calc/index.ts

@@ -0,0 +1,36 @@
+export {
+  computeProgressFraction,
+  computeProgressPercentage,
+  computeRemainingSteps,
+} from './progress-percentage';
+export {
+  clampStepIndex,
+  advanceStepIndex,
+  retreatStepIndex,
+} from './step-index-clamp';
+export {
+  SWIPE_DECISION_THRESHOLD_PX,
+  SWIPE_ROTATION_RANGE,
+  SWIPE_ROTATION_VALUES,
+  SWIPE_LEFT_OPACITY_INPUT,
+  SWIPE_LEFT_OPACITY_VALUES,
+  SWIPE_RIGHT_OPACITY_INPUT,
+  SWIPE_RIGHT_OPACITY_VALUES,
+  didCrossRightSwipeThreshold,
+  didCrossLeftSwipeThreshold,
+} from './swipe-gesture-curve';
+export type { CardMotionState } from './card-stack-motion-curve';
+export {
+  getCardEnterInitial,
+  getCardEnterAnimate,
+  getCardEnterExit,
+  getCardTransitionDurationMs,
+} from './card-stack-motion-curve';
+export {
+  resolveSliderBounds,
+  areSliderBoundsValid,
+  clampValueToBounds,
+} from './slider-value-bounds';
+export { splitTotalDuration, getDefaultStepDurationMs } from './duration-equal-split';
+export { formatCountWithLocale } from './count-with-locale';
+export { elapsedMillis } from './elapsed-millis';

package/src/domains/onboarding/calc/progress-percentage.ts

@@ -0,0 +1,27 @@
+const ZERO_FRACTION = 0;
+const PERCENT_MULTIPLIER = 100;
+
+function defensiveDenominator(totalSteps: number): number {
+    return totalSteps > 0 ? totalSteps : 1;
+}
+
+function defensiveCurrentStep(currentStep: number, totalSteps: number): number {
+  if (currentStep < 0) return 0;
+  if (currentStep > totalSteps) return totalSteps;
+  return currentStep;
+}
+
+export function computeProgressFraction(currentStep: number, totalSteps: number): number {
+  if (totalSteps <= 0) return ZERO_FRACTION;
+  const safeCurrent = defensiveCurrentStep(currentStep, totalSteps);
+  return safeCurrent / defensiveDenominator(totalSteps);
+}
+
+export function computeProgressPercentage(currentStep: number, totalSteps: number): number {
+  return computeProgressFraction(currentStep, totalSteps) * PERCENT_MULTIPLIER;
+}
+
+export function computeRemainingSteps(currentStep: number, totalSteps: number): number {
+  if (totalSteps <= 0) return 0;
+  return Math.max(0, totalSteps - defensiveCurrentStep(currentStep, totalSteps));
+}

package/src/domains/onboarding/calc/slider-value-bounds.ts

@@ -0,0 +1,34 @@
+const SLIDER_MIN_IF_UNSET = 0;
+const SLIDER_MAX_IF_UNSET = 100;
+
+export function resolveSliderBounds(
+  min: number | undefined,
+  max: number | undefined,
+): { min: number; max: number } {
+  return {
+    min: min ?? SLIDER_MIN_IF_UNSET,
+    max: max ?? SLIDER_MAX_IF_UNSET,
+  };
+}
+
+export function areSliderBoundsValid(min: number, max: number): boolean {
+  return min <= max;
+}
+
+export function clampValueToBounds(
+  value: number,
+  min: number,
+  max: number,
+  preferenceId: string,
+): number {
+  if (!areSliderBoundsValid(min, max)) {
+         
+    console.error(
+      `[web-onboarding] preference "${preferenceId}" has min > max (${min} > ${max}); returning value as-is.`,
+    );
+    return value;
+  }
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+}

package/src/domains/onboarding/calc/step-index-clamp.ts

@@ -0,0 +1,19 @@
+const MIN_INDEX = 0;
+const MIN_TOTAL_STEPS = 1;
+
+export function clampStepIndex(index: number, totalSteps: number): number {
+  if (totalSteps < MIN_TOTAL_STEPS) return MIN_INDEX;
+  if (index < MIN_INDEX) return MIN_INDEX;
+  if (index > totalSteps - MIN_TOTAL_STEPS) return totalSteps - MIN_TOTAL_STEPS;
+  return index;
+}
+
+export function advanceStepIndex(currentIndex: number, totalSteps: number): number {
+  if (totalSteps < MIN_TOTAL_STEPS) return MIN_INDEX;
+  const lastIndex = totalSteps - MIN_TOTAL_STEPS;
+  return Math.min(currentIndex + MIN_TOTAL_STEPS, lastIndex);
+}
+
+export function retreatStepIndex(currentIndex: number): number {
+  return Math.max(MIN_INDEX, currentIndex - MIN_TOTAL_STEPS);
+}

package/src/domains/onboarding/calc/swipe-gesture-curve.ts

@@ -0,0 +1,54 @@
+const SWIPE_THRESHOLD_PX = 120;
+const DRAG_RANGE_PX = 200;
+const OPACITY_MIDPOINT_PX = 50;
+const FULL_OPACITY = 1;
+const HALF_OPACITY = 0.5;
+const ZERO_OPACITY = 0;
+const MAX_ROTATION_DEG = 15;
+const ZERO_ROTATION_DEG = 0;
+
+export const SWIPE_DECISION_THRESHOLD_PX = SWIPE_THRESHOLD_PX;
+
+export const SWIPE_ROTATION_RANGE: [number, number, number] = [
+  -DRAG_RANGE_PX,
+  ZERO_ROTATION_DEG,
+  DRAG_RANGE_PX,
+];
+
+export const SWIPE_ROTATION_VALUES: [number, number, number] = [
+  -MAX_ROTATION_DEG,
+  ZERO_ROTATION_DEG,
+  MAX_ROTATION_DEG,
+];
+
+export const SWIPE_LEFT_OPACITY_INPUT: [number, number, number] = [
+  -DRAG_RANGE_PX,
+  -OPACITY_MIDPOINT_PX,
+  0,
+];
+
+export const SWIPE_LEFT_OPACITY_VALUES: [number, number, number] = [
+  FULL_OPACITY,
+  HALF_OPACITY,
+  ZERO_OPACITY,
+];
+
+export const SWIPE_RIGHT_OPACITY_INPUT: [number, number, number] = [
+  0,
+  OPACITY_MIDPOINT_PX,
+  DRAG_RANGE_PX,
+];
+
+export const SWIPE_RIGHT_OPACITY_VALUES: [number, number, number] = [
+  ZERO_OPACITY,
+  HALF_OPACITY,
+  FULL_OPACITY,
+];
+
+export function didCrossRightSwipeThreshold(offsetX: number): boolean {
+  return offsetX > SWIPE_THRESHOLD_PX;
+}
+
+export function didCrossLeftSwipeThreshold(offsetX: number): boolean {
+  return offsetX < -SWIPE_THRESHOLD_PX;
+}