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

package/src/Component/Carousel/Elements/Carousel.ts

@@ -3,7 +3,7 @@
  * @file Support scrolling with buttons.
  */
 
-import { createElement } from "../../../Utility/utilities"
+import { createElement, validators } from "../../../Utility/utilities"
 
 export default class Carousel extends HTMLElement {
   internals_: ElementInternals
@@ -12,7 +12,11 @@ export default class Carousel extends HTMLElement {
   loop?: boolean
   paginationType?: "pagination" | "counter"
   activePage?: number
-  itemMap?: Map<HTMLLIElement, boolean>
+  itemMap?: Map<HTMLElement, boolean>
+  iO: IntersectionObserver
+  rO: ResizeObserver
+  mO: MutationObserver
+  ioTimeout?: ReturnType<typeof setTimeout>
 
   constructor() {
     super()
@@ -21,11 +25,11 @@ export default class Carousel extends HTMLElement {
   }
 
   connectedCallback(): void {
-    if (!this.list) return
+    if (!this.track) return
     if (this.buttons) this.buttons.hidden = false
 
     this.activePage = 0
-    this.list.scrollLeft = 0
+    this.track.scrollLeft = 0
     this.debounced = null
     this.loop = this.hasAttribute("loop")
 
@@ -40,7 +44,7 @@ export default class Carousel extends HTMLElement {
       this.next.addEventListener("click", () => this.handleNavigation(this.activePage + 1), {
         signal,
       })
-    this.list.addEventListener("scroll", this.handleScroll, { signal })
+    this.track.addEventListener("scroll", this.handleScroll, { signal })
 
     if (this.pagination) {
       this.paginationType = this.pagination.getAttribute("data-pagination") as
@@ -52,68 +56,90 @@ export default class Carousel extends HTMLElement {
       })
     }
 
-    const items: NodeListOf<HTMLLIElement> = this.list.querySelectorAll(":scope > li")
+    Array.from(this.track.children).forEach((child, index) => {
+      child.setAttribute("data-index", String(index))
+    })
+    const items: NodeListOf<HTMLElement> = this.track.querySelectorAll("[data-index]")
     this.itemMap = new Map()
-    const iO = new IntersectionObserver(
+    this.iO = new IntersectionObserver(
       entries => {
         entries.forEach(({ target, intersectionRatio }) => {
-          const li = target as HTMLLIElement
+          const item = target as HTMLElement
           if (intersectionRatio > 0.5) {
-            li.removeAttribute("inert")
-            this.itemMap.set(li, true)
+            item.removeAttribute("inert")
+            item.setAttribute("aria-hidden", "false")
+            this.itemMap.set(item, true)
           } else {
-            li.setAttribute("inert", "")
-            this.itemMap.set(li, false)
+            item.setAttribute("inert", "")
+            item.setAttribute("aria-hidden", "true")
+            this.itemMap.set(item, false)
           }
         })
       },
       {
-        root: this.list,
+        root: this.track,
         threshold: 0.5,
       },
     )
-    items.forEach(item => iO.observe(item))
+    items.forEach(item => this.iO.observe(item))
 
-    const rO = new ResizeObserver(entries => {
+    this.rO = new ResizeObserver(entries => {
       entries.forEach(() => this.handleOverflow())
     })
-    rO.observe(this.list)
+    this.rO.observe(this.track)
 
-    const mO = new MutationObserver(entries => {
+    this.mO = new MutationObserver(entries => {
       entries.forEach(() => this.handleOverflow())
     })
-    mO.observe(this.list, { childList: true })
+    this.mO.observe(this.track, { childList: true })
   }
 
   disconnectedCallback(): void {
     this.controller.abort()
+    this.mO.disconnect()
+    this.iO.disconnect()
+    this.rO.disconnect()
+    clearTimeout(this.debounced)
+    clearTimeout(this.ioTimeout)
   }
 
   handleNavigation = (page: number, type: "arrow" | "pagination" = "arrow") => {
     const goesForward = page > this.activePage
     const hasRestart = this.loop && this.next.hasAttribute("data-restart")
-    if (!this.pagination) this.activePage = page
     if (page === 0 || (hasRestart && goesForward && type === "arrow")) {
-      // Scroll to the start.
-      this.items[0].scrollIntoView({ inline: "start", block: "center" })
+      // Reset to page 0 rather than the requested (out-of-range) page —
+      // otherwise every subsequent click computes an out-of-bounds item
+      // index and throws instead of scrolling.
+      this.activePage = 0
+      this.items[0].scrollIntoView({ inline: "start", block: "nearest" })
       this.next.removeAttribute("data-restart")
       return
     }
+    this.activePage = page
     // Scroll to the first item of a page.
     this.items[this.visibleCount * page].scrollIntoView({
       inline: "start",
-      block: "center",
+      block: "nearest",
     })
     if (hasRestart && !goesForward) this.next.removeAttribute("data-restart")
+    const newEvent: CustomEvent<{
+      page: number
+      type: "arrow" | "pagination"
+    }> = new CustomEvent("carousel-slide", {
+      bubbles: true,
+      cancelable: true,
+      detail: { page: this.activePage, type },
+    })
+    this.dispatchEvent(newEvent)
   }
 
   handleDisabled = () => {
     let isEnd = false
-    if (this.prev) this.prev.disabled = this.list.scrollLeft < 200
+    if (this.prev) this.prev.disabled = this.track.scrollLeft < 200
     if (this.next || this.pagination) {
       isEnd =
-        Math.round(this.list.scrollLeft) >=
-        Math.round(this.list.scrollWidth - this.list.offsetWidth)
+        Math.round(this.track.scrollLeft) >=
+        Math.round(this.track.scrollWidth - this.track.offsetWidth)
     }
     if (this.next) {
       if (!this.loop) {
@@ -124,82 +150,98 @@ export default class Carousel extends HTMLElement {
     }
     if (this.pagination) {
       // Set the activePage based on scroll.
-      const startPosition = Math.round(this.list.offsetLeft + this.list.scrollLeft)
+      const startPosition = Math.round(this.track.offsetLeft + this.track.scrollLeft)
       if (isEnd) {
         // If it's the end, the last page is active.
         this.activePage = this.pageStartItems.length - 1
       } else {
-        // Otherwise when the start of a page reaches the start of it's container, then set it to the active page.
+        // 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
         this.pageStartItems.forEach((item, index) => {
-          if (Math.round(item.offsetLeft) === startPosition) this.activePage = index
+          const distance = Math.abs(Math.round(item.offsetLeft) - startPosition)
+          if (distance < closestDistance) {
+            closestDistance = distance
+            closestIndex = index
+          }
         })
+        this.activePage = closestIndex
       }
 
       this.pagination.querySelectorAll("button").forEach(button => {
         const index = button.getAttribute("data-index")
         if (!index) return
         const page = parseInt(index, 10)
-        button.disabled = page === this.activePage
+        const isActive = page === this.activePage
+        button.disabled = isActive
+        if (isActive) {
+          button.setAttribute("aria-current", "page")
+        } else {
+          button.removeAttribute("aria-current")
+        }
       })
     }
   }
 
   handleScroll = () => {
-    window.clearTimeout(this.debounced)
+    clearTimeout(this.debounced)
     this.debounced = setTimeout(this.handleDisabled, this.pagination ? 100 : 200)
   }
 
   handleOverflow = () => {
-    const { scrollWidth, clientWidth } = this.list
+    const { scrollWidth, clientWidth } = this.track
     const hasOverflow = scrollWidth > clientWidth
-    this.list.classList.toggle("overflowing", hasOverflow)
+    this.track.classList.toggle("overflowing", hasOverflow)
     if (hasOverflow) {
       if (this.pagination) {
         // Timeout needed for this.itemMap to get populated by i0.
-        setTimeout(this.buildPagination, 200)
+        this.ioTimeout = setTimeout(this.buildPagination, 200)
       }
-      this.list.setAttribute("tabindex", "0")
+      this.track.setAttribute("tabindex", "0")
     } else {
-      this.list.removeAttribute("tabindex")
+      this.track.removeAttribute("tabindex")
     }
   }
 
   buildPagination = () => {
     if (!this.pagination.hidden) {
       // Existing pagination
-      const currentPages = this.pagination.querySelectorAll(":scope > li")
+      const currentPages = this.pagination.querySelectorAll("button")
       if (currentPages.length === this.pageStartItems.length) return
       // If the number of pages changes, remove current ones so it can be rebuilt.
-      currentPages.forEach(li => li.remove())
+      currentPages.forEach(page => page.remove())
     }
-    const pages = new Array(this.pageStartItems.length).fill(null)
+    const pages = Array.from({ length: this.pageStartItems.length }).fill(null)
     if (pages.length <= 0) return
     pages.forEach((_, index) => {
-      const li = createElement(
-        `<li><button type="button" data-index="${index}">${index + 1}</button>`,
+      const label = index + 1
+      const tab = createElement(
+        `<button type="button" data-index="${index}" aria-label="Page ${label}">${label}</button>`,
       )
-      this.pagination.append(li)
-      pages[index] = li
+      this.pagination.append(tab)
+      pages[index] = tab
     })
-    const firstPage = pages[0] as HTMLLIElement
-    firstPage.querySelector("button").disabled = true
+    const firstPage = pages[0] as HTMLButtonElement
+    firstPage.disabled = true
+    firstPage.setAttribute("aria-current", "page")
     this.pagination.hidden = false
   }
 
   handlePagination = (event: MouseEvent) => {
     const target = event.target as HTMLButtonElement
     const index = target.getAttribute("data-index")
-    if (!index) return
+    if (!index || !validators.integer(index, 0)) return
     const page: number = parseInt(index, 10)
     this.handleNavigation(page, "pagination")
   }
 
-  get list(): HTMLUListElement | null {
-    const list: HTMLUListElement | null = this.querySelector(":scope > ul")
-    if (!list) {
-      throw new Error(`${this.localName} must contain a <ul> element.`)
+  get track(): HTMLDivElement | null {
+    const track: HTMLDivElement | null = this.querySelector("[data-track]")
+    if (!track) {
+      throw new Error(`${this.localName} must contain an element with [data-track].`)
     }
-    return list
+    return track
   }
 
   get buttons(): HTMLElement | null {
@@ -218,7 +260,7 @@ export default class Carousel extends HTMLElement {
     return this.querySelector("[data-pagination]")
   }
 
-  get items(): HTMLLIElement[] {
+  get items(): HTMLElement[] {
     return [...this.itemMap.keys()]
   }
 
@@ -226,7 +268,7 @@ export default class Carousel extends HTMLElement {
     return [...this.itemMap.values()].filter(visible => visible).length
   }
 
-  get pageStartItems(): HTMLLIElement[] {
+  get pageStartItems(): HTMLElement[] {
     return [...this.items].filter((_, index) => index % this.visibleCount === 0)
   }
 }

package/src/Component/Carousel/README.md

@@ -0,0 +1,243 @@
+# Carousel
+
+A horizontally scrolling list of items (usually Cards or ContentBlocks) with native CSS scroll-snap. Progressive enhancement via the `<mx-carousel>` Web Component adds prev/next buttons, numbered pagination or dot counters, and an optional loop-to-start behaviour.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Carousel/carousel.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Carousel/carousel.twig' with {
+  items: [
+    card_1,
+    card_2,
+    card_3
+  ],
+  pagination: false,
+  counter: false,
+  loop: false
+} %}
+```
+
+**carousel.twig props** (`Carousel` type from `ids-shape`):
+
+| Prop         | Type                       | Default | Description                                                                      |
+| ------------ | -------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `items`      | `GridItem[] \| Collection` | —       | List of rendered items (usually Cards or ContentBlocks). Required.               |
+| `pagination` | `boolean`                  | `false` | Adds numbered pagination. Requires the Carousel JS.                              |
+| `counter`    | `boolean`                  | `false` | Adds dot counter navigation. Requires the Carousel JS.                           |
+| `loop`       | `boolean`                  | `false` | When Next is clicked at the end, scroll back to start. Requires the Carousel JS. |
+
+If both `pagination` and `counter` are passed, `pagination` wins.
+
+---
+
+## HTML
+
+The `<mx-carousel>` custom element enhances a `<div class="mx-carousel__scrollable" data-track>` with:
+
+- Prev/Next scroll buttons (revealed only when the list overflows)
+- Optional numbered pagination (`data-pagination="pagination"`) or dot counters (`data-pagination="counter"`) — both are built dynamically by the JS based on how many items fit per page
+- Optional `loop` attribute — when the Next button reaches the end, the next click scrolls back to the start
+- `inert` is toggled on items less than 50% visible (greys them out and removes them from focus/AT)
+- `tabindex="0"` is added to the scroll container when it overflows, so it is keyboard-scrollable
+
+```html
+<mx-carousel class="mx-carousel" role="region" aria-roledescription="carousel">
+  <div
+    class="mx-carousel__buttons"
+    data-buttons
+    hidden
+    role="group"
+    aria-label="Quick page controls"
+  >
+    <button class="mx-carousel__prev mx-button mx-button--icon-only" type="button">
+      <span class="sr-only">previous page</span>
+      <span class="mx-icon mx-icon--chevron-left"></span>
+    </button>
+    <button class="mx-carousel__next mx-button mx-button--icon-only" type="button">
+      <span class="sr-only">next page</span>
+      <span class="mx-icon mx-icon--chevron-right"></span>
+    </button>
+  </div>
+  <div class="mx-carousel__scrollable" data-track aria-live="off">
+    <div data-index="0"><!-- item 1 --></div>
+    <div data-index="1"><!-- item 2 --></div>
+    <div data-index="2"><!-- item 3 --></div>
+  </div>
+</mx-carousel>
+```
+
+Items are plain `<div>`s, not `<li>`s — a page can show a variable number of items depending on viewport width, so there's no fixed list grouping to hang list semantics off. Each item carries `data-index` (its position in `items`) so other components can address it reliably (e.g. `carousel.track.querySelector('[data-index="2"]')`) instead of relying on DOM order — used by `Gallery` to scroll to the item matching a clicked trigger.
+
+**Import the JS** (required for buttons, pagination, counter, and loop — without it the list still scrolls natively):
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Carousel/Elements/Carousel"
+```
+
+### With numbered pagination
+
+```html
+<mx-carousel class="mx-carousel" role="region" aria-roledescription="carousel">
+  <div
+    class="mx-carousel__buttons"
+    data-buttons
+    hidden
+    role="group"
+    aria-label="Quick page controls"
+  >
+    ...
+  </div>
+  <div class="mx-carousel__scrollable" data-track aria-live="off">...</div>
+  <div
+    class="mx-carousel__pagination"
+    data-pagination="pagination"
+    hidden
+    role="group"
+    aria-label="Page controls"
+  ></div>
+</mx-carousel>
+```
+
+### With dot counters
+
+```html
+<div
+  class="mx-carousel__pagination"
+  data-pagination="counter"
+  hidden
+  role="group"
+  aria-label="Page controls"
+></div>
+```
+
+### With loop
+
+```html
+<mx-carousel class="mx-carousel" role="region" aria-roledescription="carousel" loop
+  >...</mx-carousel
+>
+```
+
+Notes:
+
+- The `[data-pagination]` element must be empty and `hidden` in source — the JS appends `<button data-index="N" aria-label="Page N">N</button>` for each page once it measures overflow.
+- Pagination and counter are mutually exclusive — use one or the other.
+- The number of pages equals `Math.ceil(items / visibleItemsPerPage)`, measured at runtime.
+
+---
+
+## React
+
+```tsx
+import { Carousel } from "@pnx-mixtape/mxds/react"
+import { Card, CardContent } from "@pnx-mixtape/mxds"
+;<Carousel
+  items={[
+    <Card block>
+      <CardContent>
+        <h3>Item 1</h3>
+        <p>Content</p>
+      </CardContent>
+    </Card>,
+    <Card block>
+      <CardContent>
+        <h3>Item 2</h3>
+        <p>Content</p>
+      </CardContent>
+    </Card>,
+    <Card block>
+      <CardContent>
+        <h3>Item 3</h3>
+        <p>Content</p>
+      </CardContent>
+    </Card>,
+  ]}
+  pagination
+/>
+```
+
+Prev/Next buttons, pagination, counter, and loop behaviour are powered by React state and `IntersectionObserver`/`ResizeObserver` — no Web Component import required for the React component.
+
+The `Elements/Carousel.ts` Web Component is still available and unchanged for Twig/HTML contexts — import it there as before.
+
+**Props:**
+
+| Prop         | Type          | Default | Description                                                                                 |
+| ------------ | ------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `items`      | `ReactNode[]` | —       | List of items to render as `<li>` children of the scroll container. Required.               |
+| `pagination` | `boolean`     | `false` | Show numbered pagination buttons below the carousel (built once the list overflows)         |
+| `counter`    | `boolean`     | `false` | Show dot counter navigation. Mutually exclusive with `pagination` — pagination wins if both |
+| `loop`       | `boolean`     | `false` | When Next is clicked at the end, scroll back to the first item                              |
+| `className`  | `string`      | —       | Extra class on the outer `<div>`                                                            |
+
+Control the number of visible items per page via the `--inline-size` CSS custom property (default `25ch`) — see Customisation below.
+
+---
+
+## Modifiers
+
+The Carousel component itself has no modifier classes or enum. Variation is controlled via the three boolean attributes/props above (`loop`, `pagination`, `counter`) and the `--inline-size` custom property (see Customisation).
+
+Child items (each wrapped in a plain `<div data-index>`) are styled by whichever component is placed inside them (typically Card with its own modifiers).
+
+---
+
+## Accessibility
+
+Honest accounting of what this component does and does not do:
+
+**What it does:**
+
+- Sets `role="region" aria-roledescription="carousel"` on `<mx-carousel>` so the whole area is announced as a distinct carousel landmark.
+- Items are plain `<div data-index>` children of the scroll container (not a `<ul>`/`<li>` list) — scroll-snap needs a flat, individually-snappable set of children whose count-per-page varies by viewport, which doesn't map onto a fixed list grouping. Pagination is a plain `role="group"` of `<button>`s for the same reason (see below).
+- The scroll container has `aria-live="off"` to suppress the browser's default behaviour of announcing content changes on every scroll, which would otherwise fire constantly.
+- Prev/Next buttons have visually hidden `<span class="sr-only">` labels ("previous page", "next page"); the chevron icons are not announced separately.
+- When the list overflows, `tabindex="0"` is added to the scroll container so keyboard users can focus it and scroll with arrow keys.
+- Items less than 50% visible get the `inert` attribute, which removes their focusable children from the tab order and hides them from assistive tech — so keyboard users don't tab into partially off-screen content.
+- Prev is disabled at the start; Next is disabled at the end (unless `loop`, in which case Next gains `data-restart` instead).
+- Active pagination/counter button is set to `disabled` (so it is not re-activatable) and gets `aria-current="page"`, so it is announced as the current page even where `disabled` alone isn't conveyed.
+- Pagination is a plain `role="group"` of buttons, not a `tablist`/`tab`/`tabpanel` triad — that pattern assumes one tab reveals exactly one panel, which doesn't hold here since a page can show a variable number of items depending on viewport width. Items themselves carry no `role`/`aria-roledescription="slide"` for the same reason: an item isn't a "slide", the group of currently-visible items is.
+
+**What it does NOT do:**
+
+- No default `aria-label` on `<mx-carousel>` — `role="region"` plus `aria-roledescription="carousel"` without an accessible name is announced as just "carousel". Pass an `aria-label` yourself (e.g. via the `attributes` prop in Twig) describing what the carousel contains.
+- No live-region announcement of page changes — `data-track`'s `aria-live` is explicitly `off`, so scrolling/paginating doesn't get spoken.
+- No auto-advance / auto-play, and therefore no pause/play controls. All movement is user-initiated (scroll, button click, pagination click).
+- Keyboard navigation is native scroll-container arrow keys, not custom Left/Right arrow handlers on the buttons. The buttons themselves are reachable by Tab.
+
+If your use case requires auto-play or richer APG semantics, wrap the component and add them at the integration layer.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-carousel {
+  --vertical-gap: var(--gap); /* gap between scrollable list and pagination/buttons */
+  --horizontal-gap: var(--gap); /* gap between items in the scroll list */
+  --inline-size: 25ch; /* min width of each item — controls how many fit per page */
+  --scrollbar-gap: var(--gap); /* space below the list when a scrollbar is visible */
+  --scrollbar-color: var(--colour-border) transparent;
+}
+
+/* Pagination buttons */
+.mx-carousel__pagination {
+  --border-radius: var(--border-radius); /* overridden to --border-radius-round for counter */
+  --indent: unset; /* overridden to 200% for counter (hides the number) */
+  --line-width: 2px;
+  --line-colour: var(--colour-border);
+  --background: var(--colour-background);
+  --foreground: var(--colour-foreground);
+  --active-background: var(--colour-border); /* disabled/active page button background */
+}
+```
+
+The number of items visible per page is a product of `--inline-size` and the container width — it is measured at runtime by the Web Component and used to build pagination and to calculate scroll distances.