@fpkit/acss 0.5.13 → 0.6.0

package/src/components/nav/nav.scss

@@ -21,7 +21,7 @@ body > nav,
       padding-inline: var(--nav-px, 0.75rem);
 
       &:hover {
-        background-color: var(--nav-hov-bg, whitesmoke);
+        background-color: var(--nav-hov-bg, #e8e8e8);
       }
       &:hover:where(img) {
         background-color: transparent;
@@ -31,6 +31,12 @@ body > nav,
 }
 
 nav {
+  // Focus Indicator Variables (WCAG 2.4.7 - 3:1 contrast minimum)
+  --nav-focus-color: currentColor;
+  --nav-focus-width: 0.125rem; // 2px
+  --nav-focus-offset: 0.125rem; // 2px
+  --nav-focus-style: solid;
+
   display: var(--nav-dsp, flex);
   flex-direction: var(--nav-direction, row);
   width: var(--nav-w, auto);
@@ -87,4 +93,29 @@ nav {
   > div {
     margin-block-start: 0;
   }
+
+  // Focus indicators for links and buttons (WCAG 2.4.7)
+  a:focus {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  a:focus-visible {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  button:focus {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  button:focus-visible {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
 }

package/src/components/nav/nav.stories.tsx

@@ -82,17 +82,55 @@ export const MultipleNavs: Story = {
   args: {
     ...NavSection.args,
     classes: "navbar",
+    "aria-label": "Main navigation",
     children: (
       <>
-        <Nav.List>
-          <Nav.Item>Link 1</Nav.Item>
-          <Nav.Item>Link 2</Nav.Item>
+        <Nav.List aria-label="Primary menu">
+          <Nav.Item>
+            <Link href="/">Home</Link>
+          </Nav.Item>
+          <Nav.Item>
+            <Link href="/products">Products</Link>
+          </Nav.Item>
         </Nav.List>
-        <Nav.List>
-          <Nav.Item>Link 1</Nav.Item>
-          <Nav.Item>Link 2</Nav.Item>
+        <Nav.List aria-label="User menu">
+          <Nav.Item>
+            <Link href="/login">Login</Link>
+          </Nav.Item>
+          <Nav.Item>
+            <Link href="/signup">Sign Up</Link>
+          </Nav.Item>
         </Nav.List>
       </>
     ),
   },
 } as Story;
+
+export const WithCurrentPage: Story = {
+  args: {
+    "aria-label": "Main navigation",
+    children: (
+      <Nav.List>
+        <Nav.Item>
+          <Link href="/" aria-current="page">
+            Home
+          </Link>
+        </Nav.Item>
+        <Nav.Item>
+          <Link href="/about">About</Link>
+        </Nav.Item>
+        <Nav.Item>
+          <Link href="/products">Products</Link>
+        </Nav.Item>
+        <Nav.Item>
+          <Link href="/contact">Contact</Link>
+        </Nav.Item>
+      </Nav.List>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const homeLink = canvas.getByText(/home/i);
+    expect(homeLink).toHaveAttribute("aria-current", "page");
+  },
+} as Story;

package/src/components/nav/nav.tsx

@@ -1,76 +1,327 @@
-import UI from '../ui'
-import List from '../list/list'
-import React from 'react'
+import UI from "../ui";
+import List from "../list/list";
+import React from "react";
+import type { NavProps, NavListProps, NavItemProps } from "./nav.types";
 
-export type NavListProps = React.ComponentProps<typeof List> & {
-  isBlock?: boolean
-}
-export type NavItemProps = React.ComponentProps<typeof List.ListItem>
-
-export type NavProps = React.ComponentProps<typeof UI>
+// Re-export types for external use
+export type { NavProps, NavListProps, NavItemProps };
 
 /**
- * Renders a NavList component.
- * @param {Object} props - The props for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {Object} props - Additional props to spread to the List component.
- * @returns {JSX.Element} The rendered NavList component.
+ * NavList - A navigation-specific list component for grouping navigation items.
+ *
+ * Extends the List component with navigation-specific layout options through
+ * the `isBlock` prop. Automatically renders as an unstyled list to maintain
+ * clean navigation aesthetics.
+ *
+ * ## Key Features:
+ * - **Flexible Layout**: Supports both horizontal (inline) and vertical (block) layouts
+ * - **Semantic HTML**: Uses `<ul>` element for proper document structure
+ * - **Unstyled by Default**: Removes default list markers for clean navigation
+ * - **Accessible**: Works naturally with screen readers
+ *
+ * ## Accessibility:
+ * - ✅ Uses semantic `<ul>` element
+ * - ✅ Screen readers announce as "list" with item count
+ * - ✅ Supports `aria-label` for multiple lists
+ * - ✅ Keyboard navigation works naturally with focusable children
+ *
+ * ## Layout Options:
+ * - **Inline (default)**: Horizontal navigation bars, top menus
+ * - **Block**: Vertical sidebars, mobile menus, footer navigation
+ *
+ * @example
+ * ```tsx
+ * // Horizontal navigation (default)
+ * <NavList>
+ *   <NavItem><Link href="/">Home</Link></NavItem>
+ *   <NavItem><Link href="/about">About</Link></NavItem>
+ * </NavList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical sidebar navigation
+ * <NavList isBlock>
+ *   <NavItem><Link href="/dashboard">Dashboard</Link></NavItem>
+ *   <NavItem><Link href="/settings">Settings</Link></NavItem>
+ * </NavList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple lists with labels
+ * <Nav>
+ *   <NavList aria-label="Primary navigation">
+ *     <NavItem><Link href="/">Home</Link></NavItem>
+ *   </NavList>
+ *   <NavList aria-label="User menu">
+ *     <NavItem><Link href="/profile">Profile</Link></NavItem>
+ *   </NavList>
+ * </Nav>
+ * ```
+ *
+ * @param {NavListProps} props - Component props
+ * @param {boolean} [props.isBlock=false] - Display items vertically (block layout)
+ * @param {React.ReactNode} props.children - Navigation items (typically NavItem components)
+ * @param {string} [props.aria-label] - Accessible label for the list
+ * @returns {React.ReactElement} A navigation list component
  */
-export const NavList = ({ isBlock, children, ...props }: NavListProps) => {
+export const NavList = React.forwardRef<
+  HTMLUListElement,
+  NavListProps
+>(({ isBlock, children, ...props }, ref) => {
   return (
-    <List type="ul" {...props} data-list={`unstyled ${isBlock ? 'block' : ''}`}>
+    <List
+      type="ul"
+      {...props}
+      data-list={isBlock ? "unstyled block" : "unstyled"}
+      ref={ref}
+    >
       {children}
     </List>
-  )
-}
+  );
+});
+
+NavList.displayName = "NavList";
 
 /**
- * Renders a NavItem component.
- * @param {Object} props - The props for the component.
- * @param {string} [props.id] - The id for the component.
- * @param {Object} [props.styles] - The styles for the component.
- * @param {string} [props.classes] - The classes for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {boolean} [props.inline=true] - Whether the item should display inline.
- * @param {Object} props - Additional props to spread to the ListItem component.
- * @returns {JSX.Element} The rendered NavItem component.
+ * NavItem - An individual navigation link container (list item).
+ *
+ * Wraps navigation content (typically Link components) in a semantic list item
+ * element with consistent styling and accessibility support.
+ *
+ * ## Key Features:
+ * - **Semantic HTML**: Uses `<li>` element for proper list structure
+ * - **Flexible Content**: Accepts any React content (links, buttons, text)
+ * - **Customizable**: Supports custom styles and CSS classes
+ * - **Ref Forwarding**: Enables direct DOM access for advanced use cases
+ *
+ * ## Accessibility:
+ * - ✅ Uses semantic `<li>` element
+ * - ✅ Works with screen readers out of the box
+ * - ✅ Supports keyboard navigation naturally
+ * - ✅ Ref forwarding for programmatic focus if needed
+ *
+ * ## Best Practices:
+ * - Always wrap with NavList/Nav for proper semantics
+ * - Use `aria-current="page"` on the link inside to indicate current page
+ * - Ensure link text is descriptive and meaningful
+ * - Maintain sufficient color contrast (WCAG 2.1: 4.5:1 for normal text)
+ *
+ * @example
+ * ```tsx
+ * // Basic navigation item
+ * <NavItem>
+ *   <Link href="/about">About Us</Link>
+ * </NavItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Current page with aria-current
+ * <NavItem>
+ *   <Link href="/about" aria-current="page">
+ *     About Us
+ *   </Link>
+ * </NavItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <NavItem
+ *   classes="nav-item-featured"
+ *   styles={{ fontWeight: 'bold' }}
+ * >
+ *   <Link href="/special">Special Offer</Link>
+ * </NavItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon
+ * <NavItem>
+ *   <Link href="/settings">
+ *     <SettingsIcon aria-hidden="true" />
+ *     Settings
+ *   </Link>
+ * </NavItem>
+ * ```
+ *
+ * @param {NavItemProps} props - Component props
+ * @param {React.Ref} ref - Forwarded ref for DOM access
+ * @returns {React.ReactElement} A navigation item component
  */
-export const NavItem = ({
-  id,
-  styles,
-  classes,
-  children,
-  ...props
-}: NavItemProps) => {
+export const NavItem = React.forwardRef<
+  HTMLLIElement,
+  NavItemProps
+>(({ id, styles, classes, children, ...props }, ref) => {
   return (
     <List.ListItem
       type="li"
       id={id}
       classes={classes}
       styles={styles}
+      ref={ref}
       {...props}
     >
       {children}
     </List.ListItem>
-  )
-}
+  );
+});
+
+NavItem.displayName = "NavItem";
 
 /**
- * Renders a Nav component.
- * @param {Object} props - The props for the component.
- * @param {ReactNode} props.children - The child elements.
- * @param {Object} props - Additional props to spread to the UI component.
- * @returns {JSX.Element} The rendered Nav component.
+ * Nav - A semantic navigation container component for site navigation.
+ *
+ * The Nav component provides a semantic `<nav>` landmark element that helps
+ * users navigate your site. It meets WCAG 2.1 AA accessibility standards and
+ * follows modern React best practices with full TypeScript support.
+ *
+ * ## Key Features:
+ * - **Semantic HTML**: Uses native `<nav>` element for accessibility
+ * - **Landmark Role**: Automatically provides navigation landmark for screen readers
+ * - **Flexible Layout**: Supports multiple navigation patterns through CSS custom properties
+ * - **Compound Components**: Use Nav.List and Nav.Item for consistent structure
+ * - **Type-Safe**: Full TypeScript support with comprehensive JSDoc documentation
+ * - **Ref Forwarding**: Direct DOM access for scroll positioning and focus management
+ *
+ * ## Accessibility (WCAG 2.1 AA Compliant):
+ * - ✅ **4.1.2 Name, Role, Value**: Uses semantic `<nav>` element (landmark role)
+ * - ✅ **2.4.1 Bypass Blocks**: Navigation landmark helps skip repeated content
+ * - ✅ **1.3.1 Info and Relationships**: Proper list structure with ul > li
+ * - ✅ **2.4.8 Location**: Supports `aria-label` for multiple navigation regions
+ * - ✅ **4.1.3 Status Messages**: Use `aria-current="page"` on links for current page
+ *
+ * ## When to Use aria-label:
+ * - ✅ **Required**: When you have multiple `<nav>` elements on the same page
+ * - ✅ **Recommended**: To distinguish navigation purpose (e.g., "Footer navigation")
+ * - ❌ **Not needed**: For single navigation regions
+ *
+ * ## CSS Custom Properties:
+ * - `--nav-dsp`: Display mode (default: flex)
+ * - `--nav-direction`: Flex direction (default: row)
+ * - `--nav-bg`: Background color
+ * - `--nav-h`: Minimum height
+ * - `--nav-px`: Horizontal padding (default: 1rem)
+ * - `--nav-gap`: Gap between items
+ * - `--nav-fs`: Font size (default: 0.9rem)
+ *
+ * @example
+ * ```tsx
+ * // Simple navigation
+ * <Nav>
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *     <Nav.Item><Link href="/about">About</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple navigation regions (requires aria-label)
+ * <Nav aria-label="Main navigation">
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ *
+ * <Nav aria-label="Footer navigation">
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/privacy">Privacy</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Current page indication
+ * <Nav aria-label="Main navigation">
+ *   <Nav.List>
+ *     <Nav.Item>
+ *       <Link href="/" aria-current="page">Home</Link>
+ *     </Nav.Item>
+ *     <Nav.Item>
+ *       <Link href="/about">About</Link>
+ *     </Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical sidebar navigation
+ * <Nav aria-label="Sidebar navigation">
+ *   <Nav.List isBlock>
+ *     <Nav.Item><Link href="/dashboard">Dashboard</Link></Nav.Item>
+ *     <Nav.Item><Link href="/settings">Settings</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex navbar with multiple sections
+ * <Nav classes="navbar" aria-label="Main navigation">
+ *   <Nav.List aria-label="Primary menu">
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *     <Nav.Item><Link href="/products">Products</Link></Nav.Item>
+ *   </Nav.List>
+ *   <Nav.List aria-label="User menu">
+ *     <Nav.Item><Link href="/login">Login</Link></Nav.Item>
+ *     <Nav.Item><Link href="/signup">Sign Up</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom theming with CSS properties
+ * <Nav
+ *   aria-label="Main navigation"
+ *   styles={{
+ *     '--nav-bg': '#1a1a1a',
+ *     '--nav-h': '4rem',
+ *     '--nav-px': '2rem',
+ *   }}
+ * >
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @param {NavProps} props - Component props
+ * @param {React.Ref} ref - Forwarded ref for DOM access
+ * @returns {React.ReactElement} A navigation element
  */
-export const Nav = ({ children, ...props }: NavProps) => {
-  return (
-    <UI as="nav" {...props}>
-      {children}
-    </UI>
-  )
+export const Nav = React.forwardRef<HTMLElement, NavProps>(
+  ({ children, ...props }, ref) => {
+    return (
+      <UI as="nav" {...props} ref={ref}>
+        {children}
+      </UI>
+    );
+  }
+);
+
+Nav.displayName = "Nav";
+
+// Compound component pattern - attach sub-components to Nav
+export interface NavComponent
+  extends React.ForwardRefExoticComponent<
+    NavProps & React.RefAttributes<HTMLElement>
+  > {
+  List: typeof NavList;
+  Item: typeof NavItem;
 }
 
-export default Nav
-Nav.displayName = 'Nav'
-Nav.List = NavList
-Nav.Item = NavItem
+// Attach sub-components using Object.assign for better type inference
+const NavWithSubComponents = Object.assign(Nav, {
+  List: NavList,
+  Item: NavItem,
+});
+
+export default NavWithSubComponents as NavComponent;