@umituz/web-dashboard 6.1.0 → 6.2.0

package/src/domains/onboarding/types/screens.ts

@@ -1,10 +1,5 @@
 import type { ReactNode } from 'react';
 
-/**
- * Discriminated union: every screen is one of 14 strictly-typed shapes.
- * Eliminates `Record<string, any>` masking (project rule: no `any`).
- */
-
 export interface BaseScreen<T extends string, D = unknown> {
   id: string;
   type: T;
@@ -19,8 +14,7 @@ export interface OnboardingOption {
   id: string;
   label: string;
   description?: string;
-  iconName?: string; // lucide-react icon name; resolved by UI layer
-  image?: string;
+  iconName?: string;   image?: string;
 }
 
 export type WelcomeScreenConfig = BaseScreen<'welcome'> & {
@@ -131,8 +125,7 @@ export type ValueDeliveryScreenConfig<TResult = unknown> = BaseScreen<
 > & {
   title: string;
   result: TResult;
-  /** Optional share affordance. Uses the Web Share API with a clipboard fallback. */
-  shareConfig?: {
+    shareConfig?: {
     text: string;
     url?: string;
   };
@@ -148,8 +141,7 @@ export type AccountGateScreenConfig = BaseScreen<'account-gate', { signedIn: boo
 };
 
 export type PaywallFeature = {
-  iconName: string; // lucide-react
-  text: string;
+  iconName: string;   text: string;
   highlighted?: boolean;
 };
 

package/src/domains/onboarding/utils/analytics-dispatch.ts

@@ -1,21 +1,8 @@
-/**
- * Analytics dispatch service.
- * Routes a typed onboarding event to the configured provider.
- * Provider-specific dispatch is isolated here; callers stay provider-agnostic.
- *
- * Contract: dispatch NEVER throws. Analytics is an observation channel — a
- * broken tracker must not take down the onboarding funnel. Failures are
- * surfaced to the console (the library's documented error channel) and
- * dropped.
- */
-
 import type {
   AnalyticsProvider,
   OnboardingAnalyticsEvent,
 } from '../types/config';
 
-/** Provider globals are read through a LOCAL view of `window` — this package
- * must never augment the global `Window` type for its consumers. */
 type AnalyticsWindow = Window & {
   gtag?: (...args: unknown[]) => void;
   amplitude?: {
@@ -25,8 +12,7 @@ type AnalyticsWindow = Window & {
 };
 
 function dispatchToProvider(event: OnboardingAnalyticsEvent, provider: AnalyticsProvider): void {
-  if (typeof window === 'undefined') return; // SSR / non-browser: nothing to do.
-  const win = window as AnalyticsWindow;
+  if (typeof window === 'undefined') return;   const win = window as AnalyticsWindow;
   switch (provider) {
     case 'google-analytics':
       win.gtag?.('event', event.name, event as unknown as Record<string, unknown>);
@@ -40,8 +26,7 @@ function dispatchToProvider(event: OnboardingAnalyticsEvent, provider: Analytics
       win.mixpanel?.track(event.name, event as unknown as Record<string, unknown>);
       return;
     case 'custom':
-      return; // Handled by the caller via the customTracker path.
-  }
+      return;   }
 }
 
 function dispatchToCustomTracker(
@@ -59,10 +44,6 @@ function dispatchToCustomTracker(
   customTracker(event);
 }
 
-/**
- * Routes an event to the configured provider. Never throws: provider failures
- * are logged and dropped so an analytics outage cannot break the flow UI.
- */
 export function dispatchAnalyticsEvent(
   event: OnboardingAnalyticsEvent,
   provider: AnalyticsProvider | undefined,

package/src/domains/onboarding/utils/default-storage-key.ts

@@ -1,2 +1 @@
-/** Default localStorage key for onboarding progress. */
 export const defaultStorageKey = '@umituz/web-onboarding:progress';

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

@@ -9,5 +9,4 @@ export type { RehydratedProgress } from './local-storage-bridge';
 export { queryPermissionStatus, requestPermission } from './permission-bridge';
 export { defaultStorageKey } from './default-storage-key';
 
-// Re-export validation for convenience (the public API treats validation as a util).
 export { checkFlowStructure, checkScreenConfig, checkStoredProgress } from '../validation';

package/src/domains/onboarding/utils/local-storage-bridge.ts

@@ -1,9 +1,3 @@
-/**
- * localStorage bridge for onboarding progress.
- * Owns the I/O — validation, parsing, and the schema version are delegated
- * to the validation module so this file is a thin persistence layer.
- */
-
 import { elapsedMillis } from '../calc/elapsed-millis';
 import { isLocalStorageAvailable } from '../predicates/storage-available';
 import { checkStoredProgress } from '../validation/stored-progress-check';
@@ -22,10 +16,6 @@ function buildKey(customKey: string | undefined): string {
   return customKey ?? defaultStorageKey;
 }
 
-/**
- * Save the current progress to localStorage. Returns true on success.
- * Surfaces persistence failures to the console; never silently masks them.
- */
 export function saveOnboardingProgress(
   key: string | undefined,
   payload: {
@@ -55,18 +45,13 @@ export function saveOnboardingProgress(
   }
 }
 
-/**
- * Load and validate a previously saved progress payload.
- * Returns null if storage is unavailable, nothing is stored, or the payload is corrupt.
- */
 export function loadOnboardingProgress(key: string | undefined): RehydratedProgress | null {
   if (!isLocalStorageAvailable()) return null;
   const raw = window.localStorage.getItem(buildKey(key));
   const checked = checkStoredProgress(raw);
   if (!checked.ok) {
     if (raw !== null) {
-      // Corrupt payload — discard so future saves start clean.
-      window.localStorage.removeItem(buildKey(key));
+            window.localStorage.removeItem(buildKey(key));
     }
     return null;
   }
@@ -79,16 +64,11 @@ export function loadOnboardingProgress(key: string | undefined): RehydratedProgr
   };
 }
 
-/** Remove the stored payload. Safe to call when nothing is stored. */
 export function clearOnboardingProgress(key: string | undefined): void {
   if (!isLocalStorageAvailable()) return;
   window.localStorage.removeItem(buildKey(key));
 }
 
-/**
- * Build the final `OnboardingResult` value the consumer receives via
- * `onComplete`. Owns the duration calculation; no magic numbers here.
- */
 export function buildOnboardingResult(input: {
   completedSteps: ReadonlyArray<string>;
   collected: Record<string, unknown>;

package/src/domains/onboarding/utils/permission-bridge.ts

@@ -1,9 +1,3 @@
-/**
- * Browser permission API bridge.
- * Owns the I/O — the predicates and the validation module decide whether
- * the runtime supports the call, and how to normalize the raw status.
- */
-
 import {
   doesBrowserSupportMediaCapture,
   doesBrowserSupportGeolocation,
@@ -14,7 +8,6 @@ import type { PermissionStatus, PermissionType } from '../types/screens';
 
 const GEOLOCATION_TIMEOUT_MS = 5000;
 
-/** Read the current permission status without prompting the user. */
 export async function queryPermissionStatus(permission: PermissionType): Promise<PermissionStatus> {
   if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
 
@@ -51,7 +44,6 @@ export async function queryPermissionStatus(permission: PermissionType): Promise
   }
 }
 
-/** Prompt the user for the given permission. Never throws — failures map to a status. */
 export async function requestPermission(permission: PermissionType): Promise<PermissionStatus> {
   if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
 

package/src/domains/onboarding/validation/flow-structure-check.ts

@@ -5,12 +5,6 @@ export type ValidationOutcome = { ok: true } | { ok: false; reason: string };
 
 const MIN_FLOW_LENGTH = 1;
 
-/**
- * Validates the structure of an entire onboarding flow:
- *  - At least one screen exists
- *  - Every screen passes its own check
- *  - Step IDs are unique
- */
 export function checkFlowStructure(screens: ReadonlyArray<OnboardingScreen>): ValidationOutcome {
   if (!Array.isArray(screens) || screens.length < MIN_FLOW_LENGTH) {
     return { ok: false, reason: 'flow must contain at least one screen' };

package/src/domains/onboarding/validation/permission-status-check.ts

@@ -7,15 +7,10 @@ const RECOGNIZED_STATUSES: ReadonlySet<PermissionStatus> = new Set<PermissionSta
   'unsupported',
 ]);
 
-/** Is the given string one of the recognized permission statuses? */
 export function isRecognizedPermissionStatus(value: unknown): value is PermissionStatus {
   return typeof value === 'string' && RECOGNIZED_STATUSES.has(value as PermissionStatus);
 }
 
-/**
- * Normalize a browser-level permission string (which may be "default")
- * to our internal PermissionStatus enum.
- */
 export function normalizePermissionStatus(rawValue: string | null | undefined): PermissionStatus {
   if (rawValue === 'granted' || rawValue === 'denied') return rawValue;
   if (rawValue === 'default' || rawValue === 'prompt') return 'prompt';

package/src/domains/onboarding/validation/screen-config-check.ts

@@ -66,10 +66,6 @@ function checkPaywall(screen: OnboardingScreen): ValidationOutcome {
   return { ok: true };
 }
 
-/**
- * Validates a single screen config. Per-screen rules live here so the file
- * is the single place to look when a new screen type is added.
- */
 export function checkScreenConfig(screen: OnboardingScreen): ValidationOutcome {
   if (!isPlainObject(screen)) {
     return { ok: false, reason: 'screen must be an object' };
@@ -99,7 +95,6 @@ export function checkScreenConfig(screen: OnboardingScreen): ValidationOutcome {
   }
 }
 
-/** The set of screen types the orchestrator knows how to render. */
 export function getRecognizedScreenTypes(): ReadonlySet<OnboardingScreenType> {
   return RECOGNIZED_SCREEN_TYPES;
 }

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

@@ -1,17 +1,9 @@
-/**
- * Storage payload integrity check.
- * Decides whether a localStorage string is something we can safely rehydrate
- * from. The shape is versioned so future migrations stay clean.
- */
-
 export interface StoredProgressShape {
   version: 1;
   currentStep: number;
   completedSteps: string[];
   collected: Record<string, unknown>;
-  startedAt: string; // ISO
-  lastUpdated: string; // ISO
-}
+  startedAt: string;   lastUpdated: string; }
 
 export type StoredProgressOutcome =
   | { ok: true; data: StoredProgressShape }
@@ -34,7 +26,6 @@ function isIsoDateString(value: unknown): value is string {
   return Number.isFinite(ms);
 }
 
-/** Is the raw string a valid, current-version stored progress payload? */
 export function checkStoredProgress(raw: string | null): StoredProgressOutcome {
   if (raw === null) return { ok: false, reason: 'no stored progress' };
   let parsed: unknown;

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

@@ -8,7 +8,6 @@ import {
 } from './permission-status-check';
 import type { OnboardingScreen } from '../types/screens';
 
-// TEST_SCENARIOS.md §23
 const welcome = (id = 'a'): OnboardingScreen => ({
   id,
   type: 'welcome',
@@ -31,8 +30,7 @@ describe('flow-structure-check (§23.1)', () => {
 
   it('accepts a valid flow and propagates per-screen failures', () => {
     expect(checkFlowStructure([welcome('a'), welcome('b')])).toEqual({ ok: true });
-    // goal-question without options fails at the flow level
-    const bad = checkFlowStructure([
+        const bad = checkFlowStructure([
       welcome('a'),
       { id: 'g', type: 'goal-question', question: 'Q', options: [], onChange: () => undefined },
     ]);
@@ -40,7 +38,6 @@ describe('flow-structure-check (§23.1)', () => {
   });
 });
 
-// TEST_SCENARIOS.md §23.2
 describe('screen-config-check (§23.2)', () => {
   it('rejects malformed screens', () => {
     // @ts-expect-error -- deliberately malformed input (null is not a screen)
@@ -89,7 +86,6 @@ describe('screen-config-check (§23.2)', () => {
   });
 });
 
-// TEST_SCENARIOS.md §23.3
 describe('stored-progress-check (§23.3)', () => {
   const validPayload = JSON.stringify({
     version: 1,
@@ -157,7 +153,6 @@ describe('stored-progress-check (§23.3)', () => {
   });
 });
 
-// TEST_SCENARIOS.md §23.4
 describe('permission-status-check (§23.4)', () => {
   it('normalizes browser-level permission strings', () => {
     expect(normalizePermissionStatus('granted')).toBe('granted');

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}`;
 }