@etus/ui 0.1.0

package/src/components/navigation/SkipLinks/SkipLinks.test.tsx

@@ -0,0 +1,445 @@
+// SkipLinks/SkipLinks.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { axe, toHaveNoViolations } from "jest-axe"
+import { describe, expect, it } from "vitest"
+
+import { SkipLink, SkipLinksList } from "./SkipLinks"
+
+expect.extend(toHaveNoViolations)
+
+// ============================================
+// SKIP LINK TESTS
+// ============================================
+describe("SkipLink", () => {
+  it("renders skip link", () => {
+    render(<SkipLink targetId="main">Skip to content</SkipLink>)
+    expect(screen.getByRole("link", { name: "Skip to content" })).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip to content
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveAttribute("data-slot", "skip-link")
+  })
+
+  it("has correct href with hash", () => {
+    render(<SkipLink targetId="main-content">Skip to content</SkipLink>)
+    expect(screen.getByRole("link")).toHaveAttribute("href", "#main-content")
+  })
+
+  it("renders default text when no children provided", () => {
+    render(<SkipLink targetId="main" />)
+    expect(
+      screen.getByRole("link", { name: "Skip to main content" })
+    ).toBeInTheDocument()
+  })
+
+  it("applies custom className", () => {
+    render(
+      <SkipLink className="custom-class" data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("custom-class")
+  })
+
+  it("is hidden by default (has -top-full)", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("-top-full")
+  })
+
+  it("becomes visible on focus (has focus:top-4)", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("focus:top-4")
+  })
+
+  it("is always visible when alwaysVisible is true", () => {
+    render(
+      <SkipLink alwaysVisible data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("top-4")
+  })
+
+  it("renders with top-left position by default", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("left-4")
+  })
+
+  it("renders with top-center position", () => {
+    render(
+      <SkipLink data-testid="skip" position="top-center" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("left-1/2", "-translate-x-1/2")
+  })
+
+  it("renders with top-right position", () => {
+    render(
+      <SkipLink data-testid="skip" position="top-right" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("right-4")
+  })
+
+  it("renders with default variant", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("bg-background")
+  })
+
+  it("renders with primary variant", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main" variant="primary">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("bg-primary")
+  })
+
+  it("is the first focusable element", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <>
+        <SkipLink targetId="main">Skip to content</SkipLink>
+        <button>Other button</button>
+        <main id="main" tabIndex={-1}>
+          Content
+        </main>
+      </>
+    )
+
+    await user.tab()
+    expect(screen.getByRole("link", { name: "Skip to content" })).toHaveFocus()
+  })
+
+  it("has high z-index", () => {
+    render(
+      <SkipLink data-testid="skip" targetId="main">
+        Skip
+      </SkipLink>
+    )
+    expect(screen.getByTestId("skip")).toHaveClass("z-[100]")
+  })
+})
+
+// ============================================
+// SKIP LINKS LIST TESTS
+// ============================================
+describe("SkipLinksList", () => {
+  const links = [
+    { targetId: "main", label: "Skip to main content" },
+    { targetId: "nav", label: "Skip to navigation" },
+    { targetId: "footer", label: "Skip to footer" },
+  ]
+
+  it("renders skip links list", () => {
+    render(<SkipLinksList data-testid="list" links={links} />)
+    expect(screen.getByTestId("list")).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute", () => {
+    render(<SkipLinksList data-testid="list" links={links} />)
+    expect(screen.getByTestId("list")).toHaveAttribute(
+      "data-slot",
+      "skip-links-list"
+    )
+  })
+
+  it("has navigation role", () => {
+    render(<SkipLinksList links={links} />)
+    expect(screen.getByRole("navigation")).toBeInTheDocument()
+  })
+
+  it("has aria-label", () => {
+    render(<SkipLinksList data-testid="list" links={links} />)
+    expect(screen.getByTestId("list")).toHaveAttribute("aria-label", "Skip links")
+  })
+
+  it("applies custom className", () => {
+    render(
+      <SkipLinksList className="custom-class" data-testid="list" links={links} />
+    )
+    expect(screen.getByTestId("list")).toHaveClass("custom-class")
+  })
+
+  it("renders all links", () => {
+    render(<SkipLinksList links={links} />)
+    expect(screen.getByRole("link", { name: "Skip to main content" })).toBeInTheDocument()
+    expect(screen.getByRole("link", { name: "Skip to navigation" })).toBeInTheDocument()
+    expect(screen.getByRole("link", { name: "Skip to footer" })).toBeInTheDocument()
+  })
+
+  it("each link has correct href", () => {
+    render(<SkipLinksList links={links} />)
+    expect(screen.getByRole("link", { name: "Skip to main content" })).toHaveAttribute(
+      "href",
+      "#main"
+    )
+    expect(screen.getByRole("link", { name: "Skip to navigation" })).toHaveAttribute(
+      "href",
+      "#nav"
+    )
+    expect(screen.getByRole("link", { name: "Skip to footer" })).toHaveAttribute(
+      "href",
+      "#footer"
+    )
+  })
+
+  it("renders with top-left position by default", () => {
+    render(<SkipLinksList links={links} />)
+    expect(
+      screen.getByRole("navigation").querySelector('[data-slot="skip-links-list-inner"]')
+    ).toHaveClass("left-4")
+  })
+
+  it("renders with top-center position", () => {
+    render(<SkipLinksList links={links} position="top-center" />)
+    expect(
+      screen.getByRole("navigation").querySelector('[data-slot="skip-links-list-inner"]')
+    ).toHaveClass("left-1/2", "-translate-x-1/2")
+  })
+
+  it("renders with top-right position", () => {
+    render(<SkipLinksList links={links} position="top-right" />)
+    expect(
+      screen.getByRole("navigation").querySelector('[data-slot="skip-links-list-inner"]')
+    ).toHaveClass("right-4")
+  })
+
+  it("each link has data-slot attribute", () => {
+    render(<SkipLinksList links={links} />)
+    const linkElements = screen.getAllByRole("link")
+    linkElements.forEach((link) => {
+      expect(link).toHaveAttribute("data-slot", "skip-links-list-item")
+    })
+  })
+
+  it("container is hidden by default", () => {
+    render(<SkipLinksList links={links} />)
+    expect(
+      screen.getByRole("navigation").querySelector('[data-slot="skip-links-list-inner"]')
+    ).toHaveClass("-top-full", "opacity-0")
+  })
+
+  it("container becomes visible on focus within", () => {
+    render(<SkipLinksList links={links} />)
+    expect(
+      screen.getByRole("navigation").querySelector('[data-slot="skip-links-list-inner"]')
+    ).toHaveClass("focus-within:top-4", "focus-within:opacity-100")
+  })
+
+  it("has high z-index", () => {
+    render(<SkipLinksList data-testid="list" links={links} />)
+    expect(screen.getByTestId("list")).toHaveClass("z-[100]")
+  })
+})
+
+// ============================================
+// KEYBOARD NAVIGATION TESTS
+// ============================================
+describe("Keyboard Navigation", () => {
+  it("SkipLink receives focus on Tab", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <>
+        <SkipLink targetId="main">Skip</SkipLink>
+        <button>Button</button>
+      </>
+    )
+
+    await user.tab()
+    expect(screen.getByRole("link", { name: "Skip" })).toHaveFocus()
+  })
+
+  it("SkipLinksList first link receives focus on Tab", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <>
+        <SkipLinksList
+          links={[
+            { targetId: "main", label: "Main" },
+            { targetId: "nav", label: "Nav" },
+          ]}
+        />
+        <button>Button</button>
+      </>
+    )
+
+    await user.tab()
+    expect(screen.getByRole("link", { name: "Main" })).toHaveFocus()
+  })
+
+  it("can Tab through multiple skip links", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <>
+        <SkipLinksList
+          links={[
+            { targetId: "main", label: "Main" },
+            { targetId: "nav", label: "Nav" },
+          ]}
+        />
+        <button>Button</button>
+      </>
+    )
+
+    await user.tab()
+    expect(screen.getByRole("link", { name: "Main" })).toHaveFocus()
+
+    await user.tab()
+    expect(screen.getByRole("link", { name: "Nav" })).toHaveFocus()
+
+    await user.tab()
+    expect(screen.getByRole("button", { name: "Button" })).toHaveFocus()
+  })
+})
+
+// ============================================
+// INTEGRATION TESTS
+// ============================================
+describe("Integration", () => {
+  it("works with target element", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <>
+        <SkipLink targetId="main-content">Skip to content</SkipLink>
+        <header>Header content</header>
+        <main id="main-content" tabIndex={-1}>
+          Main content
+        </main>
+      </>
+    )
+
+    const skipLink = screen.getByRole("link", { name: "Skip to content" })
+    expect(skipLink).toHaveAttribute("href", "#main-content")
+
+    await user.tab()
+    expect(skipLink).toHaveFocus()
+  })
+
+  it("renders complete layout with skip links", () => {
+    render(
+      <>
+        <SkipLinksList
+          links={[
+            { targetId: "main", label: "Skip to main" },
+            { targetId: "footer", label: "Skip to footer" },
+          ]}
+        />
+        <header>Header</header>
+        <main id="main" tabIndex={-1}>
+          Content
+        </main>
+        <footer id="footer" tabIndex={-1}>
+          Footer
+        </footer>
+      </>
+    )
+
+    expect(screen.getByRole("navigation")).toBeInTheDocument()
+    expect(screen.getByRole("main")).toBeInTheDocument()
+    expect(screen.getByRole("contentinfo")).toBeInTheDocument()
+  })
+})
+
+// ============================================
+// ACCESSIBILITY TESTS
+// ============================================
+describe("Accessibility", () => {
+  it("SkipLink has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <SkipLink targetId="main">Skip to main content</SkipLink>
+        <header>Header</header>
+        <main id="main" tabIndex={-1}>
+          <h1>Main Content</h1>
+        </main>
+      </>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("SkipLinksList has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <SkipLinksList
+          links={[
+            { targetId: "main", label: "Skip to main" },
+            { targetId: "nav", label: "Skip to nav" },
+          ]}
+        />
+        <nav id="nav" tabIndex={-1}>
+          Navigation
+        </nav>
+        <main id="main" tabIndex={-1}>
+          <h1>Content</h1>
+        </main>
+      </>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with different positions", async () => {
+    const { container } = render(
+      <>
+        <SkipLink position="top-center" targetId="main">
+          Skip
+        </SkipLink>
+        <main id="main" tabIndex={-1}>
+          <h1>Content</h1>
+        </main>
+      </>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with primary variant", async () => {
+    const { container } = render(
+      <>
+        <SkipLink targetId="main" variant="primary">
+          Skip
+        </SkipLink>
+        <main id="main" tabIndex={-1}>
+          <h1>Content</h1>
+        </main>
+      </>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})

package/src/components/navigation/SkipLinks/SkipLinks.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+import type {
+  SkipLinkProps,
+  SkipLinksListProps,
+} from "./SkipLinks.types"
+
+import { cn } from "../../../lib/utils"
+import {
+  skipLinksListInnerVariants,
+  skipLinksListItemVariants,
+  skipLinksListVariants,
+  skipLinkVariants,
+} from "./SkipLinks.variants"
+
+/**
+ * SkipLink - An accessibility link that allows users to skip repetitive navigation.
+ *
+ * Should be the first focusable element on the page. Hidden by default,
+ * becomes visible when focused.
+ *
+ * @example
+ * <SkipLink targetId="main-content">
+ *   Skip to main content
+ * </SkipLink>
+ *
+ * <main id="main-content" tabIndex={-1}>
+ *   Content here
+ * </main>
+ */
+function SkipLink({
+  className,
+  targetId,
+  children = "Skip to main content",
+  alwaysVisible = false,
+  position = "top-left",
+  variant = "default",
+  ...props
+}: SkipLinkProps) {
+  return (
+    <a
+      className={cn(
+        skipLinkVariants({ position, variant, alwaysVisible }),
+        className
+      )}
+      data-slot="skip-link"
+      href={`#${targetId}`}
+      {...props}
+    >
+      {children}
+    </a>
+  )
+}
+
+/**
+ * SkipLinksList - Multiple skip links for complex layouts.
+ *
+ * Renders a navigation container with multiple skip links.
+ * Container becomes visible when any link receives focus.
+ *
+ * @example
+ * <SkipLinksList
+ *   links={[
+ *     { targetId: "main-content", label: "Skip to main content" },
+ *     { targetId: "navigation", label: "Skip to navigation" },
+ *     { targetId: "footer", label: "Skip to footer" },
+ *   ]}
+ * />
+ */
+function SkipLinksList({
+  className,
+  links,
+  position = "top-left",
+  variant = "default",
+  ...props
+}: SkipLinksListProps) {
+  return (
+    <nav
+      aria-label="Skip links"
+      className={cn(skipLinksListVariants(), className)}
+      data-slot="skip-links-list"
+      {...props}
+    >
+      <div
+        className={skipLinksListInnerVariants({ position })}
+        data-slot="skip-links-list-inner"
+      >
+        {links.map((link) => (
+          <a
+            key={link.targetId}
+            className={skipLinksListItemVariants({ variant })}
+            data-slot="skip-links-list-item"
+            href={`#${link.targetId}`}
+          >
+            {link.label}
+          </a>
+        ))}
+      </div>
+    </nav>
+  )
+}
+
+export { SkipLink, SkipLinksList }

package/src/components/navigation/SkipLinks/SkipLinks.types.ts

@@ -0,0 +1,39 @@
+import type { ComponentProps, ReactNode } from "react"
+
+/**
+ * SkipLink item definition
+ */
+export interface SkipLinkItem {
+  /** Label for the link */
+  label: string
+  /** ID of the target element */
+  targetId: string
+}
+
+/**
+ * SkipLink props - Single skip link
+ */
+export interface SkipLinkProps extends ComponentProps<"a"> {
+  /** If the link should always be visible (not recommended for a11y) */
+  alwaysVisible?: boolean
+  /** Link content */
+  children?: ReactNode
+  /** Position when visible */
+  position?: "top-center" | "top-left" | "top-right"
+  /** ID of the target element (without #) */
+  targetId: string
+  /** Visual variant */
+  variant?: "default" | "primary"
+}
+
+/**
+ * SkipLinksList props - Multiple skip links
+ */
+export interface SkipLinksListProps extends ComponentProps<"nav"> {
+  /** Array of skip link items */
+  links: SkipLinkItem[]
+  /** Position when visible */
+  position?: "top-center" | "top-left" | "top-right"
+  /** Visual variant */
+  variant?: "default" | "primary"
+}

package/src/components/navigation/SkipLinks/SkipLinks.variants.ts

@@ -0,0 +1,102 @@
+import { cva } from "class-variance-authority"
+
+/**
+ * SkipLink variant styles
+ */
+export const skipLinkVariants = cva(
+  [
+    // Base styles
+    "absolute z-[100]",
+    "px-4 py-2 text-sm font-medium",
+    "rounded-md shadow-lg",
+    // Transition
+    "transition-all duration-200",
+    // Focus styles
+    "focus:outline-none focus:ring-2 focus:ring-offset-2",
+    // Hidden by default, visible on focus
+    "-top-full focus:top-4",
+  ],
+  {
+    variants: {
+      position: {
+        "top-left": "left-4",
+        "top-center": "left-1/2 -translate-x-1/2",
+        "top-right": "right-4",
+      },
+      variant: {
+        default: "bg-background text-foreground border border-border focus:ring-ring",
+        primary: "bg-primary text-primary-foreground focus:ring-primary",
+      },
+      alwaysVisible: {
+        true: "top-4",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      position: "top-left",
+      variant: "default",
+      alwaysVisible: false,
+    },
+  }
+)
+
+/**
+ * SkipLinksList container variant styles
+ */
+export const skipLinksListVariants = cva([
+  "fixed z-[100]",
+])
+
+/**
+ * SkipLinksList inner container variant styles
+ */
+export const skipLinksListInnerVariants = cva(
+  [
+    // Base styles
+    "absolute",
+    "flex flex-col gap-1",
+    "p-2 rounded-lg shadow-lg",
+    "bg-background border border-border",
+    // Transition
+    "transition-all duration-200",
+    // Hidden by default
+    "-top-full opacity-0 pointer-events-none",
+    // Visible when has focus within
+    "focus-within:top-4 focus-within:opacity-100 focus-within:pointer-events-auto",
+  ],
+  {
+    variants: {
+      position: {
+        "top-left": "left-4",
+        "top-center": "left-1/2 -translate-x-1/2",
+        "top-right": "right-4",
+      },
+    },
+    defaultVariants: {
+      position: "top-left",
+    },
+  }
+)
+
+/**
+ * SkipLinksList item variant styles
+ */
+export const skipLinksListItemVariants = cva(
+  [
+    "block px-3 py-1.5 text-sm font-medium rounded",
+    "text-foreground hover:bg-accent",
+    "focus:outline-none focus:bg-accent focus:ring-2 focus:ring-ring",
+    "transition-colors",
+  ],
+  {
+    variants: {
+      variant: {
+        default: "",
+        primary: "hover:bg-primary/10 focus:bg-primary/10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)

package/src/components/navigation/SkipLinks/index.ts

@@ -0,0 +1,12 @@
+export * from './SkipLinks'
+export {
+  skipLinksListInnerVariants,
+  skipLinksListItemVariants,
+  skipLinksListVariants,
+  skipLinkVariants,
+} from './SkipLinks.variants'
+export type {
+  SkipLinkItem,
+  SkipLinkProps,
+  SkipLinksListProps,
+} from './SkipLinks.types'