@tailor-platform/app-shell 0.28.0 → 0.29.0

package/dist/app-shell.d.ts

@@ -14,6 +14,62 @@ import { useRouteError } from 'react-router';
 import { useSearchParams } from 'react-router';
 import { VariantProps } from 'class-variance-authority';
 
+/**
+ * A single action row in the ActionPanel (icon + label, triggered by onClick).
+ * For navigation, call useNavigate() inside onClick (e.g. navigate("/path")).
+ */
+declare interface ActionItem {
+    /** Unique key for React */
+    key: string;
+    /** Visible label */
+    label: string;
+    /** Icon: any component or SVG; rendered in a fixed-size slot (e.g. 16px) */
+    icon: ReactNode;
+    /** Called when the row is clicked. For navigation, use useNavigate() inside the callback. */
+    onClick?: () => void | Promise<void>;
+    /** Optional; disable the row */
+    disabled?: boolean;
+    /** When true, show loading indicator in the row and make it non-interactive */
+    loading?: boolean;
+}
+
+/**
+ * ActionPanel — Card with title and list of actions (icon + label).
+ *
+ * Each row has an icon and label and is triggered by onClick. For navigation, use
+ * useNavigate() inside the callback (e.g. onClick: () => navigate("/path")).
+ * Use `astw:w-full` so the panel fills the width of its parent container.
+ *
+ * When an action has `loading: true`, the row shows a spinner in the icon slot and is
+ * non-interactive (useful for backend-driven actions: parent sets loading from mutation/request state).
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate();
+ * <ActionPanel
+ *   title="Actions"
+ *   actions={[
+ *     { key: "1", label: "Create invoice", icon: <ReceiptIcon />, onClick: () => openModal() },
+ *     { key: "2", label: "View docs", icon: <DocIcon />, onClick: () => navigate("/docs") },
+ *     { key: "3", label: "Saving…", icon: <SaveIcon />, onClick: () => {}, loading: true },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function ActionPanel({ title, actions, className }: ActionPanelProps): JSX.Element;
+
+/**
+ * Props for the ActionPanel component.
+ */
+export declare interface ActionPanelProps {
+    /** Card title */
+    title: string;
+    /** List of actions to render */
+    actions: ActionItem[];
+    /** Additional CSS classes for the card container */
+    className?: string;
+}
+
 export declare const AppShell: {
     (props: AppShellProps): JSX.Element | null;
     /* Excluded from this release type: WithPages */
@@ -237,6 +293,11 @@ export declare const badgeVariants: (props?: ({
  */
 declare type BadgeVariantType = "default" | "success" | "warning" | "error" | "neutral" | "outline-success" | "outline-warning" | "outline-error" | "outline-info" | "outline-neutral";
 
+/**
+ * Supported area values for Layout.Column
+ */
+declare type ColumnArea = "left" | "main" | "right";
+
 /**
  * Supported column count options
  */
@@ -248,6 +309,14 @@ declare type ColumnCount = 1 | 2 | 3;
 declare interface ColumnProps {
     /** Additional CSS classes */
     className?: string;
+    /**
+     * Column area role. When specified on all columns, determines width template
+     * based on role rather than position.
+     * - "left": fixed 320px
+     * - "main": flex-1
+     * - "right": fixed 280px
+     */
+    area?: ColumnArea;
     /** Child content */
     children?: ReactNode;
 }
@@ -522,31 +591,43 @@ export declare const defineI18nLabels: <const L extends Exclude<string, "en">, c
 };
 
 /**
- * Define a root-level resource that renders a React component.
+ * Define a module that appears as a top-level item in the sidebar navigation.
+ *
+ * A module can be configured in several ways:
+ * - **With component**: renders the component at the module path.
+ * - **Without component, with resources**: child resources are accessible, but
+ *   navigating to the module path itself returns a 404.
+ * - **With guards only**: useful for redirect-only paths (e.g. legacy URL migration).
+ *   The guard loader runs and can redirect; if all guards pass, the path returns 404.
+ * - **Path only (no component, no resources, no guards)**: the module path falls
+ *   through to the catch-all 404 route.
  *
  * @example
  * ```
- * // Define a minimal resource
- * defineReactResource({
- *   path: "custom-page",
- *   component: () => {
- *     return (
- *       <div>
- *         <p>This is a custom page.</p>
- *       </div>
- *     );
- *   },
+ * defineModule({
+ *   path: "dashboard",
+ *   component: (props) => <div>{props.title}</div>,
+ *   resources: [defineResource({ ... })],
  * });
  * ```
  */
 export declare function defineModule(props: DefineModuleProps): Module;
 
-declare type DefineModuleProps = CommonProps & CommonModuleProps & {
+declare type DefineModuleProps = CommonProps & CommonModuleProps & ErrorBoundaryProps & {
     /**
      * React component to render.
      *
-     * If not provided, a guard with `redirectTo()` must be used to redirect
-     * users to the appropriate resource.
+     * If not provided and no guards are given, the module path will return a 404
+     * response while child resources remain accessible.
+     *
+     * If `resources` is non-empty and guards are provided, guards take precedence
+     * over the default 404: for example, `redirectTo()` will redirect instead of
+     * returning 404. If all guards return `pass()`, the module path still returns
+     * a 404 since there is no component to render.
+     *
+     * Guard-only modules (no component, no resources) are also supported — for
+     * example, to maintain legacy URL paths that redirect elsewhere. In this case,
+     * at least one guard must be provided.
      *
      * @example
      * ```tsx
@@ -554,22 +635,23 @@ declare type DefineModuleProps = CommonProps & CommonModuleProps & {
      * ```
      */
     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.
-     * Use the `useRouteError` hook to access error details within the component.
-     */
-    errorBoundary?: ErrorBoundaryComponent;
 };
 
 /**
  * Define a resource that renders a React component.
  *
+ * A resource can be configured in several ways:
+ * - **With component**: renders the component at the resource path.
+ * - **Without component, with subResources**: sub-resources are accessible,
+ *   but navigating to the resource path itself returns a 404.
+ * - **With guards only**: useful for redirect-only paths.
+ *   The guard loader runs and can redirect; if all guards pass, the path returns 404.
+ *
  * This resource can be used as a sub-resource of a module or as a root-level resource.
  *
  * @example
  * ```
- * // Define a minimal resource
+ * // Resource with component and sub-resources
  * defineResource({
  *   path: "custom-page",
  *   component: () => {
@@ -592,23 +674,39 @@ declare type DefineModuleProps = CommonProps & CommonModuleProps & {
  *     }),
  *   ]
  * });
+ *
+ * // Resource without component (sub-resources only, path returns 404)
+ * defineResource({
+ *   path: "namespace",
+ *   subResources: [
+ *     defineResource({
+ *       path: "page-a",
+ *       component: () => <div>Page A</div>,
+ *     }),
+ *   ]
+ * });
  * ```
  *
  */
 export declare function defineResource(props: DefineResourceProps): Resource;
 
-declare type DefineResourceProps = CommonProps & ReactResourceProps & {
+declare type DefineResourceProps = CommonProps & ErrorBoundaryProps & {
     /**
-     * Sub-resources of the resource.
+     * React component to render.
+     *
+     * If not provided and no guards are given, the resource path will return a 404
+     * response while sub-resources remain accessible.
+     *
+     * If `subResources` is non-empty and guards are provided, guards take precedence
+     * over the default 404: for example, `redirectTo()` will redirect instead of
+     * returning 404. If all guards return `pass()`, the resource path still returns
+     * a 404 since there is no component to render.
      */
-    subResources?: Array<Resource>;
+    component?: (props: ResourceComponentProps) => ReactNode;
     /**
-     * Error boundary component for this resource and its sub-resources.
-     * When an error occurs in this resource, this component will render.
-     * Overrides module-level or global error boundaries.
-     * Use the `useRouteError` hook to access error details within the component.
+     * Sub-resources of the resource.
      */
-    errorBoundary?: ErrorBoundaryComponent;
+    subResources?: Array<Resource>;
 };
 
 /**
@@ -698,6 +796,16 @@ export declare interface EnhancedAuthClient extends AuthClient {
  */
 export declare type ErrorBoundaryComponent = ReactNode;
 
+declare type ErrorBoundaryProps = {
+    /**
+     * Error boundary component for this module/resource and its children.
+     * When an error occurs, this component will render.
+     * Overrides any parent-level (module or global) error boundary.
+     * Use the `useRouteError` hook to access error details within the component.
+     */
+    errorBoundary?: ErrorBoundaryComponent;
+};
+
 /**
  * Type-safe path builder for file-based routing.
  *
@@ -818,6 +926,51 @@ export declare type GuardResult =
     to: string;
 };
 
+/**
+ * Layout.Header — Page-level header with title, actions, and an optional
+ * full-width slot.
+ *
+ * Place this as a direct child of `<Layout>`, above any `<Layout.Column>`
+ * children. The header spans the full width of the grid via `col-span-full`,
+ * regardless of column count.
+ *
+ * If multiple `Layout.Header` children are provided to `<Layout>`, only the
+ * first one is rendered.
+ *
+ * - **title** — Rendered as an `<h1>` on the left side.
+ * - **actions** — Rendered on the right side (e.g. save / cancel buttons).
+ * - **children** — Rendered full-width below the title/actions row.
+ *   Useful for tabs, breadcrumbs, or other secondary navigation.
+ *
+ * ### Data attributes
+ *
+ * The rendered `<header>` has `data-layout-header`, which `<Layout>` uses
+ * internally to apply `col-span-full`.
+ *
+ * @example
+ * ```tsx
+ * <Layout>
+ *   <Layout.Header
+ *     title="Purchase Orders"
+ *     actions={[<Button key="create">Create</Button>]}
+ *   >
+ *     <Tabs value={tab} onValueChange={setTab}>
+ *       <TabsList>
+ *         <TabsTrigger value="all">All</TabsTrigger>
+ *         <TabsTrigger value="open">Open</TabsTrigger>
+ *       </TabsList>
+ *     </Tabs>
+ *   </Layout.Header>
+ *   <Layout.Column>…</Layout.Column>
+ * </Layout>
+ * ```
+ */
+declare function Header({ title, actions, children }: LayoutHeaderProps): JSX.Element;
+
+declare namespace Header {
+    var displayName: string;
+}
+
 /**
  * Deny access and show 404 Not Found.
  *
@@ -858,23 +1011,41 @@ declare type LabelDefinition<Def extends Record<string, LabelValue>> = {
 declare type LabelValue = string | ((props: any) => string);
 
 /**
- * Layout - Responsive column layout component
+ * Layout – Responsive grid layout component
+ *
+ * Uses CSS Grid for responsive column layouts. On mobile, all columns
+ * stack vertically (`grid-cols-1`). At `lg` (2-column) or `xl` (3+ column)
+ * breakpoints, columns display side by side with widths determined by
+ * position or the `area` prop on each `Layout.Column`.
+ *
+ * ### Child filtering
  *
- * Automatically handles responsive behavior for 1, 2, or 3 column layouts.
- * Uses flexbox with viewport breakpoints for simple, CSS-only responsive behavior.
+ * Only `Layout.Header` and `Layout.Column` are recognized as children;
+ * any other elements are silently ignored and will not be rendered.
+ * If multiple `Layout.Header` children are provided, only the first one
+ * is rendered.
+ *
+ * ### Grid template
+ *
+ * Column widths are controlled via a `--layout-cols` CSS custom property
+ * set on the root `<div>`, consumed by `grid-cols-[var(--layout-cols)]`.
+ * The value is computed from position (see `Layout.Column`) or `area` props.
+ * For a single column, no custom property is set and the grid remains
+ * `grid-cols-1`.
  *
  * @example
  * ```tsx
- * // Basic layout
- * <Layout columns={2}>
+ * // With Layout.Header
+ * <Layout>
+ *   <Layout.Header title="Page Title" actions={[<Button key="save">Save</Button>]} />
  *   <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>
+ * // With area prop
+ * <Layout>
+ *   <Layout.Column area="left">Sidebar</Layout.Column>
+ *   <Layout.Column area="main">Content</Layout.Column>
  * </Layout>
  * ```
  */
@@ -882,6 +1053,19 @@ export declare function Layout({ columns, className, gap, title, actions, childr
 
 export declare namespace Layout {
     var Column: React_2.ForwardRefExoticComponent<ColumnProps & React_2.RefAttributes<HTMLDivElement>>;
+    var Header: Header;
+}
+
+/**
+ * Props for Layout.Header component
+ */
+declare interface LayoutHeaderProps {
+    /** Page title (left side) */
+    title?: string;
+    /** Action buttons or nodes (right side) */
+    actions?: ReactNode[];
+    /** Renders full-width below the title/actions row (e.g. tabs) */
+    children?: ReactNode;
 }
 
 /**
@@ -891,20 +1075,30 @@ 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.
+     * @deprecated Auto-detected from Layout.Column children count when omitted.
      */
-    columns: ColumnCount;
+    columns?: ColumnCount;
     /** Additional CSS classes */
     className?: string;
-    /** Gap between columns (default: 4 = 16px) */
+    /**
+     * Gap between columns (default: 4 = 16px)
+     *
+     * @deprecated Remove the `gap` prop and use `className` with the `astw:` prefix
+     * (e.g. `className="astw:gap-6"`) to override the default gap.
+     */
     gap?: number;
-    /** Header title - displayed at the top of the layout */
+    /** Header title - displayed at the top of the layout
+     *
+     * @deprecated Use `<Layout.Header title="...">` instead.
+     */
     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. */
+    /** Header actions displayed on the right side of the header.
+     * Layout and spacing are handled automatically.
+     *
+     * @deprecated Use `<Layout.Header actions={...}>` instead.
+     */
     actions?: ReactNode[];
-    /** Child elements - must be exactly `columns` number of Layout.Column components */
+    /** Child elements - Layout.Header and/or Layout.Column components */
     children: ReactNode;
 }
 
@@ -976,13 +1170,6 @@ export declare type PageMeta = {
  */
 export declare const pass: () => GuardResult;
 
-declare type ReactResourceProps = {
-    /**
-     * React component to render.
-     */
-    component: (props: ResourceComponentProps) => ReactNode;
-};
-
 /**
  * Redirect to another path.
  *
@@ -1007,7 +1194,7 @@ export declare const redirectTo: (to: string) => GuardResult;
  */
 declare type Resource = CommonPageResource & {
     _type: "resource";
-    component: () => ReactNode;
+    component?: () => ReactNode;
     subResources?: Array<Resource>;
     errorBoundary: ErrorBoundaryComponent;
     guards?: Guard[];