An open source design system that's fully customizable and agent ready
TypeScript
feat(core): add XDSBlockquote component (#1149) (#2198)
Andrey Goder670ef4879fdb
diff --git a/apps/storybook/stories/Blockquote.stories.tsx b/apps/storybook/stories/Blockquote.stories.tsxnew file mode 100644index 0000000000..d635e1031c--- /dev/null+++ b/apps/storybook/stories/Blockquote.stories.tsx@@ -0,0 +1,105 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSBlockquote} from '@xds/core/Blockquote';+import {XDSCard} from '@xds/core/Card';+import {XDSSection} from '@xds/core/Section';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const meta: Meta<typeof XDSBlockquote> = {+ title: 'Core/Blockquote',+ component: XDSBlockquote,+ tags: ['autodocs'],+ argTypes: {+ cite: {+ control: 'text',+ description: 'Optional attribution for the quote',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSBlockquote>;++export const Default: Story = {+ args: {+ children:+ 'Design is not just what it looks like and feels like. Design is how it works.',+ },+ render: args => (+ <XDSSection variant="muted">+ <XDSCard>+ <XDSBlockquote {...args} />+ </XDSCard>+ </XDSSection>+ ),+};++export const WithCitation: Story = {+ render: () => (+ <XDSSection variant="muted">+ <XDSCard>+ <XDSBlockquote cite="Steve Jobs">+ Design is not just what it looks like and feels like. Design is how it+ works.+ </XDSBlockquote>+ </XDSCard>+ </XDSSection>+ ),+};++export const InContent: Story = {+ render: () => (+ <XDSSection variant="muted">+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSText type="body">+ In a 2003 interview, the importance of design thinking was+ emphasized:+ </XDSText>+ <XDSBlockquote cite="Steve Jobs">+ Design is not just what it looks like and feels like. Design is how+ it works.+ </XDSBlockquote>+ <XDSText type="body">+ This philosophy has guided product development for decades.+ </XDSText>+ </XDSVStack>+ </XDSCard>+ </XDSSection>+ ),+};++export const NestedContent: Story = {+ render: () => (+ <XDSSection variant="muted">+ <XDSCard>+ <XDSBlockquote>+ <XDSText type="body">+ The best way to predict the future is to invent it.+ </XDSText>+ <XDSText type="supporting">From a talk at PARC in 1971.</XDSText>+ </XDSBlockquote>+ </XDSCard>+ </XDSSection>+ ),+};++export const MultipleParagraphs: Story = {+ render: () => (+ <XDSSection variant="muted">+ <XDSCard>+ <XDSBlockquote cite="Alan Kay">+ <XDSVStack gap={2}>+ <XDSText type="body">+ The best way to predict the future is to invent it.+ </XDSText>+ <XDSText type="body">+ People who are really serious about software should make their own+ hardware.+ </XDSText>+ </XDSVStack>+ </XDSBlockquote>+ </XDSCard>+ </XDSSection>+ ),+};diff --git a/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjs b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjsnew file mode 100644index 0000000000..ec92c77b08--- /dev/null+++ b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjs@@ -0,0 +1,12 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Blockquote',+ name: 'Blockquote — Showcase',+ description:+ 'Blockquote with and without citation. A quick visual reference for the blockquote component.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Blockquote', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsx b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsxnew file mode 100644index 0000000000..469ec750fb--- /dev/null+++ b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsx@@ -0,0 +1,26 @@+'use client';++import {XDSBlockquote} from '@xds/core/Blockquote';+import {XDSStack} from '@xds/core/Layout';+import * as stylex from '@stylexjs/stylex';++const styles = stylex.create({+ root: {+ width: 500,+ },+});++export default function BlockquoteShowcase() {+ return (+ <XDSStack direction="vertical" gap={4} xstyle={styles.root}>+ <XDSBlockquote>+ Design is not just what it looks like and feels like. Design is how it+ works.+ </XDSBlockquote>+ <XDSBlockquote cite="Steve Jobs">+ The people who are crazy enough to think they can change the world are+ the ones who do.+ </XDSBlockquote>+ </XDSStack>+ );+}diff --git a/packages/core/package.json b/packages/core/package.jsonindex 2bd821840b..791b0f8893 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -103,6 +103,12 @@"import": "./dist/Banner/index.mjs","require": "./dist/Banner/index.js"},+ "./Blockquote": {+ "source": "./src/Blockquote/index.ts",+ "types": "./dist/Blockquote/index.d.ts",+ "import": "./dist/Blockquote/index.mjs",+ "require": "./dist/Blockquote/index.js"+ },"./Breadcrumbs": {"source": "./src/Breadcrumbs/index.ts","types": "./dist/Breadcrumbs/index.d.ts",diff --git a/packages/core/src/Blockquote/Blockquote.doc.mjs b/packages/core/src/Blockquote/Blockquote.doc.mjsnew file mode 100644index 0000000000..1fe71bc25a--- /dev/null+++ b/packages/core/src/Blockquote/Blockquote.doc.mjs@@ -0,0 +1,95 @@+++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Blockquote',+ keywords: ["blockquote","quote","citation","pullquote","quotation","cite","excerpt"],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content of the blockquote.',+ required: true,+ },+ {+ name: 'cite',+ type: 'ReactNode',+ description: 'Optional attribution for the quote. Rendered in a <footer> with <cite>.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',+ },+ ],+ theming: {+ targets: [+ {className: 'xds-blockquote', visualProps: []},+ ],+ },+ usage: {+ description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',+ bestPractices: [+ { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts from external sources.' },+ { guidance: true, description: 'Provide a cite prop when the source of the quote is known.' },+ { guidance: false, description: 'Use for callout boxes or informational notes — use XDSBanner for those.' },+ ],+ },+};++/** @type {import('../docs-types').ComponentDoc} */+export const docsZh = {+ name: 'Blockquote',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: '引用块的内容。',+ required: true,+ },+ {+ name: 'cite',+ type: 'ReactNode',+ description: '引用的可选出处。在 <footer> 中以 <cite> 渲染。',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是 style={{}} 这样的内联样式对象。',+ },+ ],+ theming: {+ targets: [+ {className: 'xds-blockquote', visualProps: []},+ ],+ },+ usage: {+ description: '带有强调色左边框和次要文本颜色的引用块。用于突出显示引用内容、推荐语或摘录。',+ bestPractices: [+ { guidance: true, description: '用于引用文本、推荐语或来自外部来源的高亮摘录。' },+ { guidance: true, description: '当引用来源已知时,提供 cite 属性。' },+ { guidance: false, description: '用于提示框或信息说明 — 应使用 XDSBanner。' },+ ],+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'styled quotation block w/ accent left border, secondary text, optional citation',+ usage: {+ description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',+ bestPractices: [+ { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts.' },+ { guidance: true, description: 'Provide cite when source is known.' },+ { guidance: false, description: 'Use for callouts/notes — use XDSBanner instead.' },+ ],+ },+ propDescriptions: {+ children: 'blockquote content',+ cite: 'optional attribution rendered in <footer><cite>',+ xstyle: 'StyleX styles for layout; must be stylex.create() value',+ },+};diff --git a/packages/core/src/Blockquote/XDSBlockquote.test.tsx b/packages/core/src/Blockquote/XDSBlockquote.test.tsxnew file mode 100644index 0000000000..9cc4a6fe7f--- /dev/null+++ b/packages/core/src/Blockquote/XDSBlockquote.test.tsx@@ -0,0 +1,88 @@+/**+ * @file XDSBlockquote.test.tsx+ * @input Uses vitest, @testing-library/react, XDSBlockquote component+ * @output Unit tests for XDSBlockquote component behavior+ * @position Testing; validates XDSBlockquote.tsx implementation+ *+ * SYNC: When XDSBlockquote.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSBlockquote} from './XDSBlockquote';++describe('XDSBlockquote', () => {+ it('renders children in a blockquote element', () => {+ render(<XDSBlockquote data-testid="bq">A quoted statement.</XDSBlockquote>);+ const element = screen.getByTestId('bq');+ expect(element).toBeInTheDocument();+ expect(element.tagName).toBe('BLOCKQUOTE');+ expect(element).toHaveTextContent('A quoted statement.');+ });++ it('renders xds-* class name for theme targeting', () => {+ render(<XDSBlockquote data-testid="bq">Quote</XDSBlockquote>);+ const element = screen.getByTestId('bq');+ expect(element.className).toContain('xds-blockquote');+ });++ it('renders without cite by default', () => {+ render(<XDSBlockquote data-testid="bq">Quote</XDSBlockquote>);+ const element = screen.getByTestId('bq');+ expect(element.querySelector('footer')).toBeNull();+ expect(element.querySelector('cite')).toBeNull();+ });++ it('renders cite when provided', () => {+ render(+ <XDSBlockquote cite="Steve Jobs" data-testid="bq">+ Design is not just what it looks like.+ </XDSBlockquote>,+ );+ const element = screen.getByTestId('bq');+ const footer = element.querySelector('footer');+ expect(footer).toBeInTheDocument();+ const cite = element.querySelector('cite');+ expect(cite).toBeInTheDocument();+ expect(cite).toHaveTextContent('Steve Jobs');+ });++ it('renders cite as ReactNode', () => {+ render(+ <XDSBlockquote+ cite={<span data-testid="custom-cite">Custom attribution</span>}+ data-testid="bq">+ Quote+ </XDSBlockquote>,+ );+ expect(screen.getByTestId('custom-cite')).toBeInTheDocument();+ expect(screen.getByTestId('custom-cite')).toHaveTextContent(+ 'Custom attribution',+ );+ });++ it('forwards ref correctly', () => {+ const ref = vi.fn();+ render(<XDSBlockquote ref={ref}>Quote</XDSBlockquote>);+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));+ });++ it('passes through additional props', () => {+ render(+ <XDSBlockquote data-testid="bq" aria-label="Important quote">+ Quote+ </XDSBlockquote>,+ );+ const element = screen.getByTestId('bq');+ expect(element).toHaveAttribute('aria-label', 'Important quote');+ });++ it('renders ReactNode children', () => {+ render(+ <XDSBlockquote data-testid="bq">+ <p data-testid="child-p">Paragraph inside blockquote</p>+ </XDSBlockquote>,+ );+ expect(screen.getByTestId('child-p')).toBeInTheDocument();+ });+});diff --git a/packages/core/src/Blockquote/XDSBlockquote.tsx b/packages/core/src/Blockquote/XDSBlockquote.tsxnew file mode 100644index 0000000000..a8d302c13f--- /dev/null+++ b/packages/core/src/Blockquote/XDSBlockquote.tsx@@ -0,0 +1,116 @@+'use client';++/**+ * @file XDSBlockquote.tsx+ * @input Uses React, stylex, spacing and color tokens+ * @output Exports XDSBlockquote component and XDSBlockquoteProps+ * @position Blockquote component; renders styled quotations with optional attribution+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Blockquote/Blockquote.doc.mjs+ * - /packages/core/src/Blockquote/XDSBlockquote.test.tsx+ * - /apps/storybook/stories/Blockquote.stories.tsx+ * - /packages/cli/templates/blocks/components/Blockquote/ (showcase blocks)+ */++import {type ReactNode} from 'react';+import type {XDSBaseProps} from '../XDSBaseProps';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {colorVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';+import {xdsClassName, mergeProps} from '../utils';++export interface XDSBlockquoteProps extends XDSBaseProps<HTMLQuoteElement> {+ /** Ref forwarded to the root <blockquote> element */+ ref?: React.Ref<HTMLQuoteElement>;+ /** Content of the blockquote */+ children: ReactNode;+ /**+ * Optional attribution for the quote. Rendered in a <footer> with <cite>.+ */+ cite?: ReactNode;+ /**+ * StyleX styles created via `stylex.create()`. Merged with the component's+ * base styles inside a single `stylex.props()` call for optimal deduplication.+ *+ * @example+ * ```+ * const overrides = stylex.create({ root: { marginBottom: 8 } });+ * <XDSBlockquote xstyle={overrides.root}>Quote</XDSBlockquote>+ * ```+ */+ xstyle?: StyleXStyles;+ /**+ * CSS class name(s) appended to the root element.+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.+ */+ className?: string;+ /**+ * Inline styles to apply to the root element. Spread after StyleX+ * inline styles, so these values take priority.+ */+ style?: React.CSSProperties;+}++const styles = stylex.create({+ root: {+ borderInlineStartWidth: spacingVars['--spacing-0-5'],+ borderInlineStartStyle: 'solid',+ borderInlineStartColor: colorVars['--color-border-emphasized'],+ paddingInlineStart: spacingVars['--spacing-4'],+ color: colorVars['--color-text-secondary'],+ marginInlineStart: 0,+ marginInlineEnd: 0,+ marginBlockStart: 0,+ marginBlockEnd: 0,+ },+ cite: {+ display: 'block',+ marginBlockStart: spacingVars['--spacing-2'],+ fontSize: typeScaleVars['--text-supporting-size'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ fontStyle: 'normal',+ },+});++/**+ * Blockquote component for displaying quoted content.+ *+ * Renders a semantic `<blockquote>` with an accent-colored left border+ * and secondary text color, matching the XDS visual language.+ *+ * @example+ * ```+ * <XDSBlockquote>Design is not just what it looks like.</XDSBlockquote>+ * ```+ */+export function XDSBlockquote({+ children,+ cite,+ xstyle,+ className,+ style,+ ref,+ ...props+}: XDSBlockquoteProps) {+ return (+ <blockquote+ ref={ref}+ {...mergeProps(+ xdsClassName('blockquote'),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}+ {...props}>+ {children}+ {cite != null && (+ <footer>+ <cite {...stylex.props(styles.cite)}>{cite}</cite>+ </footer>+ )}+ </blockquote>+ );+}++XDSBlockquote.displayName = 'XDSBlockquote';diff --git a/packages/core/src/Blockquote/index.ts b/packages/core/src/Blockquote/index.tsnew file mode 100644index 0000000000..57023805cf--- /dev/null+++ b/packages/core/src/Blockquote/index.ts@@ -0,0 +1,13 @@+'use client';++/**+ * @file index.ts+ * @input Imports from XDSBlockquote.tsx+ * @output Exports XDSBlockquote component and props type+ * @position Package entry point for Blockquote+ *+ * SYNC: When modified, update /packages/core/src/Blockquote/Blockquote.doc.mjs+ */++export {XDSBlockquote} from './XDSBlockquote';+export type {XDSBlockquoteProps} from './XDSBlockquote';diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsxindex 2f84c01323..092c4024ae 100644--- a/packages/core/src/Markdown/XDSMarkdown.tsx+++ b/packages/core/src/Markdown/XDSMarkdown.tsx@@ -26,6 +26,7 @@ import {import {XDSCodeBlock, XDSCode} from '../CodeBlock';import {XDSCheckboxList} from '../CheckboxList/XDSCheckboxList';import {XDSCheckboxListItem} from '../CheckboxList/XDSCheckboxListItem';+import {XDSBlockquote} from '../Blockquote/XDSBlockquote';import {XDSList} from '../List/XDSList';import {XDSListItem} from '../List/XDSListItem';import {XDSTable} from '../Table/XDSTable';@@ -338,16 +339,6 @@ const styles = stylex.create({noMarginBlockEnd: {marginBlockEnd: 0,},- // Blockquote- blockquote: {- borderInlineStartWidth: spacingVars['--spacing-0-5'],- borderInlineStartStyle: 'solid',- borderInlineStartColor: colorVars['--color-border-emphasized'],- paddingInlineStart: spacingVars['--spacing-4'],- color: colorVars['--color-text-secondary'],- marginInlineStart: 0,- marginInlineEnd: 0,- },// TablecodeBlockWrapper: {maxWidth: '100%',@@ -1163,20 +1154,19 @@ function renderBlock(return <BlockquoteComp key={index}>{bqC}</BlockquoteComp>;}return (- <blockquote+ <XDSBlockquotekey={index}- {...stylex.props(- styles.blockquote,+ xstyle={[spacing,contentWidthValue != null? dynamicStyles.proseWidth(contentWidthValue)- : null,+ : undefined,contentAlign !== 'start'? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])- : null,+ : undefined,isFirst && styles.noMarginBlockStart,isLast && styles.noMarginBlockEnd,- )}>+ ]}>{node.children.map((c, i) =>renderBlock(c,@@ -1194,7 +1184,7 @@ function renderBlock(components,),)}- </blockquote>+ </XDSBlockquote>);}case 'list': {@@ -1407,7 +1397,16 @@ function renderBlock(node.alignments[i] === 'right' && cellAlignStyles.right,]}>{h.children.map((c, j) =>- renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components),+ renderInline(+ c,+ j,+ onLinkClick,+ cursor,+ citationCtx,+ linkComponent,+ inlinePlugins,+ components,+ ),)}</XDSTableHeaderCell>))}@@ -1425,7 +1424,16 @@ function renderBlock(node.alignments[j] === 'right' && cellAlignStyles.right,]}>{cell.children.map((c, k) =>- renderInline(c, k, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components),+ renderInline(+ c,+ k,+ onLinkClick,+ cursor,+ citationCtx,+ linkComponent,+ inlinePlugins,+ components,+ ),)}</XDSTableCell>));diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 9ee12ca407..45722719fc 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -18,6 +18,7 @@ export * from './AspectRatio';export * from './Avatar';export * from './Badge';export * from './Banner';+export * from './Blockquote';export * from './Breadcrumbs';export * from './Button';export * from './IconButton';