@tailor-platform/app-shell 1.15.0 → 1.17.0

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

@@ -0,0 +1,218 @@
+---
+title: useParams
+description: Hook to access dynamic route parameters
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/router/use-params.docs.outline.md — do not edit by hand. -->
+
+# useParams
+
+React Router hook to access dynamic route parameters from the URL. Re-exported from `react-router` for convenience.
+
+## Signature
+
+```typescript
+const useParams: <T extends Record<string, string>>() => T;
+```
+
+## Usage
+
+### Access Single Parameter
+
+```typescript
+import { useParams } from "@tailor-platform/app-shell";
+
+// Route: /products/:id
+function ProductDetail() {
+  const { id } = useParams();
+
+  return <div>Product ID: {id}</div>;
+}
+```
+
+### Multiple Parameters
+
+```typescript
+// Route: /categories/:category/products/:id
+function ProductInCategory() {
+  const { category, id } = useParams();
+
+  return (
+    <div>
+      Category: {category}
+      <br />
+      Product ID: {id}
+    </div>
+  );
+}
+```
+
+### With Data Fetching
+
+```typescript
+function OrderDetail() {
+  const { id } = useParams();
+  const [order, setOrder] = useState(null);
+
+  useEffect(() => {
+    fetch(`/api/orders/${id}`)
+      .then(r => r.json())
+      .then(setOrder);
+  }, [id]);
+
+  return <div>Order #{id}</div>;
+}
+```
+
+### TypeScript with Type Safety
+
+```typescript
+import { useParams } from "@tailor-platform/app-shell";
+
+interface ProductParams {
+  id: string;
+}
+
+function ProductDetail() {
+  const { id } = useParams<ProductParams>();
+  //    ^ type: string
+
+  return <div>Product {id}</div>;
+}
+```
+
+## Route Definition
+
+Parameters are defined in `defineResource` using `:param` syntax:
+
+```typescript
+import { defineModule, defineResource } from "@tailor-platform/app-shell";
+
+const productsModule = defineModule({
+  path: "products",
+  component: ProductsList,
+  resources: [
+    defineResource({
+      path: ":id", // ← Dynamic parameter
+      component: () => {
+        const { id } = useParams(); // Access here
+        return <div>Product {id}</div>;
+      },
+    }),
+  ],
+});
+```
+
+### Nested Parameters
+
+```typescript
+const ordersModule = defineModule({
+  path: "orders",
+  component: OrdersList,
+  resources: [
+    defineResource({
+      path: ":orderId",
+      component: OrderDetail,
+      subResources: [
+        defineResource({
+          path: "items/:itemId",
+          component: () => {
+            const { orderId, itemId } = useParams();
+            return <div>Order {orderId}, Item {itemId}</div>;
+          },
+        }),
+      ],
+    }),
+  ],
+});
+
+// URL: /orders/123/items/456
+// useParams() returns: { orderId: "123", itemId: "456" }
+```
+
+## Important Notes
+
+### Always Import from AppShell
+
+```typescript
+// ✅ Correct
+import { useParams } from "@tailor-platform/app-shell";
+
+// ❌ Wrong - won't work with AppShell's router
+import { useParams } from "react-router";
+```
+
+### Parameters are Always Strings
+
+```typescript
+const { id } = useParams();
+// id is always a string, even for numeric IDs
+
+// Convert if needed:
+const numericId = parseInt(id, 10);
+```
+
+### Optional Parameters
+
+For optional parameters, check for undefined:
+
+```typescript
+const { filter } = useParams();
+
+if (filter) {
+  // Filter is provided
+} else {
+  // Filter is optional and not provided
+}
+```
+
+## Examples
+
+### Edit Page
+
+```typescript
+// Route: /products/:id/edit
+function ProductEdit() {
+  const { id } = useParams();
+  const [product, setProduct] = useState(null);
+
+  useEffect(() => {
+    loadProduct(id).then(setProduct);
+  }, [id]);
+
+  return (
+    <form>
+      <h1>Edit Product {id}</h1>
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+### Delete Confirmation
+
+```typescript
+function DeleteConfirmation() {
+  const { id } = useParams();
+  const navigate = useNavigate();
+
+  const handleDelete = async () => {
+    await deleteProduct(id);
+    navigate("/products");
+  };
+
+  return (
+    <div>
+      <p>Delete product {id}?</p>
+      <button onClick={handleDelete}>Confirm</button>
+    </div>
+  );
+}
+```
+
+## Related
+
+- [useNavigate](./use-navigate.md) - Programmatic navigation
+- [useLocation](./use-location.md) - Access current location
+- [defineResource](../define-resource.md) - Define routes with parameters
+- [Routing & Navigation](../../concepts/routing-navigation.md) - Navigation guide

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

@@ -0,0 +1,110 @@
+---
+title: useAIChat
+description: Simple text-only chat hook for AI Gateway
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-ai-chat.docs.outline.md — do not edit by hand. -->
+
+# useAIChat
+
+React hook for simple text-only chat on top of `createAIGatewayClient`.
+
+## Signature
+
+```typescript
+const useAIChat: (config: { client: AIGatewayClient; model: string }) => {
+  messages: AIChatMessage[];
+  status: "ready" | "submitted" | "streaming" | "error";
+  error?: Error;
+  sendMessage: (message: string) => Promise<boolean>;
+  stop: () => void;
+};
+```
+
+## Return Value
+
+### `messages`
+
+```typescript
+interface AIChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+```
+
+### `status`
+
+- **Type:** `"ready" | "submitted" | "streaming" | "error"`
+- **Description:** Current request state
+
+### `error`
+
+- **Type:** `Error | undefined`
+- **Description:** Last request error, if any
+
+### `sendMessage()`
+
+- **Type:** `(message: string) => Promise<boolean>`
+- **Description:** Appends a user message and streams the assistant response
+- **Returns:** `true` when the request completes successfully, `false` when the call is ignored, stopped, or fails
+
+### `stop()`
+
+- **Type:** `() => void`
+- **Description:** Aborts the current request if one is in progress
+
+## Usage
+
+```tsx
+import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+
+const authClient = createAuthClient({
+  clientId: "your-client-id",
+  appUri: "https://xyz.erp.dev",
+});
+
+const aiClient = createAIGatewayClient({
+  gatewayUri: "https://your-ai-gateway.example.com",
+  authClient,
+});
+
+export function ChatScreen() {
+  const { messages, sendMessage, status, stop, error } = useAIChat({
+    client: aiClient,
+    model: "gpt-5-mini",
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+
+      <button
+        onClick={() => void sendMessage("Hello")}
+        disabled={status === "submitted" || status === "streaming"}
+      >
+        Send
+      </button>
+      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
+        Stop
+      </button>
+      {error ? <div>{error.message}</div> : null}
+    </div>
+  );
+}
+```
+
+## Notes
+
+- AppShell chooses the appropriate AI Gateway transport automatically
+- The hook is intentionally text-only
+- System prompts and custom history shaping should use the low-level client directly
+- `stop()` keeps any already-streamed assistant text and ignores late chunks from the stopped request
+
+## Related
+
+- [createAIGatewayClient](./create-ai-gateway-client.md)

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

@@ -0,0 +1,132 @@
+---
+title: useAppShellConfig
+description: Hook to access AppShell configuration data
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-app-shell-config.docs.outline.md — do not edit by hand. -->
+
+# useAppShellConfig
+
+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: () => {
+  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                                         |
+| `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
+
+### Display App Info
+
+```typescript
+import { useAppShellConfig } from "@tailor-platform/app-shell";
+
+function AppInfo() {
+  const { title, configurations } = useAppShellConfig();
+
+  return (
+    <div>
+      <h2>{title}</h2>
+      <p>Base: {configurations.basePath}</p>
+    </div>
+  );
+}
+```
+
+### 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 { configurations } = useAppShellConfig();
+
+  return (
+    <ul>
+      {configurations.modules.map((module) => (
+        <li key={module.path}>{module.path}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Settings Resources
+
+```typescript
+function SettingsMenu() {
+  const { configurations } = useAppShellConfig();
+
+  return (
+    <div>
+      <h3>Settings</h3>
+      {configurations.settingsResources.map((resource) => (
+        <button key={resource.path}>{resource.path}</button>
+      ))}
+    </div>
+  );
+}
+```
+
+## When to Use
+
+Use `useAppShellConfig` when you only need configuration data:
+
+```typescript
+// ✅ Good - subscribes to configuration only
+const { configurations } = useAppShellConfig();
+
+// ❌ Overkill - useAppShell also subscribes to contextData changes
+const { configurations } = useAppShell();
+```
+
+## Comparison with Other Hooks
+
+| 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
+
+- [useAppShell](./use-app-shell.md) - Full context access
+- [useAppShellData](./use-app-shell-data.md) - Context data only
+- [AppShell Component](../components/app-shell.md) - Root component

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

@@ -0,0 +1,150 @@
+---
+title: useAppShellData
+description: Hook to access custom context data passed to AppShell
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-app-shell-data.docs.outline.md — do not edit by hand. -->
+
+# useAppShellData
+
+React hook to access only the custom context data. This is a lighter alternative to `useAppShell` when you only need the contextData.
+
+## Signature
+
+```typescript
+const useAppShellData: () => {
+  contextData: ContextData;
+};
+```
+
+## Return Value
+
+| Property      | Type          | Description                                                               |
+| ------------- | ------------- | ------------------------------------------------------------------------- |
+| `contextData` | `ContextData` | Custom context data passed to AppShell (type-safe via `AppShellRegister`) |
+
+## Usage
+
+### Basic Access
+
+```typescript
+import { useAppShellData } from "@tailor-platform/app-shell";
+
+function UserProfile() {
+  const { contextData } = useAppShellData();
+
+  return (
+    <div>
+      <p>Welcome, {contextData.currentUser?.name}</p>
+      <p>Role: {contextData.currentUser?.role}</p>
+    </div>
+  );
+}
+```
+
+### Display User Info
+
+```typescript
+function UserInfo() {
+  const { contextData } = useAppShellData();
+
+  if (!contextData.currentUser) {
+    return <div>Not logged in</div>;
+  }
+
+  return (
+    <div>
+      <h2>{contextData.currentUser.name}</h2>
+      <p>{contextData.currentUser.email}</p>
+    </div>
+  );
+}
+```
+
+### Check Permissions
+
+```typescript
+function AdminPanel() {
+  const { contextData } = useAppShellData();
+  const canManageUsers = contextData.permissions.includes("users:manage");
+
+  if (!canManageUsers) {
+    return <AccessDenied />;
+  }
+
+  return <UserManagement />;
+}
+```
+
+### Feature Flags
+
+```typescript
+function BetaFeature() {
+  const { contextData } = useAppShellData();
+
+  if (!contextData.featureFlags?.newEditor) {
+    return <LegacyEditor />;
+  }
+
+  return <NewEditor />;
+}
+```
+
+## Type Safety
+
+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: {
+      currentUser: User | null;
+      permissions: string[];
+      tenantId: string;
+      featureFlags: {
+        newEditor: boolean;
+        betaDashboard: boolean;
+      };
+    };
+  }
+}
+```
+
+Now `useAppShellData()` returns fully typed data:
+
+```typescript
+const { contextData } = useAppShellData();
+contextData.currentUser; // Type: User | null
+contextData.permissions; // Type: string[]
+contextData.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
+```
+
+## When to Use
+
+Use `useAppShellData` when you only need context data:
+
+```typescript
+// ✅ Good - subscribes to context data only
+const { contextData } = useAppShellData();
+
+// ❌ Overkill - useAppShell also subscribes to configuration changes
+const { contextData } = useAppShell();
+```
+
+## Comparison with Other Hooks
+
+| 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
+
+- [useAppShell](./use-app-shell.md) - Full context access
+- [useAppShellConfig](./use-app-shell-config.md) - Configuration only
+- [AppShell Component](../components/app-shell.md) - Root component
+- [Guards Overview](./guards/overview.md) - Using context in guards