@tailor-platform/app-shell 1.15.0 → 1.16.0

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

@@ -0,0 +1,214 @@
+---
+title: useRouteError
+description: Hook to access error details in custom error boundaries
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-route-error.docs.outline.md — do not edit by hand. -->
+
+# useRouteError
+
+React Router hook to access error details within a custom error boundary component. Re-exported from `react-router` for convenience.
+
+## Signature
+
+```typescript
+const useRouteError: () => unknown;
+```
+
+## Return Value
+
+| Type      | Description                                                                  |
+| --------- | ---------------------------------------------------------------------------- |
+| `unknown` | The error that was thrown (typically `Error` object or route error response) |
+
+## Usage
+
+### Basic Error Boundary
+
+```typescript
+import { useRouteError } from "@tailor-platform/app-shell";
+
+function ErrorBoundary() {
+  const error = useRouteError();
+
+  const message = error instanceof Error
+    ? error.message
+    : "An unexpected error occurred";
+
+  return (
+    <div>
+      <h1>Something went wrong</h1>
+      <p>{message}</p>
+      <button onClick={() => window.location.reload()}>
+        Try Again
+      </button>
+    </div>
+  );
+}
+```
+
+### Use in Module Definition
+
+```typescript
+import { defineModule } from "@tailor-platform/app-shell";
+
+const myModule = defineModule({
+  path: "dashboard",
+  component: DashboardPage,
+  errorBoundary: <ErrorBoundary />,
+  resources: [...]
+});
+```
+
+### Use in Resource Definition
+
+```typescript
+const productsModule = defineModule({
+  path: "products",
+  component: ProductsPage,
+  resources: [
+    defineResource({
+      path: ":id",
+      component: ProductDetail,
+      errorBoundary: <ErrorBoundary />,
+    }),
+  ],
+});
+```
+
+### Advanced Error Handling
+
+```typescript
+import { isRouteErrorResponse, useRouteError } from "@tailor-platform/app-shell";
+
+function ErrorBoundary() {
+  const error = useRouteError();
+
+  // Handle route error responses (404, 500, etc.)
+  if (isRouteErrorResponse(error)) {
+    return (
+      <div>
+        <h1>{error.status} {error.statusText}</h1>
+        <p>{error.data}</p>
+      </div>
+    );
+  }
+
+  // Handle JavaScript errors
+  if (error instanceof Error) {
+    return (
+      <div>
+        <h1>Error</h1>
+        <p>{error.message}</p>
+        <pre>{error.stack}</pre>
+      </div>
+    );
+  }
+
+  // Handle unknown errors
+  return (
+    <div>
+      <h1>Unknown Error</h1>
+      <p>Something went wrong</p>
+    </div>
+  );
+}
+```
+
+### With Error Logging
+
+```typescript
+function ErrorBoundary() {
+  const error = useRouteError();
+
+  useEffect(() => {
+    // Log to error tracking service
+    console.error("Route error:", error);
+    // analytics.trackError(error);
+  }, [error]);
+
+  return (
+    <div>
+      <h1>Error</h1>
+      <p>We've been notified and will fix this soon.</p>
+    </div>
+  );
+}
+```
+
+### Custom Error Pages
+
+```typescript
+function ErrorBoundary() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error)) {
+    if (error.status === 404) {
+      return <NotFoundPage />;
+    }
+
+    if (error.status === 403) {
+      return <AccessDeniedPage />;
+    }
+
+    if (error.status === 500) {
+      return <ServerErrorPage />;
+    }
+  }
+
+  return <GenericErrorPage error={error} />;
+}
+```
+
+## Error Boundary Scope
+
+Error boundaries can be defined at different levels:
+
+```typescript
+// Module-level - catches errors in all resources
+defineModule({
+  path: "products",
+  errorBoundary: <ModuleErrorBoundary />,
+  resources: [...]
+})
+
+// Resource-level - catches errors in specific resource
+defineResource({
+  path: ":id",
+  errorBoundary: <ResourceErrorBoundary />,
+  component: ProductDetail
+})
+
+// Global - catches all unhandled errors
+<AppShell
+  modules={modules}
+  errorBoundary={<GlobalErrorBoundary />}
+/>
+```
+
+## Important Notes
+
+### Always Import from AppShell
+
+```typescript
+// ✅ Correct
+import { useRouteError } from "@tailor-platform/app-shell";
+
+// ❌ Wrong - won't work with AppShell's router
+import { useRouteError } from "react-router";
+```
+
+### Error Boundaries Don't Catch
+
+Error boundaries do **not** catch:
+
+- Errors in event handlers (use try/catch)
+- Async errors (use try/catch with async/await)
+- Server-side rendering errors
+- Errors thrown in the error boundary itself
+
+## Related
+
+- [defineModule](./define-module.md) - Module-level error boundaries
+- [defineResource](./define-resource.md) - Resource-level error boundaries
+- [AppShell Component](../components/app-shell.md) - Global error boundary

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

@@ -0,0 +1,108 @@
+---
+title: useTheme
+description: Hook for accessing and controlling theme (light/dark mode)
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-theme.docs.outline.md — do not edit by hand. -->
+
+# useTheme
+
+React hook to access and control the current theme (light/dark mode).
+
+## Signature
+
+```typescript
+import { type ColorTheme, type ResolvedColorTheme } from "@tailor-platform/app-shell";
+
+const useTheme: () => {
+  theme: ColorTheme;
+  resolvedTheme: ResolvedColorTheme;
+  setTheme: (theme: ColorTheme) => void;
+};
+```
+
+## Return Value
+
+### `theme`
+
+- **Type:** `ColorTheme` (`"light" | "dark" | "system"`)
+- **Description:** Current user preference. `"system"` means the OS setting is followed.
+
+### `resolvedTheme`
+
+- **Type:** `ResolvedColorTheme` (`"light" | "dark"`)
+- **Description:** Concrete color mode after resolving `"system"`. Always `"light"` or `"dark"`.
+
+### `setTheme()`
+
+- **Type:** `(theme: ColorTheme) => void`
+- **Description:** Set the color theme. Persisted to `localStorage` under the key `appshell-ui-theme`.
+
+## Usage
+
+### Display Current Theme
+
+```typescript
+import { useTheme } from "@tailor-platform/app-shell";
+
+function ThemeDisplay() {
+  const { theme } = useTheme();
+
+  return <div>Current theme: {theme}</div>;
+}
+```
+
+### Theme Toggle
+
+```typescript
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+
+  const toggleTheme = () => {
+    setTheme(theme === "dark" ? "light" : "dark");
+  };
+
+  return <button onClick={toggleTheme}>Toggle Theme</button>;
+}
+```
+
+### Theme Selector
+
+```typescript
+function ThemeSelector() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="system">System</option>
+    </select>
+  );
+}
+```
+
+### Conditional Rendering
+
+Use `resolvedTheme` when you need a concrete `"light"` or `"dark"` value — it already accounts for `"system"`:
+
+```typescript
+function Logo() {
+  const { resolvedTheme } = useTheme();
+
+  return (
+    <img
+      src={resolvedTheme === "dark" ? "/logo-dark.png" : "/logo-light.png"}
+      alt="Logo"
+    />
+  );
+}
+```
+
+## Theme Persistence
+
+Theme preference is automatically saved to localStorage and restored on page load.
+
+## Related
+
+- [Styling & Theming](../concepts/styling-theming.md) - Theme customization

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

@@ -0,0 +1,80 @@
+---
+title: useTimeZone
+description: Hook to access the configured IANA timezone from AppShell context
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-time-zone.docs.outline.md — do not edit by hand. -->
+
+# useTimeZone
+
+React hook that returns a `TimeZone` object for the timezone configured on `AppShell`. Falls back to the user's local timezone when no timezone is configured.
+
+Date/time components (`DateField`, `DatePicker`, `Calendar`) consume this hook automatically — use it when you need the same timezone in custom components.
+
+## Signature
+
+```typescript
+const useTimeZone: () => TimeZone;
+```
+
+## Return Value
+
+A `TimeZone` object with the following properties:
+
+### `value`
+
+- **Type:** `string`
+- **Description:** Raw IANA timezone identifier (e.g. `"America/Los_Angeles"`). Returns the value of AppShell's `timeZone` prop when configured, or the result of `getLocalTimeZone()` (the user's local timezone) when not.
+
+### `today()`
+
+- **Type:** `() => CalendarDate`
+- **Description:** Returns today's date in this timezone.
+
+### `now()`
+
+- **Type:** `() => ZonedDateTime`
+- **Description:** Returns the current instant in this timezone.
+
+## Usage
+
+```typescript
+import { useTimeZone } from "@tailor-platform/app-shell";
+
+function TodayDisplay() {
+  const timeZone = useTimeZone();
+  const todayDate = timeZone.today();
+
+  return <span>Today: {todayDate.toString()}</span>;
+}
+```
+
+### Current timestamp
+
+```typescript
+import { useTimeZone } from "@tailor-platform/app-shell";
+
+function CurrentTimestamp() {
+  const timeZone = useTimeZone();
+
+  return <span>{timeZone.now().toString()}</span>;
+}
+```
+
+### Accessing the raw IANA string
+
+```typescript
+import { useTimeZone } from "@tailor-platform/app-shell";
+
+function TimeZoneLabel() {
+  const { value } = useTimeZone();
+
+  return <span>Timezone: {value}</span>;
+}
+```
+
+## Related
+
+- [AppShell](../components/app-shell.md) — configure timezone via the `timeZone` prop
+- [useResolvedLocale](./use-resolved-locale.md) — access the locale for formatting
+- [DatePicker](../components/date-picker.md) — date input components that consume this timezone automatically

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

@@ -0,0 +1,107 @@
+---
+title: useToast
+description: Hook for displaying toast notifications
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-toast.docs.outline.md — do not edit by hand. -->
+
+# useToast
+
+React hook to display toast notifications for user feedback.
+
+## Signature
+
+```typescript
+const useToast: () => {
+  toast: (props: ToastProps) => void;
+};
+```
+
+## Parameters
+
+### ToastProps
+
+```typescript
+{
+  title?: string;
+  description?: string;
+  variant?: "default" | "success" | "error" | "warning";
+  duration?: number; // milliseconds
+}
+```
+
+## Usage
+
+### Basic Toast
+
+```typescript
+import { useToast } from "@tailor-platform/app-shell";
+
+function SaveButton() {
+  const { toast } = useToast();
+
+  const handleSave = () => {
+    // Save logic...
+    toast({
+      title: "Saved!",
+      description: "Your changes have been saved.",
+    });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+### Success Toast
+
+```typescript
+function CreateButton() {
+  const { toast } = useToast();
+
+  const handleCreate = async () => {
+    await createItem();
+    toast({
+      title: "Created",
+      description: "Item created successfully.",
+      variant: "success",
+    });
+  };
+
+  return <button onClick={handleCreate}>Create</button>;
+}
+```
+
+### Error Toast
+
+```typescript
+function DeleteButton() {
+  const { toast } = useToast();
+
+  const handleDelete = async () => {
+    try {
+      await deleteItem();
+    } catch (error) {
+      toast({
+        title: "Error",
+        description: error.message,
+        variant: "error",
+      });
+    }
+  };
+
+  return <button onClick={handleDelete}>Delete</button>;
+}
+```
+
+### Custom Duration
+
+```typescript
+toast({
+  title: "Processing...",
+  duration: 5000, // 5 seconds
+});
+```
+
+## Related
+
+- [SidebarLayout](../components/sidebar-layout.md) - Toast provider included

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

@@ -0,0 +1,168 @@
+---
+title: ActionPanel
+description: Display a title and a vertical list of actions with per-row loading and disabled states
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/action-panel.docs.outline.md — do not edit by hand. -->
+
+# ActionPanel
+
+`ActionPanel` is a presentational card component for rendering a vertical list of actions (icon + label). It is designed for ERP detail pages and side panels where available actions are often backend-driven.
+
+## Import
+
+```tsx
+import { ActionPanel } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+<ActionPanel
+  title="Actions"
+  actions={[
+    {
+      key: "create-invoice",
+      label: "Create new sales invoice",
+      icon: <ReceiptIcon />,
+      onClick: () => openCreateInvoiceModal(),
+    },
+    {
+      key: "view-docs",
+      label: "View documentation",
+      icon: <ExternalLinkIcon />,
+      onClick: () => window.open("/docs", "_blank", "noopener,noreferrer"),
+    },
+  ]}
+/>
+```
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### ActionPanelProps
+
+| Prop         | Type           | Default | Description                                   |
+| ------------ | -------------- | ------- | --------------------------------------------- |
+| `actions`    | `ActionItem[]` | -       | List of actions to render                     |
+| `className?` | `string`       | -       | Additional CSS classes for the card container |
+| `title`      | `string`       | -       | Card title                                    |
+
+## Exports
+
+- `ActionPanel` — function
+- `ActionPanelProps` — interface
+
+### ActionItem
+
+| Property   | Type                          | Default      | Description                                                           |
+| ---------- | ----------------------------- | ------------ | --------------------------------------------------------------------- |
+| `key`      | `string`                      | **Required** | Unique key for stable rendering                                       |
+| `label`    | `string`                      | **Required** | Action label shown to users                                           |
+| `icon`     | `ReactNode`                   | **Required** | Icon rendered in a fixed 16px slot                                    |
+| `onClick`  | `() => void \| Promise<void>` | -            | Click handler for the action                                          |
+| `disabled` | `boolean`                     | `false`      | Disables interaction and applies disabled styling                     |
+| `loading`  | `boolean`                     | `false`      | Shows spinner, disables interaction, sets busy UI                     |
+| `variant`  | `"default" \| "destructive"`  | `"default"`  | Visual variant; use `"destructive"` for dangerous actions like delete |
+
+## Behavior
+
+- Rows are rendered as `<button type="button">` elements.
+- `disabled` or `loading` makes the row non-interactive.
+- When `loading` is `true`, the icon slot renders a spinner without shifting layout.
+- Empty actions show a built-in fallback message: `No actions available`.
+
+## With Loading State
+
+Use parent state to control which row is loading:
+
+```tsx
+const [loadingKey, setLoadingKey] = useState<string | null>(null);
+
+const handleConfirm = async () => {
+  setLoadingKey("confirm");
+  try {
+    await confirmOrder(orderId);
+  } finally {
+    setLoadingKey(null);
+  }
+};
+
+<ActionPanel
+  title="Actions"
+  actions={[
+    {
+      key: "confirm",
+      label: "Confirm order",
+      icon: <CheckIcon />,
+      onClick: handleConfirm,
+      loading: loadingKey === "confirm",
+    },
+  ]}
+/>;
+```
+
+## CommandPalette Integration
+
+`ActionPanel` automatically registers its enabled actions to the CommandPalette. Actions that are not `disabled`, not `loading`, and have an `onClick` handler are registered under the panel's `title` as the group name. Registration is cleaned up when the component unmounts.
+
+This means users can discover and trigger any visible ActionPanel action via `Cmd+K` / `Ctrl+K` without any additional setup.
+
+```tsx
+// Actions in this panel will automatically appear in the CommandPalette
+<ActionPanel
+  title="Order Actions"
+  actions={[
+    { key: "confirm", label: "Confirm order", icon: <CheckIcon />, onClick: handleConfirm },
+    { key: "cancel", label: "Cancel order", icon: <XIcon />, onClick: handleCancel },
+  ]}
+/>
+```
+
+> **Note:** `ActionPanel` must be rendered inside `AppShell` (which provides the required `CommandPaletteProvider`). Rendering it outside that tree will throw.
+
+## Backend-Driven Pattern
+
+In ERP apps, the backend often decides which actions are available for a document. A common setup:
+
+1. Backend returns document data and available action keys.
+2. Frontend maps each key to a registry entry (`label`, `icon`, `execute`).
+3. Page builds `ActionItem[]` and wires `onClick`.
+4. Page controls `loading` per key and passes it to `ActionPanel`.
+
+This keeps `ActionPanel` simple and reusable across entity types.
+
+## Accessibility
+
+- Action list uses `role="list"` and each row wrapper uses `role="listitem"`.
+- Buttons are keyboard accessible and include focus-visible states.
+- Loading rows set `aria-busy="true"`.
+- Disabled rows set `aria-disabled="true"` and native `disabled`.
+
+## Styling
+
+The component is styled with the library's internal `astw:`-prefixed utilities:
+
+- Full width card
+- Compact spacing for dense action lists
+- Fixed icon slot for stable alignment
+- Inline spinner for loading state
+
+Use `className` on `ActionPanel` for card-level properties it does not set itself. Write **plain** utilities — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
+
+## Examples in This Repo
+
+- `examples/app-module` includes an **Action Panel Demo** resource.
+- The **2 Columns** layout page also includes an ActionPanel with loading behavior.
+
+## Related Components
+
+- [Layout](./layout.md) - Compose page-level column layouts
+- [DescriptionCard](./description-card.md) - Display structured record fields
+- [Badge](./badge.md) - Show statuses and semantic labels
+
+## Related Concepts
+
+- [Modules and Resources](../concepts/modules-and-resources.md) - Organize pages and routes
+- [Routing and Navigation](../concepts/routing-navigation.md) - Navigation patterns