@tailor-platform/app-shell 1.16.0 → 1.17.0

package/skills/app-shell-patterns/references/api/use-app-shell-config.md

@@ -7,24 +7,49 @@ description: Hook to access AppShell configuration data
 
 # useAppShellConfig
 
-React hook to access only the AppShell configuration (title, icon, basePath, modules, settingsResources). This is a lighter alternative to `useAppShell` when you only need configuration data.
+React hook to access only the AppShell configuration (title, icon, favicon, appInfo, and the resolved `configurations` object with modules, settingsResources, basePath, locale, and timeZone). This is a lighter alternative to `useAppShell` when you only need configuration data.
 
 ## Signature
 
 ```typescript
-const useAppShellConfig: () => AppShellConfig;
+const useAppShellConfig: () => {
+  title?: string;
+  icon?: React.ReactNode;
+  favicon?: string;
+  appInfo?: AppInfo;
+  configurations: {
+    modules: ReturnType<typeof defineModule>[];
+    settingsResources: ReturnType<typeof defineResource>[];
+    basePath?: string;
+    locale: string;
+    resolvedLocale?: string;
+    timeZone?: string;
+    errorBoundary: ErrorBoundaryComponent;
+  };
+};
 ```
 
 ## Return Value
 
-| Property            | Type                           | Description                                      |
-| ------------------- | ------------------------------ | ------------------------------------------------ |
-| `title`             | `string \| undefined`          | App title                                        |
-| `icon`              | `React.ReactNode \| undefined` | App icon                                         |
-| `basePath`          | `string \| undefined`          | Base path for all routes                         |
-| `modules`           | `Module[]`                     | Registered modules                               |
-| `settingsResources` | `Resource[]`                   | Resources that appear only in Settings menu      |
-| `appInfo`           | `AppInfo \| undefined`         | Configuration for the built-in `/__appinfo` page |
+| Property         | Type                           | Description                                      |
+| ---------------- | ------------------------------ | ------------------------------------------------ |
+| `title`          | `string \| undefined`          | App title                                        |
+| `icon`           | `React.ReactNode \| undefined` | App icon                                         |
+| `favicon`        | `string \| undefined`          | Favicon URL                                      |
+| `appInfo`        | `AppInfo \| undefined`         | Configuration for the built-in `/__appinfo` page |
+| `configurations` | object                         | Resolved configuration, see below                |
+
+### `configurations`
+
+| Property            | Type                                  | Description                                           |
+| ------------------- | ------------------------------------- | ----------------------------------------------------- |
+| `modules`           | `ReturnType<typeof defineModule>[]`   | Registered modules (`Module` itself is not exported)  |
+| `settingsResources` | `ReturnType<typeof defineResource>[]` | Resources that appear only in Settings menu           |
+| `basePath`          | `string \| undefined`                 | Base path for all routes                              |
+| `locale`            | `string`                              | Language subtag used for built-in UI strings (`"en"`) |
+| `resolvedLocale`    | `string \| undefined`                 | Full BCP-47 tag used for Intl / date formatting       |
+| `timeZone`          | `string \| undefined`                 | IANA timezone used by date/time components            |
+| `errorBoundary`     | `ErrorBoundaryComponent`              | Global error boundary element                         |
 
 ## Usage
 
@@ -34,12 +59,12 @@ const useAppShellConfig: () => AppShellConfig;
 import { useAppShellConfig } from "@tailor-platform/app-shell";
 
 function AppInfo() {
-  const { title, basePath } = useAppShellConfig();
+  const { title, configurations } = useAppShellConfig();
 
   return (
     <div>
       <h2>{title}</h2>
-      <p>Base: {basePath}</p>
+      <p>Base: {configurations.basePath}</p>
     </div>
   );
 }
@@ -47,51 +72,33 @@ function AppInfo() {
 
 ### Access Modules
 
+Module titles are `LocalizedString` values (a string or a `(locale) => string` function), so the example lists `path` instead of rendering `meta.title` directly.
+
 ```typescript
 function ModuleList() {
-  const { modules } = useAppShellConfig();
+  const { configurations } = useAppShellConfig();
 
   return (
     <ul>
-      {modules.map((module) => (
-        <li key={module.path}>{module.meta?.title}</li>
+      {configurations.modules.map((module) => (
+        <li key={module.path}>{module.path}</li>
       ))}
     </ul>
   );
 }
 ```
 
-### Build Custom Navigation
-
-```typescript
-function CustomNav() {
-  const { modules } = useAppShellConfig();
-
-  return (
-    <nav>
-      {modules.map((module) => (
-        <a key={module.path} href={`/${module.path}`}>
-          {module.meta?.title}
-        </a>
-      ))}
-    </nav>
-  );
-}
-```
-
 ### Settings Resources
 
 ```typescript
 function SettingsMenu() {
-  const { settingsResources } = useAppShellConfig();
+  const { configurations } = useAppShellConfig();
 
   return (
     <div>
       <h3>Settings</h3>
-      {settingsResources.map((resource) => (
-        <button key={resource.path}>
-          {resource.meta?.title}
-        </button>
+      {configurations.settingsResources.map((resource) => (
+        <button key={resource.path}>{resource.path}</button>
       ))}
     </div>
   );
@@ -103,21 +110,20 @@ function SettingsMenu() {
 Use `useAppShellConfig` when you only need configuration data:
 
 ```typescript
-// ✅ Good - only need config
-const { modules } = useAppShellConfig();
+// ✅ Good - subscribes to configuration only
+const { configurations } = useAppShellConfig();
 
-// ❌ Overkill - useAppShell returns more data
+// ❌ Overkill - useAppShell also subscribes to contextData changes
 const { configurations } = useAppShell();
-const modules = configurations.modules;
 ```
 
 ## Comparison with Other Hooks
 
-| Hook                | Returns               | Use When            |
-| ------------------- | --------------------- | ------------------- |
-| `useAppShellConfig` | Configuration only    | Need config data    |
-| `useAppShellData`   | Context data only     | Need custom context |
-| `useAppShell`       | Both config + context | Need both           |
+| Hook                | Returns                                             | Use When            |
+| ------------------- | --------------------------------------------------- | ------------------- |
+| `useAppShellConfig` | `{ title, icon, favicon, appInfo, configurations }` | Need config data    |
+| `useAppShellData`   | `{ contextData }`                                   | Need custom context |
+| `useAppShell`       | Both, merged into one object                        | Need both           |
 
 ## Related
 

package/skills/app-shell-patterns/references/api/use-app-shell-data.md

@@ -12,14 +12,16 @@ React hook to access only the custom context data. This is a lighter alternative
 ## Signature
 
 ```typescript
-const useAppShellData: () => ContextData;
+const useAppShellData: () => {
+  contextData: ContextData;
+};
 ```
 
 ## Return Value
 
-| Type          | Description                                                               |
-| ------------- | ------------------------------------------------------------------------- |
-| `ContextData` | Custom context data passed to AppShell (type-safe via `AppShellRegister`) |
+| Property      | Type          | Description                                                               |
+| ------------- | ------------- | ------------------------------------------------------------------------- |
+| `contextData` | `ContextData` | Custom context data passed to AppShell (type-safe via `AppShellRegister`) |
 
 ## Usage
 
@@ -29,7 +31,7 @@ const useAppShellData: () => ContextData;
 import { useAppShellData } from "@tailor-platform/app-shell";
 
 function UserProfile() {
-  const contextData = useAppShellData();
+  const { contextData } = useAppShellData();
 
   return (
     <div>
@@ -44,16 +46,16 @@ function UserProfile() {
 
 ```typescript
 function UserInfo() {
-  const data = useAppShellData();
+  const { contextData } = useAppShellData();
 
-  if (!data.currentUser) {
+  if (!contextData.currentUser) {
     return <div>Not logged in</div>;
   }
 
   return (
     <div>
-      <h2>{data.currentUser.name}</h2>
-      <p>{data.currentUser.email}</p>
+      <h2>{contextData.currentUser.name}</h2>
+      <p>{contextData.currentUser.email}</p>
     </div>
   );
 }
@@ -63,8 +65,8 @@ function UserInfo() {
 
 ```typescript
 function AdminPanel() {
-  const { permissions } = useAppShellData();
-  const canManageUsers = permissions.includes("users:manage");
+  const { contextData } = useAppShellData();
+  const canManageUsers = contextData.permissions.includes("users:manage");
 
   if (!canManageUsers) {
     return <AccessDenied />;
@@ -78,9 +80,9 @@ function AdminPanel() {
 
 ```typescript
 function BetaFeature() {
-  const { featureFlags } = useAppShellData();
+  const { contextData } = useAppShellData();
 
-  if (!featureFlags?.newEditor) {
+  if (!contextData.featureFlags?.newEditor) {
     return <LegacyEditor />;
   }
 
@@ -94,6 +96,8 @@ Define your context type with module augmentation:
 
 ```typescript
 // types.d.ts
+type User = { name: string; email: string; role: string };
+
 declare module "@tailor-platform/app-shell" {
   interface AppShellRegister {
     contextData: {
@@ -112,10 +116,10 @@ declare module "@tailor-platform/app-shell" {
 Now `useAppShellData()` returns fully typed data:
 
 ```typescript
-const data = useAppShellData();
-data.currentUser; // Type: User | null
-data.permissions; // Type: string[]
-data.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
+const { contextData } = useAppShellData();
+contextData.currentUser; // Type: User | null
+contextData.permissions; // Type: string[]
+contextData.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
 ```
 
 ## When to Use
@@ -123,20 +127,20 @@ data.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
 Use `useAppShellData` when you only need context data:
 
 ```typescript
-// ✅ Good - only need context
-const data = useAppShellData();
+// ✅ Good - subscribes to context data only
+const { contextData } = useAppShellData();
 
-// ❌ Overkill - useAppShell returns more than needed
-const { context } = useAppShell();
+// ❌ Overkill - useAppShell also subscribes to configuration changes
+const { contextData } = useAppShell();
 ```
 
 ## Comparison with Other Hooks
 
-| Hook                | Returns               | Use When            |
-| ------------------- | --------------------- | ------------------- |
-| `useAppShellData`   | Context data only     | Need custom context |
-| `useAppShellConfig` | Configuration only    | Need config data    |
-| `useAppShell`       | Both config + context | Need both           |
+| Hook                | Returns                                             | Use When            |
+| ------------------- | --------------------------------------------------- | ------------------- |
+| `useAppShellData`   | `{ contextData }`                                   | Need custom context |
+| `useAppShellConfig` | `{ title, icon, favicon, appInfo, configurations }` | Need config data    |
+| `useAppShell`       | Both, merged into one object                        | Need both           |
 
 ## Related
 

package/skills/app-shell-patterns/references/api/use-app-shell.md

@@ -13,23 +13,40 @@ React hook to access AppShell context data and configuration within your compone
 
 ```typescript
 const useAppShell: () => {
-  context: ContextData;
   contextData: ContextData;
-  configurations: AppShellConfig;
+  configurations: {
+    modules: ReturnType<typeof defineModule>[];
+    settingsResources: ReturnType<typeof defineResource>[];
+    basePath?: string;
+    locale: string;
+    resolvedLocale?: string;
+    timeZone?: string;
+    errorBoundary: ErrorBoundaryComponent;
+  };
+  title?: string;
+  icon?: React.ReactNode;
+  favicon?: string;
+  appInfo?: AppInfo;
 };
 ```
 
+The hook merges the results of [`useAppShellConfig`](./use-app-shell-config.md) and [`useAppShellData`](./use-app-shell-data.md). Prefer one of those when you only need configuration or only need context data, so the component does not re-render for changes it does not use.
+
 ## Return Value
 
-### `context` / `contextData`
+### `contextData`
 
 - **Type:** `ContextData`
 - **Description:** Custom context data passed to AppShell. Same as the `contextData` prop.
 
 ### `configurations`
 
-- **Type:** `AppShellConfig`
-- **Description:** AppShell configuration (locale, basePath, etc.)
+- **Type:** object
+- **Description:** Resolved AppShell configuration: `modules`, `settingsResources`, `basePath`, `locale`, `resolvedLocale`, `timeZone`, and `errorBoundary`.
+
+### `title`, `icon`, `favicon`, `appInfo`
+
+- **Description:** The matching AppShell props, as passed.
 
 ## Usage
 
@@ -39,9 +56,9 @@ const useAppShell: () => {
 import { useAppShell } from "@tailor-platform/app-shell";
 
 function MyComponent() {
-  const { context } = useAppShell();
+  const { contextData } = useAppShell();
 
-  return <div>Welcome, {context.currentUser?.name}</div>;
+  return <div>Welcome, {contextData.currentUser?.name}</div>;
 }
 ```
 
@@ -61,6 +78,8 @@ Define your context type with module augmentation:
 
 ```typescript
 // types.d.ts
+type User = { name: string; email: string; role: string };
+
 declare module "@tailor-platform/app-shell" {
   interface AppShellRegister {
     contextData: {
@@ -82,9 +101,9 @@ declare module "@tailor-platform/app-shell" {
 />
 
 // MyComponent.tsx
-const { context } = useAppShell();
-context.currentUser  // Fully typed!
-context.permissions  // Fully typed!
+const { contextData } = useAppShell();
+contextData.currentUser  // Fully typed!
+contextData.permissions  // Fully typed!
 ```
 
 ## Examples
@@ -93,16 +112,16 @@ context.permissions  // Fully typed!
 
 ```typescript
 function UserInfo() {
-  const { context } = useAppShell();
+  const { contextData } = useAppShell();
 
-  if (!context.currentUser) {
+  if (!contextData.currentUser) {
     return <div>Not logged in</div>;
   }
 
   return (
     <div>
-      <h2>{context.currentUser.name}</h2>
-      <p>{context.currentUser.email}</p>
+      <h2>{contextData.currentUser.name}</h2>
+      <p>{contextData.currentUser.email}</p>
     </div>
   );
 }
@@ -112,8 +131,8 @@ function UserInfo() {
 
 ```typescript
 function DeleteButton() {
-  const { context } = useAppShell();
-  const canDelete = context.permissions.includes("users:delete");
+  const { contextData } = useAppShell();
+  const canDelete = contextData.permissions.includes("users:delete");
 
   if (!canDelete) {
     return null;
@@ -123,21 +142,9 @@ function DeleteButton() {
 }
 ```
 
-### Feature Flags
-
-```typescript
-function BetaFeature() {
-  const { context } = useAppShell();
-
-  if (!context.featureFlags?.newDashboard) {
-    return <OldDashboard />;
-  }
-
-  return <NewDashboard />;
-}
-```
-
 ## Related
 
 - [AppShell Component](../components/app-shell.md) - Root component
+- [useAppShellData](./use-app-shell-data.md) - Context data only
+- [useAppShellConfig](./use-app-shell-config.md) - Configuration only
 - [Guards Overview](./guards/overview.md) - Access control using context

package/skills/app-shell-patterns/references/api/use-toast.md

@@ -7,26 +7,36 @@ description: Hook for displaying toast notifications
 
 # useToast
 
-React hook to display toast notifications for user feedback.
+React hook to display toast notifications for user feedback. It returns the `toast` function exported by [sonner](https://sonner.emilkowal.ski/toast). The built-in layouts (`SidebarLayout`, `GlobalHeaderLayout`) already render the toaster, so no provider setup is needed.
 
 ## Signature
 
 ```typescript
-const useToast: () => {
-  toast: (props: ToastProps) => void;
-};
+const useToast: () => typeof toast; // `toast` is sonner's export; use `ReturnType<typeof useToast>` to name it
+
+// The returned function (abbreviated; see sonner for the full signature)
+toast(message: React.ReactNode, options?: ExternalToast): string | number;
+toast.success(message, options?);
+toast.error(message, options?);
+toast.info(message, options?);
+toast.warning(message, options?);
+toast.loading(message, options?);
+toast.promise(promise, { loading, success, error });
+toast.dismiss(id?);
 ```
 
 ## Parameters
 
-### ToastProps
+### ExternalToast
+
+The options type of sonner's `toast`. Inside an app that depends only on `@tailor-platform/app-shell`, name it as `Parameters<ReturnType<typeof useToast>>[1]` (importing it from `sonner` requires sonner as a direct dependency). The most common fields:
 
 ```typescript
 {
-  title?: string;
-  description?: string;
-  variant?: "default" | "success" | "error" | "warning";
+  description?: React.ReactNode;
   duration?: number; // milliseconds
+  action?: { label: React.ReactNode; onClick: (event: React.MouseEvent) => void };
+  id?: string | number;
 }
 ```
 
@@ -38,14 +48,11 @@ const useToast: () => {
 import { useToast } from "@tailor-platform/app-shell";
 
 function SaveButton() {
-  const { toast } = useToast();
+  const toast = useToast();
 
   const handleSave = () => {
     // Save logic...
-    toast({
-      title: "Saved!",
-      description: "Your changes have been saved.",
-    });
+    toast("Saved", { description: "Your changes have been saved." });
   };
 
   return <button onClick={handleSave}>Save</button>;
@@ -56,15 +63,11 @@ function SaveButton() {
 
 ```typescript
 function CreateButton() {
-  const { toast } = useToast();
+  const toast = useToast();
 
   const handleCreate = async () => {
-    await createItem();
-    toast({
-      title: "Created",
-      description: "Item created successfully.",
-      variant: "success",
-    });
+    const item = await createItem();
+    toast.success(`Item ${item.id} created`);
   };
 
   return <button onClick={handleCreate}>Create</button>;
@@ -75,17 +78,13 @@ function CreateButton() {
 
 ```typescript
 function DeleteButton() {
-  const { toast } = useToast();
+  const toast = useToast();
 
   const handleDelete = async () => {
     try {
       await deleteItem();
     } catch (error) {
-      toast({
-        title: "Error",
-        description: error.message,
-        variant: "error",
-      });
+      toast.error(`Failed to delete: ${(error as Error).message}`);
     }
   };
 
@@ -96,12 +95,10 @@ function DeleteButton() {
 ### Custom Duration
 
 ```typescript
-toast({
-  title: "Processing...",
-  duration: 5000, // 5 seconds
-});
+toast("Processing...", { duration: 5000 }); // 5 seconds
 ```
 
 ## Related
 
-- [SidebarLayout](../components/sidebar-layout.md) - Toast provider included
+- [Toast pattern](../patterns/interaction-toast.md) - When to use a toast and how to word it
+- [SidebarLayout](../components/sidebar-layout.md) - Renders the toaster

package/skills/app-shell-patterns/references/components/app-shell.md

@@ -259,7 +259,7 @@ const GlobalErrorBoundary = () => {
 First, define your context data type using module augmentation:
 
 ```typescript
-// types.d.ts
+// types.d.ts — `User` and `ApiClient` are your application's own types
 declare module "@tailor-platform/app-shell" {
   interface AppShellRegister {
     contextData: {
@@ -293,11 +293,11 @@ Access the context data in your components:
 import { useAppShell } from "@tailor-platform/app-shell";
 
 function MyComponent() {
-  const { context } = useAppShell();
+  const { contextData } = useAppShell();
 
   // Fully typed!
-  const user = context.currentUser;
-  const client = context.apiClient;
+  const user = contextData.currentUser;
+  const client = contextData.apiClient;
 
   return <div>Welcome, {user?.name}</div>;
 }

package/skills/app-shell-patterns/references/components/card.md

@@ -38,7 +38,7 @@ function BasicUsage() {
 | -------------- | ---------------------------------------------------------------- |
 | `Card.Root`    | Outer container. Renders a `<div>` with surface styling applied. |
 | `Card.Header`  | Top section with an optional title and description.              |
-| `Card.Content` | Body section with consistent horizontal and bottom padding.      |
+| `Card.Content` | Body section with consistent padding, or edge-to-edge.           |
 
 ## Card.Root Props
 
@@ -62,10 +62,82 @@ function BasicUsage() {
 
 `Card.Content` accepts all standard HTML `<div>` props.
 
-| Prop        | Type              | Default | Description            |
-| ----------- | ----------------- | ------- | ---------------------- |
-| `className` | `string`          | -       | Additional CSS classes |
-| `children`  | `React.ReactNode` | -       | Card body content      |
+| Prop        | Type                    | Default     | Description                                                                                    |
+| ----------- | ----------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `padding`   | `"default"` \| `"none"` | `"default"` | `"none"` renders the content edge-to-edge — see [Edge-to-edge content](#edge-to-edge-content). |
+| `className` | `string`                | -           | Additional CSS classes                                                                         |
+| `children`  | `React.ReactNode`       | -           | Card body content                                                                              |
+
+## Edge-to-edge content
+
+Use `padding="none"` when a `Table`, `DataTable` or divided list should meet the card's border instead of floating inside it:
+
+<example-preview name="edge-to-edge-table"></example-preview>
+
+```tsx
+function EdgeToEdgeTable() {
+  return (
+    <Card.Root>
+      <Card.Header title="Line items" />
+      <Card.Content padding="none">
+        <Table.Root>
+          <Table.Header>
+            <Table.Row>
+              <Table.Head>Item</Table.Head>
+              <Table.Head align="right">Qty</Table.Head>
+            </Table.Row>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Steel bracket</Table.Cell>
+              <Table.Cell align="right">12</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Hex bolt M8</Table.Cell>
+              <Table.Cell align="right">40</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Root>
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+Don't add padding back on the table. `Table.Head` and `Table.Cell` already inset their first and last cells by 24px, which lines the first column up with the card title.
+
+Edge-to-edge content also:
+
+- **Keeps row backgrounds inside the card's rounded corners.** A direct `Table` or `DataTable` child clips its row hover and pinned-cell backgrounds to the card's corners.
+- **Removes a nested `DataTable`'s own border**, so it doesn't draw a box inside the card. Its toolbar and footer stay as they are:
+
+```tsx
+<Card.Root>
+  <Card.Header title="Line items" />
+  <Card.Content padding="none">
+    <DataTable.Root value={table}>
+      <DataTable.Table />
+      <DataTable.Footer>
+        <DataTable.Pagination />
+      </DataTable.Footer>
+    </DataTable.Root>
+  </Card.Content>
+</Card.Root>
+```
+
+For a scrollable list, put the overflow on `Card.Content`. Rows supply their own `px-6`, and dividers run to the card edges:
+
+```tsx
+<Card.Content padding="none" className="max-h-60 overflow-y-auto">
+  <ul className="divide-y divide-border border-t border-border">
+    {items.map((item) => (
+      <li key={item.id} className="px-6 py-3">
+        {item.name}
+      </li>
+    ))}
+  </ul>
+</Card.Content>
+```
 
 ## Examples
 
@@ -96,8 +168,8 @@ function BasicUsage() {
       View all
     </Button>
   </Card.Header>
-  <Card.Content>
-    <Table>{/* ... */}</Table>
+  <Card.Content padding="none">
+    <Table.Root>{/* ... */}</Table.Root>
   </Card.Content>
 </Card.Root>
 ```