@tailor-platform/app-shell 0.22.0 → 0.24.0

package/dist/index.d.ts

@@ -14,42 +14,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 +48,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 +100,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.
@@ -258,6 +282,21 @@ export declare const badgeVariants: (props?: ({
  */
 declare type BadgeVariantType = "default" | "success" | "warning" | "error" | "neutral" | "outline-success" | "outline-warning" | "outline-error" | "outline-info" | "outline-neutral";
 
+/**
+ * Supported column count options
+ */
+declare type ColumnCount = 1 | 2 | 3;
+
+/**
+ * Props for individual Layout.Column component
+ */
+declare interface ColumnProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Child content */
+    children?: ReactNode;
+}
+
 /**
  * Column layout options for the card
  */
@@ -282,7 +321,6 @@ declare type CommonModuleProps = {
 declare type CommonPageResource = {
     path: string;
     type: "component";
-    component: () => ReactNode;
     meta: {
         title: LocalizedString;
         icon?: ReactNode;
@@ -302,11 +340,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
  */
@@ -391,7 +447,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.
@@ -439,18 +512,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.
@@ -639,6 +709,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;
 } & {
@@ -658,6 +778,57 @@ declare type LabelDefinition<Def extends Record<string, LabelValue>> = {
  */
 declare type LabelValue = string | ((props: any) => string);
 
+/**
+ * Layout - Responsive column layout component
+ *
+ * Automatically handles responsive behavior for 1, 2, or 3 column layouts.
+ * Uses flexbox with viewport breakpoints for simple, CSS-only responsive behavior.
+ *
+ * @example
+ * ```tsx
+ * // Basic layout
+ * <Layout columns={2}>
+ *   <Layout.Column>Main content</Layout.Column>
+ *   <Layout.Column>Side panel</Layout.Column>
+ * </Layout>
+ *
+ * // With header and actions
+ * <Layout columns={2} title="Page Title" actions={[<Button key="save">Save</Button>]}>
+ *   <Layout.Column>...</Layout.Column>
+ *   <Layout.Column>...</Layout.Column>
+ * </Layout>
+ * ```
+ */
+export declare function Layout({ columns, className, gap, title, actions, children, }: LayoutProps): JSX.Element;
+
+export declare namespace Layout {
+    var Column: React_2.ForwardRefExoticComponent<ColumnProps & React_2.RefAttributes<HTMLDivElement>>;
+}
+
+/**
+ * Props for the Layout component
+ */
+export declare interface LayoutProps {
+    /**
+     * Number of columns (1, 2, or 3).
+     *
+     * **Required.** Must match the exact number of `Layout.Column` children.
+     * The component will throw an error in development if there's a mismatch.
+     */
+    columns: ColumnCount;
+    /** Additional CSS classes */
+    className?: string;
+    /** Gap between columns (default: 4 = 16px) */
+    gap?: number;
+    /** Header title - displayed at the top of the layout */
+    title?: string;
+    /** Header actions - array of action components (e.g., buttons) displayed on the right side of the header.
+     * Layout and spacing are handled automatically. */
+    actions?: ReactNode[];
+    /** Child elements - must be exactly `columns` number of Layout.Column components */
+    children: ReactNode;
+}
+
 export { Link }
 
 declare type LoaderHandler = (args: LoaderFunctionArgs) => Promise<unknown> | unknown;
@@ -669,18 +840,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.
@@ -689,30 +876,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.
@@ -721,9 +899,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;
 };
 
@@ -772,7 +951,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;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "type": "module",
   "exports": {
     "./styles": "./dist/app-shell.css",
@@ -18,7 +18,6 @@
     "react-dom": ">= 19"
   },
   "dependencies": {
-    "@badgateway/oauth2-client": "^3.3.0",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",
@@ -26,7 +25,6 @@
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-navigation-menu": "^1.2.14",
     "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-select": "^2.1.6",
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tooltip": "^1.2.8",
@@ -40,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",
@@ -61,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",