@fpkit/acss 0.5.12 → 0.5.13

package/libs/index.d.cts

@@ -3,7 +3,6 @@ export { Card, Content as CardContent, Footer as CardFooter, CardProps, Title as
 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 { 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';
@@ -11,16 +10,319 @@ 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, Title } from './components/text/text.cjs';
-export { TitleProps } from './components/heading/heading.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 } from './components/breadcrumbs/breadcrumb.cjs';
+export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb.cjs';
 
-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__default.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__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;
+}
+
+/**
+ * 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__default.JSX.Element;
     displayName: string;
 };
 
@@ -53,7 +355,7 @@ interface TextToSpeechComponentProps {
  */
 declare const TextToSpeech: React__default.FC<TextToSpeechComponentProps>;
 
-type ComponentProps = React__default.ComponentProps<typeof FP>;
+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.
@@ -117,12 +419,102 @@ declare const Section: ({ id, children, styles, classes, ...props }: ComponentPr
  */
 declare const Article: ({ id, children, styles, classes, ...props }: ComponentProps) => React__default.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__default.ReactNode;
+    /**
+     * Visual variant of the badge
+     * - 'rounded': Circular badge style
+     */
+    variant?: 'rounded';
+} & React__default.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__default.JSX.Element;
+    displayName: string;
+};
+
 type TagProps = {
     /** HTML element to display the badge as span or p */
     elm?: 'span' | 'p';
     /**  Aria role for the component - conditional */
     role: 'note' | 'status';
-} & React__default.ComponentProps<typeof FP>;
+} & React__default.ComponentProps<typeof UI>;
 declare const Tag: {
     ({ elm, role, children, styles, ...props }: TagProps): React__default.JSX.Element;
     displayName: string;
@@ -153,33 +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.
-     */
-    ariaLabel: string;
-} & React__default.ComponentProps<"details"> & Partial<React__default.ComponentProps<typeof FP>>;
-/**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.
+     * Optional icon displayed before the summary text.
+     * Commonly used for chevron/arrow indicators.
+     *
+     * @example
+     * ```tsx
+     * icon={<ChevronDownIcon />}
+     * ```
+     */
+    icon?: React__default.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__default.ComponentProps<"details"> & Partial<React__default.ComponentProps<typeof UI>>;
+
+/**
+ * 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 Details: {
-    ({ summary, icon, styles, classes, ariaLabel, name, open, onPointerDown, onToggle, children, ref, ...props }: DetailsProps): React__default.JSX.Element;
-    displayName: string;
-};
+declare const Details: React__default.ForwardRefExoticComponent<Omit<DetailsProps, "ref"> & React__default.RefAttributes<HTMLDetailsElement>>;
 
-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, Caption, ComponentProps$1 as ComponentProps, Details, Footer, Header, Img, ImgProps, Landmarks, Main, Section, Table, Tag, TagProps, Tbody, Td, TextToSpeech, Thead, Tr };