@chassis-ui/react 0.0.0-20260831090525

package/src/components/carousel/CarouselControlButton.tsx

@@ -0,0 +1,74 @@
+import React, { ButtonHTMLAttributes, forwardRef, useEffect, useRef } from 'react'
+import classNames from 'classnames'
+
+import { useForkedRef } from '../../hooks'
+import { markPointerClick } from '../../utils/pointerInteraction'
+import { Icon } from '../icon'
+import { useCarouselContext } from './context'
+
+interface CarouselControlButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Which direction this control navigates, and which end-of-track state disables it.
+   */
+  direction: 'prev' | 'next'
+  /**
+   * The accessible label announced by assistive technology.
+   */
+  label?: string
+}
+
+// Shared prev/next control, used by both CarouselControlPrev and CarouselControlNext — mirrors
+// how CalendarNavButton.tsx factors the same shape for Calendar/RangeCalendar.
+export const CarouselControlButton = forwardRef<HTMLButtonElement, CarouselControlButtonProps>(
+  ({ children, className, direction, disabled, label, onClick, ...rest }, ref) => {
+    const { atEnd, atStart, ends, next, prev, registerControl } = useCarouselContext()
+    const buttonRef = useRef<HTMLButtonElement>(null)
+    const forkedRef = useForkedRef(ref, buttonRef)
+
+    useEffect(() => {
+      const element = buttonRef.current
+      if (!element) return undefined
+      return registerControl(direction, element)
+    }, [registerControl, direction])
+
+    const atBoundary = direction === 'next' ? atEnd : atStart
+    const navigate = direction === 'next' ? next : prev
+
+    // Compose rather than let a caller's `onClick`/`disabled` silently replace navigation: the
+    // carousel's own end-of-track state can only ever add a disable, and the click handler always
+    // still navigates the carousel alongside whatever the caller's handler does.
+    const isDisabled = disabled || (ends === 'stop' && atBoundary)
+    const handleClick: typeof onClick = (event) => {
+      onClick?.(event)
+      if (event.detail !== 0) markPointerClick(event.currentTarget)
+      navigate()
+    }
+
+    return (
+      <button
+        type="button"
+        className={classNames('button small icon-only', className)}
+        disabled={isDisabled}
+        onClick={handleClick}
+        {...rest}
+        ref={forkedRef}
+      >
+        {children ?? (
+          <>
+            <Icon
+              name={direction === 'next' ? 'chevron-right-outline' : 'chevron-left-outline'}
+              className="directional-icon"
+            />
+            <span className="visually-hidden">{label}</span>
+          </>
+        )}
+      </button>
+    )
+  }
+)
+
+CarouselControlButton.displayName = 'CarouselControlButton'

package/src/components/carousel/CarouselControlNext.tsx

@@ -0,0 +1,22 @@
+import React, { ButtonHTMLAttributes, forwardRef } from 'react'
+
+import { CarouselControlButton } from './CarouselControlButton'
+
+export interface CarouselControlNextProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * The accessible label announced by assistive technology.
+   */
+  label?: string
+}
+
+export const CarouselControlNext = forwardRef<HTMLButtonElement, CarouselControlNextProps>(
+  ({ label = 'Next slide', ...rest }, ref) => (
+    <CarouselControlButton {...rest} direction="next" label={label} ref={ref} />
+  )
+)
+
+CarouselControlNext.displayName = 'CarouselControlNext'

package/src/components/carousel/CarouselControlPrev.tsx

@@ -0,0 +1,22 @@
+import React, { ButtonHTMLAttributes, forwardRef } from 'react'
+
+import { CarouselControlButton } from './CarouselControlButton'
+
+export interface CarouselControlPrevProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * The accessible label announced by assistive technology.
+   */
+  label?: string
+}
+
+export const CarouselControlPrev = forwardRef<HTMLButtonElement, CarouselControlPrevProps>(
+  ({ label = 'Previous slide', ...rest }, ref) => (
+    <CarouselControlButton {...rest} direction="prev" label={label} ref={ref} />
+  )
+)
+
+CarouselControlPrev.displayName = 'CarouselControlPrev'

package/src/components/carousel/CarouselIndicators.tsx

@@ -0,0 +1,44 @@
+import React, { forwardRef, HTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+import { useCarouselContext } from './context'
+
+export interface CarouselIndicatorsProps extends HTMLAttributes<HTMLOListElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Accessible label for each indicator button. Receives the slide's 1-based position.
+   */
+  label?: (position: number) => string
+}
+
+export const CarouselIndicators = forwardRef<HTMLOListElement, CarouselIndicatorsProps>(
+  ({ className, label = (position) => `Slide ${position}`, ...rest }, ref) => {
+    const { activeIndex, itemCount, itemsVisible, to } = useCarouselContext()
+    const _className = classNames('carousel-indicators', className)
+    // One indicator per reachable position, not per item — mirrors `navigate()`'s own clamping so
+    // an indicator never targets an index the carousel can't actually land on (e.g. with
+    // `items > 1`, the last few slides only ever appear alongside an earlier one).
+    const indicatorCount = itemCount === 0 ? 0 : Math.max(1, itemCount - itemsVisible + 1)
+
+    return (
+      <ol className={_className} {...rest} ref={ref}>
+        {Array.from({ length: indicatorCount }, (_, index) => index).map((index) => (
+          <li key={index}>
+            <button
+              type="button"
+              className={index === activeIndex ? 'active' : undefined}
+              aria-current={index === activeIndex ? 'true' : undefined}
+              aria-label={label(index + 1)}
+              onClick={() => to(index)}
+            />
+          </li>
+        ))}
+      </ol>
+    )
+  }
+)
+
+CarouselIndicators.displayName = 'CarouselIndicators'

package/src/components/carousel/CarouselInner.tsx

@@ -0,0 +1,56 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { useForkedRef } from '../../hooks'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { useCarouselContext } from './context'
+
+type CarouselInnerOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+}
+
+export type CarouselInnerProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  CarouselInnerOwnProps<C>
+>
+
+type CarouselInnerComponent = (<C extends ElementType = 'div'>(
+  props: CarouselInnerProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+/**
+ * The scroll viewport — a real horizontally-scrolling container using CSS scroll-snap. Wrap
+ * CarouselItem children in this rather than passing them directly to Carousel, so controls and
+ * indicators can sit alongside it (above, below, or overlaid) instead of inside the scroll track.
+ */
+function CarouselInnerRender<C extends ElementType = 'div'>(
+  { children, className, component, ...rest }: CarouselInnerProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const { registerViewport } = useCarouselContext()
+  const Component = component ?? 'div'
+  const forkedRef = useForkedRef(ref, registerViewport)
+  const _className = classNames('carousel-inner', className)
+
+  return (
+    <Component className={_className} {...rest} ref={forkedRef}>
+      {children}
+    </Component>
+  )
+}
+
+export const CarouselInner = createPolymorphicComponent<CarouselInnerComponent>(
+  CarouselInnerRender as ForwardRefRenderFunction<Element, CarouselInnerProps<ElementType>>,
+  'CarouselInner'
+)

package/src/components/carousel/CarouselItem.tsx

@@ -0,0 +1,51 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type CarouselItemOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Milliseconds to wait before autoplay advances past this slide, overriding the carousel's own `interval`.
+   */
+  interval?: number
+}
+
+export type CarouselItemProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  CarouselItemOwnProps<C>
+>
+
+type CarouselItemComponent = (<C extends ElementType = 'div'>(
+  props: CarouselItemProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function CarouselItemRender<C extends ElementType = 'div'>(
+  { children, className, component, interval, ...rest }: CarouselItemProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('carousel-item', className)
+
+  return (
+    <Component className={_className} data-interval={interval} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const CarouselItem = createPolymorphicComponent<CarouselItemComponent>(
+  CarouselItemRender as ForwardRefRenderFunction<Element, CarouselItemProps<ElementType>>,
+  'CarouselItem'
+)

package/src/components/carousel/CarouselOverlay.tsx

@@ -0,0 +1,51 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type CarouselOverlayOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+}
+
+export type CarouselOverlayProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  CarouselOverlayOwnProps<C>
+>
+
+type CarouselOverlayComponent = (<C extends ElementType = 'div'>(
+  props: CarouselOverlayProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+/**
+ * Overlays its children (typically controls and indicators) on top of the slides instead of
+ * stacking them in the flow.
+ */
+function CarouselOverlayRender<C extends ElementType = 'div'>(
+  { children, className, component, ...rest }: CarouselOverlayProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('carousel-overlay', className)
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const CarouselOverlay = createPolymorphicComponent<CarouselOverlayComponent>(
+  CarouselOverlayRender as ForwardRefRenderFunction<Element, CarouselOverlayProps<ElementType>>,
+  'CarouselOverlay'
+)

package/src/components/carousel/CarouselPlayPause.tsx

@@ -0,0 +1,61 @@
+import React, { ButtonHTMLAttributes, forwardRef } from 'react'
+import classNames from 'classnames'
+
+import { Icon } from '../icon'
+import { useCarouselContext } from './context'
+
+export interface CarouselPlayPauseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * The accessible label announced while autoplay is running.
+   */
+  pauseLabel?: string
+  /**
+   * The accessible label announced while autoplay is stopped.
+   */
+  playLabel?: string
+}
+
+/**
+ * A discoverable toggle so a viewer can stop an autoplaying carousel, as required by WCAG 2.2
+ * Success Criterion 2.2.2 (Pause, Stop, Hide). Reflects the current state automatically — a pause
+ * icon while playing, a play icon once stopped.
+ */
+export const CarouselPlayPause = forwardRef<HTMLButtonElement, CarouselPlayPauseProps>(
+  ({ children, className, onClick, pauseLabel = 'Pause', playLabel = 'Play', ...rest }, ref) => {
+    const { playing, togglePlayPause } = useCarouselContext()
+    const _className = classNames(
+      'carousel-control-play-pause button small icon-only',
+      { paused: !playing },
+      className
+    )
+    // Compose rather than let a caller's `onClick` silently replace the toggle.
+    const handleClick: typeof onClick = (event) => {
+      onClick?.(event)
+      togglePlayPause()
+    }
+
+    return (
+      <button
+        type="button"
+        className={_className}
+        aria-label={playing ? pauseLabel : playLabel}
+        onClick={handleClick}
+        {...rest}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon name="pause-solid" className="carousel-icon-pause" aria-hidden="true" />
+            <Icon name="play-solid" className="carousel-icon-play" aria-hidden="true" />
+          </>
+        )}
+      </button>
+    )
+  }
+)
+
+CarouselPlayPause.displayName = 'CarouselPlayPause'

package/src/components/carousel/carouselEngine.ts

@@ -0,0 +1,170 @@
+// Internal helpers shared by the carousel family. Not exported from the component's public
+// barrel (see CONVENTIONS.md's helper-module carve-out).
+
+export const ITEM_SELECTOR = '.carousel-item:not(.carousel-item-clone)'
+
+export function getCarouselItems(viewport: HTMLElement): HTMLElement[] {
+  return Array.from(viewport.querySelectorAll<HTMLElement>(`:scope > ${ITEM_SELECTOR}`))
+}
+
+export function isRTL(element: Element): boolean {
+  return getComputedStyle(element).direction === 'rtl'
+}
+
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  )
+}
+
+export function isElementVisible(element: Element | null): boolean {
+  if (!element) return false
+  const rect = element.getBoundingClientRect()
+  return (
+    rect.top < (window.innerHeight || document.documentElement.clientHeight) &&
+    rect.bottom > 0 &&
+    rect.left < (window.innerWidth || document.documentElement.clientWidth) &&
+    rect.right > 0
+  )
+}
+
+// Horizontal distance to scroll `viewport` so `target` rests where the active slide belongs —
+// centered when `center` is set, otherwise flush with the scroll-padding (peek) offset, which is
+// exactly where scroll-snap settles. Scrolling the viewport itself (rather than
+// `target.scrollIntoView()`) keeps an off-screen carousel from yanking the whole page to itself.
+export function scrollDeltaFor(
+  viewport: HTMLElement,
+  target: HTMLElement,
+  center: boolean
+): number {
+  const viewportRect = viewport.getBoundingClientRect()
+  const rect = target.getBoundingClientRect()
+
+  if (center) {
+    return rect.left + rect.width / 2 - (viewportRect.left + viewportRect.width / 2)
+  }
+
+  const padStart = Number.parseFloat(getComputedStyle(viewport).scrollPaddingInlineStart) || 0
+
+  return isRTL(viewport)
+    ? rect.right - (viewportRect.right - padStart)
+    : rect.left - (viewportRect.left + padStart)
+}
+
+export function isViewportScrollable(viewport: HTMLElement): boolean {
+  return viewport.scrollWidth - viewport.clientWidth > 0
+}
+
+const SCROLL_DURATION_MS = 300
+// Safety net above the animation's own duration, in case `requestAnimationFrame` stalls (a
+// backgrounded tab, a frozen/suspended webview) and never drives the animation to completion.
+// `setTimeout` still fires in that situation — throttled, but not indefinitely suspended the way
+// rAF can be — so this guarantees the scroll lands on target and callers relying on completion to
+// release a lock (e.g. re-enabling the IntersectionObserver) can never get stuck forever.
+const SCROLL_SAFETY_MS = SCROLL_DURATION_MS + 200
+
+const easeInOutCubic = (progress: number) =>
+  progress < 0.5 ? 4 * progress * progress * progress : 1 - (-2 * progress + 2) ** 3 / 2
+
+// Animates `viewport.scrollLeft` to `targetLeft` by stepping the position by hand each frame,
+// resolving deterministically once the animation completes — not by waiting on the `scrollend`
+// event or a fixed timeout as the *primary* signal. Both of those only approximate when a native
+// `scrollTo({behavior:'smooth'})` actually finishes, and firing early restores CSS scroll-snap
+// mid-flight, which snaps the track back to the nearest point instead of the intended one rather
+// than letting it arrive. Using `behavior: 'instant'` for every step keeps this animation from
+// fighting the viewport's own CSS `scroll-behavior: smooth`. Returns a canceller so a caller that
+// starts a newer scroll before this one finishes can stop it instead of both fighting over the
+// position.
+export function animateScrollTo(
+  viewport: HTMLElement,
+  targetLeft: number,
+  onSettled: () => void
+): () => void {
+  if (prefersReducedMotion() || typeof requestAnimationFrame === 'undefined') {
+    viewport.scrollTo({ left: targetLeft, behavior: 'instant' })
+    onSettled()
+    return () => {}
+  }
+
+  const startLeft = viewport.scrollLeft
+  const distance = targetLeft - startLeft
+  let startTime: number | null = null
+  let frame: number | null = null
+  let done = false
+
+  const finish = () => {
+    if (done) return
+    done = true
+    if (frame !== null) cancelAnimationFrame(frame)
+    clearTimeout(safetyTimer)
+    viewport.scrollTo({ left: targetLeft, behavior: 'instant' })
+    onSettled()
+  }
+
+  const step = (now: number) => {
+    if (done) return
+    if (startTime === null) startTime = now
+
+    const progress = Math.min((now - startTime) / SCROLL_DURATION_MS, 1)
+    viewport.scrollTo({
+      left: startLeft + distance * easeInOutCubic(progress),
+      behavior: 'instant'
+    })
+
+    if (progress < 1) {
+      frame = requestAnimationFrame(step)
+      return
+    }
+
+    finish()
+  }
+
+  const safetyTimer = setTimeout(finish, SCROLL_SAFETY_MS)
+  frame = requestAnimationFrame(step)
+
+  return () => {
+    if (done) return
+    done = true
+    if (frame !== null) cancelAnimationFrame(frame)
+    clearTimeout(safetyTimer)
+  }
+}
+
+export function normalizeIndex(index: number, length: number, wraps: boolean): number | null {
+  if (Number.isNaN(index) || length === 0) return null
+  if (index < 0) return wraps ? length - 1 : null
+  if (index > length - 1) return wraps ? 0 : null
+  return index
+}
+
+export type CarouselDirection = 'left' | 'right'
+
+export function directionBetween(from: number, to: number, rtl: boolean): CarouselDirection {
+  const isNext = to > from
+  if (rtl) return isNext ? 'right' : 'left'
+  return isNext ? 'left' : 'right'
+}
+
+export function loopDirection(isNext: boolean, rtl: boolean): CarouselDirection {
+  if (rtl) return isNext ? 'right' : 'left'
+  return isNext ? 'left' : 'right'
+}
+
+// Seamless looping only reads right for the plain single-slide scroll layout — multi-item, peek,
+// centered, and variable-width layouts fall back to a `wrap` jump instead (see `canLoop`).
+export function canLoop(
+  carouselElement: HTMLElement,
+  itemCount: number,
+  isFade: boolean,
+  center: boolean,
+  auto: boolean
+): boolean {
+  if (isFade || itemCount < 2 || center || auto) return false
+
+  const styles = getComputedStyle(carouselElement)
+  const num = (name: string) => Number.parseFloat(styles.getPropertyValue(name)) || 0
+
+  return (num('--cx-carousel-items') || 1) === 1 && num('--cx-carousel-items-peek') === 0
+}

package/src/components/carousel/context.ts

@@ -0,0 +1,29 @@
+import { createContext, useContext } from 'react'
+
+export type CarouselEnds = 'loop' | 'wrap' | 'stop'
+
+export interface CarouselContextProps {
+  activeIndex: number
+  atEnd: boolean
+  atStart: boolean
+  ends: CarouselEnds
+  itemCount: number
+  itemsVisible: number
+  next: () => void
+  playing: boolean
+  prev: () => void
+  registerControl: (kind: 'prev' | 'next', element: HTMLButtonElement) => () => void
+  registerViewport: (node: HTMLDivElement | null) => void
+  to: (index: number) => void
+  togglePlayPause: () => void
+}
+
+export const CarouselContext = createContext<CarouselContextProps | null>(null)
+
+export const useCarouselContext = (): CarouselContextProps => {
+  const context = useContext(CarouselContext)
+  if (!context) {
+    throw new Error('Carousel sub-components must be rendered inside a Carousel')
+  }
+  return context
+}

package/src/components/carousel/index.ts

@@ -0,0 +1,21 @@
+export { Carousel } from './Carousel'
+export type {
+  CarouselEnds,
+  CarouselProps,
+  CarouselSlideDetail,
+  CarouselTransition
+} from './Carousel'
+export { CarouselControlNext } from './CarouselControlNext'
+export type { CarouselControlNextProps } from './CarouselControlNext'
+export { CarouselControlPrev } from './CarouselControlPrev'
+export type { CarouselControlPrevProps } from './CarouselControlPrev'
+export { CarouselIndicators } from './CarouselIndicators'
+export type { CarouselIndicatorsProps } from './CarouselIndicators'
+export { CarouselInner } from './CarouselInner'
+export type { CarouselInnerProps } from './CarouselInner'
+export { CarouselItem } from './CarouselItem'
+export type { CarouselItemProps } from './CarouselItem'
+export { CarouselOverlay } from './CarouselOverlay'
+export type { CarouselOverlayProps } from './CarouselOverlay'
+export { CarouselPlayPause } from './CarouselPlayPause'
+export type { CarouselPlayPauseProps } from './CarouselPlayPause'