An open source design system that's fully customizable and agent ready
TypeScript
feat(theme): sub-element xdsClassName targets + state classes (#763)
Cindy Zhanged45101b073d
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjsindex 9d8cf8f7ba..b7d19a627c 100644--- a/packages/cli/src/lib/component-format.mjs+++ b/packages/cli/src/lib/component-format.mjs@@ -66,7 +66,51 @@ export function formatFull(docs) {if (docs.theming) {sections.push('## Theming\n');- sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);+ const componentKey = docs.name.toLowerCase();++ // Targets table+ if (docs.theming.targets?.length) {+ const targetLines = [];+ targetLines.push('| Class | Variants | States |');+ targetLines.push('|-------|---------|--------|');+ for (const t of docs.theming.targets) {+ const variants = t.visualProps?.length ? t.visualProps.join(', ') : '—';+ const states = t.states?.length ? t.states.join(', ') : '—';+ targetLines.push(`| \`${t.className}\` | ${variants} | ${states} |`);+ }+ sections.push(targetLines.join('\n') + '\n');++ // Generate defineTheme example with class targeting+ const exampleLines = ['Override in defineTheme:\n```ts\ncomponents: {'];+ const rootTarget = docs.theming.targets[0];+ const rootKey = rootTarget.className.replace('xds-', '');+ exampleLines.push(` '${rootKey}': {`);+ exampleLines.push(` base: { /* CSS properties */ },`);+ if (rootTarget.visualProps?.length) {+ const firstVariant = rootTarget.visualProps[0];+ exampleLines.push(` '${firstVariant}:value': { /* variant-specific */ },`);+ }+ if (rootTarget.states?.length) {+ const firstState = rootTarget.states[0];+ exampleLines.push(` '${firstState}': { /* state-specific */ },`);+ }+ exampleLines.push(` },`);+ // Show sub-element example if there are multiple targets+ if (docs.theming.targets.length > 1) {+ const subTarget = docs.theming.targets[1];+ const subKey = subTarget.className.replace('xds-', '');+ exampleLines.push(` '${subKey}': {`);+ exampleLines.push(` base: { /* CSS properties */ },`);+ if (subTarget.states?.length) {+ const firstState = subTarget.states[0];+ exampleLines.push(` '${firstState}': { /* state-specific */ },`);+ }+ exampleLines.push(` },`);+ }+ exampleLines.push('}\n```\n');+ sections.push(exampleLines.join('\n'));+ }+if (docs.theming.surfaces?.length) {const surfaceLines = [];surfaceLines.push('| Surface | Description |');@@ -89,12 +133,11 @@ export function formatFull(docs) {}sections.push(varLines.join('\n') + '\n');- // Show override example+ // Show var override exampleconst overridableVars = docs.theming.vars.filter(v => !v.derived);if (overridableVars.length > 0) {- const componentKey = docs.name.toLowerCase();const exampleVar = overridableVars[0];- sections.push('Override in defineTheme:\n```tsx\ncomponents: {\n ' + componentKey + ': {\n base: { \'' + exampleVar.name + '\': \'...\' },\n },\n}\n```\n');+ sections.push('Override CSS vars in defineTheme:\n```ts\ncomponents: {\n ' + componentKey + ': {\n base: { \'' + exampleVar.name + '\': \'...\' },\n },\n}\n```\n');}}}@@ -257,6 +300,17 @@ export function formatBrief(docs, componentName, importHint) {}}+ // Theme targets (class names, variants, states)+ if (docs.theming?.targets?.length) {+ const targetParts = docs.theming.targets.map(t => {+ const parts = [t.className];+ if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);+ if (t.states?.length) parts.push(`states: ${t.states.join(', ')}`);+ return parts.join(' ');+ });+ output.push(` Targets: ${targetParts.join(' | ')}`);+ }+// Other propsif (otherProps.length > 0) {output.push(` ${otherProps.join(' · ')}`);diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex fa222295b3..f1f03b5d5b 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -118,6 +118,7 @@ export const docs = {theming: {targets: [{className: 'xds-banner', visualProps: ['variant']},+ {className: 'xds-banner-icon', visualProps: ['status']},],vars: [{name: '--banner-radius', description: 'Border radius (card variant only)', default: 'var(--radius-3)'},@@ -247,6 +248,7 @@ export const docsZh = {theming: {targets: [{className: 'xds-banner', visualProps: ['variant']},+ {className: 'xds-banner-icon', visualProps: ['status']},],vars: [{name: '--banner-radius', description: 'Border radius (card variant only)', default: 'var(--radius-3)'},diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex c59d68f9c9..8e5219c840 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -423,7 +423,12 @@ export function XDSBanner({isSingleLine && styles.headerCentered,statusStyles[status],)}>- <div {...stylex.props(styles.iconWrapper)} aria-hidden="true">+ <div+ {...mergeProps(+ xdsClassName('banner-icon', {status}),+ stylex.props(styles.iconWrapper),+ )}+ aria-hidden="true">{icon != null ? (icon) : (diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjsindex 67f0156aba..0962d92b2a 100644--- a/packages/core/src/Calendar/Calendar.doc.mjs+++ b/packages/core/src/Calendar/Calendar.doc.mjs@@ -119,6 +119,7 @@ export const docs = {theming: {targets: [{className: 'xds-calendar', visualProps: ['mode']},+ {className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},],},notes: [@@ -248,6 +249,7 @@ export const docsZh = {theming: {targets: [{className: 'xds-calendar', visualProps: ['mode']},+ {className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},],},notes: [diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsxindex 9370ddce18..5a3e026e4f 100644--- a/packages/core/src/Calendar/XDSCalendar.tsx+++ b/packages/core/src/Calendar/XDSCalendar.tsx@@ -812,21 +812,33 @@ function DayCell({onClick={() => !isDisabled && onDayClick(date)}onMouseEnter={() => !isDisabled && onDayHover(date)}onMouseLeave={() => onDayHover(null)}- {...stylex.props(- dayCellStyles.day,- dayCellTheme.day,- isOutside && dayCellStyles.dayOutside,- isOutside && dayCellTheme.dayOutside,- isToday && !isSelected && !isInRange && dayCellStyles.dayToday,- isToday && !isSelected && !isInRange && dayCellTheme.dayToday,- isToday && !isSelected && isInRange && dayCellStyles.dayTodayInRange,- isToday && !isSelected && isInRange && dayCellTheme.dayTodayInRange,- (isSelected || isRangeStart || isRangeEnd) &&- dayCellStyles.daySelected,- (isSelected || isRangeStart || isRangeEnd) &&- dayCellTheme.daySelected,- isDisabled && dayCellStyles.dayDisabled,- isDisabled && dayCellTheme.dayDisabled,+ {...mergeProps(+ xdsClassName('calendar-day', {+ selected:+ isSelected || isRangeStart || isRangeEnd ? 'selected' : null,+ today: isToday ? 'today' : null,+ disabled: isDisabled ? 'disabled' : null,+ 'in-range': isInRange ? 'in-range' : null,+ }),+ stylex.props(+ dayCellStyles.day,+ dayCellTheme.day,+ isOutside && dayCellStyles.dayOutside,+ isOutside && dayCellTheme.dayOutside,+ isToday && !isSelected && !isInRange && dayCellStyles.dayToday,+ isToday && !isSelected && !isInRange && dayCellTheme.dayToday,+ isToday &&+ !isSelected &&+ isInRange &&+ dayCellStyles.dayTodayInRange,+ isToday && !isSelected && isInRange && dayCellTheme.dayTodayInRange,+ (isSelected || isRangeStart || isRangeEnd) &&+ dayCellStyles.daySelected,+ (isSelected || isRangeStart || isRangeEnd) &&+ dayCellTheme.daySelected,+ isDisabled && dayCellStyles.dayDisabled,+ isDisabled && dayCellTheme.dayDisabled,+ ),)}>{dayNumber}</button>diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex 75897cd22f..7f6fb327d4 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -188,7 +188,7 @@ export const docs = {theming: {targets: [{className: 'xds-checkbox-input', visualProps: ['size']},- {className: 'xds-checkbox'},+ {className: 'xds-checkbox', states: ['checked', 'disabled']},],},notes: [@@ -384,7 +384,7 @@ export const docsZh = {theming: {targets: [{className: 'xds-checkbox-input', visualProps: ['size']},- {className: 'xds-checkbox'},+ {className: 'xds-checkbox', states: ['checked', 'disabled']},],},notes: [diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex 24a1d01aca..7bb21b92c6 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -383,7 +383,10 @@ export function XDSCheckboxInput({<divaria-hidden="true"{...mergeProps(- xdsClassName('checkbox'),+ xdsClassName('checkbox', {+ checked: isCheckedOrIndeterminate ? 'checked' : null,+ disabled: isDisabled ? 'disabled' : null,+ }),stylex.props(styles.checkbox,checkboxSizeStyles[size],@@ -431,8 +434,7 @@ export function XDSCheckboxInput({)}</div></div>- <div- {...stylex.props(styles.labelWrapper)}>+ <div {...stylex.props(styles.labelWrapper)}><XDSFieldLabellabel={label}inputID={id}diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex 2495f3e8e5..923732c3ac 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -111,6 +111,7 @@ export const docs = {theming: {targets: [{className: 'xds-progressbar', visualProps: ['size', 'variant']},+ {className: 'xds-progressbar-fill', visualProps: ['variant']},],},accessibility: [@@ -234,6 +235,7 @@ export const docsZh = {theming: {targets: [{className: 'xds-progressbar', visualProps: ['size', 'variant']},+ {className: 'xds-progressbar-fill', visualProps: ['variant']},],},accessibility: [diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsxindex 3b36fa7ed6..b892029288 100644--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx@@ -336,11 +336,17 @@ export function XDSProgressBar({{...stylex.props(styles.track, sizeStyles[size])}>{isIndeterminate ? (<div- {...stylex.props(styles.indeterminateFill, variantStyles[variant])}+ {...mergeProps(+ xdsClassName('progressbar-fill', {variant}),+ stylex.props(styles.indeterminateFill, variantStyles[variant]),+ )}/>) : (<div- {...stylex.props(styles.fill, variantStyles[variant])}+ {...mergeProps(+ xdsClassName('progressbar-fill', {variant}),+ stylex.props(styles.fill, variantStyles[variant]),+ )}style={{width: `${percentage}%`}}/>)}diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex 6807397afd..4ea22ca511 100644--- a/packages/core/src/RadioList/RadioList.doc.mjs+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -88,6 +88,8 @@ export const docs = {targets: [{className: 'xds-radio-list', visualProps: ['orientation', 'size']},{className: 'xds-radio-list-item'},+ {className: 'xds-radio', visualProps: ['size'], states: ['checked', 'disabled']},+ {className: 'xds-radio-dot', visualProps: ['size']},],},notes: [@@ -340,6 +342,8 @@ export const docsZh = {targets: [{className: 'xds-radio-list', visualProps: ['orientation', 'size']},{className: 'xds-radio-list-item'},+ {className: 'xds-radio', visualProps: ['size'], states: ['checked', 'disabled']},+ {className: 'xds-radio-dot', visualProps: ['size']},],},notes: [diff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsxindex 2aa69b32d7..8fb652689c 100644--- a/packages/core/src/RadioList/XDSRadioListItem.tsx+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx@@ -290,15 +290,27 @@ export function XDSRadioListItem({/><divaria-hidden="true"- {...stylex.props(- styles.radio,- radioSizeStyles[size],- isChecked ? styles.radioChecked : styles.radioUnchecked,- isDisabled && styles.radioDisabled,- isDisabled && !isChecked && styles.radioDisabledUnchecked,+ {...mergeProps(+ xdsClassName('radio', {+ size,+ checked: isChecked ? 'checked' : null,+ disabled: isDisabled ? 'disabled' : null,+ }),+ stylex.props(+ styles.radio,+ radioSizeStyles[size],+ isChecked ? styles.radioChecked : styles.radioUnchecked,+ isDisabled && styles.radioDisabled,+ isDisabled && !isChecked && styles.radioDisabledUnchecked,+ ),)}>{isChecked && (- <div {...stylex.props(styles.innerDot, dotSizeStyles[size])} />+ <div+ {...mergeProps(+ xdsClassName('radio-dot', {size}),+ stylex.props(styles.innerDot, dotSizeStyles[size]),+ )}+ />)}</div></div>diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjsindex 34bca4e618..f6b13f2e80 100644--- a/packages/core/src/Slider/Slider.doc.mjs+++ b/packages/core/src/Slider/Slider.doc.mjs@@ -221,6 +221,13 @@ export const docs = {'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-slider', visualProps: ['orientation']},+ {className: 'xds-slider-track', visualProps: ['orientation']},+ {className: 'xds-slider-thumb', visualProps: ['orientation']},+ ],+ },accessibility: ['Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.','The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',@@ -460,6 +467,13 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],+ theming: {+ targets: [+ {className: 'xds-slider', visualProps: ['orientation']},+ {className: 'xds-slider-track', visualProps: ['orientation']},+ {className: 'xds-slider-thumb', visualProps: ['orientation']},+ ],+ },accessibility: ['每个滑块使用 `role="slider"`,配合 `aria-valuenow`、`aria-valuemin`、`aria-valuemax` 和 `aria-valuetext`。','即使 `isLabelHidden` 为 true,标签也始终在 DOM 中渲染以确保无障碍可访问性。',diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsxindex 1166f2c556..1efced8b1b 100644--- a/packages/core/src/Slider/XDSSlider.tsx+++ b/packages/core/src/Slider/XDSSlider.tsx@@ -34,6 +34,7 @@ import {import {XDSField} from '../Field/XDSField';import {XDSTooltip} from '../Tooltip/XDSTooltip';import type {XDSInputStatus} from '../Field/types';+import {xdsClassName, mergeProps} from '../utils';// =============================================================================// Types@@ -574,12 +575,15 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {aria-describedby={ariaDescribedBy}style={positionStyle}onKeyDown={e => handleKeyDown(thumbIndex, e)}- {...stylex.props(- styles.thumb,- isHorizontal ? styles.thumbHorizontal : styles.thumbVertical,- !isDisabled && styles.thumbHover,- !isDisabled && styles.thumbFocusWithin,- isDisabled && styles.thumbDisabled,+ {...mergeProps(+ xdsClassName('slider-thumb', {orientation}),+ stylex.props(+ styles.thumb,+ isHorizontal ? styles.thumbHorizontal : styles.thumbVertical,+ !isDisabled && styles.thumbHover,+ !isDisabled && styles.thumbFocusWithin,+ isDisabled && styles.thumbDisabled,+ ),)}/>);@@ -652,7 +656,11 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {xstyle={xstyle}className={className}style={style}>- <div {...stylex.props(styles.sliderRow)}>+ <div+ {...mergeProps(+ xdsClassName('slider', {orientation}),+ stylex.props(styles.sliderRow),+ )}><divref={node => {// Merge refs@@ -678,9 +686,12 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {)}>{/* Background track */}<div- {...stylex.props(- styles.track,- isHorizontal ? styles.trackHorizontal : styles.trackVertical,+ {...mergeProps(+ xdsClassName('slider-track', {orientation}),+ stylex.props(+ styles.track,+ isHorizontal ? styles.trackHorizontal : styles.trackVertical,+ ),)}/>diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjsindex 0a07d91814..35c6a16283 100644--- a/packages/core/src/Switch/Switch.doc.mjs+++ b/packages/core/src/Switch/Switch.doc.mjs@@ -188,7 +188,8 @@ export const docs = {],theming: {targets: [- {className: 'xds-switch'},+ {className: 'xds-switch', states: ['checked', 'disabled']},+ {className: 'xds-switch-thumb', states: ['checked']},{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},],},@@ -400,7 +401,8 @@ export const docsZh = {],theming: {targets: [- {className: 'xds-switch'},+ {className: 'xds-switch', states: ['checked', 'disabled']},+ {className: 'xds-switch-thumb', states: ['checked']},{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},],},diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsxindex 27cc4a3744..596cad0a15 100644--- a/packages/core/src/Switch/XDSSwitch.tsx+++ b/packages/core/src/Switch/XDSSwitch.tsx@@ -351,7 +351,10 @@ export function XDSSwitch({<divaria-hidden="true"{...mergeProps(- xdsClassName('switch'),+ xdsClassName('switch', {+ checked: isOn ? 'checked' : null,+ disabled: isDisabled ? 'disabled' : null,+ }),stylex.props(styles.track,isOn ? styles.trackOn : styles.trackOff,@@ -361,9 +364,9 @@ export function XDSSwitch({),)}><div- {...stylex.props(- styles.thumb,- isOn ? styles.thumbOn : styles.thumbOff,+ {...mergeProps(+ xdsClassName('switch-thumb', {checked: isOn ? 'checked' : null}),+ stylex.props(styles.thumb, isOn ? styles.thumbOn : styles.thumbOff),)}>{isBusy && <XDSSpinner size="sm" />}</div>diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex 1b9f9e4df5..da927b9820 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -91,6 +91,12 @@ export interface ThemingTarget {* Themes can target specific variants via `.xds-button.secondary`.* Omit if the component has no visual props (class name only). */visualProps?: string[];+ /** State class names that appear on this element based on component state.+ * Unlike visualProps (driven by props), these reflect runtime state+ * (checked, selected, today, on, expanded, etc.).+ * Themes target them the same way as variants: `.xds-radio.checked { ... }`+ * Omit if the element has no state-driven classes. */+ states?: string[];}/**