material 1.0.3 → 3.0.0-next.0

package/dist/components/carousel/keylines.js

@@ -0,0 +1,292 @@
+import { findLowestCostArrangement, itemCount } from "./arrangement.js";
+export const firstFocalIndex = (list) => list.findIndex((k) => k.isFocal);
+export const lastFocalIndex = (list) => {
+    for (let i = list.length - 1; i >= 0; i--)
+        if (list[i].isFocal)
+            return i;
+    return -1;
+};
+export const firstNonAnchorIndex = (list) => list.findIndex((k) => !k.isAnchor);
+export const lastNonAnchorIndex = (list) => {
+    for (let i = list.length - 1; i >= 0; i--)
+        if (!list[i].isAnchor)
+            return i;
+    return -1;
+};
+export const pivotIndex = (list) => list.findIndex((k) => k.isPivot);
+export const focalCount = (list) => lastFocalIndex(list) - firstFocalIndex(list) + 1;
+export const minSize = (list) => list.reduce((m, k) => Math.min(m, k.size), Number.MAX_VALUE);
+export const maxSize = (list) => list.reduce((m, k) => Math.max(m, k.size), 0);
+export const isFirstFocalItemAtStartOfContainer = (list) => {
+    const first = list[firstFocalIndex(list)];
+    return first.offset - first.size / 2 >= 0 && firstFocalIndex(list) === firstNonAnchorIndex(list);
+};
+export const isLastFocalItemAtEndOfContainer = (list, containerSize) => {
+    const last = list[lastFocalIndex(list)];
+    return last.offset + last.size / 2 <= containerSize && lastFocalIndex(list) === lastNonAnchorIndex(list);
+};
+export const firstIndexAfterFocalRangeWithSize = (list, size) => {
+    for (let i = lastFocalIndex(list); i < list.length; i++)
+        if (list[i].size === size)
+            return i;
+    return list.length - 1;
+};
+export const lastIndexBeforeFocalRangeWithSize = (list, size) => {
+    for (let i = firstFocalIndex(list) - 1; i >= 0; i--)
+        if (list[i].size === size)
+            return i;
+    return 0;
+};
+export const keylineBefore = (list, unadjustedOffset) => {
+    for (let i = list.length - 1; i >= 0; i--) {
+        if (list[i].unadjustedOffset < unadjustedOffset)
+            return list[i];
+    }
+    return list[0];
+};
+export const keylineAfter = (list, unadjustedOffset) => list.find((k) => k.unadjustedOffset >= unadjustedOffset) ?? list[list.length - 1];
+const mix = (a, b, t) => a + (b - a) * t;
+export const lerpKeyline = (a, b, t) => ({
+    size: mix(a.size, b.size, t),
+    offset: mix(a.offset, b.offset, t),
+    unadjustedOffset: mix(a.unadjustedOffset, b.unadjustedOffset, t),
+    isFocal: t < 0.5 ? a.isFocal : b.isFocal,
+    isAnchor: t < 0.5 ? a.isAnchor : b.isAnchor,
+    isPivot: t < 0.5 ? a.isPivot : b.isPivot,
+    cutoff: mix(a.cutoff, b.cutoff, t),
+});
+export const lerpKeylineList = (from, to, t) => from.map((k, i) => lerpKeyline(k, to[i], t));
+const isCutoffLeft = (size, offset) => offset - size / 2 < 0 && offset + size / 2 > 0;
+const isCutoffRight = (size, offset, containerSize) => offset - size / 2 < containerSize && offset + size / 2 > containerSize;
+const focalRange = (tmp) => {
+    let first = -1;
+    let size = 0;
+    tmp.forEach((k, i) => {
+        if (!k.isAnchor && k.size > size) {
+            first = i;
+            size = k.size;
+        }
+    });
+    if (first < 0)
+        return [-1, -1, 0];
+    let last = first;
+    while (last < tmp.length - 1 && tmp[last + 1].size === size)
+        last++;
+    return [first, last, size];
+};
+const buildAroundPivot = (tmp, pivotIdx, pivotOffset, firstFocal, lastFocal, itemSize, containerSize, gap) => {
+    if (tmp.length === 0 || pivotIdx < 0 || pivotIdx >= tmp.length)
+        return [];
+    const pivot = tmp[pivotIdx];
+    const list = [];
+    const pivotCutoff = isCutoffLeft(pivot.size, pivotOffset)
+        ? pivotOffset - pivot.size / 2
+        : isCutoffRight(pivot.size, pivotOffset, containerSize)
+            ? pivotOffset + pivot.size / 2 - containerSize
+            : 0;
+    list.push({
+        size: pivot.size,
+        offset: pivotOffset,
+        unadjustedOffset: pivotOffset,
+        isFocal: pivotIdx >= firstFocal && pivotIdx <= lastFocal,
+        isAnchor: pivot.isAnchor,
+        isPivot: true,
+        cutoff: pivotCutoff,
+    });
+    let offset = pivotOffset - itemSize / 2 - gap;
+    let unadjusted = pivotOffset - itemSize / 2 - gap;
+    for (let i = pivotIdx - 1; i >= 0; i--) {
+        const k = tmp[i];
+        const kOffset = offset - k.size / 2;
+        const kUnadjusted = unadjusted - itemSize / 2;
+        list.unshift({
+            size: k.size,
+            offset: kOffset,
+            unadjustedOffset: kUnadjusted,
+            isFocal: i >= firstFocal && i <= lastFocal,
+            isAnchor: k.isAnchor,
+            isPivot: false,
+            cutoff: isCutoffLeft(k.size, kOffset) ? Math.abs(kOffset - k.size / 2) : 0,
+        });
+        offset -= k.size + gap;
+        unadjusted -= itemSize + gap;
+    }
+    offset = pivotOffset + itemSize / 2 + gap;
+    unadjusted = pivotOffset + itemSize / 2 + gap;
+    for (let i = pivotIdx + 1; i < tmp.length; i++) {
+        const k = tmp[i];
+        const kOffset = offset + k.size / 2;
+        const kUnadjusted = unadjusted + itemSize / 2;
+        list.push({
+            size: k.size,
+            offset: kOffset,
+            unadjustedOffset: kUnadjusted,
+            isFocal: i >= firstFocal && i <= lastFocal,
+            isAnchor: k.isAnchor,
+            isPivot: false,
+            cutoff: isCutoffRight(k.size, kOffset, containerSize) ? kOffset + k.size / 2 - containerSize : 0,
+        });
+        offset += k.size + gap;
+        unadjusted += itemSize + gap;
+    }
+    return list;
+};
+export const keylineListWithPivot = (containerSize, gap, pivotIdx, pivotOffset, tmp) => {
+    const [firstFocal, lastFocal, itemSize] = focalRange(tmp);
+    return buildAroundPivot(tmp, pivotIdx, pivotOffset, firstFocal, lastFocal, itemSize, containerSize, gap);
+};
+export const keylineListAligned = (containerSize, gap, alignment, tmp) => {
+    const [firstFocal, lastFocal, itemSize] = focalRange(tmp);
+    if (firstFocal < 0)
+        return [];
+    const focalItems = lastFocal - firstFocal;
+    let pivotOffset = itemSize / 2;
+    if (alignment === 'center') {
+        const split = gap === 0 || focalItems % 2 === 0 ? 0 : gap / 2;
+        const spaces = Math.floor(focalItems / 2) * gap;
+        pivotOffset = containerSize / 2 - (itemSize / 2) * focalItems - split - spaces;
+    }
+    return buildAroundPivot(tmp, firstFocal, pivotOffset, firstFocal, lastFocal, itemSize, containerSize, gap);
+};
+const fromArrangement = (a, containerSize, gap, leftAnchor, rightAnchor, alignment) => {
+    const tmp = [{ size: leftAnchor, isAnchor: true }];
+    const push = (size, count) => {
+        for (let i = 0; i < count; i++)
+            tmp.push({ size, isAnchor: false });
+    };
+    if (alignment === 'center') {
+        push(a.smallSize, Math.floor(a.smallCount / 2));
+        push(a.mediumSize, Math.floor(a.mediumCount / 2));
+        push(a.largeSize, a.largeCount);
+        push(a.mediumSize, Math.ceil(a.mediumCount / 2));
+        push(a.smallSize, Math.ceil(a.smallCount / 2));
+    }
+    else {
+        push(a.largeSize, a.largeCount);
+        push(a.mediumSize, a.mediumCount);
+        push(a.smallSize, a.smallCount);
+    }
+    tmp.push({ size: rightAnchor, isAnchor: true });
+    return keylineListAligned(containerSize, gap, alignment, tmp);
+};
+const range = (from, to) => {
+    const out = [];
+    for (let n = from; n >= to; n--)
+        out.push(n);
+    return out;
+};
+export const multiBrowseKeylines = (containerSize, preferredItemSize, gap, count, rules) => {
+    if (containerSize <= 0 || preferredItemSize <= 0)
+        return [];
+    let smallCounts = [1];
+    const mediumCounts = [1, 0];
+    const targetLarge = Math.min(preferredItemSize, containerSize);
+    const targetSmall = Math.min(Math.max(targetLarge / 3, rules.minSmallSize), rules.maxSmallSize);
+    const targetMedium = (targetLarge + targetSmall) / 2;
+    if (containerSize < rules.minSmallSize * 2)
+        smallCounts = [0];
+    const minLargeSpace = containerSize - targetMedium * Math.max(...mediumCounts) - rules.maxSmallSize * Math.max(...smallCounts);
+    const minLargeCount = Math.max(1, Math.floor(minLargeSpace / targetLarge));
+    const maxLargeCount = Math.ceil(containerSize / targetLarge);
+    const largeCounts = range(maxLargeCount, minLargeCount);
+    const options = {
+        availableSpace: containerSize,
+        gap,
+        targetSmallSize: targetSmall,
+        minSmallSize: rules.minSmallSize,
+        maxSmallSize: rules.maxSmallSize,
+        smallCounts,
+        targetMediumSize: targetMedium,
+        mediumCounts,
+        targetLargeSize: targetLarge,
+        largeCounts,
+    };
+    let arrangement = findLowestCostArrangement(options);
+    if (arrangement && itemCount(arrangement) > count) {
+        let surplus = itemCount(arrangement) - count;
+        let smallCount = arrangement.smallCount;
+        let mediumCount = arrangement.mediumCount;
+        while (surplus > 0) {
+            if (smallCount > 0)
+                smallCount -= 1;
+            else if (mediumCount > 1)
+                mediumCount -= 1;
+            surplus -= 1;
+        }
+        arrangement = findLowestCostArrangement({ ...options, smallCounts: [smallCount], mediumCounts: [mediumCount] });
+    }
+    if (!arrangement)
+        return [];
+    return fromArrangement(arrangement, containerSize, gap, rules.anchorSize, rules.anchorSize, 'start');
+};
+export const heroKeylines = (containerSize, maxItemSize, gap, count, centered, rules) => {
+    if (containerSize <= 0)
+        return [];
+    const shouldCenter = centered && count >= 3;
+    let smallCounts = count <= 1 ? [0] : shouldCenter ? [2] : [1];
+    const targetLarge = Math.min(maxItemSize ?? containerSize, containerSize);
+    const targetSmall = Math.min(Math.max(targetLarge / 3, rules.minSmallSize), rules.maxSmallSize);
+    const fullscreenThreshold = rules.minSmallSize * Math.max(...smallCounts) + rules.minSmallSize * 1.25;
+    if (containerSize < fullscreenThreshold)
+        smallCounts = [0];
+    const minLargeSpace = containerSize - rules.minSmallSize * Math.max(...smallCounts);
+    const minLargeCount = Math.max(1, Math.floor(minLargeSpace / targetLarge));
+    const maxLargeCount = Math.ceil(containerSize / targetLarge);
+    const arrangement = findLowestCostArrangement({
+        availableSpace: containerSize,
+        gap,
+        targetSmallSize: targetSmall,
+        minSmallSize: rules.minSmallSize,
+        maxSmallSize: rules.maxSmallSize,
+        smallCounts,
+        targetMediumSize: 0,
+        mediumCounts: [0],
+        targetLargeSize: targetLarge,
+        largeCounts: range(maxLargeCount, minLargeCount),
+    });
+    if (!arrangement)
+        return [];
+    const alignment = shouldCenter && count >= itemCount(arrangement) ? 'center' : 'start';
+    return fromArrangement(arrangement, containerSize, gap, rules.anchorSize, rules.anchorSize, alignment);
+};
+const mediumChildSize = (minimum, largeSize, remaining, threshold) => {
+    let medium = Math.max(remaining * 1.5, minimum);
+    if (medium > largeSize * threshold)
+        medium = Math.max(remaining * 1.2, minimum);
+    return medium;
+};
+export const uncontainedKeylines = (containerSize, itemSize, gap, rules) => {
+    if (containerSize <= 0 || itemSize <= 0)
+        return [];
+    const large = Math.min(itemSize, containerSize);
+    const largeCount = Math.max(1, Math.floor((containerSize + gap) / (large + gap)));
+    const remaining = Math.max(0, containerSize - largeCount * (large + gap));
+    const mediumCount = remaining > 0 ? 1 : 0;
+    const medium = mediumChildSize(rules.anchorSize, large, remaining, rules.mediumLargeThreshold);
+    const arrangement = {
+        priority: 0,
+        smallSize: 0,
+        smallCount: 0,
+        mediumSize: medium,
+        mediumCount,
+        largeSize: large,
+        largeCount,
+    };
+    const xSmall = Math.min(rules.anchorSize, itemSize);
+    const leftAnchor = Math.max(xSmall, medium * 0.5);
+    return fromArrangement(arrangement, containerSize, gap, leftAnchor, rules.anchorSize, 'start');
+};
+export const fullScreenKeylines = (containerSize, gap, rules) => {
+    if (containerSize <= 0)
+        return [];
+    const arrangement = {
+        priority: 0,
+        smallSize: 0,
+        smallCount: 0,
+        mediumSize: 0,
+        mediumCount: 0,
+        largeSize: containerSize,
+        largeCount: 1,
+    };
+    return fromArrangement(arrangement, containerSize, gap, rules.anchorSize, rules.anchorSize, 'start');
+};

package/dist/components/carousel/strategy.d.ts

@@ -0,0 +1,36 @@
+import { Keyline, KeylineList } from "./keylines.js";
+export interface Strategy {
+    defaultKeylines: KeylineList;
+    startSteps: KeylineList[];
+    endSteps: KeylineList[];
+    availableSpace: number;
+    gap: number;
+    beforePadding: number;
+    afterPadding: number;
+    /** Size of a large item: the unit every item is measured in before adjustment */
+    itemSize: number;
+    minItemSize: number;
+    maxItemSize: number;
+    valid: boolean;
+    startShiftDistance: number;
+    endShiftDistance: number;
+    startShiftPoints: number[];
+    endShiftPoints: number[];
+}
+export interface ItemPlacement {
+    /** Visible size of the item along the axis */
+    size: number;
+    /** Centre of the visible part, in container coordinates */
+    center: number;
+    /** Interpolated keyline the item sits on */
+    keyline: Keyline;
+}
+export declare const createStrategy: (defaultKeylines: KeylineList, availableSpace: number, gap: number, beforePadding: number, afterPadding: number) => Strategy;
+/** Keylines in effect for a scroll offset: default, or interpolated within the start or end shift range */
+export declare const keylinesForScrollOffset: (s: Strategy, scrollOffset: number, maxScrollOffset: number, roundToNearestStep?: boolean) => KeylineList;
+/** Distance from the container start to an item's start when that item is snapped */
+export declare const snapPositionOffset: (s: Strategy, index: number, count: number) => number;
+/** Largest scroll offset: the content laid out at large size minus the container */
+export declare const maxScrollOffset: (s: Strategy, count: number) => number;
+/** Where an item sits and how much of it shows for the keylines in effect */
+export declare const placeItem: (s: Strategy, keylines: KeylineList, index: number, scrollOffset: number) => ItemPlacement;

package/dist/components/carousel/strategy.js

@@ -0,0 +1,207 @@
+import { firstFocalIndex, lastFocalIndex, firstNonAnchorIndex, lastNonAnchorIndex, pivotIndex, focalCount, minSize, maxSize, isFirstFocalItemAtStartOfContainer, isLastFocalItemAtEndOfContainer, firstIndexAfterFocalRangeWithSize, lastIndexBeforeFocalRangeWithSize, keylineBefore, keylineAfter, lerpKeyline, lerpKeylineList, keylineListWithPivot, } from "./keylines.js";
+const clampLerp = (outMin, outMax, inMin, inMax, value) => {
+    if (value <= inMin)
+        return outMin;
+    if (value >= inMax)
+        return outMax;
+    return outMin + (outMax - outMin) * ((value - inMin) / (inMax - inMin));
+};
+const shiftedForContentPadding = (from, containerSize, gap, contentPadding, pivot, pivotIdx) => {
+    const nonAnchors = from.filter((k) => !k.isAnchor).length;
+    const reduction = contentPadding / nonAnchors;
+    const shifted = keylineListWithPivot(containerSize, gap, pivotIdx, pivot.offset - reduction / 2 + contentPadding, from.map((k) => ({ size: k.size - Math.abs(reduction), isAnchor: k.isAnchor })));
+    return shifted.map((k, i) => ({ ...k, unadjustedOffset: from[i].unadjustedOffset }));
+};
+const moveKeyline = (from, srcIndex, dstIndex, containerSize, gap) => {
+    const dir = srcIndex > dstIndex ? 1 : -1;
+    const src = from[srcIndex];
+    const delta = (src.size - src.cutoff + gap) * dir;
+    const pivot = from[pivotIndex(from)];
+    const moved = from.slice();
+    moved.splice(srcIndex, 1);
+    moved.splice(dstIndex, 0, src);
+    return keylineListWithPivot(containerSize, gap, pivotIndex(from) + dir, pivot.offset + delta, moved.map((k) => ({ size: k.size, isAnchor: k.isAnchor })));
+};
+const startSteps = (defaults, containerSize, gap, beforePadding) => {
+    if (defaults.length === 0)
+        return [];
+    const steps = [defaults];
+    if (isFirstFocalItemAtStartOfContainer(defaults)) {
+        if (beforePadding !== 0) {
+            steps.push(shiftedForContentPadding(defaults, containerSize, gap, beforePadding, defaults[firstFocalIndex(defaults)], firstFocalIndex(defaults)));
+        }
+        return steps;
+    }
+    const startIndex = firstNonAnchorIndex(defaults);
+    const endIndex = firstFocalIndex(defaults);
+    const numberOfSteps = endIndex - startIndex;
+    if (numberOfSteps <= 0 && defaults[firstFocalIndex(defaults)].cutoff > 0) {
+        steps.push(moveKeyline(defaults, 0, 0, containerSize, gap));
+        return steps;
+    }
+    for (let i = 0; i < numberOfSteps; i++) {
+        const prev = steps[steps.length - 1];
+        const originalIndex = startIndex + i;
+        let dstIndex = defaults.length - 1;
+        if (originalIndex > 0) {
+            const neighbourSize = defaults[originalIndex - 1].size;
+            dstIndex = firstIndexAfterFocalRangeWithSize(prev, neighbourSize) - 1;
+        }
+        steps.push(moveKeyline(prev, firstNonAnchorIndex(defaults), dstIndex, containerSize, gap));
+    }
+    if (beforePadding !== 0) {
+        const last = steps[steps.length - 1];
+        steps[steps.length - 1] = shiftedForContentPadding(last, containerSize, gap, beforePadding, last[firstFocalIndex(last)], firstFocalIndex(last));
+    }
+    return steps;
+};
+const endSteps = (defaults, containerSize, gap, afterPadding) => {
+    if (defaults.length === 0)
+        return [];
+    const steps = [defaults];
+    if (isLastFocalItemAtEndOfContainer(defaults, containerSize)) {
+        if (afterPadding !== 0) {
+            steps.push(shiftedForContentPadding(defaults, containerSize, gap, -afterPadding, defaults[lastFocalIndex(defaults)], lastFocalIndex(defaults)));
+        }
+        return steps;
+    }
+    const startIndex = lastFocalIndex(defaults);
+    const endIndex = lastNonAnchorIndex(defaults);
+    const numberOfSteps = endIndex - startIndex;
+    if (numberOfSteps <= 0 && defaults[lastFocalIndex(defaults)].cutoff > 0) {
+        steps.push(moveKeyline(defaults, 0, 0, containerSize, gap));
+        return steps;
+    }
+    for (let i = 0; i < numberOfSteps; i++) {
+        const prev = steps[steps.length - 1];
+        const originalIndex = endIndex - i;
+        let dstIndex = 0;
+        if (originalIndex < defaults.length - 1) {
+            const neighbourSize = defaults[originalIndex + 1].size;
+            dstIndex = lastIndexBeforeFocalRangeWithSize(prev, neighbourSize) + 1;
+        }
+        steps.push(moveKeyline(prev, lastNonAnchorIndex(defaults), dstIndex, containerSize, gap));
+    }
+    if (afterPadding !== 0) {
+        const last = steps[steps.length - 1];
+        steps[steps.length - 1] = shiftedForContentPadding(last, containerSize, gap, -afterPadding, last[lastFocalIndex(last)], lastFocalIndex(last));
+    }
+    return steps;
+};
+const stepInterpolationPoints = (totalShift, steps, shiftingLeft) => {
+    const points = [0];
+    if (totalShift === 0 || steps.length === 0)
+        return points;
+    for (let i = 1; i < steps.length; i++) {
+        const prev = steps[i - 1];
+        const curr = steps[i];
+        const shifted = shiftingLeft
+            ? curr[0].unadjustedOffset - prev[0].unadjustedOffset
+            : prev[prev.length - 1].unadjustedOffset - curr[curr.length - 1].unadjustedOffset;
+        const point = i === steps.length - 1 ? 1 : points[i - 1] + shifted / totalShift;
+        points.push(point);
+    }
+    return points;
+};
+export const createStrategy = (defaultKeylines, availableSpace, gap, beforePadding, afterPadding) => {
+    const starts = startSteps(defaultKeylines, availableSpace, gap, beforePadding);
+    const ends = endSteps(defaultKeylines, availableSpace, gap, afterPadding);
+    const itemSize = defaultKeylines.length ? defaultKeylines[firstFocalIndex(defaultKeylines)].size : 0;
+    const startShiftDistance = starts.length
+        ? Math.max(starts[starts.length - 1][0].unadjustedOffset - starts[0][0].unadjustedOffset, beforePadding)
+        : 0;
+    const endShiftDistance = ends.length
+        ? Math.max(ends[0][ends[0].length - 1].unadjustedOffset - ends[ends.length - 1][ends[ends.length - 1].length - 1].unadjustedOffset, afterPadding)
+        : 0;
+    let min = defaultKeylines.length ? minSize(defaultKeylines) : 0;
+    let max = defaultKeylines.length ? maxSize(defaultKeylines) : 0;
+    for (const step of [...starts, ...ends]) {
+        min = Math.min(min, minSize(step));
+        max = Math.max(max, maxSize(step));
+    }
+    return {
+        defaultKeylines,
+        startSteps: starts,
+        endSteps: ends,
+        availableSpace,
+        gap,
+        beforePadding,
+        afterPadding,
+        itemSize,
+        minItemSize: min,
+        maxItemSize: max,
+        valid: defaultKeylines.length > 0 && availableSpace !== 0 && itemSize !== 0,
+        startShiftDistance,
+        endShiftDistance,
+        startShiftPoints: stepInterpolationPoints(startShiftDistance, starts, true),
+        endShiftPoints: stepInterpolationPoints(endShiftDistance, ends, false),
+    };
+};
+export const keylinesForScrollOffset = (s, scrollOffset, maxScrollOffset, roundToNearestStep = false) => {
+    const positive = Math.max(0, scrollOffset);
+    const startShiftOffset = s.startShiftDistance;
+    const endShiftOffset = Math.max(0, maxScrollOffset - s.endShiftDistance);
+    if (positive >= startShiftOffset && positive <= endShiftOffset)
+        return s.defaultKeylines;
+    let interpolation = clampLerp(1, 0, 0, startShiftOffset, positive);
+    let points = s.startShiftPoints;
+    let steps = s.startSteps;
+    if (positive > endShiftOffset) {
+        interpolation = clampLerp(0, 1, endShiftOffset, maxScrollOffset, positive);
+        points = s.endShiftPoints;
+        steps = s.endSteps;
+        if (endShiftOffset < 0.01 && s.startSteps.length === 2 && s.endSteps.length === 2) {
+            steps = [s.startSteps[1], s.endSteps[1]];
+        }
+    }
+    let fromStep = 0;
+    let toStep = 0;
+    let stepped = 0;
+    let lower = points[0];
+    for (let i = 1; i < steps.length; i++) {
+        const upper = points[i];
+        if (interpolation <= upper) {
+            fromStep = i - 1;
+            toStep = i;
+            stepped = clampLerp(0, 1, lower, upper, interpolation);
+            break;
+        }
+        lower = upper;
+    }
+    if (roundToNearestStep)
+        return steps[Math.round(stepped) === 0 ? fromStep : toStep];
+    return lerpKeylineList(steps[fromStep], steps[toStep], stepped);
+};
+export const snapPositionOffset = (s, index, count) => {
+    if (!s.valid)
+        return 0;
+    const focalStart = (list) => list[firstFocalIndex(list)].unadjustedOffset - s.itemSize / 2;
+    const focalEnd = (list) => list[lastFocalIndex(list)].unadjustedOffset - s.itemSize / 2;
+    let offset = Math.round(focalStart(s.defaultKeylines));
+    const lastStart = s.startSteps.length - 1;
+    if (index <= lastStart) {
+        const step = Math.min(Math.max(lastStart - index, 0), lastStart);
+        offset = Math.round(focalStart(s.startSteps[step]));
+    }
+    const lastEnd = s.endSteps.length - 1;
+    const lastItem = count - 1;
+    if (index >= lastItem - lastEnd && count > focalCount(s.defaultKeylines)) {
+        const step = Math.min(Math.max(lastEnd - (lastItem - index), 0), lastEnd);
+        offset = Math.round(focalEnd(s.endSteps[step]));
+    }
+    return offset;
+};
+export const maxScrollOffset = (s, count) => Math.max(0, s.itemSize * count + s.gap * (count - 1) - s.availableSpace);
+export const placeItem = (s, keylines, index, scrollOffset) => {
+    const unit = s.itemSize + s.gap;
+    const unadjustedCenter = index * unit + s.itemSize / 2 - scrollOffset;
+    const before = keylineBefore(keylines, unadjustedCenter);
+    const after = keylineAfter(keylines, unadjustedCenter);
+    const progress = before === after ? 1 : (unadjustedCenter - before.unadjustedOffset) / (after.unadjustedOffset - before.unadjustedOffset);
+    const keyline = lerpKeyline(before, after, progress);
+    let center = keyline.offset;
+    if (before === after) {
+        center += (unadjustedCenter - keyline.unadjustedOffset) / keyline.size;
+    }
+    return { size: keyline.size, center, keyline };
+};

package/dist/components/carousel/types.d.ts

@@ -0,0 +1,94 @@
+import type { ForwardedEventPayload } from "../../core/dom/index.js";
+/** Current item reported by programmatic navigation or native scrolling. */
+export interface CarouselChangePayload {
+    /** The current item's index, as `getValue()` returns it; every model event carries it (FLO-380) */
+    value: number;
+}
+/** Events emitted by the scroll feature and forwarded from the root. */
+export interface CarouselEvents {
+    change: (payload: CarouselChangePayload) => void;
+    focus: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
+    blur: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
+}
+export type CarouselVariant = "multi-browse" | "uncontained" | "hero" | "hero-center" | "full-screen";
+/**
+ * Content of one carousel item. Either an image with optional text and a
+ * call to action, or arbitrary content.
+ */
+export interface CarouselSlide {
+    image?: string;
+    /** Alternative text for the image; empty when the image is decorative */
+    alt?: string;
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    buttonUrl?: string;
+    /** Custom content, replaces the image and text */
+    content?: HTMLElement | string;
+}
+export interface CarouselConfig {
+    /** Layout, "multi-browse" by default */
+    variant?: CarouselVariant;
+    slides?: CarouselSlide[];
+    /**
+     * Width of a large item in px. Multi-browse and uncontained layouts
+     * treat it as the preferred width, hero layouts as a maximum (the
+     * container width by default).
+     */
+    itemWidth?: number;
+    /** Space between items, 8 by default (16 for full-screen) */
+    gap?: number;
+    /** Space between the container edges and the items, 16 by default (0 for full-screen) */
+    padding?: number;
+    /** Corner radius of the items, 28 by default */
+    cornerRadius?: number;
+    /** Snap to items after scrolling; on by default except for uncontained layouts */
+    snap?: boolean;
+    /**
+     * Scroll horizontal carousels with a vertical mouse wheel; false by default.
+     * Normalized deltas accumulate per gesture and glide to directional snap points.
+     * One notch advances at least one item; momentum can pass several whole items.
+     * At either edge the page scrolls.
+     * Horizontal trackpad gestures, zoom and vertical layouts stay native.
+     */
+    wheel?: boolean;
+    initialSlide?: number;
+    minSmallItemWidth?: number;
+    maxSmallItemWidth?: number;
+    /** Accessible name of the carousel */
+    ariaLabel?: string;
+    prefix?: string;
+    componentName?: string;
+    class?: string;
+}
+export interface CarouselComponent {
+    element: HTMLElement;
+    slides: SlidesAPI;
+    lifecycle: {
+        destroy: () => void;
+    };
+    getClass: (name: string) => string;
+    next: () => CarouselComponent;
+    prev: () => CarouselComponent;
+    goTo: (index: number) => CarouselComponent;
+    getCurrentSlide: () => number;
+    /** Reads the current model value without changing selection. */
+    getValue: () => number;
+    getVariant: () => CarouselVariant;
+    /** Enable or disable vertical mouse wheel scrolling in place. */
+    setWheel: (on: boolean) => CarouselComponent;
+    addSlide: (slide: CarouselSlide, index?: number) => CarouselComponent;
+    removeSlide: (index: number) => CarouselComponent;
+    destroy: () => void;
+    on: <K extends keyof CarouselEvents>(event: K, handler: CarouselEvents[K]) => CarouselComponent;
+    off: <K extends keyof CarouselEvents>(event: K, handler: CarouselEvents[K]) => CarouselComponent;
+    addClass: (...classes: string[]) => CarouselComponent;
+}
+export interface SlidesAPI {
+    addSlide: (slide: CarouselSlide, index?: number) => SlidesAPI;
+    removeSlide: (index: number) => SlidesAPI;
+    updateSlide: (index: number, slide: CarouselSlide) => SlidesAPI;
+    getSlide: (index: number) => CarouselSlide | null;
+    getCount: () => number;
+    getElements: () => HTMLElement[];
+}

package/dist/components/carousel/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/checkbox/api.d.ts

@@ -0,0 +1,7 @@
+import type { BaseComponent, CheckboxComponent, ApiOptions } from "./types.js";
+/**
+ * Enhances checkbox component with API methods
+ * @param {ApiOptions} options - API configuration
+ * @returns {Function} Higher-order function that adds API methods to component
+ */
+export declare const withAPI: ({ disabled, lifecycle, checkable }: ApiOptions) => (component: BaseComponent) => CheckboxComponent;