@vaneui/ui 0.3.1-alpha.20251201135827.a31cb1e → 0.3.1-alpha.20251213103636.79707b4

package/dist/index.esm.js

@@ -5409,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, outline).
+ *
+ * @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 outline 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 outline>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 outline 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 outline 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
@@ -5467,97 +5664,739 @@ 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 outline 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 outline 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 });