Skip to content

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

TypeScript

Improve Timestamp docs page and block examples (#1611)

Kenton Quatmanfa31f4dc6f8e
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.doc.mjs
index b2f5bc05f2..3a49a42bcd 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.doc.mjs
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Timestamp — Auto Format',
- description:
- 'Auto format that switches between relative time for recent dates and absolute date_time for older ones.',
+ name: 'Timestamp — Auto',
+ description: 'Auto format that shows relative time for recent dates and switches to the full date for older ones. The default choice for most use cases.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Timestamp', 'Text'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Timestamp', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.tsx
index 18bf1af489..fbb316bdcd 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.tsx
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampAutoFormat.tsx
@@ -1,23 +1,32 @@
'use client';
import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function TimestampAutoFormat() {
+ const now = Date.now() / 1000;
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
- <div>
- <XDSText type="label" color="secondary">
- Recent (relative):{' '}
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Recent — renders as relative
</XDSText>
- <XDSTimestamp value={Date.now() / 1000 - 3600} format="auto" />
- </div>
- <div>
- <XDSText type="label" color="secondary">
- Old (date_time):{' '}
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value={now - 300} format="auto" color="primary" />
+ <XDSTimestamp value={now - 7200} format="auto" color="primary" />
+ <XDSTimestamp value={now - 86400} format="auto" color="primary" />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Older than 7 days — renders as date_time
</XDSText>
- <XDSTimestamp value="2025-01-01T12:00:00Z" format="auto" />
- </div>
- </div>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value="2025-01-15T09:30:00Z" format="auto" color="primary" />
+ <XDSTimestamp value="2024-06-01T14:00:00Z" format="auto" color="primary" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.doc.mjs
deleted file mode 100644
index 13945e6b9f..0000000000
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Timestamp — Date & Time Formats',
- description:
- 'All date/time display formats including date, date_time, time, and system variants.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Timestamp', 'Text'],
-};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.tsx
deleted file mode 100644
index ba6d6044c7..0000000000
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampDateTimeFormats.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-'use client';
-
-import {XDSTimestamp} from '@xds/core/Timestamp';
-import {XDSText} from '@xds/core/Text';
-
-export default function TimestampDateTimeFormats() {
- const date = '2026-02-19T17:00:00Z';
- return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
- <div>
- <XDSText type="label" color="secondary">
- date:{' '}
- </XDSText>
- <XDSTimestamp value={date} format="date" />
- </div>
- <div>
- <XDSText type="label" color="secondary">
- date_time:{' '}
- </XDSText>
- <XDSTimestamp value={date} format="date_time" />
- </div>
- <div>
- <XDSText type="label" color="secondary">
- time:{' '}
- </XDSText>
- <XDSTimestamp value={date} format="time" />
- </div>
- <div>
- <XDSText type="label" color="secondary">
- system_date:{' '}
- </XDSText>
- <XDSTimestamp value={date} format="system_date" type="code" />
- </div>
- <div>
- <XDSText type="label" color="secondary">
- system_date_time:{' '}
- </XDSText>
- <XDSTimestamp value={date} format="system_date_time" type="code" />
- </div>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.doc.mjs
new file mode 100644
index 0000000000..36e34ad81a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Timestamp — Formats',
+ description: 'All display formats side by side: date, date_time, time, and their system equivalents. Use date and date_time for user-facing UI, system variants for logs and dev tools.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Timestamp', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx
new file mode 100644
index 0000000000..a6d6bbcc11
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampFormats.tsx
@@ -0,0 +1,34 @@
+'use client';
+
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const DATE = '2026-02-19T17:00:00Z';
+
+export default function TimestampFormats() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ User-facing formats
+ </XDSText>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value={DATE} format="date" color="primary" />
+ <XDSTimestamp value={DATE} format="date_time" color="primary" />
+ <XDSTimestamp value={DATE} format="time" color="primary" />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ System formats (logs and dev tools)
+ </XDSText>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value={DATE} format="system_date" type="code" color="primary" />
+ <XDSTimestamp value={DATE} format="system_date_time" type="code" color="primary" />
+ <XDSTimestamp value={DATE} format="system_time" type="code" color="primary" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.doc.mjs
index 9e466f6e88..82f458d9b6 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.doc.mjs
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Timestamp — Relative Format',
- description:
- 'Series of timestamps showing relative time labels from seconds ago to months ago.',
+ name: 'Timestamp — Relative',
+ description: 'Relative time labels from seconds to months ago, with hover tooltips showing the full date. Use in feeds, comment threads, and activity logs.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Timestamp'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Timestamp', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.tsx
index b72885b74e..a0082322d2 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.tsx
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampRelativeFormat.tsx
@@ -1,23 +1,24 @@
'use client';
import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function TimestampRelativeFormat() {
const now = Date.now() / 1000;
return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: 8,
- alignItems: 'flex-start',
- }}>
- <XDSTimestamp value={now - 5} format="relative" />
- <XDSTimestamp value={now - 120} format="relative" />
- <XDSTimestamp value={now - 3600} format="relative" />
- <XDSTimestamp value={now - 86400} format="relative" />
- <XDSTimestamp value={now - 259200} format="relative" />
- <XDSTimestamp value={now - 90 * 86400} format="relative" />
- </div>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Relative timestamps (hover for full date)
+ </XDSText>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSTimestamp value={now - 5} format="relative" color="primary" />
+ <XDSTimestamp value={now - 120} format="relative" color="primary" />
+ <XDSTimestamp value={now - 3600} format="relative" color="primary" />
+ <XDSTimestamp value={now - 86400} format="relative" color="primary" />
+ <XDSTimestamp value={now - 259200} format="relative" color="primary" />
+ <XDSTimestamp value={now - 90 * 86400} format="relative" color="primary" />
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.doc.mjs
index 09e35d138c..3d44bc0c72 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'Timestamp',
isReady: true,
- aspectRatio: 1,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.tsx
index 844791c093..5a15006548 100644
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampShowcase.tsx
@@ -3,5 +3,5 @@
import {XDSTimestamp} from '@xds/core/Timestamp';
export default function TimestampShowcase() {
- return <XDSTimestamp value="2026-03-25T12:00:00Z" />;
+ return <XDSTimestamp value="2026-03-25T12:00:00Z" color="primary" />;
}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.doc.mjs
new file mode 100644
index 0000000000..6459dd8ed8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Timestamp — Timezone',
+ description: 'Timestamps with the timezone abbreviation appended. Enable isTimezoneShown for audiences across time zones, like audit logs or team calendars.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Timestamp', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.tsx
new file mode 100644
index 0000000000..9a745909d8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Timestamp/TimestampTimezone.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const DATE = '2026-02-19T17:00:00Z';
+
+export default function TimestampTimezone() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ User-facing with timezone
+ </XDSText>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value={DATE} format="date_time" isTimezoneShown color="primary" />
+ <XDSTimestamp value={DATE} format="time" isTimezoneShown color="primary" />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ System formats with timezone
+ </XDSText>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSTimestamp value={DATE} format="system_date_time" isTimezoneShown type="code" color="primary" />
+ <XDSTimestamp value={DATE} format="system_time" isTimezoneShown type="code" color="primary" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.doc.mjs b/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.doc.mjs
deleted file mode 100644
index a17750e9e6..0000000000
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Timestamp — With Timezone',
- description:
- 'Date-time timestamp with the timezone abbreviation appended.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Timestamp'],
-};
diff --git a/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.tsx b/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.tsx
deleted file mode 100644
index 11bc4417f1..0000000000
--- a/packages/cli/templates/blocks/components/Timestamp/TimestampWithTimezone.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-'use client';
-
-import {XDSTimestamp} from '@xds/core/Timestamp';
-
-export default function TimestampWithTimezone() {
- return (
- <XDSTimestamp
- value="2026-02-19T17:00:00Z"
- format="date_time"
- isTimezoneShown
- />
- );
-}
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index ef966aef15..e394b31536 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -43,7 +43,7 @@ export const docs = {
name: 'isLive',
type: 'boolean',
description:
- 'Whether the relative time should update live (e.g. "2 min ago" → "3 min ago").',
+ 'Whether the relative time should update live (e.g. "2 min ago" \u2192 "3 min ago").',
default: 'false',
},
{
@@ -76,16 +76,19 @@ export const docs = {
},
usage: {
description:
- 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ 'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled \u2014 picking relative for recency, absolute for precision, or auto to let the component decide.',
bestPractices: [
- { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
- { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
- { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
+ {guidance: true, description: 'Use the auto format in feeds and lists so recent items show \u201c2 hours ago\u201d and older items show the full date automatically.'},
+ {guidance: true, description: 'Keep formatting consistent within the same list or table \u2014 mixing relative and absolute timestamps in the same column confuses scanning.'},
+ {guidance: true, description: 'Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.'},
+ {guidance: true, description: 'Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.'},
+ {guidance: false, description: 'Don\u2019t display raw Unix timestamps or ISO strings to users \u2014 always pass them through Timestamp to get a human-readable format.'},
+ {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI \u2014 they are meant for developer tools, logs, and machine-readable contexts.'},
+ {guidance: false, description: 'Don\u2019t disable the tooltip on relative timestamps \u2014 users expect to hover for the full date when they see \u201c3 hours ago\u201d.'},
],
anatomy: [
- {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
- {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
- {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
+ {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like \u201c2 hours ago\u201d or \u201cMar 21, 2025\u201d.'},
+ {name: 'Tooltip', required: false, description: 'A hover card showing the full absolute date and time when the display is relative.'},
],
},
};
@@ -93,54 +96,56 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
propDescriptions: {
- value: '要显示的日期/时间。接受 Unix 时间戳(秒)或 ISO 8601 字符串。',
- format: "显示格式。'relative' 显示 '2小时前','date' 显示日期,'auto' 根据时间近远自动切换。",
- autoThreshold: "auto 格式从相对时间切换到 date_time 的阈值秒数。",
- hasTooltip: '悬停时是否显示包含完整日期/时间的工具提示(相对时间模式)。',
- isTimezoneShown: '是否附加时区缩写。',
- isLive: '相对时间是否实时更新。',
- type: '来自 XDSText 的语义文本类型。',
- size: '显式字体大小覆盖。',
- color: '文字颜色。',
- weight: '字体粗细覆盖。',
+ 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",
+ 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',
+ isLive: '\u76f8\u5bf9\u65f6\u95f4\u662f\u5426\u5b9e\u65f6\u66f4\u65b0\u3002',
+ type: '\u6765\u81ea XDSText \u7684\u8bed\u4e49\u6587\u672c\u7c7b\u578b\u3002',
+ size: '\u663e\u5f0f\u5b57\u4f53\u5927\u5c0f\u8986\u76d6\u3002',
+ color: '\u6587\u5b57\u989c\u8272\u3002',
+ weight: '\u5b57\u4f53\u7c97\u7ec6\u8986\u76d6\u3002',
},
usage: {
description:
- 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ 'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled \u2014 picking relative for recency, absolute for precision, or auto to let the component decide.',
bestPractices: [
- { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
- { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
- { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
+ {guidance: true, description: 'Use the auto format in feeds and lists so recent items show \u201c2 hours ago\u201d and older items show the full date automatically.'},
+ {guidance: true, description: 'Keep formatting consistent within the same list or table \u2014 mixing relative and absolute timestamps in the same column confuses scanning.'},
+ {guidance: true, description: 'Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.'},
+ {guidance: true, description: 'Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.'},
+ {guidance: false, description: 'Don\u2019t display raw Unix timestamps or ISO strings to users \u2014 always pass them through Timestamp to get a human-readable format.'},
+ {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI \u2014 they are meant for developer tools, logs, and machine-readable contexts.'},
+ {guidance: false, description: 'Don\u2019t disable the tooltip on relative timestamps \u2014 users expect to hover for the full date when they see \u201c3 hours ago\u201d.'},
],
anatomy: [
- {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
- {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
- {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
+ {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like \u201c2 hours ago\u201d or \u201cMar 21, 2025\u201d.'},
+ {name: 'Tooltip', required: false, description: 'A hover card showing the full absolute date and time when the display is relative.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'formatted timestamp display with relative/absolute/auto modes via XDSText',
+ description: 'formatted timestamp with relative/absolute/auto modes, live updates, timezone display',
usage: {
description:
- 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ 'Timestamp formats a date or time into readable text. Use for creation dates, update times, or schedules \u2014 relative for recency, absolute for precision, auto to switch automatically.',
bestPractices: [
- { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
- { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
- { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
- ],
- anatomy: [
- {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
- {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
- {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
+ {guidance: true, description: 'Auto format in feeds and lists \u2014 recent shows relative, older shows date_time.'},
+ {guidance: true, description: 'Consistent formatting within the same list or table column.'},
+ {guidance: true, description: 'isTimezoneShown for multi-timezone audiences.'},
+ {guidance: true, description: 'isLive for dashboards so relative time stays current.'},
+ {guidance: false, description: 'Don\u2019t show raw Unix timestamps or ISO strings \u2014 always use Timestamp.'},
+ {guidance: false, description: 'Avoid system_* formats in user-facing UI \u2014 those are for dev tools and logs.'},
+ {guidance: false, description: 'Don\u2019t disable tooltip on relative timestamps \u2014 users expect the full date on hover.'},
],
},
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'",
- autoThreshold: 'seconds threshold for auto relative→date_time switch',
+ autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
hasTooltip: 'show full time tooltip on hover (relative mode)',
isTimezoneShown: 'append timezone abbreviation',
isLive: 'live-update relative time',