@umituz/web-dashboard 6.0.0 → 6.1.0

package/src/domains/onboarding/predicates/icon-name-resolves.ts

@@ -0,0 +1,113 @@
+/**
+ * Icon name registry.
+ *
+ * Consumers configure icons by string name (`iconName`, `heroIconName`).
+ * The library resolves those names against a CURATED, STATICALLY-IMPORTED set
+ * of lucide-react icons. A static registry is what keeps the published bundle
+ * small: a namespace import (`import * as Icons`) with dynamic lookup would
+ * force every one of lucide's ~1,500 icons into the consumer's bundle.
+ *
+ * Icons not in the registry simply do not render (callers fall back to a
+ * default or hide the icon slot). See README "Icons" for the full list.
+ */
+import type { LucideIcon } from 'lucide-react';
+import {
+  Activity,
+  AlertTriangle,
+  Apple,
+  Award,
+  Ban,
+  Bell,
+  BookOpen,
+  Camera,
+  Check,
+  CheckCircle2,
+  Download,
+  Dumbbell,
+  GraduationCap,
+  Headphones,
+  HeartPulse,
+  Image,
+  Infinity as InfinityIcon,
+  Lock,
+  MapPin,
+  MessageCircle,
+  Mic,
+  Moon,
+  Palette,
+  PenTool,
+  Play,
+  Rocket,
+  Rewind,
+  Share2,
+  Shield,
+  ShieldCheck,
+  Smile,
+  Sparkles,
+  Square,
+  Star,
+  Theater,
+  Tv,
+  Users,
+  X,
+  Zap,
+} from 'lucide-react';
+
+const ICON_REGISTRY: Readonly<Record<string, LucideIcon>> = {
+  Activity,
+  AlertTriangle,
+  Apple,
+  Award,
+  Ban,
+  Bell,
+  BookOpen,
+  Camera,
+  Check,
+  CheckCircle2,
+  Download,
+  Dumbbell,
+  GraduationCap,
+  Headphones,
+  HeartPulse,
+  Image,
+  // `Infinity` is a reserved word — the lucide export is aliased at import.
+  Infinity: InfinityIcon,
+  Lock,
+  MapPin,
+  MessageCircle,
+  Mic,
+  Moon,
+  Palette,
+  PenTool,
+  Play,
+  Rocket,
+  Rewind,
+  Share2,
+  Shield,
+  ShieldCheck,
+  Smile,
+  Sparkles,
+  Square,
+  Star,
+  Theater,
+  Tv,
+  Users,
+  X,
+  Zap,
+};
+
+/** The icon names this package can resolve without application help. */
+export function getRegisteredIconNames(): ReadonlyArray<string> {
+  return Object.keys(ICON_REGISTRY);
+}
+
+/** Does the given name resolve to an icon bundled with this package? */
+export function doesIconNameResolve(name: string | undefined): boolean {
+  return typeof name === 'string' && name in ICON_REGISTRY;
+}
+
+/** Resolve a bundled icon by name. Returns null when the name is unknown. */
+export function resolveIconByName(name: string | undefined): LucideIcon | null {
+  if (!doesIconNameResolve(name)) return null;
+  return ICON_REGISTRY[name as string];
+}

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

@@ -0,0 +1,26 @@
+export {
+  isPermissionGranted,
+  isPermissionDenied,
+  isPermissionPrompt,
+  isPermissionUnsupported,
+  isPermissionDecided,
+} from './permission-granted';
+export {
+  doesBrowserSupportNotifications,
+  doesBrowserSupportMediaCapture,
+  doesBrowserSupportGeolocation,
+  isRuntimeSupportMissing,
+} from './permission-supports';
+export { isLocalStorageAvailable } from './storage-available';
+export {
+  doesIconNameResolve,
+  resolveIconByName,
+  getRegisteredIconNames,
+} from './icon-name-resolves';
+export {
+  hasOnRequest,
+  hasOnAccept,
+  hasOnSignIn,
+  accountGateAllowsSkip,
+} from './has-handler';
+export { screenEmitsData } from './screen-emits-data';

package/src/domains/onboarding/predicates/permission-granted.ts

@@ -0,0 +1,26 @@
+import type { PermissionStatus } from '../types/screens';
+
+/** Is the permission currently granted by the user? */
+export function isPermissionGranted(status: PermissionStatus): boolean {
+  return status === 'granted';
+}
+
+/** Did the user explicitly deny this permission? */
+export function isPermissionDenied(status: PermissionStatus): boolean {
+  return status === 'denied';
+}
+
+/** Is the permission in the initial "ask the user" state? */
+export function isPermissionPrompt(status: PermissionStatus): boolean {
+  return status === 'prompt';
+}
+
+/** Does the current runtime lack support for this permission? */
+export function isPermissionUnsupported(status: PermissionStatus): boolean {
+  return status === 'unsupported';
+}
+
+/** Has the permission been decided one way or the other? (granted OR denied) */
+export function isPermissionDecided(status: PermissionStatus): boolean {
+  return status === 'granted' || status === 'denied';
+}

package/src/domains/onboarding/predicates/permission-supports.ts

@@ -0,0 +1,66 @@
+/**
+ * Browser-feature predicates for the runtime.
+ * Each predicate answers "does the user's browser/environment support this API?".
+ */
+
+import type { PermissionType } from '../types/screens';
+
+declare const navigator: undefined | {
+  mediaDevices?: { getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream> };
+  geolocation?: {
+    getCurrentPosition: (
+      success: (pos: GeolocationPosition) => void,
+      error?: (err: GeolocationPositionError) => void,
+      options?: PositionOptions,
+    ) => void;
+  };
+  permissions?: { query: (descriptor: { name: string }) => Promise<{ state: string }> };
+};
+
+function safeWindow(): (Window & typeof globalThis) | null {
+  return typeof window === 'undefined' ? null : (window as Window & typeof globalThis);
+}
+
+function safeNavigator(): typeof navigator | null {
+  if (typeof navigator === 'undefined') return null;
+  return navigator;
+}
+
+/** Is `Notification` available in the current runtime? */
+export function doesBrowserSupportNotifications(): boolean {
+  const win = safeWindow();
+  if (!win) return false;
+  return typeof win.Notification !== 'undefined';
+}
+
+/** Is `getUserMedia` available (camera/microphone capture)? */
+export function doesBrowserSupportMediaCapture(): boolean {
+  const nav = safeNavigator();
+  if (!nav) return false;
+  return Boolean(nav.mediaDevices?.getUserMedia);
+}
+
+/** Is geolocation available? */
+export function doesBrowserSupportGeolocation(): boolean {
+  const nav = safeNavigator();
+  if (!nav) return false;
+  return Boolean(nav.geolocation);
+}
+
+/** Aggregate check used by `usePermissionPriming` to report "unsupported" cleanly. */
+export function isRuntimeSupportMissing(permission: PermissionType): boolean {
+  switch (permission) {
+    case 'notifications':
+      return !doesBrowserSupportNotifications();
+    case 'camera':
+    case 'microphone':
+      return !doesBrowserSupportMediaCapture();
+    case 'location':
+      return !doesBrowserSupportGeolocation();
+    case 'photos':
+    case 'contacts':
+      return true; // No web-standard APIs for these in this package.
+    default:
+      return true;
+  }
+}

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

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import {
+  doesIconNameResolve,
+  getRegisteredIconNames,
+  resolveIconByName,
+} from './icon-name-resolves';
+import {
+  isPermissionDecided,
+  isPermissionDenied,
+  isPermissionGranted,
+  isPermissionPrompt,
+  isPermissionUnsupported,
+} from './permission-granted';
+import {
+  doesBrowserSupportGeolocation,
+  doesBrowserSupportMediaCapture,
+  doesBrowserSupportNotifications,
+  isRuntimeSupportMissing,
+} from './permission-supports';
+import { isLocalStorageAvailable } from './storage-available';
+import {
+  accountGateAllowsSkip,
+  hasOnAccept,
+  hasOnRequest,
+  hasOnSignIn,
+} from './has-handler';
+import { screenEmitsData } from './screen-emits-data';
+import type { OnboardingScreen } from '../types/screens';
+
+// TEST_SCENARIOS.md §24
+describe('icon-name-resolves (§24.4)', () => {
+  it('resolves registered names', () => {
+    expect(doesIconNameResolve('HeartPulse')).toBe(true);
+    expect(doesIconNameResolve('Sparkles')).toBe(true);
+    // lucide-react icons are forwardRef memo objects, not plain functions.
+    expect(resolveIconByName('Sparkles')).toBeTruthy();
+  });
+
+  it('does not resolve unknown, missing, or case-mismatched names', () => {
+    expect(doesIconNameResolve('NonExistentIcon')).toBe(false);
+    expect(doesIconNameResolve(undefined)).toBe(false);
+    expect(doesIconNameResolve('sparkles')).toBe(false); // registry is PascalCase
+    expect(resolveIconByName('NonExistentIcon')).toBeNull();
+  });
+
+  it('resolves the reserved-word alias "Infinity"', () => {
+    expect(doesIconNameResolve('Infinity')).toBe(true);
+    expect(resolveIconByName('Infinity')).toBeTruthy();
+  });
+
+  it('resolves every icon used by the bundled templates — including the video set', () => {
+    // Icons referenced across art/health/platform/video templates.
+    const templateIcons = [
+      'Activity', 'Apple', 'Award', 'Ban', 'Bell', 'BookOpen', 'Camera', 'Check',
+      'CheckCircle2', 'Download', 'Dumbbell', 'GraduationCap', 'Headphones',
+      'HeartPulse', 'Image', 'Infinity', 'Lock', 'MapPin', 'MessageCircle',
+      'Mic', 'Moon', 'Palette', 'PenTool', 'Play', 'Rocket', 'Rewind', 'Share2',
+      'Shield', 'ShieldCheck', 'Smile', 'Sparkles', 'Square', 'Star', 'Theater',
+      'Tv', 'Users', 'X', 'Zap',
+    ];
+    for (const name of templateIcons) {
+      expect(doesIconNameResolve(name), `expected "${name}" to resolve`).toBe(true);
+    }
+  });
+
+  it('keeps the registry curated (each name maps to a component)', () => {
+    const names = getRegisteredIconNames();
+    expect(names.length).toBeGreaterThan(30);
+    expect(names.length).toBeLessThan(60); // a namespace import would be ~1,500
+    for (const name of names) {
+      expect(resolveIconByName(name), `icon "${name}"`).toBeTruthy();
+    }
+  });
+});
+
+// TEST_SCENARIOS.md §24.1
+describe('permission-granted (§24.1)', () => {
+  it('classifies statuses', () => {
+    expect(isPermissionGranted('granted')).toBe(true);
+    expect(isPermissionGranted('prompt')).toBe(false);
+    expect(isPermissionDenied('denied')).toBe(true);
+    expect(isPermissionPrompt('prompt')).toBe(true);
+    expect(isPermissionDecided('granted')).toBe(true);
+    expect(isPermissionDecided('denied')).toBe(true);
+    expect(isPermissionDecided('prompt')).toBe(false);
+    expect(isPermissionUnsupported('unsupported')).toBe(true);
+    expect(isPermissionUnsupported('granted')).toBe(false);
+  });
+});
+
+// TEST_SCENARIOS.md §24.2 — jsdom stands in for the "modern browser" runtime.
+describe('permission-supports (§24.2)', () => {
+  it('reports support from the live navigator/window', () => {
+    // jsdom ships geolocation + mediaDevices in recent versions; the exact
+    // answer varies by jsdom build, so assert predicate/API agreement instead
+    // of hardcoding booleans.
+    expect(doesBrowserSupportMediaCapture()).toBe(
+      Boolean((globalThis as { navigator?: { mediaDevices?: { getUserMedia?: unknown } } })
+        .navigator?.mediaDevices?.getUserMedia),
+    );
+    expect(doesBrowserSupportGeolocation()).toBe(
+      Boolean(
+        (globalThis as { navigator?: { geolocation?: unknown } }).navigator?.geolocation,
+      ),
+    );
+  });
+
+  it('reports notification support from the window object', () => {
+    expect(doesBrowserSupportNotifications()).toBe(
+      typeof (globalThis as { Notification?: unknown }).Notification !== 'undefined',
+    );
+  });
+
+  it('treats photos/contacts as unsupported (no web-standard API)', () => {
+    expect(isRuntimeSupportMissing('photos')).toBe(true);
+    expect(isRuntimeSupportMissing('contacts')).toBe(true);
+  });
+});
+
+// TEST_SCENARIOS.md §24.3
+describe('storage-available (§24.3)', () => {
+  it('works in the jsdom browser environment', () => {
+    expect(isLocalStorageAvailable()).toBe(true);
+  });
+
+  it('returns false when storage access throws (e.g. blocked cookies)', () => {
+    const original = window.localStorage;
+    // Replace with a getter that throws, as Safari private mode historically did.
+    Object.defineProperty(window, 'localStorage', {
+      configurable: true,
+      get() {
+        throw new DOMException('Access is denied for this document', 'SecurityError');
+      },
+    });
+    try {
+      expect(isLocalStorageAvailable()).toBe(false);
+    } finally {
+      Object.defineProperty(window, 'localStorage', {
+        configurable: true,
+        value: original,
+        writable: true,
+      });
+    }
+  });
+});
+
+// TEST_SCENARIOS.md §24.5
+describe('has-handler (§24.5)', () => {
+  const paywall = {
+    id: 'w',
+    type: 'paywall',
+    price: '$1',
+    trialDays: 7,
+  } as Parameters<typeof hasOnAccept>[0];
+
+  it('detects usable callbacks', () => {
+    expect(hasOnAccept(paywall)).toBe(false);
+    expect(hasOnAccept({ ...paywall, onAccept: async () => ({ accepted: true, trialStarted: true }) })).toBe(true);
+
+    expect(
+      hasOnRequest({
+        permission: 'camera',
+        description: 'd',
+        benefits: [],
+      } as unknown as Parameters<typeof hasOnRequest>[0]),
+    ).toBe(false);
+
+    expect(
+      hasOnSignIn({
+        optional: false,
+        onSignIn: () => Promise.resolve({ signedIn: true }),
+      } as unknown as Parameters<typeof hasOnSignIn>[0]),
+    ).toBe(true);
+  });
+
+  it('allows skip only on optional account gates', () => {
+    expect(
+      accountGateAllowsSkip({ optional: true } as unknown as Parameters<
+        typeof accountGateAllowsSkip
+      >[0]),
+    ).toBe(true);
+    expect(
+      accountGateAllowsSkip({ optional: false } as unknown as Parameters<
+        typeof accountGateAllowsSkip
+      >[0]),
+    ).toBe(false);
+  });
+});
+
+// TEST_SCENARIOS.md §24.6
+describe('screen-emits-data (§24.6)', () => {
+  it('marks view-only screens as non-emitting', () => {
+    expect(screenEmitsData({ id: 'a', type: 'welcome' } as OnboardingScreen)).toBe(false);
+    expect(screenEmitsData({ id: 'v', type: 'value-delivery' } as OnboardingScreen)).toBe(false);
+    expect(screenEmitsData({ id: 's', type: 'social-proof' } as OnboardingScreen)).toBe(false);
+  });
+
+  it('marks data-collecting screens as emitting', () => {
+    expect(screenEmitsData({ id: 'g', type: 'goal-question' } as OnboardingScreen)).toBe(true);
+    expect(screenEmitsData({ id: 'p', type: 'preferences' } as OnboardingScreen)).toBe(true);
+  });
+});

package/src/domains/onboarding/predicates/screen-emits-data.ts

@@ -0,0 +1,17 @@
+import type { OnboardingScreen } from '../types/screens';
+
+/**
+ * Does this screen type emit a payload to the orchestrator when the user advances?
+ * Pure view-only screens (welcome, social-proof, comparison, value-delivery) do not.
+ */
+const VIEW_ONLY_SCREEN_TYPES: ReadonlySet<OnboardingScreen['type']> = new Set([
+  'welcome',
+  'social-proof',
+  'comparison',
+  'value-delivery',
+  'personalized-solution',
+]);
+
+export function screenEmitsData(screen: OnboardingScreen): boolean {
+  return !VIEW_ONLY_SCREEN_TYPES.has(screen.type);
+}

package/src/domains/onboarding/predicates/storage-available.ts

@@ -0,0 +1,22 @@
+const PROBE_KEY = '@umituz/web-onboarding:probe';
+const PROBE_VALUE = '1';
+
+/**
+ * Can the current environment use `localStorage`?
+ * - Server-side / SSR: false
+ * - Disabled cookies/storage in the browser: false
+ * - Otherwise: true
+ *
+ * Side effect: writes and removes a tiny probe to verify both write & read work.
+ */
+export function isLocalStorageAvailable(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const probe = window.localStorage;
+    probe.setItem(PROBE_KEY, PROBE_VALUE);
+    probe.removeItem(PROBE_KEY);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/domains/onboarding/templates/TemplateDemoFallback.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react';
+import { Sparkles } from 'lucide-react';
+import type { DemoConfig } from '../types/screens';
+import type { OnboardingScreen } from '../types/screens';
+
+export interface TemplateDemoResult {
+  variant: string;
+  palette: string[];
+  generatedAt: number;
+}
+
+/**
+ * Default demo component used by the art and platform templates.
+ * Lets users produce a real artifact in the template without forcing consumers
+ * to wire up their own demo before they can preview the flow.
+ *
+ * Consumers who want their own demo should clone the template and replace
+ * `screens[?].demo.component` with their own implementation.
+ */
+function TemplateDemoFallback({ onSave }: { onSave: (result: TemplateDemoResult) => void }) {
+  const palettes: ReadonlyArray<{ variant: string; palette: string[] }> = [
+    { variant: 'Minimal', palette: ['#0F172A', '#475569', '#94A3B8', '#F1F5F9', '#FFFFFF'] },
+    { variant: 'Bold', palette: ['#7C3AED', '#EC4899', '#F59E0B', '#10B981', '#0EA5E9'] },
+    { variant: 'Retro', palette: ['#92400E', '#B45309', '#D97706', '#FCD34D', '#FEF3C7'] },
+    { variant: 'Playful', palette: ['#F472B6', '#A78BFA', '#60A9FA', '#34D399', '#FBBF24'] },
+  ];
+
+  const [activeIdx, setActiveIdx] = useState(0);
+  const active = palettes[activeIdx];
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+        {palettes.map((p, i) => (
+          <button
+            key={p.variant}
+            type="button"
+            onClick={() => setActiveIdx(i)}
+            className={
+              i === activeIdx
+                ? 'rounded-lg border-2 border-[rgb(var(--uob-primary-500))] p-2'
+                : 'rounded-lg border-2 border-transparent p-2 hover:border-[rgb(var(--uob-border))]'
+            }
+          >
+            <div className="flex h-12 w-full overflow-hidden rounded">
+              {p.palette.map((c) => (
+                <span key={c} className="flex-1" style={{ background: c }} />
+              ))}
+            </div>
+            <span className="mt-1 block text-xs font-medium text-[rgb(var(--uob-text-primary))]">
+              {p.variant}
+            </span>
+          </button>
+        ))}
+      </div>
+      <div className="rounded-xl border border-[rgb(var(--uob-border))] bg-[rgb(var(--uob-surface))] p-6">
+        <div className="flex h-32 w-full overflow-hidden rounded-lg">
+          {active.palette.map((c) => (
+            <span key={c} className="flex-1" style={{ background: c }} />
+          ))}
+        </div>
+        <p className="mt-3 text-sm text-[rgb(var(--uob-text-muted))]">
+          Preview: <strong className="text-[rgb(var(--uob-text-primary))]">{active.variant}</strong>{' '}
+          palette
+        </p>
+      </div>
+      <button
+        type="button"
+        onClick={() =>
+          onSave({
+            variant: active.variant,
+            palette: [...active.palette],
+            generatedAt: Date.now(),
+          })
+        }
+        className="inline-flex items-center justify-center gap-2 rounded-xl bg-[rgb(var(--uob-primary-500))] px-4 py-3 text-sm font-semibold text-white hover:bg-[rgb(var(--uob-primary-600))]"
+      >
+        <Sparkles className="h-4 w-4" />
+        Save this style
+      </button>
+    </div>
+  );
+}
+
+const fallbackDemo: DemoConfig = {
+  component: TemplateDemoFallback as React.ComponentType<Record<string, unknown>>,
+  onSave: () => undefined,
+};
+
+const fallbackResult: TemplateDemoResult = {
+  variant: 'Minimal',
+  palette: ['#0F172A', '#475569', '#94A3B8', '#F1F5F9', '#FFFFFF'],
+  generatedAt: 0,
+};
+
+/**
+ * Replace an `app-demo` screen in a template with a working default.
+ * Used by the art and platform templates so the flow is fully runnable
+ * out of the box; consumers can override the demo.component for their app.
+ */
+export function withDefaultDemo(screen: OnboardingScreen, fallback: DemoConfig = fallbackDemo): OnboardingScreen {
+  if (screen.type !== 'app-demo') return screen;
+  return { ...screen, demo: { ...fallback, ...screen.demo } };
+}
+
+export function defaultDemoResult(): TemplateDemoResult {
+  return { ...fallbackResult };
+}
+
+// Re-export for convenience.
+export { TemplateDemoFallback };
+export type { DemoConfig };

package/src/domains/onboarding/templates/art-onboarding.ts

@@ -0,0 +1,81 @@
+import type { OnboardingConfig } from '../types/config';
+import type { OnboardingScreen } from '../types/screens';
+import { withDefaultDemo, defaultDemoResult } from './TemplateDemoFallback';
+
+/**
+ * Art category — demo-driven, 3–5 screens.
+ * Show value fast: by the end of step 3 the user has produced a real artifact.
+ *
+ * The demo screen ships with a working palette-preview fallback so the template
+ * is runnable out of the box. Replace `screens[2].demo.component` to plug in
+ * the consumer's own demo.
+ */
+
+const baseScreens: OnboardingScreen[] = [
+  {
+    id: 'welcome',
+    type: 'welcome',
+    title: 'Make something beautiful in 60 seconds',
+    subtitle: 'No design skills. No learning curve. Just create.',
+    cta: 'Try the demo',
+    heroIconName: 'Sparkles',
+    highlight: 'Live demo',
+  },
+  {
+    id: 'style',
+    type: 'goal-question',
+    question: 'Pick a style that feels like you',
+    multiSelect: true,
+    options: [
+      { id: 'minimal', label: 'Minimal', iconName: 'Square' },
+      { id: 'bold', label: 'Bold colors', iconName: 'Zap' },
+      { id: 'retro', label: 'Retro', iconName: 'Rewind' },
+      { id: 'playful', label: 'Playful', iconName: 'Smile' },
+    ],
+    onChange: () => undefined,
+    cta: 'Continue',
+  },
+  {
+    id: 'demo',
+    type: 'app-demo',
+    title: 'Your turn — pick a palette',
+    demo: {
+      // `withDefaultDemo` below replaces this no-op with the built-in fallback.
+      component: () => null,
+      onSave: () => undefined,
+    },
+  },
+  {
+    id: 'value',
+    type: 'value-delivery',
+    title: 'You made this!',
+    result: defaultDemoResult(),
+  },
+  {
+    id: 'paywall',
+    type: 'paywall',
+    title: 'Keep creating',
+    subtitle: 'Unlimited generations, all styles, no watermarks.',
+    price: '$4.99 / week',
+    trialDays: 3,
+    cta: 'Start free trial',
+    secondaryCta: 'Not now',
+    features: [
+      { iconName: 'Infinity', text: 'Unlimited creations', highlighted: true },
+      { iconName: 'Palette', text: 'All styles unlocked' },
+      { iconName: 'Download', text: 'High-res export' },
+      { iconName: 'Share2', text: 'Share anywhere' },
+    ],
+    onSecondaryCta: () => undefined,
+    onAccept: async () => ({ accepted: true, trialStarted: true }),
+  },
+];
+
+const screens = baseScreens.map((s) => withDefaultDemo(s));
+
+export const artOnboardingTemplate: OnboardingConfig = {
+  category: 'art',
+  screens,
+  onSkip: () => undefined,
+  onComplete: () => undefined,
+};