@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/SideNav/SideNav.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     targets: [
       {className: 'astryx-side-nav', visualProps: ['mode']},
       {className: 'astryx-side-nav-heading'},
-      {className: 'astryx-side-nav-item'},
+      {className: 'astryx-side-nav-item', visualProps: ['size'], states: ['selected']},
       {className: 'astryx-side-nav-section'},
     ],
   },
@@ -102,6 +102,12 @@ export const docs = {
       description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
       default: 'false',
     },
+    {
+      name: 'resizable',
+      type: 'boolean | { defaultWidth?: number; minWidth?: number; maxWidth?: number; autoSaveId?: string; onWidthChange?: (width: number) => void }',
+      description: 'Enables a resize handle at the inline-end edge. true for defaults (260px initial, 180-480px range), or a ResizableConfig object (defaultWidth, minWidth, maxWidth, autoSaveId for localStorage persistence, onWidthChange). The handle is hidden while collapsed.',
+      default: 'false',
+    },
     {
       name: 'handleRef',
       type: 'Ref<SideNavImperativeCollapseHandle>',

package/src/SideNav/SideNav.test.tsx

@@ -162,6 +162,61 @@ describe('SideNav', () => {
       screen.getByRole('button', {name: 'Expand sidebar'}),
     ).toBeInTheDocument();
   });
+
+  it('does not render an empty footer container when collapsible.hasButton is false', () => {
+    render(
+      <SideNav data-testid="nav" collapsible={{hasButton: false}}>
+        Content
+      </SideNav>,
+    );
+
+    // The built-in collapse button is opted out (consumers render their own
+    // SideNavCollapseButton in the header), so it must not appear...
+    expect(
+      screen.queryByRole('button', {name: 'Collapse sidebar'}),
+    ).not.toBeInTheDocument();
+
+    // ...and no empty sticky-bottom container should be left behind. With no
+    // footer/footerIcons and no built-in button, the scrollable content region
+    // is the nav's only child.
+    const nav = screen.getByTestId('nav');
+    expect(nav.children).toHaveLength(1);
+  });
+
+  it('fires a consumer onClick on the collapse button in addition to toggling', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    function Example() {
+      const [isCollapsed, setIsCollapsed] = useState(false);
+      const handleRef = useRef<SideNavImperativeCollapseHandle>(null);
+      return (
+        <>
+          <SideNavCollapseButton handleRef={handleRef} onClick={onClick} />
+          <SideNav
+            handleRef={handleRef}
+            collapsible={{
+              isCollapsed,
+              onCollapsedChange: setIsCollapsed,
+              hasButton: false,
+            }}>
+            <SideNavSection title="Main">
+              <SideNavItem label="Dashboard" icon={StubIcon} />
+            </SideNavSection>
+          </SideNav>
+        </>
+      );
+    }
+
+    render(<Example />);
+    await user.click(screen.getByRole('button', {name: 'Collapse sidebar'}));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    // Toggle still ran: the label flipped to "Expand sidebar".
+    expect(
+      screen.getByRole('button', {name: 'Expand sidebar'}),
+    ).toBeInTheDocument();
+  });
 });
 
 // =============================================================================
@@ -734,6 +789,17 @@ describe('SideNavSection', () => {
     const group = screen.getByRole('group');
     expect(group.style.marginTop).toBe('16px');
   });
+
+  it('forwards arbitrary pass-through attributes (id, aria-*) to root element', () => {
+    render(
+      <SideNavSection title="Main" id="section-1" aria-describedby="hint">
+        <SideNavItem label="Dashboard" />
+      </SideNavSection>,
+    );
+    const group = screen.getByRole('group');
+    expect(group).toHaveAttribute('id', 'section-1');
+    expect(group).toHaveAttribute('aria-describedby', 'hint');
+  });
 });
 
 // =============================================================================

package/src/SideNav/SideNav.tsx

@@ -490,6 +490,10 @@ export function SideNav({
   // =========================================================================
   const hasStickyTop = !!(header || topContent);
   const hasStickyBottom = !!(footer || footerIcons);
+  // The built-in collapse button only renders when collapse is enabled and it
+  // hasn't been opted out via `collapsible.hasButton: false` (e.g. when the
+  // consumer places a SideNavCollapseButton in the header instead).
+  const showCollapseButton = isCollapsible && hasCollapseButton;
 
   // When resizable, override the nav width via inline style
   const resizableNavStyle: React.CSSProperties | undefined = isResizable
@@ -532,7 +536,7 @@ export function SideNav({
         )}>
         {children}
       </div>
-      {(hasStickyBottom || isCollapsible) && (
+      {(hasStickyBottom || showCollapseButton) && (
         <div
           {...stylex.props(
             styles.stickyBottom,
@@ -544,7 +548,7 @@ export function SideNav({
               styles.footerRow,
               collapsed && styles.footerRowCollapsed,
             )}>
-            {isCollapsible && hasCollapseButton && <SideNavCollapseButton />}
+            {showCollapseButton && <SideNavCollapseButton />}
             {footerIcons}
           </div>
         </div>

package/src/SideNav/SideNavCollapseButton.tsx

@@ -23,6 +23,7 @@ import {durationVars, easeVars} from '../theme/tokens.stylex';
 import {getIcon} from '../Icon/globalIconRegistry';
 import {Button} from '../Button';
 import type {BaseProps} from '../BaseProps';
+import {composeEventHandlers} from '../utils';
 import {
   useSideNavCollapse,
   type SideNavCollapseState,
@@ -101,6 +102,7 @@ export function SideNavCollapseButton({
   handleRef,
   label,
   children,
+  onClick: onClickProp,
   ...props
 }: SideNavCollapseButtonProps) {
   const {isCollapsed, toggle, isCollapsible} =
@@ -119,7 +121,7 @@ export function SideNavCollapseButton({
       label={label ?? (isCollapsed ? 'Expand sidebar' : 'Collapse sidebar')}
       variant="ghost"
       {...props}
-      onClick={toggle}
+      onClick={composeEventHandlers(onClickProp, toggle)}
       icon={
         children ?? (
           <span
@@ -140,8 +142,7 @@ SideNavCollapseButton.displayName = 'SideNavCollapseButton';
 
 function useSideNavCollapseState(
   handleRef:
-    | React.RefObject<SideNavImperativeCollapseHandle | null>
-    | undefined,
+    React.RefObject<SideNavImperativeCollapseHandle | null> | undefined,
 ): SideNavCollapseState {
   const contextCollapseState = useSideNavCollapse();
 

package/src/SideNav/SideNavSection.tsx

@@ -145,6 +145,7 @@ export function SideNavSection({
   className,
   style,
   'data-testid': testId,
+  ...rest
 }: SideNavSectionProps) {
   const {isCollapsed} = useSideNavCollapse();
   const id = useId();
@@ -183,15 +184,16 @@ export function SideNavSection({
   return (
     <div
       ref={ref}
-      role="group"
-      aria-labelledby={titleId}
-      data-testid={testId}
       {...mergeProps(
         themeProps('side-nav-section'),
         stylex.props(styles.root, xstyle),
         className,
         style,
-      )}>
+      )}
+      {...rest}
+      role="group"
+      aria-labelledby={titleId}
+      data-testid={testId}>
       <div
         {...mergeProps(stylex.props(styles.header), {
           style: shouldHideHeader ? visuallyHiddenStyle : undefined,

package/src/SizeContext/SizeContext.test.tsx

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SizeContext.test.tsx
+ * @input Uses vitest, @testing-library/react, SizeContext module
+ * @output Characterization tests for SizeContext / useSize / SizeProvider
+ * @position Testing; validates the size-cascade resolution contract
+ *
+ * SYNC: When SizeContext.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {renderHook, render, screen} from '@testing-library/react';
+import {createElement, type ReactNode} from 'react';
+import {
+  SizeContext,
+  SizeProvider,
+  useSize,
+  type ElementSize,
+} from './SizeContext';
+
+/**
+ * Wrap children in a SizeProvider set to `size`. Passing `null` mimics
+ * "no container is providing a size".
+ */
+function withProvider(size: ElementSize | null) {
+  return function Wrapper({children}: {children: ReactNode}) {
+    return <SizeProvider value={size}>{children}</SizeProvider>;
+  };
+}
+
+describe('SizeContext', () => {
+  describe('context identity', () => {
+    it('defaults to null when read outside any provider', () => {
+      const {result} = renderHook(() => useSize());
+      // No provider + no prop + no explicit default → the 'md' fallback.
+      expect(result.current).toBe('md');
+    });
+
+    it('exposes a displayName for devtools', () => {
+      expect(SizeContext.displayName).toBe('SizeContext');
+    });
+
+    it('SizeProvider is the context Provider itself', () => {
+      expect(SizeProvider).toBe(SizeContext.Provider);
+    });
+  });
+
+  describe('useSize — resolution priority', () => {
+    it('returns the default "md" with no prop and no provider', () => {
+      const {result} = renderHook(() => useSize());
+      expect(result.current).toBe('md');
+    });
+
+    it('honors an explicit defaultSize when neither prop nor context is set', () => {
+      const {result} = renderHook(() => useSize(undefined, 'lg'));
+      expect(result.current).toBe('lg');
+    });
+
+    it('returns the explicit size prop when provided', () => {
+      const {result} = renderHook(() => useSize('sm'));
+      expect(result.current).toBe('sm');
+    });
+
+    it('prop wins over the explicit default', () => {
+      const {result} = renderHook(() => useSize('sm', 'lg'));
+      expect(result.current).toBe('sm');
+    });
+
+    it('inherits the size from an enclosing provider when no prop is passed', () => {
+      const {result} = renderHook(() => useSize(), {
+        wrapper: withProvider('lg'),
+      });
+      expect(result.current).toBe('lg');
+    });
+
+    it('prop wins over the inherited provider size', () => {
+      const {result} = renderHook(() => useSize('sm'), {
+        wrapper: withProvider('lg'),
+      });
+      expect(result.current).toBe('sm');
+    });
+
+    it('inherited context wins over the explicit default fallback', () => {
+      const {result} = renderHook(() => useSize(undefined, 'sm'), {
+        wrapper: withProvider('lg'),
+      });
+      expect(result.current).toBe('lg');
+    });
+
+    it('falls back to default when the provider value is explicitly null', () => {
+      const {result} = renderHook(() => useSize(undefined, 'sm'), {
+        wrapper: withProvider(null),
+      });
+      expect(result.current).toBe('sm');
+    });
+
+    it('falls back to "md" when provider is null and no default is given', () => {
+      const {result} = renderHook(() => useSize(), {
+        wrapper: withProvider(null),
+      });
+      expect(result.current).toBe('md');
+    });
+  });
+
+  describe('useSize — every standard ElementSize resolves', () => {
+    const sizes: ElementSize[] = ['sm', 'md', 'lg'];
+
+    it.each(sizes)('resolves explicit prop "%s"', size => {
+      const {result} = renderHook(() => useSize(size));
+      expect(result.current).toBe(size);
+    });
+
+    it.each(sizes)('resolves inherited provider "%s"', size => {
+      const {result} = renderHook(() => useSize(), {
+        wrapper: withProvider(size),
+      });
+      expect(result.current).toBe(size);
+    });
+  });
+
+  describe('useSize — nested providers', () => {
+    it('resolves to the nearest provider', () => {
+      function Nested({children}: {children: ReactNode}) {
+        return (
+          <SizeProvider value="sm">
+            <SizeProvider value="lg">{children}</SizeProvider>
+          </SizeProvider>
+        );
+      }
+      const {result} = renderHook(() => useSize(), {wrapper: Nested});
+      expect(result.current).toBe('lg');
+    });
+
+    it('a prop still overrides the nearest provider', () => {
+      function Nested({children}: {children: ReactNode}) {
+        return (
+          <SizeProvider value="sm">
+            <SizeProvider value="lg">{children}</SizeProvider>
+          </SizeProvider>
+        );
+      }
+      const {result} = renderHook(() => useSize('md'), {wrapper: Nested});
+      expect(result.current).toBe('md');
+    });
+  });
+
+  describe('useSize — generic (non-ElementSize) values', () => {
+    it('supports a custom string union via the type parameter', () => {
+      type Custom = 'compact' | 'comfortable';
+      const {result} = renderHook(() =>
+        useSize<Custom>('compact', 'comfortable'),
+      );
+      expect(result.current).toBe('compact');
+    });
+
+    it('returns the custom default when no prop is given', () => {
+      type Custom = 'compact' | 'comfortable';
+      const {result} = renderHook(() =>
+        useSize<Custom>(undefined, 'comfortable'),
+      );
+      expect(result.current).toBe('comfortable');
+    });
+
+    it('empty-string prop is a real value and does NOT fall through to default', () => {
+      // '' ?? x === '' because nullish coalescing only catches null/undefined.
+      const {result} = renderHook(() => useSize('' as ElementSize, 'lg'));
+      expect(result.current).toBe('');
+    });
+  });
+
+  describe('integration — components consuming the cascade', () => {
+    function SizedProbe({size}: {size?: ElementSize}) {
+      const resolved = useSize(size);
+      return <span data-testid="probe">{resolved}</span>;
+    }
+
+    it('a child with no size prop reads the container size', () => {
+      render(
+        <SizeProvider value="lg">
+          <SizedProbe />
+        </SizeProvider>,
+      );
+      expect(screen.getByTestId('probe')).toHaveTextContent('lg');
+    });
+
+    it('sibling children resolve independently against the same provider', () => {
+      render(
+        <SizeProvider value="lg">
+          <span data-testid="a">
+            <SizedProbe />
+          </span>
+          <span data-testid="b">
+            <SizedProbe size="sm" />
+          </span>
+        </SizeProvider>,
+      );
+      expect(screen.getByTestId('a')).toHaveTextContent('lg');
+      expect(screen.getByTestId('b')).toHaveTextContent('sm');
+    });
+
+    it('re-renders with the new size when the provider value changes', () => {
+      const {rerender} = render(
+        <SizeProvider value="sm">
+          <SizedProbe />
+        </SizeProvider>,
+      );
+      expect(screen.getByTestId('probe')).toHaveTextContent('sm');
+
+      rerender(
+        <SizeProvider value="lg">
+          <SizedProbe />
+        </SizeProvider>,
+      );
+      expect(screen.getByTestId('probe')).toHaveTextContent('lg');
+    });
+
+    it('works with createElement (no JSX) call form', () => {
+      const {result} = renderHook(() => useSize(), {
+        wrapper: ({children}: {children: ReactNode}) =>
+          createElement(SizeProvider, {value: 'sm'}, children),
+      });
+      expect(result.current).toBe('sm');
+    });
+  });
+});

package/src/Switch/Switch.doc.mjs

@@ -124,10 +124,10 @@ export const docs = {
     },
     {
       name: 'labelSpacing',
-      type: "'default' | 'spread'",
+      type: "'hug' | 'spread'",
       description:
-        'Spacing behavior between label and switch. "spread" pushes them to opposite ends of the container (full width).',
-      default: "'default'",
+        'Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width). "default" is a deprecated alias for "hug".',
+      default: "'hug'",
     },
   ],
   theming: {
@@ -270,10 +270,10 @@ export const docsZh = {
     },
     {
       name: 'labelSpacing',
-      type: "'default' | 'spread'",
+      type: "'hug' | 'spread'",
       description:
-        '标签和开关之间的间距行为。"spread" 将它们推到容器的两端（全宽）。',
-      default: "'default'",
+        '标签和开关之间的间距行为。"hug" 将它们并排放置；"spread" 将它们推到容器的两端（全宽）。"default" 是 "hug" 的已弃用别名。',
+      default: "'hug'",
     },
   ],
   theming: {
@@ -329,6 +329,6 @@ export const docsDense = {
     labelIcon: 'Icon before label text.',
     labelTooltip: 'Tooltip text in info icon at label end.',
     labelPosition: 'Which side label appears; "start" places before switch.',
-    labelSpacing: 'Spacing behavior; "spread" pushes to opposite ends (full width).',
+    labelSpacing: 'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width). "default" is deprecated alias for "hug".',
   },
 };

package/src/Switch/Switch.test.tsx

@@ -470,11 +470,84 @@ describe('Switch', () => {
       expect(screen.getByRole('switch')).toBeDisabled();
     });
   });
+  describe('labelSpacing', () => {
+    const getField = (container: HTMLElement) =>
+      container.querySelector<HTMLElement>('.astryx-switch-field')!;
+
+    it('omits the data attribute for the default hug spacing', () => {
+      const {container} = render(
+        <Switch label="Notify" value={false} onChange={() => {}} />,
+      );
+      expect(getField(container)).not.toHaveAttribute('data-label-spacing');
+    });
+
+    it('reflects spread spacing as a data attribute and variant class', () => {
+      const {container} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="spread"
+        />,
+      );
+      expect(getField(container)).toHaveAttribute(
+        'data-label-spacing',
+        'spread',
+      );
+      expect(getField(container).className).toContain('spread');
+    });
+
+    it('renders explicit hug the same as the default', () => {
+      const {container: implicit} = render(
+        <Switch label="Notify" value={false} onChange={() => {}} />,
+      );
+      const {container: explicit} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="hug"
+        />,
+      );
+      expect(getField(explicit)).not.toHaveAttribute('data-label-spacing');
+      expect(getField(explicit).className).toBe(getField(implicit).className);
+    });
+
+    it("treats the deprecated 'default' value as an alias for hug", () => {
+      const {container: hug} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="hug"
+        />,
+      );
+      const {container: deprecated} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="default"
+        />,
+      );
+      expect(getField(deprecated)).not.toHaveAttribute('data-label-spacing');
+      expect(getField(deprecated).className).toBe(getField(hug).className);
+      // The switch row keeps the hug layout, not the spread justification.
+      expect(getField(deprecated).firstElementChild?.className).toBe(
+        getField(hug).firstElementChild?.className,
+      );
+    });
+  });
   describe('form participation', () => {
     it('submits under htmlName when on', () => {
       const {container} = render(
         <form>
-          <Switch label="Notify" htmlName="notify" value={true} onChange={() => {}} />
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={true}
+            onChange={() => {}}
+          />
         </form>,
       );
       const data = new FormData(container.querySelector('form')!);
@@ -494,13 +567,20 @@ describe('Switch', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
 
     it('submits nothing when off or when htmlName is omitted', () => {
       const {container} = render(
         <form>
-          <Switch label="Off" htmlName="off" value={false} onChange={() => {}} />
+          <Switch
+            label="Off"
+            htmlName="off"
+            value={false}
+            onChange={() => {}}
+          />
           <Switch label="Unnamed" value={true} onChange={() => {}} />
         </form>,
       );
@@ -508,4 +588,23 @@ describe('Switch', () => {
       expect([...data.keys()]).toEqual([]);
     });
   });
+
+  describe('rest forwarding', () => {
+    it('forwards data-testid, id, and aria-* to the root element', () => {
+      const {container} = render(
+        <Switch
+          label="Notifications"
+          value={false}
+          onChange={() => {}}
+          data-testid="my-switch"
+          id="switch-1"
+          aria-label="Toggle notifications"
+        />,
+      );
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toBeNull();
+      expect(root).toHaveAttribute('id', 'switch-1');
+      expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
+    });
+  });
 });

package/src/Switch/Switch.tsx

@@ -185,7 +185,11 @@ const styles = stylex.create({
 
 export type SwitchLabelPosition = 'start' | 'end';
 
-export type SwitchLabelSpacing = 'default' | 'spread';
+export type SwitchLabelSpacing =
+  | 'hug'
+  | 'spread'
+  /** @deprecated Use `'hug'` instead. */
+  | 'default';
 
 export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
   /** Ref forwarded to the root element */
@@ -297,9 +301,11 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
   labelPosition?: SwitchLabelPosition;
   /**
    * Spacing behavior between label and switch.
-   * - 'default': Label and switch are positioned next to each other
+   * - 'hug': Label and switch are positioned next to each other
    * - 'spread': Label and switch are pushed to opposite ends
-   * @default 'default'
+   *
+   * 'default' is a deprecated alias for 'hug'.
+   * @default 'hug'
    */
   labelSpacing?: SwitchLabelSpacing;
   /**
@@ -350,13 +356,14 @@ export function Switch({
   labelIcon,
   labelTooltip,
   labelPosition = 'end',
-  labelSpacing = 'default',
+  labelSpacing = 'hug',
   status,
   width,
   xstyle,
   className,
   style,
   ref,
+  ...rest
 }: SwitchProps) {
   const id = useId();
   const descriptionID = useId();
@@ -368,6 +375,10 @@ export function Switch({
 
   const isOn = optimisticValue === true;
 
+  // 'default' is a deprecated alias for 'hug' (#2889).
+  const resolvedLabelSpacing: SwitchLabelSpacing =
+    labelSpacing === 'default' ? 'hug' : labelSpacing;
+
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the switch row (which already exists) and the
   // native checkbox stays perceivable via aria-disabled instead of the disabled
@@ -487,12 +498,14 @@ export function Switch({
       {...mergeProps(
         themeProps('switch-field', {
           labelPosition: labelPosition !== 'end' ? labelPosition : undefined,
-          labelSpacing: labelSpacing !== 'default' ? labelSpacing : undefined,
+          labelSpacing:
+            resolvedLabelSpacing !== 'hug' ? resolvedLabelSpacing : undefined,
         }),
         stylex.props(width != null && dynamicWidthStyles.width(width), xstyle),
         className,
         style,
-      )}>
+      )}
+      {...rest}>
       <div
         ref={el => {
           // Interaction (hover/focus) listeners for the disabled-message
@@ -505,7 +518,7 @@ export function Switch({
         }}
         {...stylex.props(
           styles.container,
-          labelSpacing === 'spread' && styles.containerSpread,
+          resolvedLabelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
         )}>
         {' '}