An open source design system that's fully customizable and agent ready
TypeScript
feat(core): Calendar weekStartsOn accepts 3-letter day names (#2843) (#3257)
Durvesh Pilankarcac8ed594d4c
diff --git a/.changeset/calendar-weekstartson-names.md b/.changeset/calendar-weekstartson-names.mdnew file mode 100644index 0000000000..175b991268--- /dev/null+++ b/.changeset/calendar-weekstartson-names.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] Calendar: `weekStartsOn` now also accepts a three-letter day name (`'sun'`–`'sat'`, case-insensitive) in addition to the numeric `0`–`6`, so the starting day is self-documenting at the call site (e.g. `weekStartsOn="mon"`). Numbers keep working unchanged. Adds an exported `DayOfWeekName` type and a `normalizeDayOfWeek` helper (#2843)+@durvesh1992diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjsindex 18be2684f9..cc16890b32 100644--- a/packages/core/src/Calendar/Calendar.doc.mjs+++ b/packages/core/src/Calendar/Calendar.doc.mjs@@ -103,8 +103,8 @@ export const docs = {},{name: 'weekStartsOn',- type: '0 | 1 | 2 | 3 | 4 | 5 | 6',- description: 'First day of week (0=Sunday).',+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",+ description: 'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',default: '0',},],@@ -147,7 +147,7 @@ export const docsZh = {{name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},{name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},{name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},- {name: 'weekStartsOn', type: '0 | 1 | 2 | 3 | 4 | 5 | 6', description: '每周起始日(0=周日)。', default: '0'},+ {name: 'weekStartsOn', type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun'…'sat'", description: '每周起始日。可为数字(0=周日)或三字母星期缩写(如 "mon")。', default: '0'},],theming: {targets: [@@ -200,6 +200,6 @@ export const docsDense = {hasOutsideDays: 'show days from adjacent months',hasWeekNumbers: 'show ISO week numbers',hasVariableRowCount: 'variable vs fixed 6-row grid',- weekStartsOn: 'first day of week (0=Sunday)',+ weekStartsOn: 'first day of week (0=Sunday, or name e.g. "mon")',},};diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsxindex 36eb0c37a8..19ae547579 100644--- a/packages/core/src/Calendar/Calendar.test.tsx+++ b/packages/core/src/Calendar/Calendar.test.tsx@@ -146,10 +146,7 @@ describe('Calendar', () => {const handleFocusChange = vi.fn();render(- <Calendar- focusDate="2026-01-01"- onFocusDateChange={handleFocusChange}- />,+ <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,);const nextButton = screen.getByRole('button', {name: 'Next month'});@@ -189,9 +186,7 @@ describe('Calendar', () => {return day !== 0 && day !== 6;};- render(- <Calendar focusDate="2026-01-01" dateConstraints={[isWeekday]} />,- );+ render(<Calendar focusDate="2026-01-01" dateConstraints={[isWeekday]} />);// January 4, 2026 is a Sunday - should be disabledconst sunday = getDayButton(4);@@ -238,6 +233,21 @@ describe('Calendar', () => {expect(dayNames[0]).toHaveTextContent('Mo');});+ it('accepts a three-letter day name for weekStartsOn', () => {+ render(<Calendar weekStartsOn="mon" />);++ // "mon" should behave exactly like the numeric 1 (Monday first).+ const dayNames = screen.getAllByText(/^(Mo|Tu|We|Th|Fr|Sa|Su)$/);+ expect(dayNames[0]).toHaveTextContent('Mo');+ });++ it('treats weekStartsOn day names case-insensitively', () => {+ render(<Calendar weekStartsOn={'WED' as 'wed'} />);++ const dayNames = screen.getAllByText(/^(Mo|Tu|We|Th|Fr|Sa|Su)$/);+ expect(dayNames[0]).toHaveTextContent('We');+ });+// ─── Range Mode ──────────────────────────────────────────────it('supports range selection mode', async () => {@@ -245,11 +255,7 @@ describe('Calendar', () => {const handleChange = vi.fn();render(- <Calendar- mode="range"- onChange={handleChange}- focusDate="2026-01-01"- />,+ <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,);// Click start date@@ -271,11 +277,7 @@ describe('Calendar', () => {const handleChange = vi.fn();render(- <Calendar- mode="range"- onChange={handleChange}- focusDate="2026-01-01"- />,+ <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,);// Click later date first@@ -346,10 +348,7 @@ describe('Calendar', () => {const handleFocusChange = vi.fn();render(- <Calendar- focusDate="2026-01-01"- onFocusDateChange={handleFocusChange}- />,+ <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,);// Focus Jan 28@@ -414,11 +413,7 @@ describe('Calendar', () => {const handleChange = vi.fn();render(- <Calendar- mode="range"- onChange={handleChange}- focusDate="2026-01-01"- />,+ <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,);// Click start date to begin range selectiondiff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsxindex c82bef2f45..e27967d857 100644--- a/packages/core/src/Calendar/Calendar.tsx+++ b/packages/core/src/Calendar/Calendar.tsx@@ -70,8 +70,19 @@ import {// Types// =============================================================================-export type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';-import type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';+export type {+ ISODateString,+ DayOfWeek,+ DayOfWeekName,+ DateRange,+} from '../utils/dateTypes';+import type {+ ISODateString,+ DayOfWeek,+ DayOfWeekName,+ DateRange,+} from '../utils/dateTypes';+import {normalizeDayOfWeek} from '../utils/dateTypes';import {themeProps} from '../utils/themeProps';/** Imperative handle for Calendar handleRef */@@ -134,10 +145,11 @@ interface CalendarBaseProps extends Omit<hasVariableRowCount?: boolean;/**- * First day of week.+ * First day of week. Accepts a number (0 = Sunday … 6 = Saturday) or a+ * three-letter day name ('sun'–'sat', case-insensitive) for readability.* Default: 0 (Sunday)*/- weekStartsOn?: DayOfWeek;+ weekStartsOn?: DayOfWeek | DayOfWeekName;}// ─── Mode-specific Props (discriminated union) ────────────────@@ -200,13 +212,17 @@ export function Calendar({ref, ...props}: CalendarProps) {hasOutsideDays = true,hasWeekNumbers = false,hasVariableRowCount = false,- weekStartsOn = 0,+ weekStartsOn: weekStartsOnProp = 0,xstyle,className,style,...rest} = props;+ // Normalize `weekStartsOn` (number or three-letter day name) to a numeric+ // DayOfWeek so all downstream date math keeps working with an index.+ const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);+// Today's date (memoized)const today = useMemo(() => plainDateToday(), []);diff --git a/packages/core/src/Calendar/index.ts b/packages/core/src/Calendar/index.tsindex 63bc27d173..92f76874da 100644--- a/packages/core/src/Calendar/index.ts+++ b/packages/core/src/Calendar/index.ts@@ -17,6 +17,7 @@ export type {CalendarHandle,ISODateString,DayOfWeek,+ DayOfWeekName,DateRange,} from './Calendar';diff --git a/packages/core/src/utils/dateTypes.test.ts b/packages/core/src/utils/dateTypes.test.tsnew file mode 100644index 0000000000..7d334fa0d7--- /dev/null+++ b/packages/core/src/utils/dateTypes.test.ts@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file dateTypes.test.ts+ * @input Uses vitest+ * @output Test suite for date type helpers+ * @position Tests for dateTypes.ts (normalizeDayOfWeek)+ *+ * SYNC: When dateTypes.ts changes, update tests accordingly+ */++import {describe, it, expect} from 'vitest';+import {normalizeDayOfWeek} from './dateTypes';++describe('normalizeDayOfWeek', () => {+ it('passes numeric days through unchanged', () => {+ expect(normalizeDayOfWeek(0)).toBe(0);+ expect(normalizeDayOfWeek(1)).toBe(1);+ expect(normalizeDayOfWeek(6)).toBe(6);+ });++ it('maps three-letter day names to their index', () => {+ expect(normalizeDayOfWeek('sun')).toBe(0);+ expect(normalizeDayOfWeek('mon')).toBe(1);+ expect(normalizeDayOfWeek('tue')).toBe(2);+ expect(normalizeDayOfWeek('wed')).toBe(3);+ expect(normalizeDayOfWeek('thu')).toBe(4);+ expect(normalizeDayOfWeek('fri')).toBe(5);+ expect(normalizeDayOfWeek('sat')).toBe(6);+ });++ it('is case-insensitive for day names', () => {+ expect(normalizeDayOfWeek('MON' as 'mon')).toBe(1);+ expect(normalizeDayOfWeek('Sat' as 'sat')).toBe(6);+ });++ it('falls back to 0 (Sunday) for an unrecognized name', () => {+ expect(normalizeDayOfWeek('xyz' as 'mon')).toBe(0);+ });+});diff --git a/packages/core/src/utils/dateTypes.ts b/packages/core/src/utils/dateTypes.tsindex b9879f04ac..75fa00bcb5 100644--- a/packages/core/src/utils/dateTypes.ts+++ b/packages/core/src/utils/dateTypes.ts@@ -17,6 +17,46 @@ export type ISODateString =/** Day of week: 0 = Sunday through 6 = Saturday */export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;+/**+ * Three-letter lowercase weekday name, 'sun' through 'sat'.+ * A more self-documenting alternative to the numeric {@link DayOfWeek}.+ */+export type DayOfWeekName =+ | 'sun'+ | 'mon'+ | 'tue'+ | 'wed'+ | 'thu'+ | 'fri'+ | 'sat';++/** Weekday names indexed by {@link DayOfWeek} (0 = Sunday). */+const WEEKDAY_NAMES: ReadonlyArray<DayOfWeekName> = [+ 'sun',+ 'mon',+ 'tue',+ 'wed',+ 'thu',+ 'fri',+ 'sat',+];++/**+ * Normalize a weekday to its numeric {@link DayOfWeek}. Accepts either a+ * number (0–6) or a three-letter day name ('sun'–'sat', case-insensitive),+ * so APIs like `weekStartsOn` can take whichever is more readable at the+ * call site. Unrecognized values fall back to 0 (Sunday).+ */+export function normalizeDayOfWeek(+ value: DayOfWeek | DayOfWeekName,+): DayOfWeek {+ if (typeof value === 'number') {+ return value;+ }+ const index = WEEKDAY_NAMES.indexOf(value.toLowerCase() as DayOfWeekName);+ return index === -1 ? 0 : (index as DayOfWeek);+}+/** Immutable date record with 1-based month. */export interface PlainDate {readonly year: number;