Skip to content

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.md
new file mode 100644
index 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.
+
+@HelloOjasMutreja
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index 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.tsx
index 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.tsx
index 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.ts
index 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',
]);
// ---------------------------------------------------------------------------