@fragments-sdk/ui 0.11.1 → 0.13.0

package/src/components/Select/index.tsx

@@ -16,17 +16,31 @@ export interface SelectOption {
   disabled?: boolean;
 }
 
+/**
+ * Select dropdown for choosing from a list of options.
+ * @see https://usefragments.com/components/select
+ */
 export interface SelectProps {
   children: React.ReactNode;
+  /** Controlled selected value */
   value?: SelectValue | null;
+  /** Default value for uncontrolled usage */
   defaultValue?: SelectValue;
+  /** Called when selection changes */
   onValueChange?: (value: SelectValue | null) => void;
+  /** Controlled open state */
   open?: boolean;
+  /** Default open state */
   defaultOpen?: boolean;
+  /** Called when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Whether the select is non-interactive */
   disabled?: boolean;
+  /** Whether a selection is required */
   required?: boolean;
+  /** Form field name */
   name?: string;
+  /** Placeholder text when no value is selected */
   placeholder?: string;
 }
 
@@ -43,21 +57,18 @@ export interface SelectContentProps extends React.HTMLAttributes<HTMLDivElement>
   maxVisibleItems?: number;
 }
 
-export interface SelectItemProps {
+export interface SelectItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
   children: React.ReactNode;
   value: SelectValue;
   disabled?: boolean;
-  className?: string;
 }
 
-export interface SelectGroupProps {
+export interface SelectGroupProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface SelectGroupLabelProps {
+export interface SelectGroupLabelProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
 // ============================================
@@ -262,7 +273,7 @@ function SelectContent({
   );
 }
 
-function SelectItem({ children, value, disabled, className }: SelectItemProps) {
+function SelectItem({ children, value, disabled, className, ...htmlProps }: SelectItemProps) {
   const { itemsRef, incrementItemsVersion } = React.useContext(SelectContext);
   const classes = [styles.item, className].filter(Boolean).join(' ');
 
@@ -274,11 +285,12 @@ function SelectItem({ children, value, disabled, className }: SelectItemProps) {
     incrementItemsVersion();
     return () => {
       items.delete(value);
+      incrementItemsVersion();
     };
   }, [itemsRef, incrementItemsVersion, value, children]);
 
   return (
-    <BaseSelect.Item value={value} disabled={disabled} className={classes}>
+    <BaseSelect.Item {...htmlProps} value={value} disabled={disabled} className={classes}>
       <BaseSelect.ItemText>{children}</BaseSelect.ItemText>
       <BaseSelect.ItemIndicator className={styles.itemIndicator}>
         <CheckIcon />
@@ -287,14 +299,14 @@ function SelectItem({ children, value, disabled, className }: SelectItemProps) {
   );
 }
 
-function SelectGroup({ children, className }: SelectGroupProps) {
+function SelectGroup({ children, className, ...htmlProps }: SelectGroupProps) {
   const classes = [styles.group, className].filter(Boolean).join(' ');
-  return <BaseSelect.Group className={classes}>{children}</BaseSelect.Group>;
+  return <BaseSelect.Group {...htmlProps} className={classes}>{children}</BaseSelect.Group>;
 }
 
-function SelectGroupLabel({ children, className }: SelectGroupLabelProps) {
+function SelectGroupLabel({ children, className, ...htmlProps }: SelectGroupLabelProps) {
   const classes = [styles.groupLabel, className].filter(Boolean).join(' ');
-  return <BaseSelect.GroupLabel className={classes}>{children}</BaseSelect.GroupLabel>;
+  return <BaseSelect.GroupLabel {...htmlProps} className={classes}>{children}</BaseSelect.GroupLabel>;
 }
 
 // ============================================

package/src/components/Sidebar/Sidebar.test.tsx

@@ -1,13 +1,12 @@
 import { describe, it, expect, vi, beforeAll } from 'vitest';
-import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
 import { Sidebar } from './index';
 
-// Mock matchMedia for jsdom
-beforeAll(() => {
+function mockMatchMedia(matches: boolean) {
   Object.defineProperty(window, 'matchMedia', {
     writable: true,
     value: vi.fn().mockImplementation((query: string) => ({
-      matches: false,
+      matches,
       media: query,
       onchange: null,
       addListener: vi.fn(),
@@ -17,6 +16,11 @@ beforeAll(() => {
       dispatchEvent: vi.fn(),
     })),
   });
+}
+
+// Mock matchMedia for jsdom
+beforeAll(() => {
+  mockMatchMedia(false);
 });
 
 function renderSidebar(props: Partial<React.ComponentProps<typeof Sidebar>> = {}) {
@@ -113,6 +117,81 @@ describe('Sidebar', () => {
     expect(screen.getByRole('button', { name: /expand sidebar/i })).toBeInTheDocument();
   });
 
+  it('composes child click handler in Sidebar.Item asChild mode', async () => {
+    const user = userEvent.setup();
+    const childClick = vi.fn();
+    const onItemClick = vi.fn();
+
+    render(
+      <Sidebar aria-label="Test sidebar">
+        <Sidebar.Nav aria-label="Main">
+          <Sidebar.Section label="Section One">
+            <Sidebar.Item asChild icon={<span>I</span>} onClick={onItemClick}>
+              <a href="#dashboard" onClick={childClick}>Dashboard</a>
+            </Sidebar.Item>
+          </Sidebar.Section>
+        </Sidebar.Nav>
+      </Sidebar>
+    );
+
+    await user.click(screen.getByRole('link', { name: /dashboard/i }));
+
+    expect(childClick).toHaveBeenCalled();
+    expect(onItemClick).toHaveBeenCalled();
+  });
+
+  it('forwards html props to desktop compound parts', () => {
+    render(
+      <Sidebar aria-label="Test sidebar">
+        <Sidebar.Header data-testid="header" data-part="header">Header</Sidebar.Header>
+        <Sidebar.Nav aria-label="Main" data-testid="nav" data-part="nav">
+          <Sidebar.Section data-testid="section" data-part="section" label="Section One">
+            <Sidebar.Item icon={<span>I</span>}>Dashboard</Sidebar.Item>
+          </Sidebar.Section>
+        </Sidebar.Nav>
+        <Sidebar.Footer data-testid="footer" data-part="footer">Footer</Sidebar.Footer>
+        <Sidebar.CollapseToggle data-testid="collapse-toggle" data-part="collapse-toggle" />
+        <Sidebar.Rail data-testid="rail" data-part="rail" />
+      </Sidebar>
+    );
+
+    expect(screen.getByTestId('header')).toHaveAttribute('data-part', 'header');
+    expect(screen.getByTestId('nav')).toHaveAttribute('data-part', 'nav');
+    expect(screen.getByTestId('section')).toHaveAttribute('data-part', 'section');
+    expect(screen.getByTestId('footer')).toHaveAttribute('data-part', 'footer');
+    expect(screen.getByTestId('collapse-toggle')).toHaveAttribute('data-part', 'collapse-toggle');
+    expect(screen.getByTestId('rail')).toHaveAttribute('data-part', 'rail');
+  });
+
+  it('forwards props to mobile Trigger/Overlay and composes overlay click', async () => {
+    mockMatchMedia(true);
+    const user = userEvent.setup();
+    const overlayClick = vi.fn();
+
+    render(
+      <Sidebar defaultOpen aria-label="Mobile sidebar">
+        <Sidebar.Trigger data-testid="trigger" data-part="trigger" />
+        <Sidebar.Overlay data-testid="overlay" data-part="overlay" onClick={overlayClick} />
+        <Sidebar.Nav aria-label="Main">
+          <Sidebar.Section label="Section One">
+            <Sidebar.Item icon={<span>I</span>}>Dashboard</Sidebar.Item>
+          </Sidebar.Section>
+        </Sidebar.Nav>
+      </Sidebar>
+    );
+
+    const trigger = await screen.findByTestId('trigger');
+    const overlay = await screen.findByTestId('overlay');
+
+    expect(trigger).toHaveAttribute('data-part', 'trigger');
+    expect(overlay).toHaveAttribute('data-part', 'overlay');
+
+    await user.click(overlay);
+    expect(overlayClick).toHaveBeenCalled();
+
+    mockMatchMedia(false);
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = renderSidebar();
     await expectNoA11yViolations(container);

package/src/components/Sidebar/index.tsx

@@ -9,6 +9,17 @@ import { ScrollArea } from '../ScrollArea';
 import { useFocusTrap } from '../../utils/a11y';
 import { useKeyboardShortcut } from '../../utils/keyboard-shortcuts';
 
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
+  userHandler: ((event: E) => void) | undefined,
+  internalHandler: (event: E) => void
+) {
+  return (event: E) => {
+    userHandler?.(event);
+    if (event.defaultPrevented) return;
+    internalHandler(event);
+  };
+}
+
 // ============================================
 // Types
 // ============================================
@@ -66,21 +77,19 @@ export interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
   collapsible?: SidebarCollapsible;
 }
 
-export interface SidebarHeaderProps {
+export interface SidebarHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Content to show when sidebar is collapsed (e.g., just logo icon) */
   collapsedContent?: React.ReactNode;
-  className?: string;
 }
 
-export interface SidebarNavProps {
+export interface SidebarNavProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Accessible label for navigation */
   'aria-label'?: string;
-  className?: string;
 }
 
-export interface SidebarSectionProps {
+export interface SidebarSectionProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Optional section label */
   label?: string;
@@ -90,16 +99,14 @@ export interface SidebarSectionProps {
   collapsible?: boolean;
   /** Default expanded state (only applies when collapsible is true) */
   defaultOpen?: boolean;
-  className?: string;
 }
 
-export interface SidebarSectionActionProps {
+export interface SidebarSectionActionProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
   children: React.ReactNode;
   /** Click handler */
-  onClick?: () => void;
+  onClick?: (event?: React.MouseEvent<HTMLButtonElement>) => void;
   /** Accessible label */
   'aria-label'?: string;
-  className?: string;
 }
 
 export interface SidebarItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onClick'> {
@@ -143,39 +150,31 @@ export interface SidebarSubItemProps extends Omit<React.HTMLAttributes<HTMLEleme
   onClick?: () => void;
 }
 
-export interface SidebarFooterProps {
+export interface SidebarFooterProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface SidebarTriggerProps {
+export interface SidebarTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Custom trigger element (uses render prop pattern) */
   children?: React.ReactNode;
   /** Accessible label */
   'aria-label'?: string;
-  className?: string;
 }
 
-export interface SidebarOverlayProps {
-  className?: string;
-}
+export type SidebarOverlayProps = React.HTMLAttributes<HTMLDivElement>;
 
-export interface SidebarCollapseToggleProps {
+export interface SidebarCollapseToggleProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Accessible label */
   'aria-label'?: string;
-  className?: string;
 }
 
-export interface SidebarRailProps {
-  className?: string;
-}
+export type SidebarRailProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
 
-export interface SidebarMenuSkeletonProps {
+export interface SidebarMenuSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Number of skeleton items to render */
   count?: number;
   /** Show icons in skeleton items */
   showIcon?: boolean;
-  className?: string;
 }
 
 // ============================================
@@ -632,7 +631,12 @@ function SidebarRoot({
   );
 }
 
-function SidebarHeader({ children, collapsedContent, className }: SidebarHeaderProps) {
+function SidebarHeader({
+  children,
+  collapsedContent,
+  className,
+  ...htmlProps
+}: SidebarHeaderProps) {
   const { collapsed, isMobile } = useSidebarContext();
   const isCollapsed = collapsed && !isMobile;
   const classes = [styles.header, className].filter(Boolean).join(' ');
@@ -640,13 +644,18 @@ function SidebarHeader({ children, collapsedContent, className }: SidebarHeaderP
   // Show collapsed content when sidebar is collapsed (and we have it), otherwise show children
   const content = isCollapsed && collapsedContent ? collapsedContent : children;
 
-  return <div className={classes}>{content}</div>;
+  return <div {...htmlProps} className={classes}>{content}</div>;
 }
 
-function SidebarNav({ children, 'aria-label': ariaLabel = 'Main navigation', className }: SidebarNavProps) {
+function SidebarNav({
+  children,
+  'aria-label': ariaLabel = 'Main navigation',
+  className,
+  ...htmlProps
+}: SidebarNavProps) {
   const classes = [styles.nav, className].filter(Boolean).join(' ');
   return (
-    <nav className={classes} aria-label={ariaLabel}>
+    <nav {...htmlProps} className={classes} aria-label={ariaLabel}>
       <ScrollArea orientation="vertical" showFades className={styles.navScrollArea}>
         {children}
       </ScrollArea>
@@ -660,7 +669,8 @@ function SidebarSection({
   action,
   collapsible: isCollapsibleProp = false,
   defaultOpen = true,
-  className
+  className,
+  ...htmlProps
 }: SidebarSectionProps) {
   const { collapsed, isMobile } = useSidebarContext();
 
@@ -676,7 +686,7 @@ function SidebarSection({
   // Non-collapsible section
   if (!isCollapsible) {
     return (
-      <div className={classes} role="group" aria-label={label}>
+      <div {...htmlProps} className={classes} role="group" aria-label={label}>
         {(showLabel || showAction) && (
           <div className={styles.sectionHeader}>
             {showLabel && <div className={styles.sectionLabel}>{label}</div>}
@@ -692,7 +702,7 @@ function SidebarSection({
 
   // Collapsible section using Collapsible component
   return (
-    <div className={classes} role="group" aria-label={label}>
+    <div {...htmlProps} className={classes} role="group" aria-label={label}>
       <Collapsible defaultOpen={defaultOpen} className={styles.sectionCollapsible}>
         <div className={styles.sectionHeader}>
           <Collapsible.Trigger
@@ -718,14 +728,16 @@ function SidebarSectionAction({
   onClick,
   'aria-label': ariaLabel,
   className,
+  ...htmlProps
 }: SidebarSectionActionProps) {
   const classes = [styles.sectionAction, className].filter(Boolean).join(' ');
 
   return (
     <button
       type="button"
+      {...htmlProps}
       className={classes}
-      onClick={onClick}
+      onClick={(event) => onClick?.(event)}
       aria-label={ariaLabel}
     >
       {children}
@@ -817,11 +829,19 @@ function SidebarItem({
 
   if (asChild && React.isValidElement(children)) {
     // Clone the child element and merge props
+    const childProps = children.props as {
+      className?: string;
+      onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+    };
     itemElement = React.cloneElement(children, {
       ...itemProps,
       ...rest,
+      onClick: composeEventHandlers(
+        childProps.onClick,
+        (event: React.MouseEvent<HTMLElement>) => handleClick(event)
+      ),
       // Merge classNames
-      className: [classes, (children.props as { className?: string }).className].filter(Boolean).join(' '),
+      className: [classes, childProps.className].filter(Boolean).join(' '),
       children: itemContent,
     } as React.HTMLAttributes<HTMLElement>);
   } else if (href) {
@@ -917,12 +937,18 @@ function SidebarSubmenu({ children }: { children: React.ReactNode }) {
   );
 }
 
-function SidebarFooter({ children, className }: SidebarFooterProps) {
+function SidebarFooter({ children, className, ...htmlProps }: SidebarFooterProps) {
   const classes = [styles.footer, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
-function SidebarTrigger({ children, 'aria-label': ariaLabel = 'Toggle navigation', className }: SidebarTriggerProps) {
+function SidebarTrigger({
+  children,
+  'aria-label': ariaLabel = 'Toggle navigation',
+  className,
+  onClick,
+  ...htmlProps
+}: SidebarTriggerProps) {
   const { open, setOpen, isMobile, sidebarId } = useSidebarContext();
 
   // Only render trigger on mobile
@@ -934,9 +960,10 @@ function SidebarTrigger({ children, 'aria-label': ariaLabel = 'Toggle navigation
 
   return (
     <button
+      {...htmlProps}
       type="button"
       className={classes}
-      onClick={() => setOpen(!open)}
+      onClick={composeEventHandlers(onClick, () => setOpen(!open))}
       aria-label={ariaLabel}
       aria-expanded={open}
       aria-controls={sidebarId}
@@ -946,7 +973,7 @@ function SidebarTrigger({ children, 'aria-label': ariaLabel = 'Toggle navigation
   );
 }
 
-function SidebarOverlay({ className }: SidebarOverlayProps) {
+function SidebarOverlay({ className, onClick, ...htmlProps }: SidebarOverlayProps) {
   const { open, setOpen, isMobile } = useSidebarContext();
 
   // Only render overlay on mobile when open
@@ -958,15 +985,21 @@ function SidebarOverlay({ className }: SidebarOverlayProps) {
 
   return (
     <div
+      {...htmlProps}
       className={classes}
-      onClick={() => setOpen(false)}
+      onClick={composeEventHandlers(onClick, () => setOpen(false))}
       aria-hidden="true"
       data-state={open ? 'open' : 'closed'}
     />
   );
 }
 
-function SidebarCollapseToggle({ 'aria-label': ariaLabel, className }: SidebarCollapseToggleProps) {
+function SidebarCollapseToggle({
+  'aria-label': ariaLabel,
+  className,
+  onClick,
+  ...htmlProps
+}: SidebarCollapseToggleProps) {
   const { collapsed, setCollapsed, isMobile, collapsible, hasIcons } = useSidebarContext();
 
   // Don't show on mobile or when collapsing is disabled
@@ -987,9 +1020,10 @@ function SidebarCollapseToggle({ 'aria-label': ariaLabel, className }: SidebarCo
 
   return (
     <button
+      {...htmlProps}
       type="button"
       className={classes}
-      onClick={() => setCollapsed(!collapsed)}
+      onClick={composeEventHandlers(onClick, () => setCollapsed(!collapsed))}
       aria-label={label}
     >
       <CollapsePanelIcon />
@@ -997,7 +1031,13 @@ function SidebarCollapseToggle({ 'aria-label': ariaLabel, className }: SidebarCo
   );
 }
 
-function SidebarRail({ className }: SidebarRailProps) {
+function SidebarRail({
+  className,
+  onClick,
+  title,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: SidebarRailProps) {
   const { collapsed, setCollapsed, isMobile, collapsible } = useSidebarContext();
 
   // Don't show on mobile or when collapsing is disabled
@@ -1013,11 +1053,12 @@ function SidebarRail({ className }: SidebarRailProps) {
 
   return (
     <button
+      {...htmlProps}
       type="button"
       className={classes}
-      onClick={() => setCollapsed(!collapsed)}
-      aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-      title={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+      onClick={composeEventHandlers(onClick, () => setCollapsed(!collapsed))}
+      aria-label={ariaLabel ?? (collapsed ? 'Expand sidebar' : 'Collapse sidebar')}
+      title={title ?? (collapsed ? 'Expand sidebar' : 'Collapse sidebar')}
     />
   );
 }
@@ -1026,6 +1067,7 @@ function SidebarMenuSkeleton({
   count = 5,
   showIcon = true,
   className,
+  ...htmlProps
 }: SidebarMenuSkeletonProps) {
   const { collapsed, isMobile } = useSidebarContext();
   const isCollapsed = collapsed && !isMobile;
@@ -1034,7 +1076,7 @@ function SidebarMenuSkeleton({
   const labelWidths = ['64%', '72%', '68%', '79%', '74%', '66%', '83%', '70%'];
 
   return (
-    <div className={classes} aria-hidden="true">
+    <div {...htmlProps} className={classes} aria-hidden="true">
       {Array.from({ length: count }).map((_, i) => (
         <div key={i} className={styles.skeletonItem}>
           {showIcon && <Skeleton variant="avatar" size="sm" />}

package/src/components/Slider/Slider.fragment.tsx

@@ -71,6 +71,10 @@ export default defineFragment({
       type: 'function',
       description: 'Called with new value when changed',
     },
+    onValueChange: {
+      type: 'function',
+      description: 'Alias for onChange (Radix convention): (value: number) => void',
+    },
     min: {
       type: 'number',
       description: 'Minimum value',
@@ -115,7 +119,7 @@ export default defineFragment({
     propsSummary: [
       'value: number - controlled value',
       'defaultValue: number - initial value',
-      'onChange: (value: number) => void - change handler',
+      'onChange: (value: number) => void - change handler (or onValueChange)',
       'min/max: number - range bounds',
       'step: number - increment size',
       'label: string - field label',

package/src/components/Slider/Slider.test.tsx

@@ -44,6 +44,12 @@ describe('Slider', () => {
     expect(screen.getByText('75')).toBeInTheDocument();
   });
 
+  it('accepts onValueChange alias for onChange', () => {
+    const handleChange = vi.fn();
+    render(<Slider aria-label="Volume" value={50} onValueChange={handleChange} />);
+    expect(screen.getByRole('slider')).toBeInTheDocument();
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Slider label="Accessible slider" defaultValue={50} />);
     await expectNoA11yViolations(container);

package/src/components/Slider/index.tsx

@@ -5,11 +5,21 @@ import { Field } from '@base-ui/react/field';
 import { Slider as BaseSlider } from '@base-ui/react/slider';
 import styles from './Slider.module.scss';
 
+/**
+ * Range slider for selecting a numeric value within a defined range.
+ * @see https://usefragments.com/components/slider
+ */
 export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /** Visible label text */
   label?: string;
+  /** Controlled value */
   value?: number;
+  /** Default value for uncontrolled usage */
   defaultValue?: number;
+  /** Called when the slider value changes */
   onChange?: (value: number) => void;
+  /** Alias for onChange (Radix convention) */
+  onValueChange?: (value: number) => void;
   min?: number;
   max?: number;
   step?: number;
@@ -32,6 +42,7 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
       value,
       defaultValue,
       onChange,
+      onValueChange,
       min = 0,
       max = 100,
       step = 1,
@@ -52,10 +63,11 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
     const [internalValue, setInternalValue] = React.useState(defaultValue ?? min);
     const displayValue = value !== undefined ? value : internalValue;
 
+    const resolvedOnChange = onChange ?? onValueChange;
     const handleChange = (newValue: number | number[]) => {
       const val = Array.isArray(newValue) ? newValue[0] : newValue;
       setInternalValue(val);
-      onChange?.(val);
+      resolvedOnChange?.(val);
     };
 
     return (

package/src/components/Stack/Stack.fragment.tsx

@@ -54,7 +54,7 @@ export default defineFragment({
     },
     gap: {
       type: 'union',
-      description: 'Spacing between items: "none", "xs", "sm", "md", "lg", "xl", or responsive object',
+      description: 'Spacing between items: "none"|"xs"|"sm"|"md"|"lg"|"xl", a number (1-8) for space scale, or responsive object',
       default: 'md',
     },
     align: {
@@ -93,7 +93,7 @@ export default defineFragment({
   contract: {
     propsSummary: [
       'direction: row|column|{responsive} - stack direction',
-      'gap: none|xs|sm|md|lg|xl|{responsive} - spacing',
+      'gap: none|xs|sm|md|lg|xl|number|{responsive} - spacing (number maps to space scale)',
       'align: start|center|end|stretch|baseline - cross-axis',
       'justify: start|center|end|between - main-axis',
       'wrap: boolean - allow wrapping',
@@ -155,6 +155,26 @@ export default defineFragment({
         </Stack>
       ),
     },
+    {
+      name: 'Numeric Gap',
+      description: 'Using number values (1-8) mapped to the spacing scale',
+      render: () => (
+        <Stack gap="lg">
+          <Stack direction="row" gap={2}>
+            <Badge variant="info">Gap 2</Badge>
+            <Badge variant="info">Gap 2</Badge>
+          </Stack>
+          <Stack direction="row" gap={4}>
+            <Badge variant="info">Gap 4</Badge>
+            <Badge variant="info">Gap 4</Badge>
+          </Stack>
+          <Stack direction="row" gap={6}>
+            <Badge variant="info">Gap 6</Badge>
+            <Badge variant="info">Gap 6</Badge>
+          </Stack>
+        </Stack>
+      ),
+    },
     {
       name: 'Alignment',
       description: 'Cross-axis and main-axis alignment',

package/src/components/Stack/Stack.test.tsx

@@ -40,6 +40,12 @@ describe('Stack', () => {
     expect(ref).toHaveBeenCalled();
   });
 
+  it('applies inline style for numeric gap values', () => {
+    const { container } = render(<Stack gap={4}><span>A</span></Stack>);
+    const el = container.firstChild as HTMLElement;
+    expect(el.style.gap).toBe('var(--fui-space-4)');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Stack><span>A</span><span>B</span></Stack>);
     await expectNoA11yViolations(container);