@almoamendev/ngx-md3 0.2.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almoamendev/ngx-md3",
-  "version": "0.2.2",
+  "version": "0.3.4",
   "description": "MD3-style Angular components & style library",
   "author": "Murtadha (Hussain) Almoamen",
   "license": "MIT",

package/types/almoamendev-ngx-md3.d.ts

@@ -44,6 +44,37 @@ type ListLeadingType = 'icon' | 'avatar' | 'media' | 'selection-input';
 
 type ListLeadingSize = 'image' | 'small-video' | 'large-video';
 
+/**
+ * The arrangement strategy used to size and position carousel items.
+ *
+ * Material Design 3 defines four layouts. Only `multi-browse` is implemented today; the
+ * remaining values will be added to this union as their strategies land, which is a
+ * non-breaking change for consumers.
+ */
+type CarouselLayout = 'multi-browse';
+
+/**
+ * Where the focal (large) items sit within the carousel container.
+ */
+type CarouselAlignment = 'start' | 'center';
+
+/**
+ * The axis the carousel scrolls along.
+ *
+ * Only `horizontal` is implemented today. The type exists so vertical layouts can be added
+ * without changing the public API shape.
+ */
+type CarouselOrientation = 'horizontal';
+
+/**
+ * Size band a carousel item currently renders at.
+ *
+ * Item sizes are continuous, so this is the nearest of the arrangement's three sizes rather than
+ * the keyline the item happens to be resting on. It changes as the item is scrolled, and is
+ * mirrored onto the element as `md3-large`, `md3-medium` or `md3-small`.
+ */
+type CarouselItemSize = 'large' | 'medium' | 'small';
+
 /**
  * What happens to a dialog that is already open when a new dialog opens.
  * - close: the open dialogs are closed before the new one opens.
@@ -263,6 +294,147 @@ interface SnackbarConfig<D = unknown> {
     injector?: Injector;
 }
 
+/**
+ * A solved distribution of large, medium and small items that exactly fills the carousel
+ * container. Produced by a {@link CarouselStrategy}, consumed by the keyline builder.
+ *
+ * All sizes are in pixels and already include the item gap.
+ */
+interface CarouselArrangement {
+    /** Size of a fully unmasked item. Also the size each item occupies in scroll space. */
+    largeSize: number;
+    largeCount: number;
+    mediumSize: number;
+    mediumCount: number;
+    smallSize: number;
+    smallCount: number;
+}
+
+/**
+ * A single slot in the carousel container.
+ *
+ * An item does not have a fixed size: it adopts the size of whichever keyline it is currently
+ * passing through, interpolating continuously between neighbours as it scrolls.
+ *
+ * Two coordinate systems are in play, both measured along the scroll axis from the container's
+ * logical start edge:
+ *
+ * - **screen space** (`screenLoc`) — where the keyline actually renders, the running sum of
+ *   masked sizes.
+ * - **scroll space** (`scrollLoc`) — where the keyline sits if every item were fully unmasked.
+ *   Keylines are always `largeSize` apart here, which is what makes item positions a simple
+ *   function of `scrollLeft`.
+ */
+interface CarouselKeyline {
+    /** Centre of the keyline in scroll space. Used to look an item up by its scroll position. */
+    scrollLoc: number;
+    /** Centre of the keyline in screen space. Used to position the item. */
+    screenLoc: number;
+    /** Rendered size of an item resting exactly on this keyline. */
+    maskedSize: number;
+    /** True for the large keylines — the "selected" region of the carousel. */
+    isFocal: boolean;
+    /** True for the off-screen keylines items shrink into as they leave the container. */
+    isAnchor: boolean;
+}
+/**
+ * A complete keyline arrangement for one discrete shift step.
+ *
+ * Every state in a carousel holds the same number of keylines, so states can be interpolated
+ * index by index.
+ */
+interface CarouselKeylineState {
+    keylines: CarouselKeyline[];
+    /** Offset of the focal region's leading edge, in screen space. */
+    focalStart: number;
+    firstFocalIndex: number;
+    lastFocalIndex: number;
+}
+/**
+ * Everything needed to place items for a given container size, resolved once per layout pass.
+ */
+interface CarouselGeometry {
+    /** The solved arrangement this geometry was built from. */
+    arrangement: CarouselArrangement;
+    /** Shift steps ordered by ascending `focalStart`, from the start state to the end state. */
+    steps: CarouselKeylineState[];
+    /** Index within `steps` of the arrangement's resting state. */
+    defaultStep: number;
+    /** Size of a fully unmasked item, and the scroll distance between consecutive items. */
+    itemSize: number;
+    /** Scroll distance over which keylines shift while approaching the start of the list. */
+    startShiftRange: number;
+    /** Scroll distance over which keylines shift while approaching the end of the list. */
+    endShiftRange: number;
+    /** Largest valid scroll offset. */
+    maxScroll: number;
+    /**
+     * Highest index the carousel can come to rest on.
+     *
+     * The final `largeCount` items share the focal range at `maxScroll`, so they are all visible
+     * at once and none of them has a resting position of its own. Scrolling past this index is
+     * impossible, which is why it is the point where the carousel counts as being at the end.
+     */
+    lastIndex: number;
+    /** Total inline size of the scrollable content. */
+    scrollSize: number;
+}
+/**
+ * Resolved placement for a single item at a given scroll offset.
+ */
+interface CarouselItemGeometry {
+    /** Distance from the container's logical start edge to the item's leading edge. */
+    offset: number;
+    /** Current rendered size of the item. */
+    maskedSize: number;
+    /** Which of the arrangement's three sizes the item currently renders closest to. */
+    size: CarouselItemSize;
+    /** 0 when fully unmasked, approaching 1 as the item crops away. */
+    maskRatio: number;
+    /** True while the item rests within the focal region. */
+    isFocal: boolean;
+    /** False when the item is outside the container and should not be rendered. */
+    isVisible: boolean;
+}
+
+/**
+ * Everything a strategy needs to solve an arrangement. All sizes are in pixels.
+ */
+interface CarouselStrategyContext {
+    /** Size of the carousel along the scroll axis. */
+    containerSize: number;
+    /** Requested size of a fully unmasked item, gap included. */
+    itemSize: number;
+    /** Smallest a small item is allowed to be, gap included. */
+    smallSizeMin: number;
+    /** Largest a small item is allowed to be, gap included. */
+    smallSizeMax: number;
+    /** Number of items projected into the carousel. */
+    itemCount: number;
+    alignment: CarouselAlignment;
+}
+/**
+ * Sizes and counts the items of a carousel so they fill the container in a visually balanced way.
+ *
+ * Implement this to add a new carousel layout, then register it in `CAROUSEL_STRATEGIES`.
+ * Strategies must be pure: same context in, same arrangement out.
+ */
+interface CarouselStrategy {
+    /**
+     * Whether items must come to rest exactly on keylines.
+     *
+     * Layouts that resize items need this: their arrangement only reads correctly when every
+     * item is sitting on a keyline, and settling part-way through leaves items at sizes that
+     * belong to no keyline at all. Layouts that keep items at a fixed size, such as uncontained,
+     * can scroll freely.
+     *
+     * This is a property of the layout rather than something consumers choose, so that a
+     * carousel can never be configured into a state that contradicts its own arrangement.
+     */
+    readonly snap: boolean;
+    arrange(context: CarouselStrategyContext): CarouselArrangement;
+}
+
 declare class TypeDisplay {
     el: ElementRef;
     size: _angular_core.InputSignal<TextSize | "default">;
@@ -598,6 +770,234 @@ declare class Card implements AfterViewInit {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<Card, "md3-card, button[md3-card], a[md3-card]", never, { "cardType": { "alias": "card-type"; "required": false; "isSignal": true; }; "isInteractive": { "alias": "interactive"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof StateComponent; inputs: {}; outputs: {}; }]>;
 }
 
+/**
+ * A single item within an `md3-carousel`.
+ *
+ * The item is a clipping box whose content stays at full size, so scrolling crops the item
+ * towards its centre rather than squashing it. Content should be full-bleed — an image or a
+ * background that reaches the edges — or the crop will reveal empty space.
+ *
+ * Position and size are written straight to CSS custom properties by the parent carousel, so
+ * styling never waits on change detection. The same values are mirrored onto signals and onto
+ * `md3-large` / `md3-medium` / `md3-small` classes, so content can react to the item's size
+ * either declaratively or from a stylesheet.
+ */
+declare class CarouselItem {
+    private el;
+    /** 0 while the item is fully unmasked, approaching 1 as it crops away. */
+    readonly maskRatio: _angular_core.WritableSignal<number>;
+    /** Current rendered size of the item, in pixels. */
+    readonly maskedSize: _angular_core.WritableSignal<number>;
+    /** True while the item rests in the carousel's focal range. */
+    readonly isFocal: _angular_core.WritableSignal<boolean>;
+    /**
+     * Which of the arrangement's three sizes the item currently reads as.
+     *
+     * Mirrored onto the element as `md3-large`, `md3-medium` or `md3-small`.
+     */
+    readonly size: _angular_core.WritableSignal<CarouselItemSize>;
+    constructor(el: ElementRef<HTMLElement>);
+    get element(): HTMLElement;
+    /**
+     * Applies a resolved placement.
+     *
+     * Called from the carousel's scroll handler on every frame, so this writes to the DOM
+     * directly and only touches signals when a value actually changes.
+     */
+    applyGeometry(geometry: CarouselItemGeometry, itemSize: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CarouselItem, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CarouselItem, "md3-carousel-item", never, {}, {}, never, ["*"], true, never>;
+}
+
+/**
+ * A Material Design 3 carousel.
+ *
+ * Items are laid out against a set of keylines — large, medium, small and an off-screen anchor —
+ * and adopt the size of whichever keyline they are passing through, so they grow into the focal
+ * range and crop away as they leave it.
+ *
+ * Scrolling is native, which keeps momentum, touch, snapping and the scrollbar intact. Only the
+ * visual sizing is derived in TypeScript, and it is written straight to CSS custom properties so
+ * scrolling never triggers change detection.
+ *
+ * All size inputs are in pixels.
+ *
+ * ```html
+ * <md3-carousel [(index)]="selected" [item-size]="200">
+ *   @for (photo of photos(); track photo.id) {
+ *     <md3-carousel-item>
+ *       <img [src]="photo.url" [alt]="photo.alt" />
+ *     </md3-carousel-item>
+ *   }
+ * </md3-carousel>
+ * ```
+ */
+declare class Carousel {
+    private el;
+    /** Arrangement strategy. Additional Material Design layouts will widen this type. */
+    carouselLayout: _angular_core.InputSignal<"multi-browse">;
+    /** Where the focal (large) items sit within the container. */
+    alignment: _angular_core.InputSignal<CarouselAlignment>;
+    /** Scroll axis. Only `horizontal` is implemented today. */
+    orientation: _angular_core.InputSignal<"horizontal">;
+    /** Preferred size of a fully unmasked item, in pixels. */
+    itemSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Smallest a small item may shrink to, in pixels. */
+    smallItemSizeMin: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Largest a small item may grow to, in pixels. */
+    smallItemSizeMax: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Space between items, in pixels. */
+    gap: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Index of the item leading the focal range. Two-way bindable.
+     *
+     * Clamped to {@link lastIndex}: the final items share the focal range and are all visible at
+     * once, so there is no scroll position where any of them leads on its own. Setting a higher
+     * value scrolls to the end and reads back as `lastIndex`.
+     */
+    index: _angular_core.ModelSignal<number>;
+    /** Items projected into the carousel, in document order. */
+    readonly items: _angular_core.Signal<readonly CarouselItem[]>;
+    /**
+     * Whether the current layout brings items to rest on keylines.
+     *
+     * Decided by the layout, not by the consumer: an arrangement that resizes items only reads
+     * correctly when they are sitting on keylines.
+     */
+    readonly snap: _angular_core.Signal<boolean>;
+    private scroller;
+    private containerSize;
+    private readonly directionality;
+    /**
+     * Sizes handed to the solver.
+     *
+     * Gaps are folded into item sizes so the solver only has one quantity to balance, then
+     * removed again visually by insetting each item half a gap on both sides.
+     */
+    private readonly metrics;
+    /** The solved distribution of large, medium and small items for the current container. */
+    readonly arrangement: _angular_core.Signal<CarouselArrangement | undefined>;
+    /** Keyline geometry derived from the arrangement. */
+    readonly geometry: _angular_core.Signal<CarouselGeometry | undefined>;
+    /** Scroll offsets that items snap to, one per item. */
+    protected readonly snapPoints: _angular_core.Signal<number[]>;
+    /**
+     * Highest index the carousel can rest on.
+     *
+     * Lower than the last item's index, because the trailing items share the focal range once
+     * the carousel is scrolled to the end. It moves as the container is resized, since a wider
+     * container fits more items in the focal range.
+     */
+    readonly lastIndex: _angular_core.Signal<number>;
+    readonly atStart: _angular_core.Signal<boolean>;
+    /** True when the carousel cannot scroll any further towards the end. */
+    readonly atEnd: _angular_core.Signal<boolean>;
+    private readonly isBrowser;
+    private scrollEndTimer;
+    private frame;
+    /**
+     * Target of an in-flight programmatic scroll.
+     *
+     * Smooth scrolling reports intermediate offsets, and reading the index back from those would
+     * fight the animation, so index syncing pauses until the target is reached or the user takes
+     * over.
+     */
+    private pendingScroll;
+    constructor(el: ElementRef<HTMLElement>);
+    get element(): HTMLElement;
+    /** True when laid out right-to-left. */
+    protected get isRtl(): boolean;
+    protected onKeydown(event: KeyboardEvent): void;
+    /**
+     * Keeps a focused item in view.
+     *
+     * Items are absolutely positioned, so the browser cannot scroll them into view on its own.
+     * Without this, tabbing to a link inside a cropped item would leave it invisible.
+     */
+    protected onFocusIn(event: FocusEvent): void;
+    /** Scrolls until `index` leads the focal range, clamping to {@link lastIndex}. */
+    scrollToIndex(index: number, behavior?: ScrollBehavior): void;
+    next(): void;
+    previous(): void;
+    private measure;
+    /**
+     * Current scroll position as a positive offset from the logical start edge.
+     *
+     * Right-to-left scroll containers report `scrollLeft` as zero at the start and negative
+     * moving away from it, so the magnitude is the logical offset in both directions.
+     */
+    private scrollOffset;
+    private scrollTo;
+    private scheduleGeometry;
+    /** `scrollend` is not universally supported, so back it with a timer. */
+    private scheduleIndexSync;
+    private syncIndexFromScroll;
+    /**
+     * Writes the current placement of every item.
+     *
+     * Runs on every scroll frame, so it touches the DOM directly and allocates nothing beyond
+     * the resolved state.
+     */
+    private applyGeometry;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Carousel, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Carousel, "md3-carousel", never, { "carouselLayout": { "alias": "carousel-layout"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "itemSize": { "alias": "item-size"; "required": false; "isSignal": true; }; "smallItemSizeMin": { "alias": "small-item-size-min"; "required": false; "isSignal": true; }; "smallItemSizeMax": { "alias": "small-item-size-max"; "required": false; "isSignal": true; }; "gap": { "alias": "gap"; "required": false; "isSignal": true; }; "index": { "alias": "index"; "required": false; "isSignal": true; }; }, { "index": "indexChange"; }, ["items"], ["*"], true, never>;
+}
+
+/**
+ * The Material Design 3 multi-browse layout: a run of large items followed by a medium and a
+ * small item, sized so the whole arrangement fills the container exactly.
+ *
+ * Ported from `MultiBrowseCarouselStrategy` and `Arrangement` in Material Components for
+ * Android so the two implementations agree on sizing.
+ */
+declare const multiBrowseStrategy: CarouselStrategy;
+/**
+ * Registry of the available carousel layouts.
+ *
+ * Adding a layout means implementing {@link CarouselStrategy}, widening `CarouselLayout` and
+ * adding the entry here — no changes to the component itself.
+ */
+declare const CAROUSEL_STRATEGIES: Record<CarouselLayout, CarouselStrategy>;
+
+/**
+ * Turns a solved arrangement into everything the component needs to place items.
+ */
+declare function buildGeometry(arrangement: CarouselArrangement, alignment: CarouselAlignment, itemCount: number, containerSize: number): CarouselGeometry;
+/**
+ * Resolves the keyline arrangement in effect at a given scroll offset.
+ */
+declare function resolveState(geometry: CarouselGeometry, scrollOffset: number): CarouselKeylineState;
+/**
+ * Classifies a rendered size against the arrangement's three sizes.
+ *
+ * Items resize continuously, so this snaps to whichever size the item currently reads as,
+ * flipping at the midpoint between one size and the next.
+ */
+declare function sizeBandFor(maskedSize: number, geometry: CarouselGeometry): CarouselItemSize;
+/**
+ * Places one item.
+ *
+ * The item's centre is a plain linear function of the scroll offset in scroll space; looking
+ * that position up against the current keylines is what converts it into a rendered size and
+ * an on-screen position.
+ */
+declare function resolveItemGeometry(geometry: CarouselGeometry, state: CarouselKeylineState, index: number, scrollOffset: number): CarouselItemGeometry;
+/**
+ * Clamps an index to one the carousel can actually come to rest on.
+ */
+declare function clampIndex(geometry: CarouselGeometry, index: number): number;
+/**
+ * Scroll offset at which `index` leads the focal range.
+ *
+ * The shifting focal range cancels out here, so this stays a simple multiple regardless of
+ * alignment or how close to either end of the list the item is.
+ */
+declare function scrollOffsetForIndex(geometry: CarouselGeometry, index: number): number;
+/**
+ * The item leading the focal range at a given scroll offset.
+ */
+declare function indexForScrollOffset(geometry: CarouselGeometry, scrollOffset: number): number;
+
 declare class ChipAvatar {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChipAvatar, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ChipAvatar, "[md3-chip-avatar]", never, {}, {}, never, never, true, never>;
@@ -760,7 +1160,7 @@ declare class ListItemPrimaryAction {
 declare class ListItem implements AfterViewInit {
     private el;
     private state;
-    slotsAlignment: _angular_core.InputSignal<"start" | "end" | "center">;
+    slotsAlignment: _angular_core.InputSignal<"start" | "center" | "end">;
     selected: _angular_core.InputSignalWithTransform<boolean, unknown>;
     isActionTag: boolean;
     private isLabelTag;
@@ -1510,5 +1910,5 @@ declare class SnackbarService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SnackbarService>;
 }
 
-export { AppBar, AppBarLogo, Avatar, Badge, Button, ButtonGroup, Card, Checkbox, ChipAvatar, Chips, CircularProgressIndicator, DIALOG_COMPONENT, DIALOG_CONFIG, DIALOG_DATA, Dialog, DialogActions, DialogBody, DialogHeader, DialogRef, DialogService, Divider, FloatingActionButton, FullScreenDialog, FullScreenDialogHeader, Grid, GridItem, IconButton, IconElement, InputElement, LayoutService, LinearProgressIndicator, List, ListItem, ListItemPrimaryAction, ListLeading, ListSlot, LoadingIndicator, MENU_COMPONENT, MENU_CONFIG, MENU_DATA, MaterialIcon, Menu, MenuGroup, MenuItem, MenuRef, MenuService, NavigationBar, NavigationGroup, NavigationItem, NavigationRail, RadioButton, SIDE_SHEET_COMPONENT, SIDE_SHEET_CONFIG, SIDE_SHEET_DATA, SNACKBAR_ACTION_LABEL, SNACKBAR_CONFIG, SNACKBAR_MESSAGE, Scaffold, ScaffoldBar, ScaffoldPane, ScaffoldRail, SheetsService, SideSheetActions, SideSheetBody, SideSheetHeader, SideSheetRef, Slider, Snackbar, SnackbarRef, SnackbarService, SplitButton, StateComponent, SupportingText, Switch, TextField, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle };
-export type { AppBarScrollingStyle, AppBarType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, ChipStyle, ChipType, DialogConfig, DialogContainer, DialogRole, FabSize, FabType, FullScreenDialogConfig, IconButtonType, IconButtonWidth, ListLeadingSize, ListLeadingType, Md3NavigationMode, MenuConfig, MenuPositionOrigin, MenuPositionX, MenuPositionY, MenuScrollStrategy, PreviousDialog, SideSheetConfig, SideSheetContainer, SideSheetSide, SideSheetType, SliderSize, SnackbarConfig, SnackbarDismiss, SnackbarDismissReason, SnackbarPoliteness, SplitButtonType, TextColor, TextSize };
+export { AppBar, AppBarLogo, Avatar, Badge, Button, ButtonGroup, CAROUSEL_STRATEGIES, Card, Carousel, CarouselItem, Checkbox, ChipAvatar, Chips, CircularProgressIndicator, DIALOG_COMPONENT, DIALOG_CONFIG, DIALOG_DATA, Dialog, DialogActions, DialogBody, DialogHeader, DialogRef, DialogService, Divider, FloatingActionButton, FullScreenDialog, FullScreenDialogHeader, Grid, GridItem, IconButton, IconElement, InputElement, LayoutService, LinearProgressIndicator, List, ListItem, ListItemPrimaryAction, ListLeading, ListSlot, LoadingIndicator, MENU_COMPONENT, MENU_CONFIG, MENU_DATA, MaterialIcon, Menu, MenuGroup, MenuItem, MenuRef, MenuService, NavigationBar, NavigationGroup, NavigationItem, NavigationRail, RadioButton, SIDE_SHEET_COMPONENT, SIDE_SHEET_CONFIG, SIDE_SHEET_DATA, SNACKBAR_ACTION_LABEL, SNACKBAR_CONFIG, SNACKBAR_MESSAGE, Scaffold, ScaffoldBar, ScaffoldPane, ScaffoldRail, SheetsService, SideSheetActions, SideSheetBody, SideSheetHeader, SideSheetRef, Slider, Snackbar, SnackbarRef, SnackbarService, SplitButton, StateComponent, SupportingText, Switch, TextField, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle, buildGeometry, clampIndex, indexForScrollOffset, multiBrowseStrategy, resolveItemGeometry, resolveState, scrollOffsetForIndex, sizeBandFor };
+export type { AppBarScrollingStyle, AppBarType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, CarouselAlignment, CarouselArrangement, CarouselGeometry, CarouselItemGeometry, CarouselItemSize, CarouselKeyline, CarouselKeylineState, CarouselLayout, CarouselOrientation, CarouselStrategy, CarouselStrategyContext, ChipStyle, ChipType, DialogConfig, DialogContainer, DialogRole, FabSize, FabType, FullScreenDialogConfig, IconButtonType, IconButtonWidth, ListLeadingSize, ListLeadingType, Md3NavigationMode, MenuConfig, MenuPositionOrigin, MenuPositionX, MenuPositionY, MenuScrollStrategy, PreviousDialog, SideSheetConfig, SideSheetContainer, SideSheetSide, SideSheetType, SliderSize, SnackbarConfig, SnackbarDismiss, SnackbarDismissReason, SnackbarPoliteness, SplitButtonType, TextColor, TextSize };