Skip to content

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

TypeScript

docs: add Carousel docs, ChatSendButton sub-component docs (#1316)

Joeyca4e3822198f
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
new file mode 100644
index 0000000000..dfb7bfb9a6
--- /dev/null
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -0,0 +1,135 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Carousel',
+ description:
+ 'Horizontal scroll container with fade-edge overflow indication, optional navigation buttons, and scroll-snap support.',
+ keywords: ['carousel', 'slider', 'scroll', 'gallery', 'filmstrip', 'swiper', 'horizontal', 'overflow', 'snap'],
+ features: [
+ 'Overflow Detection: Gradient fades appear at edges when content overflows, signaling more items',
+ 'Navigation Buttons: Prev/next buttons appear on hover (desktop only) via XDSLayer top-layer rendering',
+ 'Scroll Snap: Optional snap-to-item behavior for precise item alignment',
+ 'Gap Scale: Configurable item spacing using the spacing token scale (0 to 4)',
+ 'Scale Animation: Items scale down slightly when entering/exiting the viewport via scroll-driven animation',
+ 'Accessible: role="region" with aria-roledescription="carousel" and configurable aria-label',
+ 'Reduced Motion: Respects prefers-reduced-motion for scroll behavior and entry animations',
+ ],
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
+ {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
+ {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+ {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
+ {name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
+ {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
+ {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},
+ {name: 'style', type: 'CSSProperties', description: 'Inline styles for the root element. Prefer xstyle.'},
+ {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSCarousel gap={1}>
+ <XDSThumbnail src="/a.jpg" alt="A" />
+ <XDSThumbnail src="/b.jpg" alt="B" />
+ <XDSThumbnail src="/c.jpg" alt="C" />
+</XDSCarousel>`,
+ },
+ {
+ label: 'With snap and wider gap',
+ code: `<XDSCarousel gap={2} hasSnap>
+ <XDSCard>Item 1</XDSCard>
+ <XDSCard>Item 2</XDSCard>
+ <XDSCard>Item 3</XDSCard>
+ <XDSCard>Item 4</XDSCard>
+</XDSCarousel>`,
+ },
+ {
+ label: 'Without navigation buttons',
+ code: `<XDSCarousel hasButtons={false} aria-label="Photo gallery">
+ <img src="/photo1.jpg" alt="Photo 1" />
+ <img src="/photo2.jpg" alt="Photo 2" />
+</XDSCarousel>`,
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-carousel'},
+ ],
+ },
+ accessibility: [
+ 'Root element uses role="region" with aria-roledescription="carousel" for screen reader context.',
+ 'Navigation buttons have accessible labels ("Scroll left", "Scroll right").',
+ 'Scroll behavior and scale animations respect prefers-reduced-motion.',
+ ],
+ notes: [
+ 'Navigation buttons render on the top layer via XDSLayer, so they escape parent overflow clipping.',
+ 'The fade-edge effect uses CSS mask-image gradients that transition smoothly.',
+ 'Each child is wrapped in a flex-shrink:0 container with scroll-snap-align:start when snap is enabled.',
+ 'Items use scroll-driven animation (animationTimeline: view(inline)) for the scale effect.',
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+ description: '水平滚动容器,具有渐变边缘溢出指示、可选导航按钮和滚动吸附支持。',
+ features: [
+ '溢出检测:当内容溢出时,边缘出现渐变淡化效果,提示还有更多项目',
+ '导航按钮:鼠标悬停时显示上一个/下一个按钮(仅桌面端),通过 XDSLayer 顶层渲染',
+ '滚动吸附:可选的吸附到项目行为,实现精确的项目对齐',
+ '间距比例:使用间距令牌比例(0 到 4)配置项目间距',
+ '缩放动画:项目在进入/离开视口时通过滚动驱动动画略微缩小',
+ '无障碍:role="region",带 aria-roledescription="carousel" 和可配置的 aria-label',
+ '减少动效:尊重 prefers-reduced-motion 的滚动行为和入场动画',
+ ],
+ propDescriptions: {
+ children: '在水平滚动容器中渲染的轮播项目。',
+ gap: '使用间距令牌比例的项目间距。',
+ hasButtons: '悬停时显示上一个/下一个导航按钮(仅桌面端)。',
+ hasSnap: '启用滚动吸附,使每个子元素吸附到起始边缘。',
+ 'aria-label': '轮播区域的无障碍标签。',
+ },
+ accessibility: [
+ '根元素使用 role="region" 和 aria-roledescription="carousel",为屏幕阅读器提供上下文。',
+ '导航按钮具有无障碍标签("向左滚动"、"向右滚动")。',
+ '滚动行为和缩放动画尊重 prefers-reduced-motion。',
+ ],
+ notes: [
+ '导航按钮通过 XDSLayer 在顶层渲染,因此它们可以逃离父级溢出裁剪。',
+ '渐变边缘效果使用 CSS mask-image 渐变,过渡平滑。',
+ '启用吸附时,每个子元素被包裹在 flex-shrink:0 容器中,带有 scroll-snap-align:start。',
+ '项目使用滚动驱动动画(animationTimeline: view(inline))实现缩放效果。',
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'horizontal scroll container w/ fade-edge overflow, optional prev/next nav buttons on top layer, scroll-snap',
+ features: [
+ 'overflow detection: gradient fades at edges when content overflows',
+ 'nav buttons: prev/next on hover (desktop) via XDSLayer top-layer',
+ 'scroll-snap: optional snap-to-item alignment',
+ 'gap scale: spacing token scale 0-4',
+ 'scale animation: items shrink at viewport edges via scroll-driven anim',
+ 'a11y: role=region + aria-roledescription=carousel',
+ 'prefers-reduced-motion: smooth scroll + scale anim disabled',
+ ],
+ propDescriptions: {
+ children: 'carousel items in horizontal scroll',
+ gap: 'item spacing via spacing token scale',
+ hasButtons: 'prev/next buttons on hover (desktop)',
+ hasSnap: 'scroll-snap; children snap to start edge',
+ 'aria-label': 'accessible label for carousel region',
+ },
+ accessibility: [
+ 'root: role=region + aria-roledescription=carousel',
+ 'nav buttons: "Scroll left"/"Scroll right" labels',
+ 'respects prefers-reduced-motion',
+ ],
+ notes: [
+ 'nav buttons on top layer via XDSLayer; escape parent overflow',
+ 'fade-edge: CSS mask-image gradients w/ smooth transition',
+ 'children wrapped in flex-shrink:0 + scroll-snap-align:start when snap on',
+ 'scroll-driven animation (animationTimeline: view(inline)) for scale effect',
+ ],
+};
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 4530d31f41..d5afe172f5 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -23,6 +23,7 @@ export const docs = {
'XDSSearchSource integration — reuses Typeahead search sources',
'Concentric radius — inner elements follow outer shell curvature',
'Themeable via --composer-radius and --composer-padding CSS vars',
+ 'Extractable send/stop button (XDSChatSendButton) with automatic composer context',
],
theming: {
targets: [
@@ -178,6 +179,24 @@ export const docs = {
{label: 'With tokens', code: `<XDSChatComposerAttachments>\n <XDSToken label="report.pdf" onDismiss={() => {}} />\n</XDSChatComposerAttachments>`},
],
},
+ {
+ name: 'XDSChatSendButton',
+ description: 'Circular send/stop toggle button for the composer. Reads state from XDSChatComposerContext by default so it works automatically inside XDSChatComposer. All context values can be overridden via props for standalone usage.',
+ props: [
+ {name: 'isStreaming', type: 'boolean', description: 'Whether the assistant is currently streaming. Defaults to context value.'},
+ {name: 'isDisabled', type: 'boolean', description: 'Whether the send button is disabled. Defaults to !canSend from context.'},
+ {name: 'onSend', type: '() => void', description: 'Called when the user clicks send. Defaults to context onSubmit.'},
+ {name: 'onStop', type: '() => void', description: 'Called when the user clicks stop during streaming. Defaults to context onStop.'},
+ {name: 'sendIcon', type: 'ReactNode', description: 'Custom icon for the send state. Defaults to arrowUp from icon registry.'},
+ {name: 'stopIcon', type: 'ReactNode', description: 'Custom icon for the stop state. Defaults to stop from icon registry.'},
+ {name: 'size', type: "'sm' | 'md'", description: 'Button size.', default: "'md'"},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'Additional StyleX styles.'},
+ ],
+ examples: [
+ {label: 'Default (inside composer)', code: '<XDSChatComposer onSubmit={handleSubmit} sendButton={<XDSChatSendButton />} />'},
+ {label: 'Custom icons', code: '<XDSChatSendButton sendIcon={<CustomSendIcon />} stopIcon={<CustomStopIcon />} onSend={handleSend} onStop={handleStop} />'},
+ ],
+ },
{
name: 'XDSChatTokenizedText',
description: 'Renders text with token patterns replaced by inline XDSBadge components. Use inside XDSChatMessageBubble to display @mentions or other tokens as styled badges.',
@@ -236,6 +255,7 @@ export const docsZh = {
'XDSSearchSource 集成 — 复用 Typeahead 搜索源',
'同心圆角 — 内部元素跟随外部外壳曲率',
'通过 --composer-radius 和 --composer-padding CSS 变量实现主题化',
+ '可提取的发送/停止按钮(XDSChatSendButton),自动读取编写器上下文',
],
components: [
{
@@ -331,6 +351,20 @@ export const docsZh = {
},
},
{
+ name: 'XDSChatSendButton',
+ description: '编写器的圆形发送/停止切换按钮。默认从 XDSChatComposerContext 读取状态,在 XDSChatComposer 内自动工作。所有上下文值均可通过 props 覆盖以用于独立使用。',
+ propDescriptions: {
+ isStreaming: '助手是否正在流式响应。默认使用上下文值。',
+ isDisabled: '发送按钮是否禁用。默认使用上下文的 !canSend。',
+ onSend: '用户点击发送时调用。默认使用上下文的 onSubmit。',
+ onStop: '流式响应期间用户点击停止时调用。默认使用上下文的 onStop。',
+ sendIcon: '发送状态的自定义图标。默认使用图标注册表的 arrowUp。',
+ stopIcon: '停止状态的自定义图标。默认使用图标注册表的 stop。',
+ size: '按钮大小。',
+ xstyle: '额外的 StyleX 样式。',
+ },
+ },
+ {
name: 'XDSChatTokenizedText',
description: '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,以徽章样式显示 @提及或其他标记。',
propDescriptions: {
@@ -372,6 +406,7 @@ export const docsDense = {
'XDSSearchSource integration; reuses Typeahead search sources',
'concentric radius; inner elements follow outer shell curvature',
'themeable via --composer-radius + --composer-padding CSS vars',
+ 'extractable send/stop btn (XDSChatSendButton) w/ auto composer context',
],
components: [
{
@@ -467,6 +502,20 @@ export const docsDense = {
},
},
{
+ name: 'XDSChatSendButton',
+ description: 'circular send/stop toggle btn for composer; reads XDSChatComposerContext; all context vals overridable via props',
+ propDescriptions: {
+ isStreaming: 'streaming state; defaults to context',
+ isDisabled: 'disabled; defaults to !canSend from context',
+ onSend: 'send click handler; defaults to context onSubmit',
+ onStop: 'stop click handler; defaults to context onStop',
+ sendIcon: 'custom send icon; default arrowUp from registry',
+ stopIcon: 'custom stop icon; default stop from registry',
+ size: 'btn size',
+ xstyle: 'additional StyleX styles',
+ },
+ },
+ {
name: 'XDSChatTokenizedText',
description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions',
propDescriptions: {
diff --git a/packages/core/src/Chat/XDSChatSendButton.tsx b/packages/core/src/Chat/XDSChatSendButton.tsx
index 831b273246..9953704747 100644
--- a/packages/core/src/Chat/XDSChatSendButton.tsx
+++ b/packages/core/src/Chat/XDSChatSendButton.tsx
@@ -60,6 +60,17 @@ const styles = stylex.create({
// Component
// =============================================================================
+/**
+ * Circular send/stop toggle button for the chat composer.
+ *
+ * Reads state from XDSChatComposerContext by default. Override any value
+ * via props for standalone usage.
+ *
+ * @example
+ * ```
+ * <XDSChatComposer onSubmit={handleSubmit} sendButton={<XDSChatSendButton />} />
+ * ```
+ */
export function XDSChatSendButton(props: XDSChatSendButtonProps): ReactNode {
const context = useXDSChatComposerContext();