@0001-labs/design-system-1 0.3.0-alpha.13 → 0.3.0-alpha.14

package/dist/0-face/carousel.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Carousels without Lit: the behaviour of `.ds-carousel` (drawn by
+ * `1-root/carousel.css`) and its dots (`.ds-progress--dots`, from
+ * `progress.css`) on a page's own markup, and the pieces `ds-carousel` and
+ * `ds-progress` share with it. No framework and no imports.
+ *
+ * ```html
+ * <section class="ds-carousel" aria-label="Colours">
+ *   <div class="ds-carousel__track">
+ *     <figure>…</figure>
+ *     <figure>…</figure>
+ *   </div>
+ *   <div class="ds-carousel__controls">
+ *     <button class="ds-button ds-button--icon ds-carousel__previous" type="button">…</button>
+ *     <div class="ds-progress ds-progress--dots"></div>
+ *     <button class="ds-button ds-button--icon ds-carousel__next" type="button">…</button>
+ *   </div>
+ * </section>
+ * <script type="module">
+ *   import { startCarousels } from "/ds1/0-face/carousel.js";
+ *   startCarousels();
+ * </script>
+ * ```
+ *
+ * `startCarousels()` starts every `.ds-carousel` on the page: it makes the
+ * block a region described as a carousel, each slide a group labelled "2 of
+ * 5" (unless the page labels it), fills `.ds-progress--dots` with a dot for each
+ * slide, keeps the dots and the buttons on the slide in view, and announces
+ * the current slide politely in a `.ds-carousel__status` it adds. Dots take
+ * the arrow keys, Home and End. Scrolling is instant when the reader asks for
+ * reduced motion. The block fires `change` (`detail: { index, previous }`)
+ * when a person moves to another slide.
+ *
+ * A strip of things of their own width (`data-slides="auto"`, several in
+ * view, each stopping at the strip's start) takes three more options, as data
+ * attributes on `.ds-carousel` (and attributes of the same names on
+ * `ds-carousel`):
+ *
+ * - `data-bleed`: `none` (the default) keeps the strip in its box; `end` runs
+ *   it on to the window's end edge, the first slide still on the box's start;
+ *   `both` runs it to both edges, slides passing out of the box at its start.
+ * - `data-loop`: the slides held three times over, the copies unseen by
+ *   assistive technology and never focused, so the strip has no end. A
+ *   looping carousel draws no dots.
+ * - `data-autoplay`: move on a slide at a time by itself every so many
+ *   milliseconds (`data-autoplay="5000"`; empty is 5000). Held while the
+ *   pointer, a finger or the keyboard is in the strip, while it is out of
+ *   view or the page hidden, and never for a reader who asks for reduced
+ *   motion. A pause button (`.ds-carousel__pause`) is always drawn with it
+ *   (WCAG 2.2.2).
+ * - `data-snap="none"`: slide freely, without stopping at slides.
+ *
+ * The words read English, or the shared words in the page's language where
+ * the page loads the language module; `setCarouselWords()` gives others.
+ */
+/** The words a carousel says, keyed by the shared words' English. */
+export type CarouselWord = "Carousel" | "Slide" | "Slides" | "Slide {index}" | "{index} of {count}" | "Previous slide" | "Next slide" | "Pause" | "Play";
+/** What a strip's drive can be told; every option is off unless given. */
+export interface CarouselDriveOptions {
+    bleed?: "none" | "end" | "both";
+    loop?: boolean;
+    /** Milliseconds between steps; `0` or absent for none. */
+    autoplay?: number;
+    /** A copy was made: mark and change it before it is placed. */
+    onCopy?: (copy: HTMLElement) => void;
+}
+/** A running drive: the bleed's measures, the loop's copies and autoplay. */
+export interface CarouselDrive {
+    /** Moves a slide on (`1`) or back (`-1`). */
+    step(direction: 1 | -1): void;
+    /** Holds or resumes autoplay, as the pause button does. */
+    pause(paused: boolean): void;
+    /** Whether autoplay is held by the pause button. */
+    readonly paused: boolean;
+    stop(): void;
+}
+/** How long an autoplaying carousel stands when no interval is given. */
+export declare const CAROUSEL_AUTOPLAY_MS = 5000;
+/** An autoplay interval from an attribute: empty or `true` is the default, a number of milliseconds otherwise, at least a second. */
+export declare function autoplayInterval(value: string | number | boolean | null | undefined): number;
+/** Marks an element as a copy made for a loop. */
+export declare const COPY = "data-ds-carousel-copy";
+/** Whether an attribute asks for a bleed. */
+export declare const bleedOf: (value: string | undefined) => CarouselDriveOptions["bleed"];
+export type CarouselWords = Partial<Record<CarouselWord, string>> | ((word: CarouselWord, params: Record<string, string | number>) => string);
+/** Give the carousel script words of the page's own, or `null` for the language module's (or English). */
+export declare function setCarouselWords(next: CarouselWords | null): void;
+/** A carousel word in the page's language, with its placeholders filled. */
+export declare function carouselWord(word: CarouselWord, params?: Record<string, string | number>): string;
+/** How a dot is drawn: before, at or after the current slide, or the end marker. */
+export type DotState = "past" | "current" | "next" | "future" | "end";
+/** The state of dot `index` of `count` when `current` is the slide in view. */
+export declare function dotState(index: number, current: number, count: number, end?: boolean): DotState;
+/**
+ * The dot a key moves to from `index`, or `undefined` for a key dots leave
+ * alone. Left and right follow the reading direction.
+ */
+export declare function dotForKey(key: string, index: number, count: number, rtl?: boolean): number | undefined;
+/** Whether the reader asks for reduced motion. */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Scrolls the track so `slide` stands at its start: smoothly, unless the
+ * reader asks for reduced motion. Says whether the track had to move.
+ */
+export declare function scrollToSlide(track: HTMLElement, slide: HTMLElement, smooth?: boolean): boolean;
+/**
+ * The slide in view: the one whose start is nearest the track's. At the far
+ * end, where the last slides cannot reach the start, the current slide stays
+ * while it is wholly in view, and the last slide is current otherwise.
+ */
+export declare function nearestSlide(track: HTMLElement, slides: readonly HTMLElement[], current?: number): number;
+/**
+ * The room between an element and the window's edges, at its start and its
+ * end, for a strip that bleeds out to them. Measured against the document's
+ * width, so a scrollbar is never covered.
+ */
+export declare function bleedRoom(element: HTMLElement): {
+    before: number;
+    after: number;
+};
+/**
+ * Drives a strip: `block` carries the bleed's measures, `track` scrolls, and
+ * the slides (the children of `holder`, the track itself on a native page)
+ * are what it holds. The bleed's room is measured as the page's width
+ * changes; a loop holds the slides three times over, opened on the middle
+ * set and kept within it; autoplay steps a slide at a time while nobody is in
+ * the strip and it can be seen.
+ */
+export declare function driveCarousel(block: HTMLElement, track: HTMLElement, holder: HTMLElement, options?: CarouselDriveOptions): CarouselDrive;
+/** What `startDots` is given: the number of dots, the current one and the end marker. */
+export interface DotsOptions {
+    count: number;
+    current?: number;
+    /** Draw the last dot as an end marker. */
+    end?: boolean;
+    /** Called when a person picks a dot, by a click or a key. */
+    onSelect?: (index: number) => void;
+}
+/** A running set of native dots. */
+export interface DotsHandle {
+    /** Draw `count` dots, `current` among them. */
+    set(count: number, current: number): void;
+    stop(): void;
+}
+/**
+ * Fills a `.ds-progress--dots` element with a button for each dot and keeps
+ * its states: a group labelled "Slides", each dot "Slide 2", the current one
+ * `aria-current` and the only one in the tab order, arrows, Home and End
+ * moving between them.
+ */
+export declare function startDots(element: HTMLElement, options: DotsOptions): DotsHandle;
+/** A running native carousel. */
+export interface CarouselHandle {
+    /** The slide in view. */
+    readonly current: number;
+    /** Go to a slide, as its dot does. */
+    goTo(index: number): void;
+    stop(): void;
+}
+/** Detail of a carousel's `change` event. */
+export interface CarouselChangeDetail {
+    index: number;
+    previous: number;
+}
+/** What `startCarousel` and `startCarousels` are told. */
+export interface StartCarouselOptions {
+    /** Where the icons are, for the pause button the script adds (`/ds1/x-icon/`). */
+    icons?: string;
+}
+/** Starts one `.ds-carousel` block; starting it again returns the running one. */
+export declare function startCarousel(element: HTMLElement, options?: StartCarouselOptions): CarouselHandle;
+/** Starts every `.ds-carousel` inside `root` (the document by default); the returned function stops them. */
+export declare function startCarousels(root?: ParentNode, options?: StartCarouselOptions): () => void;
+//# sourceMappingURL=carousel.d.ts.map

package/dist/0-face/carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../DS1/0-face/carousel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,GAAG,oBAAoB,GAAG,gBAAgB,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzJ,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CACtC;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,qIAAqI;AACrI,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAK5F;AAED,kDAAkD;AAClD,eAAO,MAAM,IAAI,0BAA0B,CAAC;AAE5C,6CAA6C;AAC7C,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,oBAAoB,CAAC,OAAO,CAA2D,CAAC;AAC5I,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC;AAM9I,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEjE;AAKD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAM,GAAG,MAAM,CAMrG;AAED,oFAAoF;AACpF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtE,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAQ,GAAG,QAAQ,CAK7F;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAQ,GAAG,MAAM,GAAG,SAAS,CAQpG;AAED,kDAAkD;AAClD,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAO,GAAG,OAAO,CAW5F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,SAAI,GAAG,MAAM,CAkBpG;AAUD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAMjF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CA4H5I;AAuBD,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AAoBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAiDhF;AAED,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAIzE,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,oBAAyB,GAAG,cAAc,CAsItG;AAED,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAG1G"}