@fpkit/acss 3.2.1 → 3.4.0

package/libs/index.d.cts

@@ -611,6 +611,38 @@ type GridElement = "div" | "section" | "article" | "ul" | "ol";
  * Semantic HTML element types for Grid.Item sub-component
  */
 type GridItemElement = "div" | "section" | "article" | "li";
+/**
+ * Semantic HTML element types for Row component
+ */
+type RowElement = "div" | "section" | "article" | "ul" | "ol" | "nav";
+/**
+ * Semantic HTML element types for Col component
+ */
+type ColElement = "div" | "section" | "article" | "li";
+/**
+ * Column span values (1-12 columns)
+ */
+type ColumnSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Column offset values (0-11 columns)
+ */
+type ColumnOffset = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+/**
+ * Column order values
+ */
+type ColumnOrder = "first" | "last" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Flex justify-content values
+ */
+type JustifyContent = "start" | "center" | "end" | "between" | "around" | "evenly";
+/**
+ * Flex align-items values
+ */
+type AlignItems = "start" | "center" | "end" | "baseline" | "stretch";
+/**
+ * Flex wrap values
+ */
+type FlexWrap$1 = "wrap" | "nowrap" | "wrap-reverse";
 
 /**
  * Props for the Box component - a fundamental container primitive for spacing and sizing control.
@@ -1496,6 +1528,248 @@ declare const GridWithItem: React$1.ForwardRefExoticComponent<GridProps & React$
     Item: typeof GridItem;
 };
 
+/**
+ * Props for the Row component
+ *
+ * Row provides a flex container for column layouts with customizable gap,
+ * justify, align, and wrap properties. Always renders with the .col-row
+ * base class and adds variant utilities based on props.
+ *
+ * @example
+ * // Basic row with default settings
+ * <Row>
+ *   <Col span={6}>Column 1</Col>
+ *   <Col span={6}>Column 2</Col>
+ * </Row>
+ *
+ * @example
+ * // Custom gap and centering
+ * <Row gap="lg" justify="center" align="center">
+ *   <Col span={4}>Centered content</Col>
+ * </Row>
+ */
+interface RowProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Gap size between columns
+     * Maps to --spacing-* CSS custom properties
+     * @default undefined (uses .col-row default gap)
+     */
+    gap?: SpacingScale;
+    /**
+     * Horizontal alignment of columns (justify-content)
+     * @default undefined (flex-start)
+     */
+    justify?: JustifyContent;
+    /**
+     * Vertical alignment of columns (align-items)
+     * @default undefined (stretch)
+     */
+    align?: AlignItems;
+    /**
+     * Flex wrap behavior
+     * @default "wrap"
+     */
+    wrap?: FlexWrap$1;
+    /**
+     * When true, columns maintain their proportional layout on tablets and larger
+     * instead of stacking to 100% width on all mobile devices (< 768px).
+     *
+     * Wrapping behavior with this prop:
+     * - Mobile phones (< 480px): Columns still stack at 100% width
+     * - Tablets & larger (≥ 480px): Columns maintain proportional layout
+     *
+     * Use this when you want columns to stay side-by-side on tablets and desktops
+     * but still provide mobile-friendly stacking on phones.
+     *
+     * @default false
+     * @example
+     * <Row alwaysProportional>
+     *   <Col span={6}>Column 1</Col>
+     *   <Col span={6}>Column 2</Col>
+     * </Row>
+     */
+    alwaysProportional?: boolean;
+    /**
+     * Element type to render
+     * @default "div"
+     */
+    as?: RowElement;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Child elements (typically Col components)
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Row - A flex container component for 12-column layouts.
+ *
+ * Row provides a type-safe React wrapper around the .col-row utility class,
+ * allowing developers to create responsive column layouts with customizable
+ * gap, alignment, and wrapping behavior. Always includes the .col-row base
+ * class and adds variant utilities based on props.
+ *
+ * ## Key Features
+ * - **Flex Container**: Display flex with wrap enabled by default
+ * - **Customizable Gap**: Control spacing between columns with gap prop
+ * - **Alignment Control**: Justify and align props for layout control
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support with literal types
+ *
+ * ## Use Cases
+ * - Multi-column layouts
+ * - Responsive grid systems
+ * - Card grids
+ * - Dashboard layouts
+ * - Form layouts
+ *
+ * @example
+ * // Basic two-column layout
+ * <Row>
+ *   <Col span={6}>Left column</Col>
+ *   <Col span={6}>Right column</Col>
+ * </Row>
+ *
+ * @example
+ * // Custom gap and centered alignment
+ * <Row gap="lg" justify="center" align="center">
+ *   <Col span={4}>Column 1</Col>
+ *   <Col span={4}>Column 2</Col>
+ *   <Col span={4}>Column 3</Col>
+ * </Row>
+ *
+ * @example
+ * // Semantic HTML with list elements
+ * <Row as="ul" gap="md">
+ *   <Col as="li" span={4}>Item 1</Col>
+ *   <Col as="li" span={4}>Item 2</Col>
+ *   <Col as="li" span={4}>Item 3</Col>
+ * </Row>
+ *
+ * @example
+ * // Proportional layout - maintains columns on tablets and larger
+ * <Row alwaysProportional gap="lg">
+ *   <Col span={6}>Column 1 (50% on tablets+)</Col>
+ *   <Col span={6}>Column 2 (50% on tablets+)</Col>
+ * </Row>
+ *
+ * @see {@link RowProps} for complete props documentation
+ */
+declare const Row: React$1.ForwardRefExoticComponent<RowProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Props for the Col component
+ *
+ * Col provides a column element for use within Row containers. Maps React
+ * props to column utility classes (.col-*, .col-offset-*, .col-order-*,
+ * .col-auto) without a base class. Pure utility class composition.
+ *
+ * @example
+ * // Basic column with 50% width
+ * <Col span={6}>Column content</Col>
+ *
+ * @example
+ * // Column with offset and order
+ * <Col span={4} offset={2} order={1}>
+ *   Offset and reordered
+ * </Col>
+ */
+interface ColProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Column span (1-12)
+     * Maps to .col-{span} utility class
+     * Ignored if auto is true
+     * @default undefined
+     */
+    span?: ColumnSpan;
+    /**
+     * Column offset (0-11)
+     * Pushes column to the right using margin-inline-start
+     * Maps to .col-offset-{offset} utility class
+     * @default undefined
+     */
+    offset?: ColumnOffset;
+    /**
+     * Column order
+     * Controls visual order using flexbox order property
+     * Maps to .col-order-{order} utility class
+     * @default undefined
+     */
+    order?: ColumnOrder;
+    /**
+     * Auto-width column
+     * When true, uses .col-auto (content-based width)
+     * Takes precedence over span prop
+     * @default false
+     */
+    auto?: boolean;
+    /**
+     * Element type to render
+     * @default "div"
+     */
+    as?: ColElement;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Child elements
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Col - A column component for 12-column layouts.
+ *
+ * Col provides a type-safe React wrapper around column utility classes,
+ * allowing developers to create responsive columns with span, offset, order,
+ * and auto-width options. Unlike Row, Col has no base class - it's pure
+ * utility class composition.
+ *
+ * ## Key Features
+ * - **No base class**: Pure utility class mapping (follows Grid.Item pattern)
+ * - **Span control**: 1-12 column widths via span prop
+ * - **Offset positioning**: Push columns right with offset prop
+ * - **Visual reordering**: Change order with order prop
+ * - **Auto-width**: Content-based width with auto prop
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support with literal types
+ *
+ * ## Use Cases
+ * - Responsive column layouts
+ * - Grid-based designs
+ * - Content positioning
+ * - Visual reordering
+ *
+ * @example
+ * // Basic 50% column
+ * <Col span={6}>Half width column</Col>
+ *
+ * @example
+ * // Centered column with offset
+ * <Col span={6} offset={3}>Centered column</Col>
+ *
+ * @example
+ * // Auto-width column
+ * <Col auto>Content-based width</Col>
+ *
+ * @example
+ * // Reordered column
+ * <Col span={6} order="first">Appears first visually</Col>
+ *
+ * @example
+ * // Semantic HTML
+ * <Row as="ul">
+ *   <Col as="li" span={4}>List item</Col>
+ * </Row>
+ *
+ * @see {@link ColProps} for complete props documentation
+ */
+declare const Col: React$1.ForwardRefExoticComponent<ColProps & React$1.RefAttributes<HTMLElement>>;
+
 /**
  * Type definitions for Flex container components
  * Supports responsive flexbox layouts with CSS custom properties
@@ -2221,4 +2495,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-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 };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Cluster, ClusterProps, Col, ColProps, 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, Row, RowProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };

package/libs/index.d.ts

@@ -611,6 +611,38 @@ type GridElement = "div" | "section" | "article" | "ul" | "ol";
  * Semantic HTML element types for Grid.Item sub-component
  */
 type GridItemElement = "div" | "section" | "article" | "li";
+/**
+ * Semantic HTML element types for Row component
+ */
+type RowElement = "div" | "section" | "article" | "ul" | "ol" | "nav";
+/**
+ * Semantic HTML element types for Col component
+ */
+type ColElement = "div" | "section" | "article" | "li";
+/**
+ * Column span values (1-12 columns)
+ */
+type ColumnSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Column offset values (0-11 columns)
+ */
+type ColumnOffset = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+/**
+ * Column order values
+ */
+type ColumnOrder = "first" | "last" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Flex justify-content values
+ */
+type JustifyContent = "start" | "center" | "end" | "between" | "around" | "evenly";
+/**
+ * Flex align-items values
+ */
+type AlignItems = "start" | "center" | "end" | "baseline" | "stretch";
+/**
+ * Flex wrap values
+ */
+type FlexWrap$1 = "wrap" | "nowrap" | "wrap-reverse";
 
 /**
  * Props for the Box component - a fundamental container primitive for spacing and sizing control.
@@ -1496,6 +1528,248 @@ declare const GridWithItem: React$1.ForwardRefExoticComponent<GridProps & React$
     Item: typeof GridItem;
 };
 
+/**
+ * Props for the Row component
+ *
+ * Row provides a flex container for column layouts with customizable gap,
+ * justify, align, and wrap properties. Always renders with the .col-row
+ * base class and adds variant utilities based on props.
+ *
+ * @example
+ * // Basic row with default settings
+ * <Row>
+ *   <Col span={6}>Column 1</Col>
+ *   <Col span={6}>Column 2</Col>
+ * </Row>
+ *
+ * @example
+ * // Custom gap and centering
+ * <Row gap="lg" justify="center" align="center">
+ *   <Col span={4}>Centered content</Col>
+ * </Row>
+ */
+interface RowProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Gap size between columns
+     * Maps to --spacing-* CSS custom properties
+     * @default undefined (uses .col-row default gap)
+     */
+    gap?: SpacingScale;
+    /**
+     * Horizontal alignment of columns (justify-content)
+     * @default undefined (flex-start)
+     */
+    justify?: JustifyContent;
+    /**
+     * Vertical alignment of columns (align-items)
+     * @default undefined (stretch)
+     */
+    align?: AlignItems;
+    /**
+     * Flex wrap behavior
+     * @default "wrap"
+     */
+    wrap?: FlexWrap$1;
+    /**
+     * When true, columns maintain their proportional layout on tablets and larger
+     * instead of stacking to 100% width on all mobile devices (< 768px).
+     *
+     * Wrapping behavior with this prop:
+     * - Mobile phones (< 480px): Columns still stack at 100% width
+     * - Tablets & larger (≥ 480px): Columns maintain proportional layout
+     *
+     * Use this when you want columns to stay side-by-side on tablets and desktops
+     * but still provide mobile-friendly stacking on phones.
+     *
+     * @default false
+     * @example
+     * <Row alwaysProportional>
+     *   <Col span={6}>Column 1</Col>
+     *   <Col span={6}>Column 2</Col>
+     * </Row>
+     */
+    alwaysProportional?: boolean;
+    /**
+     * Element type to render
+     * @default "div"
+     */
+    as?: RowElement;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Child elements (typically Col components)
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Row - A flex container component for 12-column layouts.
+ *
+ * Row provides a type-safe React wrapper around the .col-row utility class,
+ * allowing developers to create responsive column layouts with customizable
+ * gap, alignment, and wrapping behavior. Always includes the .col-row base
+ * class and adds variant utilities based on props.
+ *
+ * ## Key Features
+ * - **Flex Container**: Display flex with wrap enabled by default
+ * - **Customizable Gap**: Control spacing between columns with gap prop
+ * - **Alignment Control**: Justify and align props for layout control
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support with literal types
+ *
+ * ## Use Cases
+ * - Multi-column layouts
+ * - Responsive grid systems
+ * - Card grids
+ * - Dashboard layouts
+ * - Form layouts
+ *
+ * @example
+ * // Basic two-column layout
+ * <Row>
+ *   <Col span={6}>Left column</Col>
+ *   <Col span={6}>Right column</Col>
+ * </Row>
+ *
+ * @example
+ * // Custom gap and centered alignment
+ * <Row gap="lg" justify="center" align="center">
+ *   <Col span={4}>Column 1</Col>
+ *   <Col span={4}>Column 2</Col>
+ *   <Col span={4}>Column 3</Col>
+ * </Row>
+ *
+ * @example
+ * // Semantic HTML with list elements
+ * <Row as="ul" gap="md">
+ *   <Col as="li" span={4}>Item 1</Col>
+ *   <Col as="li" span={4}>Item 2</Col>
+ *   <Col as="li" span={4}>Item 3</Col>
+ * </Row>
+ *
+ * @example
+ * // Proportional layout - maintains columns on tablets and larger
+ * <Row alwaysProportional gap="lg">
+ *   <Col span={6}>Column 1 (50% on tablets+)</Col>
+ *   <Col span={6}>Column 2 (50% on tablets+)</Col>
+ * </Row>
+ *
+ * @see {@link RowProps} for complete props documentation
+ */
+declare const Row: React$1.ForwardRefExoticComponent<RowProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Props for the Col component
+ *
+ * Col provides a column element for use within Row containers. Maps React
+ * props to column utility classes (.col-*, .col-offset-*, .col-order-*,
+ * .col-auto) without a base class. Pure utility class composition.
+ *
+ * @example
+ * // Basic column with 50% width
+ * <Col span={6}>Column content</Col>
+ *
+ * @example
+ * // Column with offset and order
+ * <Col span={4} offset={2} order={1}>
+ *   Offset and reordered
+ * </Col>
+ */
+interface ColProps extends Partial<ComponentProps$1>, Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Column span (1-12)
+     * Maps to .col-{span} utility class
+     * Ignored if auto is true
+     * @default undefined
+     */
+    span?: ColumnSpan;
+    /**
+     * Column offset (0-11)
+     * Pushes column to the right using margin-inline-start
+     * Maps to .col-offset-{offset} utility class
+     * @default undefined
+     */
+    offset?: ColumnOffset;
+    /**
+     * Column order
+     * Controls visual order using flexbox order property
+     * Maps to .col-order-{order} utility class
+     * @default undefined
+     */
+    order?: ColumnOrder;
+    /**
+     * Auto-width column
+     * When true, uses .col-auto (content-based width)
+     * Takes precedence over span prop
+     * @default false
+     */
+    auto?: boolean;
+    /**
+     * Element type to render
+     * @default "div"
+     */
+    as?: ColElement;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Child elements
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Col - A column component for 12-column layouts.
+ *
+ * Col provides a type-safe React wrapper around column utility classes,
+ * allowing developers to create responsive columns with span, offset, order,
+ * and auto-width options. Unlike Row, Col has no base class - it's pure
+ * utility class composition.
+ *
+ * ## Key Features
+ * - **No base class**: Pure utility class mapping (follows Grid.Item pattern)
+ * - **Span control**: 1-12 column widths via span prop
+ * - **Offset positioning**: Push columns right with offset prop
+ * - **Visual reordering**: Change order with order prop
+ * - **Auto-width**: Content-based width with auto prop
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support with literal types
+ *
+ * ## Use Cases
+ * - Responsive column layouts
+ * - Grid-based designs
+ * - Content positioning
+ * - Visual reordering
+ *
+ * @example
+ * // Basic 50% column
+ * <Col span={6}>Half width column</Col>
+ *
+ * @example
+ * // Centered column with offset
+ * <Col span={6} offset={3}>Centered column</Col>
+ *
+ * @example
+ * // Auto-width column
+ * <Col auto>Content-based width</Col>
+ *
+ * @example
+ * // Reordered column
+ * <Col span={6} order="first">Appears first visually</Col>
+ *
+ * @example
+ * // Semantic HTML
+ * <Row as="ul">
+ *   <Col as="li" span={4}>List item</Col>
+ * </Row>
+ *
+ * @see {@link ColProps} for complete props documentation
+ */
+declare const Col: React$1.ForwardRefExoticComponent<ColProps & React$1.RefAttributes<HTMLElement>>;
+
 /**
  * Type definitions for Flex container components
  * Supports responsive flexbox layouts with CSS custom properties
@@ -2221,4 +2495,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-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 };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Cluster, ClusterProps, Col, ColProps, 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, Row, RowProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };