@fpkit/acss 0.5.13 → 0.6.0

package/libs/index.d.ts

@@ -1,22 +1,24 @@
 export { Button, ButtonProps } from './components/button.js';
 export { Card, Content as CardContent, Footer as CardFooter, CardProps, Title as CardTitle } from './components/card.js';
 export { default as Field, FieldProps } from './components/form/fields.js';
-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.js';
 export { default as Icon, IconProps } from './components/icons/icon.js';
-import React__default, { ReactNode } from 'react';
-export { default as Link, LinkProps, default as To } from './components/link/link.js';
-export { default as List, ListItemProps } from './components/list/list.js';
+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.js';
 export { Modal, ModalProps } from './components/modal.js';
 export { default as Popover, PopoverProps } from './components/popover/popover.js';
 export { RenderTable as TBL, TableProps } from './components/tables/table.js';
 export { Dialog } from './components/dialog/dialog.js';
-import { U as UI } from './ui-645f95b5.js';
-export { default as Nav, NavItem, NavItemProps, NavList, NavListProps, NavProps } from './components/nav/nav.js';
+import { U as UI } from './ui-d01b50d4.js';
+export { Nav, NavComponent, NavItem, NavItemProps, NavList, NavListProps, NavProps } from './components/nav/nav.js';
 export { default as Text, TextProps } from './components/text/text.js';
-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.js';
-import { C as ComponentProps$1 } from './component-props-a8a2f97e.js';
+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.js';
+import { C as ComponentProps$1 } from './component-props-67d978a2.js';
 export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb.js';
+export { I as InputProps, T as TextareaProps } from './form.types-d25ebfac.js';
+export { L as ListItemProps } from './list.types-d26de310.js';
 
 /**
  * Props for the Img component.
@@ -63,7 +65,7 @@ export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegme
  *
  * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
  */
-interface ImgProps extends Omit<React__default.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
+interface ImgProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
     /**
      * The image source URL.
      * @default '//'
@@ -97,7 +99,7 @@ interface ImgProps extends Omit<React__default.ImgHTMLAttributes<HTMLImageElemen
     /**
      * Inline styles to apply to the image.
      */
-    styles?: React__default.CSSProperties;
+    styles?: React.CSSProperties;
     /**
      * Loading behavior for the image.
      * - `"lazy"` (default): Defers loading until near viewport
@@ -197,7 +199,7 @@ interface ImgProps extends Omit<React__default.ImgHTMLAttributes<HTMLImageElemen
      * />
      * ```
      */
-    onError?: (event: React__default.SyntheticEvent<HTMLImageElement, Event>) => void;
+    onError?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void;
     /**
      * Callback fired when the image successfully loads.
      *
@@ -212,7 +214,7 @@ interface ImgProps extends Omit<React__default.ImgHTMLAttributes<HTMLImageElemen
      * />
      * ```
      */
-    onLoad?: (event: React__default.SyntheticEvent<HTMLImageElement, Event>) => void;
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void;
 }
 
 /**
@@ -322,7 +324,7 @@ interface ImgProps extends Omit<React__default.ImgHTMLAttributes<HTMLImageElemen
  * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
  */
 declare const Img: {
-    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, srcSet, sizes, onError, onLoad, ...props }: ImgProps): React__default.JSX.Element;
+    ({ src, alt, width, height, styles, loading, placeholder, fetchpriority, decoding, srcSet, sizes, onError, onLoad, ...props }: ImgProps): React.JSX.Element;
     displayName: string;
 };
 
@@ -344,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;
 }
@@ -353,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 UI>;
+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;
@@ -382,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.
  *
@@ -392,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.
@@ -400,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.
  *
@@ -409,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.
  *
@@ -417,7 +419,7 @@ 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
@@ -434,13 +436,13 @@ type BadgeProps = {
     /**
      * Content to display inside the badge (typically numbers or short text)
      */
-    children?: React__default.ReactNode;
+    children?: React.ReactNode;
     /**
      * Visual variant of the badge
      * - 'rounded': Circular badge style
      */
     variant?: 'rounded';
-} & React__default.ComponentProps<typeof UI>;
+} & React.ComponentProps<typeof UI>;
 /**
  * Badge - A small label component for displaying status, counts, or notifications
  *
@@ -505,43 +507,229 @@ type BadgeProps = {
  * <Badge>12</Badge>
  */
 declare const Badge: {
-    ({ id, styles, classes, children, variant, ...props }: BadgeProps): React__default.JSX.Element;
+    ({ 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 UI>;
+    /**
+     * 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;
 };
 
@@ -576,7 +764,7 @@ type DetailsProps = {
      * summary={<><Icon /> Shipping Information</>}
      * ```
      */
-    summary: React__default.ReactNode;
+    summary: React.ReactNode;
     /**
      * Optional icon displayed before the summary text.
      * Commonly used for chevron/arrow indicators.
@@ -586,7 +774,7 @@ type DetailsProps = {
      * icon={<ChevronDownIcon />}
      * ```
      */
-    icon?: React__default.ReactNode;
+    icon?: React.ReactNode;
     /**
      * Accessible label for screen readers.
      * If not provided, the native `<details>` semantic will be used.
@@ -613,7 +801,7 @@ type DetailsProps = {
      * ```
      */
     name?: string;
-} & React__default.ComponentProps<"details"> & Partial<React__default.ComponentProps<typeof UI>>;
+} & React.ComponentProps<"details"> & Partial<React.ComponentProps<typeof UI>>;
 
 /**
  * Details - A progressive disclosure component using native HTML `<details>` element.
@@ -664,6 +852,107 @@ type DetailsProps = {
  * <Details name="faq" summary="Question 3">Answer 3</Details>
  * ```
  */
-declare const Details: React__default.ForwardRefExoticComponent<Omit<DetailsProps, "ref"> & React__default.RefAttributes<HTMLDetailsElement>>;
+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, Badge, BadgeProps, Caption, ComponentProps$1 as ComponentProps, Details, Footer, Header, Img, ImgProps, 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 };

package/libs/index.js

@@ -1,27 +1,29 @@
-import { b } from './chunk-XBA562WW.js';
-export { a as Textarea } from './chunk-XBA562WW.js';
-export { a as Field } from './chunk-RIVUMPOG.js';
-export { a as Caption, i as TBL, f as Table, c as Tbody, e as Td, b as Thead, d as Tr } from './chunk-5M57K4SW.js';
-export { a as Dialog } from './chunk-VUH3FXGJ.js';
-export { c as Nav, b as NavItem, a as NavList } from './chunk-2Y7W75TT.js';
-export { b as List } from './chunk-SMYRLO3E.js';
+import { b } from './chunk-IRLFZ3OL.js';
+export { a as Textarea } from './chunk-IRLFZ3OL.js';
+export { a as Field } from './chunk-HRRHPLER.js';
+export { a as Caption, i as TBL, f as Table, c as Tbody, e as Td, b as Thead, d as Tr } from './chunk-Y2PFDELK.js';
+export { a as Dialog } from './chunk-X3JCTEPD.js';
+export { c as Nav, b as NavItem, a as NavList } from './chunk-FVROL3V5.js';
+export { b as List } from './chunk-IEB64SWY.js';
 export { b as Popover } from './chunk-23ANBDCR.js';
-export { a as Text } from './chunk-NGTJDDFO.js';
-export { b as Heading, a as Title } from './chunk-ETFLFC2S.js';
-export { b as Breadcrumb, a as useBreadcrumbSegments } from './chunk-GZ4QFPRY.js';
+export { a as Text } from './chunk-IQ76HGVP.js';
+export { b as Heading, a as Title } from './chunk-ZFJ4U45S.js';
+export { b as Breadcrumb, a as useBreadcrumbSegments } from './chunk-X5LGFCWG.js';
 import './chunk-GCGKYLDG.js';
-import { b as b$1 } from './chunk-772NRB75.js';
-export { a as Icon } from './chunk-772NRB75.js';
-export { d as Card, b as CardContent, c as CardFooter, a as CardTitle } from './chunk-JJ43O4Y5.js';
-export { a as Modal } from './chunk-ZANSFMTD.js';
-export { a as Button } from './chunk-QLZWHAMK.js';
-export { a as Input } from './chunk-BHRQBJRY.js';
-export { a as Box, a as FP } from './chunk-P7TTEYCD.js';
-export { a as Link, b as To } from './chunk-TYRCEX2L.js';
-import { a } from './chunk-KUKIVRC2.js';
+import { b as b$1 } from './chunk-5QD3DWFI.js';
+export { a as Icon } from './chunk-5QD3DWFI.js';
+export { d as Card, b as CardContent, c as CardFooter, a as CardTitle } from './chunk-KK47SYZI.js';
+export { a as Modal } from './chunk-7XPFW7CB.js';
+export { a as Button } from './chunk-OVWLQYMK.js';
+export { a as Input } from './chunk-F5EYMVQM.js';
+export { a as Box, a as FP } from './chunk-6SAHIYCZ.js';
+import './chunk-BFK62VX5.js';
+import './chunk-75QHTLFO.js';
+export { a as Link, b as To } from './chunk-UEPAWMDF.js';
+import { a } from './chunk-HHLNOC5T.js';
 import u, { useCallback, useMemo, useState, useEffect } from 'react';
 
-var M=({src:e="//",alt:t,width:s=480,height:n,styles:r,loading:l="lazy",placeholder:m,fetchpriority:c="low",decoding:d="auto",srcSet:T,sizes:x,onError:y,onLoad:P,...C})=>{let h=useMemo(()=>{let o=typeof s=="number"?s:480,p=typeof n=="number"?n:Math.round(o*.75),i=`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${o} ${p}">
+var V=({src:e="//",alt:s,width:t=480,height:n,styles:r,loading:i="lazy",placeholder:c,fetchpriority:m="low",decoding:d="auto",srcSet:T,sizes:x,onError:y,onLoad:P,...C})=>{let h=useMemo(()=>{let o=typeof t=="number"?t:480,p=typeof n=="number"?n:Math.round(o*.75),l=`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${o} ${p}">
       <defs>
         <linearGradient id="grad-${o}-${p}" x1="0%" y1="0%" x2="100%" y2="100%">
           <stop offset="0%" style="stop-color:#6366f1;stop-opacity:1" />
@@ -33,8 +35,8 @@ var M=({src:e="//",alt:t,width:s=480,height:n,styles:r,loading:l="lazy",placehol
       <circle cx="${o*.15}" cy="${p*.2}" r="${Math.min(o,p)*.08}" fill="rgba(255,255,255,0.2)"/>
       <path d="M0,${p*.75} Q${o*.25},${p*.65} ${o*.5},${p*.75} T${o},${p*.75} L${o},${p} L0,${p} Z" fill="rgba(0,0,0,0.15)"/>
       <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="system-ui,-apple-system,sans-serif" font-size="${Math.max(16,Math.min(o,p)*.05)}" font-weight="500" fill="rgba(255,255,255,0.9)">${o}\xD7${p}</text>
-    </svg>`;return `data:image/svg+xml,${encodeURIComponent(i)}`},[s,n]),w=m??h;return u.createElement(a,{as:"img",src:e,alt:t,width:s,height:n||"auto",loading:l,style:r,srcSet:T,sizes:x,onError:o=>{y&&y(o),o.defaultPrevented||o.currentTarget.src!==w&&(o.currentTarget.src=w);},onLoad:o=>{P?.(o);},decoding:d,...C,...c&&{fetchpriority:c}})};M.displayName="Img";var V=e=>{let[t,s]=useState([]),[n,r]=useState(e),[l,m]=useState(!1),[c,d]=useState(!1),[T,x]=useState(null);return useEffect(()=>{let f=()=>{let o=window.speechSynthesis.getVoices();s(o);let p=o.find(i=>i.name==="Google US English");if(p)r(p);else {let i=o.find($=>$.lang.startsWith("en-"));i&&r(i);}};return f(),window.speechSynthesis.onvoiceschanged=f,()=>{window.speechSynthesis.onvoiceschanged=null;}},[]),{speak:(f,o={},p)=>{let i=new SpeechSynthesisUtterance(f);i.lang=o.lang??"en-US",i.pitch=o.pitch??1,i.rate=o.rate??1,i.voice=n??o.voice??null,i.onend=()=>{m(!1),d(!1),p&&p();},"speechSynthesis"in window?(window.speechSynthesis.speak(i),x(i),m(!0),d(!1)):console.error("Speech synthesis not supported");},pause:()=>{l&&!c&&(window.speechSynthesis.pause(),d(!0));},resume:()=>{l&&c&&(window.speechSynthesis.resume(),d(!1));},cancel:()=>{l&&(window.speechSynthesis.cancel(),m(!1),d(!1));},isSpeaking:l,isPaused:c,availableVoices:t,changeVoice:f=>{r(f);},currentVoice:n,getAvailableLanguages:()=>[...new Set(t.map(f=>f.lang))]}};var pe=({children:e,onClick:t})=>u.createElement(a,{as:"button",type:"button",className:"tts-border","data-btn":"sm text pill",onClick:t},e),U=u.memo(pe),L=({label:e,isSpeaking:t,isPaused:s,onSpeak:n,onPause:r,onResume:l,onCancel:m})=>u.createElement(a,{as:"div","data-tts":!0},e&&u.createElement("p",null,e),!t&&u.createElement(U,{"aria-label":"Speak",onClick:n},u.createElement(b$1.PlaySolid,{size:16})),t&&!s&&u.createElement(U,{"aria-label":"Pause",onClick:r},u.createElement(b$1.PauseSolid,{size:16})),s&&u.createElement(U,{"aria-label":"Resume",onClick:l},u.createElement(b$1.ResumeSolid,{size:16})),u.createElement(U,{"aria-label":"Stop",onClick:m},u.createElement(b$1.StopSolid,{size:16})));L.displayName="TextToSpeechControls";L.TTSButton=U;var H=L;var z=({initialText:e="",showTextInput:t=!1,voice:s,pitch:n=1,rate:r=1,language:l,label:m,onEnd:c})=>{let{speak:d,pause:T,resume:x,cancel:y,isSpeaking:P,isPaused:C,getAvailableLanguages:h,availableVoices:w}=V(),[I,f]=useState(e);console.log(h()),useEffect(()=>{f(e);},[e]);let o=()=>{I.trim()!==""&&d(I,{voice:s,pitch:n,rate:r},i);},p=$=>{f($.target.value);},i=()=>{c&&c();};return u.createElement(u.Fragment,null,t&&u.createElement(b,{value:I,onChange:p}),u.createElement(H,{label:m,isSpeaking:P,isPaused:C,onSpeak:o,onPause:T,onResume:x,onCancel:y}))};z.displayName="TextToSpeechComponent";var S=e=>u.createElement(u.Fragment,null,e),ce=({id:e,children:t,headerBackground:s,styles:n,classes:r,...l})=>u.createElement(a,{as:"header",id:e,styles:n,className:r,...l},s,u.createElement(a,{as:"section"},t)),me=({id:e,children:t,styles:s,classes:n,...r})=>u.createElement(a,{as:"main",id:e,styles:s,...r,className:n},t),de=({id:e,classes:t,children:s,styles:n={},...r})=>u.createElement(a,{as:"footer",id:e,className:t,styles:n,...r},u.createElement(a,{as:"section"},s||"Copyright \xA9 2022")),fe=({id:e,children:t,styles:s={},classes:n,...r})=>u.createElement(a,{as:"aside",id:e,styles:s,className:n,...r},u.createElement(a,{as:"section"},t)),ue=({id:e,children:t,styles:s,classes:n,...r})=>u.createElement(a,{as:"section",id:e,styles:s,className:n,...r},t),ge=({id:e,children:t,styles:s,classes:n,...r})=>u.createElement(a,{as:"article",id:e,styles:s,className:n,...r},t);S.displayName="Landmarks";S.Header=ce;S.Main=me;S.Footer=de;S.Aside=fe;S.Section=ue;S.Article=ge;var A=({id:e,styles:t,classes:s,children:n,variant:r,...l})=>u.createElement(a,{as:"sup",id:e,styles:t,className:s,"data-badge":r||void 0,role:"status",...l},u.createElement(a,{as:"span"},n));A.displayName="Badge";var xe=({elm:e="span",role:t="note",children:s,styles:n,...r})=>u.createElement(a,{as:e,role:t,styles:n,...r},s);xe.displayName="Tag";var ye=u.forwardRef(({summary:e,icon:t,styles:s,classes:n,ariaLabel:r,name:l,open:m,onPointerDown:c,onToggle:d,children:T,...x},y)=>{let P=useCallback(h=>{c?.(h);},[c]),C=useCallback(h=>{d?.(h);},[d]);return u.createElement(a,{as:"details",styles:s,classes:n,onToggle:C,ref:y,open:m,"aria-label":r,name:l,...x},u.createElement(a,{as:"summary",onPointerDown:P},t,e),u.createElement(a,{as:"section"},T))});ye.displayName="Details";
+    </svg>`;return `data:image/svg+xml,${encodeURIComponent(l)}`},[t,n]),w=c??h;return u.createElement(a,{as:"img",src:e,alt:s,width:t,height:n||"auto",loading:i,style:r,srcSet:T,sizes:x,onError:o=>{y&&y(o),o.defaultPrevented||o.currentTarget.src!==w&&(o.currentTarget.src=w);},onLoad:o=>{P?.(o);},decoding:d,...C,...m&&{fetchpriority:m}})};V.displayName="Img";var M=e=>{let[s,t]=useState([]),[n,r]=useState(e),[i,c]=useState(!1),[m,d]=useState(!1),[T,x]=useState(null);return useEffect(()=>{let f=()=>{let o=window.speechSynthesis.getVoices();t(o);let p=o.find(l=>l.name==="Google US English");if(p)r(p);else {let l=o.find($=>$.lang.startsWith("en-"));l&&r(l);}};return f(),window.speechSynthesis.onvoiceschanged=f,()=>{window.speechSynthesis.onvoiceschanged=null;}},[]),{speak:(f,o={},p)=>{let l=new SpeechSynthesisUtterance(f);l.lang=o.lang??"en-US",l.pitch=o.pitch??1,l.rate=o.rate??1,l.voice=n??o.voice??null,l.onend=()=>{c(!1),d(!1),p&&p();},"speechSynthesis"in window?(window.speechSynthesis.speak(l),x(l),c(!0),d(!1)):console.error("Speech synthesis not supported");},pause:()=>{i&&!m&&(window.speechSynthesis.pause(),d(!0));},resume:()=>{i&&m&&(window.speechSynthesis.resume(),d(!1));},cancel:()=>{i&&(window.speechSynthesis.cancel(),c(!1),d(!1));},isSpeaking:i,isPaused:m,availableVoices:s,changeVoice:f=>{r(f);},currentVoice:n,getAvailableLanguages:()=>[...new Set(s.map(f=>f.lang))]}};var pe=({children:e,onClick:s})=>u.createElement(a,{as:"button",type:"button",className:"tts-border","data-btn":"sm text pill",onClick:s},e),U=u.memo(pe),L=({label:e,isSpeaking:s,isPaused:t,onSpeak:n,onPause:r,onResume:i,onCancel:c})=>u.createElement(a,{as:"div","data-tts":!0},e&&u.createElement("p",null,e),!s&&u.createElement(U,{"aria-label":"Speak",onClick:n},u.createElement(b$1.PlaySolid,{size:16})),s&&!t&&u.createElement(U,{"aria-label":"Pause",onClick:r},u.createElement(b$1.PauseSolid,{size:16})),t&&u.createElement(U,{"aria-label":"Resume",onClick:i},u.createElement(b$1.ResumeSolid,{size:16})),u.createElement(U,{"aria-label":"Stop",onClick:c},u.createElement(b$1.StopSolid,{size:16})));L.displayName="TextToSpeechControls";L.TTSButton=U;var H=L;var z=({initialText:e="",showTextInput:s=!1,voice:t,pitch:n=1,rate:r=1,language:i,label:c,onEnd:m})=>{let{speak:d,pause:T,resume:x,cancel:y,isSpeaking:P,isPaused:C,getAvailableLanguages:h,availableVoices:w}=M(),[I,f]=useState(e);console.log(h()),useEffect(()=>{f(e);},[e]);let o=()=>{I.trim()!==""&&d(I,{voice:t,pitch:n,rate:r},l);},p=$=>{f($.target.value);},l=()=>{m&&m();};return u.createElement(u.Fragment,null,s&&u.createElement(b,{value:I,onChange:p}),u.createElement(H,{label:c,isSpeaking:P,isPaused:C,onSpeak:o,onPause:T,onResume:x,onCancel:y}))};z.displayName="TextToSpeechComponent";var S=e=>u.createElement(u.Fragment,null,e),ce=({id:e,children:s,headerBackground:t,styles:n,classes:r,...i})=>u.createElement(a,{as:"header",id:e,styles:n,className:r,...i},t,u.createElement(a,{as:"section"},s)),me=({id:e,children:s,styles:t,classes:n,...r})=>u.createElement(a,{as:"main",id:e,styles:t,...r,className:n},s),de=({id:e,classes:s,children:t,styles:n={},...r})=>u.createElement(a,{as:"footer",id:e,className:s,styles:n,...r},u.createElement(a,{as:"section"},t||"Copyright \xA9 2022")),fe=({id:e,children:s,styles:t={},classes:n,...r})=>u.createElement(a,{as:"aside",id:e,styles:t,className:n,...r},u.createElement(a,{as:"section"},s)),ue=({id:e,children:s,styles:t,classes:n,...r})=>u.createElement(a,{as:"section",id:e,styles:t,className:n,...r},s),ge=({id:e,children:s,styles:t,classes:n,...r})=>u.createElement(a,{as:"article",id:e,styles:t,className:n,...r},s);S.displayName="Landmarks";S.Header=ce;S.Main=me;S.Footer=de;S.Aside=fe;S.Section=ue;S.Article=ge;var A=({id:e,styles:s,classes:t,children:n,variant:r,...i})=>u.createElement(a,{as:"sup",id:e,styles:s,className:t,"data-badge":r||void 0,role:"status",...i},u.createElement(a,{as:"span"},n));A.displayName="Badge";var xe=({elm:e="span",role:s="note",variant:t,children:n,styles:r,...i})=>u.createElement(a,{as:e,role:s,"data-tag":t||void 0,styles:r,...i},n);xe.displayName="Tag";var ye=u.forwardRef(({summary:e,icon:s,styles:t,classes:n,ariaLabel:r,name:i,open:c,onPointerDown:m,onToggle:d,children:T,...x},y)=>{let P=useCallback(h=>{m?.(h);},[m]),C=useCallback(h=>{d?.(h);},[d]);return u.createElement(a,{as:"details",styles:t,classes:n,onToggle:C,ref:y,open:c,"aria-label":r,name:i,...x},u.createElement(a,{as:"summary",onPointerDown:P},s,e),u.createElement(a,{as:"section"},T))});ye.displayName="Details";
 
-export { ge as Article, fe as Aside, A as Badge, ye as Details, de as Footer, ce as Header, M as Img, S as Landmarks, me as Main, ue as Section, xe as Tag, z as TextToSpeech };
+export { ge as Article, fe as Aside, A as Badge, ye as Details, de as Footer, ce as Header, V as Img, S as Landmarks, me as Main, ue as Section, xe as Tag, z as TextToSpeech };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map