@umituz/web-dashboard 5.0.1 → 6.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "5.0.1",
-  "description": "Installable app skeleton for the fleet — layouts, auth, analytics (dependency-free SVG charts), calendar, i18n via @umituz/web-localization, permissions/session/module registry; udb-* stylesheet on design-system tokens",
+  "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)",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -12,7 +12,6 @@
     ".": "./src/index.ts",
     "./styles.css": "./src/styles/dashboard.css",
     "./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",
@@ -25,11 +24,6 @@
     "./settings/hooks": "./src/domains/settings/hooks/index.ts",
     "./settings/utils": "./src/domains/settings/utils/index.ts",
     "./settings/types": "./src/domains/settings/types/index.ts",
-    "./auth": "./src/domains/auth/index.ts",
-    "./auth/components": "./src/domains/auth/components/index.ts",
-    "./auth/hooks": "./src/domains/auth/hooks/index.ts",
-    "./auth/utils": "./src/domains/auth/utils/index.ts",
-    "./auth/types": "./src/domains/auth/types/index.ts",
     "./analytics": "./src/domains/analytics/index.ts",
     "./analytics/components": "./src/domains/analytics/components/index.ts",
     "./analytics/hooks": "./src/domains/analytics/hooks/index.ts",
@@ -43,7 +37,9 @@
     "./calendar/utils": "./src/domains/calendar/utils/index.ts",
     "./config": "./src/config/index.ts",
     "./package.json": "./package.json",
-    "./charts": "./src/domains/charts/index.ts"
+    "./charts": "./src/domains/charts/index.ts",
+    "./onboarding": "./src/domains/onboarding/index.ts",
+    "./onboarding.css": "./src/domains/onboarding/onboarding.css"
   },
   "files": [
     "src",
@@ -61,12 +57,16 @@
   "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"
+    "react-router-dom": "^6.0.0 || ^7.0.0",
+    "framer-motion": "^12.0.0"
   },
   "dependencies": {
     "@umituz/web-design-system": "^4.8.1",
     "lucide-react": "^0.577.0",
-    "@umituz/web-localization": "^1.2.1"
+    "@umituz/web-localization": "^1.2.1",
+    "@radix-ui/react-progress": "^1.1.7",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
@@ -77,16 +77,15 @@
     "eslint": "^10.0.2",
     "react-router-dom": "^7.13.1",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "jsdom": "^29.1.1"
   },
   "keywords": [
     "dashboard",
     "layout",
     "settings",
-    "auth",
-    "authentication",
-    "login",
-    "register",
     "analytics",
     "analytics-services",
     "cohort-analysis",
@@ -112,7 +111,10 @@
     "sidebar",
     "header",
     "config-driven",
-    "package-driven"
+    "package-driven",
+    "onboarding",
+    "wizard",
+    "product-tour"
   ],
   "author": "umituz",
   "license": "MIT",

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

@@ -0,0 +1,181 @@
+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';
+
+// TEST_SCENARIOS.md §22
+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);
+  });
+});
+
+// TEST_SCENARIOS.md §22.2
+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);
+  });
+});
+
+// TEST_SCENARIOS.md §22.3
+describe('swipe-gesture-curve (§22.3)', () => {
+  it('registers right swipes only above the threshold', () => {
+    expect(didCrossRightSwipeThreshold(50)).toBe(false);
+    expect(didCrossRightSwipeThreshold(120)).toBe(false); // boundary is not "above"
+    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);
+  });
+});
+
+// TEST_SCENARIOS.md §22.4
+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);
+  });
+});
+
+// TEST_SCENARIOS.md §22.5
+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);
+  });
+});
+
+// TEST_SCENARIOS.md §22.6
+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');
+  });
+});
+
+// TEST_SCENARIOS.md §22.7
+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,33 @@
+/**
+ * Card stack motion math.
+ * Owns the scale/opacity transitions used by TinderCardsScreen and similar
+ * stack-style screens. Tuning these in one place keeps the stack feel consistent.
+ */
+
+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,16 @@
+/**
+ * Locale-aware count formatting.
+ * Used wherever a large count (e.g. "Trusted by 250,000+") is shown to the user.
+ * The consumer never has to call .toLocaleString() directly.
+ */
+
+/** Format a number for human display. e.g. 250000 -> "250,000" (en) / "250.000" (de-DE).
+ *  An omitted locale uses the host default; an invalid locale falls back to en-US. */
+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,24 @@
+/**
+ * Duration equal-split math.
+ * Splits a total processing duration into equal per-step slices.
+ * Falls back to a sensible default when the consumer doesn't provide a total.
+ */
+
+const DEFAULT_STEP_DURATION_MS = 1500;
+const MIN_PARTS = 1;
+
+/**
+ * Per-step duration when a total is given.
+ * Returns 0 if the total is unset OR the parts list is empty —
+ * never divides by zero.
+ */
+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;
+}
+
+/** The default per-step duration when the consumer omits the total. */
+export function getDefaultStepDurationMs(): number {
+  return DEFAULT_STEP_DURATION_MS;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Elapsed-millisecond math.
+ * Single source of truth for "how long did this take?".
+ */
+
+const ZERO_MS = 0;
+
+/** Milliseconds between two Dates. Never negative — clamps to 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,37 @@
+/**
+ * Progress percentage calculations.
+ * Owns the math for "how far are we through the flow?".
+ * Zero hardcoded fallbacks — every input is explicit.
+ */
+
+const ZERO_FRACTION = 0;
+const PERCENT_MULTIPLIER = 100;
+
+function defensiveDenominator(totalSteps: number): number {
+  // Defensive: an empty flow must report 0%, never NaN or Infinity.
+  return totalSteps > 0 ? totalSteps : 1;
+}
+
+function defensiveCurrentStep(currentStep: number, totalSteps: number): number {
+  if (currentStep < 0) return 0;
+  if (currentStep > totalSteps) return totalSteps;
+  return currentStep;
+}
+
+/** Progress as a 0..1 fraction. `1` means "all steps visited". */
+export function computeProgressFraction(currentStep: number, totalSteps: number): number {
+  if (totalSteps <= 0) return ZERO_FRACTION;
+  const safeCurrent = defensiveCurrentStep(currentStep, totalSteps);
+  return safeCurrent / defensiveDenominator(totalSteps);
+}
+
+/** Progress as a 0..100 percentage. Safe for the UI bar. */
+export function computeProgressPercentage(currentStep: number, totalSteps: number): number {
+  return computeProgressFraction(currentStep, totalSteps) * PERCENT_MULTIPLIER;
+}
+
+/** Number of steps remaining (including the current one). */
+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,44 @@
+/**
+ * Slider value math.
+ * Owns the bounds enforcement for preference sliders.
+ * Misconfigured bounds (min > max) are surfaced via console — never silently masked.
+ */
+
+const SLIDER_MIN_IF_UNSET = 0;
+const SLIDER_MAX_IF_UNSET = 100;
+
+/** Defensive bounds for a slider: if the config omits one, fall back to a sensible default. */
+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,
+  };
+}
+
+/** Were the configured bounds logically valid? */
+export function areSliderBoundsValid(min: number, max: number): boolean {
+  return min <= max;
+}
+
+/** Clamp a value into the [min, max] range, surfacing misconfigured bounds to the console. */
+export function clampValueToBounds(
+  value: number,
+  min: number,
+  max: number,
+  preferenceId: string,
+): number {
+  if (!areSliderBoundsValid(min, max)) {
+    // Surface the misconfiguration — never silently mask.
+     
+    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,28 @@
+/**
+ * Step index math.
+ * Owns the bounds for "where can the cursor be in the flow?".
+ * Pure, no React, no side effects.
+ */
+
+const MIN_INDEX = 0;
+const MIN_TOTAL_STEPS = 1;
+
+/** Clamp an arbitrary index into the valid [0, totalSteps-1] range. */
+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;
+}
+
+/** Move one step forward, stopping at the last step. */
+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);
+}
+
+/** Move one step backward, stopping at the first step. */
+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,67 @@
+/**
+ * Swipe gesture math.
+ * Owns every numeric value used by SwipeCard's drag/rotation/opacity curves.
+ * Centralizing them here means the gesture "feel" can be tuned in one place.
+ */
+
+const SWIPE_THRESHOLD_PX = 120;
+const DRAG_RANGE_PX = 200;
+/** Drag distance (px) at which the decision badges reach half opacity. */
+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;
+
+/** Minimum horizontal distance the user must drag to commit a swipe decision. */
+export const SWIPE_DECISION_THRESHOLD_PX = SWIPE_THRESHOLD_PX;
+
+/** Card rotation expressed in degrees, mapped from -200..+200 px drag. */
+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,
+];
+
+/** DISAGREE badge opacity curve, mapped from -200..0 px drag. */
+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,
+];
+
+/** AGREE badge opacity curve, mapped from 0..+200 px drag. */
+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,
+];
+
+/** Did the gesture cross the threshold to register as a right-swipe? */
+export function didCrossRightSwipeThreshold(offsetX: number): boolean {
+  return offsetX > SWIPE_THRESHOLD_PX;
+}
+
+/** Did the gesture cross the threshold to register as a left-swipe? */
+export function didCrossLeftSwipeThreshold(offsetX: number): boolean {
+  return offsetX < -SWIPE_THRESHOLD_PX;
+}