@nordwerk/scroll-carousel 0.1.0

package/dist/carousel.css

@@ -0,0 +1,258 @@
+/*
+ * scroll-carousel, prototype stylesheet.
+ *
+ * The layout is complete without JavaScript: the server-rendered markup is already the final
+ * layout, and the script only adds controls. Everything is configured with custom properties,
+ * which can be set anywhere above the track and changed in media or container queries. The root
+ * is the query container, so inside `@container sc (...)` set them on .sc-track.
+ *
+ *   --sc-per-view       slides per view; a fraction shows part of the next slide. Default 1.
+ *   --sc-slide-size     a fixed slide size, or auto for the content width. Wins over per-view.
+ *   --sc-gap            space between slides. Default 1rem.
+ *   --sc-offset-before  space before the first slide; snapped slides line up with it. Default 0.
+ *   --sc-offset-after   space after the last slide. Default 0.
+ *   --sc-snap           mandatory, proximity or none. Default mandatory.
+ *   --sc-align          start or center. Default start.
+ *   --sc-centered       1 pads both ends so the first and last slide can reach the centre.
+ *                       Derived from --sc-per-view, so it does not combine with --sc-slide-size.
+ *   --sc-count          the number of slides, when known; per-view never exceeds it.
+ *   --sc-group          slides per step of next and previous: a number, or page. Read by the script.
+ *   --sc-controls       none hides the arrows, dots and play button, e.g. for free mode on phones.
+ *
+ * Theme, all optional: --sc-control-bg, --sc-control-fg, --sc-control-border,
+ * --sc-control-size, --sc-control-radius, --sc-control-shadow, --sc-nav-top, --sc-nav-inset,
+ * --sc-dot, --sc-dot-size, --sc-dot-height, --sc-dot-active-size, --sc-dot-radius, --sc-dot-idle,
+ * --sc-focus.
+ */
+
+.sc {
+  container: sc / inline-size;
+  position: relative;
+}
+
+.sc-track {
+  --_n: min(var(--sc-per-view, 1), var(--sc-count, 1000));
+  --_gap: var(--sc-gap, 1rem);
+  --_size: calc(
+    (100cqi - var(--sc-offset-before, 0px) - var(--sc-offset-after, 0px) - (var(--_n) - 1) * var(--_gap)) /
+      var(--_n)
+  );
+  --_edge: calc((100cqi - var(--_size)) / 2 * var(--sc-centered, 0));
+  /* Also the containing block for anything absolutely positioned inside the slides, which the
+     scroller then clips instead of letting it widen the page. */
+  position: relative;
+  display: flex;
+  gap: var(--_gap);
+  margin: 0;
+  padding-block: 0;
+  padding-inline: calc(var(--sc-offset-before, 0px) + var(--_edge)) calc(var(--sc-offset-after, 0px) + var(--_edge));
+  list-style: none;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  /* `x none` is invalid, which makes the property fall back to its initial value, none. */
+  scroll-snap-type: x var(--sc-snap, mandatory);
+  scroll-padding-inline: var(--sc-offset-before, 0px) var(--sc-offset-after, 0px);
+  scrollbar-width: none;
+  transition: opacity 0.16s ease;
+}
+
+.sc-track::-webkit-scrollbar {
+  display: none;
+}
+
+/* Zero specificity, so a host can size its own slides without a fight. */
+:where(.sc-track > *) {
+  flex: 0 0 var(--sc-slide-size, var(--_size));
+  min-width: 0;
+  scroll-snap-align: var(--sc-align, start);
+}
+
+:where(.sc-track > [data-sc-snap-off]) {
+  scroll-snap-align: none;
+}
+
+/* A row too short to scroll sits in the middle; auto margins collapse to 0 once it overflows. */
+.sc--center-few :where(.sc-track > :first-child) {
+  margin-inline-start: auto;
+}
+
+.sc--center-few :where(.sc-track > :last-child) {
+  margin-inline-end: auto;
+}
+
+.sc-track:focus-visible {
+  outline: 2px solid var(--sc-focus, Highlight);
+  outline-offset: -2px;
+}
+
+.sc[data-sc-drag][data-sc-overflow] .sc-track {
+  cursor: grab;
+}
+
+.sc[data-sc-drag] .sc-track :is(img, a) {
+  -webkit-user-drag: none;
+}
+
+.sc-track[data-sc-dragging] {
+  cursor: grabbing;
+  scroll-snap-type: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.sc-track[data-sc-fading] {
+  opacity: 0;
+}
+
+/* Default controls. All optional: a host can bring its own and bind them to the API. */
+
+.sc-nav,
+.sc-play {
+  display: var(--sc-controls, grid);
+  place-items: center;
+  box-sizing: border-box;
+  inline-size: var(--sc-control-size, 2.75rem);
+  block-size: var(--sc-control-size, 2.75rem);
+  padding: 0;
+  border: 1px solid var(--sc-control-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--sc-control-radius, 50%);
+  background: var(--sc-control-bg, Canvas);
+  box-shadow: var(--sc-control-shadow, none);
+  color: var(--sc-control-fg, CanvasText);
+  font: inherit;
+  cursor: pointer;
+}
+
+.sc-nav {
+  position: absolute;
+  z-index: 1;
+  inset-block-start: var(--sc-nav-top, 50%);
+  translate: 0 -50%;
+}
+
+.sc-prev {
+  inset-inline-start: var(--sc-nav-inset, 0.5rem);
+}
+
+.sc-next {
+  inset-inline-end: var(--sc-nav-inset, 0.5rem);
+}
+
+.sc-nav svg,
+.sc-play svg {
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.sc-nav:dir(rtl) svg {
+  scale: -1 1;
+}
+
+.sc-nav[aria-disabled='true'] {
+  opacity: 0.35;
+  cursor: default;
+}
+
+.sc-play .sc-icon-pause,
+.sc[data-sc-playing] .sc-play .sc-icon-play {
+  display: none;
+}
+
+.sc[data-sc-playing] .sc-play .sc-icon-pause {
+  display: block;
+}
+
+.sc-dots {
+  display: var(--sc-controls, flex);
+  flex-wrap: wrap;
+  justify-content: center;
+  min-block-size: 1.5rem;
+}
+
+.sc-dot {
+  display: grid;
+  place-items: center;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--sc-dot, currentColor);
+  cursor: pointer;
+}
+
+.sc-dot::before {
+  content: '';
+  inline-size: var(--sc-dot-size, 0.5rem);
+  block-size: var(--sc-dot-height, var(--sc-dot-size, 0.5rem));
+  border-radius: var(--sc-dot-radius, 1rem);
+  background: currentColor;
+  opacity: var(--sc-dot-idle, 0.35);
+  transition: inline-size 0.2s ease, opacity 0.2s ease;
+}
+
+.sc-dot[aria-current]::before {
+  inline-size: var(--sc-dot-active-size, 1.25rem);
+  opacity: 1;
+}
+
+/* While autoplay runs, the current dot fills up until the next move. */
+.sc[data-sc-playing] .sc-dot[aria-current]::before {
+  background:
+    linear-gradient(currentColor, currentColor) 0 0 / 0 100% no-repeat,
+    color-mix(in srgb, currentColor 35%, transparent);
+  animation: sc-progress var(--sc-autoplay-delay, 5s) linear forwards;
+}
+
+.sc[data-sc-playing] .sc-dot[aria-current]:dir(rtl)::before {
+  background-position: 100% 0;
+}
+
+.sc[data-sc-paused] .sc-dot::before {
+  animation-play-state: paused;
+}
+
+@keyframes sc-progress {
+  to {
+    background-size: 100% 100%;
+  }
+}
+
+:is(.sc-nav, .sc-play, .sc-dot):focus-visible {
+  outline: 2px solid var(--sc-focus, Highlight);
+  outline-offset: 2px;
+}
+
+/* Without the script, or without overflow, controls are absent: never focusable and dead.
+   Arrows float over the track and can simply go; dots and the play button keep their space,
+   so attaching the script cannot shift the layout around them. */
+.sc:not([data-sc-ready][data-sc-overflow]) .sc-nav {
+  display: none;
+}
+
+.sc:not([data-sc-ready][data-sc-overflow]) :is(.sc-dots, .sc-play) {
+  visibility: hidden;
+}
+
+.sc-status,
+.sc-skip:not(:focus) {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sc-track,
+  .sc-dot::before {
+    transition: none;
+  }
+}

package/dist/drag.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from './index.js';
+export interface DragOptions {
+    /** Pixels the pointer must travel before a press becomes a drag. Default 6. */
+    threshold?: number;
+}
+export declare const drag: ({ threshold }?: DragOptions) => Plugin;

package/dist/drag.js

@@ -0,0 +1,79 @@
+import {
+  clamp,
+  closest
+} from "./shared/chunk-3THCBXDW.js";
+
+// src/drag.ts
+var drag = ({ threshold = 6 } = {}) => ({ root, track, listen, layout, toPage, scrollTo, grab, hold, on }) => {
+  let suppressUntil = 0;
+  let press = null;
+  const readPos = () => Math.abs(track.scrollLeft);
+  root.setAttribute("data-sc-drag", "");
+  listen(track, "dragstart", (event) => event.preventDefault());
+  listen(
+    track,
+    "click",
+    (event) => {
+      if (event.timeStamp > suppressUntil) return;
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    { capture: true }
+  );
+  on("settle", () => track.removeAttribute("data-sc-dragging"));
+  listen(track, "pointerdown", (event) => {
+    if (event.pointerType != "mouse" || event.button || !layout().state.overflow) return;
+    if (event.target.closest("input, textarea, select, label, [contenteditable], [data-sc-no-drag]")) return;
+    press = { id: event.pointerId, x: event.clientX, left: track.scrollLeft, from: readPos(), moved: false, trail: [[event.timeStamp, event.clientX]] };
+  });
+  listen(document, "pointermove", (event) => {
+    if (!press || event.pointerId != press.id) return;
+    if (!(event.buttons & 1)) return release(event);
+    const dx = event.clientX - press.x;
+    if (!press.moved) {
+      if (Math.abs(dx) < threshold) return;
+      press.moved = true;
+      grab();
+      hold(true);
+      track.setPointerCapture(press.id);
+      track.setAttribute("data-sc-dragging", "");
+      getSelection()?.removeAllRanges();
+    }
+    track.scrollLeft = press.left - dx;
+    press.trail.push([event.timeStamp, event.clientX]);
+    while (press.trail.length > 2 && event.timeStamp - press.trail[0][0] > 100) press.trail.shift();
+  });
+  const release = (event) => {
+    const done = press;
+    if (!done || event.pointerId != done.id) return;
+    press = null;
+    if (!done.moved) return;
+    hold(false);
+    suppressUntil = event.timeStamp + 100;
+    const { pages, max, rtl, snap } = layout();
+    const [t0, x0] = done.trail[0];
+    const velocity = event.timeStamp > t0 ? (event.clientX - x0) / (event.timeStamp - t0) : 0;
+    const here = readPos();
+    const forward = rtl ? velocity : -velocity;
+    if (snap == "none") return scrollTo(clamp(here + forward * 200, 0, max));
+    const positions = pages.map((page2) => page2.pos);
+    const start = closest(positions, done.from);
+    let page = closest(positions, here);
+    const moved = here - done.from;
+    if (page == start && (Math.abs(moved) > 40 || Math.abs(forward) > 0.3)) {
+      page = clamp(start + Math.sign(Math.abs(moved) > 40 ? moved : forward), 0, pages.length - 1);
+    }
+    toPage(page);
+  };
+  listen(document, "pointerup", release);
+  listen(document, "pointercancel", release);
+  return {
+    destroy() {
+      root.removeAttribute("data-sc-drag");
+      track.removeAttribute("data-sc-dragging");
+    }
+  };
+};
+export {
+  drag
+};

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { type Group, type Page } from './math.js';
+export type { Align, Geometry, Group, Page } from './math.js';
+export interface CarouselState {
+    /** The slide at the snap position, or the destination of a move in flight. */
+    index: number;
+    page: number;
+    pageCount: number;
+    isBeginning: boolean;
+    isEnd: boolean;
+    /** Whether the content overflows at all. Without overflow there are no controls. */
+    overflow: boolean;
+}
+export interface Labels {
+    /** Accessible name of a default dot. */
+    page: (n: number, count: number) => string;
+    /** Live-region text after a settled move, from the first and last visible slide (1-based). */
+    status: (first: number, last: number, count: number, slides: HTMLElement[]) => string;
+}
+export interface CarouselOptions {
+    /** Slides per step of next and previous: a number or 'page'. Default: --sc-group, then 1. */
+    group?: Group;
+    /** Initial slide. Default: the slide with [data-sc-initial], then 0. */
+    initial?: number;
+    /** Next at the end goes to the start and the reverse. true fades, 'scroll' scrolls back. */
+    rewind?: boolean | 'fade' | 'scroll';
+    labels?: Partial<Labels>;
+    /** Called after every settled move that changed the state, like the sc:change event. */
+    onChange?: (state: CarouselState) => void;
+    /** Default: [data-sc-prev], [data-sc-next], [data-sc-dots], [data-sc-status] inside the root. */
+    prev?: HTMLElement | null;
+    next?: HTMLElement | null;
+    dots?: HTMLElement | null;
+    status?: HTMLElement | null;
+    /** Opt-in behaviour, e.g. drag() and autoplay(). */
+    plugins?: Plugin[];
+}
+export interface MoveOptions {
+    /** Jump instead of scrolling smoothly. */
+    instant?: boolean;
+}
+export interface Carousel {
+    readonly root: HTMLElement;
+    readonly track: HTMLElement;
+    readonly slides: HTMLElement[];
+    readonly state: CarouselState;
+    readonly index: number;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly isBeginning: boolean;
+    readonly isEnd: boolean;
+    next(): void;
+    prev(): void;
+    slideTo(index: number, options?: MoveOptions): void;
+    goToPage(page: number, options?: MoveOptions): void;
+    /** Measure again, e.g. after changing the direction or a custom property from script. */
+    update(): void;
+    destroy(): void;
+    /** Present when the autoplay plugin is attached. */
+    play?(): void;
+    pause?(): void;
+}
+export interface Layout {
+    pages: Page[];
+    max: number;
+    rtl: boolean;
+    snap: 'mandatory' | 'proximity' | 'none';
+    state: CarouselState;
+}
+/** What a plugin gets to work with. Listeners added through `listen` end with destroy(). */
+export interface PluginContext {
+    root: HTMLElement;
+    track: HTMLElement;
+    listen(target: EventTarget | null | undefined, type: string, handler: (event: any) => void, options?: AddEventListenerOptions): void;
+    layout(): Layout;
+    toPage(page: number): void;
+    /** Scroll to a position, e.g. where a drag's momentum ends. */
+    scrollTo(pos: number): void;
+    /** Next or previous page; a quiet step is not announced in the live region. */
+    step(direction: 1 | -1, wrap: boolean, quiet?: boolean): void;
+    /** The user took hold of the track: a programmatic move in flight is abandoned. */
+    grab(): void;
+    /** While held, scrolling never counts as settled, e.g. during a drag. */
+    hold(on: boolean): void;
+    /** control: the user took over. settle: a move came to rest. measure: layout was read. */
+    on(event: 'control' | 'settle' | 'measure', handler: () => void): void;
+}
+export type Plugin = (context: PluginContext) => {
+    destroy?(): void;
+    play?(): void;
+    pause?(): void;
+} | void;
+/** The carousel attached to `root`, if any. */
+export declare const getCarousel: (root: HTMLElement) => Carousel | undefined;
+/** Attach to server-rendered markup. Attaching twice returns the same carousel. */
+export declare function attach(root: HTMLElement, options?: CarouselOptions): Carousel;

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  attach,
+  getCarousel
+} from "./shared/chunk-HPGJKTV5.js";
+import "./shared/chunk-3THCBXDW.js";
+export {
+  attach,
+  getCarousel
+};

package/dist/markup.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A value, or values by minimum container width in px, e.g. { 0: 2, 600: 3, 900: 4 }.
+ * Widths are container widths: the carousel root is the query container.
+ */
+export type Responsive<T> = T | Record<number, T>;
+export interface LayoutProps {
+    /** Slides per view; fractions show part of the next slide. */
+    perView?: Responsive<number>;
+    /** A fixed slide size such as '18rem', or 'auto' for the content width. Wins over perView. */
+    slideSize?: Responsive<string>;
+    /** Numbers are px. */
+    gap?: Responsive<number | string>;
+    offsetBefore?: Responsive<number | string>;
+    offsetAfter?: Responsive<number | string>;
+    snap?: Responsive<'mandatory' | 'proximity' | 'none'>;
+    align?: Responsive<'start' | 'center'>;
+    /** Pad both ends so the first and last slide can reach the centre. Needs perView. */
+    centered?: boolean;
+    /** Slides per step of next and previous. */
+    group?: Responsive<number | 'page'>;
+    /** false hides arrows, dots and the play button, e.g. for free mode on small containers. */
+    controls?: Responsive<boolean>;
+}
+/** Custom properties for the root's style attribute: plain values and the 0 breakpoint. */
+export declare function baseVars(props: LayoutProps): Record<string, string>;
+/** The same as a CSS declaration string, for templating languages. */
+export declare const baseStyle: (props: LayoutProps) => string;
+/**
+ * Container-query rules for responsive values, scoped to [data-sc-id="id"]. Empty when nothing
+ * is responsive. Render it in a <style> element inside the root.
+ */
+export declare function responsiveCss(id: string, props: LayoutProps): string;
+/**
+ * Inline script to render immediately after a carousel that opens on a later slide. It sets the
+ * start position before the first paint, so a deferred or module script finds it in place.
+ * Start alignment only. It expects the root as its previous sibling.
+ */
+export declare const PRE_POSITION: string;
+/** Label templates such as 'Slide {n} of {count}' turned into label functions. */
+export declare function templateLabels(templates?: {
+    page?: string;
+    status?: string;
+}): {
+    page?: ((n: number, count: number) => string) | undefined;
+    status?: ((first: number, last: number, count: number) => string) | undefined;
+};

package/dist/markup.js

@@ -0,0 +1,14 @@
+import {
+  PRE_POSITION,
+  baseStyle,
+  baseVars,
+  responsiveCss,
+  templateLabels
+} from "./shared/chunk-I4ZMRKZV.js";
+export {
+  PRE_POSITION,
+  baseStyle,
+  baseVars,
+  responsiveCss,
+  templateLabels
+};

package/dist/math.d.ts

@@ -0,0 +1,45 @@
+export type Align = 'start' | 'center' | 'end';
+export type Group = number | 'page';
+export interface Geometry {
+    /** Start of each slide in scroll-content coordinates, px. */
+    starts: number[];
+    /** Inline size of each slide, px. */
+    sizes: number[];
+    /** Width of the scrollport, px. */
+    port: number;
+    /** Scroll padding at the start and the end, px. */
+    padStart: number;
+    padEnd: number;
+    /** Largest scroll position, px. */
+    max: number;
+    align: Align;
+}
+export interface Page {
+    /** Scroll position of the page. */
+    pos: number;
+    /** Index of the first slide of the page. */
+    first: number;
+}
+/** Two positions closer than this, in px, are the same place. */
+export declare const EPS = 2;
+export declare const clamp: (value: number, min: number, max: number) => number;
+/** Index of the value closest to `target`; the earliest one wins a tie. */
+export declare const closest: (values: number[], target: number) => number;
+/** The scroll position at which each slide is aligned, clamped to the scroll range. */
+export declare const snapPositions: ({ starts, sizes, port, padStart, padEnd, max, align }: Geometry) => number[];
+/**
+ * The first slide of every page. Pages are counted outwards from `anchor` (the initial slide),
+ * so the initial slide always starts a page and the first page may be shorter than the rest.
+ * `group` is a number of slides, or 'page' for as many whole slides as fit in the view.
+ */
+export declare const pageStarts: (geo: Geometry, snaps: number[], group: Group, anchor: number) => number[];
+/**
+ * Pages at distinct positions, always ending at the end of the scroll range. A page's `first` is
+ * the earliest slide aligned at its position, which is also the index reported there: at the
+ * clamped end that is the first slide of the last full view, not the start of the last group.
+ */
+export declare const buildPages: (geo: Geometry, snaps: number[], group: Group, anchor: number) => Page[];
+/** The page that contains slide `index`. */
+export declare const pageOf: (pages: Page[], index: number) => number;
+/** First and last slide that are at least half visible at `pos`, or [-1, -1]. */
+export declare const visibleRange: (pos: number, { starts, sizes, port }: Geometry) => [number, number];

package/dist/preact.d.ts

@@ -0,0 +1,9 @@
+export type { CarouselProps } from './adapter.js';
+export type { Carousel as CarouselApi, CarouselOptions, CarouselState } from './index.js';
+export declare const Carousel: (props: import("./adapter.ts").CarouselProps) => any, useCarousel: (options?: import("./index.ts").CarouselOptions) => {
+    ref: {
+        current: HTMLElement | null;
+    };
+    carousel: import("./index.ts").Carousel | null;
+    state: import("./index.ts").CarouselState | null;
+};

package/dist/preact.js

@@ -0,0 +1,24 @@
+import {
+  createAdapter
+} from "./shared/chunk-5Q4YPVNK.js";
+import "./shared/chunk-HPGJKTV5.js";
+import "./shared/chunk-3THCBXDW.js";
+import "./shared/chunk-I4ZMRKZV.js";
+
+// src/preact.ts
+import { Fragment, createElement, toChildArray } from "preact";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "preact/hooks";
+var { Carousel, useCarousel } = createAdapter({
+  createElement,
+  Fragment,
+  useState,
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useId,
+  toChildArray
+});
+export {
+  Carousel,
+  useCarousel
+};

package/dist/react.d.ts

@@ -0,0 +1,9 @@
+export type { CarouselProps } from './adapter.js';
+export type { Carousel as CarouselApi, CarouselOptions, CarouselState } from './index.js';
+export declare const Carousel: (props: import("./adapter.ts").CarouselProps) => any, useCarousel: (options?: import("./index.ts").CarouselOptions) => {
+    ref: {
+        current: HTMLElement | null;
+    };
+    carousel: import("./index.ts").Carousel | null;
+    state: import("./index.ts").CarouselState | null;
+};

package/dist/react.js

@@ -0,0 +1,23 @@
+import {
+  createAdapter
+} from "./shared/chunk-5Q4YPVNK.js";
+import "./shared/chunk-HPGJKTV5.js";
+import "./shared/chunk-3THCBXDW.js";
+import "./shared/chunk-I4ZMRKZV.js";
+
+// src/react.ts
+import { Children, Fragment, createElement, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+var { Carousel, useCarousel } = createAdapter({
+  createElement,
+  Fragment,
+  useState,
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useId,
+  toChildArray: Children.toArray
+});
+export {
+  Carousel,
+  useCarousel
+};