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.mjsnew file mode 100644index 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.mjsindex 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.tsxindex 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();