@tailor-platform/app-shell 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { LoaderFunctionArgs } from 'react-router';
 import { Params } from 'react-router';
 import * as React_2 from 'react';
 import { ReactNode } from 'react';
+import { toast } from 'sonner';
 import { useLocation } from 'react-router';
 import { useNavigate } from 'react-router';
 import { useParams } from 'react-router';
@@ -14,42 +15,26 @@ import { useRouteError } from 'react-router';
 import { useSearchParams } from 'react-router';
 import { VariantProps } from 'class-variance-authority';
 
-/**
- * Context provided to access control functions
- */
-declare type AccessContext = {
-    params: Params;
-    searchParams: URLSearchParams;
-    signal: AbortSignal;
-};
-
-declare type AccessControl = (context: AccessContext) => Promise<AccessResult> | AccessResult;
+export declare const AppShell: (props: AppShellProps) => JSX.Element | null;
 
 /**
- * Result of access control evaluation
+ * Context for static configuration (title, icon, configurations).
+ * Changes to this context will cause RouterContainer to re-render.
  */
-declare type AccessResult = 
-/**
-* Resource is visible and accessible
-*/
-    {
-    state: "visible";
-}
-/**
-* Resource is hidden and not accessible
-*/
-| {
-    state: "hidden";
-};
-
-export declare const AppShell: (props: AppShellProps) => JSX.Element | null;
-
-declare type AppShellContextType = {
+declare type AppShellConfigContextType = {
     title?: string;
     icon?: ReactNode;
     configurations: RootConfiguration;
 };
 
+/**
+ * Context for dynamic data (contextData).
+ * Changes to this context will NOT cause RouterContainer to re-render.
+ */
+declare type AppShellDataContextType = {
+    contextData: ContextData;
+};
+
 export declare type AppShellProps = React.PropsWithChildren<{
     /**
      * App shell title
@@ -64,19 +49,15 @@ export declare type AppShellProps = React.PropsWithChildren<{
      */
     basePath?: string;
     /**
-     * A component to be rendered at the root level of AppShell,
-     * or a redirect configuration
+     * A component to be rendered at the root level of AppShell.
+     * Use guards with redirectTo() for redirects.
      *
      * @example
      * ```tsx
-     * // Render a component
      * rootComponent: () => <DashboardHome />
-     *
-     * // Redirect to a resource
-     * rootComponent: redirectToResource("dashboard/overview")
      * ```
      */
-    rootComponent?: (() => React.ReactNode) | RedirectConfig;
+    rootComponent?: () => React.ReactNode;
     /**
      * Navigation configuration
      */
@@ -120,8 +101,52 @@ export declare type AppShellProps = React.PropsWithChildren<{
      * ```
      */
     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;
 }>;
 
+/**
+ * Empty interface for module augmentation.
+ * Users can extend this to define their own context data type.
+ *
+ * @example
+ * ```typescript
+ * declare module "@tailor-platform/app-shell" {
+ *   interface AppShellRegister {
+ *     contextData: {
+ *       apiClient: ApiClient;
+ *       currentUser: User;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare interface AppShellRegister {
+}
+
 declare type AuthContextType = {
     /**
      * Current authentication state.
@@ -297,7 +322,6 @@ declare type CommonModuleProps = {
 declare type CommonPageResource = {
     path: string;
     type: "component";
-    component: () => ReactNode;
     meta: {
         title: LocalizedString;
         icon?: ReactNode;
@@ -317,11 +341,29 @@ declare type CommonProps = {
      */
     meta?: ResourceMetaProps;
     /**
-     * Access guard to control visibility and access of this module and its resources.
+     * Guards to control access to this module/resource.
+     * Guards are executed in order. If any guard returns non-pass result,
+     * access is denied.
+     *
+     * @example
+     * ```tsx
+     * guards: [
+     *   ({ context }) => context.currentUser ? pass() : redirectTo("/login"),
+     *   ({ context }) => context.currentUser.role === "admin" ? pass() : hidden(),
+     * ]
+     * ```
      */
-    accessControl?: AccessControl;
+    guards?: Guard[];
 };
 
+/**
+ * Context data type inferred from AppShellRegister.
+ * Falls back to Record<string, unknown> if not augmented.
+ */
+export declare type ContextData = AppShellRegister extends {
+    contextData: infer T;
+} ? T : Record<string, unknown>;
+
 /**
  * Date format options
  */
@@ -406,7 +448,24 @@ export declare const defineI18nLabels: <const L extends Exclude<string, "en">, c
      * }
      * ```
      */
-    useT: () => <K extends keyof Def & string>(key: K, ...args: Def[K] extends (props: infer P) => string ? [props: P] : []) => string;
+    useT: () => (<K extends keyof Def & string>(key: K, ...args: Def[K] extends (props: infer P) => string ? [props: P] : []) => string) & {
+        /**
+         * Resolve a label with a dynamic key.
+         * This is useful when the key is constructed at runtime.
+         *
+         * @param key - The dynamic key to resolve
+         * @param fallback - The fallback value if the key is not found
+         * @returns The resolved label or the fallback value
+         *
+         * @example
+         * ```tsx
+         * const employeeType = "STAFF";
+         * t.dynamic(`employees.${employeeType}`, "Unknown");  // "Staff"
+         * t.dynamic("unknown.key", "Default");                // "Default"
+         * ```
+         */
+        dynamic: (key: string, fallback: string) => string;
+    };
     /**
      * A function to get the translater for a specific label key.
      * This is expected to be used in `meta.title` in module/resource definitions.
@@ -454,18 +513,15 @@ export declare function defineModule(props: DefineModuleProps): Module;
 
 declare type DefineModuleProps = CommonProps & CommonModuleProps & {
     /**
-     * React component to render or redirect configuration
+     * React component to render.
+     * If not provided, the module will redirect to the first resource.
      *
      * @example
      * ```tsx
-     * // Render a component
      * component: (props) => <div>{props.title}</div>
-     *
-     * // Redirect to a resource
-     * component: redirectToResource("dashboard/overview")
      * ```
      */
-    component: ((props: ResourceComponentProps) => ReactNode) | RedirectConfig;
+    component?: (props: ResourceComponentProps) => ReactNode;
     /**
      * Error boundary component for this module and its child resources.
      * When an error occurs in this module or its resources, this component will render.
@@ -654,6 +710,56 @@ declare interface FieldMeta {
  */
 declare type FieldType = "text" | "badge" | "money" | "date" | "link" | "address" | "reference";
 
+/**
+ * Guard function type.
+ * Guards are executed in order and stop on the first non-pass result.
+ */
+export declare type Guard = (ctx: GuardContext) => Promise<GuardResult> | GuardResult;
+
+/**
+ * Context provided to guard functions
+ */
+export declare type GuardContext = {
+    params: Params;
+    searchParams: URLSearchParams;
+    signal: AbortSignal;
+    context: ContextData;
+};
+
+/**
+ * Result of guard evaluation.
+ * Guards can only return one of these constrained result types.
+ */
+export declare type GuardResult = 
+/** Allow access and render the component */
+    {
+    type: "pass";
+}
+/** Deny access and show 404 */
+| {
+    type: "hidden";
+}
+/** Redirect to another path */
+| {
+    type: "redirect";
+    to: string;
+};
+
+/**
+ * Deny access and show 404 Not Found.
+ *
+ * @example
+ * ```tsx
+ * const adminOnly: Guard = ({ context }) => {
+ *   if (context.currentUser.role !== "admin") {
+ *     return hidden();
+ *   }
+ *   return pass();
+ * };
+ * ```
+ */
+export declare const hidden: () => GuardResult;
+
 export declare type I18nLabels<Def extends Record<string, LabelValue> = Record<string, LabelValue>, L extends string = never> = {
     en: Def;
 } & {
@@ -735,18 +841,34 @@ declare type LocalizedString = string | ((locale: string) => string);
  */
 declare type Module = Omit<CommonPageResource, "meta"> & {
     _type: "module";
+    component?: () => ReactNode;
     meta: CommonPageResource["meta"] & {
         icon?: ReactNode;
         menuItemClickable: boolean;
     };
     resources: Array<Resource>;
     errorBoundary: ErrorBoundaryComponent;
-    accessControl?: AccessControl;
+    guards?: Guard[];
     loader?: LoaderHandler;
 };
 
 declare type Modules = Array<Module>;
 
+/**
+ * Allow access to the route. Continue to next guard or render component.
+ *
+ * @example
+ * ```tsx
+ * const myGuard: Guard = ({ context }) => {
+ *   if (context.currentUser) {
+ *     return pass();
+ *   }
+ *   return hidden();
+ * };
+ * ```
+ */
+export declare const pass: () => GuardResult;
+
 declare type ReactResourceProps = {
     /**
      * React component to render.
@@ -755,30 +877,21 @@ declare type ReactResourceProps = {
 };
 
 /**
- * Redirect configuration for module or root component
- */
-declare type RedirectConfig = {
-    /**
-     * Path to redirect to (under /resources/)
-     */
-    redirectTo: string;
-};
-
-/**
- * Helper function to define a redirect to a resource path
+ * Redirect to another path.
  *
- * @param path - Path under `/resources/` (e.g., "dashboard/overview")
+ * @param to - Path to redirect to
  *
  * @example
  * ```tsx
- * defineModule({
- *   path: "dashboard",
- *   component: redirectToResource("dashboard/overview"),
- *   resources: [overviewResource],
- * });
+ * const requireAuth: Guard = ({ context }) => {
+ *   if (!context.currentUser) {
+ *     return redirectTo("/login");
+ *   }
+ *   return pass();
+ * };
  * ```
  */
-export declare function redirectToResource(path: string): RedirectConfig;
+export declare const redirectTo: (to: string) => GuardResult;
 
 /**
  * A resource that can be included in the sub-content in the root resource.
@@ -787,9 +900,10 @@ export declare function redirectToResource(path: string): RedirectConfig;
  */
 declare type Resource = CommonPageResource & {
     _type: "resource";
+    component: () => ReactNode;
     subResources?: Array<Resource>;
     errorBoundary: ErrorBoundaryComponent;
-    accessControl?: AccessControl;
+    guards?: Guard[];
     loader?: LoaderHandler;
 };
 
@@ -838,7 +952,29 @@ declare type ThemeProviderState = {
     setTheme: (theme: Theme) => void;
 };
 
-export declare const useAppShell: () => AppShellContextType;
+/**
+ * Hook to access the full AppShell context (both config and data).
+ * For better performance, prefer useAppShellConfig() or useAppShellData()
+ * depending on what you need, as this hook subscribes to both contexts.
+ */
+export declare const useAppShell: () => {
+    contextData: ContextData;
+    title?: string;
+    icon?: ReactNode;
+    configurations: RootConfiguration;
+};
+
+/**
+ * Hook to access only the static configuration.
+ * Use this in components that don't need contextData to avoid unnecessary re-renders.
+ */
+export declare const useAppShellConfig: () => AppShellConfigContextType;
+
+/**
+ * Hook to access only the dynamic contextData.
+ * Use this in components that need contextData.
+ */
+export declare const useAppShellData: () => AppShellDataContextType;
 
 export declare const useAuth: () => AuthContextType;
 
@@ -864,4 +1000,6 @@ export { useSearchParams }
 
 export declare const useTheme: () => ThemeProviderState;
 
+export declare const useToast: () => typeof toast;
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     "./styles": "./dist/app-shell.css",
@@ -38,8 +38,8 @@
     "lucide-react": "^0.562.0",
     "next-themes": "^0.4.6",
     "oauth4webapi": "^3.8.3",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "react-hook-form": "^7.54.2",
     "react-router": "^7.4.0",
     "sonner": "^2.0.7",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.2",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/node": "^22",
     "@types/react": "^19",
@@ -59,7 +59,7 @@
     "tailwindcss": "^4.1.3",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5",
-    "vite": "^7.3.0",
+    "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.0",
     "vite-plugin-externalize-deps": "^0.10.0",
     "vite-tsconfig-paths": "^6.0.4",