@astryxdesign/core 0.1.2 → 0.1.3

package/src/Slider/Slider.doc.mjs

@@ -95,6 +95,12 @@ export const docs = {
       description: 'Whether the slider is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -151,6 +157,7 @@ export const docs = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -237,6 +244,12 @@ export const docsZh = {
       description: '是否禁用滑块。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -293,6 +306,7 @@ export const docsZh = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -307,6 +321,7 @@ export const docsDense = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {

package/src/Slider/Slider.test.tsx

@@ -9,11 +9,44 @@
  * SYNC: When Slider.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, act, fireEvent} from '@testing-library/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 {Slider} from './Slider';
 
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    // jsdom does not derive :focus-visible from keyboard focus for a
+    // div[role="slider"] thumb; treat the focused thumb as focus-visible so the
+    // disabled-reason tooltip's keyboard-focus path can be exercised.
+    if (selector === ':focus-visible') {
+      return this === document.activeElement;
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
 describe('Slider', () => {
   // --- Aria labels ---
 
@@ -382,4 +415,124 @@ describe('Slider', () => {
     await user.keyboard('{ArrowLeft}');
     expect(handleChange).toHaveBeenCalledWith(0);
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function getTrack(): HTMLElement {
+      return screen.getByRole('slider').parentElement!;
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          isDisabled
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'Volume is locked while sharing your screen',
+      );
+      fireEvent.mouseEnter(getTrack());
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(getTrack());
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          isDisabled
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('slider')).toHaveFocus();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <Slider label="Volume" value={50} valueDisplay="none" isDisabled />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the thumb focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          isDisabled
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      const thumb = screen.getByRole('slider');
+      expect(thumb).toHaveAttribute('aria-disabled', 'true');
+      expect(thumb).toHaveAttribute('tabindex', '0');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          isDisabled
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      const thumb = screen.getByRole('slider');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(thumb.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks value changes while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Slider
+          label="Volume"
+          value={50}
+          valueDisplay="none"
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Volume is locked while sharing your screen"
+        />,
+      );
+      const thumb = screen.getByRole('slider');
+      thumb.focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains non-focusable when disabled without a reason', () => {
+      render(
+        <Slider label="Volume" value={50} valueDisplay="none" isDisabled />,
+      );
+      expect(screen.getByRole('slider')).toHaveAttribute('tabindex', '-1');
+    });
+  });
 });

package/src/Slider/Slider.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Slider.tsx
- * @input Uses React, useId, useRef, useCallback, Field, Tooltip
+ * @input Uses React, useId, useRef, useCallback, Field, Tooltip, useTooltip
  * @output Exports Slider component, SliderProps, SliderSingleProps, SliderRangeProps, SliderBaseProps
  * @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
  *
@@ -37,6 +37,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import {Tooltip} from '../Tooltip/Tooltip';
+import {useTooltip} from '../Tooltip';
 import type {InputStatus} from '../Field/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -61,6 +62,27 @@ export interface SliderBaseProps extends Omit<
   description?: string;
   /** Whether the slider is disabled. @default false */
   isDisabled?: boolean;
+  /**
+   * Explains why the slider is disabled. When set together with `isDisabled`,
+   * the slider shows a tooltip with this text on hover and keyboard focus, and
+   * the thumb stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Value changes stay
+   * blocked.
+   *
+   * Use this instead of wrapping a disabled slider in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <Slider
+   *   label="Volume"
+   *   value={50}
+   *   isDisabled
+   *   disabledMessage="Volume is locked while sharing your screen"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /** Whether the field is optional. @default false */
   isOptional?: boolean;
   /** Whether the field is required. @default false */
@@ -331,6 +353,7 @@ export function Slider({ref, ...props}: SliderProps) {
     isLabelHidden = false,
     description,
     isDisabled = false,
+    disabledMessage,
     isOptional = false,
     isRequired = false,
     status,
@@ -368,6 +391,20 @@ export function Slider({ref, ...props}: SliderProps) {
   const draggingThumbRef = useRef<number | null>(null);
   const [draggingThumb, setDraggingThumb] = useState<number | null>(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
+  // controls swallow pointer events, so the thumb stays perceivable via
+  // aria-disabled while pointer/keyboard handlers early-return on isDisabled.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The track container is not naturally focusable; focusin bubbles up from
+    // the thumb, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Build aria-describedby
   const describedByParts: string[] = [];
   if (description) {
@@ -376,6 +413,9 @@ export function Slider({ref, ...props}: SliderProps) {
   if (status?.message) {
     describedByParts.push(statusMessageID);
   }
+  if (showsDisabledMessage) {
+    describedByParts.push(disabledMessageTooltip.describedBy);
+  }
   const ariaDescribedBy =
     describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
 
@@ -641,7 +681,10 @@ export function Slider({ref, ...props}: SliderProps) {
         : `${label}, maximum value`
       : label;
 
-    const useTooltip = valueDisplay === 'tooltip';
+    // Suppress the per-thumb value bubble while the disabled-message tooltip is
+    // showing, so a disabled slider surfaces the *reason* on hover/focus rather
+    // than stacking two tooltips over the same thumb.
+    const useValueTooltip = valueDisplay === 'tooltip' && !showsDisabledMessage;
     const tooltipPlacement = isHorizontal ? 'above' : 'start';
 
     const thumbElement = (
@@ -649,7 +692,10 @@ export function Slider({ref, ...props}: SliderProps) {
         key={thumbIndex}
         id={!isRange ? id : undefined}
         role="slider"
-        tabIndex={isDisabled ? -1 : 0}
+        // With a disabledMessage the thumb keeps focusability so the reason is
+        // focus-discoverable; value changes stay blocked by the isDisabled
+        // guards in the pointer/keyboard handlers.
+        tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
         aria-valuemin={min}
         aria-valuemax={max}
         aria-valuenow={val}
@@ -678,7 +724,7 @@ export function Slider({ref, ...props}: SliderProps) {
       />
     );
 
-    if (useTooltip) {
+    if (useValueTooltip) {
       return (
         <Tooltip
           key={thumbIndex}
@@ -758,7 +804,7 @@ export function Slider({ref, ...props}: SliderProps) {
           stylex.props(styles.sliderRow),
         )}>
         <div
-          ref={mergeRefs(ref, trackRef)}
+          ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
           {...(isRange ? {role: 'group', 'aria-label': label} : undefined)}
           onPointerDown={handlePointerDown}
           onPointerMove={handlePointerMove}
@@ -855,6 +901,8 @@ export function Slider({ref, ...props}: SliderProps) {
 
         {textDisplay}
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Spinner/Spinner.tsx

@@ -70,7 +70,13 @@ const styles = stylex.create({
   canvas: {
     backfaceVisibility: 'hidden',
     display: 'block',
-    animationDuration: durationVars['--duration-slow-min'],
+    // Slow the rotation dramatically under reduced-motion rather than freezing
+    // it (a frozen spinner reads as broken), matching ProgressBar's approach.
+    // The role="status" + "Loading" label still convey busy state (obs-6).
+    animationDuration: {
+      default: durationVars['--duration-slow-min'],
+      '@media (prefers-reduced-motion: reduce)': '3s',
+    },
     animationIterationCount: 'infinite',
     animationName: rotation,
     animationTimingFunction: 'linear',

package/src/Stack/Stack.doc.mjs

@@ -28,6 +28,31 @@ export const docs = {
           description:
             'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
         },
+        {
+          name: 'padding',
+          type: 'SpacingStep',
+          description:
+            'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
+        },
+        {
+          name: 'paddingInline',
+          type: 'SpacingStep',
+          description:
+            'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
+        },
+        {
+          name: 'paddingBlock',
+          type: 'SpacingStep',
+          description:
+            'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
+        },
+        {
+          name: 'isScrollable',
+          type: 'boolean',
+          description:
+            'Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel.',
+          default: 'false',
+        },
         {
           name: 'width',
           type: 'SizeValue',
@@ -38,6 +63,16 @@ export const docs = {
           type: 'SizeValue',
           description: "Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
         },
+        {
+          name: 'maxWidth',
+          type: 'SizeValue',
+          description: "Maximum width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
+        {
+          name: 'minHeight',
+          type: 'SizeValue',
+          description: "Minimum height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
         {
           name: 'hAlign',
           type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
@@ -96,6 +131,31 @@ export const docs = {
           description:
             'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
         },
+        {
+          name: 'padding',
+          type: 'SpacingStep',
+          description:
+            'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
+        },
+        {
+          name: 'paddingInline',
+          type: 'SpacingStep',
+          description:
+            'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
+        },
+        {
+          name: 'paddingBlock',
+          type: 'SpacingStep',
+          description:
+            'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
+        },
+        {
+          name: 'isScrollable',
+          type: 'boolean',
+          description:
+            'Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel.',
+          default: 'false',
+        },
         {
           name: 'width',
           type: 'SizeValue',
@@ -106,6 +166,16 @@ export const docs = {
           type: 'SizeValue',
           description: "Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
         },
+        {
+          name: 'maxWidth',
+          type: 'SizeValue',
+          description: "Maximum width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
+        {
+          name: 'minHeight',
+          type: 'SizeValue',
+          description: "Minimum height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
         {
           name: 'hAlign',
           type: "'start' | 'center' | 'end' | 'stretch'",
@@ -160,6 +230,13 @@ export const docs = {
             'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',
           default: "'static'",
         },
+        {
+          name: 'isScrollable',
+          type: 'boolean',
+          description:
+            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel.',
+          default: 'false',
+        },
         {
           name: 'crossAlignSelf',
           type: "'start' | 'center' | 'end' | 'stretch'",

package/src/Stack/Stack.test.tsx

@@ -253,15 +253,65 @@ describe('Stack', () => {
 
   it('applies both width and height together', () => {
     render(
-      <Stack
-        direction="vertical"
-        width={400}
-        height="100%"
-        data-testid="stack">
+      <Stack direction="vertical" width={400} height="100%" data-testid="stack">
         <div>Item</div>
       </Stack>,
     );
     const el = screen.getByTestId('stack');
     expect(el).toHaveStyle({width: '400px', height: '100%'});
   });
+
+  it('applies a class when padding is set', () => {
+    render(
+      <Stack padding={3} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('accepts paddingInline and paddingBlock without error', () => {
+    render(
+      <Stack paddingInline={4} paddingBlock={2} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toBeInTheDocument();
+  });
+
+  it('lets paddingInline/paddingBlock override padding on their axis', () => {
+    // padding sets both axes; paddingInline overrides the inline axis. The
+    // component should render without conflict and carry a class.
+    render(
+      <Stack padding={2} paddingInline={5} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('applies a class when isScrollable is set', () => {
+    render(
+      <Stack isScrollable data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('does not set overflow class when isScrollable is false', () => {
+    const {rerender} = render(
+      <Stack data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    const withoutScroll = screen.getByTestId('stack').className;
+    rerender(
+      <Stack isScrollable data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    const withScroll = screen.getByTestId('stack').className;
+    expect(withScroll).not.toBe(withoutScroll);
+  });
 });