@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/concepts/file-based-routing.md

@@ -0,0 +1,356 @@
+---
+title: File-Based Routing
+description: Define pages via directory structure using the Vite plugin instead of explicit module configuration
+---
+
+<!-- GENERATED by docs-kit from docs-src/concepts/file-based-routing.docs.outline.md — do not edit by hand. -->
+
+# File-Based Routing
+
+File-based routing allows you to define pages by simply placing components in a directory structure, eliminating the need for explicit `defineModule()` and `defineResource()` calls.
+
+## Overview
+
+Instead of manually assembling module/resource hierarchies, you define pages as files in a `pages/` directory. The path is automatically derived from the directory structure.
+
+```
+src/pages/
+├── page.tsx                  # / (root path)
+├── purchasing/
+│   ├── page.tsx              # /purchasing
+│   └── orders/
+│       ├── page.tsx          # /purchasing/orders
+│       └── [id]/
+│           └── page.tsx      # /purchasing/orders/:id
+└── (admin)/                  # Grouping (not included in path)
+    └── settings/
+        └── page.tsx          # /settings
+```
+
+Directories **without** a `page.tsx` still contribute a path segment — navigating to that path returns a 404 while their children remain accessible:
+
+```
+src/pages/
+├── admin/
+│   ├── users/
+│   │   └── page.tsx   # /admin/users → renders page
+│   └── roles/
+│       └── page.tsx   # /admin/roles → renders page
+│   # no page.tsx for /admin → 404
+```
+
+Guards defined on a `page.tsx` apply to that exact path. Directories without `page.tsx` do not support guards — add guards to the individual child pages instead.
+
+## Setup
+
+### 1. Configure Vite Plugin
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    appShellRoutes({
+      entrypoint: "src/App.tsx", // recommended
+    }),
+  ],
+});
+```
+
+#### Plugin Options
+
+The canonical TypeScript import for the Vite plugin and its option types is the
+`@tailor-platform/app-shell/vite-plugin` subpath:
+
+```ts
+import {
+  appShellRoutes,
+  type AppShellRoutesPluginOptions,
+  type TypedRoutesOptions,
+} from "@tailor-platform/app-shell/vite-plugin";
+```
+
+| Option                | Type                            | Default       | Description                                                                          |
+| --------------------- | ------------------------------- | ------------- | ------------------------------------------------------------------------------------ |
+| `pagesDir`            | `string`                        | `"src/pages"` | Directory containing page files                                                      |
+| `logLevel`            | `"info" \| "debug" \| "off"`    | `"info"`      | Log level for plugin output                                                          |
+| `entrypoint`          | `string`                        | `undefined`   | File that renders the AppShell component (relative to project root). See note below. |
+| `generateTypedRoutes` | `boolean \| { output: string }` | `false`       | Generate a TypeScript file with type-safe route definitions                          |
+
+> **`entrypoint` (recommended):** When specified, only imports from this file are intercepted and replaced with the pages-injected AppShell. All other files — including page components — import directly from the real package. Without this option, all user-code imports of `@tailor-platform/app-shell` are intercepted, which can cause TDZ (Temporal Dead Zone) errors in page components that also import from the package.
+
+### 2. Use AppShell (No Configuration Needed)
+
+```tsx
+// App.tsx
+import { AppShell, SidebarLayout, DefaultSidebar } from "@tailor-platform/app-shell";
+
+const App = () => {
+  return (
+    <AppShell title="My App">
+      <SidebarLayout sidebar={<DefaultSidebar />} />
+    </AppShell>
+  );
+};
+```
+
+Pages are automatically discovered and injected—no `modules` prop required!
+
+## Page Components
+
+### Minimal Example
+
+The simplest page is just a default-exported component:
+
+```tsx
+// src/pages/about/page.tsx
+export default () => <div>About</div>;
+```
+
+### Full Example
+
+Use `appShellPageProps` static field to configure page metadata and guards:
+
+```tsx
+// src/pages/dashboard/page.tsx
+import type { AppShellPageProps } from "@tailor-platform/app-shell";
+import { authGuard } from "../guards";
+import { DashboardIcon } from "../icons";
+
+const DashboardPage = () => {
+  return <div>Dashboard Content</div>;
+};
+
+DashboardPage.appShellPageProps = {
+  meta: {
+    title: "Dashboard",
+    icon: <DashboardIcon />,
+  },
+  guards: [authGuard],
+} satisfies AppShellPageProps;
+
+export default DashboardPage;
+```
+
+### AppShellPageProps Type
+
+```typescript
+type AppShellPageProps = {
+  meta?: {
+    title?: LocalizedString;
+    icon?: ReactNode;
+    breadcrumbTitle?: string | ((segment: string) => LocalizedString);
+  };
+  guards?: Guard[];
+};
+```
+
+For a localized breadcrumb, use `meta: { breadcrumbTitle: labels.t("orders") }`, just like `meta.title`.
+AppShell recognizes translation functions created by `labels.t()` and resolves them with the current locale.
+For a dynamic label, use `breadcrumbTitle: (segment) => labels.t("order", { id: segment })`.
+Other callbacks receive the URL segment; AppShell resolves any returned `LocalizedString` with the current locale.
+The existing `() => labels.t("orders")` form remains supported. Wrap handwritten locale functions in an outer callback rather than passing them directly.
+
+## Path Conventions
+
+| Directory Name | Converts To | Description                                    |
+| -------------- | ----------- | ---------------------------------------------- |
+| `orders`       | `orders`    | Static segment                                 |
+| `[id]`         | `:id`       | Dynamic parameter                              |
+| `[...slug]`    | `*slug`     | Catch-all — matches zero or more path segments |
+| `(group)`      | (excluded)  | Grouping only (not in path)                    |
+| `_lib`         | (ignored)   | Not routed (for shared logic)                  |
+
+### Examples
+
+```
+src/pages/
+├── users/
+│   ├── page.tsx              # /users
+│   └── [userId]/
+│       └── page.tsx          # /users/:userId
+├── (marketing)/
+│   ├── campaigns/
+│   │   └── page.tsx          # /campaigns (not /marketing/campaigns)
+│   └── analytics/
+│       └── page.tsx          # /analytics
+└── _utils/
+    └── helpers.ts            # Not routed (shared utilities)
+```
+
+## Guards
+
+Guards are **not** automatically inherited from parent pages. Each page must explicitly define its own guards:
+
+```tsx
+// /dashboard/page.tsx
+DashboardPage.appShellPageProps = {
+  guards: [authGuard],
+} satisfies AppShellPageProps;
+
+// /dashboard/admin/page.tsx — must include authGuard explicitly
+AdminPage.appShellPageProps = {
+  guards: [authGuard, adminGuard],
+} satisfies AppShellPageProps;
+```
+
+To share common guards across pages, compose them from a shared module:
+
+```tsx
+// src/guards.ts
+export const requireAuth = [authGuard];
+export const requireAdmin = [authGuard, adminGuard];
+
+// src/pages/dashboard/orders/page.tsx
+import { requireAuth } from "@/guards";
+
+OrdersPage.appShellPageProps = {
+  guards: [...requireAuth],
+} satisfies AppShellPageProps;
+```
+
+## Typed Routes
+
+Enable `generateTypedRoutes` in the Vite plugin to generate type-safe route helpers:
+
+```typescript
+// vite.config.ts
+appShellRoutes({
+  generateTypedRoutes: true,
+});
+```
+
+This generates `src/routes.generated.ts` with a `paths` helper:
+
+```tsx
+import { paths } from './routes.generated';
+import { Link } from '@tailor-platform/app-shell';
+
+// Static routes
+<Link to={paths.for("/dashboard")}>Dashboard</Link>
+
+// Dynamic routes - params are type-checked
+<Link to={paths.for("/dashboard/orders/:id", { id: orderId })}>Order</Link>
+
+// TypeScript catches errors:
+paths.for("/dashboard/orders/:id"); // Error: missing 'id'
+paths.for("/invalid");              // Error: route doesn't exist
+```
+
+## Comparison with Legacy API
+
+### Before: Explicit Hierarchy Assembly
+
+```tsx
+const orderDetailResource = defineResource({ path: ":id", component: OrderDetail });
+const ordersResource = defineResource({
+  path: "orders",
+  component: OrdersList,
+  subResources: [orderDetailResource],
+});
+const purchasingModule = defineModule({
+  path: "purchasing",
+  resources: [ordersResource],
+});
+
+<AppShell modules={[purchasingModule]} />;
+```
+
+### After: File-Based Pages
+
+```tsx
+// src/pages/purchasing/orders/[id]/page.tsx
+const OrderDetailPage = () => <div>Order Detail</div>;
+OrderDetailPage.appShellPageProps = {
+  meta: { title: "Order Detail" },
+} satisfies AppShellPageProps;
+export default OrderDetailPage;
+```
+
+```tsx
+// App.tsx - No configuration needed
+<AppShell title="My App">
+  <SidebarLayout sidebar={<DefaultSidebar />} />
+</AppShell>
+```
+
+### Concept Mapping
+
+| Legacy API              | File-Based                      | Notes                         |
+| ----------------------- | ------------------------------- | ----------------------------- |
+| `Module`                | —                               | First-level directory         |
+| `Resource`              | —                               | Directory structure           |
+| `defineModule()`        | —                               | Not needed                    |
+| `defineResource()`      | —                               | Not needed                    |
+| `path` property         | Directory name                  | Auto-derived                  |
+| `component` property    | `page.tsx` default export       | File convention               |
+| `meta` property         | `Page.appShellPageProps.meta`   | Static field                  |
+| `guards` property       | `Page.appShellPageProps.guards` | Static field (no inheritance) |
+| `subResources` property | Subdirectories                  | Auto-derived                  |
+
+## Compatibility
+
+File-based pages and explicit `modules` prop are **mutually exclusive**.
+
+### Usage Patterns
+
+```tsx
+// ✅ Pattern 1: File-based pages with plugin (recommended)
+// vite.config.ts has plugin configured
+<AppShell title="My App">
+  <SidebarLayout sidebar={<DefaultSidebar />} />
+</AppShell>
+
+// ✅ Pattern 2: Explicit modules without plugin (legacy)
+<AppShell modules={[myModule]} title="My App">
+  <SidebarLayout sidebar={<DefaultSidebar />} />
+</AppShell>
+
+// ✅ Pattern 3: Plugin enabled + modules prop (modules takes precedence)
+// Even with plugin enabled, modules prop is used when provided
+<AppShell modules={[myModule]} title="My App">
+  <SidebarLayout sidebar={<DefaultSidebar />} />
+</AppShell>
+
+// ❌ Pattern 4: No plugin + no modules (runtime error)
+<AppShell title="My App">
+  {/* → Runtime error: No routes configured */}
+</AppShell>
+```
+
+## Migration Guide
+
+To migrate from `defineModule`/`defineResource` to file-based routing:
+
+1. **Add Vite Plugin**
+
+   ```typescript
+   // vite.config.ts
+   import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";
+
+   export default defineConfig({
+     plugins: [react(), appShellRoutes({ entrypoint: "src/App.tsx" })],
+   });
+   ```
+
+2. **Create pages directory structure**
+   - Map each module to a top-level directory
+   - Map each resource to a subdirectory with `page.tsx`
+   - Use `[param]` for dynamic segments
+
+3. **Move component and metadata**
+
+   ```tsx
+   // Before: defineResource({ path: "orders", component: Orders, meta: {...} })
+
+   // After: src/pages/orders/page.tsx
+   const OrdersPage = () => <Orders />;
+   OrdersPage.appShellPageProps = { meta: {...} };
+   export default OrdersPage;
+   ```
+
+4. **Remove `modules` prop** from `<AppShell>` once all pages are migrated

package/skills/app-shell-patterns/references/{fundamental → concepts}/graphql.md

@@ -1,3 +1,10 @@
+---
+title: GraphQL Conventions
+description: Conventions for data access in AppShell apps — urql setup, fragment collocation, the connection pattern, and mutation cache invalidation
+---
+
+<!-- GENERATED by docs-kit from docs-src/concepts/graphql.docs.outline.md — do not edit by hand. -->
+
 # GraphQL Conventions
 
 Type-safe GraphQL via `gql.tada`. The frontend never hand-writes types — generated bindings come from `pnpm generate` (step 2 of the workflow) reading the deployed backend schema.
@@ -12,7 +19,7 @@ import { graphql, type FragmentOf, readFragment } from "@/graphql";
 
 `@/graphql` is generated. Don't import `gql` from `urql` or `gql.tada` directly — go through the barrel so types stay coherent.
 
-The urql client is wired in `App.tsx` (see [project-setup.md](project-setup.md)). Pages don't construct their own client.
+The urql client is wired in your app's root (`App.tsx`); pages don't construct their own client.
 
 ## Built-in operations vs custom resolvers
 
@@ -106,7 +113,7 @@ For `pnpm gql-tada:check` to pass, always destructure with optional chaining and
 
 ### Wiring to `DataTable` (sort, filters, pagination)
 
-For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See **`patterns/list/dense-scan.md`** and **`components.md` → DataTable**.
+For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See [`list-dense-scan`](../patterns/list-dense-scan.md) and [`DataTable`](../components/data-table.md).
 
 When `@tailor-platform/sdk-plugin-app-shell` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
 
@@ -146,22 +153,28 @@ function CreateOrderButton() {
 
 ### `additionalTypenames`
 
-When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename:
+When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename.
+
+Define the query's static `context` at module scope, outside the component, so its reference stays stable between renders. `useQuery` lists `context` as a hook dependency, so a fresh object on each render re-creates the query subscription and can cause query re-execution loops. The mutation's second argument is passed per call and is not a hook dependency, so it can stay inline.
 
 ```tsx
-// Query side — declares it cares about the Order typename
-const [{ data }] = useQuery({
-  query: OrdersQuery,
-  variables: { first: 25 },
-  context: { additionalTypenames: ["Order"] },
-});
-
-// Mutation side — declares it produces Order writes
-const [, createOrder] = useMutation(CreateOrderMutation);
-await createOrder(
-  { input },
-  { additionalTypenames: ["Order"] }, // triggers refetch of any query subscribed to 'Order'
-);
+const ordersQueryContext = { additionalTypenames: ["Order"] };
+
+function useOrders() {
+  // Query side — declares it cares about the Order typename
+  const [{ data }] = useQuery({
+    query: OrdersQuery,
+    variables: { first: 25 },
+    context: ordersQueryContext,
+  });
+
+  // Mutation side — declares it produces Order writes
+  const [, executeCreateOrder] = useMutation(CreateOrderMutation);
+  const createOrder = (input: CreateOrderInput) =>
+    executeCreateOrder({ input }, { additionalTypenames: ["Order"] });
+
+  return { data, createOrder };
+}
 ```
 
 Skip `additionalTypenames` only when the mutation's return type already includes the affected entity _and_ every cached query for it touched the same `id` — urql will then refresh by id. When in doubt, add it.
@@ -191,7 +204,7 @@ Every page component:
    };
    ```
 
-3. Uses `appShellPageProps.guards` for permission gates. See [project-setup.md](project-setup.md).
+3. Uses `appShellPageProps.guards` for permission gates.
 
 ## Quick reference
 
@@ -202,4 +215,4 @@ Every page component:
 | Why isn't my list refreshing after a mutation? | Add `additionalTypenames: ['<Type>']` on both query and mutation                                              |
 | Connection vs array?                           | Always connection (`edges { node }`) for built-in `<entities>` queries; check the schema for custom resolvers |
 | Pagination / sort / toolbar filters together?  | `useCollectionVariables` + `DataTable`; see § **Wiring to `DataTable`** above                                 |
-| Where's the urql client configured?            | `App.tsx` — see `project-setup.md`                                                                            |
+| Where's the urql client configured?            | `App.tsx` (your app's root)                                                                                   |

package/skills/app-shell-patterns/references/concepts/modules-and-resources.md

@@ -0,0 +1,229 @@
+---
+title: Modules and Resources
+description: Learn how to structure your AppShell application using modules and resources for automatic routing, navigation, and breadcrumbs
+---
+
+<!-- GENERATED by docs-kit from docs-src/concepts/modules-and-resources.docs.outline.md — do not edit by hand. -->
+
+# Modules and Resources
+
+AppShell renders sidebar navigation, breadcrumbs, and handles routing based on a structured configuration of modules and resources (and sub-resources, sub-sub-resources, and so on).
+
+Modules and Resources both share core interface. Of interest:
+
+- `path: string` - the path segment
+- `component: (props: ResourceComponentProps) => ReactNode` - the component to render when the router navigates to that module/resource (optional — omitting it causes the path to return a 404 while child routes remain accessible)
+- `guards?: Guard[]` - optional array of guard functions to control access based on permissions or feature flags
+
+A trivial `modules` example:
+
+```tsx
+import { defineModule, defineResource, pass, hidden } from "@tailor-platform/app-shell";
+
+const appShellPropModule = [
+  defineModule({
+    path: "purchasing",
+    component: PurchasingLandingPage,
+    resources: [
+      defineResource({
+        path: "orders",
+        component: OrdersPage,
+        subResources: [
+          defineResource({
+            path: ":id",
+            component: OrderDetailPage,
+          }),
+        ],
+      }),
+      defineResource({
+        path: "invoices",
+        component: PurchaseInvoicesPage,
+        // ...
+      }),
+    ],
+  }),
+  defineModule({
+    path: "sales",
+    component: SalesLandingPage,
+    resources: [
+      defineResource({
+        path: "invoices",
+        component: SalesInvoicesPage,
+        // ...
+      }),
+      // ...
+    ],
+  }),
+  // Module without component - /dashboard returns 404, child routes remain accessible
+  defineModule({
+    path: "dashboard",
+    resources: [
+      defineResource({
+        path: "overview",
+        component: DashboardOverview,
+      }),
+      defineResource({
+        path: "analytics",
+        component: DashboardAnalytics,
+      }),
+    ],
+  }),
+  // Module with guards for access control
+  defineModule({
+    path: "reports",
+    component: ReportsPage,
+    resources: [reportsListResource],
+    guards: [
+      async ({ context, signal }) => {
+        const ok = await fetch("/api/me/permissions?scope=reports", {
+          signal,
+        }).then((r) => r.ok);
+        return ok ? pass() : hidden();
+      },
+    ],
+  }),
+];
+```
+
+Produces the following navigation menu:
+
+```
+› Purchasing
+  - Orders
+  - Invoices
+› Sales
+  - Invoices
+  ...
+› Reports  (only visible if user has reports permission)
+```
+
+Modules show as top-level menu items and resources are the sub-menu items. Sub-resources do not show up on the side navigation menu, but will be available via other navigation and show in breadcrumbs.
+
+In the example above, clicking the 'Orders' menu item above will take you to `/{basePath}/purchasing/orders` and render the OrdersPage page. If you browse, either by direct request or via client-side navigation to `/{basePath}/purchasing/orders/1234`, AppShell will render OrderDetailPage with 'id' available via useParams
+
+Providing a `component` for a Module is optional. If omitted, navigating directly to the module path returns a 404 response while its child resources remain fully accessible. This is useful when a path segment exists solely to group child routes under a shared URL prefix with no landing page of its own.
+
+When a module has no `component`, its breadcrumb segment is rendered as plain non-clickable text (instead of a link), preventing navigation to a page that does not exist.
+
+The same applies to resources: a `defineResource()` call without a `component` makes the resource path itself return 404 while its `subResources` remain accessible.
+
+Guards on component-less modules and resources execute correctly. For example, a `redirectTo()` guard will fire as expected. If all guards return `pass()`, the route falls back to a 404 (since there is no component to render).
+
+> Read more about [client-side navigation](./routing-navigation.md) in AppShell apps
+
+## Route Guards
+
+Both modules and resources support `guards` - an array of functions that control access based on permissions, feature flags, or any other criteria. Guards are executed in order and provide:
+
+- Composability: Combine multiple guards for complex access logic
+- Reusability: Share common guards across routes
+- Semantic constraints: Clear `pass()`, `hidden()`, or `redirectTo()` results
+
+See the [Guards documentation](../api/guards/overview.md) for full details.
+
+### Guard Examples
+
+**Permission-based access:**
+
+```tsx
+import { defineModule, pass, hidden } from "@tailor-platform/app-shell";
+
+const reportsModule = defineModule({
+  path: "reports",
+  component: ReportsPage,
+  resources: [reportsListResource],
+  guards: [
+    async ({ context }) => {
+      const ok = await fetch("/api/me/permissions?scope=reports").then((r) => r.ok);
+      return ok ? pass() : hidden();
+    },
+  ],
+});
+```
+
+**Feature flag based:**
+
+```tsx
+import { pass, hidden } from "@tailor-platform/app-shell";
+
+const betaFeaturesModule = defineModule({
+  path: "beta",
+  component: BetaFeaturesPage,
+  resources: [newFeatureResource],
+  guards: [
+    async ({ context }) => {
+      const enabled = await checkFeatureFlag("beta-features");
+      return enabled ? pass() : hidden();
+    },
+  ],
+});
+```
+
+**Tenant tier based:**
+
+```tsx
+import { pass, hidden } from "@tailor-platform/app-shell";
+
+const billingModule = defineModule({
+  path: "billing",
+  component: BillingPage,
+  resources: [billingResources],
+  guards: [
+    async ({ context }) => {
+      const plan = await getCurrentTenantPlan();
+      return plan === "enterprise" ? pass() : hidden();
+    },
+  ],
+});
+```
+
+**Resource-level guards:**
+
+```tsx
+import { pass, hidden } from "@tailor-platform/app-shell";
+
+defineResource({
+  path: "admin-settings",
+  component: AdminSettingsPage,
+  guards: [
+    async ({ context }) => {
+      const user = await getCurrentUser();
+      return user.role === "admin" ? pass() : hidden();
+    },
+  ],
+});
+```
+
+**Reusable guards:**
+
+```tsx
+import { type Guard, pass, hidden, redirectTo } from "@tailor-platform/app-shell";
+
+// Define reusable guards
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    return redirectTo("/login");
+  }
+  return pass();
+};
+
+const requireAdmin: Guard = ({ context }) => {
+  if (context.currentUser?.role !== "admin") {
+    return hidden();
+  }
+  return pass();
+};
+
+// Use in multiple resources
+defineResource({
+  path: "admin/users",
+  component: AdminUsersPage,
+  guards: [requireAuth, requireAdmin],
+});
+```
+
+When a module or resource is hidden via guards, it will:
+
+- Not appear in navigation menus
+- Not be accessible via direct URL navigation
+- Not appear in CommandPalette search results