@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.1

package/src/Component/Carousel/Carousel.stories.tsx

@@ -0,0 +1,214 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./Carousel"
+import Card from "../Card/Card"
+import CardContent from "../Card/Components/CardContent"
+import Heading from "../../Atom/Heading/Heading"
+import Text from "../../Atom/Text/Text"
+import Link from "../../Atom/Link/Link"
+import { HeadingTypes } from "@pnx-mixtape/ids-shape"
+import { BackgroundStyles, TextStyles } from "../../enums"
+import "./carousel.css"
+import "../Card/card.css"
+import { Page } from "../../../.storybook-react/decorators"
+import { expect, waitFor } from "storybook/test"
+
+const makeCard = (n: number) => (
+  <Card background={BackgroundStyles.BOX} block>
+    <CardContent>
+      <Heading as={HeadingTypes.THREE}>Tile {n}</Heading>
+      <Text modifier={TextStyles.LEDE}>Tiles are just block cards without an image.</Text>
+      <Link to="#" more>
+        Find out more
+      </Link>
+    </CardContent>
+  </Card>
+)
+
+const defaultItems = [1, 2, 3, 4, 5, 6].map(makeCard)
+
+/**
+ * A horizontally scrolling list of items with native CSS scroll-snap. Prev/Next
+ * buttons, pagination, and loop-to-start are powered by React state and
+ * IntersectionObserver — no Web Component required.
+ *
+ * The `Elements/Carousel.ts` Web Component is still available for Twig/HTML contexts.
+ * Adjust `--inline-size` via CSS to control how many items are visible per page.
+ */
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  decorators: [Page],
+  component: Component,
+  args: {
+    items: defaultItems,
+    pagination: false,
+    counter: false,
+    loop: false,
+  },
+  argTypes: {
+    pagination: { control: "boolean" },
+    counter: { control: "boolean" },
+    loop: { control: "boolean" },
+  },
+}
+
+export default meta
+
+export const Default: StoryObj<typeof meta> = {
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const back = await canvas.findByRole("button", { name: "previous page" }, { timeout: 2000 })
+    const next = await canvas.findByRole("button", { name: "next page" }, { timeout: 2000 })
+    await step("Has prev/next buttons", async () => {
+      await expect(back).toHaveAttribute("disabled")
+      await expect(next).not.toHaveAttribute("disabled")
+    })
+    await step("Navigates on click", async () => {
+      await userEvent.click(next)
+      await waitFor(
+        () => {
+          expect(back).not.toHaveAttribute("disabled")
+          expect(next).toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+    })
+    await step("Navigates back", async () => {
+      await userEvent.click(back)
+      await waitFor(
+        () => {
+          expect(back).toHaveAttribute("disabled")
+          expect(next).not.toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}
+
+/** Numbered pagination buttons appear below the carousel once it overflows. */
+export const WithPagination: StoryObj<typeof meta> = {
+  args: { pagination: true },
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const pagination = await canvas.findByLabelText("Page controls", {}, { timeout: 2000 })
+    const back = await canvas.findByRole("button", { name: "previous page" }, { timeout: 2000 })
+    const next = await canvas.findByRole("button", { name: "next page" }, { timeout: 2000 })
+    const button1 = await canvas.findByRole("button", { name: "Page 1" })
+    const button2 = await canvas.findByRole("button", { name: "Page 2" })
+    await step("Has pager buttons", async () => {
+      await expect(pagination).not.toHaveAttribute("hidden")
+      await expect(button1).toBeInTheDocument()
+      await expect(button1).toHaveAttribute("aria-current", "page")
+      await expect(button2).toBeInTheDocument()
+      await expect(button2).not.toHaveAttribute("aria-current")
+    })
+    await step("Navigates on click", async () => {
+      await userEvent.click(button2)
+      // Wait for the pagination buttons' `aria-current` AND the quick-nav
+      // buttons' `disabled` (scroll-debounce-driven) to settle together -
+      // the two are updated by independent code paths.
+      await waitFor(
+        () => {
+          expect(button1).not.toHaveAttribute("aria-current")
+          expect(button2).toHaveAttribute("aria-current", "page")
+          expect(next).toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+    })
+    await step("Navigates back", async () => {
+      await userEvent.click(back)
+      await waitFor(
+        () => {
+          expect(button2).not.toHaveAttribute("aria-current")
+          expect(button1).toHaveAttribute("aria-current", "page")
+          expect(back).toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}
+
+/** Dot-style counter navigation — mutually exclusive with pagination. */
+export const WithCounter: StoryObj<typeof meta> = {
+  args: { counter: true },
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const pagination = await canvas.findByLabelText("Page controls", {}, { timeout: 2000 })
+    const back = await canvas.findByRole("button", { name: "previous page" }, { timeout: 2000 })
+    const next = await canvas.findByRole("button", { name: "next page" }, { timeout: 2000 })
+    const button1 = await canvas.findByRole("button", { name: "Page 1" })
+    const button2 = await canvas.findByRole("button", { name: "Page 2" })
+    await step("Has pager buttons", async () => {
+      await expect(pagination).not.toHaveAttribute("hidden")
+      await expect(button1).toBeInTheDocument()
+      await expect(button1).toHaveAttribute("aria-current", "page")
+      await expect(button2).toBeInTheDocument()
+      await expect(button2).not.toHaveAttribute("aria-current")
+    })
+    await step("Navigates on click", async () => {
+      await userEvent.click(button2)
+      // Wait for the pagination buttons' `aria-current` AND the quick-nav
+      // buttons' `disabled` (scroll-debounce-driven) to settle together -
+      // the two are updated by independent code paths.
+      await waitFor(
+        () => {
+          expect(button1).not.toHaveAttribute("aria-current")
+          expect(button2).toHaveAttribute("aria-current", "page")
+          expect(next).toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+    })
+    await step("Navigates back", async () => {
+      await userEvent.click(back)
+      await waitFor(
+        () => {
+          expect(button2).not.toHaveAttribute("aria-current")
+          expect(button1).toHaveAttribute("aria-current", "page")
+          expect(back).toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}
+
+/** At the end of the list, Next scrolls back to the first item. */
+export const WithLoop: StoryObj<typeof meta> = {
+  args: { loop: true },
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const back = await canvas.findByRole("button", { name: "previous page" }, { timeout: 2000 })
+    const next = await canvas.findByRole("button", { name: "next page" }, { timeout: 2000 })
+    await step("Has prev/next buttons", async () => {
+      await expect(back).toHaveAttribute("disabled")
+      await expect(next).not.toHaveAttribute("disabled")
+    })
+    await step("Navigates on click", async () => {
+      await userEvent.click(next)
+      await waitFor(
+        () => {
+          expect(back).not.toHaveAttribute("disabled")
+          expect(next).not.toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+    })
+    await step("Loops back", async () => {
+      await userEvent.click(next)
+      await waitFor(
+        () => {
+          expect(back).toHaveAttribute("disabled")
+          expect(next).not.toHaveAttribute("disabled")
+        },
+        { timeout: 2000 },
+      )
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}

package/src/Component/Carousel/Carousel.tsx

@@ -0,0 +1,261 @@
+import { JSX, ReactNode, useCallback, useEffect, useId, useRef, useState } from "react"
+import classNames from "classnames"
+
+type CarouselProps = {
+  items: ReactNode[]
+  pagination?: boolean
+  counter?: boolean
+  loop?: boolean
+  className?: string
+}
+
+const Carousel = ({
+  items,
+  pagination: showPagination = false,
+  counter: showCounter = false,
+  loop = false,
+  className,
+}: CarouselProps): JSX.Element => {
+  const listRef = useRef<HTMLUListElement>(null)
+  const [activePage, setActivePage] = useState(0)
+  const [pageCount, setPageCount] = useState(0)
+  const [isOverflowing, setIsOverflowing] = useState(false)
+  const [prevDisabled, setPrevDisabled] = useState(true)
+  const [nextDisabled, setNextDisabled] = useState(false)
+  const [atEnd, setAtEnd] = useState(false)
+
+  // itemMap tracks which <li> elements are currently visible (> 50% intersection).
+  const itemMapRef = useRef<Map<HTMLLIElement, boolean>>(new Map())
+
+  const paginationType = showPagination ? "pagination" : showCounter ? "counter" : null
+  const carouselId = useId()
+
+  // Derive visible count and page-start items from itemMap.
+  const getVisibleCount = useCallback(
+    (): number => [...itemMapRef.current.values()].filter(Boolean).length,
+    [],
+  )
+
+  const getPageStartItems = useCallback((): HTMLLIElement[] => {
+    const allItems = [...itemMapRef.current.keys()]
+    const visibleCount = getVisibleCount()
+    if (visibleCount === 0) return allItems
+    return allItems.filter((_, index) => index % visibleCount === 0)
+  }, [getVisibleCount])
+
+  // Build pagination buttons based on current page layout.
+  const buildPagination = useCallback(() => {
+    const pageStartItems = getPageStartItems()
+    const count = pageStartItems.length
+    if (count <= 0) return
+    setPageCount(count)
+  }, [getPageStartItems])
+
+  // Measure overflow and toggle scroll affordances.
+  const handleOverflow = useCallback(() => {
+    const list = listRef.current
+    if (!list) return
+    const overflow = list.scrollWidth > list.clientWidth
+    setIsOverflowing(overflow)
+    if (overflow && paginationType) {
+      setTimeout(buildPagination, 200)
+    }
+  }, [buildPagination, paginationType])
+
+  // Disable state for prev/next buttons.
+  const handleDisabled = useCallback(() => {
+    const list = listRef.current
+    if (!list) return
+
+    setPrevDisabled(list.scrollLeft < 200)
+
+    const reachedEnd =
+      Math.round(list.scrollLeft) >= Math.round(list.scrollWidth - list.offsetWidth)
+    setAtEnd(reachedEnd)
+
+    if (!loop) {
+      setNextDisabled(reachedEnd)
+    }
+
+    if (paginationType) {
+      const startPosition = Math.round(list.offsetLeft + list.scrollLeft)
+      if (reachedEnd) {
+        const lastPage = getPageStartItems().length - 1
+        setActivePage(lastPage)
+      } else {
+        // Closest match, not exact equality — sub-pixel/rounding differences
+        // mean an exact match can silently miss every "middle" page.
+        let closestIndex = 0
+        let closestDistance = Infinity
+        getPageStartItems().forEach((item, index) => {
+          const distance = Math.abs(Math.round(item.offsetLeft) - startPosition)
+          if (distance < closestDistance) {
+            closestDistance = distance
+            closestIndex = index
+          }
+        })
+        setActivePage(closestIndex)
+      }
+    }
+  }, [loop, paginationType, getPageStartItems])
+
+  const scrollDebounceRef = useRef<ReturnType<typeof setTimeout>>(null)
+
+  const handleScroll = useCallback(() => {
+    clearTimeout(scrollDebounceRef.current)
+    scrollDebounceRef.current = setTimeout(handleDisabled, paginationType ? 100 : 200)
+  }, [handleDisabled, paginationType])
+
+  // Navigate to a page index.
+  const handleNavigation = useCallback(
+    (page: number) => {
+      if (page < 0) return
+
+      const list = listRef.current
+      if (!list) return
+
+      const allItems = [...itemMapRef.current.keys()]
+      const visibleCount = getVisibleCount() || 1
+      const goesForward = page > activePage
+      const willRestart = loop && atEnd && goesForward
+
+      if (page === 0 || willRestart) {
+        // Reset to page 0 rather than the requested (out-of-range) page —
+        // otherwise every subsequent click computes an out-of-bounds
+        // targetIndex and silently does nothing.
+        setActivePage(0)
+        allItems[0]?.scrollIntoView({ inline: "start", block: "nearest" })
+        return
+      }
+
+      setActivePage(page)
+      const targetIndex = visibleCount * page
+      allItems[targetIndex]?.scrollIntoView({ inline: "start", block: "nearest" })
+    },
+    [activePage, atEnd, loop, getVisibleCount],
+  )
+
+  // Wire IntersectionObserver, ResizeObserver, and MutationObserver.
+  useEffect(() => {
+    const list = listRef.current
+    if (!list) return
+
+    const liElements = list.querySelectorAll<HTMLLIElement>(":scope > li")
+    itemMapRef.current = new Map()
+
+    const iO = new IntersectionObserver(
+      entries => {
+        entries.forEach(({ target, intersectionRatio }) => {
+          const li = target as HTMLLIElement
+          if (intersectionRatio > 0.5) {
+            li.removeAttribute("inert")
+            li.setAttribute("aria-hidden", "false")
+            itemMapRef.current.set(li, true)
+          } else {
+            li.setAttribute("inert", "")
+            li.setAttribute("aria-hidden", "true")
+            itemMapRef.current.set(li, false)
+          }
+        })
+      },
+      { root: list, threshold: 0.5 },
+    )
+    liElements.forEach(li => iO.observe(li))
+
+    const rO = new ResizeObserver(() => handleOverflow())
+    rO.observe(list)
+
+    const mO = new MutationObserver(() => handleOverflow())
+    mO.observe(list, { childList: true })
+
+    list.addEventListener("scroll", handleScroll)
+
+    return () => {
+      iO.disconnect()
+      rO.disconnect()
+      mO.disconnect()
+      list.removeEventListener("scroll", handleScroll)
+      clearTimeout(scrollDebounceRef.current)
+    }
+  }, [handleScroll, handleOverflow])
+
+  return (
+    // role="region"/aria-roledescription is intentional for the carousel; no semantic tag fits.
+    <div
+      className={classNames("mx-carousel", className)}
+      // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role
+      role="region"
+      aria-roledescription="carousel"
+      id={carouselId}
+    >
+      <div
+        className="mx-carousel__buttons"
+        hidden={!isOverflowing}
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role
+        role="group"
+        aria-label="Quick page controls"
+      >
+        <button
+          className="mx-button mx-button--icon-only mx-carousel__prev"
+          type="button"
+          disabled={prevDisabled}
+          onClick={() => handleNavigation(activePage - 1)}
+        >
+          <span className="sr-only">previous page</span>
+          <span className="mx-icon mx-icon--chevron-left" aria-hidden="true" />
+        </button>
+        <button
+          className="mx-button mx-button--icon-only mx-carousel__next"
+          type="button"
+          disabled={nextDisabled}
+          onClick={() => handleNavigation(activePage + 1)}
+        >
+          <span className="sr-only">next page</span>
+          <span className="mx-icon mx-icon--chevron-right" aria-hidden="true" />
+        </button>
+      </div>
+
+      <ul
+        ref={listRef}
+        className="mx-carousel__scrollable"
+        aria-live="off"
+        {...(isOverflowing ? { tabIndex: 0 } : {})}
+      >
+        {items.map((item, i) => (
+          // Opaque ReactNode with no stable id; index is the only available key.
+          // oxlint-disable-next-line react/no-array-index-key
+          <li key={i} data-index={i}>
+            {item}
+          </li>
+        ))}
+      </ul>
+
+      {paginationType && pageCount > 0 && (
+        <div
+          className="mx-carousel__pagination"
+          data-pagination={paginationType}
+          hidden={!isOverflowing}
+          // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role
+          role="group"
+          aria-label="Page controls"
+        >
+          {Array.from({ length: pageCount }, (_, index) => (
+            <button
+              key={index}
+              type="button"
+              data-index={index}
+              disabled={index === activePage}
+              aria-current={index === activePage ? "page" : undefined}
+              aria-label={`Page ${index + 1}`}
+              onClick={() => handleNavigation(index)}
+            >
+              {index + 1}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default Carousel