@tailor-platform/app-shell 0.26.2 → 0.27.0

package/dist/{index.d.ts → app-shell.d.ts}

@@ -1,9 +1,9 @@
 import { AuthClient } from '@tailor-platform/auth-public-client';
 import { ClassProp } from 'class-variance-authority/types';
+import { FC } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { Link } from 'react-router';
 import { LoaderFunctionArgs } from 'react-router';
-import { Params } from 'react-router';
 import * as React_2 from 'react';
 import { ReactNode } from 'react';
 import { toast } from 'sonner';
@@ -14,7 +14,10 @@ import { useRouteError } from 'react-router';
 import { useSearchParams } from 'react-router';
 import { VariantProps } from 'class-variance-authority';
 
-export declare const AppShell: (props: AppShellProps) => JSX.Element | null;
+export declare const AppShell: {
+    (props: AppShellProps): JSX.Element | null;
+    /* Excluded from this release type: WithPages */
+};
 
 /**
  * Context for static configuration (title, icon, configurations).
@@ -34,102 +37,93 @@ declare type AppShellDataContextType = {
     contextData: ContextData;
 };
 
-export declare type AppShellProps = React.PropsWithChildren<{
-    /**
-     * App shell title
-     */
-    title?: string;
-    /**
-     * App shell icon
-     */
-    icon?: React.ReactNode;
+/**
+ * Props that can be attached to a page component via static field.
+ *
+ * @example
+ * ```tsx
+ * const DashboardPage = () => <div>Dashboard</div>;
+ *
+ * DashboardPage.appShellPageProps = {
+ *   meta: { title: "Dashboard", icon: <DashboardIcon /> },
+ *   guards: [authGuard],
+ * } satisfies AppShellPageProps;
+ *
+ * export default DashboardPage;
+ * ```
+ */
+export declare type AppShellPageProps = {
     /**
-     * Base path for the app shell
+     * Metadata for the page used in navigation and breadcrumbs.
      */
-    basePath?: string;
+    meta?: {
+        /**
+         * Title of the page displayed in navigation and breadcrumbs.
+         * Supports localized strings with translations.
+         */
+        title?: LocalizedString;
+        /**
+         * Icon displayed alongside the title in navigation.
+         */
+        icon?: ReactNode;
+    };
     /**
-     * A component to be rendered at the root level of AppShell.
-     * Use guards with redirectTo() for redirects.
+     * Guards to control access to this page.
+     * Guards are executed in order. Each page must define its own guards explicitly.
      *
      * @example
      * ```tsx
-     * rootComponent: () => <DashboardHome />
+     * guards: [authGuard, adminGuard]
      * ```
      */
-    rootComponent?: () => React.ReactNode;
-    /**
-     * Navigation configuration
-     */
-    modules: Modules;
-    /**
-     * Settings resources to be included in the settings menu
-     */
-    settingsResources?: Array<Resource>;
+    guards?: Guard[];
     /**
-     * Locale code used for built-in UI strings.
-     *
-     * If not provided, auto-detects from browser preferences.
-     * No browser locale information avilable, "en" used as default.
+     * Loader function to fetch data before rendering the page.
      */
-    locale?: string;
+    loader?: LoaderHandler;
+};
+
+/**
+ * Props for AppShell component.
+ *
+ * Routes can be configured in two ways:
+ * 1. **Automatic (recommended)**: Use the vite-plugin which automatically
+ *    configures pages via `AppShell.WithPages()`.
+ * 2. **Explicit modules**: Pass the `modules` prop for manual configuration.
+ *
+ * @example
+ * ```tsx
+ * // Automatic mode (configured by vite-plugin)
+ * import { AppShell } from "@tailor-platform/app-shell";
+ *
+ * <AppShell title="My App">
+ *   <SidebarLayout />
+ * </AppShell>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Explicit modules mode
+ * import { AppShell, defineModule } from "@tailor-platform/app-shell";
+ *
+ * <AppShell title="My App" modules={[...]}>
+ *   <SidebarLayout />
+ * </AppShell>
+ * ```
+ */
+export declare type AppShellProps = SharedAppShellProps & {
     /**
-     * Global error boundary component applied to all routes.
-     *
-     * When an error occurs in any route component, this component will render.
-     * Module and resource-level error boundaries take precedence over this.
-     * Use the `useRouteError` hook to access error details within the component.
-     *
-     * @example
-     * ```tsx
-     * import { useRouteError } from "@tailor-platform/app-shell";
-     *
-     * const GlobalErrorBoundary = () => {
-     *   const error = useRouteError() as Error;
-     *   return (
-     *     <div>
-     *       <h1>Something went wrong</h1>
-     *       <p>{error.message}</p>
-     *     </div>
-     *   );
-     * };
+     * Navigation configuration.
      *
-     * <AppShell
-     *   modules: [...],
-     *   errorBoundary: <GlobalErrorBoundary />,
-     * />
-     * ```
+     * When using vite-plugin, this is automatically set via `AppShell.WithPages()`.
+     * For manual configuration, pass modules directly.
      */
-    errorBoundary?: ErrorBoundaryComponent;
-    /**
-     * Custom context data accessible from guards and components.
-     *
-     * Use module augmentation to define the type of context data:
-     *
-     * @example
-     * ```typescript
-     * // types.d.ts
-     * declare module "@tailor-platform/app-shell" {
-     *   interface AppShellRegister {
-     *     contextData: {
-     *       apiClient: ApiClient;
-     *       currentUser: User;
-     *     };
-     *   }
-     * }
-     *
-     * // App.tsx
-     * <AppShell
-     *   modules={modules}
-     *   contextData={{ apiClient, currentUser }}
-     * />
-     * ```
-     */
-    contextData?: ContextData;
-}>;
+    modules?: Modules;
+};
 
 /**
  * Empty interface for module augmentation.
- * Users can extend this to define their own context data type.
+ * Users can extend this to define their own context data type and route parameters.
  *
  * @example
  * ```typescript
@@ -139,6 +133,11 @@ export declare type AppShellProps = React.PropsWithChildren<{
  *       apiClient: ApiClient;
  *       currentUser: User;
  *     };
+ *     routeParams: {
+ *       "/": {};
+ *       "/dashboard": {};
+ *       "/orders/:id": { id: string };
+ *     };
  *   }
  * }
  * ```
@@ -292,9 +291,9 @@ declare type CommonProps = {
      */
     path: string;
     /**
-     * Metadata for the resource.
+     * Metadata for the page.
      */
-    meta?: ResourceMetaProps;
+    meta?: ResourceMeta;
     /**
      * Guards to control access to this module/resource.
      * Guards are executed in order. If any guard returns non-pass result,
@@ -321,16 +320,76 @@ export declare type ContextData = AppShellRegister extends {
 
 export declare function createAuthClient(config: AuthClientConfig): EnhancedAuthClient;
 
+/**
+ * Create a type-safe path builder from route definitions.
+ *
+ * This factory is designed to work with auto-generated RouteParams types
+ * from the vite-plugin's `generateTypedRoutes` option.
+ *
+ * @typeParam TRoutes - Mapping of route paths to their parameter types
+ * @returns TypedPaths instance with `for()` method
+ *
+ * @example
+ * ```ts
+ * type RouteParams = {
+ *   "/dashboard": {};
+ *   "/orders/:id": { id: string };
+ *   "/orders/:orderId/items/:itemId": { orderId: string; itemId: string };
+ * };
+ *
+ * const paths = createTypedPaths<RouteParams>();
+ *
+ * paths.for("/dashboard"); // ✅
+ * paths.for("/orders/:id", { id: "123" }); // ✅
+ * paths.for("/orders/:id"); // ❌ TypeScript error: params required
+ * paths.for("/invalid"); // ❌ TypeScript error: path not found
+ * ```
+ */
+export declare function createTypedPaths<TRoutes extends Record<string, Record<string, string>>>(): TypedPaths<TRoutes>;
+
 /**
  * Date format options
  */
 declare type DateFormat = "short" | "medium" | "long" | "relative";
 
+/**
+ * Default sidebar component with auto-generated navigation items.
+ *
+ * It works in both auto-generation mode and composition mode.
+ * - Auto-generation mode: when no children are provided, it automatically generates sidebar items based on the application's resource definitions.
+ * - Composition mode: when children are provided, it allows developers to manually define the sidebar structure using SidebarItem, SidebarGroup, and other components.
+ *
+ * @example
+ * ```tsx
+ * // Auto-generation mode
+ * <DefaultSidebar />
+ *
+ * // Composition mode
+ * <DefaultSidebar>
+ *   <SidebarItem to="/dashboard" />
+ *   <SidebarGroup title="products">
+ *     <SidebarItem to="/products/all" />
+ *   </SidebarGroup>
+ *   <SidebarSeparator />
+ * </DefaultSidebar>
+ * ```
+ */
 export declare const DefaultSidebar: (props: DefaultSidebarProps) => JSX.Element;
 
-declare type DefaultSidebarProps = {
+export declare type DefaultSidebarProps = {
+    /**
+     * Header content.
+     */
     header?: React.ReactNode;
+    /**
+     * Footer content.
+     */
     footer?: React.ReactNode;
+    /**
+     * When provided, enables explicit sidebar composition using React components.
+     * Auto-generation is completely disabled when children is specified.
+     */
+    children?: React.ReactNode;
 };
 
 /**
@@ -451,7 +510,9 @@ export declare function defineModule(props: DefineModuleProps): Module;
 declare type DefineModuleProps = CommonProps & CommonModuleProps & {
     /**
      * React component to render.
-     * If not provided, the module will redirect to the first resource.
+     *
+     * If not provided, a guard with `redirectTo()` must be used to redirect
+     * users to the appropriate resource.
      *
      * @example
      * ```tsx
@@ -609,6 +670,35 @@ export declare interface EnhancedAuthClient extends AuthClient {
  */
 export declare type ErrorBoundaryComponent = ReactNode;
 
+/**
+ * Type-safe path builder for file-based routing.
+ *
+ * This module provides a factory function to create type-safe path builders
+ * that work with auto-generated route type definitions.
+ *
+ * @example
+ * ```ts
+ * // In routes.generated.ts (auto-generated by vite-plugin)
+ * import { createTypedPaths } from "@tailor-platform/app-shell";
+ *
+ * type RouteParams = {
+ *   "/": {};
+ *   "/dashboard": {};
+ *   "/orders/:id": { id: string };
+ * };
+ *
+ * export const paths = createTypedPaths<RouteParams>();
+ *
+ * // Usage
+ * paths.for("/orders/:id", { id: "123" }); // → "/orders/123"
+ * paths.for("/orders/:id?tab=details", { id: "123" }); // → "/orders/123?tab=details"
+ * ```
+ */
+/**
+ * Extract base path (before ?) from a path that may include query string.
+ */
+declare type ExtractBasePath<T extends string> = T extends `${infer Base}?${string}` ? Base : T;
+
 /**
  * A field configuration - either a divider or a field definition
  */
@@ -678,9 +768,6 @@ export declare type Guard = (ctx: GuardContext) => Promise<GuardResult> | GuardR
  * Context provided to guard functions
  */
 export declare type GuardContext = {
-    params: Params;
-    searchParams: URLSearchParams;
-    signal: AbortSignal;
     context: ContextData;
 };
 
@@ -724,6 +811,11 @@ export declare type I18nLabels<Def extends Record<string, LabelValue> = Record<s
     [K in L]: LabelDefinition<Def>;
 } & DynamicLocales<Def>;
 
+/**
+ * Check if an object type has no keys.
+ */
+declare type IsEmptyObject<T> = keyof T extends never ? true : false;
+
 /**
  * Ensures that other locales have the same label structure as the base definition.
  * For dynamic labels (functions), the props type must match.
@@ -812,6 +904,35 @@ declare type Module = Omit<CommonPageResource, "meta"> & {
 
 declare type Modules = Array<Module>;
 
+/**
+ * A React component that can be used as a page in file-based routing.
+ *
+ * The component can optionally have an `appShellPageProps` static field
+ * for configuring navigation metadata, guards, and loaders.
+ */
+export declare type PageComponent = FC & {
+    appShellPageProps?: AppShellPageProps;
+};
+
+/**
+ * A page entry generated by the Vite plugin from file system.
+ */
+declare type PageEntry = {
+    /**
+     * The resolved path for this page (e.g., "/dashboard/orders/:id")
+     */
+    path: string;
+    /**
+     * The page component with optional appShellProps
+     */
+    component: PageComponent;
+};
+
+export declare type PageMeta = {
+    title: string;
+    icon?: ReactNode;
+};
+
 /**
  * Allow access to the route. Continue to next guard or render component.
  *
@@ -871,16 +992,16 @@ export declare type ResourceComponentProps = {
     resources?: Array<Resource>;
 };
 
-declare type ResourceMetaProps = {
+declare type ResourceMeta = {
     /**
-     * Title of the resource used in navigation.
+     * Title of the page used in navigation.
      *
      * If not provided, the title will be generated from the path.
      */
     title?: LocalizedString;
     icon?: ReactNode;
     /**
-     * Custom breadcrumb segment title for this resource. Can be a string or a function.
+     * Custom breadcrumb segment title for this page. Can be a string or a function.
      */
     breadcrumbTitle?: string | ((segment: string) => string);
 };
@@ -893,15 +1014,284 @@ declare type RootConfiguration = {
     locale: string;
 };
 
+/**
+ * Route parameters type inferred from AppShellRegister.
+ * Falls back to Record<string, Record<string, string>> if not augmented.
+ * This is typically set by the generated routes file from vite-plugin.
+ */
+export declare type RouteParams = AppShellRegister extends {
+    routeParams: infer T;
+} ? T : Record<string, Record<string, string>>;
+
+declare type SharedAppShellProps = React.PropsWithChildren<{
+    /**
+     * App shell title
+     */
+    title?: string;
+    /**
+     * App shell icon
+     */
+    icon?: React.ReactNode;
+    /**
+     * Base path for the app shell
+     */
+    basePath?: string;
+    /**
+     * A component to be rendered at the root level of AppShell.
+     * Use guards with redirectTo() for redirects.
+     *
+     * @example
+     * ```tsx
+     * rootComponent: () => <DashboardHome />
+     * ```
+     */
+    rootComponent?: () => React.ReactNode;
+    /**
+     * Settings resources to be included in the settings menu
+     */
+    settingsResources?: Array<Resource>;
+    /**
+     * Locale code used for built-in UI strings.
+     *
+     * If not provided, auto-detects from browser preferences.
+     * No browser locale information avilable, "en" used as default.
+     */
+    locale?: string;
+    /**
+     * Global error boundary component applied to all routes.
+     *
+     * When an error occurs in any route component, this component will render.
+     * Module and resource-level error boundaries take precedence over this.
+     * Use the `useRouteError` hook to access error details within the component.
+     *
+     * @example
+     * ```tsx
+     * import { useRouteError } from "@tailor-platform/app-shell";
+     *
+     * const GlobalErrorBoundary = () => {
+     *   const error = useRouteError() as Error;
+     *   return (
+     *     <div>
+     *       <h1>Something went wrong</h1>
+     *       <p>{error.message}</p>
+     *     </div>
+     *   );
+     * };
+     *
+     * <AppShell
+     *   modules: [...],
+     *   errorBoundary: <GlobalErrorBoundary />,
+     * />
+     * ```
+     */
+    errorBoundary?: ErrorBoundaryComponent;
+    /**
+     * Custom context data accessible from guards and components.
+     *
+     * Use module augmentation to define the type of context data:
+     *
+     * @example
+     * ```typescript
+     * // types.d.ts
+     * declare module "@tailor-platform/app-shell" {
+     *   interface AppShellRegister {
+     *     contextData: {
+     *       apiClient: ApiClient;
+     *       currentUser: User;
+     *     };
+     *   }
+     * }
+     *
+     * // App.tsx
+     * <AppShell
+     *   modules={modules}
+     *   contextData={{ apiClient, currentUser }}
+     * />
+     * ```
+     */
+    contextData?: ContextData;
+}>;
+
+/**
+ * A collapsible group for sidebar navigation.
+ *
+ * @example
+ * ```tsx
+ * // Basic group
+ * <SidebarGroup title={labels.t("products")} icon={<Package />}>
+ *   <SidebarItem to="/products/all" />
+ *   <SidebarItem to="/products/categories" />
+ * </SidebarGroup>
+ *
+ * // Clickable group header
+ * <SidebarGroup title={labels.t("settings")} icon={<Settings />} to="/settings">
+ *   <SidebarItem to="/settings/profile" />
+ *   <SidebarItem to="/settings/security" />
+ * </SidebarGroup>
+ *
+ * // Nested groups
+ * <SidebarGroup title={labels.t("products")} icon={<Package />}>
+ *   <SidebarItem to="/products/all" />
+ *   <SidebarGroup title={labels.t("archives")} defaultOpen={false}>
+ *     <SidebarItem to="/products/archives/2024" />
+ *     <SidebarItem to="/products/archives/2023" />
+ *   </SidebarGroup>
+ * </SidebarGroup>
+ * ```
+ */
+export declare const SidebarGroup: (props: SidebarGroupProps) => JSX.Element;
+
+export declare type SidebarGroupProps = {
+    /**
+     * Group title (i18n supported).
+     */
+    title: LocalizedString;
+    /**
+     * Group icon.
+     */
+    icon?: ReactNode;
+    /**
+     * When specified, title becomes a clickable link.
+     */
+    to?: string;
+    /**
+     * Initial expanded state.
+     * @default true
+     */
+    defaultOpen?: boolean;
+    /**
+     * Child items (SidebarItem, SidebarGroup, etc.)
+     */
+    children: ReactNode;
+};
+
+/**
+ * A navigation item for the sidebar.
+ *
+ * Automatically resolves title and icon from the resource definition's meta
+ * corresponding to the URL specified in `to`.
+ *
+ * @example
+ * ```tsx
+ * // Auto-resolved from resource meta
+ * <SidebarItem to="/dashboard" />
+ *
+ * // Override title and icon
+ * <SidebarItem to="/" title="Home" icon={<Home />} />
+ *
+ * // Custom rendering
+ * <SidebarItem
+ *   to="/tasks"
+ *   render={({ title, icon, isActive }) => (
+ *     <>
+ *       {icon}
+ *       {title}
+ *       <Badge>5</Badge>
+ *     </>
+ *   )}
+ * />
+ *
+ * // External link
+ * <SidebarItem to="https://docs.example.com" external />
+ * ```
+ */
+export declare const SidebarItem: (props: SidebarItemProps) => JSX.Element;
+
+export declare type SidebarItemProps = {
+    /**
+     * Target URL (required).
+     * External URLs (http://...) are rendered as external links.
+     */
+    to: string;
+    /**
+     * Override title.
+     * When omitted, title is auto-resolved from resource meta.
+     */
+    title?: string;
+    /**
+     * Override icon.
+     * When omitted, icon is auto-resolved from resource meta.
+     */
+    icon?: ReactNode;
+    /**
+     * Opens as external link with `target="_blank"`.
+     * When true, adds an external link icon and opens in new tab.
+     */
+    external?: boolean;
+    /**
+     * How to match the current path for active state.
+     * - "exact": Only highlight when the path matches exactly.
+     * - "prefix": Highlight when the current path starts with `to` (with segment boundary check).
+     * @default "prefix"
+     */
+    activeMatch?: "exact" | "prefix";
+    /**
+     * Custom rendering function.
+     * When omitted, title/icon are auto-resolved from resource meta and default UI is rendered.
+     * When specified, receives title/icon/isActive in render function for full customization.
+     */
+    render?: (props: SidebarItemRenderProps) => ReactNode;
+};
+
+declare type SidebarItemRenderProps = {
+    /** Title auto-resolved from resource meta */
+    title: string;
+    /** Target URL */
+    url: string;
+    /** Icon auto-resolved from resource meta */
+    icon?: ReactNode;
+    /** Whether this item is currently active */
+    isActive: boolean;
+};
+
 export declare const SidebarLayout: (props: SidebarLayoutProps) => JSX.Element;
 
-declare type SidebarLayoutProps = {
+export declare type SidebarLayoutProps = {
+    /**
+     * Custom content renderer.
+     *
+     * @example
+     * ```tsx
+     * <SidebarLayout>
+     *   {({ Outlet }) => (
+     *     <>
+     *       <CustomHeader />
+     *       <Outlet />
+     *       <CustomFooter />
+     *     </>
+     *   )}
+     * </SidebarLayout>
+     * ```
+     */
     children?: (props: {
         Outlet: () => React.ReactNode;
     }) => React.ReactNode;
+    /**
+     * Custom sidebar content.
+     *
+     * @default DefaultSidebar
+     * @example
+     * ```tsx
+     * <SidebarLayout sidebar={<MyCustomSidebar />} />
+     * ```
+     */
     sidebar?: React.ReactNode;
 };
 
+/**
+ * A visual divider for sidebar navigation.
+ *
+ * @example
+ * ```tsx
+ * <DefaultSidebar>
+ *   <SidebarItem to="/dashboard" />
+ *   <SidebarSeparator />
+ *   <SidebarItem to="/settings" />
+ * </DefaultSidebar>
+ * ```
+ */
+export declare const SidebarSeparator: () => JSX.Element;
+
 declare type Theme = "dark" | "light" | "system";
 
 declare type ThemeProviderState = {
@@ -910,6 +1300,34 @@ declare type ThemeProviderState = {
     setTheme: (theme: Theme) => void;
 };
 
+/**
+ * Type-safe path builder interface.
+ *
+ * @typeParam TRoutes - Mapping of route paths to their parameter types
+ */
+declare type TypedPaths<TRoutes extends Record<string, Record<string, string>>> = {
+    /**
+     * Build a URL path with type-checked parameters.
+     *
+     * @param path - Route path template (can include ?query suffix)
+     * @param params - Path parameters (required if route has dynamic segments)
+     * @returns Resolved URL path string
+     *
+     * @example
+     * ```ts
+     * // Static route
+     * paths.for("/dashboard"); // → "/dashboard"
+     *
+     * // Dynamic route
+     * paths.for("/orders/:id", { id: "123" }); // → "/orders/123"
+     *
+     * // With query string
+     * paths.for("/items/:id?tab=details", { id: "456" }); // → "/items/456?tab=details"
+     * ```
+     */
+    for<T extends (keyof TRoutes & string) | `${keyof TRoutes & string}?${string}`>(path: T, ...params: ExtractBasePath<T> extends keyof TRoutes ? IsEmptyObject<TRoutes[ExtractBasePath<T>]> extends true ? [] : [TRoutes[ExtractBasePath<T>]] : never): string;
+};
+
 /**
  * Hook to access the full AppShell context (both config and data).
  * For better performance, prefer useAppShellConfig() or useAppShellData()
@@ -1025,6 +1443,15 @@ export { useLocation }
 
 export { useNavigate }
 
+/**
+ * Find page meta (title, icon) for a given URL path.
+ * Searches through modules and their resources recursively.
+ *
+ * @param path - URL path to find meta for (e.g., "/products/all")
+ * @returns PageMeta if found, null for external links or not found
+ */
+export declare const usePageMeta: (path: string) => PageMeta | null;
+
 export { useParams }
 
 export { useRouteError }
@@ -1035,4 +1462,72 @@ export declare const useTheme: () => ThemeProviderState;
 
 export declare const useToast: () => typeof toast;
 
+/**
+ * Conditionally render children based on guard evaluation.
+ *
+ * Guards are evaluated in order. If any guard returns `hidden()`,
+ * the fallback is rendered instead of children. Supports async guards.
+ *
+ * Note: Unlike route guards, `redirectTo()` is not supported in WithGuard.
+ * Use `hidden()` with a fallback that handles navigation if needed.
+ *
+ * @example
+ * ```tsx
+ * // Simple role-based guard
+ * const isAdmin = ({ context }) =>
+ *   context.currentUser.role === "admin" ? pass() : hidden();
+ *
+ * <WithGuard guards={[isAdmin]}>
+ *   <AdminPanel />
+ * </WithGuard>
+ *
+ * // With fallback
+ * <WithGuard guards={[isAdmin]} fallback={<UpgradePrompt />}>
+ *   <AdminPanel />
+ * </WithGuard>
+ *
+ * // Parameterized guard (curried)
+ * const isOwner = (resourceId: string) => ({ context }) =>
+ *   resourceId === context.currentUser.id ? pass() : hidden();
+ *
+ * const { id } = useParams();
+ * <WithGuard guards={[isOwner(id)]}>
+ *   <EditButton />
+ * </WithGuard>
+ *
+ * // In sidebar
+ * <DefaultSidebar>
+ *   <SidebarItem to="/dashboard" />
+ *   <WithGuard guards={[isAdmin]}>
+ *     <SidebarItem to="/admin" />
+ *   </WithGuard>
+ * </DefaultSidebar>
+ * ```
+ */
+export declare const WithGuard: (props: WithGuardProps) => JSX.Element;
+
+export declare type WithGuardProps = {
+    /**
+     * Guards to evaluate. All guards must pass for children to render.
+     * Uses the same Guard type as route guards for full reusability.
+     */
+    guards: Guard[];
+    /**
+     * Content to render when all guards pass.
+     */
+    children: ReactNode;
+    /**
+     * Content to render when any guard returns hidden.
+     * @default null (renders nothing)
+     */
+    fallback?: ReactNode;
+    /**
+     * Content to render while guards are being evaluated (for async guards).
+     * @default null (renders nothing)
+     */
+    loading?: ReactNode;
+};
+
+declare function withPages(pages: PageEntry[]): FC<AppShellProps>;
+
 export { }