diff --git a/.changeset/clear-dates-return.md b/.changeset/clear-dates-return.md
new file mode 100644
index 000000000..a1fd5afb4
--- /dev/null
+++ b/.changeset/clear-dates-return.md
@@ -0,0 +1,6 @@
+---
+"@tailor-platform/app-shell": patch
+---
+
+Correct the DatePicker documentation and migration examples to use `useTimeZone().today()` instead of a standalone `today` import.
+Keep date constraints aligned with AppShell's configured timezone, and clarify how to obtain the current date and time without adding public exports.
diff --git a/docs-manifest.json b/docs-manifest.json
index 900048d9d..79598ede2 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -501,9 +501,9 @@
],
"hashes": {
"typeSurface": "a0f5522359e8f81d",
- "outline": "3144450969e87c0a",
+ "outline": "adc21f4e13532e09",
"snapshot": null,
- "outputMd": "d4b478c7ba8304d5",
+ "outputMd": "b7302d55df8907bc",
"examples": null
}
},
@@ -1130,9 +1130,9 @@
"symbols": [],
"hashes": {
"typeSurface": null,
- "outline": "80dfe11d696ce694",
+ "outline": "e88bb360eb853c34",
"snapshot": null,
- "outputMd": "af237de157fd8691",
+ "outputMd": "19ca77c7802ca5f6",
"examples": null
}
},
@@ -1773,9 +1773,9 @@
"symbols": [],
"hashes": {
"typeSurface": null,
- "outline": "0453e622960d3c3a",
+ "outline": "44c8aac9cb791bd9",
"snapshot": null,
- "outputMd": "30c15545ab3c4954",
+ "outputMd": "aaf63f2f33d6665e",
"examples": null
}
},
@@ -1841,7 +1841,7 @@
"packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a",
"packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc",
"packages/core/skills/app-shell-patterns/references/components/data-table.md": "06f3ce2174fda10a",
- "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "d4b478c7ba8304d5",
+ "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "b7302d55df8907bc",
"packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be",
"packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "9b1672c71b6db3ff",
"packages/core/skills/app-shell-patterns/references/components/description-card.md": "a347fd1f4ccd433e",
@@ -1896,7 +1896,7 @@
"packages/core/skills/app-shell-patterns/references/api/use-resolved-locale.md": "d0eb9f125c314d85",
"packages/core/skills/app-shell-patterns/references/api/use-route-error.md": "1a44180ec84ce4b9",
"packages/core/skills/app-shell-patterns/references/api/use-theme.md": "c338022de386d5e4",
- "packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "30c15545ab3c4954",
+ "packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "aaf63f2f33d6665e",
"packages/core/skills/app-shell-patterns/references/api/use-toast.md": "30983a761bc61593",
"packages/core/skills/app-shell-patterns/references/patterns/form-composer.md": "ed187ac3a0773d3d",
"packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "a0d3c952b0b10351",
@@ -1910,7 +1910,7 @@
"packages/core/skills/app-shell-patterns/references/pages/document-collection.md": "e79d9120d86db198",
"packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "e07c7fee2478a21d",
"packages/core/skills/app-shell-patterns/SKILL.md": "18efee79280174e7",
- "packages/core/skills/app-shell-upgrade/references/migrations.md": "2b1c0ad9006a3c55",
+ "packages/core/skills/app-shell-upgrade/references/migrations.md": "9bd2735c34fd35e3",
"packages/core/skills/app-shell-upgrade/SKILL.md": "f9be942f3e596c00"
}
}
diff --git a/docs-src/components/date-picker.docs.outline.md b/docs-src/components/date-picker.docs.outline.md
index 669f2895c..0f5fd9f23 100644
--- a/docs-src/components/date-picker.docs.outline.md
+++ b/docs-src/components/date-picker.docs.outline.md
@@ -21,10 +21,9 @@ import {
Calendar,
RangeCalendar,
Field,
+ useTimeZone,
// Date value helpers (re-exported from @internationalized/date)
parseDate,
- getLocalTimeZone,
- today,
type CalendarDate,
type DateValue,
type DateRange,
@@ -89,19 +88,29 @@ A `DateField` with a calendar popover.
Constrained + unavailable dates:
+Use [`useTimeZone()`](../api/use-time-zone.md) to obtain today's date in AppShell's configured timezone, rather than calculating against the browser's timezone directly.
+
```tsx
-
- {
- const dow = date.toDate(getLocalTimeZone()).getDay();
- return dow === 0 || dow === 6; // weekends
- }}
-/>
+function DeliveryDatePicker() {
+ const timeZone = useTimeZone();
+
+ return (
+ <>
+
+ {
+ const dow = date.toDate("UTC").getUTCDay();
+ return dow === 0 || dow === 6; // weekends
+ }}
+ />
+ >
+ );
+}
```
Week start:
diff --git a/docs-src/guides/migrations.docs.outline.md b/docs-src/guides/migrations.docs.outline.md
index 3750f3ffa..8387819fe 100644
--- a/docs-src/guides/migrations.docs.outline.md
+++ b/docs-src/guides/migrations.docs.outline.md
@@ -167,27 +167,33 @@ The date controls now follow the same composition model as `Field`, `Select`, `C
TypeScript will error on the removed props; delete them and compose with `Field.Root` instead.
+Both examples use `useTimeZone()` at the top level of the component so the minimum date follows AppShell's configured timezone.
+
Before:
```tsx
+const timeZone = useTimeZone();
+
+/>;
```
After:
```tsx
+const timeZone = useTimeZone();
+
Delivery date
-
+ When should we ship your order?{error}
-
+;
```
`isInvalid` remains a top-level prop for externally-controlled invalid styling. Semantic date props (`isRequired`, `isDisabled`, `isReadOnly`, `minValue`, `maxValue`, `isDateUnavailable`) remain top-level and unchanged. Standalone usage still works with an accessible name:
diff --git a/docs-src/hooks/use-time-zone.docs.outline.md b/docs-src/hooks/use-time-zone.docs.outline.md
index 96ff2173b..58fd3af52 100644
--- a/docs-src/hooks/use-time-zone.docs.outline.md
+++ b/docs-src/hooks/use-time-zone.docs.outline.md
@@ -11,6 +11,10 @@ React hook that returns a `TimeZone` object for the timezone configured on `AppS
Date/time components (`DateField`, `DatePicker`, `Calendar`) consume this hook automatically — use it when you need the same timezone in custom components.
+For the current date or time in React components, use `timeZone.today()` or `timeZone.now()` rather than importing standalone `today` or `now` helpers from AppShell. These methods respect AppShell's `timeZone` setting; calculating against the browser's timezone directly can produce a different date.
+
+Both methods read the current clock when called. They do not schedule re-renders when the date or time changes.
+
## Signature
```typescript
diff --git a/docs/api/use-time-zone.md b/docs/api/use-time-zone.md
index 0f6374a3a..59ec39c95 100644
--- a/docs/api/use-time-zone.md
+++ b/docs/api/use-time-zone.md
@@ -11,6 +11,10 @@ React hook that returns a `TimeZone` object for the timezone configured on `AppS
Date/time components (`DateField`, `DatePicker`, `Calendar`) consume this hook automatically — use it when you need the same timezone in custom components.
+For the current date or time in React components, use `timeZone.today()` or `timeZone.now()` rather than importing standalone `today` or `now` helpers from AppShell. These methods respect AppShell's `timeZone` setting; calculating against the browser's timezone directly can produce a different date.
+
+Both methods read the current clock when called. They do not schedule re-renders when the date or time changes.
+
## Signature
```typescript
diff --git a/docs/components/date-picker.md b/docs/components/date-picker.md
index a6efdb8ad..50e2fd58a 100644
--- a/docs/components/date-picker.md
+++ b/docs/components/date-picker.md
@@ -19,10 +19,9 @@ import {
Calendar,
RangeCalendar,
Field,
+ useTimeZone,
// Date value helpers (re-exported from @internationalized/date)
parseDate,
- getLocalTimeZone,
- today,
type CalendarDate,
type DateValue,
type DateRange,
@@ -87,19 +86,29 @@ A `DateField` with a calendar popover.
Constrained + unavailable dates:
+Use [`useTimeZone()`](../api/use-time-zone.md) to obtain today's date in AppShell's configured timezone, rather than calculating against the browser's timezone directly.
+
```tsx
-
- {
- const dow = date.toDate(getLocalTimeZone()).getDay();
- return dow === 0 || dow === 6; // weekends
- }}
-/>
+function DeliveryDatePicker() {
+ const timeZone = useTimeZone();
+
+ return (
+ <>
+
+ {
+ const dow = date.toDate("UTC").getUTCDay();
+ return dow === 0 || dow === 6; // weekends
+ }}
+ />
+ >
+ );
+}
```
Week start:
diff --git a/docs/migrations.md b/docs/migrations.md
index 2a379d76a..ba49b357a 100644
--- a/docs/migrations.md
+++ b/docs/migrations.md
@@ -167,27 +167,33 @@ The date controls now follow the same composition model as `Field`, `Select`, `C
TypeScript will error on the removed props; delete them and compose with `Field.Root` instead.
+Both examples use `useTimeZone()` at the top level of the component so the minimum date follows AppShell's configured timezone.
+
Before:
```tsx
+const timeZone = useTimeZone();
+
+/>;
```
After:
```tsx
+const timeZone = useTimeZone();
+
Delivery date
-
+ When should we ship your order?{error}
-
+;
```
`isInvalid` remains a top-level prop for externally-controlled invalid styling. Semantic date props (`isRequired`, `isDisabled`, `isReadOnly`, `minValue`, `maxValue`, `isDateUnavailable`) remain top-level and unchanged. Standalone usage still works with an accessible name: