An open source design system that's fully customizable and agent ready
TypeScript
feat(markdown): expose per-block spacing to theming via astryx-markdown-* targets (#4669)
freddymeta3d4860ab9a67
diff --git a/.changeset/markdown-block-spacing-theme-targets.md b/.changeset/markdown-block-spacing-theme-targets.mdnew file mode 100644index 0000000000..125a529f20--- /dev/null+++ b/.changeset/markdown-block-spacing-theme-targets.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Markdown: expose per-block spacing to theming. Every block type now renders a stable theme target — `astryx-markdown-heading`, `-paragraph`, `-list`, `-codeblock`, `-blockquote`, `-table`, `-hr`, and `-image` — so a theme can tune the gap around any block (`marginBlockStart`/`marginBlockEnd`) via `defineTheme` instead of overriding global spacing tokens or reaching for fragile `[role="paragraph"]`-style descendant selectors. Each target reflects `data-density` (so spacing can differ per `default`/`compact`), and the heading target additionally reflects `data-level` (1–6) for per-level spacing. Targets apply only to the default render path — a custom `components.heading`/`code`/`blockquote`/`hr`/`image` continues to own its own styling. Purely additive — default rendering is unchanged.++@freddymetadiff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex 6a3762e80f..52dd698804 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -128,6 +128,38 @@ export const docs = {theming: {targets: [{className: 'astryx-markdown', visualProps: ['density']},+ {+ className: 'astryx-markdown-heading',+ visualProps: ['density', 'level'],+ },+ {+ className: 'astryx-markdown-paragraph',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-list',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-codeblock',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-blockquote',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-table',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-hr',+ visualProps: ['density'],+ },+ {+ className: 'astryx-markdown-image',+ visualProps: ['density'],+ },],},usage: {@@ -292,6 +324,54 @@ export const docsZh = {theming: {targets: [{className: 'astryx-markdown', visualProps: ['density']},+ {+ className: 'astryx-markdown-heading',+ visualProps: ['density', 'level'],+ description:+ '每个渲染的标题块(h1–h6)。覆盖 marginBlockStart/marginBlockEnd 可调整标题周围的间距;反映 data-density 和 data-level,因此主题可按密度和标题层级设置间距。仅适用于默认标题渲染——自定义的 components.heading 拥有自己的样式。',+ },+ {+ className: 'astryx-markdown-paragraph',+ visualProps: ['density'],+ description:+ '每个渲染的段落块。覆盖 marginBlockStart/marginBlockEnd 可调整段落之间的间距。反映 data-density,因此主题可以为不同密度设置不同的间距。',+ },+ {+ className: 'astryx-markdown-list',+ visualProps: ['density'],+ description:+ '每个渲染的列表块(有序、无序和任务列表)。覆盖 marginBlockStart/marginBlockEnd 可调整列表周围的间距;反映 data-density。',+ },+ {+ className: 'astryx-markdown-codeblock',+ visualProps: ['density'],+ description:+ '每个渲染的代码块外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整代码块周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.code 拥有自己的样式。',+ },+ {+ className: 'astryx-markdown-blockquote',+ visualProps: ['density'],+ description:+ '每个渲染的引用块(与 astryx-blockquote 目标共用同一元素)。覆盖 marginBlockStart/marginBlockEnd 可调整引用块周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.blockquote 拥有自己的样式。',+ },+ {+ className: 'astryx-markdown-table',+ visualProps: ['density'],+ description:+ '每个渲染的表格外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整表格周围的间距;反映 data-density。',+ },+ {+ className: 'astryx-markdown-hr',+ visualProps: ['density'],+ description:+ '每个渲染的水平分隔线。覆盖 marginBlockStart/marginBlockEnd 可调整分隔线周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.hr 拥有自己的样式。',+ },+ {+ className: 'astryx-markdown-image',+ visualProps: ['density'],+ description:+ '每个渲染的块级图片外层容器(以及损坏图片的占位符)。覆盖 marginBlockStart/marginBlockEnd 可调整图片周围的间距;反映 data-density。仅适用于默认渲染——自定义的 components.image 拥有自己的样式。',+ },],},usage: {diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsxindex 1720be73bf..1a36daf0c5 100644--- a/packages/core/src/Markdown/Markdown.test.tsx+++ b/packages/core/src/Markdown/Markdown.test.tsx@@ -2,6 +2,7 @@import {describe, it, expect, vi} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';+import type {ReactNode} from 'react';import {Markdown} from './Markdown';import type {MarkdownInlinePlugin} from './Markdown';@@ -34,6 +35,97 @@ describe('Markdown', () => {expect(para).toHaveAttribute('role', 'paragraph');});+ it('renders the astryx-markdown-paragraph theme target on each paragraph', () => {+ render(<Markdown>{'First para\n\nSecond para'}</Markdown>);+ const first = screen.getByText('First para');+ const second = screen.getByText('Second para');+ // Stable theme-target class lets a theme adjust the inter-paragraph gap+ // (marginBlockStart/marginBlockEnd) via defineTheme without reaching for+ // fragile descendant selectors or global spacing tokens.+ expect(first.className).toContain('astryx-markdown-paragraph');+ expect(second.className).toContain('astryx-markdown-paragraph');+ });++ describe('block spacing theme targets', () => {+ // Every block type renders a stable astryx-markdown-<block> class so a+ // theme can tune the gap around it (marginBlockStart/marginBlockEnd) via+ // defineTheme — the whole prose rhythm is themeable, not just paragraphs.+ it('renders a stable theme-target class on every block type', () => {+ const {container} = render(+ <Markdown>+ {[+ '# Heading',+ 'Paragraph text',+ '- item one',+ '```\ncode\n```',+ '> quoted',+ '| a | b |\n| - | - |\n| 1 | 2 |',+ '---',+ '',+ ].join('\n\n')}+ </Markdown>,+ );+ for (const cls of [+ 'astryx-markdown-heading',+ 'astryx-markdown-paragraph',+ 'astryx-markdown-list',+ 'astryx-markdown-codeblock',+ 'astryx-markdown-blockquote',+ 'astryx-markdown-table',+ 'astryx-markdown-hr',+ 'astryx-markdown-image',+ ]) {+ expect(+ container.querySelector(`.${cls}`),+ `expected a .${cls} element`,+ ).not.toBeNull();+ }+ });++ it('renders the theme target on task lists too', () => {+ const {container} = render(<Markdown>{'- [ ] todo'}</Markdown>);+ expect(container.querySelector('.astryx-markdown-list')).not.toBeNull();+ });++ it('reflects density on block targets as data-density', () => {+ const {rerender} = render(<Markdown>{'Hello world'}</Markdown>);+ // Default density is reflected so themes can tune spacing per density.+ expect(screen.getByText('Hello world')).toHaveAttribute(+ 'data-density',+ 'default',+ );+ rerender(<Markdown density="compact">{'Hello world'}</Markdown>);+ expect(screen.getByText('Hello world')).toHaveAttribute(+ 'data-density',+ 'compact',+ );+ });++ it('reflects the heading level on the heading target as data-level', () => {+ render(<Markdown>{'## Section'}</Markdown>);+ const heading = screen.getByText('Section');+ expect(heading.className).toContain('astryx-markdown-heading');+ expect(heading).toHaveAttribute('data-level', '2');+ });++ it('does not apply the theme target when a custom block component is provided', () => {+ const {container} = render(+ <Markdown+ components={{+ heading: ({children}: {children: ReactNode}) => (+ <h2 data-custom>{children}</h2>+ ),+ }}>+ {'# Custom heading'}+ </Markdown>,+ );+ // Custom components own their own styling — the default target is not+ // imposed on them.+ expect(container.querySelector('.astryx-markdown-heading')).toBeNull();+ expect(container.querySelector('[data-custom]')).not.toBeNull();+ });+ });+it('renders inline display without block wrappers', () => {const {container} = render(<Markdown display="inline">{'Use `code` and **bold**'}</Markdown>,diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 0b5b0b99fc..a6f850b7e2 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/src/Markdown/Markdown.tsx@@ -1083,18 +1083,21 @@ function renderBlock(return (<Tagkey={index}- {...stylex.props(- styles.headingBase,- headingStyles[level],- spacing,- contentWidthValue != null- ? dynamicStyles.proseWidth(contentWidthValue)- : null,- contentAlign !== 'start'- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])- : null,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-heading', {density, level}),+ stylex.props(+ styles.headingBase,+ headingStyles[level],+ spacing,+ contentWidthValue != null+ ? dynamicStyles.proseWidth(contentWidthValue)+ : null,+ contentAlign !== 'start'+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])+ : null,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}>{headingChildren}</Tag>@@ -1130,16 +1133,19 @@ function renderBlock(<divkey={index}role="paragraph"- {...stylex.props(- spacing,- contentWidthValue != null- ? dynamicStyles.proseWidth(contentWidthValue)- : null,- contentAlign !== 'start'- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])- : null,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-paragraph', {density}),+ stylex.props(+ spacing,+ contentWidthValue != null+ ? dynamicStyles.proseWidth(contentWidthValue)+ : null,+ contentAlign !== 'start'+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])+ : null,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}>{paraChildren}</div>@@ -1161,11 +1167,14 @@ function renderBlock(return (<divkey={index}- {...stylex.props(- spacing,- styles.codeBlockWrapper,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-codeblock', {density}),+ stylex.props(+ spacing,+ styles.codeBlockWrapper,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}><CodeBlockcode={node.content}@@ -1207,6 +1216,7 @@ function renderBlock(return (<Blockquotekey={index}+ {...themeProps('markdown-blockquote', {density})}xstyle={[spacing,contentWidthValue != null@@ -1254,10 +1264,13 @@ function renderBlock(return (<divkey={index}- {...stylex.props(- spacing,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-list', {density}),+ stylex.props(+ spacing,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}><CheckboxListlabel={t('@astryx.markdown.taskList')}@@ -1327,16 +1340,19 @@ function renderBlock(return (<divkey={index}- {...stylex.props(- spacing,- contentWidthValue != null- ? dynamicStyles.proseWidth(contentWidthValue)- : null,- contentAlign !== 'start'- ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])- : null,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-list', {density}),+ stylex.props(+ spacing,+ contentWidthValue != null+ ? dynamicStyles.proseWidth(contentWidthValue)+ : null,+ contentAlign !== 'start'+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])+ : null,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}><ListlistStyle={node.ordered ? 'decimal' : 'disc'}@@ -1414,17 +1430,20 @@ function renderBlock(tabIndex={0}role="group"aria-label={t('@astryx.markdown.table')}- {...stylex.props(- styles.tableWrapper,- spacing,- contentWidthValue != null- ? dynamicStyles.blockWidth(contentWidthValue)- : null,- BLOCK_ALIGN_MARGIN[contentAlign] != null- ? dynamicStyles.blockAlign(BLOCK_ALIGN_MARGIN[contentAlign])- : null,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-table', {density}),+ stylex.props(+ styles.tableWrapper,+ spacing,+ contentWidthValue != null+ ? dynamicStyles.blockWidth(contentWidthValue)+ : null,+ BLOCK_ALIGN_MARGIN[contentAlign] != null+ ? dynamicStyles.blockAlign(BLOCK_ALIGN_MARGIN[contentAlign])+ : null,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}><Table dividers="rows" textOverflow="wrap"><TableHeader>@@ -1499,11 +1518,14 @@ function renderBlock(return (<hrkey={index}- {...stylex.props(- styles.hr,- spacing,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-hr', {density}),+ stylex.props(+ styles.hr,+ spacing,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}/>);@@ -1514,10 +1536,13 @@ function renderBlock(return (<divkey={index}- {...stylex.props(- spacing,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-image', {density}),+ stylex.props(+ spacing,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}>[{node.alt}]</div>@@ -1530,10 +1555,13 @@ function renderBlock(return (<divkey={index}- {...stylex.props(- spacing,- isFirst && styles.noMarginBlockStart,- isLast && styles.noMarginBlockEnd,+ {...mergeProps(+ themeProps('markdown-image', {density}),+ stylex.props(+ spacing,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ ),)}><img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} /></div>