@fpkit/acss 0.5.11 → 0.5.13

package/libs/index.d.cts

@@ -1,73 +1,361 @@
-import { F as FP$1, C as ComponentProps$1 } from './icons-31ace3de.js';
-export { I as Icon } from './icons-31ace3de.js';
-import * as React from 'react';
-import React__default, { ReactNode, CSSProperties } from 'react';
+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 Icon, IconProps } from './components/icons/icon.cjs';
+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';
+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';
+import { U as UI } from './ui-645f95b5.js';
+export { default as Nav, 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-3648c538.js';
+export { default as Textarea, TextareaProps } from './components/form/textarea.cjs';
+import { C as ComponentProps$1 } from './component-props-a8a2f97e.js';
+export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb.cjs';
 
-type ButtonProps = Partial<React__default.ComponentProps<typeof FP$1>> & {
+/**
+ * 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__default.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
     /**
-     * The button type
-     * Required - 'button' | 'submit' | 'reset'
+     * The image source URL.
+     * @default '//'
      */
-    type: 'button' | 'submit' | 'reset';
-};
-declare const Button: {
-    ({ type, children, styles, disabled, classes, onPointerDown, onPointerOver, onPointerLeave, onClick, ...props }: ButtonProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type CardProps = {
-    elm?: 'div' | 'aside' | 'section' | 'article';
-    title?: React__default.ReactNode;
-    footer?: React__default.ReactNode;
-} & React__default.ComponentProps<typeof FP$1>;
-declare const Card: {
-    ({ elm, styles, children, classes, id, ...props }: CardProps): React__default.JSX.Element;
-    displayName: string;
-    Title: {
-        ({ children, className, styles, as, ...props }: React__default.PropsWithChildren<{
-            className?: string | undefined;
-            styles?: React__default.CSSProperties | undefined;
-            as?: React__default.ElementType<any> | undefined;
-        }>): React__default.JSX.Element;
-        displayName: string;
-    };
-    Content: {
-        ({ children, className, styles, ...props }: React__default.PropsWithChildren<{
-            className?: string | undefined;
-            styles?: React__default.CSSProperties | undefined;
-        }>): React__default.JSX.Element;
-        displayName: string;
-    };
-    Footer: {
-        ({ children, className, styles, ...props }: React__default.PropsWithChildren<{
-            className?: string | undefined;
-            styles?: React__default.CSSProperties | undefined;
-        }>): React__default.JSX.Element;
-        displayName: string;
-    };
-};
-
-type FieldProps = {
+    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;
     /**
-     * The label content
+     * Inline styles to apply to the image.
      */
-    label: React__default.ReactNode;
-    children: React__default.ReactNode;
-} & React__default.ComponentProps<'label'> & Partial<React__default.ComponentProps<typeof FP$1>>;
+    styles?: React__default.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__default.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__default.SyntheticEvent<HTMLImageElement, Event>) => void;
+}
+
 /**
- * Field component that renders a label and children wrapped in a div element.
- * @param labelFor Defines the for attribute of the label element
- * @param styles Custom styles to be applied to the component
- * @param label The label content
- * @param children The children to be rendered inside the component
- * @param props Additional props to be spread to the component
+ * 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 Field: {
-    ({ label, labelFor, id, styles, classes, children, ...props }: FieldProps): React__default.JSX.Element;
+declare const Img: {
+    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, srcSet, sizes, onError, onLoad, ...props }: ImgProps): React__default.JSX.Element;
     displayName: string;
 };
 
-type ComponentProps = React__default.ComponentProps<typeof FP$1>;
+/**
+ * Props for the TextToSpeechComponent.
+ * @interface TextToSpeechComponentProps
+ */
+interface TextToSpeechComponentProps {
+    /** Initial text to be spoken. Defaults to an empty string. */
+    initialText?: string;
+    /** Whether to show the text input field. Defaults to true. */
+    showTextInput?: boolean;
+    /** The voice to be used for speech synthesis. */
+    voice?: SpeechSynthesisVoice | undefined;
+    /** The pitch of the voice. Defaults to 1. */
+    pitch?: number;
+    /** The rate of speech. Defaults to 1. */
+    rate?: number;
+    /** The language to be used for speech synthesis. */
+    language?: string;
+    /** Player label */
+    label?: string | React__default.ReactNode;
+    /** Callback function to be called when speech ends. */
+    onEnd?: () => void;
+}
+/**
+ * A component that converts text to speech using the Web Speech API.
+ * @param {TextToSpeechComponentProps} props - The props for the component.
+ * @returns {JSX.Element} The rendered TextToSpeechComponent.
+ */
+declare const TextToSpeech: React__default.FC<TextToSpeechComponentProps>;
+
+type ComponentProps = React__default.ComponentProps<typeof UI>;
 /**
  * Renders children elements without any wrapping component.
  * Can be used as a placeholder when no semantic landmark is needed.
@@ -131,212 +419,93 @@ declare const Section: ({ id, children, styles, classes, ...props }: ComponentPr
  */
 declare const Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.JSX.Element;
 
-type ImageProps = React__default.ComponentProps<'img'> & React__default.ComponentProps<typeof FP$1>;
-declare const Img: {
-    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, imgLoaded, imgError, ...props }: ImageProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type PolymorphicRef<C extends React__default.ElementType> = React__default.ComponentPropsWithRef<C>['ref'];
-type AsProp<C extends React__default.ElementType> = {
-    as?: C;
-};
-type PropsToOmit<C extends React__default.ElementType, P> = keyof (AsProp<C> & P);
-type PolymorphicComponentProp<C extends React__default.ElementType, Props = {}> = React__default.PropsWithChildren<Props & AsProp<C>> & Omit<React__default.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;
-type PolymorphicComponentPropWithRef<C extends React__default.ElementType, Props = {}> = PolymorphicComponentProp<C, Props> & {
-    ref?: PolymorphicRef<C>;
-};
-type FPProps<C extends React__default.ElementType> = PolymorphicComponentPropWithRef<C, {
-    renderStyles?: boolean;
-    styles?: React__default.CSSProperties;
-    classes?: string;
-}>;
-type FPComponent = <C extends React__default.ElementType = 'span'>(props: FPProps<C>) => React__default.ReactElement | any;
-/**
- * FP component is a polymorphic component that renders an HTML element with optional styles.
- * @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;
-
-type InputProps = {
-    /**
-     * The type of the input.
-     */
-    type?: "text" | "password" | "email" | "number" | "tel" | "url" | "search";
-    /**
-     * Set the element as disabled
-     */
-    isDisabled?: boolean;
-} & React__default.ComponentProps<typeof FP>;
-declare const Input: {
-    ({ type, name, value, placeholder, id, styles, classes, isDisabled, disabled, readonly, required, ref, onChange, onBlur, onPointerDown, ...props }: InputProps): JSX.Element;
-    displayName: string;
-};
-
-type LinkProps = {
-    href?: string;
-    target?: string;
-    rel?: string;
-    children: React__default.ReactNode;
-    styles?: React__default.CSSProperties;
-    prefetch?: boolean;
-    btnStyle?: string;
-    onPointerDown?: (event: React__default.PointerEvent<HTMLAnchorElement>) => void;
-} & React__default.ComponentProps<typeof FP$1> & React__default.ComponentProps<"a">;
-declare const Link: {
-    ({ href, target, rel, children, styles, prefetch, btnStyle, onPointerDown, ...props }: LinkProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type ListProps = {
-    /** Type of list to render (default: 'ul') */
-    type?: 'ul' | 'ol' | 'dl';
-    /** variant of list to render (default: 'none') */
-    variant?: string;
-} & React.ComponentProps<typeof FP$1>;
-type ListItemProps = {
-    /** Type of list item to render (default: 'li') */
-    type?: 'li' | 'dt' | 'dd';
-} & React.ComponentProps<typeof FP$1>;
 /**
- * List component renders a list element with provided props
- * @param children - Child elements to render inside the list
- * @param classes - CSS classes to apply
- * @param type - Type of list element (default: 'ul')
- * @param variant - Variant for styling purposes
- * @param styles - Inline styles object
- * @param role - ARIA role
- * @param props - Additional props to pass to underlying 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
  */
-declare const List: {
-    ({ children, classes, type, variant, styles, role, ...props }: ListProps): React.JSX.Element;
-    displayName: string;
-    ListItem: ({ type, id, styles, children, classes, ...props }: ListItemProps) => React.JSX.Element;
-};
-
-interface ModalProps extends ComponentProps$1 {
-    /**
-     * The child component/content for open button
-     */
-    openChild?: React__default.ReactNode;
-    /**
-     * The child component/content for close button
-     */
-    closeChild?: React__default.ReactNode;
-    /**
-     * The child component/content for modal header
-     */
-    modalHeader?: React__default.ReactNode;
+type BadgeProps = {
     /**
-     * The child component/content for modal footer
+     * Content to display inside the badge (typically numbers or short text)
      */
-    modalFooter?: React__default.ReactNode;
+    children?: React__default.ReactNode;
     /**
-     * The child component/content for modal body
+     * Visual variant of the badge
+     * - 'rounded': Circular badge style
      */
-    children: React__default.ReactNode;
-    /**
-     * Open modal on mount when set to true
-     */
-    showOpen?: boolean;
-}
-declare const Modal: {
-    ({ openChild, closeChild, modalHeader, modalFooter, children, showOpen, ...props }: ModalProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type NavListProps = React__default.ComponentProps<typeof List> & {
-    isBlock?: boolean;
-};
-type NavItemProps = React__default.ComponentProps<typeof List.ListItem>;
-type NavProps = React__default.ComponentProps<typeof FP$1>;
+    variant?: 'rounded';
+} & React__default.ComponentProps<typeof UI>;
 /**
- * Renders a NavList component.
- * @param {Object} props - The props for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {Object} props - Additional props to spread to the List component.
- * @returns {JSX.Element} The rendered NavList component.
- */
-declare const NavList: ({ isBlock, children, ...props }: NavListProps) => React__default.JSX.Element;
-/**
- * Renders a NavItem component.
- * @param {Object} props - The props for the component.
- * @param {string} [props.id] - The id for the component.
- * @param {Object} [props.styles] - The styles for the component.
- * @param {string} [props.classes] - The classes for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {boolean} [props.inline=true] - Whether the item should display inline.
- * @param {Object} props - Additional props to spread to the ListItem component.
- * @returns {JSX.Element} The rendered NavItem component.
- */
-declare const NavItem: ({ id, styles, classes, children, ...props }: NavItemProps) => React__default.JSX.Element;
-/**
- * Renders a Nav component.
- * @param {Object} props - The props for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {Object} props - Additional props to spread to the UI component.
- * @returns {JSX.Element} The rendered Nav component.
- */
-declare const Nav: {
-    ({ children, ...props }: NavProps): React__default.JSX.Element;
-    displayName: string;
-    List: ({ isBlock, children, ...props }: NavListProps) => React__default.JSX.Element;
-    Item: ({ id, styles, classes, children, ...props }: NavItemProps) => React__default.JSX.Element;
-};
-
-/**
- * Interface for props accepted by the Popover component
+ * Badge - A small label component for displaying status, counts, or notifications
  *
- * @property {ReactNode} children - The content to show in the popover
- * @property {ReactNode} [content] - Optional alternative content for popover
- */
-type PopoverProps = {
-    children: React__default.ReactNode;
-    popoverTrigger: React__default.ReactNode;
-    styles?: {};
-};
-/**
- * Popover component to display popover content.
+ * 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.
  *
- * @param props - The props for the component
- * @param props.children - The content to show in the popover
- * @param props.popoverTrigger - The element that triggers the popover on hover
+ * ## Styling Architecture
  *
- * @returns JSX.Element - The rendered JSX element for the Popover
- * @example - <Popover popoverTrigger={<button>Hover here</button>}>Popover content</Popover>
+ * 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).
  *
- * The component uses the usePopover hook to handle popover visibility and positioning.
+ * ## Rounded Variant Behavior
  *
- * It renders the triggerElement, and conditionally renders the popover content
- * positioned absolutely when visible.
+ * 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").
  *
- * Inline styles handle visuals like background, border, padding, etc.
+ * ## Accessibility Considerations
  *
- * Transforms and opacity animate the enter/exit transition of the popover.
- */
-declare const Popover: {
-    ({ children, popoverTrigger, styles, ...props }: PopoverProps): JSX.Element;
-    displayName: string;
-    styles: React__default.CSSProperties;
-};
-
-interface TableProps extends ComponentProps$1 {
-    tblHead: React__default.ReactNode;
-    tblBody: React__default.ReactNode;
-    tblCaption?: React__default.ReactNode;
-}
-/**
- * Render the table placing `caption`, `thead` and `tbody` in the correct order
- * caption is optional
+ * - **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 RenderTable: {
-    ({ tblBody, tblCaption, tblHead }: TableProps): React__default.JSX.Element;
+declare const Badge: {
+    ({ id, styles, classes, children, variant, ...props }: BadgeProps): React__default.JSX.Element;
     displayName: string;
 };
 
@@ -345,7 +514,7 @@ type TagProps = {
     elm?: 'span' | 'p';
     /**  Aria role for the component - conditional */
     role: 'note' | 'status';
-} & React__default.ComponentProps<typeof FP$1>;
+} & React__default.ComponentProps<typeof UI>;
 declare const Tag: {
     ({ elm, role, children, styles, ...props }: TagProps): React__default.JSX.Element;
     displayName: string;
@@ -376,211 +545,125 @@ declare const Table: {
     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;
     /**
-     * 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$1>>;
-/**3
- * Details component props interface.
- *
- * @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.
- */
-declare const Details: {
-    ({ summary, icon, styles, classes, ariaLabel, name, open, onPointerDown, onToggle, children, ref, ...props }: DetailsProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type InheritedProps = React__default.ComponentProps<typeof FP$1>;
-type TextElements = 'a' | 'b' | 'blockquote' | 'b' | 'blockquote' | 'cite' | 'code' | 'em' | 'i' | 'em' | 'i' | 'kbd' | 'mark' | 'p' | 's' | 'small' | 'span' | 'span' | 'strong' | 'mark' | 'p' | 's' | 'small' | 'span' | 'span' | 'strong' | 'sub' | 'sup' | 'time' | 'time' | 'u';
-type TextProps = {
+    icon?: React__default.ReactNode;
     /**
-     * Text element to to use
-     * Text element to to use
+     * 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"
+     * ```
      */
-    elm?: TextElements;
-    /** Pass a text element or string */
-    text?: string;
-} & InheritedProps;
-declare const Text: {
-    ({ elm, id, text, styles, classes, children, ...props }: TextProps): React__default.JSX.Element;
-    displayName: string;
-};
-type TitleProps$1 = {
+    ariaLabel?: string;
     /**
-     * HTML headings
+     * 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>
+     * ```
      */
-    elm?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-} & InheritedProps;
-declare const Title: {
-    ({ elm, id, children, styles, classes, ...props }: TitleProps$1): React__default.JSX.Element;
-    displayName: string;
-};
-
-type TextareaProps = React__default.ComponentProps<'textarea'> & React__default.ComponentProps<typeof FP$1>;
-/**
- * Textarea component.
- *
- * @param value - The value of the textarea.
- * @param rows - The number of rows.
- * @param cols - The number of columns.
- * @param id - The id of the textarea.
- * @param name - The name of the textarea.
- * @param required - Whether the textarea is required.
- * @param disabled - Whether the textarea is disabled.
- * @param readOnly - Whether the textarea is read only.
- * @param onBlur - Blur event handler.
- * @param onPointerDown - Pointer down event handler.
- * @param onChange - Change event handler.
- * @param ref - Ref for the textarea.
- * @param styles - Styles object for the textarea.
- * @param textareaRef - Ref specifically for the textarea element.
- * @param props - Other props.
- */
-declare const Textarea: {
-    ({ id, classes, value, rows, cols, name, required, disabled, readOnly, onBlur, onPointerDown, onChange, ref, styles, placeholder, ...props }: TextareaProps): React__default.JSX.Element;
-    displayName: string;
-};
-
-type TitleProps = {
-    children: React__default.ReactNode;
-    type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-    ui?: string;
-} & React__default.ComponentProps<typeof FP$1>;
-
-type customRoute = {
-    /** The path or id for routing */
-    path?: string;
-    /** The display name */
-    name: string;
-    /** The url if linking out */
-    url?: string;
-};
-type BreadcrumbProps = {
-    /** Array of custom route objects */
-    routes?: customRoute[];
-    /** Starting route node */
-    startRoute?: React__default.ReactNode;
-    startRouteUrl?: string;
-    /** Spacer node between routes */
-    spacer?: React__default.ReactNode;
-    /** String representing current route */
-    currentRoute?: string;
-    /** Prefix breadcrumb aria-label - "prefix breadcrumb" */
-    ariaLabelPrefix?: string;
-    /** Truncate breadcrumb text after this length */
-    truncateLength?: number;
-    /** Link props for breadcrumb links */
-    linkProps?: React__default.ComponentProps<typeof Link>;
-} & React__default.ComponentProps<typeof FP$1>;
-/**
- * Navigation component for breadcrumbs.
- *
- * @param props - Props for the navigation component.
- * @param props.startRoute - Starting route node. Default 'Home'.
- * @param props.currentRoute - String representing current route.
- * @param props.spacer - Spacer node between routes. Default '&#47;'.
- * @param props.routes - Array of custom route objects.
- * @param props.styles - Styles object for the nav.
- * @param props.id - Id for the nav.
- * @param props.classes - Class names for the nav.
- * @param props.children - Child components.
- */
-declare const Breadcrumb: {
-    ({ startRoute, startRouteUrl, currentRoute, spacer, routes, styles, id, classes, ariaLabelPrefix, truncateLength, linkProps, ...props }: BreadcrumbProps): React__default.JSX.Element;
-    displayName: string;
-    Nav: ({ styles, id, classes, children, ...props }: React__default.ComponentProps<typeof FP$1>) => React__default.JSX.Element;
-    List: ({ children, ...props }: React__default.ComponentProps<typeof FP$1>) => React__default.JSX.Element;
-    Items: ({ styles, id, classes, children, ...props }: React__default.ComponentProps<typeof FP$1>) => React__default.JSX.Element;
-};
-
-/**
- * Props for the TextToSpeechComponent.
- * @interface TextToSpeechComponentProps
- */
-interface TextToSpeechComponentProps {
-    /** Initial text to be spoken. Defaults to an empty string. */
-    initialText?: string;
-    /** Whether to show the text input field. Defaults to true. */
-    showTextInput?: boolean;
-    /** The voice to be used for speech synthesis. */
-    voice?: SpeechSynthesisVoice | undefined;
-    /** The pitch of the voice. Defaults to 1. */
-    pitch?: number;
-    /** The rate of speech. Defaults to 1. */
-    rate?: number;
-    /** The language to be used for speech synthesis. */
-    language?: string;
-    /** Player label */
-    label?: string | React__default.ReactNode;
-    /** Callback function to be called when speech ends. */
-    onEnd?: () => void;
-}
-/**
- * A component that converts text to speech using the Web Speech API.
- * @param {TextToSpeechComponentProps} props - The props for the component.
- * @returns {JSX.Element} The rendered TextToSpeechComponent.
- */
-declare const TextToSpeech: React__default.FC<TextToSpeechComponentProps>;
+    name?: string;
+} & React__default.ComponentProps<"details"> & Partial<React__default.ComponentProps<typeof UI>>;
 
 /**
- * Defines the props for the Dialog component.
- *
- * @property {boolean} [showDialog] - Determines whether the dialog should be shown.
- * @property {boolean} [isAlertDialog] - Determines whether the dialog should be displayed as an alert dialog.
- * @property {() => void} [onClose] - A callback function to be called when the dialog is closed.
- * @property {string} dialogTitle - The title of the dialog.
- * @property {string} [dialogLabel] - An optional label for the dialog.
- * @property {React.ReactNode} children - The content to be displayed inside the dialog.
- * @property {() => void | Promise<void>} [onConfirm] - A callback function to be called when the user confirms the dialog.
- * @property {string} [confirmLabel] - The label for the confirm button.
- * @property {string} [cancelLabel] - The label for the cancel button.
- * @property {string} [className] - An optional CSS class name to be applied to the dialog.
- * @property {CSSProperties} [styles] - Optional inline styles to be applied to the dialog.
- */
-type DialogModalProps = React__default.ComponentProps<typeof FP$1> & React__default.ComponentProps<"dialog"> & {
-    dialogTitle: string;
-    dialogLabel?: string;
-    children: React__default.ReactNode;
-    showDialog?: boolean;
-    isAlertDialog?: boolean;
-    onClose?: () => void;
-    onConfirm?: () => void | Promise<void>;
-    confirmLabel?: string;
-    cancelLabel?: string;
-    className?: string;
-    hideFooter?: boolean;
-    styles?: CSSProperties;
-};
-/**
- * Renders a dialog modal component with customizable content and behavior.
- *
- * @param showDialog - Determines whether the dialog should be shown.
- * @param isAlertDialog - Determines whether the dialog should be displayed as an alert dialog.
- * @param onClose - A callback function to be called when the dialog is closed.
- * @param dialogTitle - The title of the dialog.
- * @param dialogLabel - An optional label for the dialog.
- * @param children - The content to be displayed inside the dialog.
- * @param onConfirm - A callback function to be called when the user confirms the dialog.
- * @param confirmLabel - The label for the confirm button.
- * @param cancelLabel - The label for the cancel button.
- * @param className - An optional CSS class name to be applied to the dialog.
- * @param styles - Optional inline styles to be applied to the dialog.
+ * Details - A progressive disclosure component using native HTML `<details>` element.
+ *
+ * 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 Dialog: React__default.FC<DialogModalProps>;
+declare const Details: React__default.ForwardRefExoticComponent<Omit<DetailsProps, "ref"> & React__default.RefAttributes<HTMLDetailsElement>>;
 
-export { Article, Aside, FP as Box, Breadcrumb, Button, Caption, Card, Details, Dialog, FP, Field, Footer, Header, Img, Input, Landmarks, Link, List, Main, Modal, Nav, NavItem, NavItemProps, NavList, NavListProps, NavProps, Popover, Section, RenderTable as TBL, Table, Tag, TagProps, Tbody, Td, Text, TextProps, TextToSpeech, Textarea, TextareaProps, Thead, Title, TitleProps, Link as To, Tr };
+export { Article, Aside, Badge, BadgeProps, Caption, ComponentProps$1 as ComponentProps, Details, Footer, Header, Img, ImgProps, Landmarks, Main, Section, Table, Tag, TagProps, Tbody, Td, TextToSpeech, Thead, Tr };