@a11y-context/mcp-server 0.1.0

package/corpus/web/react/components/carousel.thumbnails.md

@@ -0,0 +1,395 @@
+---
+id: carousel.thumbnails
+title: Carousel with Thumbnail Navigation
+stack: web/react
+status: beta
+latest_version: 0.2.0
+tags: [marquee, carousel, slider, gallery, thumbnails, autoplay, reduced-motion, image-preview]
+aliases: [hero carousel thumbnails, marquee thumbnails, featured gallery thumbnails, hero gallery thumbnails, preview carousel]
+summary: Horizontally-advancing carousel (aka hero or marquee carousel) with thumbnail navigation, prev/next buttons, and pause behavior.
+---
+
+# Carousel with Thumbnail Navigation
+
+Pattern ID: `carousel.thumbnails`
+
+Horizontally-advancing carousel (aka hero or marquee carousel) with thumbnail navigation, prev/next buttons, and pause behavior.
+
+## Use When
+- Use when thumbnail images are displayed for direct slide selection.
+- Use when users can identify slide content from visible preview images before activating a slide.
+- Use when thumbnails act as explicit navigation controls for specific slides.
+
+## Do Not Use When
+- Do not use when navigation is limited to dot indicators without image previews (use `carousel.dots`).
+- Do not use when multiple full-size items are visible simultaneously in a scrollable row (use `content-shelf`).
+
+## Must Haves
+- Render a carousel container with `aria-roledescription="carousel"` and an accessible name (`aria-label`).
+- Ensure the carousel container has a semantic HTML5 element or role, such as `<section>` or `role="region"`.
+- Each slide must have `role="group"`, `aria-roledescription="slide"` and an `aria-label` like "1 of N".
+- Slides that are not currently visible must not be rendered, or must be hidden in the DOM (e.g., via the `hidden` attribute), so their content cannot be reached by keyboard or screen readers.
+- Provide Previous/Next buttons as real `<button>` elements, with `aria-label` like "Previous Slide" and "Next Slide".
+- Provide thumbnail navigation as real `<button>` elements in normal tab order (no roving tabindex), with `aria-label` like "Go to slide 2: {title of slide 2}", and with `aria-current="true"` on the button corresponding to the active slide.
+- Provide a Pause/Play button as the first focusable element inside the carousel container.
+- Default to paused when prefers-reduced-motion: reduce.
+- Pause when keyboard focus enters the carousel region.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) on each focusable element, including the previous/next buttons, pause button, and thumbnail controls.
+
+## Customizable
+- The contents of each slide are customizable. However, if they contain a title, then these should usually be `<h2>`.
+
+## Don'ts
+- Do not auto-advance the slides without a visible Pause/Play control.
+- Do not ignore `prefers-reduced-motion: reduce`.
+- Do not keep moving while the user is interacting (focus inside carousel must pause autoplay).
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+export function CarouselThumbnailsDemo({
+  ariaLabel = "Featured content",
+  items = DEFAULT_ITEMS,
+  autoplay = true,
+  intervalMs = 5000,
+}) {
+  const [index, setIndex] = useState(0);
+  const [isPaused, setIsPaused] = useState(false);
+
+  const hasUserToggledPauseRef = useRef(false);
+  const reducedMotionRef = useRef(false);
+  const timerRef = useRef(null);
+  const skipFocusPauseRef = useRef(false);
+
+  const count = items.length;
+
+  // Reduced motion: paused by default.
+  useEffect(() => {
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const apply = () => {
+      reducedMotionRef.current = !!mq.matches;
+      if (mq.matches) {
+        setIsPaused(true);
+      }
+    };
+
+    apply();
+
+    // Safari still supports addListener in some versions
+    if (mq.addEventListener) mq.addEventListener("change", apply);
+    else mq.addListener(apply);
+
+    return () => {
+      if (mq.removeEventListener) mq.removeEventListener("change", apply);
+      else mq.removeListener(apply);
+    };
+  }, []);
+
+  function goTo(nextIndex) {
+    const clamped = ((nextIndex % count) + count) % count;
+    setIndex(clamped);
+  }
+
+  function goPrev() {
+    goTo(index - 1);
+  }
+
+  function goNext() {
+    goTo(index + 1);
+  }
+
+  function pause() {
+    setIsPaused(true);
+  }
+
+  function togglePause() {
+    skipFocusPauseRef.current = false;
+    hasUserToggledPauseRef.current = true;
+    setIsPaused((p) => !p);
+  }
+
+  function onPauseButtonPointerDown() {
+    skipFocusPauseRef.current = true;
+  }
+
+  // Pause autoplay when focus enters the carousel.
+  function onFocusCapture() {
+    if (skipFocusPauseRef.current) {
+      skipFocusPauseRef.current = false;
+      return;
+    }
+    pause();
+  }
+
+  // Autoplay (respects reduced motion, focus-paused state, and user pause).
+  useEffect(() => {
+    if (!autoplay || isPaused || reducedMotionRef.current) return;
+
+    // Functional update avoids stale-closure reads of the current index.
+    timerRef.current = window.setInterval(() => {
+      setIndex((i) => (i + 1) % count);
+    }, intervalMs);
+
+    return () => {
+      if (timerRef.current) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [autoplay, isPaused, intervalMs, count]);
+
+  const active = items[index];
+
+  // aria-live: off while moving, polite when paused so changes can be announced if user moves slides.
+  const ariaLive = isPaused ? "polite" : "off";
+
+  return (
+    <section
+      aria-roledescription="carousel"
+      aria-label={ariaLabel}
+      onFocusCapture={onFocusCapture}
+      style={{
+        position: "relative",
+        maxWidth: 960,
+        margin: "0 auto",
+        padding: 16,
+        background: "#fff",
+        color: "#111",
+        borderRadius: 12,
+      }}
+    >
+      {/* Slides viewport */}
+      <div
+        aria-live={ariaLive}
+        style={{
+          position: "relative",
+          overflow: "hidden",
+          borderRadius: 12,
+          minHeight: 400,
+          background: "#000",
+        }}
+      >
+        <button
+          type="button"
+          onPointerDown={onPauseButtonPointerDown}
+          onClick={togglePause}
+          aria-label={isPaused ? "Play automatic rotation" : "Pause automatic rotation"}
+          aria-pressed={isPaused}
+          style={pauseButtonStyle}
+        >
+          <span aria-hidden="true">
+            {isPaused ? "[play-icon]" : "[pause-icon]"}
+          </span>
+        </button>
+
+        {/* Slide */}
+        <div
+          aria-roledescription="slide"
+          aria-label={`${index + 1} of ${count}`}
+          style={{
+            display: "grid",
+            gridTemplateColumns: "1fr",
+            alignItems: "end",
+            minHeight: 400,
+            padding: "16px 72px 72px",
+            backgroundImage: active.image ? `url(${active.image})` : undefined,
+            backgroundSize: "cover",
+            backgroundPosition: "center",
+          }}
+        >
+          <div
+            style={{
+              maxWidth: 520,
+              background: "#000",
+              color: "#fff",
+              padding: 12,
+              borderRadius: 10,
+            }}
+          >
+            <h2 style={{ margin: 0, fontSize: 24 }}>{active.title}</h2>
+            <p style={{ marginTop: 8, marginBottom: 12, lineHeight: 1.4 }}>
+              {active.description}
+            </p>
+            <a
+              href={active.href}
+              style={{
+                display: "inline-block",
+                padding: "10px 12px",
+                borderRadius: 10,
+                background: "#fff",
+                color: "#000",
+                textDecoration: "none",
+                fontWeight: 600,
+              }}
+            >
+              View details
+            </a>
+          </div>
+        </div>
+
+        {/* Prev / Next (inside visible slide area) */}
+        <button
+          type="button"
+          onClick={() => {
+            pause();
+            goPrev();
+          }}
+          aria-label="Previous slide"
+          style={navButtonStyle("left")}
+        >
+          ‹
+        </button>
+
+        <button
+          type="button"
+          onClick={() => {
+            pause();
+            goNext();
+          }}
+          aria-label="Next slide"
+          style={navButtonStyle("right")}
+        >
+          ›
+        </button>
+
+        {/* Thumbnail navigation overlay (inside viewport, outside slide node) */}
+        <div
+          style={{
+            position: "absolute",
+            right: 12,
+            bottom: 12,
+            zIndex: 2,
+          }}
+        >
+          <div style={{ display: "flex", gap: 10 }} aria-label="Choose a slide">
+            {items.map((item, i) => {
+              const isActive = i === index;
+              return (
+                <button
+                  key={i}
+                  type="button"
+                  onClick={() => {
+                    pause();
+                    goTo(i);
+                  }}
+                  aria-label={`Go to slide ${i + 1}: ${item.title}`}
+                  aria-current={isActive ? "true" : undefined}
+                  style={thumbnailButtonStyle(isActive)}
+                >
+                  <span
+                    aria-hidden="true"
+                    style={{
+                      display: "block",
+                      width: "100%",
+                      height: "100%",
+                      borderRadius: 10,
+                      backgroundImage: item.thumbnail ? `url(${item.thumbnail})` : undefined,
+                      backgroundSize: "cover",
+                      backgroundPosition: "center",
+                    }}
+                  />
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function navButtonStyle(side) {
+  return {
+    position: "absolute",
+    top: "50%",
+    transform: "translateY(-50%)",
+    [side]: 12,
+    width: 44,
+    height: 44,
+    borderRadius: 12,
+    border: "1px solid rgba(255,255,255,0.25)",
+    background: "rgba(0,0,0,0.45)",
+    color: "#fff",
+    display: "grid",
+    placeItems: "center",
+    cursor: "pointer",
+    fontSize: 28,
+    lineHeight: 1,
+  };
+}
+
+const pauseButtonStyle = {
+  position: "absolute",
+  top: 12,
+  left: 12,
+  zIndex: 2,
+  width: 40,
+  height: 40,
+  borderRadius: 10,
+  border: "1px solid rgba(255,255,255,0.25)",
+  background: "rgba(0,0,0,0.6)",
+  color: "#fff",
+  display: "grid",
+  placeItems: "center",
+  cursor: "pointer",
+};
+
+function thumbnailButtonStyle(active) {
+  return {
+    width: 72,
+    height: 44,
+    padding: 0,
+    borderRadius: 10,
+    border: active ? "2px solid #111" : "1px solid rgba(0,0,0,0.35)",
+    background: active ? "rgba(0,0,0,0.06)" : "transparent",
+    cursor: "pointer",
+  };
+}
+
+const DEFAULT_ITEMS = [
+  {
+    title: "Neighbors",
+    description: "A chaotic dispute spirals. Watch the latest episode now.",
+    href: "#",
+    image: "https://picsum.photos/seed/hero-1/1200/600",
+    thumbnail: "https://picsum.photos/seed/thumb-1/240/140",
+  },
+  {
+    title: "UCLA at Michigan",
+    description: "Tip-off at 12:45 PM ET. Catch it live.",
+    href: "#",
+    image: "https://picsum.photos/seed/hero-2/1200/600",
+    thumbnail: "https://picsum.photos/seed/thumb-2/240/140",
+  },
+  {
+    title: "Fire Country",
+    description: "A risky mission tests loyalties and nerves.",
+    href: "#",
+    image: "https://picsum.photos/seed/hero-3/1200/600",
+    thumbnail: "https://picsum.photos/seed/thumb-3/240/140",
+  },
+];
+```
+
+## Acceptance Checks
+- Semantics:
+  - The carousel container has `aria-roledescription="carousel"` and an accessible name.
+  - Each slide has `aria-roledescription="slide"` and exposes position (e.g., "2 of 3").
+  - Content of non-visible slides is not reachable by keyboard or screen reader.
+- Autoplay:
+  - With `prefers-reduced-motion: reduce`, autoplay is paused by default.
+  - Tabbing into the carousel pauses autoplay.
+  - Autoplay does not run while paused.
+- Controls (keyboard):
+  - Previous and Next buttons are reachable via Tab and move one slide per activation.
+  - Each thumbnail is reachable via Tab and activates its corresponding slide.
+  - Each thumbnail's `aria-label` includes not only "Go to slide N" but also a simple title or name for the corresponding slide.
+  - The active thumbnail exposes state (e.g., `aria-current="true"`).
+- Content:
+  - Each slide includes a visible title (`<h2>`), a short description, and one primary CTA link.
+- Screen reader:
+  - When changing slides while paused, the carousel name and slide position are announced without duplicate announcements.

package/corpus/web/react/components/collection-row.basic.md

@@ -0,0 +1,179 @@
+---
+id: collection-row.basic
+title: Collection Row
+stack: web/react
+status: beta
+latest_version: 0.2.0
+tags: [collection-row, shelf, rail, horizontal-list, ecommerce, navigation]
+aliases: [content row, content rail, rail, strip, shelf, multi item carousel, product row, product card grid, product cards, card row, media row]
+summary: Horizontal product shelf with a heading, list semantics, and Prev/Next paging that moves focus to newly revealed items.
+---
+
+# Collection Row
+
+Pattern ID: `collection-row.basic`
+
+Horizontal product shelf with a heading, list semantics, and Prev/Next paging that moves focus to newly revealed items.
+
+## Use When
+- Use when displaying multiple related items in a horizontally scrollable row under a shared category heading (e.g., "Customers Also Viewed", "Action Movies").
+- Use when multiple items are visible simultaneously and can be scrolled left or right.
+- Use when each item is a compact card with a primary visual element and brief supporting text.
+
+## Do Not Use When
+- Do not use when only one item is visible at a time within a rotatable sequence (use `carousel`).
+- Do not use when items are arranged in a multi-row or multi-column layout (use `grid`).
+- Do not use when items are presented as a simple vertical list without horizontal scrolling (use `list`).
+
+## Must Haves
+- Use a visible heading, typically an `<h2>`, above the row.
+- Use list semantics for the row: `ul` with `li` items.
+- Each item must comprise a single focus stop: in other words, consist of a single link `<a>` that contains:
+  - A visual element (image, poster, thumbnail, or media preview).
+  - A visible title that identifies the item.
+  - Optional visible metadata (e.g., price, episode number, rating).
+- Each item link must have an accessible name composed of:
+  - title + metadata (optional) via `aria-labelledby`
+- Each item link should expose position context (e.g., "3 of 18") as supplemental information:
+  - Provide an offscreen "X of Y" element.
+  - Reference it via `aria-describedby`.
+  - The position must reflect the item's index within the full set, not just the currently visible subset.
+- Provide paging controls:
+  - Next button on the right edge of the row container (vertically centered)
+  - Previous button on the left edge when not on the first page
+- Paging focus behavior:
+  - Activating Next moves focus to the first newly revealed item (left-most visible link).
+    - For example, if items 1 through 6 are visible, and the user activates the Next button, then items 7 through 12 become visible, and focus moves to item 7.
+  - Activating Previous moves focus to the last newly revealed item (right-most visible link).
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) on each item and button.
+ 
+## Customizable
+- In the golden pattern, we wrap the component in a container with `role="group"` and `aria-labelledby` pointing to the heading ID. This is optional. Engineers may choose instead to use a `<section>` or `role="region"`, or to eschew the container entirely.
+- Items must at minimum have some "title" text that gives each item a name, but they are not required to also have metadata, like a price, or rating, etc.
+
+## Don'ts
+- Do not let Tab from the last visible item move into out-of-view items; it must reach the Next button instead.
+- Do not split the item into multiple separate interactive elements (one item = one link).
+- Do not rely solely on poster art or imagery to communicate the name of each item.
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+export function CollectionRow({ heading = "Customers Also Viewed", items = ITEMS, pageSize = 4 }) {
+  const headingId = useId();
+  const [startIndex, setStartIndex] = useState(0);
+
+  const linkRefs = useRef([]);
+
+  const total = items.length;
+  const endIndex = Math.min(startIndex + pageSize, total);
+  const visible = items.slice(startIndex, endIndex);
+
+  const canPrev = startIndex > 0;
+  const canNext = endIndex < total;
+
+  function goNext() {
+    if (!canNext) return;
+    const nextStart = Math.min(startIndex + pageSize, Math.max(total - pageSize, 0));
+    setStartIndex(nextStart);
+    requestAnimationFrame(() => linkRefs.current[0]?.focus());
+  }
+
+  function goPrev() {
+    if (!canPrev) return;
+    const prevStart = Math.max(startIndex - pageSize, 0);
+    setStartIndex(prevStart);
+    requestAnimationFrame(() => linkRefs.current[visible.length - 1]?.focus());
+  }
+
+  return (
+    <div role="group" aria-labelledby={headingId}>
+      <h2 id={headingId}>{heading}</h2>
+
+      {canPrev && (
+        <button type="button" onClick={goPrev} aria-label="Previous items">
+          Prev
+        </button>
+      )}
+
+      <ul>
+        {visible.map((item, i) => {
+          const globalIndex = startIndex + i;
+          const titleId = `${headingId}-title-${globalIndex}`;
+          const metaId = `${headingId}-meta-${globalIndex}`;
+          const posId = `${headingId}-pos-${globalIndex}`;
+
+          return (
+            <li key={item.id}>
+              <a
+                href={item.href}
+                ref={(el) => (linkRefs.current[i] = el)}
+                aria-labelledby={`${titleId} ${metaId}`}
+                aria-describedby={posId}
+              >
+                <span aria-hidden="true">[image]</span>
+                <div id={titleId}>{item.title}</div>
+                <span id={posId} style={srOnly}>
+                  {globalIndex + 1} of {total}
+                </span>
+                <div id={metaId}>{item.meta}</div>
+              </a>
+            </li>
+          );
+        })}
+      </ul>
+
+      {canNext && (
+        <button type="button" onClick={goNext} aria-label="Next items">
+          Next
+        </button>
+      )}
+    </div>
+  );
+}
+
+// Visually-hidden styles matching the global sr-only utility (global.sr-only).
+const srOnly = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0,0,0,0)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+const ITEMS = [
+  { id: "1", title: "Item One", meta: "$24.95", href: "#" },
+  { id: "2", title: "Item Two", meta: "$29.00", href: "#" },
+  { id: "3", title: "Item Three", meta: "$18.50", href: "#" },
+  { id: "4", title: "Item Four", meta: "$22.00", href: "#" },
+  { id: "5", title: "Item Five", meta: "$27.99", href: "#" },
+  { id: "6", title: "Item Six", meta: "$16.95", href: "#" },
+  { id: "7", title: "Item Seven", meta: "$25.50", href: "#" },
+  { id: "8", title: "Item Eight", meta: "$34.00", href: "#" },
+];
+```
+
+## Acceptance Checks
+- Structure:
+  - A visible heading is present.
+  - The row uses `ul` / `li` semantics.
+  - Each item is a single link wrapping its content.
+- Accessible naming:
+  - Each link exposes a programmatic name that includes the visible title.
+  - If metadata is present, it contributes to the accessible name.
+  - Each link exposes position context (e.g., "3 of 18") once via `aria-describedby`.
+- Keyboard:
+  - Tab order reaches Previous and Next buttons without forcing navigation through hidden items.
+  - Activating Next moves focus to the first newly visible item.
+  - Activating Previous moves focus to the last newly visible item.
+  - Tabbing from the last visible item moves to the Next button (not to hidden items).
+- Visual focus:
+  - All interactive elements (item links and paging buttons) have a visible focus indicator.