@vef-framework-react/starter 2.2.0 → 2.2.2

package/dist/es/routes/root.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.0 made by Venus | 2026-05-18T05:49:20.358Z */
+/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
 import { useAppStore as e } from "../stores/app.js";
 import { jsx as t } from "@emotion/react/jsx-runtime";
 import { Outlet as n, useLocation as r, useRouteContext as i } from "@tanstack/react-router";

package/dist/es/stores/app.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.0 made by Venus | 2026-05-18T05:49:20.358Z */
+/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
 import { createPersistedStore as e } from "@vef-framework-react/core";
 //#region src/stores/app.ts
 var t = e(() => ({ isAuthenticated: !1 }), {

package/dist/es/stores/index.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.0 made by Venus | 2026-05-18T05:49:20.358Z */
+/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
 import "./app.js";
 import "./tab.js";
 import "./theme.js";

package/dist/es/stores/tab.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.0 made by Venus | 2026-05-18T05:49:20.358Z */
+/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
 import "../constants/router.js";
 import { createPersistedStore as e, originalState as t } from "@vef-framework-react/core";
 //#region src/stores/tab.ts

package/dist/es/stores/theme.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.0 made by Venus | 2026-05-18T05:49:20.358Z */
+/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
 import { createPersistedStore as e } from "@vef-framework-react/core";
 import { omit as t } from "@vef-framework-react/shared";
 //#region src/stores/theme.ts

package/dist/types/components/index.d.ts

@@ -3,7 +3,7 @@ export { App, type AppProps } from './app';
 export { BaseLayout, type BaseLayoutProps } from './base-layout';
 export { Error } from './error';
 export { Layout, type LayoutProps } from './layout';
-export { Login, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './login';
+export { Login, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './login';
 export { NProgress, nProgressEventEmitter } from './n-progress';
 export { NotFound } from './not-found';
 export { RouterContextHookProvider, RouterProvider, type RouterProviderProps, type UseRouterContext } from './router-provider';

package/dist/types/components/layout/components/header/index.d.ts

@@ -1,5 +1,5 @@
 import { LayoutProps } from '../../props';
-interface HeaderProps extends Pick<LayoutProps, "title" | "logo" | "headerActions" | "userMenuItems" | "onLogout"> {
+interface HeaderProps extends Pick<LayoutProps, "title" | "logo" | "headerActions" | "userMenuItems" | "onUserMenuClick" | "onLogout"> {
 }
-export declare function Header({ title, logo, headerActions, userMenuItems, onLogout }: HeaderProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function Header({ title, logo, headerActions, userMenuItems, onUserMenuClick, onLogout }: HeaderProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/components/layout/components/header/user-avatar.d.ts

@@ -1,6 +1,6 @@
 import { LayoutProps } from '../../props';
-interface UserAvatarProps extends Pick<LayoutProps, "userMenuItems" | "onLogout"> {
+interface UserAvatarProps extends Pick<LayoutProps, "userMenuItems" | "onUserMenuClick" | "onLogout"> {
     className?: string;
 }
-export declare function UserAvatar({ className, userMenuItems, onLogout }: UserAvatarProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function UserAvatar({ className, userMenuItems, onUserMenuClick, onLogout }: UserAvatarProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/components/layout/index.d.ts

@@ -1,3 +1,3 @@
 import { LayoutProps } from './props';
-export declare function Layout({ title, logo, headerActions, userMenuItems, onLogout, children }: LayoutProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function Layout({ title, logo, headerActions, userMenuItems, onUserMenuClick, onLogout, children }: LayoutProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export { type LayoutProps } from './props';

package/dist/types/components/layout/props.d.ts

@@ -18,9 +18,15 @@ export interface LayoutProps extends PropsWithChildren {
      */
     headerActions?: ReactNode;
     /**
-     * The user menu items of the layout.
+     * Extra items appended to the user dropdown menu. They render before the
+     * built-in items (e.g. logout), with an automatic divider in between.
      */
     userMenuItems?: DropdownMenuProps["items"];
+    /**
+     * Handles clicks on user menu items. The built-in `logout` key is owned by
+     * the framework and never forwarded; all other keys are delivered here.
+     */
+    onUserMenuClick?: (key: string) => void;
     /**
      * The logout api function.
      */

package/dist/types/components/login/index.d.ts

@@ -1,4 +1,4 @@
 import { LoginProps } from './props';
 export declare function Login({ logo, title, description, publicKey, onLogin, onResolveChallenge, challengeRenderers }: LoginProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export { type LoginChallenge, type LoginParams, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './payload';
-export { type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginProps } from './props';
+export { type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginProps } from './props';

package/dist/types/components/login/payload.d.ts

@@ -1,4 +1,5 @@
 import { AuthTokens } from '../../models';
+import { ResolvedChallenges } from '../../types/common';
 /**
  * The payload for login
  */
@@ -31,21 +32,19 @@ export interface PasswordLoginParams extends BaseLoginParams<string> {
 }
 /**
  * A challenge the user must complete during login (e.g., 2FA, department selection).
+ *
+ * When `Register['challenges']` is augmented by the consuming project, this becomes
+ * a discriminated union narrowed per `type`, with `data` typed to the augmented
+ * spec. Without augmentation, it degrades to `{ type: string; data: unknown }` —
+ * exactly today's wire shape.
  */
-export interface LoginChallenge {
-    /**
-     * The challenge type identifier (e.g., "totp", "select_department")
-     */
-    type: string;
-    /**
-     * Optional challenge-specific data
-     */
-    data?: unknown;
-    /**
-     * Whether the challenge is required
-     */
-    required: boolean;
-}
+export type LoginChallenge = {
+    [K in keyof ResolvedChallenges]: {
+        type: K;
+        data: ResolvedChallenges[K]["data"];
+        required: boolean;
+    };
+}[keyof ResolvedChallenges];
 /**
  * The result of a login attempt.
  * When a challenge is pending, tokens is undefined and challengeToken + challenge are set.

package/dist/types/components/login/props.d.ts

@@ -1,23 +1,30 @@
 import { ReactNode } from 'react';
+import { ResolvedChallenges } from '../../types/common';
 import { LoginChallenge, LoginParams, LoginResult, ResolveChallengeParams } from './payload';
 /**
  * Arguments passed to a challenge renderer. Renderers are stateless from the
  * Login component's perspective — they consume `challenge` for prompt data
  * and call `resolve` / `cancel` to drive the flow forward or backward.
+ *
+ * Parameterised by `K`, the specific challenge type the renderer is bound to.
+ * When projects augment `Register['challenges']`, `challenge.data` and the
+ * `resolve` argument are both narrowed to the corresponding spec entry.
  */
-export interface LoginChallengeRendererProps {
+export interface LoginChallengeRendererProps<K extends keyof ResolvedChallenges = keyof ResolvedChallenges> {
     /**
      * The pending challenge to present (type identifier and challenge-specific data).
      */
-    challenge: LoginChallenge;
+    challenge: Extract<LoginChallenge, {
+        type: K;
+    }>;
     /**
      * Submit the user's answer to the current challenge. The concrete shape of
-     * `response` is decided by each challenge type — renderers narrow it
-     * internally before calling this.
+     * `response` is dictated by the augmented `ResolvedChallenges[K]['response']`;
+     * without augmentation, it falls back to `unknown`.
      * Returns once the resulting `LoginResult` has been applied — either the
      * next challenge is shown or authentication completes and navigation runs.
      */
-    resolve: (response: unknown) => Promise<void>;
+    resolve: (response: ResolvedChallenges[K]["response"]) => Promise<void>;
     /**
      * Abandon the challenge and return to the initial credentials form.
      * The held challenge token is discarded; the user must log in again.
@@ -46,7 +53,16 @@ export interface LoginChallengeRendererProps {
  * Business apps register one per challenge type they support; the Login
  * component looks up the renderer by `challenge.type` at runtime.
  */
-export type LoginChallengeRenderer = (props: LoginChallengeRendererProps) => ReactNode;
+export type LoginChallengeRenderer<K extends keyof ResolvedChallenges = keyof ResolvedChallenges> = (props: LoginChallengeRendererProps<K>) => ReactNode;
+/**
+ * The full renderer registry — one renderer per known challenge type. When
+ * `Register['challenges']` is augmented, TypeScript enforces exhaustiveness
+ * (every declared challenge must have a renderer) and per-key typing of the
+ * `challenge.data` / `resolve` payloads.
+ */
+export type LoginChallengeRenderers = {
+    [K in keyof ResolvedChallenges]: LoginChallengeRenderer<K>;
+};
 /**
  * The shared subset of LoginProps, independent of whether the flow may
  * surface challenges.
@@ -81,7 +97,7 @@ interface BaseLoginProps {
  */
 interface LoginPropsWithChallenge {
     onResolveChallenge: (params: ResolveChallengeParams) => Promise<LoginResult>;
-    challengeRenderers: Record<string, LoginChallengeRenderer>;
+    challengeRenderers: LoginChallengeRenderers;
 }
 /**
  * Login wiring for backends that never issue challenges.

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './components';
+export { type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './components';
 export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH } from './constants';
 export { createApiClient, createApp, createRouter, dispatchCustomEvent, emitAccessDenied, emitUnauthenticated, extractQueryParams, handleClientLogout, noopMutationFn, setupAppVersionNotification, type ApiClientOptions, type AppChangelog, type AppVersionNotificationOptions, type RouterOptions } from './helpers';
 export { createAccessDeniedRouteOptions, createLayoutRouteOptions, createLoginRouteOptions, createRootRouteOptions } from './routes';

package/dist/types/types/common.d.ts

@@ -13,7 +13,8 @@ export interface UserMenu {
  * Extension registry for framework types.
  *
  * Projects augment this interface via `declare module` to refine
- * extensible fields such as `UserInfo['details']`.
+ * extensible fields such as `UserInfo['details']` or the set of
+ * login challenge types the backend may issue.
  *
  * @example
  * declare module "@vef-framework-react/starter" {
@@ -22,6 +23,13 @@ export interface UserMenu {
  *       department: string;
  *       organization: string;
  *     };
+ *     challenges: {
+ *       department_selection: {
+ *         data: { departments: Array<{ id: string; name: string }> };
+ *         response: string;
+ *       };
+ *       totp: { response: string };
+ *     };
  *   }
  * }
  */
@@ -34,6 +42,22 @@ export type UserDetails = Record<string, unknown>;
 type ResolvedUserDetails = Register extends {
     userDetails: infer T extends UserDetails;
 } ? T : UserDetails;
+/**
+ * Contract for a single login challenge type. `data` is the payload the
+ * server attaches to the challenge for the renderer to display; `response`
+ * is the value the renderer feeds back to `resolve`.
+ */
+export interface ChallengeSpec {
+    data?: unknown;
+    response: unknown;
+}
+/**
+ * Resolved challenge registry. Falls back to an open `Record` so codebases
+ * that never augment `Register['challenges']` retain today's loose typing.
+ */
+export type ResolvedChallenges = Register extends {
+    challenges: infer T extends Record<string, ChallengeSpec>;
+} ? T : Record<string, ChallengeSpec>;
 export interface UserInfo {
     id: string;
     name: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework-react/starter",
   "type": "module",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "private": false,
   "description": "Starter for VEF framework",
   "author": {
@@ -64,10 +64,10 @@
     "@tanstack/react-router": "^1.170.1",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "@vef-framework-react/components": "2.2.0",
-    "@vef-framework-react/core": "2.2.0",
-    "@vef-framework-react/hooks": "2.2.0",
-    "@vef-framework-react/shared": "2.2.0"
+    "@vef-framework-react/components": "2.2.2",
+    "@vef-framework-react/core": "2.2.2",
+    "@vef-framework-react/shared": "2.2.2",
+    "@vef-framework-react/hooks": "2.2.2"
   },
   "scripts": {
     "clean": "rimraf dist",