Update App Shell pages (#68)

Co-authored-by: anukiransolur <3693214+anukiransolur@users.noreply.github.com>

Author: github-actions[bot]

docs/app-shell/api/use-override-breadcrumb.md

@@ -0,0 +1,72 @@
+---
+title: useOverrideBreadcrumb
+description: Hook for dynamically overriding breadcrumb titles from within page components
+---
+
+# 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) - Define routes and their default breadcrumb titles
+- [Routing and Navigation](../concepts/routing-navigation) - Overview of breadcrumb behavior

docs/app-shell/components/autocomplete.md

@@ -91,13 +91,13 @@ const cities: City[] = [
 
 ## Async Suggestions
 
-Use `Autocomplete.Async` to fetch suggestions as the user types. The fetcher is called on each keystroke (debounced).
+Use `Autocomplete.Async` to fetch suggestions as the user types. The fetcher is called on each keystroke (debounced). When the dropdown first opens or the input is cleared, the fetcher receives `null` as the query — return initial/default suggestions for `null`, or return an empty array to show nothing until the user starts typing.
 
 ```tsx
 import { type AutocompleteAsyncFetcher } from "@tailor-platform/app-shell";
 
 const fetcher: AutocompleteAsyncFetcher<string> = async (query, { signal }) => {
-  const res = await fetch(`/api/suggestions?q=${query}`, { signal });
+  const res = await fetch(`/api/suggestions?q=${query ?? ""}`, { signal });
   return res.json();
 };
 
@@ -121,11 +121,14 @@ Accepts all the same props as `Autocomplete` except `items`, plus:
 
 ```ts
 type AutocompleteAsyncFetcher<T> =
-  | ((query: string, options: { signal: AbortSignal }) => Promise<T[]>)
-  | { fn: (query: string, options: { signal: AbortSignal }) => Promise<T[]>; debounceMs: number };
+  | ((query: string | null, options: { signal: AbortSignal }) => Promise<T[]>)
+  | {
+      fn: (query: string | null, options: { signal: AbortSignal }) => Promise<T[]>;
+      debounceMs: number;
+    };
 ```
 
-Pass `{ fn, debounceMs }` to customize the debounce delay. Errors thrown by the fetcher are silently caught — handle errors inside the fetcher.
+`query` is `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Pass `{ fn, debounceMs }` to customize the debounce delay. Errors thrown by the fetcher are silently caught — handle errors inside the fetcher.
 
 ## Low-level Primitives
 

docs/app-shell/components/combobox.md

@@ -117,13 +117,13 @@ const [tags, setTags] = useState<Tag[]>([
 
 ## Async Loading
 
-Use `Combobox.Async` to load items from an API. The fetcher is called on each keystroke (debounced).
+Use `Combobox.Async` to load items from an API. The fetcher is called on each keystroke (debounced). When the dropdown first opens or the input is cleared, the fetcher receives `null` as the query — return initial/default items for `null`, or return an empty array to show nothing until the user starts typing.
 
 ```tsx
 import { type ComboboxAsyncFetcher } from "@tailor-platform/app-shell";
 
 const fetcher: ComboboxAsyncFetcher<User> = async (query, { signal }) => {
-  const res = await fetch(`/api/users?q=${query}`, { signal });
+  const res = await fetch(`/api/users?q=${query ?? ""}`, { signal });
   return res.json();
 };
 
@@ -150,11 +150,14 @@ Accepts all the same props as `Combobox` except `items`, plus:
 
 ```ts
 type ComboboxAsyncFetcher<T> =
-  | ((query: string, options: { signal: AbortSignal }) => Promise<T[]>)
-  | { fn: (query: string, options: { signal: AbortSignal }) => Promise<T[]>; debounceMs: number };
+  | ((query: string | null, options: { signal: AbortSignal }) => Promise<T[]>)
+  | {
+      fn: (query: string | null, options: { signal: AbortSignal }) => Promise<T[]>;
+      debounceMs: number;
+    };
 ```
 
-Pass `{ fn, debounceMs }` to customize the debounce delay. Errors thrown by the fetcher are silently caught — handle errors inside the fetcher.
+`query` is `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Pass `{ fn, debounceMs }` to customize the debounce delay. Errors thrown by the fetcher are silently caught — handle errors inside the fetcher.
 
 ## Low-level Primitives
 

docs/app-shell/concepts/routing-navigation.md

@@ -49,6 +49,49 @@ const MyComponent = () => {
 };
 ```
 
+## Breadcrumbs
+
+AppShell automatically generates breadcrumbs from your module and resource hierarchy. Each path segment corresponds to a breadcrumb item, using the `title` (or `meta.breadcrumbTitle`) defined in `defineModule` / `defineResource`.
+
+### Static Breadcrumb Titles
+
+Set a fixed breadcrumb title via `meta.breadcrumbTitle`:
+
+```tsx
+defineResource({
+  path: ":id",
+  meta: {
+    breadcrumbTitle: (segment) => `Order #${segment}`,
+  },
+  component: OrderDetailPage,
+});
+// Breadcrumb shows: "Orders > Order #12345"
+```
+
+### Dynamic Breadcrumb Titles
+
+Use the `useOverrideBreadcrumb` hook to replace a breadcrumb segment with a data-driven value from within the rendered page component:
+
+```tsx
+import { useOverrideBreadcrumb } from "@tailor-platform/app-shell";
+
+defineResource({
+  path: ":id",
+  component: () => {
+    const { data } = useQuery(GET_ORDER, { variables: { id } });
+
+    // Breadcrumb updates reactively once data loads
+    useOverrideBreadcrumb(data?.order?.name);
+
+    return <OrderDetail />;
+  },
+});
+```
+
+While `title` is `undefined` (e.g., loading), the override is cleared and the static title is shown. The override is automatically cleaned up on unmount.
+
+See [useOverrideBreadcrumb](../api/use-override-breadcrumb) for the full API reference.
+
 ## Command Palette for Quick Navigation
 
 AppShell includes a `CommandPalette` component that provides keyboard-driven quick navigation to any page in your application.

docs/app-shell/concepts/styling-theming.md

@@ -35,3 +35,28 @@ In CSS, the order of style-definition affects the final styles which are compute
 To avoid this situation, and to ensure correct style resolution, AppShell components use a class prefix "astw" (AppShell TailWind) to avoid clashes.
 
 This is important to note for developing in AppShell.
+
+## Z-Index Layering
+
+AppShell defines CSS custom properties for z-index values so you can adjust the stacking order to integrate with other libraries or overlays in your application.
+
+These properties are defined in `:root` and can be overridden in your own CSS:
+
+| Property           | Default | Used for                                                            |
+| ------------------ | ------- | ------------------------------------------------------------------- |
+| `--z-sidebar`      | `10`    | The sidebar panel                                                   |
+| `--z-sidebar-rail` | `20`    | The sidebar collapse rail / toggle button                           |
+| `--z-popup`        | `50`    | Portal-based popups (Menu, Select, Combobox, Autocomplete, Tooltip) |
+| `--z-overlay`      | `50`    | Modal overlays (Dialog, Sheet)                                      |
+
+### Example: Raising popup z-index
+
+```css
+/* your-app/globals.css */
+@import "@tailor-platform/app-shell/theme.css";
+@import "tailwindcss";
+
+:root {
+  --z-popup: 100;
+}
+```