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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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: {