@tailor-platform/app-shell 1.15.0 → 1.17.0

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

@@ -0,0 +1,150 @@
+---
+title: useAppShell
+description: Hook to access AppShell context data and configuration
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-app-shell.docs.outline.md — do not edit by hand. -->
+
+# useAppShell
+
+React hook to access AppShell context data and configuration within your components.
+
+## Signature
+
+```typescript
+const useAppShell: () => {
+  contextData: ContextData;
+  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
+
+### `contextData`
+
+- **Type:** `ContextData`
+- **Description:** Custom context data passed to AppShell. Same as the `contextData` prop.
+
+### `configurations`
+
+- **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
+
+### Basic Access
+
+```typescript
+import { useAppShell } from "@tailor-platform/app-shell";
+
+function MyComponent() {
+  const { contextData } = useAppShell();
+
+  return <div>Welcome, {contextData.currentUser?.name}</div>;
+}
+```
+
+### Access Configuration
+
+```typescript
+function LocaleDisplay() {
+  const { configurations } = useAppShell();
+
+  return <div>Current locale: {configurations.locale}</div>;
+}
+```
+
+## Context Data
+
+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;
+    };
+  }
+}
+
+// App.tsx
+<AppShell
+  modules={modules}
+  contextData={{
+    currentUser,
+    permissions,
+    tenantId,
+  }}
+/>
+
+// MyComponent.tsx
+const { contextData } = useAppShell();
+contextData.currentUser  // Fully typed!
+contextData.permissions  // Fully typed!
+```
+
+## Examples
+
+### Display User Info
+
+```typescript
+function UserInfo() {
+  const { contextData } = useAppShell();
+
+  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 DeleteButton() {
+  const { contextData } = useAppShell();
+  const canDelete = contextData.permissions.includes("users:delete");
+
+  if (!canDelete) {
+    return null;
+  }
+
+  return <Button variant="destructive">Delete</Button>;
+}
+```
+
+## 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-auth.md

@@ -0,0 +1,145 @@
+---
+title: useAuth
+description: Hook for accessing authentication state and methods
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-auth.docs.outline.md — do not edit by hand. -->
+
+# useAuth
+
+React hook to access authentication state and methods when using `AuthProvider`.
+
+## Signature
+
+```typescript
+const useAuth: () => {
+  error: string | null;
+  isAuthenticated: boolean;
+  isReady: boolean;
+  login: () => Promise<void>;
+  logout: () => Promise<void>;
+  checkAuthStatus: () => Promise<AuthState>;
+};
+```
+
+## Return Value
+
+### `error`
+
+- **Type:** `string | null`
+- **Description:** Error message if authentication failed
+
+### `isAuthenticated`
+
+- **Type:** `boolean`
+- **Description:** Whether the user is currently authenticated
+
+### `isReady`
+
+- **Type:** `boolean`
+- **Description:** Whether the initial auth check has completed. Always check this before rendering authenticated content to avoid flashing unauthenticated state.
+
+### `login()`
+
+- **Type:** `() => Promise<void>`
+- **Description:** Initiates the login process. Redirects to Tailor Platform authentication page.
+
+### `logout()`
+
+- **Type:** `() => Promise<void>`
+- **Description:** Logs out the current user. Clears tokens and session.
+
+### `checkAuthStatus()`
+
+- **Type:** `() => Promise<AuthState>`
+- **Description:** Checks current auth status. Makes network request to verify and refresh tokens if needed.
+
+## Usage
+
+### Basic Authentication Flow
+
+```typescript
+import { useAuth } from "@tailor-platform/app-shell";
+
+function MyComponent() {
+  const { isAuthenticated, isReady, login, logout } = useAuth();
+
+  if (!isReady) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    return <button onClick={login}>Log In</button>;
+  }
+
+  return (
+    <div>
+      <p>You are logged in!</p>
+      <button onClick={logout}>Log Out</button>
+    </div>
+  );
+}
+```
+
+### Protected Content
+
+```typescript
+function ProtectedPage() {
+  const { isAuthenticated, isReady } = useAuth();
+
+  if (!isReady) {
+    return <Spinner />;
+  }
+
+  if (!isAuthenticated) {
+    return <LoginPrompt />;
+  }
+
+  return <SecureContent />;
+}
+```
+
+### Handle Auth Errors
+
+```typescript
+function AuthStatus() {
+  const { isAuthenticated, error, login } = useAuth();
+
+  if (error) {
+    return (
+      <div>
+        <p>Authentication failed: {error}</p>
+        <button onClick={login}>Retry</button>
+      </div>
+    );
+  }
+
+  return <div>Status: {isAuthenticated ? "Logged in" : "Logged out"}</div>;
+}
+```
+
+## With AuthProvider
+
+```typescript
+import { AuthProvider, AppShell, useAuth } from "@tailor-platform/app-shell";
+
+function App() {
+  return (
+    <AuthProvider
+      apiEndpoint="https://api.tailor.tech"
+      clientId="your-client-id"
+      redirectUri="http://localhost:3000/callback"
+      autoLogin={true}
+    >
+      <AppShell modules={modules}>
+        <SidebarLayout />
+      </AppShell>
+    </AuthProvider>
+  );
+}
+```
+
+## Related
+
+- [Authentication Concept](../concepts/authentication.md) - Authentication guide
+- [AuthProvider](../components/app-shell.md) - Auth provider setup

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

@@ -0,0 +1,74 @@
+---
+title: useOverrideBreadcrumb
+description: Hook for dynamically overriding breadcrumb titles from within page components
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-override-breadcrumb.docs.outline.md — do not edit by hand. -->
+
+# useOverrideBreadcrumb
+
+React hook to dynamically override the breadcrumb title for the current page. Useful for displaying data-driven titles (e.g., record names fetched from an API) instead of static route-based titles.
+
+## Signature
+
+```typescript
+function useOverrideBreadcrumb(title: string | undefined): void;
+```
+
+## Parameters
+
+### `title`
+
+- **Type:** `string | undefined`
+- **Required:** Yes
+- **Description:** The title to display in the breadcrumb for the current path. When `undefined`, any previous override is removed and the default title (from `defineResource`) is restored.
+
+## Usage
+
+### With `defineResource`
+
+```tsx
+import { useOverrideBreadcrumb } from "@tailor-platform/app-shell";
+
+defineResource({
+  path: ":id",
+  component: () => {
+    const { id } = useParams();
+    const { data } = useQuery(GET_ORDER, { variables: { id } });
+
+    // Update breadcrumb with the order name
+    useOverrideBreadcrumb(data?.order?.name);
+
+    return <OrderDetail />;
+  },
+});
+```
+
+### With file-based routing
+
+```tsx
+import { useOverrideBreadcrumb, useParams } from "@tailor-platform/app-shell";
+
+const OrderDetailPage = () => {
+  const { id } = useParams();
+  const { data } = useQuery(GET_ORDER, { variables: { id } });
+
+  // Update breadcrumb with the order name
+  useOverrideBreadcrumb(data?.order?.name);
+
+  return <div>...</div>;
+};
+
+export default OrderDetailPage;
+```
+
+## Notes
+
+- The hook updates reactively — pass the result of a data-fetching query directly and the breadcrumb updates when the data resolves.
+- When `title` is `undefined` (e.g., while data is loading), the override is cleared and the default title is shown.
+- The override is automatically cleaned up when the component unmounts.
+
+## Related
+
+- [defineResource](./define-resource.md) - Define routes and their default breadcrumb titles
+- [Routing and Navigation](../concepts/routing-navigation.md) - Overview of breadcrumb behavior

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

@@ -0,0 +1,96 @@
+---
+title: usePageMeta
+description: Hook to resolve page metadata from route path
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-page-meta.docs.outline.md — do not edit by hand. -->
+
+# usePageMeta
+
+React hook to resolve page metadata (title, icon) from a route path.
+
+## Signature
+
+```typescript
+const usePageMeta: (path: string) => {
+  title: string;
+  icon?: React.ReactNode;
+} | null;
+```
+
+## Parameters
+
+### `path`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Route path to look up metadata for
+
+## Return Value
+
+Returns an object with `title` and optional `icon`, or `null` when the path is external or does not match any AppShell route.
+
+## Usage
+
+### Resolve Title and Icon
+
+```typescript
+import { usePageMeta } from "@tailor-platform/app-shell";
+
+function NavigationItem({ path }: { path: string }) {
+  const meta = usePageMeta(path);
+
+  if (!meta) {
+    return null;
+  }
+
+  return (
+    <div>
+      {meta.icon}
+      <span>{meta.title}</span>
+    </div>
+  );
+}
+```
+
+### Custom Link Component
+
+```typescript
+function CustomLink({ to }: { to: string }) {
+  const meta = usePageMeta(to);
+
+  return (
+    <a href={to}>
+      {meta?.icon}
+      {meta?.title || to}
+    </a>
+  );
+}
+```
+
+### Breadcrumb Builder
+
+```typescript
+function Breadcrumb({ paths }: { paths: string[] }) {
+  return (
+    <div>
+      {paths.map((path) => {
+        const meta = usePageMeta(path);
+        return <span key={path}>{meta?.title}</span>;
+      })}
+    </div>
+  );
+}
+```
+
+## Notes
+
+- Used internally by `SidebarItem` to auto-resolve titles and icons
+- Returns `null` for external URLs (`http://...` / `https://...`) and for paths that do not match any defined route
+- Resolves from module and resource `meta` properties
+- Prefers literal routes before dynamic siblings, so `/users/new` resolves that route's metadata instead of `/users/:id`
+
+## Related
+
+- [SidebarItem](../components/sidebar-item.md) - Uses usePageMeta internally
+- [defineModule](./define-module.md) - Define meta.title and meta.icon

package/skills/app-shell-patterns/references/api/use-register-command-palette-actions.md

@@ -0,0 +1,90 @@
+---
+title: useRegisterCommandPaletteActions
+description: Hook for registering contextual page actions into the CommandPalette
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-register-command-palette-actions.docs.outline.md — do not edit by hand. -->
+
+# useRegisterCommandPaletteActions
+
+React hook that declaratively registers page-level actions into the CommandPalette's **Actions** section. Actions are searchable and triggerable via the `Cmd+K` / `Ctrl+K` shortcut. They are automatically unregistered when the calling component unmounts.
+
+## Import
+
+```tsx
+import {
+  useRegisterCommandPaletteActions,
+  type CommandPaletteAction,
+} from "@tailor-platform/app-shell";
+```
+
+## Signature
+
+```typescript
+function useRegisterCommandPaletteActions(group: string, actions: CommandPaletteAction[]): void;
+```
+
+## Parameters
+
+| Parameter | Type                     | Description                                               |
+| --------- | ------------------------ | --------------------------------------------------------- |
+| `group`   | `string`                 | Display group name shown in the palette for these actions |
+| `actions` | `CommandPaletteAction[]` | List of actions to register                               |
+
+## `CommandPaletteAction`
+
+```typescript
+type CommandPaletteAction = {
+  key: string;
+  label: string;
+  icon?: ReactNode;
+  group?: string;
+  onSelect: () => void | Promise<void>;
+};
+```
+
+| Property   | Type                          | Description                                                                   |
+| ---------- | ----------------------------- | ----------------------------------------------------------------------------- |
+| `key`      | `string`                      | Unique key for React reconciliation                                           |
+| `label`    | `string`                      | Visible label shown in the palette; also used for search matching             |
+| `icon`     | `ReactNode`                   | Optional icon rendered next to the label                                      |
+| `group`    | `string`                      | Optional group override; defaults to the `group` parameter passed to the hook |
+| `onSelect` | `() => void \| Promise<void>` | Callback invoked when the user selects the action                             |
+
+## Usage
+
+```tsx
+import { useRegisterCommandPaletteActions } from "@tailor-platform/app-shell";
+
+function OrderDetailPage() {
+  const [loading, setLoading] = useState(false);
+
+  const handleConfirm = async () => {
+    setLoading(true);
+    try {
+      await confirmOrder(orderId);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useRegisterCommandPaletteActions("Order Actions", [
+    { key: "confirm", label: "Confirm order", onSelect: handleConfirm },
+    { key: "cancel", label: "Cancel order", icon: <XIcon />, onSelect: handleCancel },
+  ]);
+
+  return <div>{/* page content */}</div>;
+}
+```
+
+## Behavior
+
+- Actions are registered while the component is mounted and removed on unmount.
+- Re-rendering with a new `actions` array replaces the previously registered set.
+- `icon` changes alone do not trigger re-registration. If you need to reflect a dynamic icon update, also change the action's `key` or `label`.
+- The hook requires `CommandPaletteProvider`, which is mounted automatically by `AppShell`.
+
+## Related
+
+- [CommandPalette](../components/command-palette.md) — Keyboard-driven navigation and action palette
+- [ActionPanel](../components/action-panel.md) — Automatically uses this hook to expose its actions in the palette

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

@@ -0,0 +1,67 @@
+---
+title: useResolvedLocale
+description: Hook to access the full BCP-47 locale and language code from AppShell context
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/use-resolved-locale.docs.outline.md — do not edit by hand. -->
+
+# useResolvedLocale
+
+React hook that returns the full BCP-47 locale (e.g. `"en-GB"`) and the language code (e.g. `"en"`) from the AppShell context. Use this for `Intl` APIs and date formatting that require a specific locale.
+
+## Signature
+
+```typescript
+const useResolvedLocale: () => {
+  locale: string;
+  language: string;
+};
+```
+
+## Return Value
+
+### `locale`
+
+- **Type:** `string`
+- **Description:** Full BCP-47 locale tag (e.g. `"en-GB"`, `"ja-JP"`). Sourced from the `locale` prop passed to `AppShell`, or auto-detected from the browser when omitted.
+
+### `language`
+
+- **Type:** `string`
+- **Description:** Language subtag only (e.g. `"en"`, `"ja"`). Used for resolving built-in UI label tables.
+
+## Usage
+
+```typescript
+import { useResolvedLocale } from "@tailor-platform/app-shell";
+
+function DateDisplay({ date }: { date: Date }) {
+  const { locale } = useResolvedLocale();
+
+  return (
+    <span>
+      {new Intl.DateTimeFormat(locale, { dateStyle: "long" }).format(date)}
+    </span>
+  );
+}
+```
+
+### Locale-aware number formatting
+
+```typescript
+function PriceDisplay({ amount }: { amount: number }) {
+  const { locale } = useResolvedLocale();
+
+  return (
+    <span>
+      {new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(amount)}
+    </span>
+  );
+}
+```
+
+## Related
+
+- [AppShell](../components/app-shell.md) — configure locale via the `locale` prop
+- [useTimeZone](./use-time-zone.md) — access the configured IANA timezone
+- [DatePicker](../components/date-picker.md) — date input components that consume this locale automatically