@umituz/web-dashboard 6.0.0 → 6.2.0

package/src/domains/onboarding/validation/stored-progress-check.ts

@@ -0,0 +1,59 @@
+export interface StoredProgressShape {
+  version: 1;
+  currentStep: number;
+  completedSteps: string[];
+  collected: Record<string, unknown>;
+  startedAt: string;   lastUpdated: string; }
+
+export type StoredProgressOutcome =
+  | { ok: true; data: StoredProgressShape }
+  | { ok: false; reason: string };
+
+const STORAGE_VERSION = 1;
+const MIN_STEP_INDEX = 0;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+
+function isIsoDateString(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms);
+}
+
+export function checkStoredProgress(raw: string | null): StoredProgressOutcome {
+  if (raw === null) return { ok: false, reason: 'no stored progress' };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      ok: false,
+      reason: e instanceof Error ? e.message : 'invalid JSON',
+    };
+  }
+  if (!isObject(parsed)) {
+    return { ok: false, reason: 'stored payload must be an object' };
+  }
+  if (parsed.version !== STORAGE_VERSION) {
+    return { ok: false, reason: `unsupported storage version: ${String(parsed.version)}` };
+  }
+  if (typeof parsed.currentStep !== 'number' || parsed.currentStep < MIN_STEP_INDEX) {
+    return { ok: false, reason: 'currentStep must be a non-negative number' };
+  }
+  if (!isStringArray(parsed.completedSteps)) {
+    return { ok: false, reason: 'completedSteps must be a string array' };
+  }
+  if (!isObject(parsed.collected)) {
+    return { ok: false, reason: 'collected must be an object' };
+  }
+  if (!isIsoDateString(parsed.startedAt) || !isIsoDateString(parsed.lastUpdated)) {
+    return { ok: false, reason: 'startedAt and lastUpdated must be ISO date strings' };
+  }
+  return { ok: true, data: parsed as unknown as StoredProgressShape };
+}

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

@@ -0,0 +1,170 @@
+import { describe, it, expect } from 'vitest';
+import { checkFlowStructure } from './flow-structure-check';
+import { checkScreenConfig, getRecognizedScreenTypes } from './screen-config-check';
+import { checkStoredProgress } from './stored-progress-check';
+import {
+  isRecognizedPermissionStatus,
+  normalizePermissionStatus,
+} from './permission-status-check';
+import type { OnboardingScreen } from '../types/screens';
+
+const welcome = (id = 'a'): OnboardingScreen => ({
+  id,
+  type: 'welcome',
+  title: 'T',
+});
+
+describe('flow-structure-check (§23.1)', () => {
+  it('rejects empty flows', () => {
+    expect(checkFlowStructure([])).toEqual({
+      ok: false,
+      reason: 'flow must contain at least one screen',
+    });
+  });
+
+  it('rejects duplicate step ids', () => {
+    const outcome = checkFlowStructure([welcome('dup'), welcome('dup')]);
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.reason).toMatch(/duplicate step id/);
+  });
+
+  it('accepts a valid flow and propagates per-screen failures', () => {
+    expect(checkFlowStructure([welcome('a'), welcome('b')])).toEqual({ ok: true });
+        const bad = checkFlowStructure([
+      welcome('a'),
+      { id: 'g', type: 'goal-question', question: 'Q', options: [], onChange: () => undefined },
+    ]);
+    expect(bad.ok).toBe(false);
+  });
+});
+
+describe('screen-config-check (§23.2)', () => {
+  it('rejects malformed screens', () => {
+    // @ts-expect-error -- deliberately malformed input (null is not a screen)
+    expect(checkScreenConfig(null).ok).toBe(false);
+    // @ts-expect-error -- deliberately malformed input (missing id)
+    expect(checkScreenConfig({ type: 'welcome' }).ok).toBe(false);
+    expect(checkScreenConfig({ id: '', type: 'welcome' } as OnboardingScreen).ok).toBe(false);
+    expect(
+      checkScreenConfig({ id: 'x', type: 'unknown' } as unknown as OnboardingScreen).ok,
+    ).toBe(false);
+    expect(
+      checkScreenConfig({ id: 'x', type: 'goal-question' } as OnboardingScreen).ok,
+    ).toBe(false);
+  });
+
+  it('requires content for content-driven screens', () => {
+    expect(
+      checkScreenConfig({
+        id: 'p',
+        type: 'pain-points',
+        painPoints: [],
+      } as unknown as OnboardingScreen).ok,
+    ).toBe(false);
+    expect(
+      checkScreenConfig({
+        id: 't',
+        type: 'tinder-cards',
+        statements: [],
+      } as unknown as OnboardingScreen).ok,
+    ).toBe(false);
+    expect(
+      checkScreenConfig({ id: 'pp', type: 'permission-priming' } as unknown as OnboardingScreen)
+        .ok,
+    ).toBe(false);
+    expect(
+      checkScreenConfig({ id: 'w', type: 'paywall', price: 9 } as unknown as OnboardingScreen).ok,
+    ).toBe(false);
+  });
+
+  it('accepts a well-formed screen', () => {
+    expect(checkScreenConfig(welcome('ok'))).toEqual({ ok: true });
+  });
+
+  it('knows every screen type the orchestrator can render', () => {
+    expect(getRecognizedScreenTypes().size).toBe(14);
+  });
+});
+
+describe('stored-progress-check (§23.3)', () => {
+  const validPayload = JSON.stringify({
+    version: 1,
+    currentStep: 2,
+    completedSteps: ['a', 'b'],
+    collected: { a: { selected: ['x'] } },
+    startedAt: '2026-01-01T10:00:00.000Z',
+    lastUpdated: '2026-01-01T10:01:00.000Z',
+  });
+
+  it('returns not-ok for missing, corrupt, or future-version payloads', () => {
+    expect(checkStoredProgress(null)).toEqual({ ok: false, reason: 'no stored progress' });
+    expect(checkStoredProgress('{ malformed').ok).toBe(false);
+    const v2 = checkStoredProgress(JSON.stringify({ version: 2 }));
+    expect(v2.ok).toBe(false);
+    if (!v2.ok) expect(v2.reason).toMatch(/unsupported storage version/);
+  });
+
+  it('rejects shape violations inside an otherwise-valid envelope', () => {
+    expect(
+      checkStoredProgress(
+        JSON.stringify({
+          version: 1,
+          currentStep: -1,
+          completedSteps: [],
+          collected: {},
+          startedAt: '2026-01-01T10:00:00.000Z',
+          lastUpdated: '2026-01-01T10:00:00.000Z',
+        }),
+      ).ok,
+    ).toBe(false);
+    expect(
+      checkStoredProgress(
+        JSON.stringify({
+          version: 1,
+          currentStep: 0,
+          completedSteps: 'nope',
+          collected: {},
+          startedAt: '2026-01-01T10:00:00.000Z',
+          lastUpdated: '2026-01-01T10:00:00.000Z',
+        }),
+      ).ok,
+    ).toBe(false);
+    expect(
+      checkStoredProgress(
+        JSON.stringify({
+          version: 1,
+          currentStep: 0,
+          completedSteps: [],
+          collected: {},
+          startedAt: 'not a date',
+          lastUpdated: '2026-01-01T10:00:00.000Z',
+        }),
+      ).ok,
+    ).toBe(false);
+  });
+
+  it('accepts a valid v1 payload and returns it typed', () => {
+    const outcome = checkStoredProgress(validPayload);
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) {
+      expect(outcome.data.currentStep).toBe(2);
+      expect(outcome.data.completedSteps).toEqual(['a', 'b']);
+    }
+  });
+});
+
+describe('permission-status-check (§23.4)', () => {
+  it('normalizes browser-level permission strings', () => {
+    expect(normalizePermissionStatus('granted')).toBe('granted');
+    expect(normalizePermissionStatus('denied')).toBe('denied');
+    expect(normalizePermissionStatus('default')).toBe('prompt');
+    expect(normalizePermissionStatus(null)).toBe('unsupported');
+    expect(normalizePermissionStatus('whatever')).toBe('unsupported');
+  });
+
+  it('recognizes exactly the four internal statuses', () => {
+    expect(isRecognizedPermissionStatus('prompt')).toBe(true);
+    expect(isRecognizedPermissionStatus('revoked')).toBe(false);
+    expect(isRecognizedPermissionStatus(42)).toBe(false);
+  });
+});

package/src/domains/permissions/hasPermission.ts

@@ -1,11 +1,3 @@
-/**
- * hasPermission — pure permission lookup against a matrix.
- *
- * Deny-by-default: unknown roles, unknown permissions and empty
- * grants all resolve to `false`. Only an exact entry, a module
- * wildcard ("sales.*") or the full wildcard ("*") grants access.
- */
-
 import {
   PERMISSION_WILDCARD,
   type Permission,

package/src/domains/permissions/types.ts

@@ -1,33 +1,13 @@
-/**
- * Permission model — generalized from the texora/visora fleet pattern.
- *
- * Hosts keep their own role and permission vocabularies (string unions
- * in the app); the package treats them as opaque strings and stays
- * camp-agnostic. A matrix maps each role to either the full-grant
- * wildcard `"*"` or a list of permission strings, which may themselves
- * end in `.*` to grant every permission of a module
- * (e.g. `"sales.*"` grants `"sales.view"`).
- */
-
-/** A single permission, e.g. "sales.view". Opaque to the package. */
 export type Permission = string;
 
-/** A role key, e.g. "owner", "operator". Opaque to the package. */
 export type RoleKey = string;
 
-/** Full-grant wildcard — grants every permission. */
 export const PERMISSION_WILDCARD = "*" as const;
 
-/**
- * What a role grants: the wildcard or an explicit permission list
- * (module wildcards like `"sales.*"` allowed).
- */
 export type RoleGrant = typeof PERMISSION_WILDCARD | readonly string[];
 
-/** Role x permission matrix. */
 export type PermissionMatrix = Readonly<Record<RoleKey, RoleGrant>>;
 
-/** Display metadata for a role (matrix screens). */
 export interface RoleInfo {
   key: RoleKey;
   label: string;

package/src/domains/settings/components/index.ts

@@ -1,7 +1,3 @@
-/**
- * Settings Components Export
- */
-
 export { SettingsLayout } from './SettingsLayout';
 export { SettingsSection } from './SettingsSection';
 export {

package/src/domains/settings/hooks/index.ts

@@ -1,7 +1,3 @@
-/**
- * Settings Hooks Export
- */
-
 export {
   useSettings,
 } from './useSettings';

package/src/domains/settings/hooks/useSettings.ts

@@ -1,26 +1,11 @@
-/**
- * Settings Hooks
- *
- * Custom React hooks for settings functionality.
- * Uses a single `useReducer` so the three update paths share one
- * well-tested tree-walking helper instead of duplicating it.
- */
-
 import { useReducer, useCallback } from "react";
 import type { SettingsConfig, SettingsItem } from "../types/settings";
 
-/**
- * Action discriminated union for the settings reducer.
- */
 type SettingsAction =
   | { type: 'updateItem'; sectionKey: string; itemKey: string; updates: Partial<SettingsItem> }
   | { type: 'toggleItem'; sectionKey: string; itemKey: string }
   | { type: 'setItemBadge'; sectionKey: string; itemKey: string; badge: number | undefined };
 
-/**
- * Apply a transform to the item identified by (sectionKey, itemKey).
- * Single source of truth for the tree-walking logic.
- */
 const mapItemInTree = (
   config: SettingsConfig,
   sectionKey: string,
@@ -48,8 +33,7 @@ const settingsReducer = (state: SettingsConfig, action: SettingsAction): Setting
     case 'toggleItem':
       return mapItemInTree(state, action.sectionKey, action.itemKey, (item) => ({
         ...item,
-        // Tri-state semantics: undefined is treated as enabled by default.
-        enabled: item.enabled === undefined ? false : !item.enabled,
+                enabled: item.enabled === undefined ? false : !item.enabled,
       }));
     case 'setItemBadge':
       return mapItemInTree(state, action.sectionKey, action.itemKey, (item) => ({
@@ -59,10 +43,6 @@ const settingsReducer = (state: SettingsConfig, action: SettingsAction): Setting
   }
 };
 
-/**
- * Public surface of the hook. Returned callbacks are stable
- * (no deps that change between renders).
- */
 export interface UseSettingsReturn {
   config: SettingsConfig;
   updateItem: (sectionKey: string, itemKey: string, updates: Partial<SettingsItem>) => void;
@@ -70,11 +50,6 @@ export interface UseSettingsReturn {
   setItemBadge: (sectionKey: string, itemKey: string, badge: number | undefined) => void;
 }
 
-/**
- * Use Settings Hook
- *
- * Manages settings configuration state and provides update actions.
- */
 export function useSettings(initialConfig: SettingsConfig): UseSettingsReturn {
   const [config, dispatch] = useReducer(settingsReducer, initialConfig);
 

package/src/domains/settings/index.ts

@@ -1,9 +1,3 @@
-/**
- * @umituz/web-dashboard - Settings Domain
- *
- * Config-driven Settings System
- */
-
 export { SettingsLayout, SettingsSection } from './components';
 export { useSettings } from './hooks';
 export {

package/src/domains/settings/types/index.ts

@@ -1,7 +1,3 @@
-/**
- * Settings Types Export
- */
-
 export type {
   SettingsItem,
   SettingsSection,

package/src/domains/settings/types/settings.ts

@@ -1,83 +1,39 @@
-/**
- * Settings Types
- *
- * Type definitions for settings system
- */
-
 import type { LucideIcon } from "lucide-react";
 
-/**
- * Settings item configuration
- */
 export interface SettingsItem {
-  /** Unique key for the setting */
-  key: string;
-  /** Display label (can be i18n key) */
-  label: string;
-  /** Description text (optional) */
-  description?: string;
-  /** Icon component */
-  icon?: LucideIcon;
-  /** Route path for this setting */
-  path?: string;
-  /** Click handler when no route is available */
-  onClick?: () => void;
-  /** Whether this item is enabled */
-  enabled?: boolean;
-  /** Required permission to access */
-  permission?: string;
-  /** Badge count (for notifications) */
-  badge?: number;
+    key: string;
+    label: string;
+    description?: string;
+    icon?: LucideIcon;
+    path?: string;
+    onClick?: () => void;
+    enabled?: boolean;
+    permission?: string;
+    badge?: number;
 }
 
-/**
- * Settings section configuration
- */
 export interface SettingsSection {
-  /** Section title */
-  title: string;
-  /** Section key */
-  key: string;
-  /** Items in this section */
-  items: SettingsItem[];
-  /** Optional: Section icon */
-  icon?: LucideIcon;
+    title: string;
+    key: string;
+    items: SettingsItem[];
+    icon?: LucideIcon;
 }
 
-/**
- * Settings layout configuration
- */
 export interface SettingsConfig {
-  /** Settings sections */
-  sections: SettingsSection[];
-  /** Brand name */
-  brandName?: string;
-  /** Default route */
-  defaultRoute?: string;
+    sections: SettingsSection[];
+    brandName?: string;
+    defaultRoute?: string;
 }
 
-/**
- * Settings layout props
- */
 export interface SettingsLayoutProps {
-  /** Settings configuration */
-  config: SettingsConfig;
-  /** Current path */
-  currentPath?: string;
-  /** On navigate callback */
-  onNavigate?: (path: string) => void;
+    config: SettingsConfig;
+    currentPath?: string;
+    onNavigate?: (path: string) => void;
 }
 
-/**
- * Settings section component props
- */
 export interface SettingsSectionProps {
-  /** Section configuration */
-  section: SettingsSection;
-  /** Current path */
-  currentPath?: string;
-  /** On navigate callback */
-  onNavigate?: (path: string) => void;
-  /** Collapsed state */
-  collapsed?: boolean;
+    section: SettingsSection;
+    currentPath?: string;
+    onNavigate?: (path: string) => void;
+    collapsed?: boolean;
 }

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

@@ -1,7 +1,3 @@
-/**
- * Settings Utils Export
- */
-
 export {
   findSettingsItem,
   findSettingsSection,

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

@@ -1,18 +1,5 @@
-/**
- * Settings Utilities
- *
- * Utility functions for settings operations
- */
-
 import type { SettingsConfig, SettingsItem, SettingsSection } from "../types/settings";
 
-/**
- * Find settings item by key
- *
- * @param config - Settings configuration
- * @param itemKey - Item key to find
- * @returns Item or undefined
- */
 export function findSettingsItem(config: SettingsConfig, itemKey: string): SettingsItem | undefined {
   for (const section of config.sections) {
     const item = section.items.find((i) => i.key === itemKey);
@@ -21,24 +8,10 @@ export function findSettingsItem(config: SettingsConfig, itemKey: string): Setti
   return undefined;
 }
 
-/**
- * Find settings section by key
- *
- * @param config - Settings configuration
- * @param sectionKey - Section key to find
- * @returns Section or undefined
- */
 export function findSettingsSection(config: SettingsConfig, sectionKey: string): SettingsSection | undefined {
   return config.sections.find((s) => s.key === sectionKey);
 }
 
-/**
- * Filter settings items by permission
- *
- * @param items - Settings items to filter
- * @param userPermissions - User permissions
- * @returns Filtered items
- */
 export function filterSettingsByPermission<T extends SettingsItem>(
   items: T[],
   userPermissions?: string[]
@@ -51,19 +24,8 @@ export function filterSettingsByPermission<T extends SettingsItem>(
   });
 }
 
-/**
- * Fallback route when no default or first available route can be resolved.
- * Caller should treat this as an explicit "no route configured" signal
- * rather than a silent success.
- */
 export const SETTINGS_FALLBACK_ROUTE = "/settings";
 
-/**
- * Get default route from settings config
- *
- * Returns null when no default route is resolvable. The caller is
- * responsible for handling that case (e.g. redirect, error).
- */
 export function getSettingsDefaultRoute(config: SettingsConfig): string | null {
   if (config.defaultRoute) return config.defaultRoute;
 
@@ -75,13 +37,6 @@ export function getSettingsDefaultRoute(config: SettingsConfig): string | null {
   return null;
 }
 
-/**
- * Generate settings item key
- *
- * @param prefix - Key prefix
- * @param identifier - Unique identifier
- * @returns Generated key
- */
 export function generateSettingsKey(prefix: string, identifier: string): string {
   return `${prefix}_${identifier}`;
 }

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

@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";