@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/Slider/Slider.test.tsx

@@ -13,7 +13,10 @@ import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
 import {Slider} from './Slider';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
@@ -854,7 +857,7 @@ describe('Slider', () => {
         />,
       );
       const thumb = screen.getByRole('slider');
-      thumb.focus();
+      act(() => thumb.focus());
       await user.keyboard('{ArrowRight}');
       expect(onChange).not.toHaveBeenCalled();
     });
@@ -902,4 +905,106 @@ describe('Slider', () => {
       ]).toEqual([]);
     });
   });
+
+  describe('focus ring modality', () => {
+    beforeEach(() => {
+      __resetInteractionModalityForTest();
+    });
+
+    // The ring is a stylex class, so derive it from the same source the
+    // component applies rather than hardcoding a hash.
+    const RING = stylex
+      .props(focusOutlineStyles.focusVisible)
+      .className!.split(' ');
+    const isRinged = (el: HTMLElement) =>
+      RING.every(c => el.classList.contains(c));
+
+    // The track has no layout in jsdom; pointer maths needs a real rect.
+    const grabTrack = (thumb: HTMLElement) => {
+      const track = thumb.parentElement!;
+      track.getBoundingClientRect = () => ({
+        left: 0,
+        top: 0,
+        right: 200,
+        bottom: 20,
+        width: 200,
+        height: 20,
+        x: 0,
+        y: 0,
+        toJSON: () => {},
+      });
+      fireEvent.pointerDown(track, {clientX: 100, clientY: 10, pointerId: 1});
+    };
+
+    it('rings when the thumb is reached with the keyboard', async () => {
+      const user = userEvent.setup();
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      await user.tab();
+      expect(isRinged(screen.getByRole('slider'))).toBe(true);
+    });
+
+    it('does not ring when the thumb is grabbed with the mouse', () => {
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      const thumb = screen.getByRole('slider');
+      grabTrack(thumb);
+      expect(thumb).toHaveFocus();
+      expect(isRinged(thumb)).toBe(false);
+    });
+
+    it('drops the ring when the mouse grabs a thumb that already had it', async () => {
+      const user = userEvent.setup();
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      await user.tab();
+      const thumb = screen.getByRole('slider');
+      expect(isRinged(thumb)).toBe(true);
+      // Already focused, so focus() fires no focus event.
+      grabTrack(thumb);
+      expect(isRinged(thumb)).toBe(false);
+    });
+
+    it('brings the ring back when an arrow key follows a mouse drag', () => {
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      const thumb = screen.getByRole('slider');
+      grabTrack(thumb);
+      expect(isRinged(thumb)).toBe(false);
+      fireEvent.keyDown(thumb, {key: 'ArrowRight'});
+      expect(isRinged(thumb)).toBe(true);
+    });
+
+    it('leaves the ring off for a modifier chord after a mouse drag', () => {
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      const thumb = screen.getByRole('slider');
+      grabTrack(thumb);
+      // Copying or reloading is not navigation, and the mouse is still on it.
+      fireEvent.keyDown(thumb, {key: 'c', metaKey: true});
+      expect(isRinged(thumb)).toBe(false);
+    });
+
+    it('drops the ring on blur', async () => {
+      const user = userEvent.setup();
+      render(<Slider label="Volume" value={50} onChange={vi.fn()} />);
+      await user.tab();
+      const thumb = screen.getByRole('slider');
+      expect(isRinged(thumb)).toBe(true);
+      act(() => thumb.blur());
+      expect(isRinged(thumb)).toBe(false);
+    });
+
+    it('rings the range thumb the keyboard reached, not its sibling', async () => {
+      const user = userEvent.setup();
+      render(
+        <Slider
+          label="Price"
+          value={[20, 80] as [number, number]}
+          onChange={vi.fn()}
+        />,
+      );
+      await user.tab();
+      await user.tab();
+      const thumbs = screen.getAllByRole('slider');
+      expect(thumbs[1]).toHaveFocus();
+      expect(isRinged(thumbs[1])).toBe(true);
+      expect(isRinged(thumbs[0])).toBe(false);
+    });
+  });
 });

package/src/Slider/Slider.tsx

@@ -17,11 +17,13 @@
  */
 
 import {
+  useEffect,
   useId,
   useMemo,
   useRef,
   useState,
   useCallback,
+  type FocusEvent,
   type KeyboardEvent,
   type PointerEvent,
 } from 'react';
@@ -42,6 +44,10 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import type {InputStatus} from '../Field/types';
 import {mergeProps, rtlStyles} from '../utils';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -493,6 +499,36 @@ export function Slider({ref, ...props}: SliderProps) {
   const draggingThumbRef = useRef<number | null>(null);
   const [draggingThumb, setDraggingThumb] = useState<number | null>(null);
 
+  // A thumb is a div[role="slider"], and `handlePointerDown` focuses it from
+  // script after preventDefault — which Chromium treats as focus-visible, so
+  // dragging with a mouse drew the keyboard ring (measured: `:focus-visible`
+  // true on pointerdown). Gate the ring on how the user last interacted; the
+  // CSS condition stays `:focus-visible`, this only narrows it.
+  const [keyboardFocusThumb, setKeyboardFocusThumb] = useState<number | null>(
+    null,
+  );
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const handleThumbFocus = useCallback(
+    (thumbIndex: number, _e: FocusEvent<HTMLDivElement>) => {
+      // A disabled thumb draws no ring even when it stays focusable for its
+      // reason tooltip, so there is nothing to track for one.
+      setKeyboardFocusThumb(
+        !isDisabled && getInteractionModality() === 'keyboard'
+          ? thumbIndex
+          : null,
+      );
+    },
+    [isDisabled],
+  );
+
+  const handleThumbBlur = useCallback((_e: FocusEvent<HTMLDivElement>) => {
+    setKeyboardFocusThumb(null);
+  }, []);
+
   // Disabled-reason tooltip. This is a *separate* useTooltip instance from the
   // per-thumb value bubble (the `<Tooltip>` component below): it anchors to the
   // track container and fires on hover/focus of the whole control. Disabled
@@ -679,6 +715,10 @@ export function Slider({ref, ...props}: SliderProps) {
         const thumbs = track.querySelectorAll<HTMLElement>('[role="slider"]');
         thumbs[thumbIndex]?.focus();
       }
+      // Also clear it explicitly: focusing an already-focused thumb fires no
+      // focus event, so a thumb the user had tabbed to would keep its ring
+      // through the drag.
+      setKeyboardFocusThumb(null);
 
       if (
         typeof (e.currentTarget as HTMLElement).setPointerCapture === 'function'
@@ -717,6 +757,13 @@ export function Slider({ref, ...props}: SliderProps) {
       if (isDisabled) {
         return;
       }
+      // Unlike a text field, a thumb has no caret to show where input is
+      // going, so a keypress after a mouse drag must bring the ring back.
+      // Ask the utility rather than assuming: a modifier chord (⌘R, ⌃C) is
+      // not navigation and must not re-ring a thumb the mouse is holding.
+      if (getInteractionModality() === 'keyboard') {
+        setKeyboardFocusThumb(thumbIndex);
+      }
       const currentVal = values[thumbIndex];
       let newVal: number;
 
@@ -843,6 +890,8 @@ export function Slider({ref, ...props}: SliderProps) {
         aria-labelledby={!isRange ? labelID : undefined}
         aria-describedby={ariaDescribedBy}
         onKeyDown={e => handleKeyDown(thumbIndex, e)}
+        onFocus={e => handleThumbFocus(thumbIndex, e)}
+        onBlur={handleThumbBlur}
         {...mergeProps(
           themeProps('slider-thumb', {
             orientation,
@@ -854,7 +903,9 @@ export function Slider({ref, ...props}: SliderProps) {
               ? styles.thumbHorizontal
               : rtlStyles.centerInline('50%'),
             !isDisabled && styles.thumbHover,
-            !isDisabled && focusOutlineStyles.focusVisible,
+            !isDisabled &&
+              keyboardFocusThumb === thumbIndex &&
+              focusOutlineStyles.focusVisible,
             isDisabled && styles.thumbDisabled,
           ),
           undefined,

package/src/Spinner/Spinner.doc.mjs

@@ -10,8 +10,8 @@ export const docs = {
   props: [
     {
       name: 'size',
-      type: "'sm' | 'md' | 'lg'",
-      description: 'Spinner size (10px, 14px, 18px).',
+      type: "'sm' | 'md' | 'lg' | 'xl'",
+      description: 'Spinner size — ring diameter (10px, 14px, 18px, 28px).',
       default: "'md'",
     },
     {
@@ -43,6 +43,12 @@ export const docs = {
     targets: [
       {className: 'astryx-spinner', visualProps: ['size', 'shade']},
     ],
+    vars: [
+      {name: '--spinner-diameter', description: "Diameter of the drawn ring. Set it on a size-variant target to retheme what each named size resolves to, e.g. spinner: { 'size:xl': { '--spinner-diameter': '2.5rem' } }. The rendered box is this plus the stroke width on each side, and follows automatically. Any length works — rem, em and calc() are resolved before the ring is drawn.", default: '10px (sm), 14px (md), 18px (lg), 28px (xl)'},
+      {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)'},
+    ],
   },
   usage: {
     description:
@@ -63,8 +69,8 @@ export const docsZh = {
   props: [
     {
       name: 'size',
-      type: "'sm' | 'md' | 'lg'",
-      description: '旋转器尺寸（10px、14px、18px）。',
+      type: "'sm' | 'md' | 'lg' | 'xl'",
+      description: '旋转器尺寸——环直径（10px、14px、18px、28px）。',
       default: "'md'",
     },
     {
@@ -95,6 +101,12 @@ export const docsZh = {
     targets: [
       {className: 'astryx-spinner', visualProps: ['size', 'shade']},
     ],
+    vars: [
+      {name: '--spinner-diameter', description: "绘制环的直径。在尺寸变体目标上设置，以重新定义每个命名尺寸的解析值，例如 spinner: { 'size:xl': { '--spinner-diameter': '2.5rem' } }。渲染盒子的尺寸为该值加上两侧的描边宽度，并自动跟随。支持任意长度单位——rem、em 与 calc() 会在绘制前解析。", default: '10px (sm), 14px (md), 18px (lg), 28px (xl)'},
+      {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）'},
+    ],
   },
   usage: {
     description:
@@ -121,7 +133,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    size: 'Spinner size (10px, 14px, 18px).',
+    size: 'Spinner size — ring diameter (10px, 14px, 18px, 28px).',
     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".',

package/src/Spinner/Spinner.test.tsx

@@ -12,6 +12,8 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Spinner} from './Spinner';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
 
 /** sm/md/lg/xl, as Spinner.tsx defines them. */
 const SIZES = {
@@ -140,6 +142,85 @@ describe('Spinner', () => {
     const spinner = screen.getByTestId('spinner');
     expect(spinner.tagName.toLowerCase()).toBe('span');
   });
+
+  // The box has always been sized by an inline width/height written after the
+  // caller's `style`, so the component's own size wins over a `style={{width}}`
+  // passed in. Making the geometry themeable changed what that value is made
+  // of — a composed var rather than a number — and deliberately not where it is
+  // written: moving the sizing into a rule would have handed a caller's inline
+  // width a precedence over the box it has never had. This pins the precedence
+  // itself, which is the part a consumer could be depending on.
+  describe('box sizing', () => {
+    it.each(Object.entries(SIZES))(
+      'falls back to the %s frame where no stylesheet has declared the var',
+      (size, {diameter, border}) => {
+        render(
+          <Spinner size={size as keyof typeof SIZES} data-testid="spinner" />,
+        );
+        const box = screen.getByTestId('spinner');
+        const expected = `var(--_spinner-box-size, ${diameter + border * 2}px)`;
+        expect(box.style.width).toBe(expected);
+        expect(box.style.height).toBe(expected);
+      },
+    );
+
+    it('keeps its own size over a width the caller passes in style', () => {
+      render(
+        <Spinner
+          size="xl"
+          style={{width: 999, height: 999, opacity: 0.5}}
+          data-testid="spinner"
+        />,
+      );
+      const box = screen.getByTestId('spinner');
+      expect(box.style.width).toBe('var(--_spinner-box-size, 36px)');
+      expect(box.style.height).toBe('var(--_spinner-box-size, 36px)');
+      // Everything else the caller passed still applies — only the two
+      // properties the box owns are taken back.
+      expect(box.style.opacity).toBe('0.5');
+    });
+  });
+
+  // The themed geometry resolves in the cascade — jsdom implements no layout
+  // and no custom-property registration, so no test here can reach what a
+  // theme actually draws; that is verified in a browser and the numbers are in
+  // the PR. What IS a contract a unit test can hold is the routing: a theme
+  // writes an override against the documented key, and it has to come out on
+  // the selector the component reads from.
+  describe('a theme reaches the spinner through its public vars', () => {
+    const cssFor = (
+      components: Parameters<typeof defineTheme>[0]['components'],
+    ) =>
+      generateThemeCSS(defineTheme({name: 'spinner-theming', components}))
+        .component;
+
+    it('scopes a themed size to that size variant', () => {
+      // Asserting the whole rule, not just the declaration: the same var on
+      // the bare `.astryx-spinner` would resize every size at once, which is
+      // the bug a size-variant key exists to avoid.
+      expect(
+        cssFor({spinner: {'size:xl': {'--spinner-diameter': '2.5rem'}}}),
+      ).toContain('.astryx-spinner.xl {\n    --spinner-diameter: 2.5rem;');
+    });
+
+    it('scopes a themed color to that shade variant', () => {
+      expect(
+        cssFor({
+          spinner: {'shade:subtle': {'--spinner-track-color': 'transparent'}},
+        }),
+      ).toContain(
+        '.astryx-spinner.subtle {\n    --spinner-track-color: transparent;',
+      );
+    });
+
+    it('lets the base target set a value for every size and shade', () => {
+      expect(
+        cssFor({spinner: {base: {'--spinner-color': 'var(--color-brand)'}}}),
+      ).toContain(
+        '.astryx-spinner {\n    --spinner-color: var(--color-brand);',
+      );
+    });
+  });
 });
 
 describe('Spinner ring', () => {
@@ -196,6 +277,28 @@ describe('Spinner ring', () => {
     );
   });
 
+  // The authored dash is the size's own absolute pattern, and stays that way:
+  // it is what a render with no stylesheet draws, and it is byte-for-byte the
+  // pattern this component drew before the geometry became themeable. Scaling
+  // with a themed diameter is the rule's job — it composes the same two
+  // lengths out of the resolved diameter — and deliberately not `pathLength`'s,
+  // which rescales against the path length the UA measures on its own
+  // approximation of the circle and shortens the default arc by 0.64%.
+  it.each(Object.entries(SIZES))(
+    'leaves the %s arc its own absolute dash, with no pathLength',
+    (size, {diameter}) => {
+      render(
+        <Spinner size={size as keyof typeof SIZES} data-testid="spinner" />,
+      );
+      const {track, arc} = circles();
+      const [on, off] = dashOf(arc);
+      expect(on + off).toBeCloseTo(Math.PI * diameter, 6);
+      expect(arc.getAttribute('pathLength')).toBeNull();
+      // The track is a full ring, so it needs neither.
+      expect(track.getAttribute('pathLength')).toBeNull();
+    },
+  );
+
   // The whole point of the SVG ring: the colours come off the cascade, so
   // nothing has to resolve them in JS. A read reaching the paint path again
   // fails here.
@@ -268,3 +371,64 @@ describe('Spinner ring', () => {
     }
   });
 });
+
+describe('geometry var registration', () => {
+  /** The shape `registerSpinnerVars` passes; jsdom implements no real one. */
+  type Descriptor = {
+    name: string;
+    syntax: string;
+    inherits: boolean;
+    initialValue: string;
+  };
+  const stubRegisterProperty = (fn: (d: Descriptor) => void) => {
+    (
+      CSS as unknown as {registerProperty: (d: Descriptor) => void}
+    ).registerProperty = fn;
+  };
+
+  afterEach(() => {
+    delete (CSS as unknown as {registerProperty?: unknown}).registerProperty;
+    vi.resetModules();
+  });
+
+  it('registers when the module is imported, not when a spinner mounts', async () => {
+    // Registering an inherited property with an `initial-value` invalidates
+    // style for the whole document. A spinner mounts onto a page that has
+    // already rendered, so paying it there is paying it on the full tree —
+    // measured at 29ms against 12ms on an 11k-element page. At import the page
+    // is whatever has rendered so far, which for a bundle in the head is
+    // nothing. This pins the timing: it fails if the call moves back into a
+    // ref callback, an effect, or the component body.
+    const registerProperty = vi.fn<(d: Descriptor) => void>();
+    stubRegisterProperty(registerProperty);
+
+    vi.resetModules();
+    await import('./Spinner');
+
+    expect(registerProperty.mock.calls.map(([d]) => d.name)).toEqual([
+      '--_spinner-ring-diameter',
+      '--_spinner-ring-stroke',
+    ]);
+    // Both are `<length>` with an initial value, which is what makes a themed
+    // `0` mean `0px` inside the `calc()` rather than poisoning it.
+    for (const [descriptor] of registerProperty.mock.calls) {
+      expect(descriptor.syntax).toBe('<length>');
+      expect(descriptor.inherits).toBe(true);
+      expect(descriptor.initialValue).toBe('0px');
+    }
+  });
+
+  it('survives a second evaluation, and does not need the DOM', async () => {
+    // Two copies of the package on one page, or a fast-refresh re-evaluation:
+    // registerProperty throws on a duplicate rather than replacing, and the
+    // existing registration is this same one.
+    const registerProperty = vi.fn<(d: Descriptor) => void>(() => {
+      throw new Error('InvalidModificationError');
+    });
+    stubRegisterProperty(registerProperty);
+
+    vi.resetModules();
+    await expect(import('./Spinner')).resolves.toBeDefined();
+    expect(registerProperty).toHaveBeenCalledTimes(2);
+  });
+});