@tailor-platform/app-shell 1.15.0 → 1.16.0

package/skills/app-shell-patterns/references/api/define-module.md

@@ -0,0 +1,247 @@
+---
+title: defineModule
+description: Define a top-level module that appears in the main navigation
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/define-module.docs.outline.md — do not edit by hand. -->
+
+# defineModule
+
+Creates a top-level module that appears in the main navigation. Modules can contain resources and optionally have their own landing page component.
+
+## Signature
+
+```typescript
+function defineModule(props: DefineModuleProps): Module;
+```
+
+## Parameters
+
+### `path`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** URL path segment for the module
+
+```typescript
+defineModule({
+  path: "products", // URL: /products
+});
+```
+
+### `component`
+
+- **Type:** `(props: ResourceComponentProps) => React.ReactNode`
+- **Required:** No
+- **Description:** Landing page component for the module. If omitted, the module redirects to its first resource, and its breadcrumb segment is rendered as plain text (not a link).
+
+**ResourceComponentProps:**
+
+```typescript
+{
+  title: string;          // Resolved title
+  icon?: React.ReactNode; // Module icon
+  resources?: Resource[]; // Child resources
+}
+```
+
+### `resources`
+
+- **Type:** `Resource[]`
+- **Required:** Yes
+- **Description:** Array of resources within this module. Define using `defineResource()`.
+
+### `meta`
+
+- **Type:** `object`
+- **Required:** No
+- **Description:** Metadata configuration for the module
+
+**meta.title**
+
+- **Type:** `string | LocalizedString`
+- **Default:** Capitalized `path`
+- **Description:** Display title in navigation and breadcrumbs
+
+**meta.icon**
+
+- **Type:** `React.ReactNode`
+- **Description:** Icon displayed in sidebar navigation
+
+**meta.breadcrumbTitle**
+
+- **Type:** `string | ((segment: string) => string)`
+- **Description:** Custom breadcrumb segment title override
+
+### `guards`
+
+- **Type:** `Guard[]`
+- **Required:** No
+- **Description:** Access control guards executed in order. If any guard returns non-pass, access is denied.
+
+See [Guards Overview](./guards/overview.md) for details.
+
+### `errorBoundary`
+
+- **Type:** `React.ReactNode`
+- **Required:** No
+- **Description:** Error boundary component for this module and its child resources. Use `useRouteError` hook to access error details.
+
+## Return Type
+
+```typescript
+Module;
+```
+
+A module object that can be passed to the `modules` prop of `AppShell`.
+
+## Examples
+
+### Basic Module
+
+```typescript
+import { defineModule } from "@tailor-platform/app-shell";
+
+const dashboardModule = defineModule({
+  path: "dashboard",
+  component: () => <h1>Dashboard</h1>,
+  resources: [],
+});
+```
+
+### Module with Icon and Title
+
+```typescript
+import { Home } from "lucide-react";
+
+const dashboardModule = defineModule({
+  path: "dashboard",
+  meta: {
+    title: "Dashboard",
+    icon: <Home />,
+  },
+  component: DashboardPage,
+  resources: [],
+});
+```
+
+### Module with Resources
+
+```typescript
+const productsModule = defineModule({
+  path: "products",
+  component: ProductsListPage,
+  resources: [
+    defineResource({
+      path: ":id",
+      component: ProductDetailPage,
+    }),
+    defineResource({
+      path: "categories",
+      component: CategoriesPage,
+    }),
+  ],
+});
+```
+
+### Module without Component (Auto-redirect)
+
+```typescript
+const dashboardModule = defineModule({
+  path: "dashboard",
+  // No component - automatically redirects to first resource
+  resources: [
+    defineResource({
+      path: "overview",
+      component: OverviewPage,
+    }),
+    defineResource({
+      path: "analytics",
+      component: AnalyticsPage,
+    }),
+  ],
+});
+```
+
+### Module with Guards
+
+```typescript
+import { pass, hidden } from "@tailor-platform/app-shell";
+
+const adminModule = defineModule({
+  path: "admin",
+  component: AdminPage,
+  resources: [adminResources],
+  guards: [
+    ({ context }) => {
+      return context.currentUser?.role === "admin" ? pass() : hidden();
+    },
+  ],
+});
+```
+
+### Module with Error Boundary
+
+```typescript
+import { useRouteError } from "@tailor-platform/app-shell";
+
+const ErrorBoundary = () => {
+  const error = useRouteError() as Error;
+  return (
+    <div>
+      <h1>Module Error</h1>
+      <p>{error.message}</p>
+    </div>
+  );
+};
+
+const productsModule = defineModule({
+  path: "products",
+  component: ProductsPage,
+  resources: [],
+  errorBoundary: <ErrorBoundary />,
+});
+```
+
+### Module with Internationalization
+
+```typescript
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  dashboard: {
+    en: "Dashboard",
+    ja: "ダッシュボード",
+  },
+});
+
+const dashboardModule = defineModule({
+  path: "dashboard",
+  meta: {
+    title: labels.t("dashboard"),
+  },
+  component: DashboardPage,
+  resources: [],
+});
+```
+
+## TypeScript
+
+```typescript
+import { type DefineModuleProps, type Module } from "@tailor-platform/app-shell";
+
+const props: DefineModuleProps = {
+  path: "products",
+  component: ProductsPage,
+  resources: [],
+};
+
+const module: Module = defineModule(props);
+```
+
+## Related
+
+- [defineResource](./define-resource.md) - Define nested resources
+- [Guards Overview](./guards/overview.md) - Access control
+- [defineI18nLabels](./define-i18n-labels.md) - Internationalization
+- [Modules & Resources Concept](../concepts/modules-and-resources.md) - Detailed guide

package/skills/app-shell-patterns/references/api/define-resource.md

@@ -0,0 +1,307 @@
+---
+title: defineResource
+description: Define a nested resource (page) within a module
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/define-resource.docs.outline.md — do not edit by hand. -->
+
+# defineResource
+
+Creates a nested resource (page) within a module. Resources represent individual pages in your application hierarchy.
+
+## Signature
+
+```typescript
+function defineResource(props: DefineResourceProps): Resource;
+```
+
+## Parameters
+
+### `path`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** URL path segment for the resource. Supports dynamic parameters with `:param` syntax.
+
+```typescript
+defineResource({
+  path: ":id", // Dynamic: /products/:id
+  path: "categories", // Static: /products/categories
+});
+```
+
+### `component`
+
+- **Type:** `(props: ResourceComponentProps) => React.ReactNode`
+- **Required:** Yes
+- **Description:** Page component to render
+
+**ResourceComponentProps:**
+
+```typescript
+{
+  title: string;          // Resolved title
+  icon?: React.ReactNode; // Inherited from module
+  resources?: Resource[]; // Child resources
+}
+```
+
+### `meta`
+
+- **Type:** `object`
+- **Required:** No
+- **Description:** Metadata configuration
+
+**meta.title**
+
+- **Type:** `string | LocalizedString`
+- **Default:** Capitalized `path`
+- **Description:** Display title in navigation and breadcrumbs
+
+**meta.icon**
+
+- **Type:** `React.ReactNode`
+- **Description:** Icon override (inherits from module by default)
+
+**meta.breadcrumbTitle**
+
+- **Type:** `string | ((segment: string) => string)`
+- **Description:** Custom breadcrumb segment title
+
+### `subResources`
+
+- **Type:** `Resource[]`
+- **Required:** No
+- **Description:** Nested resources within this resource
+
+### `guards`
+
+- **Type:** `Guard[]`
+- **Required:** No
+- **Description:** Access control guards
+
+See [Guards Overview](./guards/overview.md) for details.
+
+### `errorBoundary`
+
+- **Type:** `React.ReactNode`
+- **Required:** No
+- **Description:** Error boundary component for this resource
+
+## Return Type
+
+```typescript
+Resource;
+```
+
+A resource object used in the `resources` array of `defineModule`.
+
+## Examples
+
+### Basic Resource
+
+```typescript
+import { defineResource } from "@tailor-platform/app-shell";
+
+const detailResource = defineResource({
+  path: ":id",
+  component: () => <div>Detail Page</div>,
+});
+```
+
+### Resource with Title
+
+```typescript
+const categoriesResource = defineResource({
+  path: "categories",
+  meta: {
+    title: "Product Categories",
+  },
+  component: CategoriesPage,
+});
+```
+
+### Dynamic Route with useParams
+
+```typescript
+import { useParams } from "@tailor-platform/app-shell";
+
+const productDetailResource = defineResource({
+  path: ":id",
+  meta: {
+    title: "Product Details",
+  },
+  component: () => {
+    const { id } = useParams();
+    return <div>Product {id}</div>;
+  },
+});
+```
+
+### Nested Resources
+
+```typescript
+const ordersResource = defineResource({
+  path: "orders",
+  component: OrdersListPage,
+  subResources: [
+    defineResource({
+      path: ":id",
+      component: OrderDetailPage,
+      subResources: [
+        defineResource({
+          path: "edit",
+          component: OrderEditPage,
+        }),
+      ],
+    }),
+  ],
+});
+
+// URLs:
+// /orders
+// /orders/:id
+// /orders/:id/edit
+```
+
+### Resource with Guards
+
+```typescript
+import { pass, hidden } from "@tailor-platform/app-shell";
+
+const adminSettingsResource = defineResource({
+  path: "admin-settings",
+  component: AdminSettingsPage,
+  guards: [
+    ({ context }) => {
+      return context.currentUser?.role === "admin" ? pass() : hidden();
+    },
+  ],
+});
+```
+
+### Resource with Error Boundary
+
+```typescript
+import { useRouteError } from "@tailor-platform/app-shell";
+
+const ErrorBoundary = () => {
+  const error = useRouteError() as Error;
+  return <div>Error: {error.message}</div>;
+};
+
+const detailResource = defineResource({
+  path: ":id",
+  component: DetailPage,
+  errorBoundary: <ErrorBoundary />,
+});
+```
+
+### Resource with Custom Breadcrumb
+
+```typescript
+const orderResource = defineResource({
+  path: ":id",
+  meta: {
+    breadcrumbTitle: (segment) => `Order #${segment}`,
+  },
+  component: OrderDetailPage,
+});
+
+// Breadcrumb shows: "Orders > Order #12345"
+// Instead of: "Orders > 12345"
+```
+
+### Multiple Resources
+
+```typescript
+const productsModule = defineModule({
+  path: "products",
+  component: ProductsPage,
+  resources: [
+    defineResource({
+      path: ":id",
+      meta: { title: "Product Details" },
+      component: ProductDetailPage,
+    }),
+    defineResource({
+      path: "categories",
+      meta: { title: "Categories" },
+      component: CategoriesPage,
+    }),
+    defineResource({
+      path: "brands",
+      meta: { title: "Brands" },
+      component: BrandsPage,
+    }),
+  ],
+});
+```
+
+## Navigation Behavior
+
+Resources appear in:
+
+- ✅ Sidebar navigation (top-level resources only)
+- ✅ Breadcrumbs (all levels)
+- ✅ CommandPalette search (all levels)
+- ❌ Main navigation menu (use modules instead)
+
+### Example Navigation
+
+```typescript
+defineModule({
+  path: "products",
+  component: ProductsPage,
+  resources: [
+    defineResource({
+      path: "all",
+      component: AllProductsPage, // Appears in sidebar
+    }),
+    defineResource({
+      path: ":id",
+      component: ProductDetailPage,
+      subResources: [
+        defineResource({
+          path: "edit",
+          component: EditPage, // Only in breadcrumbs, not sidebar
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**Sidebar:**
+
+```
+› Products
+  - All Products
+```
+
+**Breadcrumbs (on edit page):**
+
+```
+Products > Product Details > Edit
+```
+
+## TypeScript
+
+```typescript
+import { type DefineResourceProps, type Resource } from "@tailor-platform/app-shell";
+
+const props: DefineResourceProps = {
+  path: ":id",
+  component: DetailPage,
+  guards: [],
+};
+
+const resource: Resource = defineResource(props);
+```
+
+## Related
+
+- [defineModule](./define-module.md) - Define top-level modules
+- [Guards Overview](./guards/overview.md) - Access control
+- [useParams](./router/use-params.md) - Access route parameters
+- [Modules & Resources Concept](../concepts/modules-and-resources.md) - Detailed guide