Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Calendar docs page and block examples (#1555)

rubyycheunge6bb6eb47bad
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.doc.mjs
new file mode 100644
index 0000000000..351e0c38c1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Calendar — Constraints',
+ description: 'Limit which dates can be selected using min/max bounds and custom rules like weekdays only. Use for scheduling UIs where certain dates are unavailable.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Calendar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.tsx
new file mode 100644
index 0000000000..1fbdfe7176
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarConstraints.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const isWeekday = (date: Date) => {
+ const day = date.getDay();
+ return day !== 0 && day !== 6;
+};
+
+export default function CalendarConstraints() {
+ const [value, setValue] = useState<ISODateString | undefined>(undefined);
+
+ return (
+ <XDSStack direction="vertical" gap={4} hAlign="center">
+ <XDSText type="supporting" color="secondary">
+ Jan 10 – Mar 20, weekdays only
+ </XDSText>
+ <XDSCalendar
+ mode="single"
+ min={'2026-01-10' as ISODateString}
+ max={'2026-03-20' as ISODateString}
+ dateConstraints={[isWeekday]}
+ value={value}
+ onChange={val => setValue(val)}
+ focusDate={'2026-01-01' as ISODateString}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.doc.mjs
deleted file mode 100644
index 0c04271ab0..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Calendar — Min/Max Boundaries',
- description:
- 'Calendar with min and max date boundaries restricting selectable dates.',
- isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Calendar'],
-};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.tsx
deleted file mode 100644
index 56d864c137..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarMinMaxBoundary.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
-
-export default function CalendarMinMaxBoundary() {
- const [value, setValue] = useState<ISODateString | undefined>(undefined);
- return (
- <XDSCalendar
- mode="single"
- min={'2026-01-10' as ISODateString}
- max={'2026-03-20' as ISODateString}
- value={value}
- onChange={val => setValue(val)}
- focusDate={'2026-01-01' as ISODateString}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.doc.mjs
index b6593da44c..ec2294d4e4 100644
--- a/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.doc.mjs
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Calendar — Range Selection',
- description:
- 'Calendar in range mode with a pre-selected start and end date.',
+ name: 'Calendar — Range',
+ description: 'Pick a start and end date with the range highlighted between them. Use for booking dates, time-off requests, or report filters.',
isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Calendar'],
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Calendar', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.tsx
index f750936e83..3fb50efcf6 100644
--- a/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.tsx
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarRangeWithValue.tsx
@@ -2,18 +2,28 @@
import {useState} from 'react';
import {XDSCalendar, type DateRange} from '@xds/core/Calendar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function CalendarRangeWithValue() {
const [value, setValue] = useState<DateRange>({
start: '2026-01-10',
end: '2026-01-20',
});
+
return (
- <XDSCalendar
- mode="range"
- value={value}
- onChange={range => setValue(range)}
- focusDate="2026-01-01"
- />
+ <XDSStack direction="vertical" gap={4} hAlign="center">
+ <XDSText type="supporting" color="secondary">
+ {value.start && value.end
+ ? `${value.start} → ${value.end}`
+ : 'Pick a start and end date'}
+ </XDSText>
+ <XDSCalendar
+ mode="range"
+ value={value}
+ onChange={range => setValue(range)}
+ focusDate="2026-01-01"
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarSingle.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarSingle.doc.mjs
new file mode 100644
index 0000000000..4ad7bf4e9c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarSingle.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Calendar — Single',
+ description: 'Pick one date from a month grid. Use for appointment dates, due dates, or any field that needs a single date.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Calendar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarSingle.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarSingle.tsx
new file mode 100644
index 0000000000..c3f58d954b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarSingle.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function CalendarSingle() {
+ const [value, setValue] = useState<ISODateString>('2026-01-15');
+
+ return (
+ <XDSStack direction="vertical" gap={4} hAlign="center">
+ <XDSText type="supporting" color="secondary">
+ {value ? `Selected: ${value}` : 'Pick a date'}
+ </XDSText>
+ <XDSCalendar
+ mode="single"
+ value={value}
+ onChange={val => setValue(val)}
+ focusDate="2026-01-01"
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.doc.mjs
index 3ff1509999..4ac81af5cd 100644
--- a/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.doc.mjs
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.doc.mjs
@@ -2,8 +2,8 @@
export const doc = {
type: 'block',
name: 'Calendar — Two Months',
- description: 'Calendar displaying two months side by side for easier date selection.',
+ description: 'Two months side by side for selecting ranges that span a month boundary. Use in booking or travel UIs where check-in and check-out often fall in different months.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Calendar'],
+ componentsUsed: ['Calendar', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.tsx
index f98a59f631..253782ffb1 100644
--- a/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.tsx
+++ b/packages/cli/templates/blocks/components/Calendar/CalendarTwoMonths.tsx
@@ -1,17 +1,30 @@
'use client';
import {useState} from 'react';
-import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
+import {XDSCalendar, type DateRange} from '@xds/core/Calendar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function CalendarTwoMonths() {
- const [value, setValue] = useState<ISODateString | undefined>(undefined);
+ const [value, setValue] = useState<DateRange>({
+ start: '2026-01-25',
+ end: '2026-02-05',
+ });
+
return (
- <XDSCalendar
- mode="single"
- numberOfMonths={2}
- value={value}
- onChange={val => setValue(val)}
- focusDate="2026-01-01"
- />
+ <XDSStack direction="vertical" gap={4} hAlign="center">
+ <XDSText type="supporting" color="secondary">
+ {value.start && value.end
+ ? `${value.start} → ${value.end}`
+ : 'Pick a date range'}
+ </XDSText>
+ <XDSCalendar
+ mode="range"
+ numberOfMonths={2}
+ value={value}
+ onChange={range => setValue(range)}
+ focusDate="2026-01-01"
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.doc.mjs
deleted file mode 100644
index c9d364511e..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Calendar — Weekdays Only',
- description:
- 'Calendar with a date constraint that disables weekend selection.',
- isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Calendar'],
-};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.tsx
deleted file mode 100644
index 46e9974df6..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarWeekdaysOnly.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
-
-export default function CalendarWeekdaysOnly() {
- const [value, setValue] = useState<ISODateString | undefined>(undefined);
-
- const isWeekday = (date: Date) => {
- const day = date.getDay();
- return day !== 0 && day !== 6;
- };
-
- return (
- <XDSCalendar
- mode="single"
- dateConstraints={[isWeekday]}
- value={value}
- onChange={val => setValue(val)}
- focusDate="2026-01-01"
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.doc.mjs b/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.doc.mjs
deleted file mode 100644
index e95b282bcd..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Calendar — Pre-selected Date',
- description:
- 'Single-date calendar initialized with a pre-selected date value.',
- isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Calendar'],
-};
diff --git a/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.tsx b/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.tsx
deleted file mode 100644
index 0cc1dd552f..0000000000
--- a/packages/cli/templates/blocks/components/Calendar/CalendarWithSelectedDate.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
-
-export default function CalendarWithSelectedDate() {
- const [value, setValue] = useState<ISODateString>('2026-01-15');
- return (
- <XDSCalendar
- mode="single"
- value={value}
- onChange={val => setValue(val)}
- focusDate="2026-01-01"
- />
- );
-}
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 1352ed310c..072aa04924 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -5,12 +5,20 @@ export const docs = {
keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
usage: {
description:
- 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ 'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
- {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
- {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
+ {guidance: true, description: 'Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.'},
+ {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
+ {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
+ {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
+ {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without context — the user should understand why dates are unavailable.'},
+ ],
+ anatomy: [
+ {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months.'},
+ {name: 'Day grid', required: true, description: 'A 7-column grid of days with column headers for the day names.'},
+ {name: 'Selected day', required: false, description: 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.'},
+ {name: 'Today marker', required: false, description: 'A subtle indicator on the current date for orientation.'},
],
},
props: [
@@ -104,12 +112,14 @@ export const docsZh = {
name: 'Calendar',
usage: {
description:
- 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ 'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
- {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
- {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
+ {guidance: true, description: 'Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.'},
+ {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
+ {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
+ {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
+ {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without context — the user should understand why dates are unavailable.'},
],
},
props: [
@@ -151,15 +161,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'calendar for date selection w/ single+range modes',
+ description: 'month grid for picking a date or date range',
usage: {
description:
- 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ 'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
- {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
- {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
+ {guidance: true, description: 'Set min/max to limit selection. Use range mode for start + end dates.'},
+ {guidance: true, description: 'Use dateConstraints to disable weekends/holidays. Show two months for cross-month selections.'},
+ {guidance: false, description: 'Use for dates far in the past/future — text input is faster.'},
+ {guidance: false, description: 'Disable dates without explaining why.'},
],
},
propDescriptions: {