@fpkit/acss 3.1.1 → 3.2.0

package/libs/index.d.cts

@@ -1,8 +1,8 @@
 export { Button, ButtonProps } from './components/button.cjs';
 export { Card, Content as CardContent, Footer as CardFooter, CardProps, Title as CardTitle } from './components/card.cjs';
 import React$1, { ReactNode } from 'react';
-import { I as IconProps } from './icons-287fce3a.js';
-export { a as Icon, b as IconProps } from './icons-287fce3a.js';
+import { I as IconProps } from './icons-df8e744f.js';
+export { a as Icon, b as IconProps } from './icons-df8e744f.js';
 export { default as Field, FieldProps } from './components/form/fields.cjs';
 export { default as Input } from './components/form/inputs.cjs';
 export { _ as Link, L as LinkProps, _ as To } from './link-59ad884f.js';
@@ -12,11 +12,11 @@ export { default as Popover, PopoverProps } from './components/popover/popover.c
 export { RenderTable as TBL, TableProps } from './components/tables/table.cjs';
 export { Dialog } from './components/dialog/dialog.cjs';
 import { U as UI } from './ui-d01b50d4.js';
+import { C as ComponentProps$1 } from './component-props-50e69975.js';
 export { Nav, NavComponent, NavItem, NavItemProps, NavList, NavListProps, NavProps } from './components/nav/nav.cjs';
 export { default as Text, TextProps } from './components/text/text.cjs';
 export { b as Heading, H as HeadingLevel, T as Title, a as TitleProps } from './heading-7446cb46.js';
 export { default as Textarea } from './components/form/textarea.cjs';
-import { C as ComponentProps$1 } from './component-props-67d978a2.js';
 export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb.cjs';
 export { I as InputProps, T as TextareaProps } from './form.types-d25ebfac.js';
 export { L as ListItemProps, a as ListProps } from './list.types-d26de310.js';
@@ -577,6 +577,925 @@ declare const Section: ({ id, children, styles, classes, ...props }: ComponentPr
  */
 declare const Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React$1.JSX.Element;
 
+/**
+ * Shared types for layout primitive components (Box, Stack, Cluster, Grid)
+ */
+/**
+ * Spacing scale values for padding, margin, and gap properties
+ * Maps to CSS custom properties (--spacing-*)
+ * - '0': No spacing
+ * - 'xs': Extra small (clamp 4-8px)
+ * - 'sm': Small (clamp 8-12px)
+ * - 'md': Medium (clamp 12-18px)
+ * - 'lg': Large (clamp 16-24px)
+ * - 'xl': Extra large (clamp 24-32px)
+ */
+type SpacingScale = "0" | "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Semantic HTML element types for Box component
+ */
+type BoxElement = "div" | "section" | "article" | "aside" | "main" | "header" | "footer" | "nav";
+/**
+ * Semantic HTML element types for Stack component
+ */
+type StackElement = "div" | "section" | "article" | "ul" | "ol" | "nav";
+/**
+ * Semantic HTML element types for Cluster component
+ */
+type ClusterElement = "div" | "ul" | "ol" | "nav" | "section";
+/**
+ * Semantic HTML element types for Grid component
+ */
+type GridElement = "div" | "section" | "article" | "ul" | "ol";
+/**
+ * Semantic HTML element types for Grid.Item sub-component
+ */
+type GridItemElement = "div" | "section" | "article" | "li";
+
+/**
+ * Props for the Box component - a fundamental container primitive for spacing and sizing control.
+ *
+ * The Box component provides a flexible, semantic container with comprehensive spacing, sizing,
+ * and visual customization options. All spacing values use the unified spacing scale with
+ * fluid responsive values via CSS clamp().
+ *
+ * ## Design Principles
+ * - **Logical Properties**: Uses `padding-inline`/`padding-block` for better i18n support
+ * - **Fluid Spacing**: All spacing scales responsively without media queries
+ * - **Semantic HTML**: Defaults to `div` but supports semantic elements via `as` prop
+ * - **CSS Custom Properties**: All values customizable via CSS variables
+ *
+ * @example
+ * // Basic container with padding
+ * <Box padding="md">
+ *   <h1>Content</h1>
+ * </Box>
+ *
+ * @example
+ * // Centered container with max width
+ * <Box
+ *   padding="lg"
+ *   maxWidth="container"
+ *   style={{ marginInline: 'auto' }}
+ * >
+ *   <article>Centered content</article>
+ * </Box>
+ *
+ * @example
+ * // Card-like box with radius
+ * <Box
+ *   padding="lg"
+ *   radius="md"
+ *   as="article"
+ *   styles={{
+ *     '--box-bg': '#fff',
+ *     boxShadow: '0 1px 3px rgba(0,0,0,0.1)'
+ *   }}
+ * >
+ *   <h2>Card Title</h2>
+ *   <p>Card content</p>
+ * </Box>
+ */
+interface BoxProps extends Partial<ComponentProps$1>, Omit<React$1.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Padding on all sides.
+     * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+     * Maps to CSS custom properties (--spacing-*)
+     * @example
+     * <Box padding="md">Content</Box>
+     */
+    padding?: SpacingScale;
+    /**
+     * Padding on inline axis (left/right in LTR, right/left in RTL).
+     * Uses logical property `padding-inline` for better internationalization.
+     * @example
+     * <Box paddingInline="xl">Wide horizontal padding</Box>
+     */
+    paddingInline?: SpacingScale;
+    /**
+     * Padding on block axis (top/bottom).
+     * Uses logical property `padding-block` for consistency.
+     * @example
+     * <Box paddingBlock="md">Vertical padding</Box>
+     */
+    paddingBlock?: SpacingScale;
+    /**
+     * Margin on all sides.
+     * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+     * @example
+     * <Box margin="lg">Content with margin</Box>
+     */
+    margin?: SpacingScale;
+    /**
+     * Margin on inline axis (left/right in LTR).
+     * For centering, use inline styles: `style={{ marginInline: 'auto' }}`
+     * @example
+     * <Box marginInline="md">Horizontal margin</Box>
+     */
+    marginInline?: SpacingScale;
+    /**
+     * Margin on block axis (top/bottom).
+     * @example
+     * <Box marginBlock="lg">Vertical margin</Box>
+     */
+    marginBlock?: SpacingScale;
+    /**
+     * Width behavior control.
+     * - 'auto': Natural width (default)
+     * - 'full': 100% width
+     * - 'fit': Width fits content (fit-content)
+     * - 'max': Width determined by widest content (max-content)
+     * @default 'auto'
+     * @example
+     * <Box width="full">Full width box</Box>
+     */
+    width?: "auto" | "full" | "fit" | "max";
+    /**
+     * Maximum width constraint.
+     * Useful for readable text widths and responsive containers.
+     * Sizes map to: xs(480px), sm(640px), md(768px), lg(1024px), xl(1280px), container(1200px)
+     * @example
+     * <Box maxWidth="container" style={{ marginInline: 'auto' }}>
+     *   Centered container with max width
+     * </Box>
+     */
+    maxWidth?: "xs" | "sm" | "md" | "lg" | "xl" | "container";
+    /**
+     * Border radius for rounded corners.
+     * - 'xs' through 'xl': Increasing radii (2px - 12px)
+     * - 'full': Fully rounded (9999px) for pills/circles
+     * @example
+     * <Box radius="md">Slightly rounded box</Box>
+     * @example
+     * <Box radius="full" width="fit" padding="md">
+     *   <Avatar />
+     * </Box>
+     */
+    radius?: SpacingScale | "full";
+    /**
+     * Polymorphic element type to render.
+     * Defaults to 'div' but supports semantic HTML elements.
+     * Choose semantic elements for better accessibility:
+     * - 'section' for thematic groupings
+     * - 'article' for self-contained content
+     * - 'aside' for tangentially related content
+     * - 'main' for primary page content
+     * - 'header'/'footer' for page/section headers/footers
+     * - 'nav' for navigation landmarks
+     * @default 'div'
+     * @example
+     * <Box as="section" padding="lg">
+     *   <h2>Section Content</h2>
+     * </Box>
+     */
+    as?: BoxElement;
+    /**
+     * Additional CSS classes to apply.
+     * Merged with generated utility classes.
+     * @example
+     * <Box classes="my-custom-class" padding="md">Content</Box>
+     */
+    className?: string;
+    /**
+     * Children elements to render inside the Box.
+     */
+    children?: React$1.ReactNode;
+}
+
+/**
+ * Box - A fundamental container primitive for spacing and sizing control.
+ *
+ * The Box component is the foundational layout primitive in fpkit, providing a flexible,
+ * semantic container with comprehensive control over spacing (padding/margin), sizing,
+ * and visual appearance. It uses utility classes generated from props, ensuring consistent
+ * styling across the application.
+ *
+ * ## Key Features
+ * - **Unified Spacing Scale**: Fluid responsive spacing using CSS clamp()
+ * - **Logical Properties**: `padding-inline`/`padding-block` for i18n support
+ * - **Polymorphic Rendering**: Render as any semantic HTML element via `as` prop
+ * - **CSS Custom Properties**: All values customizable for theming
+ * - **Type-Safe**: Full TypeScript support with IntelliSense
+ *
+ * ## Accessibility
+ * - Uses semantic HTML elements by default
+ * - Supports ARIA attributes via spread props
+ * - Encourages semantic elements via `as` prop
+ * - All props forwarded to underlying element
+ *
+ * ## Use Cases
+ * - Container with padding/margin
+ * - Centered layouts with max-width
+ * - Card-like components
+ * - Spacing between sections
+ * - Semantic landmarks
+ *
+ * @example
+ * // Basic container with padding
+ * <Box padding="md">
+ *   <h1>Content</h1>
+ * </Box>
+ *
+ * @example
+ * // Centered container with max width
+ * <Box
+ *   padding="lg"
+ *   maxWidth="container"
+ *   style={{ marginInline: 'auto' }}
+ * >
+ *   <article>Centered content</article>
+ * </Box>
+ *
+ * @example
+ * // Card-like box with radius
+ * <Box
+ *   padding="lg"
+ *   radius="md"
+ *   as="article"
+ *   styles={{
+ *     backgroundColor: '#fff',
+ *     boxShadow: '0 1px 3px rgba(0,0,0,0.1)'
+ *   }}
+ * >
+ *   <h2>Card Title</h2>
+ *   <p>Card content</p>
+ * </Box>
+ *
+ * @example
+ * // Asymmetric spacing with logical properties
+ * <Box
+ *   paddingInline="xl"
+ *   paddingBlock="md"
+ *   as="section"
+ * >
+ *   <p>Wide horizontal padding, narrow vertical</p>
+ * </Box>
+ *
+ * @example
+ * // Semantic section with spacing
+ * <Box as="section" padding="xl" margin="lg">
+ *   <h2>Section Title</h2>
+ *   <p>Section content...</p>
+ * </Box>
+ *
+ * @see {@link BoxProps} for complete props documentation
+ */
+declare const Box: React$1.ForwardRefExoticComponent<BoxProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Props for the Stack component - a simplified layout primitive for vertical or horizontal spacing.
+ *
+ * Stack provides an easy-to-use flexbox-based layout for creating vertical or horizontal arrangements
+ * with consistent spacing between children. It's simpler than the full Flex component, ideal for
+ * common stacking patterns.
+ *
+ * ## Design Principles
+ * - **Simplified API**: Fewer props than Flex for common use cases
+ * - **Fluid Spacing**: Uses unified spacing scale with responsive values
+ * - **Flexbox-Based**: Built on CSS flexbox for reliable layouts
+ * - **Semantic HTML**: Defaults to `div` but supports semantic elements
+ *
+ * @example
+ * // Vertical stack (default)
+ * <Stack gap="md">
+ *   <h1>Title</h1>
+ *   <p>Paragraph 1</p>
+ *   <p>Paragraph 2</p>
+ * </Stack>
+ *
+ * @example
+ * // Horizontal stack for buttons
+ * <Stack direction="horizontal" gap="sm">
+ *   <Button>Cancel</Button>
+ *   <Button variant="primary">Submit</Button>
+ * </Stack>
+ *
+ * @example
+ * // Centered vertical stack
+ * <Stack
+ *   gap="lg"
+ *   align="center"
+ *   justify="center"
+ *   style={{ minHeight: '100vh' }}
+ * >
+ *   <Logo />
+ *   <h1>Welcome</h1>
+ * </Stack>
+ */
+interface StackProps extends Partial<ComponentProps$1>, Omit<React$1.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Gap between children.
+     * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+     * Maps to CSS custom properties (--spacing-*)
+     * @default 'md'
+     * @example
+     * <Stack gap="lg">Content</Stack>
+     */
+    gap?: SpacingScale;
+    /**
+     * Layout direction.
+     * - 'vertical': Stack children vertically (column)
+     * - 'horizontal': Stack children horizontally (row)
+     * @default 'vertical'
+     * @example
+     * <Stack direction="horizontal" gap="sm">
+     *   <Button>Cancel</Button>
+     *   <Button>Submit</Button>
+     * </Stack>
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * Alignment on cross axis.
+     * - 'start': Align items to start (left in horizontal, top in vertical)
+     * - 'center': Center items
+     * - 'end': Align items to end (right in horizontal, bottom in vertical)
+     * - 'stretch': Stretch items to fill cross axis
+     * @default 'stretch'
+     * @example
+     * <Stack align="center">Centered items</Stack>
+     */
+    align?: "start" | "center" | "end" | "stretch";
+    /**
+     * Alignment on main axis.
+     * - 'start': Items at start
+     * - 'center': Items centered
+     * - 'end': Items at end
+     * - 'between': Space between items
+     * @example
+     * <Stack justify="between">
+     *   <Header />
+     *   <Footer />
+     * </Stack>
+     */
+    justify?: "start" | "center" | "end" | "between";
+    /**
+     * Allow items to wrap to next line/column.
+     * - 'wrap': Items wrap when they exceed container
+     * - 'nowrap': Items stay on single line/column (default)
+     * @default 'nowrap'
+     * @example
+     * <Stack direction="horizontal" wrap="wrap">
+     *   {items.map(item => <Item key={item.id} />)}
+     * </Stack>
+     */
+    wrap?: "wrap" | "nowrap";
+    /**
+     * Polymorphic element type to render.
+     * Defaults to 'div' but supports semantic HTML elements.
+     * @default 'div'
+     * @example
+     * <Stack as="nav" direction="horizontal" gap="md">
+     *   <a href="/">Home</a>
+     *   <a href="/about">About</a>
+     * </Stack>
+     */
+    as?: StackElement;
+    /**
+     * Additional CSS classes to apply.
+     * Merged with generated utility classes.
+     * @example
+     * <Stack className="custom-stack" gap="md">Content</Stack>
+     */
+    className?: string;
+    /**
+     * Children elements to render inside the Stack.
+     */
+    children?: React$1.ReactNode;
+}
+
+/**
+ * Stack - A simplified layout primitive for vertical or horizontal spacing between children.
+ *
+ * The Stack component provides an easy-to-use flexbox-based layout for creating vertical or
+ * horizontal arrangements with consistent gap spacing. It's designed to be simpler than the
+ * full Flex component, focusing on the most common stacking patterns.
+ *
+ * ## Key Features
+ * - **Simple API**: Fewer props than Flex for common use cases
+ * - **Fluid Spacing**: Responsive gap using CSS clamp()
+ * - **Flexbox-Based**: Reliable cross-browser layout
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * ## Accessibility
+ * - Uses semantic HTML elements when appropriate via `as` prop
+ * - Supports all ARIA attributes via spread props
+ * - Proper focus order maintained (visual order matches DOM order)
+ *
+ * ## Use Cases
+ * - Vertical spacing between content sections
+ * - Horizontal button groups
+ * - Navigation menus
+ * - Form layouts
+ * - Centered content (vertical/horizontal)
+ *
+ * @example
+ * // Vertical stack with medium gap (default)
+ * <Stack gap="md">
+ *   <h1>Title</h1>
+ *   <p>Paragraph 1</p>
+ *   <p>Paragraph 2</p>
+ * </Stack>
+ *
+ * @example
+ * // Horizontal button group
+ * <Stack direction="horizontal" gap="sm">
+ *   <Button>Cancel</Button>
+ *   <Button variant="primary">Submit</Button>
+ * </Stack>
+ *
+ * @example
+ * // Centered vertical stack
+ * <Stack
+ *   gap="lg"
+ *   align="center"
+ *   justify="center"
+ *   style={{ minHeight: '100vh' }}
+ * >
+ *   <Logo />
+ *   <h1>Welcome</h1>
+ *   <Button>Get Started</Button>
+ * </Stack>
+ *
+ * @example
+ * // Navigation with horizontal layout
+ * <Stack
+ *   as="nav"
+ *   direction="horizontal"
+ *   gap="md"
+ *   justify="between"
+ *   align="center"
+ * >
+ *   <Logo />
+ *   <Stack direction="horizontal" gap="sm">
+ *     <a href="/about">About</a>
+ *     <a href="/contact">Contact</a>
+ *   </Stack>
+ * </Stack>
+ *
+ * @see {@link StackProps} for complete props documentation
+ */
+declare const Stack: React$1.ForwardRefExoticComponent<StackProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Props for the Cluster component - a wrapping flex layout for inline groups.
+ *
+ * Cluster provides a flexible layout for inline content that needs to wrap naturally,
+ * such as tags, badges, button groups, or navigation links. Items wrap to the next line
+ * when they exceed the container width.
+ *
+ * @example
+ * // Tag cloud
+ * <Cluster gap="sm">
+ *   <Tag>React</Tag>
+ *   <Tag>TypeScript</Tag>
+ *   <Tag>CSS</Tag>
+ * </Cluster>
+ *
+ * @example
+ * // Button group
+ * <Cluster gap="md" justify="center">
+ *   <Button>Action 1</Button>
+ *   <Button>Action 2</Button>
+ *   <Button>Action 3</Button>
+ * </Cluster>
+ */
+interface ClusterProps extends Partial<ComponentProps$1>, Omit<React$1.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Gap between items.
+     * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+     * @default 'sm'
+     */
+    gap?: SpacingScale;
+    /**
+     * Horizontal alignment of items.
+     * - 'start': Items at start (left in LTR)
+     * - 'center': Items centered
+     * - 'end': Items at end (right in LTR)
+     * - 'between': Space evenly between items
+     * @example
+     * <Cluster justify="center">Centered items</Cluster>
+     */
+    justify?: "start" | "center" | "end" | "between";
+    /**
+     * Vertical alignment of items.
+     * - 'start': Align to top
+     * - 'center': Vertically centered
+     * - 'end': Align to bottom
+     * - 'baseline': Align baselines (good for text)
+     * @example
+     * <Cluster align="baseline">Baseline-aligned text</Cluster>
+     */
+    align?: "start" | "center" | "end" | "baseline";
+    /**
+     * Polymorphic element type to render.
+     * @default 'div'
+     */
+    as?: ClusterElement;
+    /**
+     * Additional CSS classes to apply.
+     */
+    className?: string;
+    /**
+     * Children elements to render inside the Cluster.
+     */
+    children?: React$1.ReactNode;
+}
+
+/**
+ * Cluster - A wrapping flex layout primitive for inline groups.
+ *
+ * Cluster provides a flexible layout for inline content that wraps naturally,
+ * perfect for tags, badges, button groups, navigation links, or any inline
+ * content that needs to flow and wrap responsively.
+ *
+ * ## Key Features
+ * - **Auto-Wrapping**: Items wrap to next line when container is full
+ * - **Fluid Spacing**: Responsive gap using CSS clamp()
+ * - **Semantic Naming**: Clear intent for inline grouped content
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * ## Use Cases
+ * - Tag clouds and keyword lists
+ * - Button groups with wrapping
+ * - Navigation breadcrumbs
+ * - Badge clusters
+ * - Inline action groups
+ *
+ * @example
+ * // Tag cloud
+ * <Cluster gap="sm" justify="center">
+ *   <Tag>React</Tag>
+ *   <Tag>TypeScript</Tag>
+ *   <Tag>CSS</Tag>
+ * </Cluster>
+ *
+ * @example
+ * // Button group
+ * <Cluster gap="md">
+ *   <Button>Action 1</Button>
+ *   <Button>Action 2</Button>
+ *   <Button>Action 3</Button>
+ * </Cluster>
+ *
+ * @see {@link ClusterProps} for complete props documentation
+ */
+declare const Cluster: React$1.ForwardRefExoticComponent<ClusterProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Number of columns in the grid (1-12)
+ */
+type GridColumns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Grid auto-fit/auto-fill behavior
+ */
+type GridAuto = "fit" | "fill";
+/**
+ * Props for the Grid component
+ *
+ * Grid provides a CSS Grid-based layout primitive for responsive multi-column layouts.
+ * Supports explicit column counts, auto-fit/auto-fill, gap spacing, and alignment control.
+ *
+ * @example
+ * ```tsx
+ * // 3-column grid
+ * <Grid columns={3} gap="md">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ *   <Grid.Item>Card 3</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Auto-fit grid with minimum column width
+ * <Grid auto="fit" minColumnWidth="15rem" gap="lg">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid with custom column spans
+ * <Grid columns={12} gap="md">
+ *   <Grid.Item span={8}>Main content</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar</Grid.Item>
+ * </Grid>
+ * ```
+ */
+interface GridProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Number of columns in the grid (1-12)
+     *
+     * Creates an explicit column layout with equal-width columns.
+     * Mutually exclusive with `auto` prop.
+     *
+     * @default 1
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3}>
+     *   <div>Column 1</div>
+     *   <div>Column 2</div>
+     *   <div>Column 3</div>
+     * </Grid>
+     * ```
+     */
+    columns?: GridColumns;
+    /**
+     * Auto-fit or auto-fill behavior
+     *
+     * - `fit`: Columns expand to fill available space (grid-template-columns: repeat(auto-fit, ...))
+     * - `fill`: Creates as many columns as fit, even if empty (repeat(auto-fill, ...))
+     *
+     * Requires `minColumnWidth` to be set. Mutually exclusive with `columns` prop.
+     *
+     * @example
+     * ```tsx
+     * <Grid auto="fit" minColumnWidth="15rem" gap="md">
+     *   <div>Item 1</div>
+     *   <div>Item 2</div>
+     *   <div>Item 3</div>
+     * </Grid>
+     * ```
+     */
+    auto?: GridAuto;
+    /**
+     * Minimum column width for auto-fit/auto-fill grids
+     *
+     * Must be specified in rem units (e.g., "15rem", "20rem").
+     * Used with `auto` prop to create responsive grids without media queries.
+     *
+     * @example
+     * ```tsx
+     * <Grid auto="fit" minColumnWidth="15rem">
+     *   <div>Card</div>
+     * </Grid>
+     * ```
+     */
+    minColumnWidth?: string;
+    /**
+     * Gap spacing between grid items
+     *
+     * Uses the unified spacing scale from globals.
+     *
+     * @default undefined (uses default `.grid` gap)
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3} gap="md">
+     *   <div>Item 1</div>
+     *   <div>Item 2</div>
+     * </Grid>
+     * ```
+     */
+    gap?: SpacingScale;
+    /**
+     * Horizontal gap spacing (column gap)
+     *
+     * Overrides `gap` for horizontal spacing only.
+     * Uses the unified spacing scale.
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3} gapX="lg" gapY="sm">
+     *   <div>Item 1</div>
+     *   <div>Item 2</div>
+     * </Grid>
+     * ```
+     */
+    gapX?: SpacingScale;
+    /**
+     * Vertical gap spacing (row gap)
+     *
+     * Overrides `gap` for vertical spacing only.
+     * Uses the unified spacing scale.
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3} gapX="lg" gapY="sm">
+     *   <div>Item 1</div>
+     *   <div>Item 2</div>
+     * </Grid>
+     * ```
+     */
+    gapY?: SpacingScale;
+    /**
+     * Horizontal alignment of grid items (justify-items)
+     *
+     * Controls horizontal alignment of items within their grid cells.
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3} justifyItems="center">
+     *   <div>Centered item</div>
+     * </Grid>
+     * ```
+     */
+    justifyItems?: "start" | "center" | "end" | "stretch";
+    /**
+     * Vertical alignment of grid items (align-items)
+     *
+     * Controls vertical alignment of items within their grid cells.
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3} alignItems="center">
+     *   <div>Vertically centered</div>
+     * </Grid>
+     * ```
+     */
+    alignItems?: "start" | "center" | "end" | "stretch";
+    /**
+     * HTML element to render as
+     *
+     * @default "div"
+     *
+     * @example
+     * ```tsx
+     * <Grid as="section" columns={2}>
+     *   <article>Post 1</article>
+     *   <article>Post 2</article>
+     * </Grid>
+     * ```
+     */
+    as?: GridElement;
+    /**
+     * Additional CSS class name(s)
+     *
+     * @example
+     * ```tsx
+     * <Grid className="custom-grid" columns={3}>
+     *   <div>Item</div>
+     * </Grid>
+     * ```
+     */
+    className?: string;
+    /**
+     * Additional CSS class name(s) (alternative to className)
+     *
+     * @example
+     * ```tsx
+     * <Grid classes="utility-class" columns={3}>
+     *   <div>Item</div>
+     * </Grid>
+     * ```
+     */
+    classes?: string;
+    /**
+     * Children elements (typically Grid.Item components)
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3}>
+     *   <Grid.Item>Item 1</Grid.Item>
+     *   <Grid.Item span={2}>Item 2 (2 columns wide)</Grid.Item>
+     * </Grid>
+     * ```
+     */
+    children?: React.ReactNode;
+}
+/**
+ * Props for the Grid.Item component
+ *
+ * Grid.Item represents a single item within a Grid layout.
+ * Supports column span control for flexible grid layouts.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={12}>
+ *   <Grid.Item span={8}>Main content (8/12)</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar (4/12)</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={4}>
+ *   <Grid.Item>1 column</Grid.Item>
+ *   <Grid.Item span={2}>2 columns</Grid.Item>
+ *   <Grid.Item>1 column</Grid.Item>
+ * </Grid>
+ * ```
+ */
+interface GridItemProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Number of columns this item should span (1-12)
+     *
+     * Determines the width of the grid item relative to the parent grid's columns.
+     *
+     * @default 1
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={12}>
+     *   <Grid.Item span={6}>Half width</Grid.Item>
+     *   <Grid.Item span={6}>Half width</Grid.Item>
+     * </Grid>
+     * ```
+     */
+    span?: GridColumns;
+    /**
+     * Row span for the grid item
+     *
+     * Determines how many rows this item should span.
+     *
+     * @example
+     * ```tsx
+     * <Grid columns={3}>
+     *   <Grid.Item rowSpan={2}>Tall item</Grid.Item>
+     *   <Grid.Item>Normal</Grid.Item>
+     *   <Grid.Item>Normal</Grid.Item>
+     * </Grid>
+     * ```
+     */
+    rowSpan?: number;
+    /**
+     * HTML element to render as
+     *
+     * @default "div"
+     *
+     * @example
+     * ```tsx
+     * <Grid as="ul" columns={3}>
+     *   <Grid.Item as="li">List item 1</Grid.Item>
+     *   <Grid.Item as="li">List item 2</Grid.Item>
+     * </Grid>
+     * ```
+     */
+    as?: GridItemElement;
+    /**
+     * Additional CSS class name(s)
+     *
+     * @example
+     * ```tsx
+     * <Grid.Item className="featured" span={2}>
+     *   Featured content
+     * </Grid.Item>
+     * ```
+     */
+    className?: string;
+    /**
+     * Additional CSS class name(s) (alternative to className)
+     *
+     * @example
+     * ```tsx
+     * <Grid.Item classes="utility-class" span={3}>
+     *   Content
+     * </Grid.Item>
+     * ```
+     */
+    classes?: string;
+    /**
+     * Children elements
+     *
+     * @example
+     * ```tsx
+     * <Grid.Item span={2}>
+     *   <h2>Title</h2>
+     *   <p>Content</p>
+     * </Grid.Item>
+     * ```
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Grid.Item - A grid item component with column and row span control.
+ *
+ * Grid.Item represents a single item within a Grid layout. It supports
+ * column spanning (1-12 columns) and row spanning for flexible grid layouts.
+ *
+ * ## Key Features
+ * - **Column Span**: Span 1-12 columns
+ * - **Row Span**: Span multiple rows
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * @example
+ * // Span 2 columns
+ * <Grid.Item span={2}>Wide item</Grid.Item>
+ *
+ * @example
+ * // Span 2 rows
+ * <Grid.Item rowSpan={2}>Tall item</Grid.Item>
+ *
+ * @example
+ * // Main content + sidebar layout
+ * <Grid columns={12} gap="md">
+ *   <Grid.Item span={8}>Main content</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar</Grid.Item>
+ * </Grid>
+ *
+ * @see {@link GridItemProps} for complete props documentation
+ */
+declare const GridItem: React$1.ForwardRefExoticComponent<GridItemProps & React$1.RefAttributes<HTMLElement>>;
+declare const GridWithItem: React$1.ForwardRefExoticComponent<GridProps & React$1.RefAttributes<HTMLElement>> & {
+    Item: typeof GridItem;
+};
+
 /**
  * Type definitions for Flex container components
  * Supports responsive flexbox layouts with CSS custom properties
@@ -1302,4 +2221,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, FP as Box, Caption, ComponentProps$1 as ComponentProps, Details, FP, Flex, FlexAlign, FlexAlignContent, FlexAlignSelf, FlexContainerElement, FlexDirection, FlexGap, FlexItemElement, FlexItemProps, FlexJustify, FlexProps, FlexSpacerProps, FlexVariant, FlexWrap, Footer, Header, Img, ImgProps, Landmarks, Main, ResponsiveFlexProps, Section, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Cluster, ClusterProps, ComponentProps$1 as ComponentProps, Details, FP, Flex, FlexAlign, FlexAlignContent, FlexAlignSelf, FlexContainerElement, FlexDirection, FlexGap, FlexItemElement, FlexItemProps, FlexJustify, FlexProps, FlexSpacerProps, FlexVariant, FlexWrap, Footer, GridWithItem as Grid, GridItem, GridItemProps, GridProps, Header, Img, ImgProps, Landmarks, Main, ResponsiveFlexProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };