Skip to content

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.md
new file mode 100644
index 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)
+@durvesh1992
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 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.tsx
index 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 disabled
const 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 selection
diff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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;