An open source design system that's fully customizable and agent ready
TypeScript
feat(date): add weekStartsOn to DateInput, DateRangeInput, DateTimeInput (#4745)
freddymeta2ee5dc47b5ed
diff --git a/.changeset/date-week-start.md b/.changeset/date-week-start.mdnew file mode 100644index 0000000000..ef3fa0e3ca--- /dev/null+++ b/.changeset/date-week-start.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] DateInput, DateRangeInput, and DateTimeInput now accept a `weekStartsOn` prop that sets the first day of the week in the calendar popover (0 = Sunday … 6 = Saturday, or a three-letter day name like `"mon"`). It forwards to the underlying Calendar, whose default stays Sunday, so existing usage is unchanged.+@freddymetadiff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsxindex 93b89640de..ccf81fd20e 100644--- a/apps/storybook/stories/DateInput.stories.tsx+++ b/apps/storybook/stories/DateInput.stories.tsx@@ -58,6 +58,27 @@ const meta: Meta<typeof DateInput> = {options: [1, 2],description: 'Number of months to display in calendar',},+ weekStartsOn: {+ control: 'select',+ options: [+ 0,+ 1,+ 2,+ 3,+ 4,+ 5,+ 6,+ 'sun',+ 'mon',+ 'tue',+ 'wed',+ 'thu',+ 'fri',+ 'sat',+ ],+ description:+ 'First day of week in the calendar popover (0 = Sunday, or a three-letter day name)',+ },format: {control: 'select',options: ['date_long', 'date', 'date_weekday', 'system_date'],@@ -93,6 +114,19 @@ export const WithValue: Story = {},};+export const MondayFirstWeek: Story = {+ name: 'Week starts on Monday',+ render: args => {+ const [value, setValue] = useState<ISODateString | undefined>(undefined);+ return <DateInput {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date',+ placeholder: 'Select a date',+ weekStartsOn: 'mon',+ },+};+/*** The committed date value can be rendered in different shapes via `format`,* reusing `Timestamp`'s format vocabulary so the same literal renders the samediff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 7f46de22c3..e043eb8fbb 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -142,6 +142,13 @@ export const docs = {'Number of months displayed simultaneously in the calendar popover.',default: '1',},+ {+ name: 'weekStartsOn',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description:+ 'First day of week in the calendar popover. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',+ default: '0',+ },{name: 'format',type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",@@ -417,6 +424,12 @@ export const docsZh = {description: '日历弹出层中同时显示的月份数量。',default: '1',},+ {+ name: 'weekStartsOn',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description: '日历弹出层中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',+ default: '0',+ },{name: 'format',type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",@@ -520,6 +533,7 @@ export const docsDense = {labelTooltip: 'tooltip text via info icon at label end',hasClear: 'Shows clear button when date is set. Clears value on click.',numberOfMonths: 'months shown simultaneously in calendar popover',+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',format:"committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",xstyle: 'StyleX styles for layout; must be stylex.create() value',diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsxindex 88d40c00a2..305247876c 100644--- a/packages/core/src/DateInput/DateInput.test.tsx+++ b/packages/core/src/DateInput/DateInput.test.tsx@@ -949,6 +949,61 @@ describe('DateInput', () => {expect(screen.getByDisplayValue('Mar 10, 2026')).toBeInTheDocument();});});+ describe('weekStartsOn', () => {+ // The calendar popover renders in the top layer; jsdom keeps the content in+ // the DOM but role queries skip it, so read the columnheaders directly.+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {+ fireEvent.keyDown(screen.getByRole('combobox'), {key: 'ArrowDown'});+ return Array.from(container.querySelectorAll('[role="columnheader"]'))+ .slice(0, 7)+ .map(h => h.textContent);+ };++ it('defaults to a Sunday-first week', () => {+ const {container} = render(+ <DateInput label="Date" onChange={() => {}} />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Su',+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ ]);+ });++ it('forwards a numeric weekStartsOn to the calendar', () => {+ const {container} = render(+ <DateInput label="Date" onChange={() => {}} weekStartsOn={1} />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });++ it('accepts a three-letter day name', () => {+ const {container} = render(+ <DateInput label="Date" onChange={() => {}} weekStartsOn="mon" />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });+ });});describe('DateInput statusVariant forwarding', () => {diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsxindex 3170d1888c..c652c9aafc 100644--- a/packages/core/src/DateInput/DateInput.tsx+++ b/packages/core/src/DateInput/DateInput.tsx@@ -48,7 +48,13 @@ import {useInputGroup} from '../InputGroup/InputGroupContext';import {groupStyles} from '../InputGroup/groupStyles';import {useSize} from '../SizeContext/SizeContext';import {Spinner} from '../Spinner';-import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';+import {+ Calendar,+ type ISODateString,+ type CalendarHandle,+ type DayOfWeek,+ type DayOfWeekName,+} from '../Calendar';import {useCalendarConstraints} from '../Calendar/hooks';import {useInputStatusIcon} from '../hooks/useInputStatusIcon';import {usePopover} from '../Popover';@@ -311,6 +317,14 @@ export interface DateInputProps extends Omit<*/numberOfMonths?: 1 | 2;+ /**+ * First day of week in the calendar popover. Accepts a number+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',+ * case-insensitive).+ * @default 0+ */+ weekStartsOn?: DayOfWeek | DayOfWeekName;+/*** How the committed date value is displayed in the text field. Accepts a* named format reused from `Timestamp`'s `format` vocabulary (so the same@@ -377,6 +391,7 @@ export function DateInput({labelTooltip,hasClear = false,numberOfMonths = 1,+ weekStartsOn,format = 'date_long',width,xstyle,@@ -754,6 +769,7 @@ export function DateInput({max={max}dateConstraints={dateConstraints}numberOfMonths={numberOfMonths}+ weekStartsOn={weekStartsOn}/>,{placement: 'below', alignment: 'start'},)}diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjsindex 3ba5fbb347..396fbc3857 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs@@ -145,6 +145,13 @@ export const docs = {description: 'Number of months in the calendar.',default: '2',},+ {+ name: 'weekStartsOn',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description:+ 'First day of week in the calendar. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',+ default: '0',+ },{name: 'width',type: 'SizeValue',@@ -314,6 +321,7 @@ export const docsDense = {statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',labelTooltip: 'tooltip via info icon at label end',numberOfMonths: 'months in calendar (default 2)',+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',changeAction:'async action fired after onChange; drives optimistic UI updates via useTransition',isLoading: 'loading state; disables interaction + shows a spinner',diff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsxindex f3436f6254..21c6a34562 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx@@ -511,6 +511,72 @@ describe('DateRangeInput statusVariant forwarding', () => {'detached',);});++ describe('weekStartsOn', () => {+ // The calendar popover renders in the top layer; jsdom keeps the content in+ // the DOM but role queries skip it, so read the columnheaders directly.+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {+ fireEvent.click(getButton('Open calendar'));+ return Array.from(container.querySelectorAll('[role="columnheader"]'))+ .slice(0, 7)+ .map(h => h.textContent);+ };++ it('defaults to a Sunday-first week', () => {+ const {container} = render(+ <DateRangeInput label="Range" value={null} onChange={() => {}} />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Su',+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ ]);+ });++ it('forwards a numeric weekStartsOn to the calendar', () => {+ const {container} = render(+ <DateRangeInput+ label="Range"+ value={null}+ onChange={() => {}}+ weekStartsOn={1}+ />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });++ it('accepts a three-letter day name', () => {+ const {container} = render(+ <DateRangeInput+ label="Range"+ value={null}+ onChange={() => {}}+ weekStartsOn="mon"+ />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });+ });});describe('DateRangeInput icon theme targets', () => {diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsxindex c1e3e4235e..bddb89fa4a 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx@@ -45,7 +45,13 @@ import {} from '../Field';import {Icon} from '../Icon';import {Spinner} from '../Spinner';-import {Calendar, type ISODateString, type DateRange} from '../Calendar';+import {+ Calendar,+ type ISODateString,+ type DateRange,+ type DayOfWeek,+ type DayOfWeekName,+} from '../Calendar';import {usePopover} from '../Popover';import {useTooltip} from '../Tooltip';import {mergeProps} from '../utils';@@ -355,6 +361,14 @@ export interface DateRangeInputProps extends Omit<* @default 2*/numberOfMonths?: 1 | 2;++ /**+ * First day of week in the calendar. Accepts a number+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',+ * case-insensitive).+ * @default 0+ */+ weekStartsOn?: DayOfWeek | DayOfWeekName;}/**@@ -396,6 +410,7 @@ export function DateRangeInput({statusVariant = 'attached',labelTooltip,numberOfMonths = 2,+ weekStartsOn,width,xstyle,className,@@ -667,6 +682,7 @@ export function DateRangeInput({max={max}dateConstraints={dateConstraints}numberOfMonths={numberOfMonths}+ weekStartsOn={weekStartsOn}/></div>,{placement: 'below', alignment: 'start'},diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjsindex 3263b399a0..252861cbcb 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs@@ -173,6 +173,13 @@ export const docs = {description: 'Number of months displayed simultaneously in the calendar.',default: '1',},+ {+ name: 'weekStartsOn',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description:+ 'First day of week in the calendar. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',+ default: '0',+ },{name: 'width',type: 'SizeValue',@@ -477,6 +484,12 @@ export const docsZh = {description: '日历中同时显示的月份数量。',default: '1',},+ {+ name: 'weekStartsOn',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description: '日历中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',+ default: '0',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -577,6 +590,7 @@ export const docsDense = {status: 'error/warning/success status w/ message',labelTooltip: 'tooltip text via info icon at label end',numberOfMonths: 'months shown simultaneously in calendar',+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',xstyle: 'StyleX styles for layout; must be stylex.create() value',},};diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsxindex 098026f731..9157c910be 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx@@ -820,6 +820,62 @@ describe('DateTimeInput', () => {expect(onChange.mock.calls[0][0]).toContain('14:31');});});++ describe('weekStartsOn', () => {+ // The calendar popover renders in the top layer; jsdom keeps the content in+ // the DOM but role queries skip it, so read the columnheaders directly.+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {+ fireEvent.keyDown(screen.getAllByRole('combobox')[0], {key: 'ArrowDown'});+ return Array.from(container.querySelectorAll('[role="columnheader"]'))+ .slice(0, 7)+ .map(h => h.textContent);+ };++ it('defaults to a Sunday-first week', () => {+ const {container} = render(+ <DateTimeInput label="When" onChange={() => {}} />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Su',+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ ]);+ });++ it('forwards a numeric weekStartsOn to the calendar', () => {+ const {container} = render(+ <DateTimeInput label="When" onChange={() => {}} weekStartsOn={1} />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });++ it('accepts a three-letter day name', () => {+ const {container} = render(+ <DateTimeInput label="When" onChange={() => {}} weekStartsOn="mon" />,+ );+ expect(openAndReadWeekdays(container)).toEqual([+ 'Mo',+ 'Tu',+ 'We',+ 'Th',+ 'Fr',+ 'Sa',+ 'Su',+ ]);+ });+ });// ===========================================================================// Segment theme targets (#4075)// ===========================================================================diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsxindex df99e881d0..d82018677b 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx@@ -47,7 +47,13 @@ import {import {Icon} from '../Icon';import {VisuallyHidden} from '../VisuallyHidden';import {Spinner} from '../Spinner';-import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';+import {+ Calendar,+ type ISODateString,+ type CalendarHandle,+ type DayOfWeek,+ type DayOfWeekName,+} from '../Calendar';import {useCalendarConstraints} from '../Calendar/hooks';import {usePopover} from '../Popover';import {useTooltip} from '../Tooltip';@@ -348,6 +354,14 @@ export interface DateTimeInputProps extends Omit<* @default 1*/numberOfMonths?: 1 | 2;++ /**+ * First day of week in the calendar. Accepts a number+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',+ * case-insensitive).+ * @default 0+ */+ weekStartsOn?: DayOfWeek | DayOfWeekName;}function splitDateTime(dt: ISODateTimeString | undefined): {@@ -425,6 +439,7 @@ export function DateTimeInput({status,labelTooltip,numberOfMonths = 1,+ weekStartsOn,width,xstyle,className,@@ -1050,6 +1065,7 @@ export function DateTimeInput({max={calendarMax}dateConstraints={dateConstraints}numberOfMonths={numberOfMonths}+ weekStartsOn={weekStartsOn}/>,{placement: 'below', alignment: 'start'},)}