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: