An open source design system that's fully customizable and agent ready
TypeScript
feat(DateRangePicker): add XDSDateRangePicker component (#184) (#2201)
Andrey Goderd257a13ea9af
diff --git a/apps/storybook/stories/DateRangePicker.stories.tsx b/apps/storybook/stories/DateRangePicker.stories.tsxnew file mode 100644index 0000000000..282ac0ba50--- /dev/null+++ b/apps/storybook/stories/DateRangePicker.stories.tsx@@ -0,0 +1,289 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {XDSDateRangePicker} from '@xds/core/DateRangePicker';+import type {XDSDateRange} from '@xds/core/DateRangePicker';+import type {ISODateString} from '@xds/core/Calendar';++function daysAgo(n: number): ISODateString {+ const d = new Date();+ d.setDate(d.getDate() - n);+ return d.toISOString().slice(0, 10) as ISODateString;+}++function today(): ISODateString {+ return new Date().toISOString().slice(0, 10) as ISODateString;+}++function startOfMonth(): ISODateString {+ const d = new Date();+ d.setDate(1);+ return d.toISOString().slice(0, 10) as ISODateString;+}++const defaultPresets = [+ {label: 'Last 1 day', getRange: () => ({start: daysAgo(1), end: today()})},+ {label: 'Last 3 days', getRange: () => ({start: daysAgo(3), end: today()})},+ {label: 'Last 7 days', getRange: () => ({start: daysAgo(7), end: today()})},+ {+ label: 'Last 14 days',+ getRange: () => ({start: daysAgo(14), end: today()}),+ },+ {+ label: 'Last 30 days',+ getRange: () => ({start: daysAgo(30), end: today()}),+ },+ {+ label: 'This month',+ getRange: () => ({start: startOfMonth(), end: today()}),+ },+];++const meta: Meta<typeof XDSDateRangePicker> = {+ title: 'Core/Inputs/DateRangePicker',+ component: XDSDateRangePicker,+ tags: ['autodocs'],+ argTypes: {+ label: {control: 'text', description: 'Label text (required)'},+ isLabelHidden: {+ control: 'boolean',+ description: 'Visually hide the label',+ },+ placeholder: {control: 'text', description: 'Placeholder text'},+ description: {control: 'text', description: 'Description text'},+ isOptional: {control: 'boolean', description: 'Show optional indicator'},+ isRequired: {control: 'boolean', description: 'Mark as required'},+ isDisabled: {control: 'boolean', description: 'Disable the picker'},+ size: {+ control: 'radio',+ options: ['sm', 'md'],+ description: 'Trigger size',+ },+ hasClear: {control: 'boolean', description: 'Show clear button'},+ numberOfMonths: {+ control: 'radio',+ options: [1, 2],+ description: 'Calendar months',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSDateRangePicker>;++export const Default: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ },+};++export const WithValue: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>({+ start: '2026-03-10' as ISODateString,+ end: '2026-03-20' as ISODateString,+ });+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Report period',+ },+};++export const WithPresets: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ presets: defaultPresets,+ },+};++export const WithPresetsAndValue: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>({+ start: daysAgo(7),+ end: today(),+ });+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Analytics period',+ presets: defaultPresets,+ },+};++export const WithDescription: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Coverage period',+ description: 'Select the start and end dates for the report',+ },+};++export const WithMinMax: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Booking dates',+ min: '2026-03-01' as ISODateString,+ max: '2026-06-30' as ISODateString,+ description: 'Available: Mar 1 – Jun 30, 2026',+ },+};++export const Optional: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Filter by date',+ isOptional: true,+ },+};++export const Required: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Coverage period',+ isRequired: true,+ },+};++export const Disabled: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>({+ start: '2026-03-10' as ISODateString,+ end: '2026-03-20' as ISODateString,+ });+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Locked range',+ isDisabled: true,+ },+};++export const SmallSize: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ size: 'sm',+ },+};++export const SingleMonth: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ numberOfMonths: 1,+ },+};++export const WithErrorStatus: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>(null);+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ status: {type: 'error', message: 'Please select a date range'},+ },+};++export const WithWarningStatus: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>({+ start: '2026-03-01' as ISODateString,+ end: '2026-06-30' as ISODateString,+ });+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Date range',+ status: {type: 'warning', message: 'Range exceeds 90 days'},+ },+};++export const NoClear: Story = {+ render: args => {+ const [value, setValue] = useState<XDSDateRange | null>({+ start: '2026-03-10' as ISODateString,+ end: '2026-03-20' as ISODateString,+ });+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Required range',+ hasClear: false,+ },+};++export const AllVariations: Story = {+ render: () => {+ const [v1, setV1] = useState<XDSDateRange | null>(null);+ const [v2, setV2] = useState<XDSDateRange | null>({+ start: '2026-03-10' as ISODateString,+ end: '2026-03-20' as ISODateString,+ });+ const [v3, setV3] = useState<XDSDateRange | null>(null);+ const [v4, setV4] = useState<XDSDateRange | null>({+ start: '2026-03-10' as ISODateString,+ end: '2026-03-20' as ISODateString,+ });+ const [v5, setV5] = useState<XDSDateRange | null>(null);++ return (+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '16px',+ maxWidth: '340px',+ }}>+ <XDSDateRangePicker label="Default" value={v1} onChange={setV1} />+ <XDSDateRangePicker label="With value" value={v2} onChange={setV2} />+ <XDSDateRangePicker+ label="With presets"+ value={v3}+ onChange={setV3}+ presets={defaultPresets}+ />+ <XDSDateRangePicker+ label="Disabled"+ isDisabled+ value={v4}+ onChange={setV4}+ />+ <XDSDateRangePicker+ label="With error"+ value={v5}+ onChange={setV5}+ status={{type: 'error', message: 'Date range is required'}}+ />+ </div>+ );+ },+};diff --git a/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjs b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjsnew file mode 100644index 0000000000..5e58ef0529--- /dev/null+++ b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'DateRangePicker',+ name: 'DateRangePicker',+ description:+ 'A date range picker with a button trigger and dual-month calendar popover with preset ranges.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 1,+ componentsUsed: ['DateRangePicker', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsx b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsxnew file mode 100644index 0000000000..99bc23d2a3--- /dev/null+++ b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsx@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {useState} from 'react';+import {XDSDateRangePicker} from '@xds/core/DateRangePicker';+import type {XDSDateRange} from '@xds/core/DateRangePicker';+import type {ISODateString} from '@xds/core/Calendar';+import {XDSStack} from '@xds/core/Layout';++function daysAgo(n: number): ISODateString {+ const d = new Date();+ d.setDate(d.getDate() - n);+ return d.toISOString().slice(0, 10) as ISODateString;+}++function today(): ISODateString {+ return new Date().toISOString().slice(0, 10) as ISODateString;+}++const presets = [+ {label: 'Last 7 days', getRange: () => ({start: daysAgo(7), end: today()})},+ {label: 'Last 30 days', getRange: () => ({start: daysAgo(30), end: today()})},+];++export default function DateRangePickerShowcase() {+ const [range, setRange] = useState<XDSDateRange | null>(null);++ return (+ <XDSStack direction="vertical" width="100%" style={{maxWidth: 400}}>+ <XDSDateRangePicker+ label="Date range"+ value={range}+ onChange={setRange}+ presets={presets}+ />+ </XDSStack>+ );+}diff --git a/packages/core/package.json b/packages/core/package.jsonindex d79d2c464c..7fdd2e588a 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -199,6 +199,12 @@"import": "./dist/DateInput/index.mjs","require": "./dist/DateInput/index.js"},+ "./DateRangePicker": {+ "source": "./src/DateRangePicker/index.ts",+ "types": "./dist/DateRangePicker/index.d.ts",+ "import": "./dist/DateRangePicker/index.mjs",+ "require": "./dist/DateRangePicker/index.js"+ },"./DateTimePicker": {"source": "./src/DateTimePicker/index.ts","types": "./dist/DateTimePicker/index.d.ts",diff --git a/packages/core/src/DateRangePicker/DateRangePicker.doc.mjs b/packages/core/src/DateRangePicker/DateRangePicker.doc.mjsnew file mode 100644index 0000000000..662d359528--- /dev/null+++ b/packages/core/src/DateRangePicker/DateRangePicker.doc.mjs@@ -0,0 +1,90 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'DateRangePicker',+ keywords: ["daterangepicker","daterange","range","calendar","filter","analytics","period","schedule"],+ props: [+ { name: 'label', type: 'string', description: 'Label text.', required: true },+ { name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false' },+ { name: 'description', type: 'string', description: 'Helper text displayed below the label.' },+ { name: 'isOptional', type: 'boolean', description: 'Show an "(optional)" indicator.', default: 'false' },+ { name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false' },+ { name: 'isDisabled', type: 'boolean', description: 'Disable the trigger and picker.', default: 'false' },+ { name: 'value', type: 'XDSDateRange | null', description: 'Selected date range ({start, end} in ISO format), or null.', required: true },+ { name: 'onChange', type: '(value: XDSDateRange | null) => void', description: 'Callback when the range changes. Called with null on clear.', required: true },+ { name: 'changeAction', type: '(value: XDSDateRange | null) => void | Promise<void>', description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.' },+ { name: 'isLoading', type: 'boolean', description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.', default: 'false' },+ { name: 'min', type: 'ISODateString', description: 'Minimum selectable date.' },+ { name: 'max', type: 'ISODateString', description: 'Maximum selectable date.' },+ { name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: 'Custom constraint functions to disable specific dates.' },+ { name: 'presets', type: 'Array<XDSDateRangePreset>', description: 'Preset ranges shown as quick-select options beside the calendar.' },+ { name: 'hasClear', type: 'boolean', description: 'Shows a clear button when a range is selected.', default: 'true' },+ { name: 'placeholder', type: 'string', description: 'Placeholder text when no range is selected.', default: "'Select date range'" },+ { name: 'size', type: "'sm' | 'md'", description: 'Size of the trigger.', default: "'md'" },+ { name: 'status', type: 'XDSInputStatus', description: 'Status indicator for error, warning, or success states.' },+ { name: 'labelTooltip', type: 'string', description: 'Tooltip text via info icon at label end.' },+ { name: 'numberOfMonths', type: '1 | 2', description: 'Number of months in the calendar.', default: '2' },+ { name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.' },+ ],+ theming: {+ targets: [+ { className: 'xds-date-range-picker', visualProps: ['size', 'status'] },+ ],+ },+ usage: {+ description: 'DateRangePicker lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.',+ bestPractices: [+ { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },+ { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },+ { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },+ { guidance: true, description: 'Provide clear labels and descriptions so users understand what the range controls.' },+ { guidance: false, description: 'Use DateRangePicker when only a single date is needed — use DateInput instead.' },+ { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },+ ],+ anatomy: [+ { name: 'Label', required: true, description: 'Text above the trigger describing what date range is expected.' },+ { name: 'Trigger button', required: true, description: 'A button showing the formatted range or placeholder. Clicking opens the popover.' },+ { name: 'Calendar icon', required: true, description: 'A trailing icon that also opens the popover.' },+ { name: 'Calendar popover', required: true, description: 'A dual-month calendar grid with range selection and hover preview.' },+ { name: 'Preset sidebar', required: false, description: 'A list of preset range options beside the calendar.' },+ { name: 'Clear button', required: false, description: 'A × button that resets the range to null.' },+ { name: 'Status message', required: false, description: 'An error, warning, or success message below the trigger.' },+ ],+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'date range picker with dual-month calendar popover and preset ranges',+ usage: {+ description: 'DateRangePicker lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',+ bestPractices: [+ { guidance: true, description: 'Use presets for common ranges. Use min/max for constraints.' },+ { guidance: true, description: 'Keep hasClear enabled. Provide clear labels.' },+ { guidance: false, description: 'Use for single dates (use DateInput). Hide label without context.' },+ ],+ },+ propDescriptions: {+ label: 'label text',+ isLabelHidden: 'visually hide label',+ description: 'helper text below label',+ isOptional: 'show "(optional)" indicator',+ isRequired: 'mark field required',+ isDisabled: 'disable trigger+picker',+ value: 'selected range {start, end} or null',+ onChange: 'callback on range change; null on clear',+ min: 'min selectable date',+ max: 'max selectable date',+ dateConstraints: 'custom constraint fns to disable dates',+ presets: 'preset ranges as quick-select options',+ hasClear: 'clear button when range is set (default true)',+ placeholder: 'placeholder when empty',+ size: 'trigger size',+ status: 'error/warning/success status',+ labelTooltip: 'tooltip via info icon at label end',+ numberOfMonths: 'months in calendar (default 2)',+ xstyle: 'StyleX styles for layout',+ },+};diff --git a/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx b/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsxnew file mode 100644index 0000000000..623ceba000--- /dev/null+++ b/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx@@ -0,0 +1,317 @@+/**+ * @file XDSDateRangePicker.test.tsx+ * @input Uses vitest, @testing-library/react, XDSDateRangePicker component+ * @output Unit tests for XDSDateRangePicker component behavior+ * @position Testing; validates XDSDateRangePicker.tsx implementation+ *+ * SYNC: When XDSDateRangePicker.tsx changes, update tests to match new behavior+ */++// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect, vi} from 'vitest';+import {render, screen, fireEvent} from '@testing-library/react';+import {XDSDateRangePicker} from './XDSDateRangePicker';+import type {XDSDateRange} from './XDSDateRangePicker';+import type {ISODateString} from '../Calendar';++describe('XDSDateRangePicker', () => {+ it('renders with label', () => {+ render(+ <XDSDateRangePicker+ label="Date range"+ value={null}+ onChange={() => {}}+ />,+ );+ expect(screen.getByText('Date range')).toBeInTheDocument();+ });++ it('renders placeholder when value is null', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ expect(screen.getByText('Select date range')).toBeInTheDocument();+ });++ it('renders custom placeholder', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ value={null}+ onChange={() => {}}+ placeholder="Pick dates"+ />,+ );+ expect(screen.getByText('Pick dates')).toBeInTheDocument();+ });++ it('displays formatted range when value is set', () => {+ const range: XDSDateRange = {+ start: '2026-03-15' as ISODateString,+ end: '2026-03-22' as ISODateString,+ };+ render(+ <XDSDateRangePicker+ label="Range"+ value={range}+ onChange={() => {}}+ hasClear={false}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range:/});+ expect(trigger.textContent).toMatch(/Mar/);+ expect(trigger.textContent).toMatch(/15/);+ expect(trigger.textContent).toMatch(/22/);+ });++ it('forwards ref to trigger button', () => {+ const ref = vi.fn();+ render(+ <XDSDateRangePicker+ ref={ref}+ label="Range"+ value={null}+ onChange={() => {}}+ />,+ );+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement));+ });++ it('visually hides label when isLabelHidden is true', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ isLabelHidden+ value={null}+ onChange={() => {}}+ />,+ );+ expect(screen.getByText('Range')).toBeInTheDocument();+ });++ it('sets aria-required when isRequired is true', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ isRequired+ value={null}+ onChange={() => {}}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).toHaveAttribute('aria-required', 'true');+ });++ it('does not set aria-required when isRequired is false', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).not.toHaveAttribute('aria-required');+ });++ it('disables trigger when isDisabled is true', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ isDisabled+ value={null}+ onChange={() => {}}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).toBeDisabled();+ });++ it('is not disabled by default', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).not.toBeDisabled();+ });++ it('trigger has aria-haspopup="dialog"', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');+ });++ it('trigger has aria-expanded=false by default', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('renders status icon for error status', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ value={null}+ onChange={() => {}}+ status={{type: 'error', message: 'Required'}}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).toHaveAttribute('aria-invalid', 'true');+ });++ it('does not set aria-invalid for warning status', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ value={null}+ onChange={() => {}}+ status={{type: 'warning', message: 'Watch out'}}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ expect(trigger).not.toHaveAttribute('aria-invalid');+ });++ it('renders description', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ description="Pick a date range"+ value={null}+ onChange={() => {}}+ />,+ );+ expect(screen.getByText('Pick a date range')).toBeInTheDocument();+ });++ it('links status message via aria-describedby', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ value={null}+ onChange={() => {}}+ status={{type: 'error', message: 'Please select dates'}}+ />,+ );+ const trigger = screen.getByRole('button', {name: /Range/});+ const describedBy = trigger.getAttribute('aria-describedby')!;+ const ids = describedBy.split(' ');+ const found = ids.some(id => {+ const el = document.getElementById(id);+ return el?.textContent?.includes('Please select dates');+ });+ expect(found).toBe(true);+ });++ it('calendar icon button is present', () => {+ render(+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,+ );+ expect(+ screen.getByRole('button', {name: 'Open calendar'}),+ ).toBeInTheDocument();+ });++ it('calendar icon button is disabled when isDisabled', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ isDisabled+ value={null}+ onChange={() => {}}+ />,+ );+ expect(screen.getByRole('button', {name: 'Open calendar'})).toBeDisabled();+ });++ describe('hasClear', () => {+ it('shows clear button when hasClear is true and value exists', () => {+ const range: XDSDateRange = {+ start: '2026-03-15' as ISODateString,+ end: '2026-03-22' as ISODateString,+ };+ render(+ <XDSDateRangePicker+ label="Range"+ value={range}+ onChange={() => {}}+ hasClear+ />,+ );+ expect(+ screen.getByRole('button', {name: 'Clear Range'}),+ ).toBeInTheDocument();+ });++ it('does not show clear button when value is null', () => {+ render(+ <XDSDateRangePicker+ label="Range"+ value={null}+ onChange={() => {}}+ hasClear+ />,+ );+ expect(+ screen.queryByRole('button', {name: 'Clear Range'}),+ ).not.toBeInTheDocument();+ });++ it('does not show clear button when hasClear is false', () => {+ const range: XDSDateRange = {+ start: '2026-03-15' as ISODateString,+ end: '2026-03-22' as ISODateString,+ };+ render(+ <XDSDateRangePicker+ label="Range"+ value={range}+ onChange={() => {}}+ hasClear={false}+ />,+ );+ expect(+ screen.queryByRole('button', {name: 'Clear Range'}),+ ).not.toBeInTheDocument();+ });++ it('does not show clear button when disabled', () => {+ const range: XDSDateRange = {+ start: '2026-03-15' as ISODateString,+ end: '2026-03-22' as ISODateString,+ };+ render(+ <XDSDateRangePicker+ label="Range"+ value={range}+ onChange={() => {}}+ hasClear+ isDisabled+ />,+ );+ expect(+ screen.queryByRole('button', {name: 'Clear Range'}),+ ).not.toBeInTheDocument();+ });++ it('calls onChange with null when clear is clicked', () => {+ const onChange = vi.fn();+ const range: XDSDateRange = {+ start: '2026-03-15' as ISODateString,+ end: '2026-03-22' as ISODateString,+ };+ render(+ <XDSDateRangePicker+ label="Range"+ value={range}+ onChange={onChange}+ hasClear+ />,+ );+ fireEvent.click(screen.getByRole('button', {name: 'Clear Range'}));+ expect(onChange).toHaveBeenCalledWith(null);+ });+ });+});diff --git a/packages/core/src/DateRangePicker/XDSDateRangePicker.tsx b/packages/core/src/DateRangePicker/XDSDateRangePicker.tsxnew file mode 100644index 0000000000..96c0a8ebd4--- /dev/null+++ b/packages/core/src/DateRangePicker/XDSDateRangePicker.tsx@@ -0,0 +1,596 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSDateRangePicker.tsx+ * @input Uses React, XDSField, XDSCalendar (range mode), useXDSPopover+ * @output Exports XDSDateRangePicker component, XDSDateRangePickerProps+ * @position Core implementation; consumed by index.ts, tested by XDSDateRangePicker.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/DateRangePicker/DateRangePicker.doc.mjs (props table, features, implementation notes)+ * - /packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx (tests for new/changed behavior)+ * - /packages/core/src/DateRangePicker/index.ts (exports if types change)+ * - /apps/storybook/stories/DateRangePicker.stories.tsx (storybook stories)+ * - /packages/cli/templates/blocks/components/DateRangePicker/ (showcase blocks)+ */++import {useId, useCallback, useMemo, useOptimistic, useTransition} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {XDSIconName} from '../Icon';+import {+ colorVars,+ sizeVars,+ radiusVars,+ spacingVars,+ typographyVars,+ typeScaleVars,+ borderVars,+} from '../theme/tokens.stylex';+import {+ XDSField,+ type XDSInputStatus,+ type XDSInputStatusType,+ inputWrapperStyles,+ inputStatusBorderStyles,+ inputStatusHoverShadowStyles,+ inputStatusFocusWithinStyles,+} from '../Field';+import {XDSIcon} from '../Icon';+import {XDSSpinner} from '../Spinner';+import {XDSCalendar, type ISODateString, type DateRange} from '../Calendar';+import {useXDSPopover} from '../Popover';+import {xdsClassName, mergeProps} from '../utils';+import type {StyleXStyles} from '@stylexjs/stylex';+import type {XDSBaseProps} from '../XDSBaseProps';++export type {DateRange as XDSDateRange} from '../Calendar';++export interface XDSDateRangePreset {+ label: string;+ getRange: () => DateRange;+}++export type XDSDateRangePickerSize = 'sm' | 'md';++export type {+ XDSInputStatus as XDSDateRangePickerStatus,+ XDSInputStatusType as XDSDateRangePickerStatusType,+} from '../Field';++const styles = stylex.create({+ trigger: {+ display: 'block',+ flex: 1,+ minWidth: 0,+ borderWidth: 0,+ borderStyle: 'none',+ padding: 0,+ fontFamily: typographyVars['--font-family-body'],+ fontSize: {+ default: typeScaleVars['--text-body-size'],+ '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,+ },+ lineHeight: typeScaleVars['--text-body-leading'],+ color: colorVars['--color-text-primary'],+ backgroundColor: 'transparent',+ outline: 'none',+ cursor: 'pointer',+ textAlign: 'start',+ whiteSpace: 'nowrap',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ },+ triggerPlaceholder: {+ color: colorVars['--color-text-secondary'],+ },+ triggerDisabled: {+ cursor: 'not-allowed',+ },+ iconButton: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ padding: 0,+ margin: 0,+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ cursor: 'pointer',+ borderRadius: radiusVars['--radius-element'],+ outline: {+ default: 'none',+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,+ },+ outlineOffset: 1,+ },+ iconButtonDisabled: {+ cursor: 'not-allowed',+ },+ popoverLayout: {+ display: 'flex',+ },+ presetSidebar: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-1'],+ padding: spacingVars['--spacing-3'],+ borderRightWidth: borderVars['--border-width'],+ borderRightStyle: 'solid',+ borderRightColor: colorVars['--color-border-emphasized'],+ minWidth: 140,+ },+ presetButton: {+ display: 'block',+ width: '100%',+ padding: `${spacingVars['--spacing-1']} ${spacingVars['--spacing-2']}`,+ margin: 0,+ borderWidth: 0,+ borderStyle: 'none',+ borderRadius: radiusVars['--radius-element'],+ backgroundColor: {+ default: 'transparent',+ ':hover': {+ '@media (hover: hover)': colorVars['--color-overlay-hover'],+ },+ },+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ color: colorVars['--color-text-primary'],+ cursor: 'pointer',+ textAlign: 'start',+ outline: {+ default: 'none',+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,+ },+ },+ presetButtonActive: {+ backgroundColor: colorVars['--color-accent-muted'],+ color: colorVars['--color-accent'],+ },+});++const sizeStyles = stylex.create({+ sm: {+ height: sizeVars['--size-element-sm'],+ minWidth: 180,+ },+ md: {+ height: sizeVars['--size-element-md'],+ minWidth: 180,+ },+});++const shortDateFormatter = new Intl.DateTimeFormat(undefined, {+ month: 'short',+ day: 'numeric',+});++const shortDateWithYearFormatter = new Intl.DateTimeFormat(undefined, {+ month: 'short',+ day: 'numeric',+ year: 'numeric',+});++function parseISO(iso: ISODateString): Date {+ const [year, month, day] = iso.split('-').map(Number);+ return new Date(year, month - 1, day);+}++function formatRangeDisplay(range: DateRange | null): string {+ if (!range) return '';+ const startDate = parseISO(range.start);+ const endDate = parseISO(range.end);+ const currentYear = new Date().getFullYear();+ const sameYear =+ startDate.getFullYear() === endDate.getFullYear() &&+ startDate.getFullYear() === currentYear;++ const fmt = sameYear ? shortDateFormatter : shortDateWithYearFormatter;+ return `${fmt.format(startDate)} – ${fmt.format(endDate)}`;+}++function isRangeEqual(a: DateRange | null, b: DateRange | null): boolean {+ if (a === b) return true;+ if (!a || !b) return false;+ return a.start === b.start && a.end === b.end;+}++export interface XDSDateRangePickerProps extends Omit<+ XDSBaseProps,+ 'onChange' | 'defaultValue'+> {+ /** Ref forwarded to the trigger button */+ ref?: React.Ref<HTMLButtonElement>;++ /**+ * Label text for the input (required for accessibility).+ */+ label: string;++ /**+ * Whether to visually hide the label (still accessible to screen readers).+ * @default false+ */+ isLabelHidden?: boolean;++ /**+ * Description text displayed between the label and input.+ */+ description?: string;++ /**+ * Whether the field is optional. Mutually exclusive with isRequired.+ * @default false+ */+ isOptional?: boolean;++ /**+ * Whether the field is required. Mutually exclusive with isOptional.+ * @default false+ */+ isRequired?: boolean;++ /**+ * Whether the input is disabled.+ * @default false+ */+ isDisabled?: boolean;++ /**+ * The selected date range, or null if no range is selected.+ */+ value: DateRange | null;++ /**+ * Callback fired when the date range changes.+ * Called with null when the range is cleared.+ */+ onChange: (value: DateRange | null) => void;++ /**+ * Async action on change. Fires after onChange.+ */+ changeAction?: (value: DateRange | null) => void | Promise<void>;++ /**+ * Whether the input is in a loading state.+ * @default false+ */+ isLoading?: boolean;++ /**+ * Minimum selectable date in ISO format.+ */+ min?: ISODateString;++ /**+ * Maximum selectable date in ISO format.+ */+ max?: ISODateString;++ /**+ * Custom date constraint functions.+ * A date is disabled if ANY function returns false.+ */+ dateConstraints?: ReadonlyArray<(date: Date) => boolean>;++ /**+ * Preset date ranges shown as quick-select options beside the calendar.+ */+ presets?: ReadonlyArray<XDSDateRangePreset>;++ /**+ * Whether to show a clear button when a range is selected.+ * @default true+ */+ hasClear?: boolean;++ /**+ * Placeholder text shown when no range is selected.+ * @default "Select date range"+ */+ placeholder?: string;++ /**+ * The size of the trigger.+ * @default 'md'+ */+ size?: XDSDateRangePickerSize;++ /**+ * Status indicator for the input.+ */+ status?: XDSInputStatus;++ /**+ * Tooltip text to display in an info icon at the end of the label.+ */+ labelTooltip?: string;++ /**+ * Number of months to display in the calendar.+ * @default 2+ */+ numberOfMonths?: 1 | 2;++ /**+ * Style overrides.+ */+ xstyle?: StyleXStyles;+}++/**+ * A date range picker with a button trigger that opens a popover+ * containing a dual-month calendar and optional preset ranges.+ *+ * @example+ * ```+ * <XDSDateRangePicker+ * label="Date range"+ * value={range}+ * onChange={setRange}+ * presets={[+ * { label: "Last 7 days", getRange: () => ({start: "...", end: "..."}) },+ * ]}+ * />+ * ```+ */+export function XDSDateRangePicker({+ label,+ isLabelHidden = false,+ description,+ isOptional = false,+ isRequired = false,+ isDisabled = false,+ value,+ onChange,+ changeAction,+ isLoading = false,+ min,+ max,+ dateConstraints,+ presets,+ hasClear = true,+ placeholder = 'Select date range',+ size = 'md',+ status,+ labelTooltip,+ numberOfMonths = 2,+ xstyle,+ className,+ style,+ ref,+ ...rest+}: XDSDateRangePickerProps) {+ const id = useId();+ const descriptionID = useId();+ const statusMessageID = useId();++ const [, startTransition] = useTransition();+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);+ const isBusy = isLoading || optimisticValue !== value;+ const isEffectivelyDisabled = isDisabled || isBusy;++ const statusIconMap: Record<XDSInputStatusType, XDSIconName> = {+ warning: 'warning',+ error: 'error',+ success: 'success',+ };++ const statusIconColorMap: Record<+ XDSInputStatusType,+ 'warning' | 'negative' | 'positive'+ > = {+ warning: 'warning',+ error: 'negative',+ success: 'positive',+ };++ const ariaDescribedBy =+ [+ description ? descriptionID : null,+ status?.message ? statusMessageID : null,+ ]+ .filter(Boolean)+ .join(' ') || undefined;++ const displayValue = useMemo(+ () => formatRangeDisplay(optimisticValue),+ [optimisticValue],+ );++ const popover = useXDSPopover({+ dialogLabel: 'Choose date range',+ closeButtonLabel: 'Close calendar',+ });++ const fireChange = useCallback(+ (newValue: DateRange | null) => {+ if (isBusy) return;+ onChange(newValue);+ if (changeAction) {+ startTransition(async () => {+ setOptimisticValue(newValue);+ await changeAction(newValue);+ });+ }+ },+ [isBusy, onChange, changeAction, startTransition, setOptimisticValue],+ );++ const handleToggle = useCallback(() => {+ if (!isEffectivelyDisabled) {+ if (popover.isOpen) {+ popover.hide();+ } else {+ popover.show();+ }+ }+ }, [isEffectivelyDisabled, popover]);++ const handleRangeSelect = useCallback(+ (range: DateRange) => {+ fireChange(range);+ popover.hide();+ },+ [fireChange, popover],+ );++ const handlePresetClick = useCallback(+ (preset: XDSDateRangePreset) => {+ fireChange(preset.getRange());+ popover.hide();+ },+ [fireChange, popover],+ );++ const handleClear = useCallback(+ (e: React.MouseEvent) => {+ e.stopPropagation();+ fireChange(null);+ },+ [fireChange],+ );++ const triggerAriaLabel = value+ ? `${label}: ${displayValue}`+ : `${label}: ${placeholder}`;++ return (+ <XDSField+ label={label}+ isLabelHidden={isLabelHidden}+ description={description}+ inputID={id}+ descriptionID={description ? descriptionID : undefined}+ isOptional={isOptional}+ isRequired={isRequired}+ isDisabled={isEffectivelyDisabled}+ status={+ status+ ? {+ type: status.type,+ message: status.message,+ messageID: status.message ? statusMessageID : undefined,+ }+ : undefined+ }+ labelTooltip={labelTooltip}>+ <div+ ref={popover.triggerRef}+ {...rest}+ {...mergeProps(+ xdsClassName('date-range-picker', {+ size,+ status: status?.type ?? null,+ }),+ stylex.props(+ inputWrapperStyles.base,+ sizeStyles[size],+ isEffectivelyDisabled && inputWrapperStyles.disabled,+ status && inputStatusBorderStyles[status.type],+ status && inputStatusHoverShadowStyles[status.type],+ status && inputStatusFocusWithinStyles[status.type],+ xstyle,+ ),+ className,+ style,+ )}>+ <button+ ref={ref}+ id={id}+ type="button"+ onClick={handleToggle}+ disabled={isEffectivelyDisabled}+ aria-label={triggerAriaLabel}+ aria-describedby={ariaDescribedBy}+ aria-required={isRequired === true ? 'true' : undefined}+ aria-invalid={status?.type === 'error' ? 'true' : undefined}+ aria-busy={isBusy || undefined}+ aria-expanded={popover.isOpen}+ aria-haspopup="dialog"+ aria-controls={popover.isOpen ? popover.id : undefined}+ {...stylex.props(+ styles.trigger,+ !displayValue && styles.triggerPlaceholder,+ isEffectivelyDisabled && styles.triggerDisabled,+ )}>+ {displayValue || placeholder}+ </button>+ {hasClear && value !== null && !isEffectivelyDisabled && (+ <button+ type="button"+ onClick={handleClear}+ aria-label={`Clear ${label}`}+ {...stylex.props(styles.iconButton)}>+ <XDSIcon icon="close" size="sm" color="secondary" />+ </button>+ )}+ <button+ type="button"+ onClick={handleToggle}+ disabled={isEffectivelyDisabled}+ aria-label={popover.isOpen ? 'Close calendar' : 'Open calendar'}+ tabIndex={-1}+ {...stylex.props(+ styles.iconButton,+ isEffectivelyDisabled && styles.iconButtonDisabled,+ )}>+ <XDSIcon icon="calendar" size="sm" color="secondary" />+ </button>+ {isBusy && <XDSSpinner size="sm" />}+ {status && (+ <XDSIcon+ icon={statusIconMap[status.type]}+ size="md"+ color={statusIconColorMap[status.type]}+ />+ )}+ </div>+ {popover.render(+ <div {...stylex.props(styles.popoverLayout)}>+ {presets && presets.length > 0 && (+ <div+ role="listbox"+ aria-label="Preset date ranges"+ {...stylex.props(styles.presetSidebar)}>+ {presets.map((preset, i) => {+ const presetRange = preset.getRange();+ const isActive = isRangeEqual(value, presetRange);+ return (+ <button+ key={i}+ type="button"+ role="option"+ aria-selected={isActive}+ onClick={() => handlePresetClick(preset)}+ {...stylex.props(+ styles.presetButton,+ isActive && styles.presetButtonActive,+ )}>+ {preset.label}+ </button>+ );+ })}+ </div>+ )}+ <XDSCalendar+ mode="range"+ value={value ?? undefined}+ onChange={handleRangeSelect}+ min={min}+ max={max}+ dateConstraints={dateConstraints}+ numberOfMonths={numberOfMonths}+ />+ </div>,+ {placement: 'below', alignment: 'start'},+ )}+ </XDSField>+ );+}++XDSDateRangePicker.displayName = 'XDSDateRangePicker';diff --git a/packages/core/src/DateRangePicker/index.ts b/packages/core/src/DateRangePicker/index.tsnew file mode 100644index 0000000000..ba558c8f57--- /dev/null+++ b/packages/core/src/DateRangePicker/index.ts@@ -0,0 +1,20 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file index.ts+ * @input DateRangePicker component exports+ * @output Re-exports XDSDateRangePicker and types+ * @position Package entry point for DateRangePicker+ */++export {XDSDateRangePicker} from './XDSDateRangePicker';+export type {+ XDSDateRangePickerProps,+ XDSDateRangePickerSize,+ XDSDateRangePickerStatus,+ XDSDateRangePickerStatusType,+ XDSDateRange,+ XDSDateRangePreset,+} from './XDSDateRangePicker';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 7fba07b500..ca156a1cc5 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -52,6 +52,7 @@ export * from './Stack';export * from './Switch';export * from './DateInput';export * from './DateTimePicker';+export * from './DateRangePicker';export * from './Field';export * from './FormLayout';export * from './Grid';