@mdxui/auth 1.1.0 → 1.4.0

package/dist/shell/index.d.ts

@@ -0,0 +1,675 @@
+import * as react from 'react';
+import { ReactNode, ComponentType, Component } from 'react';
+import { LucideIcon } from 'lucide-react';
+import { ThemeMode, AuthShellConfig, RouteGroup, ProtectedRoute } from 'mdxui';
+export { AuthShellConfig, ProtectedRoute, RouteGroup, ThemeMode } from 'mdxui';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Shell Type Definitions
+ *
+ * Extended types for the auth shell that build on mdxui base types.
+ * These types include React-specific fields (ReactNode, ComponentType)
+ * that cannot be represented in Zod schemas.
+ */
+
+/**
+ * Identity configuration for WorkOS AuthKit
+ *
+ * Configures the authentication provider including client ID,
+ * dev mode settings, and unauthenticated behavior.
+ */
+interface AuthShellIdentity {
+    /** WorkOS client ID */
+    clientId: string;
+    /** Optional API hostname override */
+    apiHostname?: string;
+    /** Enable dev mode for local development */
+    devMode?: boolean;
+    /** Redirect URI after authentication */
+    redirectUri?: string;
+    /** Whether authentication is required (default: true) */
+    required?: boolean;
+    /** Behavior when unauthenticated */
+    onUnauthenticated?: 'landing' | 'redirect' | 'allow' | 'signIn';
+    /** Custom landing page component */
+    landingComponent?: ReactNode;
+    /** Custom loading component */
+    loadingComponent?: ReactNode;
+}
+/**
+ * Branding configuration
+ *
+ * Defines the app's branding including name, logo, and tagline.
+ * Logo accepts a React element for flexibility (SVG, img, etc).
+ */
+interface AuthShellBranding {
+    /** Application name */
+    name: string;
+    /** Logo element (React component or element) */
+    logo?: ReactNode;
+    /** Collapsed logo for icon-only sidebar state */
+    logoCollapsed?: ReactNode;
+    /** Tagline or description */
+    tagline?: string;
+}
+/**
+ * Route with React component
+ *
+ * Extends the base ProtectedRoute from mdxui with React-specific
+ * fields that can't be represented in Zod schemas.
+ */
+interface AuthAppRoute extends Omit<ProtectedRoute, 'icon'> {
+    /** React component to render for this route */
+    component: ComponentType;
+    /** Lucide icon component */
+    icon?: LucideIcon;
+}
+/**
+ * Full application configuration
+ *
+ * Combines all configuration needed to set up an authenticated
+ * application shell with routing, branding, and identity.
+ */
+interface AuthAppConfig {
+    /** Base path for all routes (default: '') */
+    basePath?: string;
+    /** Branding configuration */
+    branding: AuthShellBranding;
+    /** Theme configuration */
+    theme?: {
+        /** Theme mode (light, dark, system) */
+        mode?: ThemeMode;
+    };
+    /** Identity/auth configuration */
+    identity: AuthShellIdentity;
+    /** Auth shell configuration (from mdxui) */
+    auth?: AuthShellConfig;
+    /** Route groups for navigation organization */
+    groups?: RouteGroup[];
+    /** Application routes (defaults to standard account/developer/admin routes) */
+    routes?: AuthAppRoute[];
+}
+/**
+ * Props for AuthShell component
+ */
+interface AuthShellProps {
+    /** Shell content */
+    children: ReactNode;
+    /** Custom content for sidebar header */
+    sidebarHeaderContent?: ReactNode;
+    /** Custom content for main header */
+    headerContent?: ReactNode;
+    /** Breadcrumb items */
+    breadcrumbs?: Array<{
+        label: string;
+        href?: string;
+    }>;
+}
+/**
+ * Props for AuthShellNav component
+ */
+interface AuthShellNavProps {
+    /** Custom content for sidebar header */
+    headerContent?: ReactNode;
+    /** Custom user menu (uses default if not provided) */
+    userMenu?: ReactNode;
+    /** Additional CSS class */
+    className?: string;
+}
+/**
+ * Props for AuthApp component
+ *
+ * Config is optional when environment variables are set:
+ * - VITE_WORKOS_CLIENT_ID (required)
+ * - VITE_WORKOS_REDIRECT_URI
+ * - VITE_WORKOS_API_HOSTNAME
+ * - VITE_WORKOS_DEV_MODE
+ * - VITE_APP_NAME
+ * - VITE_APP_TAGLINE
+ */
+interface AuthAppProps {
+    /**
+     * Application configuration
+     *
+     * Optional when VITE_WORKOS_CLIENT_ID environment variable is set.
+     * Explicit config values take precedence over environment variables.
+     */
+    config?: Partial<AuthAppConfig>;
+    /** Custom content for main header */
+    headerContent?: ReactNode;
+    /** Custom content for sidebar header */
+    sidebarHeaderContent?: ReactNode;
+}
+
+/**
+ * Context value shape
+ */
+interface AuthShellConfigContextValue {
+    /** Full configuration */
+    config: AuthAppConfig;
+    /** All enabled routes */
+    routes: AuthAppRoute[];
+    /** Routes organized by group */
+    routesByGroup: Map<string, AuthAppRoute[]>;
+    /** Route groups sorted by order */
+    groups: RouteGroup[];
+    /** Branding configuration */
+    branding: AuthShellBranding;
+    /** Base path for routes */
+    basePath: string;
+}
+/**
+ * Props for AuthShellConfigProvider
+ */
+interface AuthShellConfigProviderProps {
+    /** Shell configuration */
+    config: AuthAppConfig;
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * Provides shell configuration context to children
+ *
+ * @example
+ * ```tsx
+ * <AuthShellConfigProvider config={config}>
+ *   <AuthShell>
+ *     <Outlet />
+ *   </AuthShell>
+ * </AuthShellConfigProvider>
+ * ```
+ */
+declare function AuthShellConfigProvider({ config, children }: AuthShellConfigProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the full shell configuration context
+ *
+ * @throws Error if used outside AuthShellConfigProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { config, routes, branding } = useAuthShellConfig()
+ *   return <div>{branding.name}</div>
+ * }
+ * ```
+ */
+declare function useAuthShellConfig(): AuthShellConfigContextValue;
+/**
+ * Access enabled routes array
+ *
+ * @example
+ * ```tsx
+ * function RouteList() {
+ *   const routes = useAuthShellRoutes()
+ *   return routes.map(r => <Link key={r.key} to={r.path}>{r.label}</Link>)
+ * }
+ * ```
+ */
+declare function useAuthShellRoutes(): AuthAppRoute[];
+/**
+ * Access routes organized by group
+ *
+ * @example
+ * ```tsx
+ * function GroupedNav() {
+ *   const { routesByGroup, groups } = useAuthShellRoutesByGroup()
+ *   return groups.map(g => (
+ *     <div key={g.id}>
+ *       {g.label && <h3>{g.label}</h3>}
+ *       {routesByGroup.get(g.id)?.map(r => <Link to={r.path}>{r.label}</Link>)}
+ *     </div>
+ *   ))
+ * }
+ * ```
+ */
+declare function useAuthShellRoutesByGroup(): {
+    routesByGroup: Map<string, AuthAppRoute[]>;
+    groups: RouteGroup[];
+};
+/**
+ * Access branding configuration
+ *
+ * @example
+ * ```tsx
+ * function Header() {
+ *   const branding = useAuthShellBranding()
+ *   return (
+ *     <header>
+ *       {branding.logo}
+ *       <span>{branding.name}</span>
+ *     </header>
+ *   )
+ * }
+ * ```
+ */
+declare function useAuthShellBranding(): AuthShellBranding;
+/**
+ * Get full path with base path prefix
+ *
+ * @example
+ * ```tsx
+ * function NavLink({ route }: { route: AuthAppRoute }) {
+ *   const getFullPath = useAuthShellFullPath()
+ *   return <Link to={getFullPath(route.path)}>{route.label}</Link>
+ * }
+ * ```
+ */
+declare function useAuthShellFullPath(): (path: string) => string;
+
+/**
+ * AuthShell - Main application shell layout
+ *
+ * Wraps content in authentication gate and provides
+ * sidebar navigation with header and main content area.
+ *
+ * @example
+ * ```tsx
+ * <AuthShellConfigProvider config={config}>
+ *   <IdentityProvider clientId={config.identity.clientId}>
+ *     <AuthShell breadcrumbs={[{ label: 'Dashboard' }]}>
+ *       <Outlet />
+ *     </AuthShell>
+ *   </IdentityProvider>
+ * </AuthShellConfigProvider>
+ * ```
+ */
+declare function AuthShell({ children, sidebarHeaderContent, headerContent, breadcrumbs, }: AuthShellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * AuthShellNav - Sidebar navigation component
+ *
+ * Renders navigation routes organized by group with branding
+ * header and user menu footer.
+ *
+ * @example
+ * ```tsx
+ * <AuthShellNav
+ *   headerContent={<TeamSwitcher />}
+ *   userMenu={<CustomUserMenu />}
+ * />
+ * ```
+ */
+declare function AuthShellNav({ headerContent, userMenu, className }: AuthShellNavProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for AuthAppProvider (providers only, no shell or routing)
+ */
+interface AuthAppProviderProps {
+    /**
+     * Application configuration
+     *
+     * Optional when VITE_WORKOS_CLIENT_ID environment variable is set.
+     */
+    config?: Partial<AuthAppConfig>;
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * AuthAppProvider - Providers only wrapper
+ *
+ * Use this when you need to customize the shell layout or
+ * integrate with an existing routing setup.
+ *
+ * Provider hierarchy:
+ * - ThemeProvider (next-themes)
+ * - AuthShellConfigProvider
+ * - IdentityProvider (WorkOS AuthKit)
+ *
+ * @example
+ * ```tsx
+ * <AuthAppProvider config={config}>
+ *   <RouterProvider router={router}>
+ *     <AuthShell>
+ *       <Outlet />
+ *     </AuthShell>
+ *   </RouterProvider>
+ * </AuthAppProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Zero-config with environment variables
+ * <AuthAppProvider>
+ *   <MyApp />
+ * </AuthAppProvider>
+ * ```
+ */
+declare function AuthAppProvider({ config, children }: AuthAppProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * AuthApp - Complete app with built-in routing
+ *
+ * This is the recommended way to use AuthApp. Define your routes
+ * in the config and AuthApp handles routing automatically.
+ *
+ * @example
+ * ```tsx
+ * // Zero-config with environment variables
+ * // Set VITE_WORKOS_CLIENT_ID, VITE_APP_NAME in .env
+ * function App() {
+ *   return <AuthApp />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import { AuthApp, type AuthAppConfig } from '@mdxui/auth/shell'
+ * import { Home, Settings, Users } from 'lucide-react'
+ *
+ * const config: AuthAppConfig = {
+ *   branding: { name: 'My App' },
+ *   identity: { clientId: 'client_xxx' },
+ *   routes: [
+ *     { key: 'home', label: 'Home', path: '/', icon: Home, component: HomePage },
+ *     { key: 'settings', label: 'Settings', path: '/settings', icon: Settings, component: SettingsPage },
+ *     { key: 'users', label: 'Users', path: '/users', icon: Users, component: UsersPage },
+ *   ],
+ * }
+ *
+ * function App() {
+ *   return <AuthApp config={config} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom header content (sidebar defaults to SidebarOrgSwitcher)
+ * <AuthApp
+ *   config={config}
+ *   headerContent={<ThemeSwitcher />}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Override sidebar header with custom content
+ * <AuthApp
+ *   config={config}
+ *   sidebarHeaderContent={<MyCustomSwitcher />}
+ * />
+ * ```
+ */
+declare function AuthApp({ config, headerContent, sidebarHeaderContent }: AuthAppProps): react_jsx_runtime.JSX.Element;
+/**
+ * AuthAppWithChildren - App wrapper with shell but no routing
+ *
+ * Use this when you want the shell but handle routing yourself,
+ * or when you have simple static content.
+ *
+ * @example
+ * ```tsx
+ * // Zero-config with environment variables
+ * <AuthAppWithChildren>
+ *   <Dashboard />
+ * </AuthAppWithChildren>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With your own router
+ * <AuthAppWithChildren config={config}>
+ *   <Routes>
+ *     <Route path="/" element={<Home />} />
+ *     <Route path="/settings" element={<Settings />} />
+ *   </Routes>
+ * </AuthAppWithChildren>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With static content
+ * <AuthAppWithChildren config={config}>
+ *   <Dashboard />
+ * </AuthAppWithChildren>
+ * ```
+ */
+declare function AuthAppWithChildren({ config, headerContent, sidebarHeaderContent, children, }: AuthAppProps & {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the Link component
+ */
+interface BreadcrumbLinkProps {
+    href: string;
+    children: react.ReactNode;
+    className?: string;
+    onClick?: () => void;
+}
+/**
+ * Single breadcrumb item configuration
+ */
+interface BreadcrumbItemConfig {
+    /** Display label */
+    label: string;
+    /** Route path - last item should not have href */
+    href?: string;
+}
+/**
+ * Props for the Breadcrumbs component
+ */
+interface BreadcrumbsProps {
+    /** Array of breadcrumb items */
+    items: BreadcrumbItemConfig[];
+    /** Custom link component (e.g., Next.js Link, TanStack Link). Defaults to WebLink */
+    LinkComponent?: react.ComponentType<BreadcrumbLinkProps>;
+    /** Additional class names */
+    className?: string;
+    /** Maximum items to show before collapsing */
+    maxItems?: number;
+    /** Custom separator element */
+    separator?: react.ReactNode;
+}
+/**
+ * Breadcrumbs provides navigation context showing the user's location.
+ *
+ * Features:
+ * - Router-agnostic - works with any Link component
+ * - Defaults to @mdxui/navigation/web WebLink for TanStack Router
+ * - Automatic collapse with dropdown for long paths
+ * - Accessible breadcrumb semantics
+ * - Custom separator support
+ *
+ * @example
+ * ```tsx
+ * // With default WebLink (TanStack Router)
+ * <Breadcrumbs
+ *   items={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Users', href: '/users' },
+ *     { label: 'John Doe' },
+ *   ]}
+ * />
+ *
+ * // With Next.js Link
+ * import NextLink from 'next/link'
+ *
+ * <Breadcrumbs
+ *   items={breadcrumbItems}
+ *   LinkComponent={NextLink}
+ * />
+ *
+ * // With custom Link wrapper
+ * <Breadcrumbs
+ *   items={breadcrumbItems}
+ *   LinkComponent={({ href, children, className }) => (
+ *     <MyCustomLink to={href} className={className}>{children}</MyCustomLink>
+ *   )}
+ * />
+ * ```
+ */
+declare function Breadcrumbs({ items, LinkComponent, className, maxItems, separator, }: BreadcrumbsProps): react_jsx_runtime.JSX.Element | null;
+declare namespace Breadcrumbs {
+    var displayName: string;
+}
+
+/**
+ * Pre-wired OrganizationSwitcher for sidebar header.
+ *
+ * Automatically uses shell branding context - when the user belongs to an
+ * organization, shows the OrganizationSwitcher widget. When not in an
+ * organization, falls back to displaying the app branding (logo + name).
+ *
+ * This component is used by default in AuthApp and AuthAppWithChildren.
+ * You only need to explicitly pass it if using AuthShell directly or
+ * if you want to override the default with a custom component.
+ *
+ * @example
+ * ```tsx
+ * // AuthApp uses SidebarOrgSwitcher by default - no config needed!
+ * import { AuthApp } from '@mdxui/auth/shell'
+ *
+ * <AuthApp config={config} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With AuthShell directly (manual setup)
+ * import { AuthShell, SidebarOrgSwitcher } from '@mdxui/auth/shell'
+ *
+ * <AuthShell sidebarHeaderContent={<SidebarOrgSwitcher />}>
+ *   <Outlet />
+ * </AuthShell>
+ * ```
+ */
+declare function SidebarOrgSwitcher(): react_jsx_runtime.JSX.Element;
+
+/** Known widget names with custom error messages */
+type KnownWidgetName = 'profile' | 'security' | 'sessions' | 'api-keys' | 'team' | 'integrations';
+interface WidgetErrorBoundaryProps {
+    children: ReactNode;
+    /** Widget name for contextual error messages (known names get fun messages, others get a friendly default) */
+    widgetName?: KnownWidgetName | (string & {});
+    /** Custom fallback UI (overrides default error message) */
+    fallback?: ReactNode;
+}
+interface WidgetErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+}
+/**
+ * Error boundary for WorkOS widgets.
+ * Catches rendering errors and displays a friendly, contextual fallback UI.
+ */
+declare class WidgetErrorBoundary extends Component<WidgetErrorBoundaryProps, WidgetErrorBoundaryState> {
+    constructor(props: WidgetErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): WidgetErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+/**
+ * Profile page that renders the UserProfile widget
+ *
+ * Displays user account information including name, email, and profile picture.
+ */
+declare function ProfilePage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Security page that renders the UserSecurity widget
+ *
+ * Allows users to manage password and MFA settings.
+ */
+declare function SecurityPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Sessions page that renders the UserSessions widget
+ *
+ * Displays active sessions and allows users to revoke them.
+ */
+declare function SessionsPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * API Keys page that renders the ApiKeys widget
+ *
+ * Allows users to create and manage their API keys.
+ */
+declare function ApiKeysPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Team page that renders the UsersManagement widget
+ *
+ * Requires organization membership and admin permissions to view.
+ */
+declare function TeamPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Integrations page that renders the Pipes widget
+ *
+ * Allows users to connect and manage third-party integrations.
+ */
+declare function IntegrationsPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Route Presets
+ *
+ * Default route configurations for AuthApp. These provide a zero-config
+ * experience - just provide branding and identity config to get started.
+ */
+
+/**
+ * Default route groups for organizing navigation
+ */
+declare const defaultGroups: RouteGroup[];
+/**
+ * Account management routes
+ */
+declare const accountRoutes: AuthAppRoute[];
+/**
+ * Developer-focused routes
+ */
+declare const developerRoutes: AuthAppRoute[];
+/**
+ * Admin/team management routes
+ */
+declare const adminRoutes: AuthAppRoute[];
+/**
+ * Integration routes (optional, not included in defaults)
+ */
+declare const integrationRoutes: AuthAppRoute[];
+/**
+ * Default routes - all standard routes combined
+ *
+ * Includes: account, developer, and admin routes
+ * Does NOT include: integrationRoutes (opt-in)
+ */
+declare const defaultRoutes: AuthAppRoute[];
+
+/**
+ * Environment Variable Configuration
+ *
+ * Reads configuration from environment variables for zero-config setup.
+ * Supports Vite's import.meta.env pattern for Cloudflare Workers Static Assets.
+ *
+ * Environment variables:
+ * - VITE_WORKOS_CLIENT_ID - WorkOS client ID (required for zero-config)
+ * - VITE_WORKOS_REDIRECT_URI - OAuth redirect URI
+ * - VITE_WORKOS_API_HOSTNAME - WorkOS API hostname override
+ * - VITE_WORKOS_DEV_MODE - Enable dev mode ("true" or "false")
+ * - VITE_APP_NAME - Application name for branding
+ * - VITE_APP_TAGLINE - Application tagline
+ *
+ * @example
+ * ```bash
+ * # .env file
+ * VITE_WORKOS_CLIENT_ID=client_01JQYTRXK9ZPD8JPJTKDCRB656
+ * VITE_WORKOS_REDIRECT_URI=https://oauth.do/callback
+ * VITE_APP_NAME=OAuth.do
+ * ```
+ */
+
+/**
+ * Get configuration from environment variables
+ *
+ * Returns a partial config that can be merged with explicit config.
+ * Missing required fields will cause runtime errors if not provided elsewhere.
+ */
+declare function getEnvConfig(): Partial<AuthAppConfig>;
+/**
+ * Merge explicit config with environment config
+ *
+ * Explicit config takes precedence over environment variables.
+ */
+declare function mergeWithEnvConfig(config?: Partial<AuthAppConfig>): AuthAppConfig;
+
+export { ApiKeysPage, AuthApp, type AuthAppConfig, type AuthAppProps, AuthAppProvider, type AuthAppRoute, AuthAppWithChildren, AuthShell, type AuthShellBranding, AuthShellConfigProvider, type AuthShellIdentity, AuthShellNav, type AuthShellNavProps, type AuthShellProps, type BreadcrumbItemConfig, type BreadcrumbLinkProps, Breadcrumbs, type BreadcrumbsProps, IntegrationsPage, ProfilePage, SecurityPage, SessionsPage, SidebarOrgSwitcher, TeamPage, WidgetErrorBoundary, accountRoutes, adminRoutes, defaultGroups, defaultRoutes, developerRoutes, getEnvConfig, integrationRoutes, mergeWithEnvConfig, useAuthShellBranding, useAuthShellConfig, useAuthShellFullPath, useAuthShellRoutes, useAuthShellRoutesByGroup };