forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-carousel.d.ts

@@ -0,0 +1,530 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import { WritingDirection, RovingTabindex, ListNavigationAction } from 'forty-cdk/core';
+import * as forty_cdk_carousel from 'forty-cdk/carousel';
+
+/** Alignment of the active slide within the viewport. */
+type CarouselAlign = 'start' | 'center' | 'end';
+/** Internal handle for a registered slide. */
+interface ForCarouselSlideHandle {
+    readonly host: HTMLElement;
+}
+/** Internal handle for a registered indicator (dot). */
+interface ForCarouselIndicatorHandle {
+    readonly host: HTMLElement;
+    readonly disabled: Signal<boolean>;
+}
+/**
+ * Coordination contract owned by `ForCarousel`. Slides and indicators
+ * register with the root so index lookups, geometry computations, and
+ * keyboard navigation are all driven from a single source of truth.
+ */
+interface ForCarouselContext {
+    readonly activeIndex: Signal<number>;
+    readonly orientation: Signal<'horizontal' | 'vertical'>;
+    readonly dir: Signal<WritingDirection>;
+    readonly loop: Signal<boolean>;
+    readonly align: Signal<CarouselAlign>;
+    readonly slidesPerView: Signal<number>;
+    readonly slideCount: Signal<number>;
+    readonly roving: RovingTabindex;
+    /** Whether auto-rotation is currently "on" (user intent). Drives the rotation control's label. */
+    readonly playing: Signal<boolean>;
+    /** Whether the carousel is actively auto-rotating right now (`playing && !paused`). Drives the viewport's `aria-live`. */
+    readonly rotating: Signal<boolean>;
+    canScrollPrev(): boolean;
+    canScrollNext(): boolean;
+    scrollPrev(): void;
+    scrollNext(): void;
+    scrollTo(index: number): void;
+    navigate(currentIndicator: HTMLElement, action: ListNavigationAction): void;
+    /** Toggle auto-rotation on/off (the explicit, sticky user choice). Called by the rotation control. */
+    toggleAutoplay(): void;
+    registerSlide(handle: ForCarouselSlideHandle): void;
+    unregisterSlide(handle: ForCarouselSlideHandle): void;
+    registerIndicator(handle: ForCarouselIndicatorHandle): void;
+    unregisterIndicator(handle: ForCarouselIndicatorHandle): void;
+    setViewport(el: HTMLElement, id: string): void;
+    viewportId(): string | null;
+    indexOfSlide(host: HTMLElement): number;
+    indexOfIndicator(host: HTMLElement): number;
+    /** Resolve the positional slide `aria-label` (`"N of M"` by default). `position` is 1-based. */
+    slideLabel(position: number): string;
+    /** Resolve the indicator `aria-label` (`"Go to slide N"` by default). `position` is 1-based. */
+    indicatorLabel(position: number): string;
+    isCurrent(index: number): boolean;
+    isInView(index: number): boolean;
+    isFirstEnabledIndicator(el: HTMLElement): boolean;
+    hasCurrentIndicator(): boolean;
+}
+/** DI token providing the carousel context to descendant pieces. */
+declare const FOR_CAROUSEL_CONTEXT: InjectionToken<ForCarouselContext>;
+
+/**
+ * Root of the Carousel primitive. Owns the active index, slide collection,
+ * indicator collection, roving tabindex tracker, and computed geometry CSS
+ * variables. Provides the shared context to descendant pieces.
+ *
+ * Implements the [WAI-ARIA APG Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
+ *
+ * With no `[forCarouselIndicators]` rendered this is a basic carousel driven
+ * by prev/next buttons only. Adding an indicator group enables APG picker
+ * semantics: roving tabindex, arrow/Home/End navigation with automatic
+ * activation.
+ */
+declare class ForCarousel implements ForCarouselContext {
+    #private;
+    /**
+     * Two-way bindable. The zero-based index of the current (leading) slide.
+     * The `model()` change emitter (`(activeIndexChange)`) fires only on internal
+     * navigation (prev/next button clicks, indicator arrow-key or click), never
+     * on consumer writes via `[(activeIndex)]`.
+     */
+    readonly activeIndex: _angular_core.ModelSignal<number>;
+    /** Scroll axis. `'horizontal'` (default) or `'vertical'`. */
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    /**
+     * Whether index wrap-around is enabled. When `true`, `next` past the last
+     * slide wraps to index 0; `prev` before index 0 wraps to the last. Default
+     * comes from `provideForCarouselDefaults` or the library fallback (`false`).
+     */
+    readonly loop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Alignment of the active slide within the viewport. Affects the
+     * `--for-carousel-offset` computation. Default from `provideForCarouselDefaults`
+     * or `'start'`.
+     */
+    readonly align: _angular_core.InputSignal<CarouselAlign>;
+    /**
+     * Number of slides simultaneously visible in the viewport. Slide width
+     * should be set to `calc(100% / var(--for-carousel-slides-per-view))` in
+     * the consumer's CSS. Default from `provideForCarouselDefaults` or `1`.
+     */
+    readonly slidesPerView: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * When `true` and the carousel is not looping, clamps `--for-carousel-offset` so the
+     * trailing slides align flush to the viewport's trailing edge instead of overscrolling
+     * into empty space (relevant when `slidesPerView > 1`). The one-indicator-per-slide
+     * mapping is preserved — `activeIndex` still reaches the last slide; only the visual
+     * offset is contained. No effect when `loop` is enabled or `slidesPerView` is 1.
+     * Default from `provideForCarouselDefaults` or `false`.
+     */
+    readonly containScroll: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Accessible label for the carousel root (`role="group"`). Should describe
+     * the carousel's purpose without using the word "carousel" (APG guidance).
+     * When null (default), no `aria-label` is emitted; use `aria-labelledby`
+     * instead when a visible heading labels the carousel.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Whether the carousel auto-rotates. When `true` and the user has not
+     * explicitly stopped it, rotation starts on mount — *unless*
+     * `prefers-reduced-motion: reduce` is set, which suppresses auto-start
+     * (the user can still start it via the rotation control). Default from
+     * `provideForCarouselDefaults` or `false`.
+     *
+     * APG requires a `[forCarouselRotationControl]` to be present whenever
+     * autoplay is enabled. The directive does not enforce this — see the README.
+     */
+    readonly autoplay: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Milliseconds between automatic slide advances while rotating. Values
+     * `<= 0` disable the timer. Default from `provideForCarouselDefaults` or `5000`.
+     */
+    readonly autoplayInterval: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Writing direction. When unset (default `null`), the inherited ambient
+     * direction is resolved from the nearest ancestor carrying a `dir` attribute
+     * (or `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]` always wins.
+     * The resolved value is reflected to the host `dir` attribute and swaps
+     * ArrowLeft / ArrowRight semantics on the indicator group in RTL.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /** Roving tabindex tracker for the indicator group. */
+    readonly roving: RovingTabindex;
+    /** Whether auto-rotation is "on" (user intent). Sticky once the user decides. */
+    readonly playing: _angular_core.Signal<boolean>;
+    /** Whether the carousel is actively auto-rotating right now. */
+    readonly rotating: _angular_core.Signal<boolean>;
+    /** Total number of registered slides. Reactive. */
+    readonly slideCount: _angular_core.Signal<number>;
+    /**
+     * The `--for-carousel-offset` value to apply via `transform` on the track.
+     * Pure arithmetic — no layout measurement — so it is safe in Vitest.
+     */
+    readonly offset: _angular_core.Signal<string>;
+    /** The measured viewport width, or `null` before first measurement / on the server. */
+    readonly viewportWidth: _angular_core.Signal<string | null>;
+    /** The measured viewport height, or `null` before first measurement / on the server. */
+    readonly viewportHeight: _angular_core.Signal<string | null>;
+    constructor();
+    /** Returns `true` when scrolling backward is possible given the current loop/index state. */
+    canScrollPrev(): boolean;
+    /** Returns `true` when scrolling forward is possible given the current loop/index state. */
+    canScrollNext(): boolean;
+    /** Navigate to the previous slide. No-op at index 0 when not looping. */
+    scrollPrev(): void;
+    /** Navigate to the next slide. No-op at the last index when not looping. */
+    scrollNext(): void;
+    /**
+     * Navigate to the slide at `index`. Clamps to `[0, slideCount-1]` when not
+     * looping; wraps modulo `slideCount` when looping.
+     */
+    scrollTo(index: number): void;
+    /**
+     * Move focus from `currentIndicator` according to `action` and activate the
+     * target slide (automatic activation). Used by `ForCarouselIndicator`'s
+     * keydown handler.
+     */
+    navigate(currentIndicator: HTMLElement, action: ListNavigationAction): void;
+    registerSlide(handle: ForCarouselSlideHandle): void;
+    unregisterSlide(handle: ForCarouselSlideHandle): void;
+    registerIndicator(handle: ForCarouselIndicatorHandle): void;
+    unregisterIndicator(handle: ForCarouselIndicatorHandle): void;
+    /** Called by `ForCarouselViewport` at construction to wire the geometry observer. */
+    setViewport(el: HTMLElement, id: string): void;
+    /** The id of the registered viewport element, or `null` if none is mounted. */
+    viewportId(): string | null;
+    /** DOM-order index of the registered slide whose host equals `host`, or -1. */
+    indexOfSlide(host: HTMLElement): number;
+    /** DOM-order index of the registered indicator whose host equals `host`, or -1. */
+    indexOfIndicator(host: HTMLElement): number;
+    /**
+     * Resolve the positional slide `aria-label` from the scope's defaults
+     * (`"N of M"` unless localized via `provideForCarouselDefaults`).
+     * `position` is the 1-based slide index.
+     */
+    slideLabel(position: number): string;
+    /**
+     * Resolve the indicator `aria-label` from the scope's defaults
+     * (`"Go to slide N"` unless localized via `provideForCarouselDefaults`).
+     * `position` is the 1-based slide index.
+     */
+    indicatorLabel(position: number): string;
+    /** Returns `true` when `index` is the current active slide index. */
+    isCurrent(index: number): boolean;
+    /**
+     * Returns `true` when `index` falls within the visible window
+     * `[activeIndex, activeIndex + slidesPerView - 1]`.
+     */
+    isInView(index: number): boolean;
+    /**
+     * Returns `true` when `el` is the host of the first non-disabled indicator
+     * in DOM order. Used by the tabindex fallback when no indicator is current.
+     */
+    isFirstEnabledIndicator(el: HTMLElement): boolean;
+    /**
+     * Returns `true` when at least one registered, non-disabled indicator
+     * matches the current `activeIndex`. Used by the tabindex ladder to decide
+     * whether the first-enabled fallback must reclaim the tab stop.
+     *
+     * Assumes the one-indicator-per-slide mapping the rest of the picker is built
+     * on: the indicator at DOM index `i` targets slide `i`. A mismatched indicator
+     * count is dev-guarded by a `console.warn` at construction.
+     */
+    hasCurrentIndicator(): boolean;
+    /** Start auto-rotation (explicit, sticky). Overrides the reduced-motion auto-start gate. */
+    play(): void;
+    /** Stop auto-rotation (explicit, sticky). Hover/focus/visibility changes will not restart it. */
+    pause(): void;
+    /** Toggle auto-rotation. Called by `[forCarouselRotationControl]`. */
+    toggleAutoplay(): void;
+    protected onAutoplayPause(reason: 'hover' | 'focus'): void;
+    protected onAutoplayResume(reason: 'hover' | 'focus'): void;
+    protected onAutoplayFocusOut(event: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarousel, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarousel, "[forCarousel]", ["forCarousel"], { "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "slidesPerView": { "alias": "slidesPerView"; "required": false; "isSignal": true; }; "containScroll": { "alias": "containScroll"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "autoplayInterval": { "alias": "autoplayInterval"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; }, { "activeIndex": "activeIndexChange"; }, never, never, true, never>;
+}
+
+/**
+ * Clips the visible window of the carousel track. Acts as the APG-mandated
+ * live region for screen-reader announcements. `aria-live` flips between
+ * `"off"` while the carousel is actively auto-rotating (so advancing slides
+ * do not bombard the screen reader) and `"polite"` at all other times so
+ * manual navigation is announced. Also serves as the `aria-controls` target
+ * for the prev/next buttons.
+ *
+ * Registers itself with the carousel root on construction so the root's
+ * `injectElementSize` observer starts and prev/next's `aria-controls` resolves.
+ * There must be exactly one viewport per carousel.
+ */
+declare class ForCarouselViewport {
+    #private;
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /** The resolved id of this element — generated or adopted from a consumer-set static `id`. */
+    readonly id: _angular_core.Signal<string>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselViewport, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselViewport, "[forCarouselViewport]", ["forCarouselViewport"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * The flex container of slides. The consumer's CSS reads
+ * `--for-carousel-offset` (inherited from the root) and applies it as a
+ * `transform: translateX(...)` / `translateY(...)` on this element.
+ * The directive adds no animation or transform itself.
+ *
+ * Reflects `data-orientation` so the consumer can select the correct CSS
+ * axis via `[data-orientation="vertical"] [forCarouselTrack] { ... }`.
+ */
+declare class ForCarouselTrack {
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselTrack, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselTrack, "[forCarouselTrack]", ["forCarouselTrack"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * One slide in the carousel track. Carries `role="group"` and
+ * `aria-roledescription="slide"` per the WAI-ARIA APG Carousel pattern.
+ *
+ * The default `aria-label` is the positional `"N of M"` string (APG mandates
+ * a positional label on each slide). Set `ariaLabel` to override with a
+ * semantically richer label for the specific slide content.
+ *
+ * Off-view slides (outside `[activeIndex, activeIndex + slidesPerView - 1]`)
+ * are hidden from the accessibility tree and focus order via
+ * `aria-hidden="true"` + `inert`.
+ */
+declare class ForCarouselSlide {
+    #private;
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /**
+     * Override the default positional `aria-label` (`"N of M"`). Use this to
+     * provide a semantically richer label when the slide's content has a
+     * meaningful title (e.g. the product name). When `null` (default), the
+     * positional label is used automatically. Localize that default format
+     * app-wide via `provideForCarouselDefaults`'s `slideLabel`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /** Whether this is the current (active) slide. */
+    protected readonly current: _angular_core.Signal<boolean>;
+    /** Whether this slide is within the visible window. */
+    protected readonly inView: _angular_core.Signal<boolean>;
+    /** The positional `"N of M"` label used when no explicit `ariaLabel` is set. */
+    protected readonly positionLabel: _angular_core.Signal<string | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselSlide, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselSlide, "[forCarouselSlide]", ["forCarouselSlide"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Previous-slide button. Apply on a `<button>` so Enter/Space activation is
+ * native. Disabled (via the native `disabled` attribute) at index 0 when the
+ * carousel is not looping. When `loop` is `true` it is never disabled.
+ *
+ * Points `aria-controls` at the viewport's id so screen readers announce the
+ * relationship. Clicking does not move focus (APG).
+ */
+declare class ForCarouselPrevious {
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /**
+     * Accessible label for this button (e.g. "Previous slide"). When `null`
+     * (default), no `aria-label` is emitted — the consumer should supply a
+     * visible label or set this input.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselPrevious, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselPrevious, "[forCarouselPrevious]", ["forCarouselPrevious"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Next-slide button. Apply on a `<button>` so Enter/Space activation is
+ * native. Disabled (via the native `disabled` attribute) at the last index
+ * when the carousel is not looping. When `loop` is `true` it is never disabled.
+ *
+ * Points `aria-controls` at the viewport's id so screen readers announce the
+ * relationship. Clicking does not move focus (APG).
+ */
+declare class ForCarouselNext {
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /**
+     * Accessible label for this button (e.g. "Next slide"). When `null`
+     * (default), no `aria-label` is emitted — the consumer should supply a
+     * visible label or set this input.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselNext, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselNext, "[forCarouselNext]", ["forCarouselNext"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * The slide-picker group (dot navigation). Renders as `role="group"` and
+ * should receive an `ariaLabel` describing its purpose (e.g. "Choose slide
+ * to display") per the WAI-ARIA APG Carousel pattern.
+ *
+ * Keyboard navigation (ArrowLeft/Right, Home/End) and automatic activation
+ * live on each `[forCarouselIndicator]` child, not on this container.
+ */
+declare class ForCarouselIndicators {
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /**
+     * Accessible label for the picker group (e.g. "Choose slide to display").
+     * APG recommends labelling the group so screen readers can distinguish it
+     * from other landmarks.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselIndicators, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselIndicators, "[forCarouselIndicators]", ["forCarouselIndicators"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * One indicator (dot) in the slide picker. Apply on a `<button>` so
+ * Enter/Space activation is native. Uses roving tabindex — only the current
+ * dot owns `tabindex=0`; all others have `tabindex=-1`. Arrow/Home/End
+ * navigation activates the target slide automatically (APG "grouped/tabbed
+ * picker" variant).
+ *
+ * The current indicator is marked with `aria-current="true"` (truthy-only).
+ * Disabled indicators receive `aria-disabled="true"` and `data-disabled` but
+ * stay focusable (custom-role rule) so assistive tech can announce them.
+ */
+declare class ForCarouselIndicator {
+    #private;
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /**
+     * Override the default positional `aria-label` (e.g. `"Go to slide 1"`).
+     * Use this to provide a more descriptive label when the slide has a title.
+     * Localize that default format app-wide via `provideForCarouselDefaults`'s
+     * `indicatorLabel`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Disables this indicator. Disabled indicators remain focusable (for
+     * assistive tech) but ignore click and keyboard activation.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether this indicator corresponds to the current active slide. */
+    protected readonly current: _angular_core.Signal<boolean>;
+    /** Default positional label used when no explicit `ariaLabel` is set. */
+    protected readonly positionLabel: _angular_core.Signal<string | null>;
+    /**
+     * APG roving tabindex: user-driven roving owns it once any indicator has
+     * been focused. Before that, fall back to "current slide's indicator, else
+     * first enabled".
+     */
+    protected readonly tabindex: _angular_core.Signal<0 | -1>;
+    constructor();
+    protected onClick(): void;
+    protected onFocus(): void;
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselIndicator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselIndicator, "[forCarouselIndicator]", ["forCarouselIndicator"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Play/pause control for carousel auto-rotation. Apply on a `<button>` so
+ * Enter/Space activation is native. Its accessible name swaps with the
+ * rotation state — `stopLabel` while rotating, `startLabel` while stopped —
+ * per the WAI-ARIA APG Carousel pattern, which forbids `aria-pressed` here.
+ *
+ * Place this control **first** in the carousel's DOM/tab order so assistive
+ * technology users meet it before the rotating content (APG requirement).
+ *
+ * Reflects a boolean `data-playing` attribute (present while rotation is on)
+ * as the styling hook for swapping a play/pause icon.
+ */
+declare class ForCarouselRotationControl {
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /** Accessible name shown while rotation is **stopped** (the button will start it). */
+    readonly startLabel: _angular_core.InputSignal<string>;
+    /** Accessible name shown while rotation is **playing** (the button will stop it). */
+    readonly stopLabel: _angular_core.InputSignal<string>;
+    /** The current accessible name — `stopLabel` while playing, else `startLabel`. */
+    protected readonly label: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselRotationControl, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselRotationControl, "[forCarouselRotationControl]", ["forCarouselRotationControl"], { "startLabel": { "alias": "startLabel"; "required": false; "isSignal": true; }; "stopLabel": { "alias": "stopLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Opt-in pointer drag / swipe directive for the Carousel viewport. Apply on the
+ * `[forCarouselViewport]` element to enable horizontal or vertical drag-to-navigate.
+ *
+ * Publishes `--for-carousel-drag` (px) during the gesture so the consumer can
+ * compose it with `--for-carousel-offset` for live track motion. Reflects
+ * `data-dragging` while the gesture is armed. Sets `touch-action` automatically
+ * to free the cross axis for page scrolling.
+ *
+ * Under `prefers-reduced-motion: reduce` the live offset is suppressed, but the
+ * gesture still snaps `activeIndex` on release (D3).
+ */
+declare class ForCarouselDrag {
+    #private;
+    protected readonly ctx: forty_cdk_carousel.ForCarouselContext;
+    /** Disable pointer drag without removing the directive. Default `false`. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether a drag gesture is currently armed (reflected as `data-dragging`). */
+    readonly dragging: _angular_core.Signal<boolean>;
+    /** `touch-action` for the viewport: capture the primary axis, free the cross axis. */
+    readonly touchAction: _angular_core.Signal<string | null>;
+    /** Live offset CSS var; suppressed at rest and under reduced motion (D3). */
+    readonly dragVar: _angular_core.Signal<string | null>;
+    constructor();
+    protected onDragStart(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCarouselDrag, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCarouselDrag, "[forCarouselDrag]", ["forCarouselDrag"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant carousels in the surrounding injector scope.
+ * Configure with `provideForCarouselDefaults` either at the application root
+ * or in any component's `providers` array; partial overrides merge with
+ * the parent scope.
+ */
+interface ForCarouselDefaults {
+    /**
+     * Whether index wrap-around is enabled. When `true`, `next` past the last
+     * slide wraps to index 0 and `prev` before index 0 wraps to the last slide.
+     */
+    loop: boolean;
+    /**
+     * Alignment of the active slide within the viewport. `'start'` (default):
+     * the active slide's leading edge aligns with the viewport's leading edge.
+     * `'center'` / `'end'` offset accordingly.
+     */
+    align: CarouselAlign;
+    /**
+     * Number of slides visible simultaneously in the viewport. Slide width is
+     * set to `100% / slidesPerView` by the consumer's CSS.
+     */
+    slidesPerView: number;
+    /**
+     * When `true` (and the carousel is not looping), clamps the track offset so the
+     * trailing slides align flush to the viewport's trailing edge instead of
+     * overscrolling into empty space when `slidesPerView > 1`. The indicator/slide
+     * mapping is unchanged — only the visual offset is contained. Default `false`.
+     */
+    containScroll: boolean;
+    /** Whether the carousel auto-rotates on mount (when not under reduced-motion). Default `false`. */
+    autoplay: boolean;
+    /** Milliseconds between automatic slide advances. Default `5000`. */
+    autoplayInterval: number;
+    /**
+     * Builds the default positional `aria-label` for each slide (`"N of M"`).
+     * Override to localize centrally. `position` is the 1-based slide index and
+     * `total` is the slide count. A per-slide `ariaLabel` still takes precedence.
+     */
+    slideLabel: (position: number, total: number) => string;
+    /**
+     * Builds the default `aria-label` for each indicator dot (`"Go to slide N"`).
+     * Override to localize centrally. `position` is the 1-based slide index. A
+     * per-indicator `ariaLabel` still takes precedence.
+     */
+    indicatorLabel: (position: number) => string;
+}
+/** Token holding the resolved carousel defaults for the current scope. */
+declare const FOR_CAROUSEL_DEFAULTS: _angular_core.InjectionToken<ForCarouselDefaults>;
+/**
+ * Configures forty-cdk carousel defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForCarouselDefaults(defaults?: Partial<ForCarouselDefaults>): Provider[];
+
+export { FOR_CAROUSEL_CONTEXT, FOR_CAROUSEL_DEFAULTS, ForCarousel, ForCarouselDrag, ForCarouselIndicator, ForCarouselIndicators, ForCarouselNext, ForCarouselPrevious, ForCarouselRotationControl, ForCarouselSlide, ForCarouselTrack, ForCarouselViewport, provideForCarouselDefaults };
+export type { CarouselAlign, ForCarouselContext, ForCarouselDefaults };

package/types/forty-cdk-checkbox.d.ts

@@ -0,0 +1,141 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+import { FormCheckboxControl } from '@angular/forms/signals';
+import { FormUiControlBase } from 'forty-cdk/core';
+
+/**
+ * Injection key the `[forCheckboxIndicator]` uses to resolve its parent
+ * checkbox, decoupled from the concrete `ForCheckbox` class. `ForCheckbox`
+ * provides itself under this token, so a design system wrapping the checkbox
+ * by subclassing re-points it at the subclass with a single provider
+ * (`{ provide: FOR_CHECKBOX, useExisting: MtxCheckbox }`) and the indicator
+ * keeps resolving — see `docs/wrapping-form-primitives.md`.
+ */
+declare const FOR_CHECKBOX: InjectionToken<ForCheckbox>;
+/**
+ * Headless checkbox implementing the
+ * [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+ * with optional tri-state (`indeterminate`) support, plus Angular's
+ * `FormCheckboxControl` from `@angular/forms/signals` for `[formField]`
+ * auto-wiring.
+ *
+ * Apply on a `<button type="button">`. The directive forces `type="button"`
+ * to avoid accidental form submission; Enter and Space activation come from
+ * native button behavior (APG only mandates Space, and Enter is harmless on
+ * a non-submit button).
+ *
+ * Tri-state: when `indeterminate` is `true`, `aria-checked="mixed"` is
+ * announced regardless of `checked`. Activating an indeterminate checkbox
+ * clears `indeterminate` and toggles `checked` from its current value
+ * (matches native `<input type="checkbox">` behavior).
+ *
+ * The accessible name is the consumer's responsibility — wrap the button in a
+ * `<label>` or use `aria-labelledby` / `aria-label`.
+ *
+ * @example
+ * ```html
+ * <button forCheckbox [(checked)]="agreed">
+ *   <span class="indicator"></span>
+ * </button>
+ * I agree to the terms.
+ *
+ * <!-- With Signal Forms: -->
+ * <button forCheckbox [formField]="form.acceptTerms"></button>
+ * ```
+ */
+declare class ForCheckbox extends FormUiControlBase implements FormCheckboxControl {
+    /** Two-way bindable on/off state. Required by `FormCheckboxControl`. */
+    readonly checked: _angular_core.ModelSignal<boolean>;
+    /**
+     * Two-way bindable indeterminate state. When true, `aria-checked="mixed"`
+     * is announced regardless of `checked`. Activation clears it.
+     *
+     * Not part of `FormCheckboxControl` — the field's value stays binary.
+     * Indeterminate is a UI-only concern (e.g. a parent "select all" reflecting
+     * children with mixed selection).
+     */
+    readonly indeterminate: _angular_core.ModelSignal<boolean>;
+    protected readonly ariaChecked: _angular_core.Signal<"true" | "false" | "mixed">;
+    /**
+     * Logical state reflected on `data-state`: `'checked'`, `'unchecked'`, or
+     * `'indeterminate'`. Exposed so `ForCheckboxIndicator` can mirror it without
+     * re-deriving the same mapping.
+     */
+    readonly dataState: _angular_core.Signal<"checked" | "indeterminate" | "unchecked">;
+    constructor();
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCheckbox, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCheckbox, "[forCheckbox]", ["forCheckbox"], { "checked": { "alias": "checked"; "required": false; "isSignal": true; }; "indeterminate": { "alias": "indeterminate"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; "indeterminate": "indeterminateChange"; }, never, never, true, never>;
+}
+
+/**
+ * Optional indicator slot inside a `ForCheckbox`. Apply on the element
+ * the consumer wants to show only while the checkbox is `checked` or
+ * `indeterminate` (typically a check icon, dash, or filled square). The
+ * directive mirrors `data-state` from the parent so the consumer can
+ * style transitions without per-state bindings; hide the unchecked state
+ * via `[data-state="unchecked"] { display: none }` or `@if`.
+ *
+ * Purely a styling convenience — consumers happy with CSS `:has`
+ * selectors or `[data-state]` checks on the parent can skip it entirely.
+ */
+declare class ForCheckboxIndicator {
+    protected readonly parent: ForCheckbox;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCheckboxIndicator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCheckboxIndicator, "[forCheckboxIndicator]", ["forCheckboxIndicator"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant checkboxes in the surrounding injector
+ * scope. Configure with `provideForCheckboxDefaults`. The shape is a stub
+ * today — present so future per-scope tuning can land without churning the
+ * public surface.
+ */
+interface ForCheckboxDefaults {
+}
+/** Token holding the resolved checkbox defaults for the current scope. */
+declare const FOR_CHECKBOX_DEFAULTS: _angular_core.InjectionToken<ForCheckboxDefaults>;
+/**
+ * Configures forty-cdk checkbox defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForCheckboxDefaults(defaults?: Partial<ForCheckboxDefaults>): Provider[];
+
+/**
+ * Exact public names of every `ForCheckbox` input, its models included. Spread it into the
+ * `inputs` array of a `hostDirectives` entry so a wrapper component re-exposes the
+ * primitive's full surface — the Signal Forms members `[formField]` binds among them —
+ * without hand-maintaining the list. Always spread into an inline object literal as shown
+ * below: the literal is what keeps the entry statically analyzable for consumers compiling
+ * against the published package. An anti-drift spec fails when this list no longer matches
+ * the directive's actual API. See `docs/wrapping-form-primitives.md` for both supported
+ * wrapping patterns.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'button[myCheckbox]',
+ *   template: '',
+ *   hostDirectives: [
+ *     {
+ *       directive: ForCheckbox,
+ *       inputs: [...FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS],
+ *       outputs: [...FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS],
+ *     },
+ *   ],
+ * })
+ * export class MyCheckbox {}
+ * ```
+ */
+declare const FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS: readonly ["checked", "indeterminate", "dirty", "disabled", "errors", "invalid", "name", "pending", "readonly", "required", "touched"];
+/**
+ * Exact public names of every `ForCheckbox` output, the Signal Forms `touch` output
+ * included. Spread it into the `outputs` array of the same `hostDirectives` entry as
+ * {@link FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS}.
+ */
+declare const FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS: readonly ["checkedChange", "indeterminateChange", "touchedChange", "touch"];
+
+export { FOR_CHECKBOX, FOR_CHECKBOX_DEFAULTS, FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS, FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS, ForCheckbox, ForCheckboxIndicator, provideForCheckboxDefaults };
+export type { ForCheckboxDefaults };