@vaneui/ui 0.3.1-alpha.20251130172447.8795285 → 0.3.1-alpha.20251201144940.b3e097b

package/dist/index.esm.js

@@ -9,99 +9,6 @@ import { createContext, useContext, useMemo, forwardRef } from 'react';
 class BaseTheme {
 }
 
-/** All appearance property values */
-const APPEARANCE_VALUES = ['default', 'accent', 'primary', 'secondary', 'tertiary', 'success', 'danger', 'warning', 'info', 'link'];
-
-/** Hide border - removes border styling (overrides appearance colors) */
-const NO_BORDER = 'noBorder';
-/** All border property values - includes all border variations and noBorder */
-const BORDER_VALUES = ['border', 'borderT', 'borderB', 'borderL', 'borderR', 'borderX', 'borderY', 'noBorder'];
-/** All border side keys (excluding noBorder since it doesn't have a CSS class) */
-const BORDER_KEYS = ['border', 'borderT', 'borderB', 'borderL', 'borderR', 'borderX', 'borderY'];
-
-/** All breakpoint property values */
-const BREAKPOINT_VALUES = ['mobileCol', 'tabletCol', 'laptopCol', 'desktopCol'];
-
-/** All display property values */
-const DISPLAY_VALUES = ['inline', 'block', 'inlineBlock', 'flex', 'inlineFlex', 'grid', 'inlineGrid', 'contents', 'table', 'tableCell', 'hidden'];
-
-/** All flex direction property values */
-const FLEX_DIRECTION_VALUES = ['row', 'column', 'rowReverse', 'columnReverse'];
-
-/** All font family property values */
-const FONT_FAMILY_VALUES = ['sans', 'serif', 'mono'];
-
-/** All font style property values */
-const FONT_STYLE_VALUES = ['italic', 'notItalic'];
-
-/** All font weight property values */
-const FONT_WEIGHT_VALUES = ['thin', 'extralight', 'light', 'normal', 'medium', 'semibold', 'bold', 'extrabold', 'black'];
-
-/** All gap property values */
-const GAP_VALUES = ['gap', 'noGap'];
-
-/** All hide property values */
-const HIDE_VALUES = ['mobileHide', 'tabletHide', 'laptopHide', 'desktopHide'];
-
-/** All items property values */
-const ITEMS_VALUES = ['itemsStart', 'itemsEnd', 'itemsCenter', 'itemsBaseline', 'itemsStretch'];
-
-/** All justify property values */
-const JUSTIFY_VALUES = ['justifyStart', 'justifyEnd', 'justifyCenter', 'justifyBetween', 'justifyAround', 'justifyEvenly', 'justifyStretch', 'justifyBaseline'];
-
-/** All list style property values */
-const LIST_STYLE_VALUES = ['disc', 'decimal'];
-
-/** All overflow property values */
-const OVERFLOW_VALUES = [
-    'overflowAuto', 'overflowHidden', 'overflowClip', 'overflowVisible', 'overflowScroll',
-    'overflowXAuto', 'overflowYAuto', 'overflowXHidden', 'overflowYHidden',
-    'overflowXClip', 'overflowYClip', 'overflowXVisible', 'overflowYVisible',
-    'overflowXScroll', 'overflowYScroll'
-];
-
-/** All padding property values */
-const PADDING_VALUES = ['padding', 'noPadding'];
-
-/** All position property values */
-const POSITION_VALUES = ['relative', 'absolute', 'fixed', 'sticky', 'static'];
-
-/** All reverse property values */
-const REVERSE_VALUES = ['reverse'];
-
-/** All ring property values */
-const RING_VALUES = ['ring', 'noRing'];
-
-/** All shadow property values */
-const SHADOW_VALUES = ['shadow', 'noShadow'];
-
-/** All focusVisible property values */
-const FOCUS_VISIBLE_VALUES = ['focusVisible', 'noFocusVisible'];
-
-/** All shape property values */
-const SHAPE_VALUES = ['pill', 'sharp', 'rounded'];
-
-/** All size property values */
-const SIZE_VALUES = ['xs', 'sm', 'md', 'lg', 'xl'];
-
-/** All text align property values */
-const TEXT_ALIGN_VALUES = ['textLeft', 'textCenter', 'textRight', 'textJustify'];
-
-/** All text decoration property values */
-const TEXT_DECORATION_VALUES = ['underline', 'lineThrough', 'noUnderline', 'overline'];
-
-/** All text transform property values */
-const TEXT_TRANSFORM_VALUES = ['uppercase', 'lowercase', 'capitalize', 'normalCase'];
-
-/** All transparent property values */
-const TRANSPARENT_VALUES = ['transparent'];
-
-/** All variant property values */
-const VARIANT_VALUES = ['filled', 'outline'];
-
-/** All wrap property values */
-const WRAP_VALUES = ['flexWrap', 'flexNoWrap', 'flexWrapReverse'];
-
 /** Base state - default resting appearance */
 const BASE = 'base';
 /** Hover state - appearance when cursor hovers over element */
@@ -166,62 +73,69 @@ const APPEARANCE_CATEGORY = ['text', 'border', 'ring', 'shadow', 'bg', 'accent',
 /** Component property keys mapping categories to their available values */
 const ComponentKeys = {
     /** Color appearance options */
-    appearance: APPEARANCE_VALUES,
+    appearance: ['default', 'accent', 'primary', 'secondary', 'tertiary', 'success', 'danger', 'warning', 'info', 'link'],
     /** Border visibility: includes all border variations and noBorder (border, borderT, borderB, etc., noBorder) */
-    border: BORDER_VALUES,
+    border: ['border', 'borderT', 'borderB', 'borderL', 'borderR', 'borderX', 'borderY', 'noBorder'],
     /** Column breakpoints for responsive grid layouts */
-    breakpoint: BREAKPOINT_VALUES,
+    breakpoint: ['mobileCol', 'tabletCol', 'laptopCol', 'desktopCol'],
     /** CSS display property values for element layout behavior */
-    display: DISPLAY_VALUES,
+    display: ['inline', 'block', 'inlineBlock', 'flex', 'inlineFlex', 'grid', 'inlineGrid', 'contents', 'table', 'tableCell', 'hidden'],
     /** Flex direction: row (horizontal), column (vertical), or reversed variants */
-    flexDirection: FLEX_DIRECTION_VALUES,
+    flexDirection: ['row', 'column', 'rowReverse', 'columnReverse'],
     /** Font family types: sans-serif, serif, or monospace */
-    fontFamily: FONT_FAMILY_VALUES,
+    fontFamily: ['sans', 'serif', 'mono'],
     /** Font style: italic or notItalic (normal) */
-    fontStyle: FONT_STYLE_VALUES,
+    fontStyle: ['italic', 'notItalic'],
     /** Font weight from thin (100) to black (900) */
-    fontWeight: FONT_WEIGHT_VALUES,
+    fontWeight: ['thin', 'extralight', 'light', 'normal', 'medium', 'semibold', 'bold', 'extrabold', 'black'],
     /** Spacing between flex/grid items: gap (enabled) or noGap (disabled) */
-    gap: GAP_VALUES,
+    gap: ['gap', 'noGap'],
     /** Hide elements at specific breakpoint sizes */
-    hide: HIDE_VALUES,
+    hide: ['mobileHide', 'tabletHide', 'laptopHide', 'desktopHide'],
     /** Cross-axis alignment for flex items (align-items) */
-    items: ITEMS_VALUES,
+    items: ['itemsStart', 'itemsEnd', 'itemsCenter', 'itemsBaseline', 'itemsStretch'],
     /** Main-axis alignment for flex items (justify-content) */
-    justify: JUSTIFY_VALUES,
+    justify: ['justifyStart', 'justifyEnd', 'justifyCenter', 'justifyBetween', 'justifyAround', 'justifyEvenly', 'justifyStretch', 'justifyBaseline'],
     /** List bullet/numbering style: disc (bullets) or decimal (numbers) */
-    listStyle: LIST_STYLE_VALUES,
+    listStyle: ['disc', 'decimal'],
     /** Overflow behavior for content that exceeds container bounds */
-    overflow: OVERFLOW_VALUES,
+    overflow: [
+        'overflowAuto', 'overflowHidden', 'overflowClip', 'overflowVisible', 'overflowScroll',
+        'overflowXAuto', 'overflowYAuto', 'overflowXHidden', 'overflowYHidden',
+        'overflowXClip', 'overflowYClip', 'overflowXVisible', 'overflowYVisible',
+        'overflowXScroll', 'overflowYScroll'
+    ],
     /** Internal spacing: padding (enabled) or noPadding (disabled) */
-    padding: PADDING_VALUES,
+    padding: ['padding', 'noPadding'],
     /** CSS positioning: relative, absolute, fixed, sticky, static */
-    position: POSITION_VALUES,
+    position: ['relative', 'absolute', 'fixed', 'sticky', 'static'],
     /** Reverse the order of flex items */
-    reverse: REVERSE_VALUES,
+    reverse: ['reverse'],
     /** Focus ring visibility: ring (show) or noRing (hide) */
-    ring: RING_VALUES,
+    ring: ['ring', 'noRing'],
     /** Drop shadow visibility: shadow (enabled) or noShadow (disabled) */
-    shadow: SHADOW_VALUES,
+    shadow: ['shadow', 'noShadow'],
     /** Focus-visible outline visibility: focusVisible (show) or noFocusVisible (hide) */
-    focusVisible: FOCUS_VISIBLE_VALUES,
+    focusVisible: ['focusVisible', 'noFocusVisible'],
     /** Border radius shape: pill (fully rounded), sharp (no radius), rounded (medium radius) */
-    shape: SHAPE_VALUES,
+    shape: ['pill', 'sharp', 'rounded'],
     /** Size scale from extra-small to extra-large */
-    size: SIZE_VALUES,
+    size: ['xs', 'sm', 'md', 'lg', 'xl'],
     /** Text alignment: left, center, right, justify */
-    textAlign: TEXT_ALIGN_VALUES,
+    textAlign: ['textLeft', 'textCenter', 'textRight', 'textJustify'],
     /** Text decoration: underline, strikethrough (lineThrough), none (noUnderline), overline */
-    textDecoration: TEXT_DECORATION_VALUES,
+    textDecoration: ['underline', 'lineThrough', 'noUnderline', 'overline'],
     /** Text case transformation: UPPERCASE, lowercase, Capitalize, normalCase */
-    textTransform: TEXT_TRANSFORM_VALUES,
+    textTransform: ['uppercase', 'lowercase', 'capitalize', 'normalCase'],
     /** Make background (layout/UI) or text (typography) transparent */
-    transparent: TRANSPARENT_VALUES,
+    transparent: ['transparent'],
     /** Style variant: filled (solid background) or outline (border only) */
-    variant: VARIANT_VALUES,
+    variant: ['filled', 'outline'],
     /** Flex item wrapping behavior: wrap, no-wrap, or wrap-reverse */
-    wrap: WRAP_VALUES,
+    wrap: ['flexWrap', 'flexNoWrap', 'flexWrapReverse'],
 };
+/** All border side keys (excluding noBorder since it doesn't have a CSS class) */
+const BORDER_KEYS = ['border', 'borderT', 'borderB', 'borderL', 'borderR', 'borderX', 'borderY'];
 /** Composite categories built from core blocks */
 /** Complete layout category including core and flex properties */
 const LAYOUT_FULL = [...LAYOUT_CORE, ...LAYOUT_FLEX];
@@ -3795,11 +3709,11 @@ class AppearanceTheme extends BaseTheme {
         var _a;
         if (this.category === 'border') {
             // If noBorder is selected from the border category, don't apply appearance colors
-            if (extractedKeys.border === NO_BORDER) {
+            if (extractedKeys.border === 'noBorder') {
                 return [];
             }
             // Only apply appearance colors if any border prop is set (and not noBorder)
-            const hasBorderProps = extractedKeys.border !== undefined && extractedKeys.border !== NO_BORDER;
+            const hasBorderProps = extractedKeys.border !== undefined && extractedKeys.border !== 'noBorder';
             // If no border props are set, don't apply appearance colors
             if (!hasBorderProps) {
                 return [];
@@ -5495,31 +5409,228 @@ const ThemedComponent = forwardRef(function ThemedComponent(allProps, ref) {
     return (jsx(Tag, { ref: ref, className: finalClasses, ...finalProps, children: props.children }));
 });
 
+/**
+ * A clickable button component with customizable appearance, size, and behavior.
+ *
+ * Supports rendering as a button element or anchor tag when href is provided.
+ * Can be styled with different appearances (primary, secondary, success, etc.),
+ * sizes (xs to xl), and variants (filled, outlined, ghost).
+ *
+ * @example
+ * ```tsx
+ * // Basic button
+ * <Button>Click me</Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Primary filled button with large size
+ * <Button primary lg filled>Submit</Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button as a link
+ * <Button href="/about" secondary>About</Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Danger button with custom styling
+ * <Button danger outlined className="w-full">Delete</Button>
+ * ```
+ *
+ * @see {@link ButtonProps} for all available props
+ */
 const Button = forwardRef(function Button(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.button, ...props });
 });
 
+/**
+ * A compact badge component for displaying status, labels, or counts.
+ *
+ * Badges are typically used to highlight important information or indicate
+ * status (e.g., "New", "Beta", notification counts). Supports the same
+ * customization options as buttons including appearances, sizes, and variants.
+ *
+ * @example
+ * ```tsx
+ * // Basic badge
+ * <Badge>New</Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success badge with filled variant
+ * <Badge success filled>Active</Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Notification count badge
+ * <Badge danger pill xs>3</Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Badge as a link
+ * <Badge href="/beta" info outlined>Beta</Badge>
+ * ```
+ *
+ * @see {@link BadgeProps} for all available props
+ */
 const Badge = forwardRef(function Badge(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.badge, ref: ref, ...props });
 });
 
+/**
+ * A visual separator component for dividing content sections.
+ *
+ * Renders a horizontal line to separate content blocks. Can be styled
+ * with different appearances and sizes. Useful for creating visual
+ * hierarchy and content organization.
+ *
+ * @example
+ * ```tsx
+ * // Basic divider
+ * <Text>Section 1</Text>
+ * <Divider />
+ * <Text>Section 2</Text>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Styled divider
+ * <Divider primary lg />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Divider with padding
+ * <Divider padding />
+ * ```
+ *
+ * @see {@link DividerProps} for all available props
+ */
 const Divider = forwardRef(function Divider(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.divider, ref: ref, ...props });
 });
 
+/**
+ * A chip component for displaying tags, filters, or selections.
+ *
+ * Chips are interactive elements commonly used to represent tags, filters,
+ * or user selections. They typically appear in pill shape and can be
+ * removed or clicked. Similar to badges but more interactive in nature.
+ *
+ * @example
+ * ```tsx
+ * // Basic chip
+ * <Chip>React</Chip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Filter chip with primary color
+ * <Chip primary pill>JavaScript</Chip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Removable tag chip
+ * <Chip secondary outlined xs>TypeScript ×</Chip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Clickable chip as link
+ * <Chip href="/tag/react" accent>React</Chip>
+ * ```
+ *
+ * @see {@link ChipProps} for all available props
+ */
 const Chip = forwardRef(function Chip(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.chip, ref: ref, ...props });
 });
 
+/**
+ * An inline code component for displaying code snippets or technical terms.
+ *
+ * Renders text in a monospace font with subtle background styling to
+ * distinguish code from regular text. Ideal for inline code references,
+ * variable names, or short code snippets within paragraphs.
+ *
+ * @example
+ * ```tsx
+ * // Basic inline code
+ * <Code>const x = 10</Code>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Code with custom appearance
+ * <Code primary filled>npm install</Code>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Code block style
+ * <Code secondary outlined lg mono>function hello() {}</Code>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Code with custom styling
+ * <Code className="px-4 py-2">git commit -m "message"</Code>
+ * ```
+ *
+ * @see {@link CodeProps} for all available props
+ */
 const Code = forwardRef(function Code(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.code, ref: ref, ...props });
 });
 
+/**
+ * A styled checkbox component for forms and selections.
+ *
+ * Provides a custom-styled checkbox with checkmark visualization. Supports
+ * all standard HTML checkbox attributes (checked, onChange, disabled, etc.)
+ * and can be customized with appearances, sizes, and variants.
+ *
+ * @example
+ * ```tsx
+ * // Basic checkbox
+ * <Checkbox />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled checkbox with label
+ * <Label>
+ *   <Checkbox checked={accepted} onChange={(e) => setAccepted(e.target.checked)} />
+ *   I accept the terms
+ * </Label>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Primary checkbox with custom size
+ * <Checkbox primary lg defaultChecked />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled checkbox
+ * <Checkbox disabled checked />
+ * ```
+ *
+ * @see {@link CheckboxProps} for all available props
+ */
 const Checkbox = forwardRef(function Checkbox(props, ref) {
     const theme = useTheme();
     // Extract only theme-relevant props for wrapper and check components
@@ -5553,101 +5664,743 @@ const Checkbox = forwardRef(function Checkbox(props, ref) {
     return (jsxs(ThemedComponent, { theme: theme.checkbox.wrapper, ref: ref, ...themeProps, children: [jsx(ThemedComponent, { theme: theme.checkbox.input, ...inputProps }), jsx(ThemedComponent, { theme: theme.checkbox.check, ...themeProps, children: theme.checkbox.check.themes.checkElement() })] }));
 });
 
+/**
+ * A label component for form fields and inputs.
+ *
+ * Renders a semantic HTML label element with typography and styling support.
+ * Typically used with form inputs like Input or Checkbox to provide
+ * accessible labels. Clicking the label focuses the associated input.
+ *
+ * @example
+ * ```tsx
+ * // Basic label
+ * <Label htmlFor="email">Email Address</Label>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Label with checkbox
+ * <Label>
+ *   <Checkbox id="terms" />
+ *   I agree to the terms
+ * </Label>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Styled label with custom appearance
+ * <Label semibold primary>Username</Label>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Label with input
+ * <Label htmlFor="password" className="block mb-2">
+ *   Password
+ * </Label>
+ * <Input id="password" type="password" />
+ * ```
+ *
+ * @see {@link LabelProps} for all available props
+ */
 const Label = forwardRef(function Label(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.label, ref: ref, ...props });
 });
 
+/**
+ * An image component with styling and layout support.
+ *
+ * Wraps the HTML img element with VaneUI's styling system. Supports all
+ * standard image attributes (src, alt, width, height, etc.) plus additional
+ * props for borders, shadows, shapes, and positioning.
+ *
+ * @example
+ * ```tsx
+ * // Basic image
+ * <Img src="/photo.jpg" alt="Description" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Rounded image with border
+ * <Img src="/avatar.jpg" alt="User" pill border primary />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Image with shadow and custom size
+ * <Img src="/product.jpg" alt="Product" shadow lg />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full width responsive image
+ * <Img src="/banner.jpg" alt="Banner" className="w-full h-auto" />
+ * ```
+ *
+ * @see {@link ImgProps} for all available props
+ */
 const Img = forwardRef(function Img(props, ref) {
     const theme = useTheme();
     return (jsx(ThemedComponent, { theme: theme.img, ref: ref, ...props }));
 });
 
+/**
+ * A text input field component for forms and user data entry.
+ *
+ * Provides a styled input element with support for all standard HTML input
+ * attributes and types. Can be customized with appearances, sizes, and variants
+ * to match your design system. Supports all native input types (text, email, password, etc.).
+ *
+ * @example
+ * ```tsx
+ * // Basic text input
+ * <Input placeholder="Enter your name" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Email input with primary styling
+ * <Input type="email" primary outlined placeholder="Email address" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Large input with custom styling
+ * <Input lg className="w-full" placeholder="Search..." />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled input with state
+ * <Input value={value} onChange={(e) => setValue(e.target.value)} />
+ * ```
+ *
+ * @see {@link InputProps} for all available props
+ */
 const Input = forwardRef(function Input(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.input, ...props });
 });
 
+/**
+ * A semantic section container for grouping related content.
+ *
+ * Renders as a semantic HTML section element with generous layout spacing.
+ * Use to organize page content into logical sections. Supports responsive
+ * flex direction with breakpoint props (mobileCol, tabletCol, etc.).
+ *
+ * @example
+ * ```tsx
+ * // Basic section
+ * <Section>
+ *   <SectionTitle>About</SectionTitle>
+ *   <Text>Section content here.</Text>
+ * </Section>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Section with padding and gap
+ * <Section padding gap>
+ *   <Title>Features</Title>
+ *   <Text>Feature descriptions...</Text>
+ * </Section>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive section that stacks on tablets
+ * <Section tabletCol gap>
+ *   <Card>Card 1</Card>
+ *   <Card>Card 2</Card>
+ * </Section>
+ * ```
+ *
+ * @see {@link SectionProps} for all available props
+ */
 const Section = forwardRef(function Section(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.section, ref: ref, ...props });
 });
 
+/**
+ * A page-level content wrapper with maximum width constraints.
+ *
+ * Provides consistent horizontal padding and centers content on the page.
+ * Typically the outermost wrapper for page content. Uses layout spacing
+ * (larger gaps) for structural organization.
+ *
+ * @example
+ * ```tsx
+ * // Basic container
+ * <Container>
+ *   <PageTitle>My Page</PageTitle>
+ *   <Text>Page content goes here.</Text>
+ * </Container>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Container with custom spacing
+ * <Container lg gap>
+ *   <Section>Section 1</Section>
+ *   <Section>Section 2</Section>
+ * </Container>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-width container
+ * <Container className="max-w-none">
+ *   Wide content
+ * </Container>
+ * ```
+ *
+ * @see {@link ContainerProps} for all available props
+ */
 const Container = forwardRef(function Container(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.container, ref: ref, ...props });
 });
 
+/**
+ * A column flex container for vertical content organization.
+ *
+ * Arranges children in a column (vertical) layout with consistent spacing.
+ * Similar to Stack but without responsive breakpoints. Use for predictable
+ * vertical layouts that don't need to change based on screen size.
+ *
+ * @example
+ * ```tsx
+ * // Basic column
+ * <Col gap>
+ *   <Title>Column Content</Title>
+ *   <Text>First paragraph</Text>
+ *   <Text>Second paragraph</Text>
+ * </Col>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Column with centered items
+ * <Col itemsCenter justifyCenter gap>
+ *   <Badge>Status</Badge>
+ *   <Button>Action</Button>
+ * </Col>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-height column
+ * <Col className="h-screen" justifyBetween>
+ *   <header>Header</header>
+ *   <main>Main Content</main>
+ *   <footer>Footer</footer>
+ * </Col>
+ * ```
+ *
+ * @see {@link ColProps} for all available props
+ */
 const Col = forwardRef(function Col(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.col, ref: ref, ...props });
 });
 
+/**
+ * A horizontal flex container for arranging elements side-by-side.
+ *
+ * Arranges children horizontally with consistent spacing. Supports responsive
+ * breakpoints to switch to vertical stacking on smaller screens. Uses layout
+ * spacing for structural organization.
+ *
+ * @example
+ * ```tsx
+ * // Basic horizontal row
+ * <Row gap>
+ *   <Button>Action 1</Button>
+ *   <Button>Action 2</Button>
+ * </Row>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Row with space-between
+ * <Row justifyBetween itemsCenter>
+ *   <Title>Page Header</Title>
+ *   <Button>CTA</Button>
+ * </Row>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive row (stacks on tablets and below)
+ * <Row tabletCol gap>
+ *   <Card>Card 1</Card>
+ *   <Card>Card 2</Card>
+ *   <Card>Card 3</Card>
+ * </Row>
+ * ```
+ *
+ * @see {@link RowProps} for all available props
+ */
 const Row = forwardRef(function Row(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.row, ref: ref, ...props });
 });
 
+/**
+ * A 2-column CSS grid container.
+ *
+ * Creates a responsive grid with 2 equal-width columns. Grid items automatically
+ * fill available columns. Uses CSS Grid for precise layout control.
+ *
+ * @example
+ * ```tsx
+ * // Basic 2-column grid
+ * <Grid2 gap>
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ *   <Card>Item 3</Card>
+ *   <Card>Item 4</Card>
+ * </Grid2>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid with custom styling
+ * <Grid2 gap lg className="auto-rows-fr">
+ *   <div>Column 1</div>
+ *   <div>Column 2</div>
+ * </Grid2>
+ * ```
+ *
+ * @see {@link GridProps} for all available props
+ */
 const Grid2 = forwardRef(function Grid2(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.grid2, ref: ref, ...props });
 });
+/**
+ * A 3-column CSS grid container.
+ *
+ * Creates a responsive grid with 3 equal-width columns. Ideal for card
+ * layouts and feature displays. Grid items automatically wrap to new rows.
+ *
+ * @example
+ * ```tsx
+ * // Basic 3-column grid
+ * <Grid3 gap>
+ *   <Card>Feature 1</Card>
+ *   <Card>Feature 2</Card>
+ *   <Card>Feature 3</Card>
+ * </Grid3>
+ * ```
+ *
+ * @see {@link GridProps} for all available props
+ */
 const Grid3 = forwardRef(function Grid3(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.grid3, ref: ref, ...props });
 });
+/**
+ * A 4-column CSS grid container.
+ *
+ * Creates a responsive grid with 4 equal-width columns. Perfect for
+ * image galleries or product listings with multiple items per row.
+ *
+ * @example
+ * ```tsx
+ * // Basic 4-column grid
+ * <Grid4 gap>
+ *   <Img src="/img1.jpg" alt="1" />
+ *   <Img src="/img2.jpg" alt="2" />
+ *   <Img src="/img3.jpg" alt="3" />
+ *   <Img src="/img4.jpg" alt="4" />
+ * </Grid4>
+ * ```
+ *
+ * @see {@link GridProps} for all available props
+ */
 const Grid4 = forwardRef(function Grid4(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.grid4, ref: ref, ...props });
 });
+/**
+ * A 5-column CSS grid container.
+ *
+ * Creates a responsive grid with 5 equal-width columns. Useful for
+ * dense layouts with many small items, like icon grids or tag clouds.
+ *
+ * @example
+ * ```tsx
+ * // Basic 5-column grid
+ * <Grid5 gap>
+ *   <Badge>Tag 1</Badge>
+ *   <Badge>Tag 2</Badge>
+ *   <Badge>Tag 3</Badge>
+ *   <Badge>Tag 4</Badge>
+ *   <Badge>Tag 5</Badge>
+ * </Grid5>
+ * ```
+ *
+ * @see {@link GridProps} for all available props
+ */
 const Grid5 = forwardRef(function Grid5(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.grid5, ref: ref, ...props });
 });
+/**
+ * A 6-column CSS grid container.
+ *
+ * Creates a responsive grid with 6 equal-width columns. Ideal for very
+ * dense layouts or dashboard widgets with many small components.
+ *
+ * @example
+ * ```tsx
+ * // Basic 6-column grid
+ * <Grid6 gap>
+ *   <Chip>Item 1</Chip>
+ *   <Chip>Item 2</Chip>
+ *   <Chip>Item 3</Chip>
+ *   <Chip>Item 4</Chip>
+ *   <Chip>Item 5</Chip>
+ *   <Chip>Item 6</Chip>
+ * </Grid6>
+ * ```
+ *
+ * @see {@link GridProps} for all available props
+ */
 const Grid6 = forwardRef(function Grid6(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { theme: theme.grid6, ref: ref, ...props });
 });
 
+/**
+ * A container component for grouping related content with padding and borders.
+ *
+ * Cards provide visual separation and organization for content blocks. Support
+ * responsive flex direction with breakpoint props. Use for content cards,
+ * feature boxes, or any grouped content that needs visual distinction.
+ *
+ * @example
+ * ```tsx
+ * // Basic card
+ * <Card>
+ *   <Title>Card Title</Title>
+ *   <Text>Card content goes here.</Text>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card with styling
+ * <Card primary outlined shadow padding gap>
+ *   <Title>Feature</Title>
+ *   <Text>Description of the feature</Text>
+ *   <Button>Learn More</Button>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive card layout
+ * <Card tabletCol gap padding>
+ *   <Img src="/image.jpg" alt="Image" />
+ *   <div>
+ *     <Title>Content</Title>
+ *     <Text>Details here</Text>
+ *   </div>
+ * </Card>
+ * ```
+ *
+ * @see {@link CardProps} for all available props
+ */
 const Card = forwardRef(function Card(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.card, ...props });
 });
 
+/**
+ * A vertical flex container for stacking elements.
+ *
+ * Arranges children vertically with consistent spacing. Supports responsive
+ * breakpoints to switch to horizontal layout on larger screens. Uses layout
+ * spacing for structural organization.
+ *
+ * @example
+ * ```tsx
+ * // Basic vertical stack
+ * <Stack gap>
+ *   <Button>Button 1</Button>
+ *   <Button>Button 2</Button>
+ *   <Button>Button 3</Button>
+ * </Stack>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Stack with padding and alignment
+ * <Stack padding gap itemsCenter>
+ *   <Title>Centered Content</Title>
+ *   <Text>All items are centered</Text>
+ * </Stack>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive stack (becomes horizontal on desktop)
+ * <Stack desktopCol gap>
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ * </Stack>
+ * ```
+ *
+ * @see {@link StackProps} for all available props
+ */
 const Stack = forwardRef(function Stack(props, ref) {
     const theme = useTheme();
     const stackTheme = theme.stack;
     return jsx(ThemedComponent, { theme: stackTheme, ref: ref, ...props });
 });
 
+/**
+ * A top-level page heading component (h1).
+ *
+ * Renders the main heading for a page with large, bold typography.
+ * Automatically scales down on smaller screens for responsive design.
+ * Can be rendered as a link when href prop is provided.
+ *
+ * @example
+ * ```tsx
+ * // Basic page title
+ * <PageTitle>Welcome to My Site</PageTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Page title with custom styling
+ * <PageTitle primary xl>Product Launch</PageTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Page title as a link
+ * <PageTitle href="/">Home Page</PageTitle>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const PageTitle = forwardRef(function PageTitle(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.pageTitle, ...props });
 });
+/**
+ * A section heading component (h2).
+ *
+ * Renders a heading for major sections of content. Medium-large size with
+ * responsive scaling on smaller screens. Typically used to divide page
+ * content into logical sections.
+ *
+ * @example
+ * ```tsx
+ * // Basic section title
+ * <SectionTitle>Features</SectionTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Section title with styling
+ * <SectionTitle secondary bold>About Us</SectionTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Section title as a link
+ * <SectionTitle href="#features">Jump to Features</SectionTitle>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const SectionTitle = forwardRef(function SectionTitle(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.sectionTitle, ...props });
 });
+/**
+ * A subsection heading component (h3).
+ *
+ * Renders a heading for subsections or cards. Medium size with subtle
+ * responsive scaling. Use for content organization below section titles.
+ *
+ * @example
+ * ```tsx
+ * // Basic title
+ * <Title>Getting Started</Title>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title with custom appearance
+ * <Title primary semibold>Installation</Title>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title as a link
+ * <Title href="/docs/intro">Documentation</Title>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const Title = forwardRef(function Title(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.title, ...props });
 });
+/**
+ * A body text component (p).
+ *
+ * Renders paragraph text with automatic URL detection and link conversion.
+ * Use for main content, descriptions, and body copy. Can be rendered as
+ * a link when href prop is provided.
+ *
+ * @example
+ * ```tsx
+ * // Basic paragraph
+ * <Text>This is a paragraph of body text.</Text>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text with custom styling
+ * <Text secondary lg>Large secondary text content.</Text>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text as a link
+ * <Text href="/about">Learn more</Text>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text with typography props
+ * <Text mono semibold>Monospace bold text</Text>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const Text = forwardRef(function Text(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.text, ...props });
 });
+/**
+ * An anchor link component (a).
+ *
+ * Renders a hyperlink with hover underline effect. Inherits text styling
+ * from parent or can be customized with typography props. Use for
+ * navigation links and clickable text.
+ *
+ * @example
+ * ```tsx
+ * // Basic link
+ * <Link href="/about">About Us</Link>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Styled link
+ * <Link href="/contact" primary semibold>Contact</Link>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // External link
+ * <Link href="https://example.com" target="_blank" rel="noopener">
+ *   Visit Example
+ * </Link>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const Link = forwardRef(function Link(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.link, ...props });
 });
+/**
+ * A list item component (li).
+ *
+ * Renders an individual list item within a List component. Supports
+ * typography styling and can be rendered as a link when href is provided.
+ * Use within List for bullet points or numbered lists.
+ *
+ * @example
+ * ```tsx
+ * // Basic list item
+ * <List>
+ *   <ListItem>First item</ListItem>
+ *   <ListItem>Second item</ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Styled list item
+ * <ListItem primary semibold>Important item</ListItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // List item as a link
+ * <ListItem href="/item/1">Click to view details</ListItem>
+ * ```
+ *
+ * @see {@link TypographyProps} for all available props
+ */
 const ListItem = forwardRef(function ListItem(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.listItem, ...props });
 });
+/**
+ * A list container component (ul or ol).
+ *
+ * Renders an unordered (bullets) or ordered (numbers) list. Automatically
+ * switches between ul and ol based on the `decimal` prop. Use with ListItem
+ * components for structured lists.
+ *
+ * @example
+ * ```tsx
+ * // Unordered list (bullets)
+ * <List>
+ *   <ListItem>Item one</ListItem>
+ *   <ListItem>Item two</ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Ordered list (numbers)
+ * <List decimal>
+ *   <ListItem>First step</ListItem>
+ *   <ListItem>Second step</ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Styled list
+ * <List primary lg padding>
+ *   <ListItem>Feature A</ListItem>
+ *   <ListItem>Feature B</ListItem>
+ * </List>
+ * ```
+ *
+ * @see {@link ListProps} for all available props
+ */
 const List = forwardRef(function List(props, ref) {
     const theme = useTheme();
     return jsx(ThemedComponent, { ref: ref, theme: theme.list, ...props });
 });
 
-export { ACTIVE, APPEARANCE_CATEGORY, APPEARANCE_VALUES, BADGE_CATEGORIES, BASE, BORDER, BORDER_KEYS, BORDER_VALUES, BREAKPOINT, BREAKPOINT_VALUES, BUTTON_CATEGORIES, Badge, Button, CARD_CATEGORIES, CHECKBOX_CATEGORIES, CHIP_CATEGORIES, CODE_CATEGORIES, COL_CATEGORIES, COMPONENT, COMPONENT_PROPS_CATEGORY, CONTAINER_CATEGORIES, Card, Checkbox, Chip, Code, Col, ComponentCategories, ComponentKeys, Container, DISPLAY_VALUES, DIVIDER_CATEGORIES, Divider, FLEX_DIRECTION_VALUES, FOCUS, FOCUS_VISIBLE, FOCUS_VISIBLE_VALUES, FONT_FAMILY_VALUES, FONT_STYLE_VALUES, FONT_WEIGHT_VALUES, GAP_VALUES, GRID_CATEGORIES, Grid2, Grid3, Grid4, Grid5, Grid6, HIDE_VALUES, HOVER, IMG_CATEGORIES, INPUT_CATEGORIES, INTERACTIVE_CATEGORIES, ITEMS_VALUES, Img, Input, JUSTIFY_VALUES, LABEL_CATEGORIES, LAYOUT_CORE, LAYOUT_FLEX, LAYOUT_FULL, LIST_CATEGORIES, LIST_STYLE, LIST_STYLE_VALUES, Label, Link, List, ListItem, MODE_VALUES, ModeKeys, NO_BORDER, OVERFLOW_VALUES, PADDING, PADDING_VALUES, POSITION_VALUES, PageTitle, REVERSE_VALUES, RING_VALUES, ROW_CATEGORIES, Row, SECTION_CATEGORIES, SHADOW_VALUES, SHAPE, SHAPE_VALUES, SIZE_VALUES, STACK_CATEGORIES, Section, SectionTitle, Stack, TEXT_ALIGN_VALUES, TEXT_DECORATION_VALUES, TEXT_TRANSFORM_VALUES, TRANSPARENT_VALUES, TYPOGRAPHY_CATEGORIES, TYPOGRAPHY_FULL, TYPOGRAPHY_STYLE, Text, ThemeProvider, Title, VARIANT, VARIANT_VALUES, VISUAL_CORE, VISUAL_DECORATION, VISUAL_DECORATION_LAYOUT, VISUAL_FULL, VISUAL_LAYOUT, WRAP_VALUES, defaultTheme, themeDefaults, useTheme };
+export { ACTIVE, APPEARANCE_CATEGORY, BADGE_CATEGORIES, BASE, BORDER, BORDER_KEYS, BREAKPOINT, BUTTON_CATEGORIES, Badge, Button, CARD_CATEGORIES, CHECKBOX_CATEGORIES, CHIP_CATEGORIES, CODE_CATEGORIES, COL_CATEGORIES, COMPONENT, COMPONENT_PROPS_CATEGORY, CONTAINER_CATEGORIES, Card, Checkbox, Chip, Code, Col, ComponentCategories, ComponentKeys, Container, DIVIDER_CATEGORIES, Divider, FOCUS, FOCUS_VISIBLE, GRID_CATEGORIES, Grid2, Grid3, Grid4, Grid5, Grid6, HOVER, IMG_CATEGORIES, INPUT_CATEGORIES, INTERACTIVE_CATEGORIES, Img, Input, LABEL_CATEGORIES, LAYOUT_CORE, LAYOUT_FLEX, LAYOUT_FULL, LIST_CATEGORIES, LIST_STYLE, Label, Link, List, ListItem, MODE_VALUES, ModeKeys, PADDING, PageTitle, ROW_CATEGORIES, Row, SECTION_CATEGORIES, SHAPE, STACK_CATEGORIES, Section, SectionTitle, Stack, TYPOGRAPHY_CATEGORIES, TYPOGRAPHY_FULL, TYPOGRAPHY_STYLE, Text, ThemeProvider, Title, VARIANT, VISUAL_CORE, VISUAL_DECORATION, VISUAL_DECORATION_LAYOUT, VISUAL_FULL, VISUAL_LAYOUT, defaultTheme, themeDefaults, useTheme };
 //# sourceMappingURL=index.esm.js.map