;
}
```
@@ -225,24 +256,27 @@ function App() {
### Prefix Syntax
-The prefix match is **case-sensitive**. When a user types `ORD:`, the string after the colon (including any space) is forwarded to `search` as the query:
+The prefix match is **case-sensitive**. When an initial value activates a search mode (for example, pasted text or programmatic opening), leading whitespace after the colon is removed from the initial query:
```
-User types: ORD:
+Initial input: ORD:
→ search("", { signal }) — empty query, show all or hint
-User types: ORD:12345
+Initial input: ORD:12345
→ search("12345", { signal })
-User types: ORD: alice
- → search(" alice", { signal }) — leading space preserved
+Initial input: ORD: alice
+ → search("alice", { signal }) — leading space removed
```
+Once the mode is active, subsequent edits to its query are passed to `search` as entered.
+
## Extending the built-in palette
The supported extension points are:
- `searchSources` on `AppShell` for async, prefix-activated search modes
+- `useOpenCommandPalette` for opening with an optional initial search
- [`useRegisterCommandPaletteActions`](../api/use-register-command-palette-actions.md) for page-level actions
- [`ActionPanel`](./action-panel.md), whose enabled rows are registered automatically
@@ -374,7 +408,7 @@ The CommandPalette follows these design principles:
## Related Components
- [AppShell](./app-shell.md) - Root component that provides CommandPalette
-- [SidebarLayout](./sidebar-layout.md) - Layout that includes CommandPalette
+- [SidebarLayout](./sidebar-layout.md) - Default layout with a search entry for CommandPalette
## Related Concepts
@@ -411,5 +445,5 @@ The CommandPalette follows these design principles:
**Solutions:**
1. Check if another app is capturing the shortcut
-2. Verify you're using `SidebarLayout` (CommandPalette is included)
+2. Verify the page is inside `AppShell`, which provides the built-in CommandPalette
3. Check browser console for JavaScript errors
diff --git a/docs-src/components/date-picker.docs.outline.md b/docs-src/components/date-picker.docs.outline.md
index 207fdb78a..6a41a370c 100644
--- a/docs-src/components/date-picker.docs.outline.md
+++ b/docs-src/components/date-picker.docs.outline.md
@@ -5,6 +5,19 @@ title: DatePicker
description: Accessible date input components (@internationalized/date + Base UI)
sources:
- packages/core/src/components/date-field/**
+ - packages/core/src/components/calendar/**
+claims:
+ - CalendarDate
+ - CalendarDateTime
+ - DateValue
+ - Time
+ - ZonedDateTime
+ - getLocalTimeZone
+ - parseAbsolute
+ - parseDate
+ - parseDateTime
+ - parseZonedDateTime
+upstream: https://react-spectrum.adobe.com/internationalized/date/
---
# DatePicker
@@ -32,6 +45,41 @@ import {
The examples below also import `Button`, `Form`, and `Text` from `@tailor-platform/app-shell`, and `useId` and `useState` from `react`.
+## Date values and parsing helpers
+
+AppShell re-exports these types and helpers from [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) so applications can import them from `@tailor-platform/app-shell` without an additional dependency.
+
+| Export | Purpose |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `CalendarDate` | Date-only value, without a time or timezone. |
+| `CalendarDateTime` | Date and time without a timezone; it does not identify a unique instant. |
+| `ZonedDateTime` | Date and time with a timezone and UTC offset. |
+| `Time` | Time of day without a date or timezone. |
+| `DateValue` | Union of `CalendarDate`, `CalendarDateTime`, and `ZonedDateTime`, accepted by the date controls. It does not include `Time`. |
+| `parseDate(text)` | Parse an ISO date into a `CalendarDate`. |
+| `parseDateTime(text)` | Parse an ISO date/time without a timezone into a `CalendarDateTime`. |
+| `parseAbsolute(text, timeZone)` | Parse an ISO instant containing `Z` or an offset and represent it in the supplied IANA timezone as a `ZonedDateTime`. |
+| `parseZonedDateTime(text)` | Parse a date/time with a bracketed IANA timezone into a `ZonedDateTime`, preserving the named zone. |
+| `getLocalTimeZone()` | Read the environment's local IANA timezone. This does not read AppShell's `timeZone` setting. |
+
+The first five exports are **types only**, not constructor values. Use the parsing helpers to create date values:
+
+```ts
+import {
+ parseDate,
+ parseDateTime,
+ parseAbsolute,
+ parseZonedDateTime,
+} from "@tailor-platform/app-shell";
+
+const date = parseDate("2026-04-09");
+const localDateTime = parseDateTime("2026-04-09T09:30");
+const instantInTokyo = parseAbsolute("2026-04-09T00:30:00Z", "Asia/Tokyo");
+const zonedDateTime = parseZonedDateTime("2026-04-09T09:30[Asia/Tokyo]");
+```
+
+Parsing can throw for invalid input; validate or catch errors when the string is not trusted. For application-timezone behavior in React components, call [`useTimeZone()`](../api/use-time-zone.md) at the component's top level and pass its `value` to `parseAbsolute`. Use its `today()` and `now()` methods for the current date and instant, rather than assuming the user's local timezone matches the configured one.
+
## API shape
`DateField` and `DatePicker` are standalone composite controls.
@@ -57,9 +105,10 @@ Inside `Field.Root`:
Controlled:
```tsx
-const [date, setDate] = useState(null);
-
-;
+function ControlledDateField() {
+ const [date, setDate] = useState(null);
+ return ;
+}
```
## DatePicker
diff --git a/docs-src/components/default-sidebar.docs.outline.md b/docs-src/components/default-sidebar.docs.outline.md
index 299cda7f4..41ab96dca 100644
--- a/docs-src/components/default-sidebar.docs.outline.md
+++ b/docs-src/components/default-sidebar.docs.outline.md
@@ -5,6 +5,7 @@ title: DefaultSidebar
description: Built-in sidebar component for auto-generated or composed navigation, with optional search suppression and icon-rail mode
sources:
- packages/core/src/components/sidebar/default-sidebar.tsx
+ - packages/core/src/components/sidebar/primitives.tsx
---
# DefaultSidebar
diff --git a/docs-src/components/form.docs.outline.md b/docs-src/components/form.docs.outline.md
index 4d36b96f0..040c12789 100644
--- a/docs-src/components/form.docs.outline.md
+++ b/docs-src/components/form.docs.outline.md
@@ -5,6 +5,8 @@ title: Form, Field, and Fieldset
description: Components for building validated forms with automatic accessibility wiring, validation state management, and optional React Hook Form integration
sources:
- packages/core/src/components/form/**
+ - packages/core/src/components/field/**
+ - packages/core/src/components/fieldset/**
---
# Form, Field, and Fieldset
diff --git a/docs-src/components/global-header-layout.docs.outline.md b/docs-src/components/global-header-layout.docs.outline.md
index 65d89c3fb..658b921e8 100644
--- a/docs-src/components/global-header-layout.docs.outline.md
+++ b/docs-src/components/global-header-layout.docs.outline.md
@@ -5,6 +5,7 @@ title: GlobalHeaderLayout
description: Opinionated layout with an app-wide header above the whole shell and a sidebar that collapses to a persistent icon rail
sources:
- packages/core/src/components/sidebar/global-header-layout.tsx
+ - packages/core/src/components/sidebar/global-header.tsx
---
# GlobalHeaderLayout
diff --git a/docs-src/components/menu.docs.outline.md b/docs-src/components/menu.docs.outline.md
index d9eb3e307..cd758e6f9 100644
--- a/docs-src/components/menu.docs.outline.md
+++ b/docs-src/components/menu.docs.outline.md
@@ -5,6 +5,7 @@ title: Menu
description: Dropdown menu with a compound component API, supporting checkbox/radio items, groups, separators, and nested sub-menus
sources:
- packages/core/src/components/menu/**
+ - packages/core/src/lib/position.ts
---
# Menu
@@ -58,11 +59,23 @@ The runnable examples also import `useState` from `react`, `Button` and `Text` f
### Menu.Content Props
-| Prop | Type | Default | Description |
-| ----------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
-| `position` | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; sideOffset?: number }` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup |
-| `className` | `string` | - | Additional CSS classes |
-| `children` | `React.ReactNode` | - | Menu items and other sub-components |
+| Prop | Type | Default | Description |
+| ----------- | ----------------- | --------------------------------------------------- | ----------------------------------- |
+| `position` | `PositionProps` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Menu items and other sub-components |
+
+### PositionProps
+
+The public `PositionProps` type is shared by the `position` prop on `Menu.Content` and [`Tooltip.Content`](./tooltip.md#tooltipcontent-props). Import it from `@tailor-platform/app-shell` when reusing a placement configuration.
+
+| Property | Type | Description |
+| ------------ | ---------------------------------------- | ------------------------------------ |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | Preferred side of the trigger. |
+| `align` | `"start" \| "center" \| "end"` | Alignment along the cross axis. |
+| `sideOffset` | `number` | Distance in pixels from the trigger. |
+
+All properties are optional. Defaults belong to the component: Menu uses bottom/start/4px, while Tooltip uses top/center/5px.
### Menu.Item Props
diff --git a/docs-src/components/select.docs.outline.md b/docs-src/components/select.docs.outline.md
index 8c13b6abc..c9d622369 100644
--- a/docs-src/components/select.docs.outline.md
+++ b/docs-src/components/select.docs.outline.md
@@ -5,6 +5,7 @@ title: Select
description: Single or multi-select dropdown with optional async data fetching
sources:
- packages/core/src/components/select/**
+ - packages/core/src/components/dropdown-items/**
---
# Select
@@ -17,7 +18,7 @@ The `Select` component provides a fully assembled single or multi-select dropdow
import { Select } from "@tailor-platform/app-shell";
```
-The examples below also import `useState` from `react`, and `Field`, `Text`, and the `SelectAsyncFetcher` type from `@tailor-platform/app-shell`.
+The examples below also import `useState` from `react`, and `Button`, `Field`, `Text`, and the `SelectAsyncFetcher` type from `@tailor-platform/app-shell`.
## Basic Usage
@@ -45,6 +46,8 @@ The examples below also import `useState` from `react`, and `Field`, `Text`, and
### MappedItem
+`MappedItem` and `ItemGroup` are public types shared by `Select`, `Combobox`, and `Autocomplete`; import them from `@tailor-platform/app-shell`.
+
```ts
interface MappedItem {
label: string; // Display text, used for filtering and a11y
@@ -154,14 +157,19 @@ or a server action.
### Controlled Select
```tsx
-const [selected, setSelected] = useState(null);
-
-;
+function ControlledSelect() {
+ const [selected, setSelected] = useState(null);
+
+ return (
+
+ );
+}
```
### Custom Render
@@ -187,46 +195,58 @@ const [selected, setSelected] = useState(null);
Combine `Select.useAsync` with `Select.Parts` for full control over layout and rendering:
-`Select.useAsync` accepts the same options as `Select.Async` (including `onFetchError`) and returns:
+`Select.useAsync` accepts `fetcher` and optional `onFetchError`, and returns:
-| Property | Type | Description |
-| --------- | ------------ | ------------------------------------------------------- |
-| `items` | `T[]` | Currently loaded items |
-| `loading` | `boolean` | Whether a fetch is in progress |
-| `error` | `unknown` | The error thrown by the last fetch, if any |
-| `retry` | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |
+| Property | Type | Description |
+| -------------- | ------------------------- | ------------------------------------------------------- |
+| `items` | `T[]` | Currently loaded items |
+| `loading` | `boolean` | Whether a fetch is in progress |
+| `error` | `unknown` | The error thrown by the last fetch, if any |
+| `retry` | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |
+| `onOpenChange` | `(open: boolean) => void` | Pass to the Root to fetch on open and cancel on close. |
```tsx
type Fruit = { id: number; name: string };
-const fruits = Select.useAsync({
- fetcher: async ({ signal }) => {
- const res = await fetch("/api/fruits", { signal });
- return res.json() as Promise;
- },
- onFetchError: (error) => reportError(error),
-});
-
- f.name}>
-
-
-
-
- {fruits.error ? (
-
;
- },
+ component: ProductDetailPage,
});
```
@@ -217,6 +224,7 @@ const orderResource = defineResource({
```typescript
const productsModule = defineModule({
path: "products",
+ meta: { title: "Products" },
component: ProductsPage,
resources: [
defineResource({
@@ -252,6 +260,7 @@ Resources appear in:
```typescript
defineModule({
path: "products",
+ meta: { title: "Products" },
component: ProductsPage,
resources: [
defineResource({
@@ -288,15 +297,18 @@ Products > Product Details > Edit
## TypeScript
```typescript
-import { type DefineResourceProps, type Resource } from "@tailor-platform/app-shell";
+import { defineResource } from "@tailor-platform/app-shell";
+
+type ResourceOptions = Parameters[0];
+type AppResource = ReturnType;
-const props: DefineResourceProps = {
+const props: ResourceOptions = {
path: ":id",
component: DetailPage,
guards: [],
};
-const resource: Resource = defineResource(props);
+const resource: AppResource = defineResource(props);
```
## Related
diff --git a/docs/api/guards/hidden.md b/docs/api/guards/hidden.md
index bfe9e64cd..065f7c3ec 100644
--- a/docs/api/guards/hidden.md
+++ b/docs/api/guards/hidden.md
@@ -121,15 +121,17 @@ const conditionalHide: Guard = ({ context }) => {
### Async Permission Check
```typescript
-const asyncHide: Guard = async ({ context }) => {
- const allowed = await fetch("/api/check-access");
- if (!allowed) {
+const asyncHide: Guard = async () => {
+ const response = await fetch("/api/check-access");
+ if (!response.ok) {
return hidden();
}
return pass();
};
```
+This endpoint must return a successful HTTP status only when access is allowed (for example, 204 for allowed and 403 for denied). A `Response` object is always truthy, including for 403 or 500 responses, so test `response.ok`, not the response itself. A rejected request propagates to the route error boundary rather than granting access.
+
## vs redirectTo()
| Aspect | hidden() | redirectTo() |
diff --git a/docs/api/guards/overview.md b/docs/api/guards/overview.md
index e142625af..21cf879a3 100644
--- a/docs/api/guards/overview.md
+++ b/docs/api/guards/overview.md
@@ -17,7 +17,7 @@ Guards are executed sequentially and can return one of three results:
- **`hidden()`** - Deny access, return 404
- **`redirectTo(path)`** - Redirect to another page
-If any guard returns `hidden()` or `redirectTo()`, execution stops immediately.
+If any guard returns `hidden()` or `redirectTo()`, execution stops immediately. These client-side guards control navigation and rendering; protected APIs must enforce authorization on the server as well.
## Guard Function Signature
@@ -38,7 +38,7 @@ type GuardResult = { type: "pass" } | { type: "hidden" } | { type: "redirect"; t
Allows access and continues to the next guard.
```typescript
-import { pass } from "@tailor-platform/app-shell";
+import { pass, type Guard } from "@tailor-platform/app-shell";
const allowAll: Guard = () => pass();
```
@@ -50,7 +50,7 @@ const allowAll: Guard = () => pass();
Denies access and shows 404 Not Found.
```typescript
-import { hidden } from "@tailor-platform/app-shell";
+import { hidden, type Guard } from "@tailor-platform/app-shell";
const denyAll: Guard = () => hidden();
```
@@ -62,7 +62,7 @@ const denyAll: Guard = () => hidden();
Redirects to another page.
```typescript
-import { redirectTo } from "@tailor-platform/app-shell";
+import { redirectTo, type Guard } from "@tailor-platform/app-shell";
const redirectToLogin: Guard = () => redirectTo("/login");
```
@@ -80,7 +80,9 @@ import { defineModule, pass, hidden } from "@tailor-platform/app-shell";
const adminModule = defineModule({
path: "admin",
+ meta: { title: "Admin" },
component: AdminPage,
+ resources: [],
guards: [
({ context }) => {
return context.currentUser?.role === "admin" ? pass() : hidden();
@@ -109,7 +111,9 @@ const isAdmin = ({ context }) =>
Guards receive context data from AppShell:
```typescript
-// Define your context type
+// Define your context type in a module augmentation
+import "@tailor-platform/app-shell";
+
declare module "@tailor-platform/app-shell" {
interface AppShellRegister {
contextData: {
@@ -198,10 +202,12 @@ const requireFeature =
### Async Permission Check
```typescript
-const checkApiPermission: Guard = async ({ context }) => {
+const checkApiPermission: Guard = async () => {
const response = await fetch("/api/permissions/admin");
+ if (!response.ok) return hidden();
+
const { allowed } = await response.json();
- return allowed ? pass() : hidden();
+ return allowed === true ? pass() : hidden();
};
```
@@ -213,6 +219,9 @@ const guards = [requireAuth, requireAdmin, requireFeature("beta")];
// All must pass() for access to be granted
defineModule({
path: "admin",
+ meta: { title: "Admin" },
+ component: AdminPage,
+ resources: [],
guards: guards,
});
```
@@ -242,6 +251,9 @@ import { requireAuth, requireRole } from "./guards";
defineModule({
path: "admin",
+ meta: { title: "Admin" },
+ component: AdminPage,
+ resources: [],
guards: [requireAuth, requireRole("admin")],
});
```
@@ -326,13 +338,15 @@ const isAdmin: Guard = ({ context }) => {
### Async Guards (Slower)
```typescript
-const checkPermission: Guard = async ({ context }) => {
- const allowed = await fetch("/api/check");
- return allowed ? pass() : hidden();
+const checkPermission: Guard = async () => {
+ const response = await fetch("/api/check");
+ return response.ok ? pass() : hidden();
};
// ~50-200ms - Network request
```
+This endpoint uses HTTP status as the permission result: success means allowed, while 403 or any other non-success status means denied. If an endpoint returns a permission flag in JSON instead, validate that flag as in [Async Permission Check](#async-permission-check). A rejected request propagates to the route error boundary rather than granting access.
+
**Tip:** Prefer sync guards when possible. Cache API results in context data.
## Comparison: Route vs Component Guards
diff --git a/docs/api/guards/pass.md b/docs/api/guards/pass.md
index a143cc544..dea6e1e41 100644
--- a/docs/api/guards/pass.md
+++ b/docs/api/guards/pass.md
@@ -120,7 +120,7 @@ guards: [
];
```
-If all guards return `pass()`, access is granted.
+If all guards return `pass()`, guard evaluation permits access. This does not create a landing page or redirect: a module/resource without a `component` still returns 404 at its exact path while its child routes remain accessible.
## Related
diff --git a/docs/api/guards/redirect-to.md b/docs/api/guards/redirect-to.md
index 4747877f3..3865b79ac 100644
--- a/docs/api/guards/redirect-to.md
+++ b/docs/api/guards/redirect-to.md
@@ -223,7 +223,9 @@ const guards = [
```typescript
const dashboardModule = defineModule({
path: "dashboard",
+ meta: { title: "Dashboard" },
component: DashboardPage,
+ resources: [],
guards: [
({ context }) => {
if (!context.currentUser) {
diff --git a/docs/api/use-ai-chat.md b/docs/api/use-ai-chat.md
index 9b1b3fbd8..d8c2b498b 100644
--- a/docs/api/use-ai-chat.md
+++ b/docs/api/use-ai-chat.md
@@ -70,10 +70,26 @@ Calls become available before local tool execution. They record requested tool n
Register local tools under a single object using `defineAIChatTool(...)`. Their schemas must implement both [Standard Schema](https://standardschema.dev/) validation and Standard JSON Schema generation (for example, Zod 4). Provider-native tools are not supported.
+## Local tool API
+
+`defineAIChatTool({ schema, execute, description? })` returns an `AILocalTool` with `kind: "local"`. The helper infers the first `execute` argument from the schema's **validated output**, including schema transformations. It does not execute or validate inputs when the tool is defined: `useAIChat` validates the model's arguments before calling `execute`.
+
+`AIChatToolSchema` is the schema contract: it combines Standard Schema validation with Standard JSON Schema generation. Zod 4 implements both. AppShell sends the schema's input JSON Schema to the AI Gateway; the executor receives the validated output.
+
+The second `execute` argument is an `AIChatToolContext`:
+
+| Property | Type | Description |
+| ---------- | ----------------- | ----------------------------------------------------------------------------------------------------------- |
+| `signal` | `AbortSignal` | Cancellation signal for the active chat request. Forward it to `fetch` or other operations that support it. |
+| `messages` | `AIChatMessage[]` | User/assistant text available to the current turn, excluding internal tool-call and tool-result messages. |
+
+Calling `stop()` or unmounting aborts the signal. Custom tool work must cooperate with cancellation; aborting does not undo side effects that have already happened. The example below forwards the signal to its request and checks the response status before returning a tool result.
+
## Usage
```tsx
import {
+ Button,
createAuthClient,
createAIGatewayClient,
defineAIChatTool,
@@ -96,8 +112,12 @@ const lookupCustomer = defineAIChatTool({
schema: z.object({
customerId: z.string(),
}),
- async execute({ customerId }) {
- return { customerId, name: "Acme Corp" };
+ async execute({ customerId }, { signal }) {
+ const response = await fetch(`/api/customers/${encodeURIComponent(customerId)}`, { signal });
+ if (!response.ok) {
+ throw new Error(`Customer lookup failed: ${response.status}`);
+ }
+ return response.json();
},
});
@@ -121,15 +141,15 @@ export function ChatScreen() {
Tool call: {call.name}
))}
-
-
+
+
{error ?
{error.message}
: null}
);
diff --git a/docs/api/use-app-shell-config.md b/docs/api/use-app-shell-config.md
index e0de25c3d..0131a4906 100644
--- a/docs/api/use-app-shell-config.md
+++ b/docs/api/use-app-shell-config.md
@@ -111,14 +111,16 @@ function SettingsMenu() {
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();
+```tsx
+function ModuleCount() {
+ // Subscribes to configuration only.
+ const { configurations } = useAppShellConfig();
+ return {configurations.modules.length} modules;
+}
```
+Using `useAppShell()` here would also subscribe to context-data changes that this component does not use.
+
## Comparison with Other Hooks
| Hook | Returns | Use When |
diff --git a/docs/api/use-app-shell-data.md b/docs/api/use-app-shell-data.md
index d617aa9e5..24fc5a650 100644
--- a/docs/api/use-app-shell-data.md
+++ b/docs/api/use-app-shell-data.md
@@ -96,6 +96,8 @@ Define your context type with module augmentation:
```typescript
// types.d.ts
+import "@tailor-platform/app-shell";
+
type User = { name: string; email: string; role: string };
declare module "@tailor-platform/app-shell" {
@@ -113,27 +115,31 @@ declare module "@tailor-platform/app-shell" {
}
```
-Now `useAppShellData()` returns fully typed data:
+Now `useAppShellData()` returns fully typed data inside your components:
-```typescript
-const { contextData } = useAppShellData();
-contextData.currentUser; // Type: User | null
-contextData.permissions; // Type: string[]
-contextData.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
+```tsx
+function UserSummary() {
+ const { contextData } = useAppShellData();
+ // currentUser is User | null; permissions is string[].
+ // featureFlags has newEditor and betaDashboard boolean properties.
+ return {contextData.currentUser?.name};
+}
```
## 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();
+```tsx
+function PermissionCount() {
+ // Subscribes to context data only.
+ const { contextData } = useAppShellData();
+ return {contextData.permissions.length} permissions;
+}
```
+Using `useAppShell()` here would also subscribe to configuration changes that this component does not use.
+
## Comparison with Other Hooks
| Hook | Returns | Use When |
diff --git a/docs/api/use-app-shell.md b/docs/api/use-app-shell.md
index 7e964cea2..797b3512c 100644
--- a/docs/api/use-app-shell.md
+++ b/docs/api/use-app-shell.md
@@ -32,6 +32,18 @@ const useAppShell: () => {
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.
+## Context API family
+
+| API | Reference |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `useAppShellConfig` | [Configuration-only subscription](./use-app-shell-config.md) |
+| `useAppShellData` | [Context-data-only subscription](./use-app-shell-data.md) |
+| `useResolvedLocale` | [Full locale and language code](./use-resolved-locale.md) |
+| `useTimeZone`, `TimeZone` | [Configured timezone and bound date/time helpers](./use-time-zone.md) |
+| `AppInfo`, `AppInfoEntry` | [Metadata for the built-in app-info page](../components/app-shell.md#appinfo) |
+| `AppShellRegister`, `ContextData` | [Context-data registration](#context-data) |
+| `RouteParams` | [Registered route-parameter map](#route-parameter-types) |
+
## Return Value
### `contextData`
@@ -81,6 +93,8 @@ Define your context type with module augmentation:
```typescript
// types.d.ts
+import "@tailor-platform/app-shell";
+
type User = { name: string; email: string; role: string };
declare module "@tailor-platform/app-shell" {
@@ -92,7 +106,13 @@ declare module "@tailor-platform/app-shell" {
};
}
}
+```
+
+`AppShellRegister.contextData` sets the exported `ContextData` type. Without registration, `ContextData` falls back to `Record`. The side-effect import makes this declaration a module augmentation rather than a replacement module declaration.
+
+Pass matching data to `AppShell`:
+```tsx
// App.tsx
+>
+
+
+```
+Read the registered data inside a component:
+
+```tsx
// MyComponent.tsx
-const { contextData } = useAppShell();
-contextData.currentUser // Fully typed!
-contextData.permissions // Fully typed!
+import { useAppShell } from "@tailor-platform/app-shell";
+
+function MyComponent() {
+ const { contextData } = useAppShell();
+
+ // currentUser is User | null; permissions is string[].
+ return (
+
);
}
diff --git a/docs/api/use-register-command-palette-actions.md b/docs/api/use-register-command-palette-actions.md
index 5be3cc29a..6d37dddc5 100644
--- a/docs/api/use-register-command-palette-actions.md
+++ b/docs/api/use-register-command-palette-actions.md
@@ -80,7 +80,7 @@ function OrderDetailPage() {
## 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.
+- Changes to action keys, labels, or the group update the registered set. The latest `onSelect` callbacks are used without requiring re-registration.
- `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`.
diff --git a/docs/api/use-route-error.md b/docs/api/use-route-error.md
index d27c7c4c3..5ad2c6d00 100644
--- a/docs/api/use-route-error.md
+++ b/docs/api/use-route-error.md
@@ -54,9 +54,10 @@ import { defineModule } from "@tailor-platform/app-shell";
const myModule = defineModule({
path: "dashboard",
+ meta: { title: "Dashboard" },
component: DashboardPage,
errorBoundary: ,
- resources: [...]
+ resources: [],
});
```
@@ -65,6 +66,7 @@ const myModule = defineModule({
```typescript
const productsModule = defineModule({
path: "products",
+ meta: { title: "Products" },
component: ProductsPage,
resources: [
defineResource({
@@ -79,17 +81,22 @@ const productsModule = defineModule({
### Advanced Error Handling
```typescript
-import { isRouteErrorResponse, Text, useRouteError } from "@tailor-platform/app-shell";
+import { Text, useRouteError } from "@tailor-platform/app-shell";
function ErrorBoundary() {
const error = useRouteError();
- // Handle route error responses (404, 500, etc.)
- if (isRouteErrorResponse(error)) {
+ // Narrow the unknown error before reading an HTTP status.
+ if (
+ typeof error === "object" &&
+ error !== null &&
+ "status" in error &&
+ typeof error.status === "number"
+ ) {
return (
- {error.status} {error.statusText}
- {error.data}
+ HTTP {error.status}
+ The requested page could not be loaded.
);
}
@@ -142,7 +149,12 @@ function ErrorBoundary() {
function ErrorBoundary() {
const error = useRouteError();
- if (isRouteErrorResponse(error)) {
+ if (
+ typeof error === "object" &&
+ error !== null &&
+ "status" in error &&
+ typeof error.status === "number"
+ ) {
if (error.status === 404) {
return ;
}
@@ -168,8 +180,9 @@ Error boundaries can be defined at different levels:
// Module-level - catches errors in all resources
defineModule({
path: "products",
+ meta: { title: "Products" },
errorBoundary: ,
- resources: [...]
+ resources: [],
})
// Resource-level - catches errors in specific resource
diff --git a/docs/components/app-shell.md b/docs/components/app-shell.md
index cef77a032..a60f6f778 100644
--- a/docs/components/app-shell.md
+++ b/docs/components/app-shell.md
@@ -25,6 +25,7 @@ const modules = [
path: "dashboard",
component: DashboardPage,
meta: { title: "Dashboard" },
+ resources: [],
}),
];
@@ -229,7 +230,7 @@ Access the configured timezone in components using [`useTimeZone`](../api/use-ti
### errorBoundary
- **Type:** `ErrorBoundaryComponent` (optional)
-- **Description:** Global error boundary component applied to all routes
+- **Description:** Global error boundary element applied to all routes. Pass JSX such as ``, not a component constructor.
```tsx
import { Text, useRouteError } from "@tailor-platform/app-shell";
@@ -244,7 +245,7 @@ const GlobalErrorBoundary = () => {
);
};
-
+}>
{/* ... */}
;
```
@@ -260,6 +261,8 @@ First, define your context data type using module augmentation:
```typescript
// types.d.ts — `User` and `ApiClient` are your application's own types
+import "@tailor-platform/app-shell";
+
declare module "@tailor-platform/app-shell" {
interface AppShellRegister {
contextData: {
@@ -469,6 +472,7 @@ const modules = [
path: "dashboard",
component: DashboardPage,
meta: { title: "Dashboard" },
+ resources: [],
}),
defineModule({
path: "products",
@@ -506,7 +510,7 @@ function App() {
settingsResources={settingsResources}
locale="en"
defaultColorTheme="system"
- errorBoundary={ErrorBoundary}
+ errorBoundary={}
contextData={{ currentUser }}
>
diff --git a/docs/components/badge.md b/docs/components/badge.md
index 1cc28661a..ae17f050f 100644
--- a/docs/components/badge.md
+++ b/docs/components/badge.md
@@ -101,7 +101,9 @@ _Generated from the type surface — first-party props only._
## Exports
- `Badge` — function
+- `BadgeOptions` — interface
- `BadgeProps` — interface
+- `BadgeVariant` — type
- `badgeVariants` — const
### Badge Variants
diff --git a/docs/components/command-palette.md b/docs/components/command-palette.md
index b9ec548c5..a08e7dd8b 100644
--- a/docs/components/command-palette.md
+++ b/docs/components/command-palette.md
@@ -52,6 +52,34 @@ The CommandPalette will automatically:
| `Enter` | Navigate to selected route |
| Type to search | Filter routes by fuzzy search |
+## Opening programmatically
+
+Call `useOpenCommandPalette()` at the top level of a component inside `AppShell`. It returns a function that opens the built-in palette; call that function from an event handler.
+
+```tsx
+import { Button, useOpenCommandPalette } from "@tailor-platform/app-shell";
+
+function SearchActions() {
+ const openCommandPalette = useOpenCommandPalette();
+
+ return (
+ <>
+
+
+
+ >
+ );
+}
+```
+
+The returned function accepts an optional `OpenCommandPaletteOptions` object:
+
+| Property | Type | Description |
+| -------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `search` | `string` | Initial search text. Omit it to open with an empty search. A registered `PREFIX:` activates its search mode. |
+
+Each call initializes the search, even if the palette is already open. The `ORD:` example requires an `ORD` source in AppShell's `searchSources`; without a matching source, the text is treated as an ordinary page/action search.
+
## Features
### Fuzzy Search
@@ -117,6 +145,8 @@ function OrderDetailPage() {
{ key: "confirm", label: "Confirm order", onSelect: handleConfirm },
{ key: "cancel", label: "Cancel order", icon: , onSelect: handleCancel },
]);
+
+ return
{/* page content */}
;
}
```
@@ -223,24 +253,27 @@ function App() {
### Prefix Syntax
-The prefix match is **case-sensitive**. When a user types `ORD:`, the string after the colon (including any space) is forwarded to `search` as the query:
+The prefix match is **case-sensitive**. When an initial value activates a search mode (for example, pasted text or programmatic opening), leading whitespace after the colon is removed from the initial query:
```
-User types: ORD:
+Initial input: ORD:
→ search("", { signal }) — empty query, show all or hint
-User types: ORD:12345
+Initial input: ORD:12345
→ search("12345", { signal })
-User types: ORD: alice
- → search(" alice", { signal }) — leading space preserved
+Initial input: ORD: alice
+ → search("alice", { signal }) — leading space removed
```
+Once the mode is active, subsequent edits to its query are passed to `search` as entered.
+
## Extending the built-in palette
The supported extension points are:
- `searchSources` on `AppShell` for async, prefix-activated search modes
+- `useOpenCommandPalette` for opening with an optional initial search
- [`useRegisterCommandPaletteActions`](../api/use-register-command-palette-actions.md) for page-level actions
- [`ActionPanel`](./action-panel.md), whose enabled rows are registered automatically
@@ -372,7 +405,7 @@ The CommandPalette follows these design principles:
## Related Components
- [AppShell](./app-shell.md) - Root component that provides CommandPalette
-- [SidebarLayout](./sidebar-layout.md) - Layout that includes CommandPalette
+- [SidebarLayout](./sidebar-layout.md) - Default layout with a search entry for CommandPalette
## Related Concepts
@@ -409,5 +442,5 @@ The CommandPalette follows these design principles:
**Solutions:**
1. Check if another app is capturing the shortcut
-2. Verify you're using `SidebarLayout` (CommandPalette is included)
+2. Verify the page is inside `AppShell`, which provides the built-in CommandPalette
3. Check browser console for JavaScript errors
diff --git a/docs/components/date-picker.md b/docs/components/date-picker.md
index 1329c79a8..6bb604feb 100644
--- a/docs/components/date-picker.md
+++ b/docs/components/date-picker.md
@@ -30,6 +30,41 @@ import {
The examples below also import `Button`, `Form`, and `Text` from `@tailor-platform/app-shell`, and `useId` and `useState` from `react`.
+## Date values and parsing helpers
+
+AppShell re-exports these types and helpers from [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) so applications can import them from `@tailor-platform/app-shell` without an additional dependency.
+
+| Export | Purpose |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `CalendarDate` | Date-only value, without a time or timezone. |
+| `CalendarDateTime` | Date and time without a timezone; it does not identify a unique instant. |
+| `ZonedDateTime` | Date and time with a timezone and UTC offset. |
+| `Time` | Time of day without a date or timezone. |
+| `DateValue` | Union of `CalendarDate`, `CalendarDateTime`, and `ZonedDateTime`, accepted by the date controls. It does not include `Time`. |
+| `parseDate(text)` | Parse an ISO date into a `CalendarDate`. |
+| `parseDateTime(text)` | Parse an ISO date/time without a timezone into a `CalendarDateTime`. |
+| `parseAbsolute(text, timeZone)` | Parse an ISO instant containing `Z` or an offset and represent it in the supplied IANA timezone as a `ZonedDateTime`. |
+| `parseZonedDateTime(text)` | Parse a date/time with a bracketed IANA timezone into a `ZonedDateTime`, preserving the named zone. |
+| `getLocalTimeZone()` | Read the environment's local IANA timezone. This does not read AppShell's `timeZone` setting. |
+
+The first five exports are **types only**, not constructor values. Use the parsing helpers to create date values:
+
+```ts
+import {
+ parseDate,
+ parseDateTime,
+ parseAbsolute,
+ parseZonedDateTime,
+} from "@tailor-platform/app-shell";
+
+const date = parseDate("2026-04-09");
+const localDateTime = parseDateTime("2026-04-09T09:30");
+const instantInTokyo = parseAbsolute("2026-04-09T00:30:00Z", "Asia/Tokyo");
+const zonedDateTime = parseZonedDateTime("2026-04-09T09:30[Asia/Tokyo]");
+```
+
+Parsing can throw for invalid input; validate or catch errors when the string is not trusted. For application-timezone behavior in React components, call [`useTimeZone()`](../api/use-time-zone.md) at the component's top level and pass its `value` to `parseAbsolute`. Use its `today()` and `now()` methods for the current date and instant, rather than assuming the user's local timezone matches the configured one.
+
## API shape
`DateField` and `DatePicker` are standalone composite controls.
@@ -88,9 +123,10 @@ function DateFieldWithField() {
Controlled:
```tsx
-const [date, setDate] = useState(null);
-
-;
+function ControlledDateField() {
+ const [date, setDate] = useState(null);
+ return ;
+}
```
## DatePicker
diff --git a/docs/components/menu.md b/docs/components/menu.md
index f6db856f4..1ebc20d7f 100644
--- a/docs/components/menu.md
+++ b/docs/components/menu.md
@@ -72,11 +72,23 @@ function BasicUsage() {
### Menu.Content Props
-| Prop | Type | Default | Description |
-| ----------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
-| `position` | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; sideOffset?: number }` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup |
-| `className` | `string` | - | Additional CSS classes |
-| `children` | `React.ReactNode` | - | Menu items and other sub-components |
+| Prop | Type | Default | Description |
+| ----------- | ----------------- | --------------------------------------------------- | ----------------------------------- |
+| `position` | `PositionProps` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Menu items and other sub-components |
+
+### PositionProps
+
+The public `PositionProps` type is shared by the `position` prop on `Menu.Content` and [`Tooltip.Content`](./tooltip.md#tooltipcontent-props). Import it from `@tailor-platform/app-shell` when reusing a placement configuration.
+
+| Property | Type | Description |
+| ------------ | ---------------------------------------- | ------------------------------------ |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | Preferred side of the trigger. |
+| `align` | `"start" \| "center" \| "end"` | Alignment along the cross axis. |
+| `sideOffset` | `number` | Distance in pixels from the trigger. |
+
+All properties are optional. Defaults belong to the component: Menu uses bottom/start/4px, while Tooltip uses top/center/5px.
### Menu.Item Props
diff --git a/docs/components/select.md b/docs/components/select.md
index e6e88bb46..84e479177 100644
--- a/docs/components/select.md
+++ b/docs/components/select.md
@@ -15,7 +15,7 @@ The `Select` component provides a fully assembled single or multi-select dropdow
import { Select } from "@tailor-platform/app-shell";
```
-The examples below also import `useState` from `react`, and `Field`, `Text`, and the `SelectAsyncFetcher` type from `@tailor-platform/app-shell`.
+The examples below also import `useState` from `react`, and `Button`, `Field`, `Text`, and the `SelectAsyncFetcher` type from `@tailor-platform/app-shell`.
## Basic Usage
@@ -55,6 +55,8 @@ function BasicUsage() {
### MappedItem
+`MappedItem` and `ItemGroup` are public types shared by `Select`, `Combobox`, and `Autocomplete`; import them from `@tailor-platform/app-shell`.
+
```ts
interface MappedItem {
label: string; // Display text, used for filtering and a11y
@@ -252,14 +254,19 @@ or a server action.
### Controlled Select
```tsx
-const [selected, setSelected] = useState(null);
+function ControlledSelect() {
+ const [selected, setSelected] = useState(null);
-;
+ return (
+
+ );
+}
```
### Custom Render
@@ -285,46 +292,58 @@ const [selected, setSelected] = useState(null);
Combine `Select.useAsync` with `Select.Parts` for full control over layout and rendering:
-`Select.useAsync` accepts the same options as `Select.Async` (including `onFetchError`) and returns:
+`Select.useAsync` accepts `fetcher` and optional `onFetchError`, and returns:
-| Property | Type | Description |
-| --------- | ------------ | ------------------------------------------------------- |
-| `items` | `T[]` | Currently loaded items |
-| `loading` | `boolean` | Whether a fetch is in progress |
-| `error` | `unknown` | The error thrown by the last fetch, if any |
-| `retry` | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |
+| Property | Type | Description |
+| -------------- | ------------------------- | ------------------------------------------------------- |
+| `items` | `T[]` | Currently loaded items |
+| `loading` | `boolean` | Whether a fetch is in progress |
+| `error` | `unknown` | The error thrown by the last fetch, if any |
+| `retry` | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |
+| `onOpenChange` | `(open: boolean) => void` | Pass to the Root to fetch on open and cancel on close. |
```tsx
type Fruit = { id: number; name: string };
-const fruits = Select.useAsync({
- fetcher: async ({ signal }) => {
- const res = await fetch("/api/fruits", { signal });
- return res.json() as Promise;
- },
- onFetchError: (error) => reportError(error),
-});
-
- f.name}>
-
-
-
-
- {fruits.error ? (
-
+ );
+}
+```
+
+`ErrorBoundaryComponent` is the public type accepted by `errorBoundary`: a `ReactNode`, such as ``, **not** the component function `ErrorBoundary`. Read errors inside that element with [`useRouteError`](../api/use-route-error.md). See [`defineModule`](../api/define-module.md) and [`defineResource`](../api/define-resource.md) for examples and option types derived from their public signatures.
+
## 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:
@@ -119,7 +142,9 @@ Both modules and resources support `guards` - an array of functions that control
- 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.
+The public `Guard` function receives a `GuardContext` containing only `{ context: ContextData }` and returns a `GuardResult`, synchronously or asynchronously. Use `pass()`, `hidden()`, or `redirectTo(path)` to construct that result. No abort signal is passed to guards.
+
+See the [Guards documentation](../api/guards/overview.md) for the complete types and helper references. These client-side guards control navigation and rendering; the server must still enforce authorization for protected data and operations.
### Guard Examples
@@ -130,12 +155,13 @@ import { defineModule, pass, hidden } from "@tailor-platform/app-shell";
const reportsModule = defineModule({
path: "reports",
+ meta: { title: "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();
+ async () => {
+ const response = await fetch("/api/me/permissions?scope=reports");
+ return response.ok ? pass() : hidden();
},
],
});
@@ -148,6 +174,7 @@ import { pass, hidden } from "@tailor-platform/app-shell";
const betaFeaturesModule = defineModule({
path: "beta",
+ meta: { title: "Beta Features" },
component: BetaFeaturesPage,
resources: [newFeatureResource],
guards: [
@@ -166,8 +193,9 @@ import { pass, hidden } from "@tailor-platform/app-shell";
const billingModule = defineModule({
path: "billing",
+ meta: { title: "Billing" },
component: BillingPage,
- resources: [billingResources],
+ resources: billingResources,
guards: [
async ({ context }) => {
const plan = await getCurrentTenantPlan();