@fpkit/acss 1.0.0 → 2.1.0

package/libs/index.d.cts

@@ -1,10 +1,11 @@
 export { Button, ButtonProps } from './components/button.cjs';
 export { Card, Content as CardContent, Footer as CardFooter, CardProps, Title as CardTitle } from './components/card.cjs';
+import React, { ReactNode } from 'react';
+import { I as IconProps } from './icons-287fce3a.js';
+export { a as Icon, b as IconProps } from './icons-287fce3a.js';
 export { default as Field, FieldProps } from './components/form/fields.cjs';
 export { default as Input } from './components/form/inputs.cjs';
-export { default as Icon, IconProps } from './components/icons/icon.cjs';
-import React, { ReactNode } from 'react';
-export { L as Link, a as LinkProps, L as To } from './link-5192f411.js';
+export { default as Link, default as To } from './components/link/link.cjs';
 export { List } from './components/list/list.cjs';
 export { Modal, ModalProps } from './components/modal.cjs';
 export { default as Popover, PopoverProps } from './components/popover/popover.cjs';
@@ -20,6 +21,161 @@ export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegme
 export { I as InputProps, T as TextareaProps } from './form.types-d25ebfac.js';
 export { L as ListItemProps } from './list.types-d26de310.js';
 
+/**
+ * Valid severity levels for alerts.
+ * Each severity has associated colors, icons, and ARIA attributes.
+ */
+type Severity = "default" | "info" | "success" | "warning" | "error";
+/**
+ * Props for the Alert component.
+ */
+type AlertProps = {
+    /**
+     * Whether the alert is open.
+     */
+    open: boolean;
+    /**
+     * The severity level of the alert.
+     * @default "default"
+     */
+    severity?: Severity;
+    /**
+     * The main message content.
+     */
+    children: React.ReactNode;
+    /**
+     * Optional title for the alert.
+     */
+    title?: string;
+    /**
+     * Whether the alert can be dismissed.
+     * @default false
+     */
+    dismissible?: boolean;
+    /**
+     * Callback when alert is dismissed.
+     */
+    onDismiss?: () => void;
+    /**
+     * Size of the severity icon in pixels.
+     * Allows customization of icon size for different contexts.
+     * @default 24
+     * @example
+     * ```tsx
+     * <Alert iconSize={32} severity="error">Larger icon</Alert>
+     * <Alert iconSize={16} severity="info">Smaller icon</Alert>
+     * ```
+     */
+    iconSize?: number;
+    /**
+     * Whether to hide the severity icon.
+     * When true, only text content is displayed.
+     * @default false
+     */
+    hideIcon?: boolean;
+    /**
+     * Additional props to pass to the Icon component.
+     * Allows fine-grained control over icon appearance.
+     * @example
+     * ```tsx
+     * <Alert iconProps={{ className: 'custom-icon', 'aria-label': 'Custom' }}>
+     *   Alert with custom icon props
+     * </Alert>
+     * ```
+     */
+    iconProps?: IconProps;
+    /**
+     * Duration in milliseconds before the alert automatically dismisses.
+     * Set to 0 or undefined to disable auto-dismiss.
+     * @default undefined
+     * @example
+     * ```tsx
+     * <Alert autoHideDuration={5000}>Success message</Alert>
+     * ```
+     */
+    autoHideDuration?: number;
+    /**
+     * Whether to pause auto-dismiss when the alert is hovered or focused.
+     * Complies with WCAG 2.2.1 (Timing Adjustable).
+     * @default true
+     */
+    pauseOnHover?: boolean;
+    /**
+     * Semantic heading level for the title (2-6).
+     * When undefined, uses <strong> element instead of heading.
+     * Use this to maintain proper heading hierarchy on the page.
+     * @default undefined
+     * @example
+     * ```tsx
+     * <Alert titleLevel={2} title="Section Alert">...</Alert>
+     * <Alert titleLevel={3} title="Subsection Alert">...</Alert>
+     * ```
+     */
+    titleLevel?: 2 | 3 | 4 | 5 | 6;
+    /**
+     * Custom action buttons to display in the alert.
+     * @example
+     * ```tsx
+     * <Alert actions={<><Button>Undo</Button><Button>Dismiss</Button></>}>
+     *   File deleted
+     * </Alert>
+     * ```
+     */
+    actions?: React.ReactNode;
+    /**
+     * Whether to automatically focus the alert when it becomes visible.
+     * Useful for critical alerts that require immediate attention.
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * Visual variant of the alert.
+     * - outlined: Border with lighter background (default)
+     * - filled: Solid colored background
+     * - soft: No border, subtle background
+     * @default "outlined"
+     */
+    variant?: "outlined" | "filled" | "soft";
+    /**
+     * Content rendering mode for alert children.
+     * Determines how the children content is wrapped in the alert message area.
+     * - "text": Wraps children in a paragraph tag (default, for simple text content)
+     * - "node": Renders children directly without wrapper (for complex layouts, lists, or custom components)
+     * @default "text"
+     * @example Simple text content (uses default "text" mode)
+     * ```tsx
+     * <Alert severity="info">
+     *   This is a simple text message that will be wrapped in a paragraph.
+     * </Alert>
+     * ```
+     * @example Complex content with list
+     * ```tsx
+     * <Alert severity="warning" contentType="node">
+     *   <p>Please review the following items:</p>
+     *   <ul>
+     *     <li>Check your email settings</li>
+     *     <li>Update your password</li>
+     *     <li>Enable two-factor authentication</li>
+     *   </ul>
+     * </Alert>
+     * ```
+     * @example Custom component layout
+     * ```tsx
+     * <Alert severity="success" contentType="node">
+     *   <div className="custom-layout">
+     *     <p>Operation completed successfully!</p>
+     *     <div className="stats">
+     *       <span>Items processed: 150</span>
+     *       <span>Time elapsed: 2.5s</span>
+     *     </div>
+     *   </div>
+     * </Alert>
+     * ```
+     */
+    contentType?: "text" | "node";
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "title" | "children">;
+declare const Alert: React.FC<AlertProps>;
+
 /**
  * Props for the Img component.
  *
@@ -328,6 +484,241 @@ declare const Img: {
     displayName: string;
 };
 
+/**
+ * Props for the Link component.
+ *
+ * The Link component renders accessible anchor elements with enhanced security,
+ * styling variants, and WCAG 2.1 AA compliance. It supports both traditional
+ * text links and button-styled links for call-to-action scenarios.
+ *
+ * ## Accessibility Considerations
+ *
+ * - External links automatically include `rel="noopener noreferrer"` for security
+ * - Links should have descriptive text or `aria-label` for screen readers
+ * - Focus indicators must meet WCAG 2.4.7 contrast requirements (3:1 minimum)
+ * - Button-styled links maintain semantic `<a>` element for proper navigation
+ *
+ * @example
+ * ```tsx
+ * // Basic link
+ * <Link href="/about">About Us</Link>
+ *
+ * // External link with prefetch
+ * <Link href="https://example.com" target="_blank" prefetch>
+ *   Visit Example
+ * </Link>
+ *
+ * // Button-styled link
+ * <Link href="/signup" btnStyle="primary">
+ *   <b>Sign Up Now</b>
+ * </Link>
+ * ```
+ */
+type LinkProps = {
+    /**
+     * The URL that the hyperlink points to.
+     * Can be relative or absolute, internal or external.
+     *
+     * @example
+     * ```tsx
+     * href="/products"
+     * href="https://example.com"
+     * href="mailto:hello@example.com"
+     * href="tel:+1234567890"
+     * ```
+     */
+    href?: string;
+    /**
+     * Where to display the linked URL.
+     *
+     * - `_self` (default): Current browsing context
+     * - `_blank`: New tab/window (automatically adds security attributes)
+     * - `_parent`: Parent browsing context
+     * - `_top`: Top-level browsing context
+     *
+     * Note: When `target="_blank"`, `rel="noopener noreferrer"` is automatically
+     * added for security unless explicitly overridden.
+     *
+     * @example
+     * ```tsx
+     * target="_blank" // Opens in new tab with security
+     * ```
+     */
+    target?: string;
+    /**
+     * Relationship between current document and linked URL.
+     *
+     * Common values:
+     * - `noopener`: Prevents window.opener access (security)
+     * - `noreferrer`: Prevents referrer header (privacy)
+     * - `nofollow`: Hints search engines not to follow (SEO)
+     * - `prefetch`: Hints to prefetch the resource (performance)
+     *
+     * Note: For `target="_blank"`, this component automatically merges
+     * `noopener noreferrer` with any user-provided values for security.
+     *
+     * @example
+     * ```tsx
+     * rel="nofollow noopener"
+     * rel="author"
+     * ```
+     */
+    rel?: string;
+    /**
+     * Content to display inside the link.
+     *
+     * For accessibility, ensure link text is descriptive and meaningful.
+     * Avoid generic text like "click here" or "read more" without context.
+     *
+     * @example
+     * ```tsx
+     * // ✅ Good: Descriptive link text
+     * <Link href="/products">View all products</Link>
+     *
+     * // ❌ Bad: Generic link text without context
+     * <Link href="/products">Click here</Link>
+     *
+     * // ✅ Good: Icon with accessible label
+     * <Link href="/home" aria-label="Return to homepage">
+     *   <HomeIcon aria-hidden="true" />
+     * </Link>
+     * ```
+     */
+    children: React.ReactNode;
+    /**
+     * Inline CSS styles to apply to the link element.
+     * Can be used to override CSS custom properties.
+     *
+     * @example
+     * ```tsx
+     * styles={{
+     *   '--link-color': '#ff0000',
+     *   '--link-decoration': 'underline',
+     * }}
+     * ```
+     */
+    styles?: React.CSSProperties;
+    /**
+     * Hints to the browser to prefetch the linked resource.
+     *
+     * When `true` and `target="_blank"`, adds `rel="prefetch"` along with
+     * security attributes. This can improve perceived performance but should
+     * be used judiciously as it consumes bandwidth.
+     *
+     * Note: Browser support varies. Modern browsers may ignore this hint.
+     *
+     * @default false
+     * @example
+     * ```tsx
+     * <Link href="/next-page" prefetch>Next Page</Link>
+     * ```
+     */
+    prefetch?: boolean;
+    /**
+     * Applies button-like styling to the link.
+     *
+     * When set, the link renders with button styling including padding,
+     * borders, and hover effects while maintaining semantic anchor behavior.
+     *
+     * Common values:
+     * - `"btn"`: Standard button styling
+     * - `"pill"`: Rounded pill button styling
+     *
+     * Alternative: Wrap children in `<b>` or `<i>` tags for automatic styling:
+     * - `<b>`: Applies button styling
+     * - `<i>`: Applies pill styling
+     *
+     * @example
+     * ```tsx
+     * // Using btnStyle prop
+     * <Link href="/signup" btnStyle="btn">Sign Up</Link>
+     *
+     * // Using child wrapper (automatic detection)
+     * <Link href="/signup"><b>Sign Up</b></Link>
+     * <Link href="/signup"><i>Pill Button</i></Link>
+     * ```
+     */
+    btnStyle?: string;
+    /**
+     * Event handler called when the link is clicked or activated.
+     *
+     * **Recommended for most use cases**, especially analytics and tracking.
+     * This event fires for:
+     * - Mouse clicks
+     * - Touch/tap interactions
+     * - Keyboard activation (Enter key)
+     * - Assistive technology activation
+     *
+     * Use `onClick` when you need to track ALL user activations, including
+     * keyboard users. This ensures full accessibility coverage.
+     *
+     * @param event - The mouse event
+     * @example
+     * ```tsx
+     * // ✅ RECOMMENDED: onClick tracks all activation methods
+     * <Link
+     *   href="/products"
+     *   onClick={(e) => {
+     *     trackEvent('link_click', { href: '/products' });
+     *   }}
+     * >
+     *   Products
+     * </Link>
+     * ```
+     */
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+    /**
+     * Event handler called when a pointer device button is pressed on the link.
+     *
+     * Use this for specific pointer interactions like:
+     * - Drag-and-drop detection
+     * - Touch gesture recognition
+     * - Distinguishing input types (mouse vs touch vs pen)
+     * - Providing early visual feedback before click completes
+     *
+     * **⚠️ Accessibility Note**: Unlike `onClick`, this does NOT fire for
+     * keyboard activation (Enter key). If you need to track all user interactions
+     * including keyboard users, use `onClick` instead.
+     *
+     * @param event - The pointer event
+     * @example
+     * ```tsx
+     * // Use onPointerDown for pointer-specific interactions
+     * <Link
+     *   href="/products"
+     *   onPointerDown={(e) => {
+     *     // Distinguish between mouse (2), touch (5), and pen (3)
+     *     console.log('Pointer type:', e.pointerType);
+     *   }}
+     * >
+     *   Products
+     * </Link>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // ✅ Use both handlers together for comprehensive tracking
+     * <Link
+     *   href="/products"
+     *   onClick={(e) => trackAllActivations(e)}
+     *   onPointerDown={(e) => provideFeedback(e)}
+     * >
+     *   Products
+     * </Link>
+     * ```
+     */
+    onPointerDown?: (event: React.PointerEvent<HTMLAnchorElement>) => void;
+    /**
+     * Icon element to display in the link (used by IconLink).
+     *
+     * @example
+     * ```tsx
+     * <IconLink href="/home" icon={<HomeIcon />} />
+     * ```
+     */
+    icon?: React.ReactNode;
+} & Omit<React.ComponentPropsWithoutRef<"a">, 'style'>;
+
 /**
  * Props for the TextToSpeechComponent.
  * @interface TextToSpeechComponentProps
@@ -955,4 +1346,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-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 };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, FP as Box, Caption, ComponentProps$1 as ComponentProps, Details, FP, Footer, Header, Img, ImgProps, Landmarks, LinkProps, Main, Section, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };