An open source design system that's fully customizable and agent ready
TypeScript
feat(Spinner): add --spinner-arc-fraction public var (#5845)
Ojas Mutrejab75ade05e672
diff --git a/.changeset/spinner-arc-fraction-var.md b/.changeset/spinner-arc-fraction-var.mdnew file mode 100644index 0000000000..8fa7f815a8--- /dev/null+++ b/.changeset/spinner-arc-fraction-var.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Add a `--spinner-arc-fraction` public var to Spinner, so a theme can change how much of the ring the moving arc covers (defaults to 0.375, a 135deg sweep), the same way it already retheme diameter, stroke width, and color.++@HelloOjasMutrejadiff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjsindex a51b3ba1b9..31fea1e704 100644--- a/packages/core/src/Spinner/Spinner.doc.mjs+++ b/packages/core/src/Spinner/Spinner.doc.mjs@@ -48,6 +48,7 @@ export const docs = {{name: '--spinner-stroke-width', description: 'Stroke width of both circles the ring is drawn from: the moving arc and the track behind it. Set it per size alongside the diameter. One stroke width drives both, so 0 is honoured as a zero-width stroke and paints nothing at all rather than falling back to the default; for an arc with no track behind it, set --spinner-track-color to transparent instead.', default: '2px (sm), 3px (md), 3px (lg), 4px (xl)'},{name: '--spinner-color', description: "Color of the moving arc. Defaults to the shade's token, so set it on a shade-variant target to retheme one shade (spinner: { 'shade:subtle': { '--spinner-color': 'var(--color-text-tertiary)' } }), or on the base target to retheme all four. Accepts any color notation, including var(), color-mix() and currentColor.", default: 'var(--color-accent) (default), var(--color-text-secondary) (subtle), var(--color-on-dark) (onMedia), currentColor (inherit)'},{name: '--spinner-track-color', description: 'Color of the track the arc travels on. Set it to `transparent` for an arc with no track. The onMedia and inherit shades draw the track at reduced alpha (30%) so it reads against an arbitrary backdrop; that fade applies to a themed color too.', default: 'var(--color-track) (default, subtle), var(--color-on-dark) (onMedia), currentColor (inherit)'},+ {name: '--spinner-arc-fraction', description: "Fraction of the ring the moving arc covers, as a plain number (not a percentage or angle). Set it on a size-variant target the same way as --spinner-diameter, e.g. spinner: { 'size:xl': { '--spinner-arc-fraction': '0.75' } } for a 270deg sweep. Only takes effect once the stylesheet loads; a render with no CSS (SSR, no-JS) always draws the default 135deg arc.", default: '0.375 (135deg), same for every size'},],},usage: {@@ -106,6 +107,7 @@ export const docsZh = {{name: '--spinner-stroke-width', description: '绘制环的两个圆——移动圆弧与其后的轨道——的描边宽度。与直径一起按尺寸设置。同一个描边宽度同时驱动两者,因此 0 会被采纳为零宽描边——什么都不绘制,而不会回退到默认值;若想要没有轨道的圆弧,请改将 --spinner-track-color 设为 transparent。', default: '2px (sm), 3px (md), 3px (lg), 4px (xl)'},{name: '--spinner-color', description: "运动圆弧的颜色。默认取所在 shade 的令牌,因此可在 shade 变体目标上设置以重新定义单个 shade——spinner: { 'shade:subtle': { '--spinner-color': 'var(--color-text-tertiary)' } }——或在 base 目标上设置以覆盖全部四种。接受任意颜色写法,包括 var()、color-mix() 与 currentColor。", default: 'var(--color-accent)(default)、var(--color-text-secondary)(subtle)、var(--color-on-dark)(onMedia)、currentColor(inherit)'},{name: '--spinner-track-color', description: '圆弧所在轨道的颜色。设为 `transparent` 可得到无轨道的圆弧。onMedia 与 inherit 两种 shade 会以降低的透明度(30%)绘制轨道,以便在任意背景上可辨;该淡化同样作用于主题化的颜色。', default: 'var(--color-track)(default、subtle)、var(--color-on-dark)(onMedia)、currentColor(inherit)'},+ {name: '--spinner-arc-fraction', description: "运动圆弧覆盖圆环的比例,为纯数字(非百分比或角度)。在尺寸变体目标上设置,方式与 --spinner-diameter 相同,例如 spinner: { 'size:xl': { '--spinner-arc-fraction': '0.75' } } 可得到 270 度的圆弧。仅在样式表加载后生效;无 CSS 的渲染(SSR、无 JS)始终绘制默认的 135 度圆弧。", default: '0.375(135 度),各尺寸相同'},],},usage: {diff --git a/packages/core/src/Spinner/Spinner.test.tsx b/packages/core/src/Spinner/Spinner.test.tsxindex e8da0d6662..5dfdfca5b2 100644--- a/packages/core/src/Spinner/Spinner.test.tsx+++ b/packages/core/src/Spinner/Spinner.test.tsx@@ -204,6 +204,14 @@ describe('Spinner', () => {'.astryx-spinner {\n --spinner-color: var(--color-brand);',);});++ it('scopes a themed arc fraction to that size variant (#5819)', () => {+ expect(+ cssFor({spinner: {'size:xl': {'--spinner-arc-fraction': '0.75'}}}),+ ).toContain(+ '.astryx-spinner[data-size="xl"] {\n --spinner-arc-fraction: 0.75;',+ );+ });});});diff --git a/packages/core/src/Spinner/Spinner.tsx b/packages/core/src/Spinner/Spinner.tsxindex 5468a830b3..ecd56f144f 100644--- a/packages/core/src/Spinner/Spinner.tsx+++ b/packages/core/src/Spinner/Spinner.tsx@@ -29,20 +29,17 @@ import {themeProps} from '../utils/themeProps';// =============================================================================/**- * Fraction of the ring the moving arc covers. The canvas ring this replaces- * swept 135deg, not the 270deg its constant's comment claimed.+ * Default fraction of the ring the moving arc covers. The canvas ring this+ * replaces swept 135deg, not the 270deg its constant's comment claimed.+ *+ * Themeable via `--spinner-arc-fraction`, declared alongside the other public+ * vars in `sizeStyles` below. Only the inline `strokeDasharray` attribute+ * (the pre-stylesheet render — see its own comment) still reads this+ * constant directly; the CSS side composes the dash from the live var.*/const ARC_FRACTION = 0.375;-/**- * The dash pattern, per unit of diameter: one arc, then the gap that closes- * the circle. The circumference is `pi x diameter`, so multiplying the- * resolved diameter by these two constants gives exactly the lengths the- * default render has always used, and scales them with a themed diameter.- */const PI = 3.141592653589793;-const ARC_DASH = PI * ARC_FRACTION;-const ARC_GAP = PI * (1 - ARC_FRACTION);const SIZES = {sm: {diameter: 10, border: 2},@@ -322,10 +319,16 @@ const styles = stylex.create({// of the circle — 87.398 against the 87.965 of pi x 28 — which shortens the// default arc by 0.64% and moves the cap by half a pixel. Composing the// lengths keeps the default byte-identical to what it drew before.+ //+ // The fraction itself also rides a public var (`--spinner-arc-fraction`),+ // unregistered like the other three color/geometry public vars — it is+ // read as a bare `<number>` multiplier here, never summed with a unitless+ // `0` the way the registered length pair guards against, so it needs no+ // registration.arc: {stroke: 'var(--spinner-color)',transform: 'rotate(-90deg)',- strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${ARC_DASH}) calc(var(${RESOLVED_DIAMETER}) * ${ARC_GAP})`,+ strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${PI} * var(--spinner-arc-fraction)) calc(var(${RESOLVED_DIAMETER}) * ${PI} * (1 - var(--spinner-arc-fraction)))`,},track: {stroke: 'var(--spinner-track-color)'},});@@ -348,22 +351,30 @@ const styles = stylex.create({// cost of its own — with nothing declaring the var,// `theme-var-reachability.js` cannot find an element to check, so a documented// var reads as unreachable.+// Arc fraction is not itself size-dependent, but it declares alongside the+// two vars that are, on the same per-size condition (`!hasLabel` gate at the+// call site) — it needs a home on whichever element carries the theme+// target, and this is the object already wired to be there.const sizeStyles = stylex.create({sm: {'--spinner-diameter': `${SIZES.sm.diameter}px`,'--spinner-stroke-width': `${SIZES.sm.border}px`,+ '--spinner-arc-fraction': `${ARC_FRACTION}`,},md: {'--spinner-diameter': `${SIZES.md.diameter}px`,'--spinner-stroke-width': `${SIZES.md.border}px`,+ '--spinner-arc-fraction': `${ARC_FRACTION}`,},lg: {'--spinner-diameter': `${SIZES.lg.diameter}px`,'--spinner-stroke-width': `${SIZES.lg.border}px`,+ '--spinner-arc-fraction': `${ARC_FRACTION}`,},xl: {'--spinner-diameter': `${SIZES.xl.diameter}px`,'--spinner-stroke-width': `${SIZES.xl.border}px`,+ '--spinner-arc-fraction': `${ARC_FRACTION}`,},});diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 42f4b5b05d..5ee6cfc69c 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -310,15 +310,17 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([// It is one component of one shadow in the list, so no standard property// maps onto it either — a theme sets it beside the fill it has to contrast.'--selectable-card-ring-color',- // The spinner's ring is drawn as an SVG circle, so none of its four vars is+ // The spinner's ring is drawn as an SVG circle, so none of its five vars is// a CSS property of the element carrying the theme target: `width` and- // `borderWidth` would name a box the ring is not, and a `color` mapping- // would take the label's text color with it. They are public vars a theme- // sets directly under a size- or shade-variant key.+ // `borderWidth` would name a box the ring is not, a `color` mapping would+ // take the label's text color with it, and the arc fraction is a pure+ // dash-length multiplier with no standard property to attach to. They are+ // public vars a theme sets directly under a size- or shade-variant key.'--spinner-diameter','--spinner-stroke-width','--spinner-color','--spinner-track-color',+ '--spinner-arc-fraction',]);// ---------------------------------------------------------------------------