An open source design system that's fully customizable and agent ready
TypeScript
spinner label props (#988)
Andrey Goder63c0baa2bcbc
diff --git a/apps/storybook/stories/Spinner.stories.tsx b/apps/storybook/stories/Spinner.stories.tsxindex c17f00b57a..945f3f1c60 100644--- a/apps/storybook/stories/Spinner.stories.tsx+++ b/apps/storybook/stories/Spinner.stories.tsx@@ -1,7 +1,7 @@import type {Meta, StoryObj} from '@storybook/react';import {XDSSpinner} from '@xds/core/Spinner';-import {XDSHStack, XDSVStack} from '@xds/core/Layout';import {XDSText} from '@xds/core/Text';+import {XDSHStack, XDSVStack} from '@xds/core/Layout';const meta: Meta<typeof XDSSpinner> = {title: 'Core/XDSSpinner',@@ -58,13 +58,24 @@ export const Shades: Story = {),};-export const InContext: Story = {+export const WithLabel: Story = {render: () => (- <XDSVStack gap={2} hAlign="center">- <XDSSpinner size="lg" />- <XDSText type="body" color="secondary">- Loading...- </XDSText>- </XDSVStack>+ <XDSHStack gap={8} vAlign="start">+ <XDSSpinner size="lg" label="Loading..." />+ <XDSSpinner+ size="lg"+ label={+ <XDSVStack gap={0} hAlign="center">+ <XDSText type="body" weight="bold">+ Fetching data+ </XDSText>+ <XDSText type="supporting" color="secondary">+ This may take a moment+ </XDSText>+ </XDSVStack>+ }+ aria-label="Fetching data"+ />+ </XDSHStack>),};diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjsindex f698438d4c..22e47406ae 100644--- a/packages/core/src/Spinner/Spinner.doc.mjs+++ b/packages/core/src/Spinner/Spinner.doc.mjs@@ -3,12 +3,13 @@export const docs = {name: 'Spinner',description:- 'A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.',+ 'An animated loading indicator with optional visible label.',features: [- 'CSS Border Animation: Lightweight border-based spinner with smooth 360° rotation',+ 'Canvas Animation: Lightweight canvas-based spinner with smooth 360° rotation','Size Variants: Three sizes (sm, md, lg) matching existing inline spinners','Shade Support: Default shade for light backgrounds, onMedia for dark/accent backgrounds',- 'Accessible: role="status" and aria-label="Loading" by default',+ 'Label: Optional visible label (string or ReactNode) displayed below spinner',+ 'Accessible: role="status" with aria-label; defaults to label text or "Loading"',],props: [{@@ -23,6 +24,19 @@ export const docs = {description: 'Color shade for light or dark backgrounds.',default: "'default'",},+ {+ name: 'label',+ type: 'ReactNode',+ description:+ 'Visible content below the spinner. String labels auto-set aria-label.',+ },+ {+ name: 'aria-label',+ type: 'string',+ description:+ 'Accessible name for screen readers. Defaults to label (if string) or "Loading".',+ default: "'Loading'",+ },],examples: [{@@ -30,19 +44,25 @@ export const docs = {code: `<XDSSpinner />`,},{- label: 'Small',- code: `<XDSSpinner size="sm" />`,+ label: 'With label',+ code: `<XDSSpinner label="Loading..." />`,},{- label: 'Large on dark background',- code: `<XDSSpinner size="lg" shade="onMedia" />`,+ label: 'A11y only (no visible text)',+ code: `<XDSSpinner aria-label="Loading data" />`,},{- label: 'Composing with layout and text',- code: `<XDSVStack gap={2} align="center">- <XDSSpinner size="lg" />- <XDSText color="secondary">Loading...</XDSText>-</XDSVStack>`,+ label: 'Rich label with composition',+ code: `<XDSSpinner+ size="lg"+ label={+ <XDSVStack gap={0} hAlign="center">+ <XDSText type="body" weight="bold">Fetching data</XDSText>+ <XDSText type="supporting" color="secondary">This may take a moment</XDSText>+ </XDSVStack>+ }+ aria-label="Fetching data"+/>`,},],theming: {@@ -64,12 +84,13 @@ export const docs = {export const docsZh = {name: 'Spinner',description:- '用于指示加载状态的纯旋转器组件。无布局、无文本——仅有旋转指示器。',+ '带有可选可见标签的动画加载指示器。',features: [- 'CSS 边框动画:基于边框的轻量级旋转器,平滑 360° 旋转',+ 'Canvas 动画:基于 Canvas 的轻量级旋转器,平滑 360° 旋转','尺寸变体:三种尺寸(sm、md、lg),与现有内联旋转器匹配','色调支持:默认色调用于浅色背景,onMedia 用于深色/强调色背景',- '无障碍:默认使用 role="status" 和 aria-label="Loading"',+ '标签:可选可见标签(字符串或 ReactNode),显示在旋转器下方',+ '无障碍:role="status" 与 aria-label;默认为标签文本或 "Loading"',],props: [{@@ -84,6 +105,17 @@ export const docsZh = {description: '浅色或深色背景的颜色色调。',default: "'default'",},+ {+ name: 'label',+ type: 'ReactNode',+ description: '旋转器下方的可见内容。字符串标签自动设置 aria-label。',+ },+ {+ name: 'aria-label',+ type: 'string',+ description: '屏幕阅读器的无障碍名称。默认为 label(如果是字符串)或 "Loading"。',+ default: "'Loading'",+ },],examples: [{@@ -91,19 +123,25 @@ export const docsZh = {code: `<XDSSpinner />`,},{- label: '小尺寸',- code: `<XDSSpinner size="sm" />`,+ label: '带标签',+ code: `<XDSSpinner label="加载中..." />`,},{- label: '深色背景上的大尺寸',- code: `<XDSSpinner size="lg" shade="onMedia" />`,+ label: '仅无障碍(无可见文本)',+ code: `<XDSSpinner aria-label="正在加载数据" />`,},{- label: '与布局和文本组合',- code: `<XDSVStack gap={2} align="center">- <XDSSpinner size="lg" />- <XDSText color="secondary">Loading...</XDSText>-</XDSVStack>`,+ label: '富文本标签',+ code: `<XDSSpinner+ size="lg"+ label={+ <XDSVStack gap={0} hAlign="center">+ <XDSText type="body" weight="bold">正在获取数据</XDSText>+ <XDSText type="supporting" color="secondary">这可能需要一些时间</XDSText>+ </XDSVStack>+ }+ aria-label="正在获取数据"+/>`,},],theming: {@@ -123,23 +161,26 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'Pure spinner for loading state. No layout, no text; just spinning indicator.',+ description: 'Animated loading indicator w/ optional visible label.',features: [- 'CSS border animation: lightweight border-based spinner w/ smooth 360\u00b0 rotation',+ 'Canvas animation: lightweight canvas-based spinner w/ smooth 360\u00b0 rotation','Size variants: sm (10px), md (14px), lg (18px) matching inline spinners','Shade support: default for light bg, onMedia for dark/accent bg',- 'Accessible: role="status" + aria-label="Loading" by default',+ 'Label: optional ReactNode below spinner; string labels auto-set aria-label',+ 'Accessible: role="status" + aria-label; defaults to label text or "Loading"',],notes: [- 'CSS border technique: 3 visible borders + 1 transparent for gap.',+ 'Canvas renders spinner arcs at device pixel ratio.','Animation: rotate(360deg) at 0.75s linear infinite.',- 'Color inherits currentColor, controlled by shade styles w/ theme tokens.',+ 'Color resolved from CSS custom properties via getComputedStyle.','Element is <span> w/ display: inline-block for inline composability.',- 'Intentionally minimal; compose w/ layout + text components for full loading states.',+ 'label + aria-label are independent props; compose, never conflict.','Size ref: sm=10x10px/3px border, md=14x14px/3px border, lg=18x18px/3px border.',],propDescriptions: {size: 'Spinner size (10px, 14px, 18px).',shade: 'Color shade for light or dark backgrounds.',+ label: 'Visible content below spinner. String auto-sets aria-label.',+ 'aria-label': 'A11y name for screen readers. Defaults to label or "Loading".',},};\ No newline at end of filediff --git a/packages/core/src/Spinner/XDSSpinner.test.tsx b/packages/core/src/Spinner/XDSSpinner.test.tsxindex 48123c9105..55664a85a1 100644--- a/packages/core/src/Spinner/XDSSpinner.test.tsx+++ b/packages/core/src/Spinner/XDSSpinner.test.tsx@@ -47,7 +47,7 @@ describe('XDSSpinner', () => {expect(screen.getByRole('status')).toBeInTheDocument();});- it('has aria-label="Loading"', () => {+ it('has aria-label="Loading" by default', () => {render(<XDSSpinner data-testid="spinner" />);expect(screen.getByTestId('spinner')).toHaveAttribute('aria-label',@@ -55,6 +55,51 @@ describe('XDSSpinner', () => {);});+ it('uses string label as aria-label automatically', () => {+ render(<XDSSpinner label="Fetching data" data-testid="spinner" />);+ expect(screen.getByRole('status')).toHaveAttribute(+ 'aria-label',+ 'Fetching data',+ );+ });++ it('uses explicit aria-label over string label', () => {+ render(+ <XDSSpinner+ label="Loading..."+ aria-label="Please wait"+ data-testid="spinner"+ />,+ );+ expect(screen.getByRole('status')).toHaveAttribute(+ 'aria-label',+ 'Please wait',+ );+ });++ it('renders label content below the spinner', () => {+ render(<XDSSpinner label="Loading..." data-testid="spinner" />);+ expect(screen.getByText('Loading...')).toBeInTheDocument();+ });++ it('renders ReactNode label', () => {+ render(+ <XDSSpinner+ label={<span data-testid="custom-label">Custom content</span>}+ aria-label="Loading"+ data-testid="spinner"+ />,+ );+ expect(screen.getByTestId('custom-label')).toBeInTheDocument();+ });++ it('defaults aria-label to "Loading" for ReactNode label without explicit aria-label', () => {+ render(+ <XDSSpinner label={<span>Rich content</span>} data-testid="spinner" />,+ );+ expect(screen.getByRole('status')).toHaveAttribute('aria-label', 'Loading');+ });+it('accepts data-testid', () => {render(<XDSSpinner data-testid="my-spinner" />);expect(screen.getByTestId('my-spinner')).toBeInTheDocument();diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsxindex 59e46116ee..7299229ff0 100644--- a/packages/core/src/Spinner/XDSSpinner.tsx+++ b/packages/core/src/Spinner/XDSSpinner.tsx@@ -13,10 +13,11 @@* - /apps/storybook/stories/Spinner.stories.tsx*/-import {useEffect, useRef} from 'react';+import {useEffect, useRef, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import type {StyleXStyles} from '@stylexjs/stylex';-import {colorVars} from '../theme/tokens.stylex';+import {colorVars, spacingVars} from '../theme/tokens.stylex';+import {XDSText} from '../Text/XDSText';import {xdsClassName, mergeProps} from '../utils';// =============================================================================@@ -49,6 +50,12 @@ const rotation = stylex.keyframes({// =============================================================================const styles = stylex.create({+ wrapper: {+ display: 'inline-flex',+ flexDirection: 'column',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ },spinner: {display: 'inline-block',overflow: 'hidden',@@ -106,6 +113,25 @@ export interface XDSSpinnerProps {* If you're using StyleX, prefer `xstyle` for optimal style deduplication.*/className?: string;+ /**+ * Visible content displayed below the spinner.+ * Accepts a string or ReactNode for rich content.+ *+ * When `label` is a string, it is also used as the accessible name+ * (aria-label) unless `aria-label` is explicitly set.+ *+ * @example+ * ```+ * <XDSSpinner label="Loading..." />+ * <XDSSpinner label={<><strong>Fetching data</strong><br/>This may take a moment</>} aria-label="Fetching data" />+ * ```+ */+ label?: ReactNode;+ /**+ * Accessible label for screen readers.+ * Defaults to `label` when label is a string, otherwise "Loading".+ */+ 'aria-label'?: string;/*** Test ID for the root element.*/@@ -124,13 +150,17 @@ export interface XDSSpinnerProps {* <XDSSpinner />* <XDSSpinner size="sm" />* <XDSSpinner size="lg" shade="onMedia" />+ * <XDSSpinner label="Loading..." />+ * <XDSSpinner aria-label="Loading data" />* ```*/export function XDSSpinner({size = 'md',shade = 'default',+ label,xstyle,className,+ 'aria-label': ariaLabel,'data-testid': testId,ref,}: XDSSpinnerProps) {@@ -190,22 +220,51 @@ export function XDSSpinner({const {border, diameter} = SIZES[size];const frameSize = diameter + border * 2;+ const hasLabel = label != null;- return (+ // Resolve accessible name: explicit aria-label > string label > "Loading"+ const resolvedAriaLabel =+ ariaLabel ?? (typeof label === 'string' ? label : undefined) ?? 'Loading';++ const spinner = (<span- ref={ref}+ ref={hasLabel ? undefined : ref}role="status"- aria-label="Loading"- data-testid={testId}+ aria-label={resolvedAriaLabel}+ data-testid={hasLabel ? undefined : testId}{...mergeProps(- xdsClassName('spinner', {size, shade}),- stylex.props(styles.spinner, xstyle),- className,+ hasLabel ? '' : xdsClassName('spinner', {size, shade}),+ stylex.props(styles.spinner, !hasLabel && xstyle),+ hasLabel ? undefined : className,)}style={{width: frameSize, height: frameSize}}><canvas ref={canvasRef} {...stylex.props(styles.canvas)} /></span>);++ if (!hasLabel) {+ return spinner;+ }++ return (+ <div+ ref={ref as React.Ref<HTMLDivElement>}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('spinner', {size, shade}),+ stylex.props(styles.wrapper, xstyle),+ className,+ )}>+ {spinner}+ {typeof label === 'string' ? (+ <XDSText type="body" weight="bold">+ {label}+ </XDSText>+ ) : (+ label+ )}+ </div>+ );}XDSSpinner.displayName = 'XDSSpinner';