@fpkit/acss 1.0.0-beta.1 → 2.0.0

package/libs/index.d.cts

@@ -4,7 +4,7 @@ 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';
@@ -328,6 +328,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 +1190,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 { 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 };

package/libs/index.d.ts

@@ -4,7 +4,7 @@ export { default as Field, FieldProps } from './components/form/fields.js';
 export { default as Input } from './components/form/inputs.js';
 export { default as Icon, IconProps } from './components/icons/icon.js';
 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.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';
@@ -328,6 +328,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 +1190,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 { 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 };

package/libs/index.js

@@ -2,24 +2,24 @@ 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 { a as Dialog } from './chunk-QKHPHMG2.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-IQ76HGVP.js';
 export { b as Heading, a as Title } from './chunk-ZFJ4U45S.js';
-export { b as Breadcrumb, a as useBreadcrumbSegments } from './chunk-X5LGFCWG.js';
+export { b as Breadcrumb, a as useBreadcrumbSegments } from './chunk-UJAQVHWC.js';
 import './chunk-GCGKYLDG.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 Modal } from './chunk-43TK2ICH.js';
+export { a as Button } from './chunk-KVKQLRJG.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';
+export { a as Link, d as To } from './chunk-NNTBIHSD.js';
 import { a } from './chunk-HHLNOC5T.js';
 import u, { useCallback, useMemo, useState, useEffect } from 'react';
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "1.0.0-beta.1",
+  "version": "2.0.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"
@@ -102,7 +102,8 @@
   "files": [
     "src",
     "libs",
-    "libs/index.css"
+    "libs/index.css",
+    "docs"
   ],
   "peerDependencies": {
     "react": "^18.0.0",
@@ -125,5 +126,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9c4bba23e1f85ae1ec81a63ec9488a5e36ff5c5b"
+  "gitHead": "c26374b7d65656bf57e002cbf44dab95ce8f0197"
 }

package/src/components/README.mdx

@@ -1,6 +1,6 @@
 import { Meta } from "@storybook/addon-docs/blocks";
 
-<Meta title="ACSS UI" />
+<Meta title="FP/ACSS UI" />
 
 # UI Component
 

package/src/components/breadcrumbs/breadcrumb.test.tsx

@@ -342,12 +342,11 @@ describe("Breadcrumb", () => {
           currentRoute="/products/shirts"
           linkProps={{
             onClick: handleClick,
-            "data-testid": "breadcrumb-link",
           }}
         />
       );
 
-      const links = screen.getAllByTestId("breadcrumb-link");
+      const links = screen.getAllByRole("link");
       expect(links.length).toBeGreaterThan(0);
 
       // Click first link

package/src/components/buttons/README.mdx

@@ -93,30 +93,38 @@ export default AdvancedButton;
 
 ### Overview
 
-The Button component now uses an **optimized disabled state implementation** that follows WCAG 2.1 Level AA accessibility guidelines. This update brings significant performance improvements and better accessibility compliance.
+The Button component now uses an **optimized disabled state implementation**
+that follows WCAG 2.1 Level AA accessibility guidelines. This update brings
+significant performance improvements and better accessibility compliance.
 
 ### Key Improvements
 
 #### 1. **ARIA-Disabled Pattern**
 
-Instead of using the native `disabled` attribute, the button uses `aria-disabled`:
+Instead of using the native `disabled` attribute, the button uses
+`aria-disabled`:
 
-- **Stays in tab order** - Screen reader users can discover and navigate to disabled buttons
-- **Allows focus** - Users can still focus disabled buttons to read tooltips or help text
-- **Prevents interactions** - All click/keyboard events are blocked when disabled
+- **Stays in tab order** - Screen reader users can discover and navigate to
+  disabled buttons
+- **Allows focus** - Users can still focus disabled buttons to read tooltips or
+  help text
+- **Prevents interactions** - All click/keyboard events are blocked when
+  disabled
 - **Better styling control** - Meets WCAG AA contrast requirements more easily
 
 #### 2. **Performance Optimizations**
 
 The new `useDisabledState` hook provides:
 
-- **~90% reduction in unnecessary re-renders** compared to previous implementation
+- **~90% reduction in unnecessary re-renders** compared to previous
+  implementation
 - **Stable handler references** - Event handlers don't recreate on every render
 - **Optimized memoization** - Single memoization pass for all props and handlers
 
 #### 3. **Automatic className Merging**
 
-The disabled state now automatically merges your custom classes with the `.is-disabled` class:
+The disabled state now automatically merges your custom classes with the
+`.is-disabled` class:
 
 ```tsx
 // Before: You had to manage className manually
@@ -188,10 +196,12 @@ This implementation follows:
 ### Related
 
 - See [useDisabledState Hook](/docs/hooks/use-disabled-state) for advanced usage
-- See [Accessibility Guide](/docs/guides/accessibility) for WCAG compliance details
+- See [Accessibility Guide](/docs/guides/accessibility) for WCAG compliance
+  details
 
 ## Additional Notes
 
 - Ensure the `type` prop is set to one of `'button'`, `'submit'`, or `'reset'`.
 - The `styles` prop can be used to apply inline styles to the button.
-- The `disabled` prop uses the accessible `aria-disabled` pattern instead of native `disabled` attribute.
+- The `disabled` prop uses the accessible `aria-disabled` pattern instead of
+  native `disabled` attribute.

package/src/components/buttons/button.scss

@@ -74,6 +74,11 @@ button {
     }
   }
 
+  &:focus-visible {
+    outline: var(--btn-focus-outline, 2px solid currentColor);
+    outline-offset: var(--btn-focus-outline-offset, 1px);
+  }
+
   &[type="reset"] {
     --btn-bg: transparent;
     --btn-color: gray;