Skip to content

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

TypeScript

feat(DateInput): configurable format reusing Timestamp's format vocabulary (#4160) (#4199)

Cindy Zhang93329cc5ac0d
diff --git a/.changeset/dateinput-format-timestamp-vocabulary.md b/.changeset/dateinput-format-timestamp-vocabulary.md
new file mode 100644
index 0000000000..1ade424895
--- /dev/null
+++ b/.changeset/dateinput-format-timestamp-vocabulary.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] DateInput gains a `format` prop for the committed date value, reusing Timestamp's `format` vocabulary so the same literal renders the same date shape in both components. Named values are `date_long` (the default, "March 21, 2026"), `date` ("Mar 21, 2026"), `date_weekday` ("Wed, Mar 21, 2026"), and `system_date` ("2026-03-21"); a `(value) => string` function is also accepted for custom output. The `date_long` default is byte-identical to DateInput's previous long-month rendering, so existing usage is unchanged. This also extends Timestamp with two new shared members, `date_long` and `date_weekday`, giving the two components full value parity on the date-only formats. Formatting applies only to the committed value, never to text being typed.
+
+@cixzhang
diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsx
index 7204718117..648636ec8f 100644
--- a/apps/storybook/stories/DateInput.stories.tsx
+++ b/apps/storybook/stories/DateInput.stories.tsx
@@ -57,6 +57,12 @@ const meta: Meta<typeof DateInput> = {
options: [1, 2],
description: 'Number of months to display in calendar',
},
+ format: {
+ control: 'select',
+ options: ['date_long', 'date', 'date_weekday', 'system_date'],
+ description:
+ "Display format for the committed value, reusing Timestamp's vocabulary. Defaults to 'date_long' (long-month date).",
+ },
},
};
@@ -86,6 +92,58 @@ export const WithValue: Story = {
},
};
+/**
+ * The committed date value can be rendered in different shapes via `format`,
+ * reusing `Timestamp`'s format vocabulary so the same literal renders the same
+ * date shape in both components. It defaults to `'date_long'` (a long-month
+ * date, "March 21, 2026"). While the user is typing, the raw text is shown
+ * verbatim — `format` applies only to the committed value.
+ */
+export const Formats: Story = {
+ render: () => {
+ const [value, setValue] = useState<ISODateString | undefined>(
+ '2026-03-21' as ISODateString,
+ );
+ return (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
+ <DateInput
+ label="Default (format='date_long')"
+ value={value}
+ onChange={setValue}
+ />
+ <DateInput
+ label="format='date'"
+ value={value}
+ onChange={setValue}
+ format="date"
+ />
+ <DateInput
+ label="format='date_weekday'"
+ value={value}
+ onChange={setValue}
+ format="date_weekday"
+ />
+ <DateInput
+ label="format='system_date'"
+ value={value}
+ onChange={setValue}
+ format="system_date"
+ />
+ <DateInput
+ label="Custom function"
+ value={value}
+ onChange={setValue}
+ format={iso =>
+ new Intl.DateTimeFormat('en-GB', {dateStyle: 'full'}).format(
+ new Date(iso + 'T00:00'),
+ )
+ }
+ />
+ </div>
+ );
+ },
+};
+
export const WithDescription: Story = {
render: args => {
const [value, setValue] = useState<ISODateString | undefined>(undefined);
diff --git a/apps/storybook/stories/Timestamp.stories.tsx b/apps/storybook/stories/Timestamp.stories.tsx
index b2fda36cbd..be6ee081e4 100644
--- a/apps/storybook/stories/Timestamp.stories.tsx
+++ b/apps/storybook/stories/Timestamp.stories.tsx
@@ -15,6 +15,8 @@ const meta: Meta<typeof Timestamp> = {
'relative',
'auto',
'date',
+ 'date_long',
+ 'date_weekday',
'date_time',
'time',
'system_date',
@@ -122,6 +124,20 @@ export const DateFormat: Story = {
},
};
+export const DateLongFormat: Story = {
+ args: {
+ value: '2026-02-19T17:00:00Z',
+ format: 'date_long',
+ },
+};
+
+export const DateWeekdayFormat: Story = {
+ args: {
+ value: '2026-02-19T17:00:00Z',
+ format: 'date_weekday',
+ },
+};
+
export const DateTimeFormat: Story = {
args: {
value: '2026-02-19T17:00:00Z',
@@ -198,6 +214,18 @@ export const AllFormats: Story = {
</Text>
<Timestamp value={date} format="date" />
</div>
+ <div>
+ <Text type="label" color="secondary">
+ date_long:{' '}
+ </Text>
+ <Timestamp value={date} format="date_long" />
+ </div>
+ <div>
+ <Text type="label" color="secondary">
+ date_weekday:{' '}
+ </Text>
+ <Timestamp value={date} format="date_weekday" />
+ </div>
<div>
<Text type="label" color="secondary">
date_time:{' '}
diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputFormats.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputFormats.doc.mjs
new file mode 100644
index 0000000000..2721e3dcf9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DateInput/DateInputFormats.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: 'DateInput',
+ name: 'DateInput — Formats',
+ displayName: 'DateInput — Formats',
+ description:
+ "The format prop reuses Timestamp's format vocabulary to control how the committed value is displayed — date, date_long (default), date_weekday, and system_date — or a function for a fully custom string. Formatting applies only to the committed value, never to text the user is actively typing.",
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['DateInput', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputFormats.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputFormats.tsx
new file mode 100644
index 0000000000..ab870ddb6f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DateInput/DateInputFormats.tsx
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {DateInput} from '@astryxdesign/core/DateInput';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+type DateString =
+ `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+
+export default function DateInputFormats() {
+ const [value, setValue] = useState<DateString | undefined>(
+ '2026-03-21' as DateString,
+ );
+
+ return (
+ <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+ <Text type="supporting" color="secondary">
+ The same committed date, displayed with different formats.
+ </Text>
+ <DateInput
+ label="Short month (date)"
+ value={value}
+ onChange={setValue}
+ format="date"
+ />
+ <DateInput
+ label="Long month (date_long, default)"
+ value={value}
+ onChange={setValue}
+ format="date_long"
+ />
+ <DateInput
+ label="With weekday (date_weekday)"
+ value={value}
+ onChange={setValue}
+ format="date_weekday"
+ />
+ <DateInput
+ label="ISO 8601 (system_date)"
+ value={value}
+ onChange={setValue}
+ format="system_date"
+ />
+ <DateInput
+ label="Custom function"
+ value={value}
+ onChange={setValue}
+ format={iso => `Ship by ${iso}`}
+ />
+ </Stack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx
index 13d9b0aa1d..f0ec931d0b 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx
@@ -17,6 +17,8 @@ export default function TimestampFormats() {
</Text>
<Stack direction="horizontal" gap={4} vAlign="center">
<Timestamp value={DATE} format="date" color="primary" />
+ <Timestamp value={DATE} format="date_long" color="primary" />
+ <Timestamp value={DATE} format="date_weekday" color="primary" />
<Timestamp value={DATE} format="date_time" color="primary" />
<Timestamp value={DATE} format="time" color="primary" />
</Stack>
@@ -26,9 +28,24 @@ export default function TimestampFormats() {
System formats (logs and dev tools)
</Text>
<Stack direction="horizontal" gap={4} vAlign="center">
- <Timestamp value={DATE} format="system_date" type="code" color="primary" />
- <Timestamp value={DATE} format="system_date_time" type="code" color="primary" />
- <Timestamp value={DATE} format="system_time" type="code" color="primary" />
+ <Timestamp
+ value={DATE}
+ format="system_date"
+ type="code"
+ color="primary"
+ />
+ <Timestamp
+ value={DATE}
+ format="system_date_time"
+ type="code"
+ color="primary"
+ />
+ <Timestamp
+ value={DATE}
+ format="system_time"
+ type="code"
+ color="primary"
+ />
</Stack>
</Stack>
</Stack>
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index fdab1deecf..40bf34df14 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -135,6 +135,13 @@ export const docs = {
'Number of months displayed simultaneously in the calendar popover.',
default: '1',
},
+ {
+ name: 'format',
+ type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
+ description:
+ "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
+ default: "'date_long'",
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -388,6 +395,13 @@ export const docsZh = {
description: '日历弹出层中同时显示的月份数量。',
default: '1',
},
+ {
+ name: 'format',
+ type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
+ description:
+ "已选日期的显示格式。命名值复用 Timestamp 的格式词汇:'date' 显示 'Mar 21, 2026','date_long' 显示 'March 21, 2026','date_weekday' 显示 'Wed, Mar 21, 2026','system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值,不影响正在输入的文本。",
+ default: "'date_long'",
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -481,6 +495,8 @@ export const docsDense = {
labelTooltip: 'tooltip text via info icon at label end',
hasClear: 'Shows clear button when date is set. Clears value on click.',
numberOfMonths: 'months shown simultaneously in calendar popover',
+ format:
+ "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
xstyle: 'StyleX styles for layout; must be stylex.create() value',
},
};
diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsx
index dc89738f0e..1fd60b1051 100644
--- a/packages/core/src/DateInput/DateInput.test.tsx
+++ b/packages/core/src/DateInput/DateInput.test.tsx
@@ -834,4 +834,112 @@ describe('DateInput', () => {
expect(input).not.toHaveAttribute('aria-disabled');
});
});
+
+ describe('format', () => {
+ it('defaults to the long-month date_long shape', () => {
+ // Non-breaking default: byte-identical to the historical hardcoded
+ // DATE_FORMAT_LONG rendering. `format` now defaults to 'date_long'.
+ render(<DateInput label="Date" value="2026-01-25" onChange={() => {}} />);
+ expect(screen.getByDisplayValue('January 25, 2026')).toBeInTheDocument();
+ });
+
+ it('renders the long-month shape for explicit format="date_long"', () => {
+ // Explicit date_long is identical to the unset default above and to the
+ // old hardcoded long-month output — real named parity with Timestamp.
+ render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format="date_long"
+ />,
+ );
+ expect(screen.getByDisplayValue('January 25, 2026')).toBeInTheDocument();
+ });
+
+ it('renders the short-month shape for format="date"', () => {
+ // Same literal + same shape as <Timestamp format="date" />.
+ render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format="date"
+ />,
+ );
+ expect(screen.getByDisplayValue('Jan 25, 2026')).toBeInTheDocument();
+ });
+
+ it('renders the ISO shape for format="system_date"', () => {
+ render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format="system_date"
+ />,
+ );
+ expect(screen.getByDisplayValue('2026-01-25')).toBeInTheDocument();
+ });
+
+ it('renders a weekday prefix for format="date_weekday"', () => {
+ render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format="date_weekday"
+ />,
+ );
+ // 2026-01-25 is a Sunday; assert the weekday-prefixed shape without
+ // over-fitting locale punctuation.
+ const input = screen.getByRole('combobox');
+ expect(input).toHaveValue('Sun, Jan 25, 2026');
+ });
+
+ it('supports a custom function format', () => {
+ render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format={iso => `custom:${iso}`}
+ />,
+ );
+ expect(screen.getByDisplayValue('custom:2026-01-25')).toBeInTheDocument();
+ });
+
+ it('does not apply format to in-progress typed input', async () => {
+ const user = userEvent.setup();
+ render(
+ <DateInput label="Date" onChange={() => {}} format="system_date" />,
+ );
+ const input = screen.getByRole('combobox');
+ await user.click(input);
+ await user.type(input, 'January 25');
+ // While typing, the raw text is shown verbatim — not reformatted.
+ expect(input).toHaveValue('January 25');
+ });
+
+ it('recomputes the display in format on external value change', () => {
+ const {rerender} = render(
+ <DateInput
+ label="Date"
+ value="2026-01-25"
+ onChange={() => {}}
+ format="date"
+ />,
+ );
+ expect(screen.getByDisplayValue('Jan 25, 2026')).toBeInTheDocument();
+ rerender(
+ <DateInput
+ label="Date"
+ value="2026-03-10"
+ onChange={() => {}}
+ format="date"
+ />,
+ );
+ expect(screen.getByDisplayValue('Mar 10, 2026')).toBeInTheDocument();
+ });
+ });
});
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index a3355b4d68..86a019b991 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -57,9 +57,9 @@ import {getInputARIA, parseDateInput} from '../utils';
import {
plainDateFromISO,
plainDateToISO,
- plainDateFormat,
- DATE_FORMAT_LONG,
+ formatSharedDate,
} from '../utils/plainDate';
+import type {TimestampFormat} from '../Timestamp';
const styles = stylex.create({
iconButton: {
@@ -127,6 +127,25 @@ const sizeStyles = stylex.create({
export type DateInputSize = keyof typeof sizeStyles;
+/**
+ * Named display formats for a committed date value. These are the date-only
+ * members of Timestamp's `format` vocabulary — reused verbatim (via
+ * `Extract`) so the same literal renders the same date shape in both
+ * `Timestamp` and `DateInput`:
+ * - `'date'`: locale short-month date, e.g. "Mar 21, 2026"
+ * - `'date_long'`: locale long-month date, e.g. "March 21, 2026" (the default)
+ * - `'date_weekday'`: short weekday + date, e.g. "Wed, Mar 21, 2026"
+ * - `'system_date'`: ISO 8601 calendar date, e.g. "2026-03-21"
+ *
+ * Because `DateInputFormat` is `Extract`ed from `TimestampFormat`, the two
+ * types stay in compile-time lockstep: renaming or removing one of these
+ * members from `TimestampFormat` breaks this type at build time.
+ */
+export type DateInputFormat = Extract<
+ TimestampFormat,
+ 'date' | 'date_long' | 'date_weekday' | 'system_date'
+>;
+
// Re-export shared types for convenience
export type {
@@ -283,6 +302,37 @@ export interface DateInputProps extends Omit<
* @default 1
*/
numberOfMonths?: 1 | 2;
+
+ /**
+ * How the committed date value is displayed in the text field. Accepts a
+ * named format reused from `Timestamp`'s `format` vocabulary (so the same
+ * literal renders the same date shape in both components) or a function that
+ * maps the ISO value to a custom display string.
+ *
+ * - `'date_long'` (default): long-month date, e.g. "March 21, 2026"
+ * - `'date'`: short-month date, e.g. "Mar 21, 2026"
+ * - `'date_weekday'`: short weekday + date, e.g. "Wed, Mar 21, 2026"
+ * - `'system_date'`: ISO 8601 calendar date, e.g. "2026-03-21"
+ * - `(value: ISODateString) => string`: fully custom display string
+ *
+ * Formatting applies only to the committed value — never to text the user is
+ * actively typing. A custom function's output that `parseDateInput` cannot
+ * read back can't be re-committed after an edit; external `value` changes
+ * always recompute the display from the ISO value.
+ *
+ * @default 'date_long'
+ * @example
+ * ```
+ * <DateInput label="Ship date" value={date} onChange={setDate} format="date" />
+ * <DateInput
+ * label="Ship date"
+ * value={date}
+ * onChange={setDate}
+ * format={iso => new Date(iso + 'T00:00').toDateString()}
+ * />
+ * ```
+ */
+ format?: DateInputFormat | ((value: ISODateString) => string);
}
/**
@@ -318,6 +368,7 @@ export function DateInput({
labelTooltip,
hasClear = false,
numberOfMonths = 1,
+ format = 'date_long',
width,
xstyle,
className,
@@ -404,12 +455,26 @@ export function DateInput({
}
}
+ // Format a committed ISO value for display. The default `date_long` renders
+ // the long-month shape (byte-identical to the historical hardcoded
+ // DATE_FORMAT_LONG rendering, so still non-breaking); a function is called
+ // with the ISO value; every other named member reuses Timestamp's shared
+ // date mapping. Applies ONLY to the committed value, never to in-progress
+ // typed input.
+ const formatCommittedValue = useCallback(
+ (iso: ISODateString): string =>
+ typeof format === 'function'
+ ? format(iso)
+ : formatSharedDate(plainDateFromISO(iso), format),
+ [format],
+ );
+
// Display value: pending input if typing, otherwise formatted value
const displayValue =
pendingInput !== null
? pendingInput
: optimisticValue && /^\d{4}-\d{2}-\d{2}$/.test(optimisticValue)
- ? plainDateFormat(plainDateFromISO(optimisticValue), DATE_FORMAT_LONG)
+ ? formatCommittedValue(optimisticValue)
: '';
// Check if current input is valid (for styling purposes)
diff --git a/packages/core/src/DateInput/index.ts b/packages/core/src/DateInput/index.ts
index b6d56b0f2d..eed5271fd2 100644
--- a/packages/core/src/DateInput/index.ts
+++ b/packages/core/src/DateInput/index.ts
@@ -13,6 +13,7 @@ export {DateInput} from './DateInput';
export type {
DateInputProps,
DateInputSize,
+ DateInputFormat,
DateInputStatus,
DateInputStatusType,
} from './DateInput';
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index 025d03ad81..4a70273c67 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -26,9 +26,9 @@ export const docs = {
},
{
name: 'format',
- type: "'relative' | 'auto' | 'date' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
+ type: "'relative' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
description:
- "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
+ "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
default: "'auto'",
},
{
@@ -110,7 +110,7 @@ export const docs = {
export const docsZh = {
propDescriptions: {
value: '\u8981\u663e\u793a\u7684\u65e5\u671f/\u65f6\u95f4\u3002\u63a5\u53d7 Unix \u65f6\u95f4\u6233\uff08\u79d2\uff09\u6216 ISO 8601 \u5b57\u7b26\u4e32\u3002',
- format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
+ format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'date_long' \u663e\u793a\u957f\u6708\u4efd\u65e5\u671f\uff0c'date_weekday' \u663e\u793a\u661f\u671f+\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
autoThreshold: "auto \u683c\u5f0f\u4ece\u76f8\u5bf9\u65f6\u95f4\u5207\u6362\u5230 date_time \u7684\u9608\u503c\u79d2\u6570\u3002",
hasTooltip: '\u60ac\u505c\u65f6\u662f\u5426\u663e\u793a\u5305\u542b\u5b8c\u6574\u65e5\u671f/\u65f6\u95f4\u7684\u5de5\u5177\u63d0\u793a\uff08\u76f8\u5bf9\u65f6\u95f4\u6a21\u5f0f\uff09\u3002',
isTimezoneShown: '\u662f\u5426\u9644\u52a0\u65f6\u533a\u7f29\u5199\u3002',
@@ -157,7 +157,7 @@ export const docsDense = {
},
propDescriptions: {
value: 'date/time as unix seconds or ISO string',
- format: "display mode: 'relative', 'auto', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
+ format: "display mode: 'relative', 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
hasTooltip: 'show full time tooltip on hover (relative mode)',
isTimezoneShown: 'append timezone abbreviation',
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index d412f881b6..f0c2997326 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/src/Timestamp/Timestamp.test.tsx
@@ -99,6 +99,38 @@ describe('Timestamp', () => {
expect(el.textContent).not.toContain(':');
});
+ it('renders date_weekday format with a weekday prefix', () => {
+ render(
+ <Timestamp
+ value="2026-02-19T17:00:00Z"
+ format="date_weekday"
+ data-testid="ts"
+ />,
+ );
+ const el = screen.getByTestId('ts');
+ // Includes the year and a leading weekday abbreviation, no time portion.
+ expect(el.textContent).toContain('2026');
+ expect(el.textContent).not.toContain(':');
+ // en-US short weekday for 2026-02-19 is "Thu"; assert a weekday word is
+ // present without over-fitting the exact locale punctuation.
+ expect(el.textContent).toMatch(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/);
+ });
+
+ it('renders date_long format with a full month name', () => {
+ render(
+ <Timestamp
+ value="2026-02-19T17:00:00Z"
+ format="date_long"
+ data-testid="ts"
+ />,
+ );
+ const el = screen.getByTestId('ts');
+ // Long-month shape: full month name, year, no time portion.
+ expect(el.textContent).toContain('February');
+ expect(el.textContent).toContain('2026');
+ expect(el.textContent).not.toContain(':');
+ });
+
it('renders date_time format', () => {
render(
<Timestamp
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index c45b07f361..29a2ad7159 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -25,6 +25,7 @@ import {useDevWarning} from '../hooks/useDevWarning';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {colorVars} from '../theme/tokens.stylex';
+import {SHARED_DATE_FORMAT_OPTIONS} from '../utils/plainDate';
const LazyXDSTooltip = lazy(async () =>
import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -38,6 +39,8 @@ export type TimestampFormat =
| 'relative'
| 'auto'
| 'date'
+ | 'date_long'
+ | 'date_weekday'
| 'date_time'
| 'time'
| 'system_date'
@@ -54,6 +57,8 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
* - `'relative'`: "2 hours ago", "yesterday", "now"
* - `'auto'`: Relative for recent times, `date_time` for older
* - `'date'`: "Mar 21, 2025"
+ * - `'date_long'`: "March 21, 2025"
+ * - `'date_weekday'`: "Wed, Mar 21, 2025"
* - `'date_time'`: "Mar 21, 2025, 2:51 PM"
* - `'time'`: "2:51 PM"
* - `'system_date'`: "2025-03-21"
@@ -250,11 +255,22 @@ function formatTimestamp(
): string {
switch (format) {
case 'date':
- return new Intl.DateTimeFormat(undefined, {
- year: 'numeric',
- month: 'short',
- day: 'numeric',
- }).format(date);
+ return new Intl.DateTimeFormat(
+ undefined,
+ SHARED_DATE_FORMAT_OPTIONS.date,
+ ).format(date);
+
+ case 'date_long':
+ return new Intl.DateTimeFormat(
+ undefined,
+ SHARED_DATE_FORMAT_OPTIONS.date_long,
+ ).format(date);
+
+ case 'date_weekday':
+ return new Intl.DateTimeFormat(
+ undefined,
+ SHARED_DATE_FORMAT_OPTIONS.date_weekday,
+ ).format(date);
case 'date_time':
return new Intl.DateTimeFormat(undefined, {
diff --git a/packages/core/src/utils/index.ts b/packages/core/src/utils/index.ts
index 2ec626ad52..34b204a811 100644
--- a/packages/core/src/utils/index.ts
+++ b/packages/core/src/utils/index.ts
@@ -42,12 +42,16 @@ export {
plainDateSetEndOfWeekExclusive,
plainDateGetWeekNumber,
plainDateFormat,
+ formatSharedDate,
DATE_FORMAT_WITH_WEEKDAY,
+ DATE_FORMAT_SHORT_WITH_WEEKDAY,
DATE_FORMAT_LONG,
DATE_FORMAT_MONTH_YEAR,
DATE_FORMAT_SHORT,
DATE_FORMAT_SHORT_WITH_YEAR,
+ SHARED_DATE_FORMAT_OPTIONS,
} from './plainDate';
+export type {SharedDateFormat} from './plainDate';
export {
parseISOTime,
diff --git a/packages/core/src/utils/plainDate.test.ts b/packages/core/src/utils/plainDate.test.ts
index 31f442a94d..c0ad3d8aa4 100644
--- a/packages/core/src/utils/plainDate.test.ts
+++ b/packages/core/src/utils/plainDate.test.ts
@@ -26,6 +26,7 @@ import {
plainDateSetEndOfWeekExclusive,
plainDateGetWeekNumber,
plainDateFormat,
+ formatSharedDate,
DATE_FORMAT_WITH_WEEKDAY,
} from './plainDate';
import type {ISODateString} from './dateTypes';
@@ -521,3 +522,24 @@ describe('plainDateFormat', () => {
expect(result).toContain('25');
});
});
+
+describe('formatSharedDate', () => {
+ const pd: PlainDate = {year: 2026, month: 1, day: 25};
+
+ it('formats the short-month "date" shape', () => {
+ expect(formatSharedDate(pd, 'date')).toBe('Jan 25, 2026');
+ });
+
+ it('formats the long-month "date_long" shape', () => {
+ expect(formatSharedDate(pd, 'date_long')).toBe('January 25, 2026');
+ });
+
+ it('formats the weekday "date_weekday" shape', () => {
+ // 2026-01-25 is a Sunday.
+ expect(formatSharedDate(pd, 'date_weekday')).toBe('Sun, Jan 25, 2026');
+ });
+
+ it('formats the ISO "system_date" shape', () => {
+ expect(formatSharedDate(pd, 'system_date')).toBe('2026-01-25');
+ });
+});
diff --git a/packages/core/src/utils/plainDate.ts b/packages/core/src/utils/plainDate.ts
index be573e3641..e1389133ad 100644
--- a/packages/core/src/utils/plainDate.ts
+++ b/packages/core/src/utils/plainDate.ts
@@ -229,6 +229,15 @@ export const DATE_FORMAT_WITH_WEEKDAY: Intl.DateTimeFormatOptions = {
day: 'numeric',
};
+// e.g. "Wed, May 21, 2026" (locale-dependent) — short weekday + short month.
+// Backs the shared `date_weekday` format used by both Timestamp and DateInput.
+export const DATE_FORMAT_SHORT_WITH_WEEKDAY: Intl.DateTimeFormatOptions = {
+ weekday: 'short',
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+};
+
// e.g. "May 21, 2026" (locale-dependent)
export const DATE_FORMAT_LONG: Intl.DateTimeFormatOptions = {
year: 'numeric',
@@ -263,3 +272,55 @@ export function plainDateFormat(
plainDateToDate(pd),
);
}
+
+// =============================================================================
+// Shared date-only format vocabulary
+// =============================================================================
+
+/**
+ * The date-only members of Timestamp's `format` vocabulary that a
+ * calendar-date field (no time-of-day) can render. Both Timestamp and
+ * DateInput share these string literals and the mapping below so that the same
+ * literal renders the same date shape in either component.
+ *
+ * - `date`: locale short-month date, e.g. "Mar 21, 2026"
+ * - `date_long`: locale long-month date, e.g. "March 21, 2026"
+ * - `date_weekday`: short weekday + short-month date, e.g. "Wed, Mar 21, 2026"
+ * - `system_date`: ISO 8601 calendar date, e.g. "2026-03-21"
+ */
+export type SharedDateFormat =
+ 'date' | 'date_long' | 'date_weekday' | 'system_date';
+
+/**
+ * Intl option bags for the locale-aware shared date members. `system_date` is
+ * intentionally absent — it is emitted as a fixed ISO `YYYY-MM-DD` string, not
+ * via `Intl` — and is handled directly by {@link formatSharedDate}.
+ *
+ * This is the single source of truth consumed by both Timestamp's
+ * `formatTimestamp` switch and DateInput's display path, so the two never
+ * drift for the members they share.
+ */
+export const SHARED_DATE_FORMAT_OPTIONS: Record<
+ Exclude<SharedDateFormat, 'system_date'>,
+ Intl.DateTimeFormatOptions
+> = {
+ date: DATE_FORMAT_SHORT_WITH_YEAR,
+ date_long: DATE_FORMAT_LONG,
+ date_weekday: DATE_FORMAT_SHORT_WITH_WEEKDAY,
+};
+
+/**
+ * Renders a {@link PlainDate} using one of the {@link SharedDateFormat}
+ * members. The shared entry point DateInput uses for the named-format path;
+ * Timestamp maps the same members onto {@link SHARED_DATE_FORMAT_OPTIONS} in
+ * its own `formatTimestamp` switch (its input is a `Date`, not a `PlainDate`).
+ */
+export function formatSharedDate(
+ pd: PlainDate,
+ format: SharedDateFormat,
+): string {
+ if (format === 'system_date') {
+ return plainDateToISO(pd);
+ }
+ return plainDateFormat(pd, SHARED_DATE_FORMAT_OPTIONS[format]);
+}