@fpkit/acss 0.5.12 → 0.6.0

package/libs/index.d.cts

@@ -1,26 +1,330 @@
 export { Button, ButtonProps } from './components/button.cjs';
 export { Card, Content as CardContent, Footer as CardFooter, CardProps, Title as CardTitle } from './components/card.cjs';
 export { default as Field, FieldProps } from './components/form/fields.cjs';
-export { F as Box, F as FP, I as Input, a as InputProps } from './inputs-f3a216db.js';
+export { default as Input } from './components/form/inputs.cjs';
 export { default as Icon, IconProps } from './components/icons/icon.cjs';
-import { F as FP } from './ui-9a6f9f8d.js';
-import React__default, { ReactNode } from 'react';
-export { default as Link, LinkProps, default as To } from './components/link/link.cjs';
-export { default as List, ListItemProps } from './components/list/list.cjs';
+import React, { ReactNode } from 'react';
+export { L as Link, a as LinkProps, L as To } from './link-5192f411.js';
+export { List } from './components/list/list.cjs';
 export { Modal, ModalProps } from './components/modal.cjs';
 export { default as Popover, PopoverProps } from './components/popover/popover.cjs';
 export { RenderTable as TBL, TableProps } from './components/tables/table.cjs';
 export { Dialog } from './components/dialog/dialog.cjs';
-export { default as Nav, NavItem, NavItemProps, NavList, NavListProps, NavProps } from './components/nav/nav.cjs';
-export { default as Text, TextProps, Title } from './components/text/text.cjs';
-export { TitleProps } from './components/heading/heading.cjs';
-export { default as Textarea, TextareaProps } from './components/form/textarea.cjs';
-import { C as ComponentProps$1 } from './component-props-a8a2f97e.js';
-export { default as Breadcrumb } from './components/breadcrumbs/breadcrumb.cjs';
+import { U as UI } from './ui-d01b50d4.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 } from './list.types-d26de310.js';
 
-type ImageProps = React__default.ComponentProps<'img'> & React__default.ComponentProps<typeof FP>;
+/**
+ * Props for the Img component.
+ *
+ * Extends native HTML img element attributes with additional functionality
+ * for responsive images, loading states, and error handling.
+ *
+ * ## Accessibility Guidelines (WCAG 2.1 AA)
+ *
+ * **Decorative Images:**
+ * Images that are purely visual decoration should have an empty alt attribute.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Decorative image (border, background pattern, visual separator)
+ * <Img src="/decorative-border.png" alt="" />
+ * ```
+ *
+ * **Semantic Images:**
+ * Images that convey information or meaning must have descriptive alt text.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Semantic image (charts, diagrams, photos with meaning)
+ * <Img
+ *   src="/sales-chart.png"
+ *   alt="Sales chart showing 30% growth in Q4 2024"
+ * />
+ * ```
+ *
+ * **Responsive Images:**
+ * Use srcset and sizes for responsive images to optimize performance.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Responsive image with srcset
+ * <Img
+ *   src="/photo.jpg"
+ *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w, /photo-1024w.jpg 1024w"
+ *   sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
+ *   alt="Team photo from annual conference"
+ * />
+ * ```
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+ */
+interface ImgProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
+    /**
+     * The image source URL.
+     * @default '//'
+     */
+    src?: string;
+    /**
+     * Alternative text for the image.
+     * - **Empty string (`""`)** for decorative images
+     * - **Descriptive text** for semantic images that convey meaning
+     *
+     * @example
+     * ```tsx
+     * // Decorative
+     * <Img src="/border.png" alt="" />
+     *
+     * // Semantic
+     * <Img src="/logo.png" alt="Company logo" />
+     * ```
+     */
+    alt?: string;
+    /**
+     * Width of the image in pixels.
+     * @default 480
+     */
+    width?: number | string;
+    /**
+     * Height of the image in pixels.
+     * When not provided, defaults to 'auto'.
+     */
+    height?: number | string;
+    /**
+     * Inline styles to apply to the image.
+     */
+    styles?: React.CSSProperties;
+    /**
+     * Loading behavior for the image.
+     * - `"lazy"` (default): Defers loading until near viewport
+     * - `"eager"`: Loads immediately
+     *
+     * @default "lazy"
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
+     */
+    loading?: 'eager' | 'lazy';
+    /**
+     * Fallback placeholder image URL to display on error.
+     * If not provided and image fails to load, a default placeholder is used.
+     *
+     * @example
+     * ```tsx
+     * <Img
+     *   src="/photo.jpg"
+     *   placeholder="/fallback.png"
+     *   alt="User profile photo"
+     * />
+     * ```
+     */
+    placeholder?: string;
+    /**
+     * Hint for the browser to prioritize image fetching.
+     * - `"high"`: High priority (above-the-fold images)
+     * - `"low"` (default): Low priority
+     * - `"auto"`: Browser decides
+     *
+     * @default "low"
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#fetchpriority
+     */
+    fetchpriority?: 'high' | 'low' | 'auto';
+    /**
+     * Decoding hint for the browser.
+     * - `"async"`: Decode asynchronously (don't block rendering)
+     * - `"sync"`: Decode synchronously
+     * - `"auto"` (default): Browser decides
+     *
+     * @default "auto"
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#decoding
+     */
+    decoding?: 'sync' | 'async' | 'auto';
+    /**
+     * Responsive image sources with width descriptors.
+     * Allows browser to choose appropriate image based on viewport.
+     *
+     * @example
+     * ```tsx
+     * <Img
+     *   src="/photo.jpg"
+     *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w"
+     *   sizes="(max-width: 640px) 100vw, 640px"
+     *   alt="Responsive image"
+     * />
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset
+     */
+    srcSet?: string;
+    /**
+     * Media conditions for responsive image sizing.
+     * Works with srcSet to determine which image to load.
+     *
+     * @example
+     * ```tsx
+     * sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+     */
+    sizes?: string;
+    /**
+     * Callback fired when the image fails to load.
+     * The default SVG placeholder is still applied after calling this handler.
+     * Call `event.preventDefault()` to prevent the default fallback behavior.
+     *
+     * @param event - The error event
+     *
+     * @example
+     * ```tsx
+     * // Log error and show default placeholder
+     * <Img
+     *   src="/photo.jpg"
+     *   onError={(e) => console.error('Image failed to load', e)}
+     *   alt="Photo"
+     * />
+     *
+     * // Prevent default and use custom fallback
+     * <Img
+     *   src="/photo.jpg"
+     *   onError={(e) => {
+     *     e.preventDefault()
+     *     e.currentTarget.src = '/custom-fallback.jpg'
+     *   }}
+     *   alt="Photo"
+     * />
+     * ```
+     */
+    onError?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void;
+    /**
+     * Callback fired when the image successfully loads.
+     *
+     * @param event - The load event
+     *
+     * @example
+     * ```tsx
+     * <Img
+     *   src="/photo.jpg"
+     *   onLoad={(e) => console.log('Image loaded successfully')}
+     *   alt="Photo"
+     * />
+     * ```
+     */
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void;
+}
+
+/**
+ * Img - A semantic image component with accessibility and performance best practices.
+ *
+ * This component wraps the native `<img>` element with enhanced features:
+ * - **Responsive images** via optional srcset/sizes
+ * - **Lazy loading** by default for performance
+ * - **Error handling** with configurable fallback placeholders
+ * - **Type safety** with full TypeScript support
+ *
+ * ## Accessibility Patterns (WCAG 2.1 AA)
+ *
+ * ### Decorative Images
+ * Images that are purely visual decoration should use an empty alt attribute.
+ * These images are typically borders, patterns, or visual separators.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Decorative border image
+ * <Img src="/decorative-border.png" alt="" />
+ *
+ * // ✅ GOOD: Background pattern
+ * <Img src="/pattern.svg" alt="" loading="eager" />
+ * ```
+ *
+ * ### Semantic Images
+ * Images that convey information must have descriptive alt text that explains
+ * the content and purpose of the image.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Informative image with descriptive alt
+ * <Img
+ *   src="/sales-chart.png"
+ *   alt="Sales chart showing 30% revenue growth in Q4 2024"
+ * />
+ *
+ * // ✅ GOOD: Product photo with context
+ * <Img
+ *   src="/laptop.jpg"
+ *   alt="Silver MacBook Pro 14-inch on wooden desk"
+ * />
+ * ```
+ *
+ * ## Performance Optimization
+ *
+ * ### Lazy Loading
+ * By default, images use lazy loading to improve page load performance.
+ * Only use `loading="eager"` for above-the-fold images.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Lazy load below-the-fold image
+ * <Img src="/photo.jpg" alt="Photo" />
+ *
+ * // ✅ GOOD: Eager load hero image
+ * <Img
+ *   src="/hero.jpg"
+ *   alt="Hero banner"
+ *   loading="eager"
+ *   fetchpriority="high"
+ * />
+ * ```
+ *
+ * ### Responsive Images
+ * Use srcset and sizes for responsive images to serve appropriate image sizes
+ * based on viewport width, improving performance and bandwidth usage.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Responsive image with multiple sizes
+ * <Img
+ *   src="/photo.jpg"
+ *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w, /photo-1024w.jpg 1024w"
+ *   sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+ *   alt="Responsive image adapts to viewport"
+ * />
+ * ```
+ *
+ * ## Error Handling
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Custom placeholder on error
+ * <Img
+ *   src="/photo.jpg"
+ *   placeholder="/fallback.png"
+ *   alt="User profile photo"
+ * />
+ *
+ * // ✅ GOOD: Custom error handler
+ * <Img
+ *   src="/photo.jpg"
+ *   onError={(e) => {
+ *     console.error('Image failed to load')
+ *     logToAnalytics('image_error', { src: e.currentTarget.src })
+ *   }}
+ *   alt="Photo"
+ * />
+ * ```
+ *
+ * @param {ImgProps} props - Component props extending native img attributes
+ * @returns {React.ReactElement} Image element with enhanced functionality
+ *
+ * @see {@link ImgProps} for complete prop documentation
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+ */
 declare const Img: {
-    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, imgLoaded, imgError, ...props }: ImageProps): React__default.JSX.Element;
+    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, srcSet, sizes, onError, onLoad, ...props }: ImgProps): React.JSX.Element;
     displayName: string;
 };
 
@@ -42,7 +346,7 @@ interface TextToSpeechComponentProps {
     /** The language to be used for speech synthesis. */
     language?: string;
     /** Player label */
-    label?: string | React__default.ReactNode;
+    label?: string | React.ReactNode;
     /** Callback function to be called when speech ends. */
     onEnd?: () => void;
 }
@@ -51,22 +355,22 @@ interface TextToSpeechComponentProps {
  * @param {TextToSpeechComponentProps} props - The props for the component.
  * @returns {JSX.Element} The rendered TextToSpeechComponent.
  */
-declare const TextToSpeech: React__default.FC<TextToSpeechComponentProps>;
+declare const TextToSpeech: React.FC<TextToSpeechComponentProps>;
 
-type ComponentProps = React__default.ComponentProps<typeof FP>;
+type ComponentProps = React.ComponentProps<typeof UI>;
 /**
  * Renders children elements without any wrapping component.
  * Can be used as a placeholder when no semantic landmark is needed.
  */
 declare const Landmarks: {
-    (children?: React__default.FC): React__default.JSX.Element;
+    (children?: React.FC): React.JSX.Element;
     displayName: string;
-    Header: ({ id, children, headerBackground, styles, classes, ...props }: HeaderProps) => React__default.JSX.Element;
-    Main: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
-    Footer: ({ id, classes, children, styles, ...props }: ComponentProps) => React__default.JSX.Element;
-    Aside: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
-    Section: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
-    Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
+    Header: ({ id, children, headerBackground, styles, classes, ...props }: HeaderProps) => React.JSX.Element;
+    Main: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
+    Footer: ({ id, classes, children, styles, ...props }: ComponentProps) => React.JSX.Element;
+    Aside: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
+    Section: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
+    Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
 };
 type HeaderProps = {
     headerBackground?: ReactNode;
@@ -80,7 +384,7 @@ type HeaderProps = {
  * @param styles - Optional styles object.
  * @param props - Other props.
  */
-declare const Header: ({ id, children, headerBackground, styles, classes, ...props }: HeaderProps) => React__default.JSX.Element;
+declare const Header: ({ id, children, headerBackground, styles, classes, ...props }: HeaderProps) => React.JSX.Element;
 /**
  * Main component.
  *
@@ -90,7 +394,7 @@ declare const Header: ({ id, children, headerBackground, styles, classes, ...pro
  * @param styles - Optional styles object.
  * @param props - Other props.
  */
-declare const Main: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
+declare const Main: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
 /**
  * Footer component that renders a footer element with a section element inside.
  * @param {ReactNode} children - Child elements to render inside the section element.
@@ -98,8 +402,8 @@ declare const Main: ({ id, children, styles, classes, ...props }: ComponentProps
  * @param props - Additional props to pass to the footer element.
  * @returns A React component that renders a footer element with a section element inside.
  */
-declare const Footer: ({ id, classes, children, styles, ...props }: ComponentProps) => React__default.JSX.Element;
-declare const Aside: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
+declare const Footer: ({ id, classes, children, styles, ...props }: ComponentProps) => React.JSX.Element;
+declare const Aside: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
 /**
  * Section component that renders a section element.
  *
@@ -107,7 +411,7 @@ declare const Aside: ({ id, children, styles, classes, ...props }: ComponentProp
  * @param styles - CSS styles to apply to the section.
  * @param props - Other props.
  */
-declare const Section: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
+declare const Section: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
 /**
  * Article component renders an HTML <article> element.
  *
@@ -115,71 +419,540 @@ declare const Section: ({ id, children, styles, classes, ...props }: ComponentPr
  * @param styles - CSS styles to apply to the article.
  * @param props - Additional props to pass to the article element.
  */
-declare const Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
+declare const Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React.JSX.Element;
+
+/**
+ * Props for the Badge component
+ *
+ * @property {React.ReactNode} children - Content to display inside the badge (typically numbers or short text)
+ * @property {string} [id] - Optional HTML id attribute for the badge element
+ * @property {React.CSSProperties} [styles] - Inline styles to apply to the badge
+ * @property {string} [classes] - CSS class names to apply to the badge
+ * @property {'rounded'} [variant] - Visual variant of the badge. Use 'rounded' for circular badges (fixed size with ellipsis for overflow)
+ * @property {string} [aria-label] - Accessible label for screen readers. Required for icon-only or number-only badges
+ * @property {'status' | 'note'} [role] - ARIA role for the badge. Defaults to 'status' for dynamic content
+ */
+type BadgeProps = {
+    /**
+     * Content to display inside the badge (typically numbers or short text)
+     */
+    children?: React.ReactNode;
+    /**
+     * Visual variant of the badge
+     * - 'rounded': Circular badge style
+     */
+    variant?: 'rounded';
+} & React.ComponentProps<typeof UI>;
+/**
+ * Badge - A small label component for displaying status, counts, or notifications
+ *
+ * The Badge component is used to display supplementary information alongside other content,
+ * such as notification counts, status indicators, or labels. It renders as a semantic `<sup>`
+ * element with a nested `<span>` required for the component's styling architecture.
+ *
+ * ## Styling Architecture
+ *
+ * The Badge uses a nested structure (`<sup><span>content</span></sup>`) which is required
+ * for the SCSS styling system. The outer `<sup>` element provides positioning context,
+ * while the inner `<span>` receives the visual styling (background, padding, border-radius).
+ *
+ * ## Rounded Variant Behavior
+ *
+ * The `rounded` variant creates a perfect circular badge with fixed dimensions (1.5625rem).
+ * Content that exceeds the available space will be truncated with an ellipsis (...).
+ * **Best practice**: Format large numbers yourself (e.g., pass "99+" instead of "999").
+ *
+ * ## Accessibility Considerations
+ *
+ * - **Semantic HTML**: Uses `<sup>` (superscript) element for proper positioning context
+ * - **ARIA Role**: Defaults to `role="status"` for dynamic badges (e.g., unread counts)
+ * - **Accessible Names**: For icon-only or number-only badges, provide an `aria-label`
+ *   to give context (e.g., "3 unread messages" instead of just "3")
+ * - **Live Regions**: The `role="status"` makes badges announce updates to screen readers
+ *
+ * @param {BadgeProps} props - Component props
+ * @returns {React.ReactElement} A Badge component
+ *
+ * @example
+ * // Basic badge with notification count
+ * <p>
+ *   Messages
+ *   <Badge aria-label="3 unread messages">3</Badge>
+ * </p>
+ *
+ * @example
+ * // Rounded badge variant (perfect circle)
+ * <p>
+ *   Notifications
+ *   <Badge variant="rounded" aria-label="99 or more notifications">99+</Badge>
+ * </p>
+ *
+ * @example
+ * // Status badge with custom styling
+ * <p>
+ *   Active Users
+ *   <Badge styles={{ backgroundColor: 'green', color: 'white' }}>21</Badge>
+ * </p>
+ *
+ * @example
+ * // ✅ GOOD: Accessible badge with descriptive label and formatted content
+ * <Badge variant="rounded" aria-label="12 items in cart">12</Badge>
+ *
+ * @example
+ * // ✅ GOOD: Large numbers formatted by developer
+ * <Badge variant="rounded" aria-label="More than 99 notifications">99+</Badge>
+ *
+ * @example
+ * // ❌ BAD: Number-only badge without context for screen readers
+ * <Badge>12</Badge>
+ */
+declare const Badge: {
+    ({ id, styles, classes, children, variant, ...props }: BadgeProps): React.JSX.Element;
+    displayName: string;
+};
 
+/**
+ * Available visual variants for the Tag component
+ *
+ * Each variant applies predefined color schemes and styling through CSS custom properties:
+ * - `alpha`: Early development stage indicator (warning colors)
+ * - `beta`: Pre-release version indicator (warning colors)
+ * - `stable`: Production-ready release indicator (success colors)
+ * - `production`: Live production environment indicator (primary colors)
+ *
+ * @example
+ * ```tsx
+ * <Tag variant="beta">Beta Feature</Tag>
+ * <Tag variant="stable">v2.0</Tag>
+ * ```
+ */
+type TagVariant = 'alpha' | 'beta' | 'stable' | 'production';
+/**
+ * Props for the Tag component
+ *
+ * @property {React.ReactNode} children - REQUIRED - Content to display inside the tag (typically short text or version numbers)
+ * @property {'span' | 'p'} [elm='span'] - HTML element to render the tag as. Use 'p' for block-level tags, 'span' for inline
+ * @property {'note' | 'status'} [role='note'] - ARIA role for semantic meaning and screen reader announcements
+ * @property {TagVariant} [variant] - Visual variant that applies predefined color schemes (alpha, beta, stable, production)
+ * @property {string} [id] - Optional HTML id attribute for the tag element
+ * @property {React.CSSProperties} [styles] - Inline styles to apply to the tag
+ * @property {string} [classes] - CSS class names to apply to the tag
+ * @property {string} [aria-label] - Accessible label for screen readers. Recommended when tag content needs additional context
+ * @property {string} [aria-labelledby] - Reference to element(s) that label the tag for additional context
+ * @property {string} [aria-describedby] - Reference to element(s) that describe the tag for additional context
+ * @property {'off' | 'polite' | 'assertive'} [aria-live] - ARIA live region politeness setting for dynamic content (use with role="status")
+ *
+ * @example
+ * ```tsx
+ * // Basic tag with variant
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * // Tag with custom element and role
+ * <Tag elm="p" role="status" variant="stable">v1.0 Released</Tag>
+ *
+ * // Tag with accessibility label
+ * <Tag variant="production" aria-label="Currently in production environment">
+ *   Production
+ * </Tag>
+ * ```
+ */
 type TagProps = {
-    /** HTML element to display the badge as span or p */
+    /**
+     * HTML element to display the tag as
+     * - 'span': Inline tag (default) - use for inline placement within text flow
+     * - 'p': Block-level tag - use when tag should appear as a distinct block element
+     */
     elm?: 'span' | 'p';
-    /**  Aria role for the component - conditional */
-    role: 'note' | 'status';
-} & React__default.ComponentProps<typeof FP>;
+    /**
+     * ARIA role for semantic meaning and screen reader behavior
+     * - 'note': For static, informational tags (default) - screen readers read once
+     * - 'status': For dynamic tags that update - screen readers announce changes to users
+     *
+     * Choose 'status' when tag content changes dynamically (e.g., real-time status updates).
+     * Choose 'note' for static tags that provide contextual information.
+     */
+    role?: 'note' | 'status';
+    /**
+     * Visual variant that applies predefined color schemes
+     * - 'alpha': Early development stage (amber background with warning symbol ⚠)
+     * - 'beta': Pre-release version (amber background with warning symbol ⚠)
+     * - 'stable': Production-ready release (green background with checkmark ✓)
+     * - 'production': Live production environment (blue background with live indicator ●)
+     *
+     * Each variant includes both color AND visual symbols for accessibility (WCAG 1.4.1).
+     */
+    variant?: TagVariant;
+    /**
+     * Content to display inside the tag
+     * REQUIRED - Ensures tag has meaningful content for all users including screen reader users
+     * Typically short text, version numbers, or status labels
+     */
+    children: React.ReactNode;
+    /**
+     * Accessible label for screen readers
+     * Provides additional context beyond visible text
+     */
+    'aria-label'?: string;
+    /**
+     * Reference to element(s) that label the tag
+     * Alternative to aria-label for programmatic labeling
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Reference to element(s) that describe the tag
+     * Provides additional descriptive context
+     */
+    'aria-describedby'?: string;
+    /**
+     * ARIA live region politeness setting
+     * - 'off': Updates not announced (default)
+     * - 'polite': Announces when user is idle (recommended for role="status")
+     * - 'assertive': Announces immediately (use sparingly for critical updates)
+     */
+    'aria-live'?: 'off' | 'polite' | 'assertive';
+} & Omit<React.ComponentProps<typeof UI>, 'as' | 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-live'>;
+
+/**
+ * Tag - A small inline label component for displaying status, versions, or environment indicators
+ *
+ * The Tag component is used to highlight supplementary information such as release stages
+ * (alpha, beta, stable), environment indicators (production), or version labels. It renders
+ * as either a `<span>` (inline) or `<p>` (block) element with semantic ARIA roles.
+ *
+ * ## Design Philosophy
+ *
+ * Tags serve as visual and semantic indicators that:
+ * - Communicate the state or stage of features, releases, or environments
+ * - Provide quick visual scanning through color-coded variants
+ * - Maintain accessibility through proper ARIA roles and labels
+ *
+ * ## Styling Architecture
+ *
+ * The Tag component uses CSS custom properties (CSS variables) for theming and styling,
+ * allowing for easy customization through the `data-tag` attribute. Each variant
+ * (alpha, beta, stable, production) applies predefined color schemes defined in SCSS.
+ *
+ * ## Accessibility Considerations (WCAG 2.1 AA Compliance)
+ *
+ * - **Semantic Roles**: Uses `role="note"` for static tags or `role="status"` for dynamic content
+ *   - `role="note"`: Read once by screen readers, suitable for static labels (default)
+ *   - `role="status"`: Announces updates to screen readers, use for changing status indicators
+ * - **Color Independence**: Don't rely solely on color to convey meaning - include text labels
+ * - **Text Alternatives**: For icon-only tags, provide `aria-label` for screen reader context
+ * - **Contrast Ratios**: All variants meet WCAG AA contrast requirements (4.5:1 for normal text)
+ * - **Live Regions**: When using `role="status"`, tag becomes a live region for accessibility
+ *
+ * ## When to Use Each Role
+ *
+ * **Use `role="note"` (default) when:**
+ * - Displaying static version numbers (e.g., "v2.1.0")
+ * - Showing fixed environment indicators (e.g., "Beta Feature")
+ * - Labeling unchanging content categories
+ *
+ * **Use `role="status"` when:**
+ * - Indicating real-time status that may change (e.g., "Processing" → "Complete")
+ * - Displaying live build/deployment states
+ * - Showing dynamic feature flags that toggle
+ *
+ * @param {TagProps} props - Component props
+ * @returns {React.ReactElement} A Tag component
+ *
+ * @example
+ * // Basic tag with beta variant (default inline span)
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * @example
+ * // Production environment indicator as block element
+ * <Tag elm="p" variant="production">Production Environment</Tag>
+ *
+ * @example
+ * // Dynamic status tag with live updates
+ * <Tag role="status" variant="stable">
+ *   {isDeployed ? 'Deployed' : 'Deploying...'}
+ * </Tag>
+ *
+ * @example
+ * // Tag with custom styling and accessibility label
+ * <Tag
+ *   variant="alpha"
+ *   aria-label="Alpha version - may contain bugs"
+ *   styles={{ fontSize: '0.75rem' }}
+ * >
+ *   Alpha
+ * </Tag>
+ *
+ * @example
+ * // ✅ GOOD: Clear text content with variant for visual enhancement
+ * <Tag variant="stable">v2.0 Stable</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Dynamic status with proper role
+ * <Tag role="status" variant="production">{deploymentStatus}</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Accessible tag with descriptive label
+ * <Tag variant="beta" aria-label="Beta feature - feedback welcome">
+ *   Beta
+ * </Tag>
+ *
+ * @example
+ * // ❌ BAD: Relying only on color without text
+ * <Tag variant="production" aria-label="Production" />
+ *
+ * @example
+ * // ❌ BAD: Using status role for static content
+ * <Tag role="status" variant="stable">v1.0</Tag>
+ */
 declare const Tag: {
-    ({ elm, role, children, styles, ...props }: TagProps): React__default.JSX.Element;
+    ({ elm, role, variant, children, styles, ...props }: TagProps): React.JSX.Element;
     displayName: string;
 };
 
 declare const Caption: {
-    ({ children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 declare const Thead: {
-    ({ children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 declare const Tbody: {
-    ({ children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 declare const Tr: {
-    ({ children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 declare const Td: {
-    ({ children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 declare const Table: {
-    ({ id, dataStyle, children, ...props }: ComponentProps$1): React__default.JSX.Element;
+    ({ id, dataStyle, children, ...props }: ComponentProps$1): React.JSX.Element;
     displayName: string;
 };
 
+/**
+ * Props for the Details component.
+ *
+ * Combines native HTML details element props with custom styling and interaction handlers.
+ * The Details component uses the native `<details>` element for progressive disclosure,
+ * providing built-in keyboard support and semantic HTML.
+ *
+ * @example
+ * ```tsx
+ * <Details
+ *   summary="Click to expand"
+ *   icon={<ChevronIcon />}
+ *   onToggle={(e) => console.log('Toggled:', e.currentTarget.open)}
+ * >
+ *   <p>Hidden content revealed when opened</p>
+ * </Details>
+ * ```
+ */
 type DetailsProps = {
     /**
-     * The summary text shown for the details.
-     * Required.
+     * The summary text or element shown in the clickable header.
+     * This is always visible and acts as the toggle control.
+     *
+     * @required
+     * @example
+     * ```tsx
+     * summary="Shipping Information"
+     * // or
+     * summary={<><Icon /> Shipping Information</>}
+     * ```
      */
-    summary: React__default.ReactNode;
+    summary: React.ReactNode;
     /**
-     * The aria-label  element for accessibility.
+     * Optional icon displayed before the summary text.
+     * Commonly used for chevron/arrow indicators.
+     *
+     * @example
+     * ```tsx
+     * icon={<ChevronDownIcon />}
+     * ```
      */
-    ariaLabel: string;
-} & React__default.ComponentProps<"details"> & Partial<React__default.ComponentProps<typeof FP>>;
-/**3
- * Details component props interface.
+    icon?: React.ReactNode;
+    /**
+     * Accessible label for screen readers.
+     * If not provided, the native `<details>` semantic will be used.
+     *
+     * Note: Native `<details>` elements are already semantic and announced properly
+     * by screen readers. Only provide this if you need to override the default behavior.
+     *
+     * @optional
+     * @example
+     * ```tsx
+     * ariaLabel="Product details section"
+     * ```
+     */
+    ariaLabel?: string;
+    /**
+     * Groups multiple details elements into an accordion where only one can be open.
+     * Multiple details elements with the same `name` will behave as a mutually exclusive group.
+     *
+     * @optional
+     * @example
+     * ```tsx
+     * <Details name="faq-accordion" summary="Question 1">...</Details>
+     * <Details name="faq-accordion" summary="Question 2">...</Details>
+     * ```
+     */
+    name?: string;
+} & React.ComponentProps<"details"> & Partial<React.ComponentProps<typeof UI>>;
+
+/**
+ * Details - A progressive disclosure component using native HTML `<details>` element.
  *
- * @param {React.CSSProperties} [styles] - CSS styles object.
- * @param {string} [classes] - Classnames string.
- * @param {boolean} [open] - Whether the details is open.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onToggle] - onToggle callback.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onPointerDown] - onPointerDown callback.
- * @param {ReactNode} children - The content inside the details.
- * @param {string} [ariaLabel] - aria-label for accessibility.
- * @param {React.Ref<any>} [ref] - Ref object.
- * @param {Object} props - Other props.
+ * This component wraps the native `<details>` and `<summary>` elements to provide
+ * an accessible, semantic way to show and hide content. It supports accordion behavior
+ * through the `name` attribute and includes proper keyboard navigation out of the box.
+ *
+ * ## Key Features:
+ * - **Semantic HTML**: Uses native `<details>` for built-in accessibility
+ * - **Keyboard Support**: Space/Enter to toggle, fully accessible by default
+ * - **Accordion Mode**: Group multiple details with `name` for exclusive expansion
+ * - **Customizable**: Supports icons, custom styles, and event handlers
+ *
+ * ## Accessibility:
+ * - ✅ WCAG 2.1 AA compliant using semantic HTML
+ * - ✅ Native keyboard support (Space, Enter)
+ * - ✅ Screen reader compatible (announced as "disclosure" or "expandable")
+ * - ✅ Focus indicators automatically applied via CSS
+ * - ✅ `aria-expanded` managed automatically by browser
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Details summary="Click to expand">
+ *   <p>Hidden content here</p>
+ * </Details>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon and custom styling
+ * <Details
+ *   summary="Shipping Information"
+ *   icon={<ChevronDownIcon />}
+ *   classes="custom-details"
+ *   onToggle={(e) => console.log('Open:', e.currentTarget.open)}
+ * >
+ *   <p>Ships within 2-3 business days</p>
+ * </Details>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Accordion mode - only one open at a time
+ * <Details name="faq" summary="Question 1">Answer 1</Details>
+ * <Details name="faq" summary="Question 2">Answer 2</Details>
+ * <Details name="faq" summary="Question 3">Answer 3</Details>
+ * ```
  */
-declare const Details: {
-    ({ summary, icon, styles, classes, ariaLabel, name, open, onPointerDown, onToggle, children, ref, ...props }: DetailsProps): React__default.JSX.Element;
-    displayName: string;
+declare const Details: React.ForwardRefExoticComponent<Omit<DetailsProps, "ref"> & React.RefAttributes<HTMLDetailsElement>>;
+
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicRef` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type PolymorphicRef<C extends React.ElementType> = React.Ref<React.ElementRef<C>>;
+/**
+ * @deprecated This type is deprecated. Use `AsProp` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type AsProp<C extends React.ElementType> = {
+    as?: C;
 };
+/**
+ * @deprecated This type is deprecated. Use `PropsToOmit` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P);
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicComponentProp` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type PolymorphicComponentProp<C extends React.ElementType, Props = {}> = React.PropsWithChildren<Props & AsProp<C>> & Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicComponentPropWithRef` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type PolymorphicComponentPropWithRef<C extends React.ElementType, Props = {}> = PolymorphicComponentProp<C, Props> & {
+    ref?: PolymorphicRef<C> | React.ForwardedRef<React.ElementRef<C>>;
+};
+/**
+ * @deprecated This type is deprecated. Use `UIProps` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type FPProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<C, {
+    renderStyles?: boolean;
+    styles?: React.CSSProperties;
+    classes?: string;
+}>;
+/**
+ * FPComponent type definition
+ *
+ * @deprecated This type is deprecated. Use the `UI` component from './ui.tsx' instead.
+ * The UI component provides enhanced accessibility documentation, better type safety,
+ * and comprehensive WCAG 2.1 AA compliance guidance.
+ *
+ * @typeParam C - The HTML element type to render
+ * @param props - The component props
+ * @returns React component
+ *
+ * @example
+ * ```typescript
+ * // Migration from FP to UI
+ * // Before:
+ * import FP from '@fpkit/acss/components/fp';
+ * <FP as="button" styles={{ padding: '1rem' }}>Click me</FP>
+ *
+ * // After:
+ * import UI from '@fpkit/acss/components/ui';
+ * <UI as="button" styles={{ padding: '1rem' }}>Click me</UI>
+ * ```
+ */
+type FPComponent = {
+    <C extends React.ElementType = 'span'>(props: FPProps<C>): React.ReactElement | null;
+    displayName?: string;
+};
+/**
+ * @deprecated **DEPRECATED:** This component is deprecated and will be removed in a future version.
+ * Please use the `UI` component from `./ui.tsx` instead.
+ *
+ * The UI component is a drop-in replacement with the same API but provides:
+ * - Enhanced accessibility documentation and WCAG 2.1 AA compliance guidance
+ * - Better TypeScript type safety with detailed JSDoc comments
+ * - Comprehensive examples for accessible component patterns
+ * - More robust style merging with defaultStyles support
+ *
+ * @example
+ * ```typescript
+ * // Migration Guide
+ * // Before:
+ * import FP from '@fpkit/acss/components/fp';
+ * <FP as="button" styles={{ padding: '1rem' }} classes="btn">
+ *   Click me
+ * </FP>
+ *
+ * // After:
+ * import UI from '@fpkit/acss/components/ui';
+ * <UI as="button" styles={{ padding: '1rem' }} classes="btn">
+ *   Click me
+ * </UI>
+ * ```
+ *
+ * @param {Object} props - Component props
+ * @param {React.ElementType} props.as - The HTML element to render. Defaults to 'div'.
+ * @param {boolean} props.renderStyles - Whether to render styles or not. Defaults to true.
+ * @param {Object} props.styles - The styles to apply to the component.
+ * @param {Object} props.defaultStyles - The default styles to apply to the component.
+ * @param {React.ReactNode} props.children - The children to render inside the component.
+ * @returns {React.ReactElement} - A React component that renders an HTML element with optional styles.
+ */
+declare const FP: FPComponent;
 
-export { Article, Aside, Caption, ComponentProps$1 as ComponentProps, Details, Footer, Header, ImageProps, Img, Landmarks, Main, Section, Table, Tag, TagProps, Tbody, Td, TextToSpeech, Thead, Tr };
+export { Article, Aside, Badge, BadgeProps, FP as Box, Caption, ComponentProps$1 as ComponentProps, Details, FP, Footer, Header, Img, ImgProps, Landmarks, Main, Section, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr };