@umituz/web-dashboard 3.2.2 → 4.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * Onboarding Domain i18n Keys
+ */
+
+export const ONBOARDING_KEYS = {
+  // Wizard
+  wizard: {
+    cancel: 'onboarding.buttons.cancel',
+    stepNotConfigured: 'onboarding.errors.stepNotConfigured',
+    errors: {
+      completionFailed: 'onboarding.errors.completionFailed',
+    },
+  },
+
+  // User type step
+  userType: {
+    title: 'onboarding.userType.title',
+    description: 'onboarding.userType.description',
+  },
+
+  // App focus step
+  appFocus: {
+    title: 'onboarding.appFocus.title',
+    description: 'onboarding.appFocus.description',
+    success: 'onboarding.appFocus.success',
+  },
+
+  // Platforms step
+  platforms: {
+    title: 'onboarding.platforms.title',
+    description: 'onboarding.platforms.description',
+    connect: 'onboarding.platforms.connect',
+    connected: 'onboarding.platforms.connected',
+    selected: 'onboarding.platforms.selected',
+  },
+
+  // Plan step
+  plan: {
+    title: 'onboarding.plan.title',
+    description: 'onboarding.plan.description',
+    monthly: 'onboarding.plan.monthly',
+    yearly: 'onboarding.plan.yearly',
+    monthlyShort: 'onboarding.plan.monthlyShort',
+    yearlyShort: 'onboarding.plan.yearlyShort',
+    save: 'onboarding.plan.save',
+    recommended: 'onboarding.plan.recommended',
+    selectedPlan: 'onboarding.plan.selectedPlan',
+    mostPopular: 'onboarding.plan.mostPopular',
+    bestValue: 'onboarding.plan.bestValue',
+    custom: 'onboarding.plan.custom',
+  },
+
+  // Steps (default data — keys can be overridden per consumer)
+  defaults: {
+    founder: 'onboarding.defaults.userType.founder',
+    founderDescription: 'onboarding.defaults.userType.founderDescription',
+    contentCreator: 'onboarding.defaults.userType.contentCreator',
+    contentCreatorDescription: 'onboarding.defaults.userType.contentCreatorDescription',
+    smallBusiness: 'onboarding.defaults.userType.smallBusiness',
+    smallBusinessDescription: 'onboarding.defaults.userType.smallBusinessDescription',
+    enterprise: 'onboarding.defaults.userType.enterprise',
+    enterpriseDescription: 'onboarding.defaults.userType.enterpriseDescription',
+    agency: 'onboarding.defaults.userType.agency',
+    agencyDescription: 'onboarding.defaults.userType.agencyDescription',
+    personal: 'onboarding.defaults.userType.personal',
+    personalDescription: 'onboarding.defaults.userType.personalDescription',
+    mobileApp: 'onboarding.defaults.appType.mobileApp',
+    mobileAppDescription: 'onboarding.defaults.appType.mobileAppDescription',
+    webApp: 'onboarding.defaults.appType.webApp',
+    webAppDescription: 'onboarding.defaults.appType.webAppDescription',
+  },
+} as const;

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

@@ -13,3 +13,5 @@ export {
   isValidEmail,
   isValidPassword,
 } from './onboarding';
+
+export { ONBOARDING_KEYS } from './i18nKeys';

package/src/domains/permissions/PermissionsContext.tsx

@@ -0,0 +1,103 @@
+/**
+ * Permissions context — provides the matrix + active role and a
+ * `can(permission)` helper bound to them. Guard components
+ * (<RequirePermission>, <Can>) consume this context.
+ */
+
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { Lock } from "lucide-react";
+import { useT } from "../../i18n";
+import { hasPermission } from "./hasPermission";
+import { PERMISSIONS_KEYS } from "./utils/i18nKeys";
+import type { Permission, PermissionMatrix, RoleKey } from "./types";
+
+export interface PermissionsProviderProps {
+  /** Role x permission matrix. */
+  matrix: PermissionMatrix;
+  /** Active user's role. */
+  role: RoleKey | null | undefined;
+  children: ReactNode;
+}
+
+interface PermissionsContextValue {
+  matrix: PermissionMatrix;
+  role: RoleKey | null;
+  can: (permission: Permission) => boolean;
+}
+
+const PermissionsContext = createContext<PermissionsContextValue | null>(null);
+
+export const PermissionsProvider = ({
+  matrix,
+  role,
+  children,
+}: PermissionsProviderProps) => {
+  const can = useCallback(
+    (permission: Permission) => hasPermission(matrix, role, permission),
+    [matrix, role],
+  );
+
+  const value = useMemo<PermissionsContextValue>(
+    () => ({ matrix, role: role ?? null, can }),
+    [matrix, role, can],
+  );
+
+  return (
+    <PermissionsContext.Provider value={value}>
+      {children}
+    </PermissionsContext.Provider>
+  );
+};
+
+export const usePermissions = (): PermissionsContextValue => {
+  const context = useContext(PermissionsContext);
+  if (!context) {
+    throw new Error("usePermissions requires a <PermissionsProvider> ancestor");
+  }
+  return context;
+};
+
+/** Default lock screen rendered by RequirePermission when denied. */
+const ForbiddenFallback = () => {
+  const t = useT();
+  return (
+    <div className="udb-empty" role="alert">
+      <div className="udb-empty__icon">
+        <Lock className="udb-empty__glyph" aria-hidden="true" />
+      </div>
+      <p className="udb-empty__text">{t(PERMISSIONS_KEYS.forbidden.title)}</p>
+      <p className="udb-empty__hint">{t(PERMISSIONS_KEYS.forbidden.hint)}</p>
+    </div>
+  );
+};
+
+export interface RequirePermissionProps {
+  /** Permission required to render the children. */
+  permission: Permission;
+  children: ReactNode;
+  /** Rendered instead of the default lock screen when denied. */
+  fallback?: ReactNode;
+}
+
+/**
+ * Page-level permission gate — renders the fallback (lock screen by
+ * default) instead of the children when `can(permission)` is false.
+ */
+export const RequirePermission = ({
+  permission,
+  children,
+  fallback,
+}: RequirePermissionProps) => {
+  const { can } = usePermissions();
+  if (can(permission)) return <>{children}</>;
+  return <>{fallback ?? <ForbiddenFallback />}</>;
+};
+
+export interface CanProps extends RequirePermissionProps {}
+
+/** Declarative twin of RequirePermission for inline use. */
+export const Can = ({ permission, children, fallback }: CanProps) => (
+  <RequirePermission permission={permission} fallback={fallback}>
+    {children}
+  </RequirePermission>
+);

package/src/domains/permissions/hasPermission.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { hasPermission } from "./hasPermission";
+import type { PermissionMatrix } from "./types";
+
+const MATRIX: PermissionMatrix = {
+  owner: "*",
+  admin: ["dashboard.view", "sales.*", "reports.view"],
+  viewer: ["dashboard.view"],
+  nobody: [],
+};
+
+describe("hasPermission", () => {
+  it("grants exact permissions", () => {
+    expect(hasPermission(MATRIX, "admin", "dashboard.view")).toBe(true);
+    expect(hasPermission(MATRIX, "viewer", "dashboard.view")).toBe(true);
+  });
+
+  it("denies permissions not granted to the role", () => {
+    expect(hasPermission(MATRIX, "viewer", "sales.view")).toBe(false);
+    expect(hasPermission(MATRIX, "admin", "settings.manage")).toBe(false);
+  });
+
+  it("honors the full wildcard", () => {
+    expect(hasPermission(MATRIX, "owner", "anything.at.all")).toBe(true);
+  });
+
+  it("honors module wildcards without over-granting", () => {
+    expect(hasPermission(MATRIX, "admin", "sales.view")).toBe(true);
+    expect(hasPermission(MATRIX, "admin", "sales.manage")).toBe(true);
+    expect(hasPermission(MATRIX, "admin", "salesforce.view")).toBe(false);
+  });
+
+  it("denies unknown roles", () => {
+    expect(hasPermission(MATRIX, "intruder", "dashboard.view")).toBe(false);
+  });
+
+  it("denies unknown modules", () => {
+    expect(hasPermission(MATRIX, "viewer", "nuclear.launch")).toBe(false);
+  });
+
+  it("denies roles with empty grants", () => {
+    expect(hasPermission(MATRIX, "nobody", "dashboard.view")).toBe(false);
+  });
+
+  it("denies when matrix or role is missing", () => {
+    expect(hasPermission(null, "admin", "dashboard.view")).toBe(false);
+    expect(hasPermission(MATRIX, null, "dashboard.view")).toBe(false);
+    expect(hasPermission(undefined, undefined, "x")).toBe(false);
+  });
+});

package/src/domains/permissions/hasPermission.ts

@@ -0,0 +1,38 @@
+/**
+ * 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,
+  type PermissionMatrix,
+  type RoleGrant,
+  type RoleKey,
+} from "./types";
+
+const MODULE_WILDCARD_SUFFIX = ".*";
+
+const grantIncludes = (grant: RoleGrant, permission: Permission): boolean => {
+  if (grant === PERMISSION_WILDCARD) return true;
+  return grant.some(
+    (entry) =>
+      entry === permission ||
+      (entry.endsWith(MODULE_WILDCARD_SUFFIX) &&
+        permission.startsWith(entry.slice(0, -1))),
+  );
+};
+
+export const hasPermission = (
+  matrix: PermissionMatrix | null | undefined,
+  role: RoleKey | null | undefined,
+  permission: Permission,
+): boolean => {
+  if (!matrix || !role) return false;
+  const grant = matrix[role];
+  if (grant === undefined) return false;
+  return grantIncludes(grant, permission);
+};

package/src/domains/permissions/index.ts

@@ -0,0 +1,19 @@
+export {
+  PermissionsProvider,
+  usePermissions,
+  RequirePermission,
+  Can,
+  type PermissionsProviderProps,
+  type RequirePermissionProps,
+  type CanProps,
+} from "./PermissionsContext";
+export { hasPermission } from "./hasPermission";
+export {
+  PERMISSION_WILDCARD,
+  type Permission,
+  type PermissionMatrix,
+  type RoleGrant,
+  type RoleKey,
+  type RoleInfo,
+} from "./types";
+export { PERMISSIONS_KEYS } from "./utils/i18nKeys";

package/src/domains/permissions/types.ts

@@ -0,0 +1,35 @@
+/**
+ * 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;
+  description?: string;
+}

package/src/domains/permissions/utils/i18nKeys.ts

@@ -0,0 +1,11 @@
+/**
+ * Permission domain i18n keys — the documented string contract.
+ * Hosts translate these via <DashboardI18nProvider t={...}>.
+ */
+
+export const PERMISSIONS_KEYS = {
+  forbidden: {
+    title: "permissions.forbidden.title",
+    hint: "permissions.forbidden.hint",
+  },
+} as const;

package/src/domains/session/DemoLogin.tsx

@@ -0,0 +1,50 @@
+/**
+ * DemoLogin — one-click demo entry (fleet pattern: log in as a demo
+ * persona without a password). Controlled: the click delegates to
+ * `onDemo` (typically `session.demoLogin`); the label defaults to
+ * the i18n catalog.
+ */
+
+import { UserRound } from "lucide-react";
+import { Button } from "../../primitives";
+import { useT } from "../../i18n";
+import { SESSION_KEYS } from "./utils/i18nKeys";
+
+export interface DemoLoginProps {
+  onDemo: (userId: string) => void | Promise<void>;
+  /** Demo user id to log in as. */
+  userId: string;
+  label?: string;
+  variant?: "default" | "outline" | "ghost";
+  size?: "default" | "sm";
+  disabled?: boolean;
+  className?: string;
+}
+
+export const DemoLogin = ({
+  onDemo,
+  userId,
+  label,
+  variant = "outline",
+  size = "default",
+  disabled = false,
+  className,
+}: DemoLoginProps) => {
+  const t = useT();
+
+  return (
+    <Button
+      type="button"
+      variant={variant}
+      size={size}
+      disabled={disabled}
+      className={className}
+      onClick={() => void onDemo(userId)}
+    >
+      <UserRound aria-hidden="true" />
+      {label ?? t(SESSION_KEYS.demoLogin.action)}
+    </Button>
+  );
+};
+
+export default DemoLogin;

package/src/domains/session/OrgSwitcher.tsx

@@ -0,0 +1,110 @@
+/**
+ * OrgSwitcher — tenant switcher trigger + dropdown.
+ *
+ * Controlled component: tenants and the active id come in as props,
+ * switches are delegated via onSwitch. Styled entirely with existing
+ * udb-* classes (profile button, avatar, menu).
+ */
+
+import { useState } from "react";
+import { Building2, Check, ChevronDown } from "lucide-react";
+import { cn } from "../../primitives";
+import { useT } from "../../i18n";
+import { SESSION_KEYS } from "./utils/i18nKeys";
+import type { Tenant } from "./types";
+
+export interface OrgSwitcherProps {
+  tenants: Tenant[];
+  activeTenantId?: string | null;
+  onSwitch: (tenantId: string) => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+const initialsOf = (tenant: Tenant): string =>
+  tenant.initials ??
+  tenant.name
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((word) => word.charAt(0).toUpperCase())
+    .join("");
+
+export const OrgSwitcher = ({
+  tenants,
+  activeTenantId,
+  onSwitch,
+  disabled = false,
+  className,
+}: OrgSwitcherProps) => {
+  const t = useT();
+  const [open, setOpen] = useState(false);
+
+  if (tenants.length === 0) return null;
+
+  const active = tenants.find((tenant) => tenant.id === activeTenantId) ?? tenants[0];
+
+  return (
+    <div className={cn("udb-header__anchor", className)}>
+      <button
+        type="button"
+        className="udb-profile-btn"
+        disabled={disabled}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-label={t(SESSION_KEYS.orgSwitcher.label)}
+        onClick={() => setOpen((prev) => !prev)}
+      >
+        <span className="udb-avatar">{initialsOf(active)}</span>
+        <span className="udb-org">
+          <span className="udb-org__name">{active.name}</span>
+          {active.plan && <span className="udb-org__meta">{active.plan}</span>}
+        </span>
+        <ChevronDown
+          className={cn(
+            "udb-profile-btn__chevron",
+            open && "udb-profile-btn__chevron--open",
+          )}
+          aria-hidden="true"
+        />
+      </button>
+
+      {open && (
+        <>
+          <button
+            type="button"
+            className="udb-overlay"
+            aria-label="close tenant menu"
+            tabIndex={-1}
+            onClick={() => setOpen(false)}
+          />
+          <div className="udb-menu udb-org-menu" role="menu">
+            {tenants.map((tenant) => {
+              const isActive = tenant.id === active.id;
+              return (
+                <button
+                  key={tenant.id}
+                  type="button"
+                  role="menuitem"
+                  className={cn(
+                    "udb-menu__item",
+                    isActive && "udb-menu__item--active",
+                  )}
+                  onClick={() => {
+                    onSwitch(tenant.id);
+                    setOpen(false);
+                  }}
+                >
+                  <Building2 className="udb-menu__item-icon" aria-hidden="true" />
+                  <span className="udb-org-menu__label">{tenant.name}</span>
+                  {isActive && <Check className="udb-org-menu__check" aria-hidden="true" />}
+                </button>
+              );
+            })}
+          </div>
+        </>
+      )}
+    </div>
+  );
+};
+
+export default OrgSwitcher;

package/src/domains/session/SessionContext.tsx

@@ -0,0 +1,150 @@
+/**
+ * Session context — user + active tenant state over an injected
+ * AuthAdapter. Restores the current user on mount, exposes
+ * login/logout/demoLogin, loads tenants for the user and keeps an
+ * `activeTenant` the OrgSwitcher drives via `switchTenant`.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import type {
+  AuthAdapter,
+  LoginCredentials,
+  SessionStatus,
+  SessionUser,
+  Tenant,
+} from "./types";
+
+export interface SessionProviderProps {
+  adapter: AuthAdapter;
+  children: ReactNode;
+}
+
+interface SessionContextValue {
+  user: SessionUser | null;
+  tenants: Tenant[];
+  activeTenant: Tenant | null;
+  status: SessionStatus;
+  login: (credentials: LoginCredentials) => Promise<SessionUser>;
+  logout: () => Promise<void>;
+  demoLogin: (userId: string) => Promise<SessionUser>;
+  switchTenant: (tenantId: string) => void;
+}
+
+const SessionContext = createContext<SessionContextValue | null>(null);
+
+export const SessionProvider = ({ adapter, children }: SessionProviderProps) => {
+  const [user, setUser] = useState<SessionUser | null>(null);
+  const [tenants, setTenants] = useState<Tenant[]>([]);
+  const [activeTenantId, setActiveTenantId] = useState<string | null>(null);
+  const [status, setStatus] = useState<SessionStatus>("loading");
+
+  // Restore the session once on mount.
+  useEffect(() => {
+    let cancelled = false;
+    adapter
+      .current()
+      .then((current) => {
+        if (cancelled) return;
+        setUser(current);
+        setStatus(current ? "authenticated" : "anonymous");
+      })
+      .catch(() => {
+        if (!cancelled) setStatus("anonymous");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [adapter]);
+
+  // Load tenants whenever the authenticated user changes.
+  useEffect(() => {
+    if (!user || !adapter.listTenants) {
+      setTenants([]);
+      setActiveTenantId(null);
+      return;
+    }
+    let cancelled = false;
+    adapter
+      .listTenants(user.id)
+      .then((list) => {
+        if (cancelled) return;
+        setTenants(list);
+        setActiveTenantId((prev) =>
+          prev && list.some((tenant) => tenant.id === prev) ? prev : (list[0]?.id ?? null),
+        );
+      })
+      .catch(() => {
+        if (!cancelled) setTenants([]);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [adapter, user]);
+
+  const login = useCallback(
+    async (credentials: LoginCredentials) => {
+      const next = await adapter.login(credentials);
+      setUser(next);
+      setStatus("authenticated");
+      return next;
+    },
+    [adapter],
+  );
+
+  const logout = useCallback(async () => {
+    await adapter.logout();
+    setUser(null);
+    setStatus("anonymous");
+  }, [adapter]);
+
+  const demoLogin = useCallback(
+    async (userId: string) => {
+      if (!adapter.demoLogin) {
+        throw new Error("AuthAdapter does not support demoLogin");
+      }
+      const next = await adapter.demoLogin(userId);
+      setUser(next);
+      setStatus("authenticated");
+      return next;
+    },
+    [adapter],
+  );
+
+  const switchTenant = useCallback((tenantId: string) => {
+    setActiveTenantId(tenantId);
+  }, []);
+
+  const value = useMemo<SessionContextValue>(
+    () => ({
+      user,
+      tenants,
+      activeTenant: tenants.find((tenant) => tenant.id === activeTenantId) ?? null,
+      status,
+      login,
+      logout,
+      demoLogin,
+      switchTenant,
+    }),
+    [user, tenants, activeTenantId, status, login, logout, demoLogin, switchTenant],
+  );
+
+  return (
+    <SessionContext.Provider value={value}>{children}</SessionContext.Provider>
+  );
+};
+
+export const useSession = (): SessionContextValue => {
+  const context = useContext(SessionContext);
+  if (!context) {
+    throw new Error("useSession requires a <SessionProvider> ancestor");
+  }
+  return context;
+};