import React from 'react'; /** * 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 `` element for proper navigation * * @example * ```tsx * // Basic link * About Us * * // External link with prefetch * * Visit Example * * * // Button-styled link * * Sign Up Now * * ``` */ 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 * View all products * * // ❌ Bad: Generic link text without context * Click here * * // ✅ Good: Icon with accessible label * * * * ``` */ 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 * Next Page * ``` */ 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 `` or `` tags for automatic styling: * - ``: Applies button styling * - ``: Applies pill styling * * @example * ```tsx * // Using btnStyle prop * Sign Up * * // Using child wrapper (automatic detection) * Sign Up * Pill Button * ``` */ 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 * { * trackEvent('link_click', { href: '/products' }); * }} * > * Products * * ``` */ onClick?: (event: React.MouseEvent) => 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 * { * // Distinguish between mouse (2), touch (5), and pen (3) * console.log('Pointer type:', e.pointerType); * }} * > * Products * * ``` * * @example * ```tsx * // ✅ Use both handlers together for comprehensive tracking * trackAllActivations(e)} * onPointerDown={(e) => provideFeedback(e)} * > * Products * * ``` */ onPointerDown?: (event: React.PointerEvent) => void; /** * Icon element to display in the link (used by IconLink). * * @example * ```tsx * } /> * ``` */ icon?: React.ReactNode; /** * Whether the link should be disabled. * * Anchors have no native `disabled` attribute, so this is implemented via * `aria-disabled` + the shared `useDisabledState` hook. The element stays * in tab order (WCAG 2.1.1), screen readers announce "dimmed/disabled", * click/pointerdown handlers no-op, and `href` is suppressed so keyboard * activation doesn't navigate. * * @default false * @example * ```tsx * * Edit settings * * ``` */ disabled?: boolean; /** * Additional className to merge with any disabled-state class the hook applies. */ className?: string; } & Omit, 'style' | 'className'>; /** * Link - A semantic, accessible anchor component with enhanced security and styling. * * The Link component renders accessible `` elements with automatic security * attributes for external links, customizable styling variants, and full WCAG 2.1 * AA compliance. It supports traditional text links, button-styled links, and * programmatic focus management via ref forwarding. * * ## Features * * - 🔒 **Automatic Security**: External links get `rel="noopener noreferrer"` * - ♿ **WCAG 2.1 AA Compliant**: Accessible focus indicators and semantic HTML * - 🎨 **Flexible Styling**: Text links, button links, and pill variants * - ⚡ **Performance**: Optional prefetch hints for faster navigation * - 🎯 **Ref Forwarding**: Direct DOM access for focus management and scroll * - 🧪 **Type-Safe**: Full TypeScript support with comprehensive prop types * * ## Accessibility * * - ✅ Semantic `` element for proper keyboard navigation * - ✅ Focus indicators meet WCAG 2.4.7 (3:1 contrast ratio) * - ✅ Screen readers announce link purpose and destination * - ✅ External links include security attributes automatically * - ✅ Supports `aria-label` for icon-only or ambiguous links * - ✅ Ref forwarding enables skip-link patterns * * @example * // Basic internal link * About Us * * @example * // External link with automatic security * * Visit Example * * * @example * // Button-styled call-to-action link * * Get Started * * * @example * // Icon-only link with accessible label * * * * * @example * // Analytics tracking with onClick (includes keyboard users) * trackEvent('link_click', { href: '/products' })} * > * Browse Products * * * @example * // Skip link with ref forwarding for focus management * const mainRef = useRef(null); * * * Skip to main content * * * @example * // Custom styled link with CSS variables * * Browse Products * * * @example * // ✅ GOOD: Descriptive link text * * Read installation guide * * * @example * // ❌ BAD: Generic link text (poor for screen readers) * * Click here * * * @see {@link LinkProps} for complete prop documentation */ declare const Link: React.ForwardRefExoticComponent<{ href?: string | undefined; target?: string | undefined; rel?: string | undefined; children: React.ReactNode; styles?: React.CSSProperties | undefined; prefetch?: boolean | undefined; btnStyle?: string | undefined; onClick?: ((event: React.MouseEvent) => void) | undefined; onPointerDown?: ((event: React.PointerEvent) => void) | undefined; icon?: React.ReactNode; disabled?: boolean | undefined; className?: string | undefined; } & Omit, HTMLAnchorElement>, "ref">, "style" | "className"> & React.RefAttributes>; declare const IconLink: React.ForwardRefExoticComponent<{ href?: string | undefined; target?: string | undefined; rel?: string | undefined; children: React.ReactNode; styles?: React.CSSProperties | undefined; prefetch?: boolean | undefined; btnStyle?: string | undefined; onClick?: ((event: React.MouseEvent) => void) | undefined; onPointerDown?: ((event: React.PointerEvent) => void) | undefined; icon?: React.ReactNode; disabled?: boolean | undefined; className?: string | undefined; } & Omit, HTMLAnchorElement>, "ref">, "style" | "className"> & React.RefAttributes>; declare const LinkButton: React.ForwardRefExoticComponent<{ href?: string | undefined; target?: string | undefined; rel?: string | undefined; children: React.ReactNode; styles?: React.CSSProperties | undefined; prefetch?: boolean | undefined; btnStyle?: string | undefined; onClick?: ((event: React.MouseEvent) => void) | undefined; onPointerDown?: ((event: React.PointerEvent) => void) | undefined; icon?: React.ReactNode; disabled?: boolean | undefined; className?: string | undefined; } & Omit, HTMLAnchorElement>, "ref">, "style" | "className"> & React.RefAttributes>; interface LinkComponent extends React.ForwardRefExoticComponent> { LinkButton: typeof LinkButton; IconLink: typeof IconLink; } declare const _default: LinkComponent; export { IconLink as I, LinkProps as L, _default as _, Link as a, LinkButton as b, LinkComponent as c };