@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/Stack/Stack.tsx

@@ -15,7 +15,6 @@
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
-import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   stack,
   type StackCrossAlignment,
@@ -25,9 +24,19 @@ import {
   type SpacingStep,
 } from './stack.stylex';
 import type {SizeValue} from '../utils/types';
+import {
+  paddingInlineStyles,
+  paddingBlockStyles,
+} from '../Layout/padding.stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
+const overflowStyles = stylex.create({
+  scrollable: {
+    overflow: 'auto',
+  },
+});
+
 /**
  * Alignment values accepted by Stack.
  *
@@ -40,7 +49,6 @@ import {themeProps} from '../utils/themeProps';
  */
 export type StackAlignment = StackMainAlignment | StackCrossAlignment;
 
-
 export interface StackProps extends BaseProps<HTMLElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLElement>;
@@ -100,12 +108,55 @@ export interface StackProps extends BaseProps<HTMLElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Spacing between items.
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
    */
   gap?: SpacingStep;
 
+  /**
+   * Inner padding on all sides, using the spacing scale.
+   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+   *
+   * Matches the `padding` prop on `Card`, `LayoutContent`, and `LayoutPanel`.
+   */
+  padding?: SpacingStep;
+
+  /**
+   * Inline (horizontal) padding, using the spacing scale.
+   * Overrides `padding` on the inline axis when both are set.
+   */
+  paddingInline?: SpacingStep;
+
+  /**
+   * Block (vertical) padding, using the spacing scale.
+   * Overrides `padding` on the block axis when both are set.
+   */
+  paddingBlock?: SpacingStep;
+
+  /**
+   * Enables scrollable overflow (`overflow: auto`) for the stack.
+   *
+   * Matches the `isScrollable` prop on `LayoutContent` and `LayoutPanel`.
+   * When the stack is itself a flex child that should scroll, pair it with
+   * a parent `StackItem size="fill" isScrollable` (StackItem applies the
+   * `min-height: 0` reset that flex scroll regions require).
+   * @default false
+   */
+  isScrollable?: boolean;
+
   /**
    * Whether items should wrap.
    * - `nowrap`: Items stay on one line (default)
@@ -121,28 +172,6 @@ export interface StackProps extends BaseProps<HTMLElement> {
    */
   as?: ElementType;
 
-  /**
-   * StyleX styles created via `stylex.create()`. Merged with the component's
-   * base styles inside a single `stylex.props()` call for optimal deduplication.
-   *
-   * @example
-   * ```
-   * const overrides = stylex.create({ root: { marginBottom: 8 } });
-   * <Component xstyle={overrides.root} />
-   * ```
-   */
-  xstyle?: StyleXStyles;
-  /**
-   * CSS class name(s) appended to the root element.
-   * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
-   */
-  className?: string;
-  /**
-   * Inline styles to apply to the root element. Spread after StyleX
-   * inline styles, so these values take priority.
-   */
-  style?: React.CSSProperties;
-
   /**
    * Content to render inside the stack.
    */
@@ -180,8 +209,14 @@ export function Stack({
   justify,
   align,
   gap,
+  padding,
+  paddingInline,
+  paddingBlock,
+  isScrollable,
   width,
   height,
+  maxWidth,
+  minHeight,
   wrap,
   as: element = 'div',
   xstyle,
@@ -207,6 +242,11 @@ export function Stack({
       ? (resolvedVAlign as StackCrossAlignment | undefined)
       : (resolvedHAlign as StackCrossAlignment | undefined);
 
+  // Resolve padding to per-axis values: `padding` sets both axes; `paddingInline`
+  // / `paddingBlock` take precedence on their own axis when provided.
+  const resolvedPaddingInline = paddingInline ?? padding;
+  const resolvedPaddingBlock = paddingBlock ?? padding;
+
   const stylexProps = stylex.props(
     ...stack({
       direction,
@@ -215,6 +255,9 @@ export function Stack({
       gap,
       wrap,
     }),
+    resolvedPaddingInline != null && paddingInlineStyles[resolvedPaddingInline],
+    resolvedPaddingBlock != null && paddingBlockStyles[resolvedPaddingBlock],
+    isScrollable && overflowStyles.scrollable,
     xstyle,
   );
 
@@ -226,6 +269,12 @@ export function Stack({
     ...(height != null && {
       height: typeof height === 'number' ? `${height}px` : height,
     }),
+    ...(maxWidth != null && {
+      maxWidth: typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+    }),
+    ...(minHeight != null && {
+      minHeight: typeof minHeight === 'number' ? `${minHeight}px` : minHeight,
+    }),
   };
 
   return createElement(

package/src/Stack/StackItem.test.tsx

@@ -79,4 +79,27 @@ describe('StackItem', () => {
     const element = screen.getByTestId('stack-item');
     expect(element).toHaveAttribute('aria-label', 'Stack item');
   });
+
+  it('applies an overflow class when isScrollable is set', () => {
+    const {rerender} = render(
+      <StackItem data-testid="stack-item">Content</StackItem>,
+    );
+    const withoutScroll = screen.getByTestId('stack-item').className;
+    rerender(
+      <StackItem isScrollable data-testid="stack-item">
+        Content
+      </StackItem>,
+    );
+    const withScroll = screen.getByTestId('stack-item').className;
+    expect(withScroll).not.toBe(withoutScroll);
+  });
+
+  it('composes isScrollable with size="fill"', () => {
+    render(
+      <StackItem size="fill" isScrollable data-testid="stack-item">
+        Content
+      </StackItem>,
+    );
+    expect(screen.getByTestId('stack-item').className).not.toBe('');
+  });
 });

package/src/Stack/StackItem.tsx

@@ -14,7 +14,6 @@
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
-import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   stackItem,
   type StackItemCrossAlignSelf,
@@ -23,6 +22,12 @@ import {
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
+const overflowStyles = stylex.create({
+  scrollable: {
+    overflow: 'auto',
+  },
+});
+
 export interface StackItemProps extends BaseProps<HTMLElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLElement>;
@@ -42,32 +47,22 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
   size?: StackItemSize;
 
   /**
-   * The element type to render.
-   * @default 'div'
-   */
-  as?: ElementType;
-
-  /**
-   * StyleX styles created via `stylex.create()`. Merged with the component's
-   * base styles inside a single `stylex.props()` call for optimal deduplication.
+   * Enables scrollable overflow (`overflow: auto`) for the item.
    *
-   * @example
-   * ```
-   * const overrides = stylex.create({ root: { marginBottom: 8 } });
-   * <Component xstyle={overrides.root} />
-   * ```
+   * StackItem already applies the flex `min-height: 0` / `min-width: 0`
+   * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
+   * region — it grows to fill the stack and scrolls its own overflow with
+   * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
+   * and `LayoutPanel`.
+   * @default false
    */
-  xstyle?: StyleXStyles;
-  /**
-   * CSS class name(s) appended to the root element.
-   * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
-   */
-  className?: string;
+  isScrollable?: boolean;
+
   /**
-   * Inline styles to apply to the root element. Spread after StyleX
-   * inline styles, so these values take priority.
+   * The element type to render.
+   * @default 'div'
    */
-  style?: React.CSSProperties;
+  as?: ElementType;
 
   /**
    * Content to render inside the stack item.
@@ -92,6 +87,7 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
 export function StackItem({
   crossAlignSelf,
   size,
+  isScrollable,
   as: element = 'div',
   xstyle,
   className,
@@ -102,6 +98,7 @@ export function StackItem({
 }: StackItemProps) {
   const stylexProps = stylex.props(
     ...stackItem({crossAlignSelf, size}),
+    isScrollable && overflowStyles.scrollable,
     xstyle,
   );
 

package/src/Switch/Switch.doc.mjs

@@ -62,6 +62,12 @@ export const docs = {
       description: 'Whether the switch is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -133,6 +139,7 @@ export const docs = {
       { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
       { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
       { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+      { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -196,6 +203,12 @@ export const docsZh = {
       description: '开关是否被禁用。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -267,6 +280,7 @@ export const docsZh = {
       { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
       { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
       { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+      { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -282,6 +296,7 @@ export const docsDense = {
       { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
       { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
       { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+      { guidance: false, description: 'Wrap a disabled switch 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/Switch/Switch.test.tsx

@@ -9,41 +9,56 @@
  * SYNC: When Switch.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Switch} from './Switch';
 
+// 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');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
 describe('Switch', () => {
   it('renders with label', () => {
     render(
-      <Switch
-        label="Enable notifications"
-        value={false}
-        onChange={() => {}}
-      />,
+      <Switch label="Enable notifications" value={false} onChange={() => {}} />,
     );
     expect(screen.getByLabelText('Enable notifications')).toBeInTheDocument();
   });
 
   it('renders as off by default', () => {
     render(
-      <Switch
-        label="Enable notifications"
-        value={false}
-        onChange={() => {}}
-      />,
+      <Switch label="Enable notifications" value={false} onChange={() => {}} />,
     );
     expect(screen.getByRole('switch')).not.toBeChecked();
   });
 
   it('renders as on when value prop is true', () => {
     render(
-      <Switch
-        label="Enable notifications"
-        value={true}
-        onChange={() => {}}
-      />,
+      <Switch label="Enable notifications" value={true} onChange={() => {}} />,
     );
     expect(screen.getByRole('switch')).toBeChecked();
   });
@@ -184,11 +199,7 @@ describe('Switch', () => {
 
   it('shows label visually by default', () => {
     render(
-      <Switch
-        label="Enable notifications"
-        value={false}
-        onChange={() => {}}
-      />,
+      <Switch label="Enable notifications" value={false} onChange={() => {}} />,
     );
     const label = screen.getByText('Enable notifications');
     expect(label).toBeVisible();
@@ -230,11 +241,7 @@ describe('Switch', () => {
 
   it('has role="switch" for accessibility', () => {
     render(
-      <Switch
-        label="Enable notifications"
-        value={false}
-        onChange={() => {}}
-      />,
+      <Switch label="Enable notifications" value={false} onChange={() => {}} />,
     );
     expect(screen.getByRole('switch')).toBeInTheDocument();
   });
@@ -335,4 +342,132 @@ describe('Switch', () => {
     expect(screen.getByRole('switch')).toBeRequired();
   });
 
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function getRow(): HTMLElement {
+      return screen.getByRole('switch', h).closest('div')!.parentElement!;
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'Notifications are turned off org-wide',
+      );
+      fireEvent.mouseEnter(getRow());
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(getRow());
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('switch', h)).toHaveFocus();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the switch focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      const control = screen.getByRole('switch', h);
+      expect(control).not.toBeDisabled();
+      expect(control).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      const control = screen.getByRole('switch', h);
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(control.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks toggling while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Notifications are turned off org-wide"
+        />,
+      );
+      const control = screen.getByRole('switch', h);
+      await user.click(control);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(control).not.toBeChecked();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('switch')).toBeDisabled();
+    });
+  });
 });