ngwr 10.2.0 → 11.0.0

package/types/ngwr-carousel-testing.d.ts

@@ -0,0 +1,257 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-carousel>` a harness query matches. */
+interface WrCarouselHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the carousel's accessible name — a string is an exact match, a RegExp
+     * is tested.
+     *
+     * This is the RESOLVED name, so it matches whatever the page announces: an
+     * `ariaLabel` the consumer passed, the `carousel.label` entry of the active
+     * `ngwr/i18n` catalog, or the built-in `'Carousel'` when a consumer named
+     * neither. A carousel is never nameless, so this option never excludes
+     * everything.
+     */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a carousel holding exactly this many `<wr-carousel-slide>` children. */
+    readonly slideCount?: number;
+    /** Match a carousel one of whose slides carries this text — exact for a string, tested for a RegExp. */
+    readonly slideText?: string | RegExp;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-carousel>` — drive the strip the way someone on the page
+ * drives it.
+ *
+ * Everything it reads is public API: the `.wr-carousel__*` elements, the dots'
+ * `aria-current`, and the `aria-roledescription` the viewport and each slide
+ * publish. Two things are worth knowing before writing an assertion against it:
+ *
+ * - **The slides do not say which one is showing.** A `<wr-carousel-slide>` carries
+ *   `role="group"` and `aria-roledescription="slide"` and nothing else — no
+ *   `aria-current`, no `aria-hidden` on the ones off-screen. The current slide is
+ *   published in exactly two places, the dot carrying `aria-current="true"` and the
+ *   track's own offset, and {@link getActiveIndex} reads them in that order. There
+ *   is likewise no live region: the component announces a move to nobody, so a
+ *   harness cannot report one.
+ * - **It never drags.** The swipe the component supports is a touch gesture
+ *   measured against the viewport's own width, and jsdom has no layout — that width
+ *   is 0, so the "20% of the viewport" threshold is 0 too and EVERY drag clears it,
+ *   a 1px twitch included. The result says nothing about a real finger, and the spec
+ *   pins that artifact rather than pretending otherwise. Every move here goes
+ *   through the arrow buttons and the dots instead, which is the accessible path
+ *   anyway. `carousel.spec.ts` is where the gesture itself is pinned, by staging the
+ *   touch events and declaring an `offsetWidth`.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const gallery = await loader.getHarness(WrCarouselHarness.with({ ariaLabel: 'Gallery' }));
+ *
+ * expect(await gallery.getSlideCount()).toBe(3);
+ * await gallery.next();
+ * expect(await gallery.getActiveIndex()).toBe(1);
+ *
+ * await gallery.goTo(2);
+ * expect(await gallery.getActiveSlideText()).toBe('Dunes');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCarouselHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrCarouselHarnessFilters): HarnessPredicate<WrCarouselHarness>;
+    /**
+     * The role the strip announces — `group`, which is what lets
+     * `aria-roledescription` mean anything.
+     *
+     * Read off the VIEWPORT rather than the host, and that is the whole point of the
+     * pairing: `aria-roledescription` is dropped on an element with no semantic role,
+     * and the host element (`<wr-carousel>`) has none.
+     */
+    getRole(): Promise<string | null>;
+    /** How the strip describes itself to a screen reader — `carousel`. */
+    getRoleDescription(): Promise<string | null>;
+    /**
+     * The carousel's accessible name.
+     *
+     * The RESOLVED one, which is the only one the page has: the `ariaLabel` input
+     * defaults to `null` and the component runs it through the `ngwr/i18n` catalog
+     * (`carousel.label`, falling back to `'Carousel'`), so a consumer who passed
+     * nothing still gets a named group and this still answers. Reporting the raw
+     * input would say `null` about a carousel that announces itself perfectly well.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** The accessible name of the previous-slide button. Throws when the arrows are not rendered. */
+    getPreviousLabel(): Promise<string | null>;
+    /** The accessible name of the next-slide button. Throws when the arrows are not rendered. */
+    getNextLabel(): Promise<string | null>;
+    /**
+     * The accessible name of the dot group — what names the row of dots as a set
+     * rather than leaving a screen reader with N unexplained buttons.
+     *
+     * Throws when the dots are not rendered: there is no group to name then, and a
+     * `null` would read like a group that lost its label.
+     */
+    getPaginationLabel(): Promise<string | null>;
+    /**
+     * What each slide announces itself as — `slide`, on every one of them, in DOM
+     * order.
+     *
+     * The one piece of ARIA the slides carry, and the reason it is worth asking: it
+     * is set on the slide component's own host, so a slide reaching the page through
+     * some other element would come back `null` here while the carousel kept working.
+     */
+    getSlideRoleDescriptions(): Promise<(string | null)[]>;
+    /** How many slides the carousel holds. */
+    getSlideCount(): Promise<number>;
+    /** The text of every slide, in DOM order. */
+    getSlideTexts(): Promise<string[]>;
+    /**
+     * Which slide is showing, as a zero-based index.
+     *
+     * Taken from the dot carrying `aria-current="true"` whenever the dots are
+     * rendered — that attribute is the only thing on the page that tells a screen
+     * reader where in the strip it has got to, so it is the answer that matters —
+     * and derived from the track's rendered offset when they are not, `[showDots]`
+     * being off and a single-slide carousel both dropping the strip entirely.
+     *
+     * That fallback takes the MAGNITUDE of the offset on purpose. The transform is
+     * physical while the slides sit on the inline axis, so a mirrored carousel paints
+     * `translateX(100%)` for the very slide an LTR one paints `translateX(-100%)`
+     * for; signed, this reported slide -1 for a perfectly healthy RTL carousel.
+     *
+     * Throws on a carousel with no slides at all — nothing is showing there, and `0`
+     * would read like the first slide.
+     */
+    getActiveIndex(): Promise<number>;
+    /** The text of the slide that is showing. Throws on a carousel with no slides. */
+    getActiveSlideText(): Promise<string>;
+    /**
+     * The track's rendered offset, as a percentage of one viewport: `-100` for the
+     * second slide of an LTR carousel, `+100` for the second slide of a mirrored one.
+     *
+     * Read off the inline `style` attribute rather than through `getCssValue()`,
+     * because the percentage only survives where the component wrote it. jsdom hands
+     * a declared `transform` straight back through `getComputedStyle`, so
+     * `getCssValue()` answers correctly HERE and would stop the moment the same
+     * harness ran against a real browser, which resolves the property to a pixel
+     * matrix — a green unit test would be hiding it. Mid-drag the component writes
+     * `translateX(calc(-100% + 12px))` and this reports the settled `-100`: the pixel
+     * half is the finger's own displacement, which is physical in both directions and
+     * belongs to no slide.
+     *
+     * Worth asserting next to {@link getActiveIndex}: it is the same fact painted
+     * instead of announced, and a carousel that lights the right dot while parking
+     * the track in blank space is exactly the failure nobody sees in a spec.
+     */
+    getTrackOffsetPercent(): Promise<number>;
+    /** Whether the prev / next arrows are on the page. Both are dropped together. */
+    hasArrows(): Promise<boolean>;
+    /** Whether the dot strip is on the page. */
+    hasDots(): Promise<boolean>;
+    /** How many dots are rendered — one per slide, or `0` while the strip is hidden. */
+    getDotCount(): Promise<number>;
+    /**
+     * The accessible name of every dot, in order — `'Go to slide 1'`, … resolved
+     * through the `ngwr/i18n` catalog.
+     *
+     * A dot is a bare button with no text of its own, so this label is all a screen
+     * reader has to tell one from another. `[]` when the strip is hidden, matching
+     * {@link getDotCount}.
+     */
+    getDotLabels(): Promise<(string | null)[]>;
+    /**
+     * Click the next-slide arrow.
+     *
+     * "Next" is the next SLIDE, not the next thing on the right: the buttons keep
+     * their semantics under `dir="rtl"` and only the travel under them turns around.
+     * At the last slide this wraps to the first one, unless `[loop]` is off — in
+     * which case it legitimately does nothing, so nothing is asserted about the move.
+     */
+    next(): Promise<void>;
+    /** Click the previous-slide arrow. Wraps to the last slide unless `[loop]` is off. */
+    previous(): Promise<void>;
+    /**
+     * Jump to a slide by clicking its dot — the only way the page offers to reach a
+     * slide directly.
+     *
+     * Throws when the dots are hidden (the component's own `goTo()` is still there
+     * for a spec holding the instance, but nothing on the page can be clicked) and
+     * throws on an index no slide has, rather than clicking nothing and leaving the
+     * carousel where it was.
+     */
+    goTo(index: number): Promise<void>;
+    /**
+     * Move the pointer onto the carousel, which is what HOLDS autoplay.
+     *
+     * Aimed at the host and not the viewport, deliberately: the arrows and the dots
+     * are the viewport's SIBLINGS, so a viewport-scoped hover would let a slide
+     * change under a cursor that is aiming at an arrow.
+     */
+    hover(): Promise<void>;
+    /** Move the pointer away again, releasing the hold. */
+    mouseAway(): Promise<void>;
+    /**
+     * Put keyboard focus on the first control the carousel renders — the previous
+     * arrow, or the first dot when the arrows are hidden.
+     *
+     * This is the keyboard half of the autoplay hold: WCAG 2.2.2 wants a way to stop
+     * moving content, and hovering is not one for someone who never touches a mouse,
+     * so the component listens for `focusin` on its host as well. Focus lands on the
+     * carousel's OWN controls; anything focusable a slide happens to project is not
+     * this harness's business, though in a browser it would hold autoplay just the
+     * same.
+     *
+     * Note what this is NOT: the dot of the slide showing. The dots are ordinary
+     * buttons with no roving `tabindex`, so each of them is a tab stop of its own and
+     * the first one a Tab press meets is the prev arrow whatever slide is current —
+     * two different questions, answered here and by {@link getActiveIndex}.
+     *
+     * Throws when the carousel renders no controls at all, because then there is
+     * nothing for a Tab press to land on and no keyboard mechanism to assert.
+     */
+    focus(): Promise<void>;
+    /**
+     * Take focus off whichever of the carousel's controls holds it, releasing the
+     * hold {@link focus} started.
+     *
+     * Throws when none of them is focused: `focusout` is what the component listens
+     * for, and blurring an element that never had focus fires nothing — a quiet
+     * no-op here surfaces as an autoplay assertion failing three lines later.
+     */
+    blur(): Promise<void>;
+    /** Whether one of the carousel's own controls holds focus — which is what holds autoplay. */
+    isFocused(): Promise<boolean>;
+    /** The element that carries the carousel's role and name. */
+    private viewport;
+    /** The moving strip, whose inline transform is where the carousel IS. */
+    private track;
+    private slides;
+    private dots;
+    /**
+     * Every control the carousel renders itself, in the order a Tab press meets
+     * them: the two arrows, then the dots.
+     */
+    private controls;
+    /** One arrow, or a failure naming both reasons it might not be there. */
+    private nav;
+}
+
+export { WrCarouselHarness };
+export type { WrCarouselHarnessFilters };

package/types/ngwr-carousel.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_i18n from 'ngwr/i18n';
 import * as _angular_core from '@angular/core';
 
 /**
@@ -25,7 +26,6 @@ declare class WrCarouselSlide {
  * @see https://ngwr.dev/reference/components/carousel
  */
 declare class WrCarousel {
-    /** Active slide index. Two-way bindable. @default 0 */
     /** Accessible name of the previous-slide button. Falls back to `carousel.prev`. */
     readonly prevLabel: _angular_core.InputSignal<string | null>;
     /** Accessible name of the next-slide button. Falls back to `carousel.next`. */
@@ -35,6 +35,11 @@ declare class WrCarousel {
     protected readonly resolvedPrevLabel: _angular_core.Signal<string>;
     protected readonly resolvedNextLabel: _angular_core.Signal<string>;
     protected readonly resolvedPaginationLabel: _angular_core.Signal<string>;
+    /** Accessible name of the carousel itself. Falls back to `carousel.label`. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
+    protected readonly slideLabel: (params?: ngwr_i18n.WrI18nParams) => string;
+    /** Active slide index. Two-way bindable. @default 0 */
     readonly active: _angular_core.ModelSignal<number>;
     /** Show prev / next arrow buttons. @default true */
     readonly showArrows: _angular_core.InputSignalWithTransform<boolean, any>;
@@ -51,14 +56,25 @@ declare class WrCarousel {
     /** Live horizontal drag offset (px) during a touch swipe. */
     protected readonly dragX: _angular_core.WritableSignal<number>;
     protected readonly dragging: _angular_core.WritableSignal<boolean>;
+    private readonly dir;
+    /**
+     * Reading direction of the track. `Directionality` is root-provided, so this
+     * always resolves — `optional` only guards a consumer who has deliberately
+     * torn the provider out. It reads the document once at construction; a
+     * subtree that overrides the direction does it with the CDK's `Dir`
+     * directive, which writes `valueSignal`, so `trackStyle` re-renders instead
+     * of leaving the track parked on the old side.
+     */
+    private readonly isRtl;
     /** CSS transform for the track — the per-slide offset plus any live drag. */
     protected readonly trackStyle: _angular_core.Signal<string>;
     private timer;
     private readonly paused;
     private readonly destroyRef;
+    private readonly isBrowser;
     constructor();
-    protected onMouseEnter(): void;
-    protected onMouseLeave(): void;
+    protected onPauseIn(): void;
+    protected onPauseOut(): void;
     goTo(index: number): void;
     next(): void;
     prev(): void;
@@ -67,7 +83,7 @@ declare class WrCarousel {
     protected onSwipeMove(event: TouchEvent): void;
     protected onSwipeEnd(event: TouchEvent, viewport: HTMLElement): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCarousel, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCarousel, "wr-carousel", never, { "prevLabel": { "alias": "prevLabel"; "required": false; "isSignal": true; }; "nextLabel": { "alias": "nextLabel"; "required": false; "isSignal": true; }; "paginationLabel": { "alias": "paginationLabel"; "required": false; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; "showArrows": { "alias": "showArrows"; "required": false; "isSignal": true; }; "showDots": { "alias": "showDots"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "intervalMs": { "alias": "intervalMs"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; }, { "active": "activeChange"; }, ["slides"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCarousel, "wr-carousel", never, { "prevLabel": { "alias": "prevLabel"; "required": false; "isSignal": true; }; "nextLabel": { "alias": "nextLabel"; "required": false; "isSignal": true; }; "paginationLabel": { "alias": "paginationLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; "showArrows": { "alias": "showArrows"; "required": false; "isSignal": true; }; "showDots": { "alias": "showDots"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "intervalMs": { "alias": "intervalMs"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; }, { "active": "activeChange"; }, ["slides"], ["*"], true, never>;
 }
 
 export { WrCarousel, WrCarouselSlide };