@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/components/date-picker.md

@@ -0,0 +1,259 @@
+---
+title: DatePicker
+description: Accessible date input components (@internationalized/date + Base UI)
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/date-picker.docs.outline.md — do not edit by hand. -->
+
+# DatePicker
+
+Three related components for date input — a segmented field, a field with a calendar popover, and a standalone calendar grid. Built on [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) and Base UI.
+
+## Import
+
+```tsx
+import {
+  DateField,
+  DatePicker,
+  DateRangePicker,
+  Calendar,
+  RangeCalendar,
+  Field,
+  // Date value helpers (re-exported from @internationalized/date)
+  parseDate,
+  getLocalTimeZone,
+  today,
+  type CalendarDate,
+  type DateValue,
+  type DateRange,
+} from "@tailor-platform/app-shell";
+```
+
+## API shape
+
+`DateField` and `DatePicker` are standalone composite controls.
+
+- They own date entry, keyboard behavior, constraints, locale/timezone handling, and form value serialization.
+- They expose standard labeling hooks: `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, and `isInvalid`.
+- They also auto-wire into `Field.Root`, so `Field.Label`, `Field.Description`, `Field.Error`, and form validation state work the same way as the other AppShell form controls.
+
+## DateField
+
+Standalone usage with an accessible name:
+
+```tsx
+<DateField aria-label="Invoice date" />
+```
+
+With a visible label + description:
+
+```tsx
+<label id="invoice-date-label" htmlFor="invoice-date">
+  Invoice date
+</label>
+<DateField
+  id="invoice-date"
+  aria-labelledby="invoice-date-label"
+  aria-describedby="invoice-date-help"
+/>
+<p id="invoice-date-help">Format follows your locale</p>
+```
+
+Inside `Field.Root`:
+
+```tsx
+<Field.Root name="invoiceDate">
+  <Field.Label>Invoice date</Field.Label>
+  <DateField />
+  <Field.Description>Format follows your locale</Field.Description>
+</Field.Root>
+```
+
+Controlled:
+
+```tsx
+const [date, setDate] = useState<CalendarDate | null>(null);
+
+<DateField aria-label="Invoice date" value={date} onChange={setDate} />;
+```
+
+## DatePicker
+
+A `DateField` with a calendar popover.
+
+```tsx
+<DatePicker aria-label="Ship date" />
+```
+
+Constrained + unavailable dates:
+
+```tsx
+<label id="delivery-date-label" htmlFor="delivery-date">
+  Delivery date
+</label>
+<DatePicker
+  id="delivery-date"
+  aria-labelledby="delivery-date-label"
+  minValue={today(getLocalTimeZone())}
+  isDateUnavailable={(date) => {
+    const dow = date.toDate(getLocalTimeZone()).getDay();
+    return dow === 0 || dow === 6; // weekends
+  }}
+/>
+```
+
+Week start:
+
+```tsx
+<DatePicker aria-label="Date" firstDayOfWeek="mon" />
+```
+
+## Validation and errors
+
+Use standard HTML + ARIA when rendering the field standalone:
+
+```tsx
+<label id="delivery-date-label" htmlFor="delivery-date">
+  Delivery date
+</label>
+<DatePicker
+  id="delivery-date"
+  aria-labelledby="delivery-date-label"
+  aria-describedby={error ? "delivery-date-error" : undefined}
+  isInvalid={!!error}
+  value={value}
+  onChange={setValue}
+/>
+{error && <p id="delivery-date-error">{error}</p>}
+```
+
+Or let `Field.Root` wire the label, description, and error elements:
+
+```tsx
+<Field.Root name="deliveryDate" error={error ? { message: error } : undefined}>
+  <Field.Label>Delivery date</Field.Label>
+  <DatePicker value={value} onChange={setValue} />
+  <Field.Error match={!!error}>{error}</Field.Error>
+</Field.Root>
+```
+
+## Calendar
+
+A standalone calendar grid for custom date-selection UIs.
+
+```tsx
+<Calendar aria-label="Select date" onChange={(date) => console.log(date)} />
+```
+
+## DateRangePicker
+
+Start and end segmented inputs sharing one calendar popover, with a `{ start, end }` value (`DateRange`) — a **separate component** from `DatePicker`, not a mode. Same composition model as the other controls: standalone with `aria-*`, or inside `Field.Root`. Selection follows the react-aria model — the first calendar pick anchors the range and keeps the popover open, the highlight follows the pointer/arrows, and the second pick completes it; picking backwards swaps the endpoints, while a range **typed** in reverse is flagged invalid (`Field.Error match="customError"`) rather than swapped.
+
+```tsx
+const [range, setRange] = useState<DateRange | null>(null);
+
+// standalone
+<DateRangePicker aria-label="Billing period" value={range} onChange={setRange} />
+
+// composed
+<Field.Root name="period">
+  <Field.Label>Billing period</Field.Label>
+  <DateRangePicker />
+  <Field.Error match="customError" />
+</Field.Root>
+```
+
+A single combined proxy input is registered as the one Field control — its value is empty until **both** ends are complete, so `isRequired` blocks a partial range. Give that combined input a `name` for a single `start/end` native-POST field (a wrapping `Field.Root` name wins), or use `startName` / `endName` to emit two plain hidden inputs for classic form-POST.
+
+## RangeCalendar
+
+The standalone inline range calendar (the grid inside `DateRangePicker`), for custom layouts.
+
+```tsx
+<RangeCalendar aria-label="Stay dates" onChange={(range) => console.log(range)} />
+```
+
+## Localization
+
+Locale and timezone come from AppShell automatically. Override per field with `locale` / `timeZone`:
+
+```tsx
+<DatePicker aria-label="Date" locale="ja-JP" />
+```
+
+### Day of the week
+
+`showDayOfWeek` adds the locale's short day of the week where the locale places it — `2025/12/19(金)` for ja-JP, `Fri, 12/19/2025` for en-US. It is read-only and derived from the entered date: it shows a placeholder until the date is complete, and while a date segment is mid-entry it keeps the previous day of the week (muted), so typing `25` into the day never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.
+
+```tsx
+<DatePicker aria-label="Closing date" showDayOfWeek />
+```
+
+## Keyboard
+
+- **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
+- **Whole-date shortcuts:** `t` today · `m`/`h` start/end of the entered month · `y`/`r` start/end of the year · `w`/`k` start/end of the week · `-` previous day · `=`/`+` next day.
+- **Calendar grid:** arrows move by day/week, `Home`/`End` to week start/end, `PageUp`/`PageDown` by month, `Shift`+`PageUp`/`PageDown` by year, `Enter`/`Space` selects. `Alt`+`↓` opens the calendar from the field.
+
+## Props
+
+### DateFieldProps
+
+| Prop                             | Type                                                          | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                              |
+| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                                 |
+| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control          |
+| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                  |
+| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                             |
+| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                     |
+| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                      |
+| `isRequired`                     | `boolean`                                                     | Marks the control required                                   |
+| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI    |
+| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                         |
+| `granularity`                    | `"day" \| "hour" \| "minute" \| "second"`                     | Smallest editable unit; time granularities add time segments |
+| `hourCycle`                      | `12 \| 24`                                                    | Force 12- or 24-hour time; defaults to the locale            |
+| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                             |
+| `locale`                         | `string`                                                      | BCP-47 locale override                                       |
+| `showDayOfWeek`                  | `boolean`                                                     | Show the locale's short day of the week next to the date     |
+| `name`                           | `string`                                                      | Emits a form value through the proxy input                   |
+| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).        |
+| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts   |
+| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                              |
+| `aria-describedby`               | `string`                                                      | IDs of description / error elements                          |
+| `className`                      | `string`                                                      | Root element class                                           |
+
+### DatePickerProps
+
+All `DateFieldProps`, plus:
+
+| Prop             | Type                    | Description                         |
+| ---------------- | ----------------------- | ----------------------------------- |
+| `timeZone`       | `string`                | IANA timezone for resolving "today" |
+| `firstDayOfWeek` | `"sun" \| "mon" \| ...` | Force the calendar's first column   |
+
+### CalendarProps
+
+See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailable dates, focused date, locale, timezone, accessible naming, and className.
+
+### DateRangePickerProps
+
+The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `firstDayOfWeek`, `timeZone`, `locale`, `showDayOfWeek`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
+
+| Prop                     | Type                             | Description                                                                     |
+| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
+| `value` / `defaultValue` | `DateRange \| null`              | Controlled / uncontrolled `{ start, end }` range                                |
+| `onChange`               | `(v: DateRange \| null) => void` | Fires with a complete range, or `null` when cleared/incomplete                  |
+| `name`                   | `string`                         | One combined hidden input (`start/end`) for native POST; `Field.Root` name wins |
+| `startName` / `endName`  | `string`                         | Emit two plain hidden inputs with the ISO start/end (classic POST)              |
+
+A typed range with `end` before `start` sets the invalid state and reports a built-in `customError` message (`Field.Error match="customError"`); the calendar always commits ordered endpoints.
+
+### RangeCalendarProps
+
+Same surface as `CalendarProps`, with `value` / `defaultValue`: `DateRange | null` and `onChange`: `(v: DateRange) => void` (fired once per selection, when the second date completes the range).
+
+## Related
+
+- [useTimeZone](../api/use-time-zone.md)
+- [useResolvedLocale](../api/use-resolved-locale.md)

package/skills/app-shell-patterns/references/components/default-header.md

@@ -0,0 +1,75 @@
+---
+title: DefaultHeader
+description: The built-in SidebarLayout top bar, extensible via an actions slot
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/default-header.docs.outline.md — do not edit by hand. -->
+
+# DefaultHeader
+
+`DefaultHeader` is the built-in top bar rendered by [`SidebarLayout`](./sidebar-layout.md). It shows the sidebar trigger and breadcrumb trail on the left, and an `actions` cluster (defaulting to the [`AppearanceSwitcher`](./appearance-switcher.md)) on the right.
+
+It is exposed as `SidebarLayout.DefaultHeader` (and as a top-level `DefaultHeader` export) so you can slightly extend the built-in header — the common case being adding a notification bell or user menu — without reconstructing the trigger and breadcrumb yourself.
+
+## Import
+
+```tsx
+import { SidebarLayout } from "@tailor-platform/app-shell";
+// SidebarLayout.DefaultHeader
+
+// or, equivalently:
+import { DefaultHeader } from "@tailor-platform/app-shell";
+```
+
+## Usage
+
+`DefaultHeader` goes into `SidebarLayout`'s [`header`](./sidebar-layout.md#header) slot:
+
+```tsx
+import { SidebarLayout, AppearanceSwitcher, Button } from "@tailor-platform/app-shell";
+import { BellIcon } from "lucide-react";
+
+<SidebarLayout
+  header={
+    <SidebarLayout.DefaultHeader
+      actions={[
+        <Button key="bell" variant="outline" size="icon" aria-label="Notifications">
+          <BellIcon />
+        </Button>,
+        <AppearanceSwitcher key="appearance" />,
+      ]}
+    />
+  }
+/>;
+```
+
+## Props
+
+### actions
+
+- **Type:** `React.ReactNode | React.ReactNode[]` (optional)
+- **Default:** `[<AppearanceSwitcher />]`
+- **Description:** The entire right-hand cluster of the header. Rendered in a horizontal, vertically-centered row (`flex flex-row items-center gap-2`) with consistent spacing — you don't wrap it yourself. Accepts a single node or an array of nodes.
+
+> ⚠️ **`actions` replaces the whole right-hand cluster, including the appearance switcher.**
+>
+> - Omitting `actions` keeps the default (`[<AppearanceSwitcher />]`), so the out-of-the-box header is unchanged.
+> - If you pass your own `actions` and still want the switcher, include `<AppearanceSwitcher />` in the array — it is a public export.
+> - `actions={[]}` renders an empty right side.
+
+This "the switcher is just another action" contract keeps the API a single slot rather than accumulating one-off props like `hideAppearanceSwitcher`.
+
+## When to use which level of customization
+
+| Goal                              | Approach                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------- |
+| The standard header               | Omit `header` on `SidebarLayout`                                                |
+| Add controls next to the switcher | `header={<SidebarLayout.DefaultHeader actions={[...]} />}`                      |
+| A completely different header     | `header={<MyCustomHeader />}` (see [SidebarLayout](./sidebar-layout.md#header)) |
+
+## Related Components
+
+- [SidebarLayout](./sidebar-layout.md) - Hosts the header via the `header` slot
+- [DefaultSidebar](./default-sidebar.md) - The sibling built-in region (`SidebarLayout.DefaultSidebar`)
+- [AppearanceSwitcher](./appearance-switcher.md) - Default action; include it in `actions` to keep it
+- [Button](./button.md) - For building icon actions

package/skills/app-shell-patterns/references/components/default-sidebar.md

@@ -0,0 +1,136 @@
+---
+title: DefaultSidebar
+description: Built-in sidebar component for auto-generated or composed navigation, with optional search suppression and icon-rail mode
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/default-sidebar.docs.outline.md — do not edit by hand. -->
+
+# DefaultSidebar
+
+`DefaultSidebar` is the built-in sidebar used by [`SidebarLayout`](./sidebar-layout.md). It has two modes:
+
+- **Auto-generation mode** — omit `children` and it renders navigation from your AppShell modules and resources.
+- **Composition mode** — pass `children` and build the menu yourself with `SidebarItem`, `SidebarGroup`, `SidebarSeparator`, and the low-level `SidebarMenuItem` / `SidebarMenuButton` primitives.
+
+> Also available as **`SidebarLayout.DefaultSidebar`**. The namespaced form is preferred for discoverability; the top-level `DefaultSidebar` export is kept for backwards compatibility.
+
+## Props
+
+| Prop         | Type              | Default  | Description                                                                                             |
+| ------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `header`     | `React.ReactNode` | built-in | Replaces the sidebar header content.                                                                    |
+| `footer`     | `React.ReactNode` | -        | Footer content rendered after the navigation area.                                                      |
+| `children`   | `React.ReactNode` | -        | When provided, enables composition mode and disables auto-generation.                                   |
+| `hideHeader` | `boolean`         | `false`  | Hides the sidebar's own header row. Useful when a full-width top bar already owns the app title/toggle. |
+| `hideSearch` | `boolean`         | `false`  | Hides the built-in **Search** entry that opens the Command Palette.                                     |
+| `iconRail`   | `boolean`         | `false`  | Collapses to a persistent icon rail instead of sliding fully off-canvas.                                |
+
+## Basic usage
+
+```tsx
+import { SidebarLayout } from "@tailor-platform/app-shell";
+
+function Layout() {
+  return <SidebarLayout.DefaultSidebar />;
+}
+```
+
+## Composition mode
+
+```tsx
+import {
+  SidebarGroup,
+  SidebarItem,
+  SidebarLayout,
+  SidebarSeparator,
+} from "@tailor-platform/app-shell";
+
+function Layout() {
+  return (
+    <SidebarLayout.DefaultSidebar>
+      <SidebarItem to="/" />
+      <SidebarSeparator />
+      <SidebarGroup title="Main">
+        <SidebarItem to="/dashboard" />
+        <SidebarItem to="/orders" />
+      </SidebarGroup>
+    </SidebarLayout.DefaultSidebar>
+  );
+}
+```
+
+## Search entry
+
+The built-in **Search** entry opens AppShell's [`CommandPalette`](./command-palette.md). It is rendered in both auto-generated and composed navigation.
+
+Hide it only when search is already exposed elsewhere, such as a dedicated top-bar control:
+
+```tsx
+<SidebarLayout.DefaultSidebar hideSearch />
+```
+
+## Icon-rail behavior
+
+With `iconRail`, collapsing the sidebar keeps icons visible at every width:
+
+- on desktop, the sidebar collapses to a narrow persistent rail
+- on mobile, the rail stays visible and its toggle opens the full sidebar as a slide-in drawer
+- grouped items reveal child pages from the collapsed icon via a flyout popover
+- items without children show their label in a tooltip
+
+[`GlobalHeaderLayout`](./global-header-layout.md) bakes this mode in through `GlobalHeaderLayout.DefaultSidebar`.
+
+## Working with a global top bar
+
+When the app title and primary toggle live in a full-width top bar, hide the sidebar's own header:
+
+```tsx
+<SidebarLayout topBar={<MyGlobalTopBar />} sidebar={<SidebarLayout.DefaultSidebar hideHeader />} />
+```
+
+## Custom footer
+
+```tsx
+function UserProfile() {
+  return (
+    <div className="border-t p-4">
+      <p className="text-sm font-medium">Ada Lovelace</p>
+      <button type="button" className="mt-2 text-sm text-muted-foreground">
+        Logout
+      </button>
+    </div>
+  );
+}
+
+<SidebarLayout.DefaultSidebar footer={<UserProfile />} />;
+```
+
+## Low-level custom items
+
+When `SidebarItem` is too opinionated, compose a custom row with the exported primitives:
+
+```tsx
+import { SidebarLayout, SidebarMenuButton, SidebarMenuItem } from "@tailor-platform/app-shell";
+import { BellIcon } from "lucide-react";
+
+<SidebarLayout.DefaultSidebar>
+  <SidebarMenuItem>
+    <SidebarMenuButton
+      render={<button type="button" />}
+      onClick={() => openNotifications()}
+      tooltip="Notifications"
+    >
+      <BellIcon className="size-4" />
+      <span>Notifications</span>
+    </SidebarMenuButton>
+  </SidebarMenuItem>
+</SidebarLayout.DefaultSidebar>;
+```
+
+## Related
+
+- [SidebarLayout](./sidebar-layout.md) - layout wrapper for sidebar + content
+- [GlobalHeaderLayout](./global-header-layout.md) - opinionated app-wide header mode
+- [SidebarItem](./sidebar-item.md) - individual navigation links
+- [SidebarGroup](./sidebar-group.md) - collapsible navigation groups
+- [Sidebar Navigation](../concepts/sidebar-navigation.md) - navigation concepts and composition patterns