@fpkit/acss 0.5.13 → 0.6.1

package/src/components/nav/nav.types.ts

@@ -0,0 +1,308 @@
+import React from "react";
+import UI from "#components/ui";
+import type { ListProps, ListItemProps } from "../list/list.types";
+
+/**
+ * Props for the Nav component (navigation container).
+ *
+ * The Nav component provides a semantic `<nav>` element for site navigation,
+ * meeting WCAG 2.1 AA standards for accessible navigation landmarks.
+ *
+ * ## Accessibility Features:
+ * - ✅ Uses semantic `<nav>` element (landmark role)
+ * - ✅ Supports `aria-label` for multiple navigation regions
+ * - ✅ Supports `aria-labelledby` for heading-based labels
+ * - ✅ Works with screen readers and keyboard navigation
+ *
+ * ## Best Practices:
+ * - Use `aria-label` when you have multiple navigation regions
+ * - Prefer descriptive labels like "Main navigation" or "Footer navigation"
+ * - Use `aria-current="page"` on links to indicate current page
+ *
+ * @example
+ * ```tsx
+ * // Single navigation on page (no label needed)
+ * <Nav>
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple navigation regions (labels required)
+ * <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
+ * // Using aria-labelledby with a heading
+ * <h2 id="main-nav-heading">Site Navigation</h2>
+ * <Nav aria-labelledby="main-nav-heading">
+ *   <Nav.List>
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ */
+export type NavProps = {
+  /**
+   * Child elements (typically Nav.List components).
+   *
+   * @required
+   * @example
+   * ```tsx
+   * <Nav>
+   *   <Nav.List>
+   *     <Nav.Item>Link 1</Nav.Item>
+   *   </Nav.List>
+   * </Nav>
+   * ```
+   */
+  children: React.ReactNode;
+
+  /**
+   * Accessible label for the navigation region.
+   *
+   * **WCAG 2.1 Requirement**: Use when you have multiple `<nav>` elements
+   * on the same page to distinguish them for screen reader users.
+   *
+   * @optional
+   * @see {@link https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA11}
+   * @example
+   * ```tsx
+   * aria-label="Main navigation"
+   * aria-label="Footer navigation"
+   * ```
+   */
+  "aria-label"?: string;
+
+  /**
+   * ID of an element that labels this navigation region.
+   *
+   * Use when a visible heading already describes the navigation.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * <h2 id="sidebar-nav">Quick Links</h2>
+   * <Nav aria-labelledby="sidebar-nav">...</Nav>
+   * ```
+   */
+  "aria-labelledby"?: string;
+
+  /**
+   * HTML id attribute for the navigation element.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * id="main-navigation"
+   * ```
+   */
+  id?: string;
+
+  /**
+   * CSS class names to apply to the nav element.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * classes="navbar sticky-header"
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * Inline CSS styles to apply.
+   * Can include CSS custom properties for theming.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * styles={{
+   *   '--nav-bg': '#f8f9fa',
+   *   '--nav-h': '4rem'
+   * }}
+   * ```
+   */
+  styles?: React.CSSProperties;
+} & Partial<React.ComponentProps<typeof UI>>;
+
+/**
+ * Props for the NavList component (list of navigation items).
+ *
+ * Extends the List component with navigation-specific styling through
+ * the `isBlock` prop for vertical layout control.
+ *
+ * ## Layout Options:
+ * - **Default (inline)**: Horizontal list for primary navigation
+ * - **Block**: Vertical stacked list for sidebars or mobile menus
+ *
+ * @example
+ * ```tsx
+ * // Horizontal navigation (default)
+ * <Nav.List>
+ *   <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   <Nav.Item><Link href="/about">About</Link></Nav.Item>
+ * </Nav.List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical navigation (block layout)
+ * <Nav.List isBlock>
+ *   <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   <Nav.Item><Link href="/about">About</Link></Nav.Item>
+ * </Nav.List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple lists in a navbar
+ * <Nav classes="navbar">
+ *   <Nav.List aria-label="Primary navigation">
+ *     <Nav.Item><Link href="/">Home</Link></Nav.Item>
+ *   </Nav.List>
+ *   <Nav.List aria-label="User actions">
+ *     <Nav.Item><Link href="/login">Login</Link></Nav.Item>
+ *   </Nav.List>
+ * </Nav>
+ * ```
+ */
+export type NavListProps = Omit<ListProps, "type"> & {
+  /**
+   * Display list items vertically (block layout).
+   *
+   * When true, applies `data-list="unstyled block"` for vertical stacking.
+   * When false or undefined, items display inline horizontally.
+   *
+   * @default false
+   * @example
+   * ```tsx
+   * isBlock={true}  // Vertical sidebar navigation
+   * isBlock={false} // Horizontal top navigation (default)
+   * ```
+   */
+  isBlock?: boolean;
+
+  /**
+   * Accessible label for the navigation list.
+   *
+   * Use when you have multiple lists in the same Nav to distinguish them.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * aria-label="Main menu"
+   * aria-label="Social media links"
+   * ```
+   */
+  "aria-label"?: string;
+
+  /**
+   * Child elements (typically Nav.Item components).
+   *
+   * @required
+   */
+  children: React.ReactNode;
+};
+
+/**
+ * Props for the NavItem component (individual navigation link container).
+ *
+ * Wraps navigation links in a list item element with consistent styling.
+ * Typically contains a Link component or anchor element.
+ *
+ * ## Accessibility Considerations:
+ * - Use `aria-current="page"` on the link inside to indicate current page
+ * - Ensure sufficient color contrast (WCAG 2.1: 4.5:1 for text)
+ * - Provide focus indicators (WCAG 2.1: 3:1 contrast for focus state)
+ *
+ * @example
+ * ```tsx
+ * // Basic navigation item
+ * <Nav.Item>
+ *   <Link href="/about">About Us</Link>
+ * </Nav.Item>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Current page indicator
+ * <Nav.Item>
+ *   <Link href="/about" aria-current="page">
+ *     About Us
+ *   </Link>
+ * </Nav.Item>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <Nav.Item
+ *   classes="nav-item-featured"
+ *   styles={{ '--nav-px': '2rem' }}
+ * >
+ *   <Link href="/pricing">Pricing</Link>
+ * </Nav.Item>
+ * ```
+ */
+export type NavItemProps = Omit<ListItemProps, "type"> & {
+  /**
+   * HTML id attribute for the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * id="nav-item-home"
+   * ```
+   */
+  id?: string;
+
+  /**
+   * Inline CSS styles to apply to the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * styles={{ paddingInline: '1.5rem' }}
+   * ```
+   */
+  styles?: React.CSSProperties;
+
+  /**
+   * CSS class names to apply to the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * classes="nav-item active"
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * Child elements (typically a Link component).
+   *
+   * @required
+   * @example
+   * ```tsx
+   * <Nav.Item>
+   *   <Link href="/">Home</Link>
+   * </Nav.Item>
+   * ```
+   */
+  children: React.ReactNode;
+};