@noxlovette/material 0.5.1 → 0.6.1

package/dist/components/containers/bottom-sheet/types.d.ts

@@ -1,13 +1,24 @@
 import type { Snippet } from 'svelte';
+/** Why a modal bottom sheet dismissed itself. */
+export type BottomSheetCloseReason = 'esc' | 'scrim' | 'drag' | 'handle';
 /**
  * Props for the BottomSheet component.
  */
 export interface BottomSheetProps {
     /**
-     * The content to be rendered inside the bottom sheet.
-     * Typically includes a list of actions or supplementary information.
+     * The content to be rendered inside the bottom sheet, below the drag handle. It scrolls inside
+     * the sheet once the sheet reaches its maximum height. Pad it yourself (M3 content usually sits
+     * 16–24dp from the edges); lists and menu items can run edge to edge.
      */
     children: Snippet;
+    /**
+     * - `modal`: in front of the app above a scrim, blocking everything else until it's dismissed
+     *   (drag it down, tap the scrim, press Esc, or activate the drag handle).
+     * - `standard`: supplementary content that leaves the rest of the screen usable, such as an
+     *   audio player. No scrim; it collapses to `peekHeight` instead of dismissing.
+     * @default 'modal'
+     */
+    variant?: 'modal' | 'standard';
     /**
      * Whether the sheet is shown. Bind it (`bind:open`) so the sheet can play its exit animation
      * before unmounting.
@@ -15,8 +26,29 @@ export interface BottomSheetProps {
      */
     open?: boolean;
     /**
-     * Called when the user dismisses the sheet.
-     * @param reason The reason for closing ('esc' key, 'click' outside, or 'low' drag height).
+     * Standard sheets only: whether the sheet is expanded to its full height, or collapsed to
+     * `peekHeight`. Dragging the handle or activating it changes this; bind it to follow along.
+     * @default true
+     */
+    expanded?: boolean;
+    /**
+     * Standard sheets only: how much of the sheet stays visible when collapsed, in px. Include the
+     * 48dp drag handle area.
+     * @default 112
+     */
+    peekHeight?: number;
+    /**
+     * The sheet's accessible name, e.g. "Share". Give one whenever the sheet has no visible
+     * heading that you point to with `aria-labelledby`.
+     */
+    label?: string;
+    /** Hides the drag handle. Only for sheets that can't be resized or dismissed by dragging. */
+    hideHandle?: boolean;
+    /**
+     * Called when a modal sheet dismisses itself.
+     * @param reason `esc`, a `scrim` click, a downward `drag`, or activating the drag `handle`.
      */
-    close?: (reason: 'esc' | 'click' | 'low') => void;
+    close?: (reason: BottomSheetCloseReason) => void;
+    class?: string;
+    'aria-labelledby'?: string;
 }

package/dist/components/containers/carousel/Carousel.mdx

@@ -0,0 +1,80 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as CarouselStories from './Carousel.stories.svelte';
+
+<Meta of={CarouselStories} />
+
+<Title />
+
+<Subtitle>
+  Carousels show a collection of items that can be scrolled on and off the screen.
+</Subtitle>
+
+[M3 spec](https://m3.material.io/components/carousel/specs) ·
+`import { Carousel } from '@noxlovette/material';`
+
+<Canvas of={CarouselStories.Playground} />
+
+<Controls of={CarouselStories.Playground} />
+
+## Choosing a layout
+
+| Layout         | Items                                                       | Use for                                              |
+| -------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
+| `multiBrowse`  | Large, medium and small at once; they resize as they scroll | Browsing many items: albums, photos, products        |
+| `hero`         | One large item and a small one peeking                      | Spotlighting one item at a time, with a hint of more |
+| `centeredHero` | One large item centred between two small ones               | The same, symmetric                                  |
+| `uncontained`  | Fixed widths that run off the trailing edge; no snapping    | Items that shouldn't resize, e.g. cards with text    |
+| `fullScreen`   | One edge-to-edge item, scrolling vertically                 | Immersive media, one item per screen                 |
+
+Give `uncontained` an `itemWidth` function for mixed aspect ratios.
+
+<Canvas of={CarouselStories.Hero} />
+
+<Canvas of={CarouselStories.UncontainedMultiAspect} />
+
+## Sizing
+
+The carousel fills its container's width. Set its height with a class; it defaults to `h-56`.
+
+- **Multi-browse** takes `itemWidth` as the preferred large width (186 by default). It then fits
+  as many whole large items as it can, plus a medium and a small one.
+- **Small items** are 40–56dp. They are 56dp once the carousel is at least 392px wide.
+- Items keep 28dp corners and 8dp gaps. Multi-browse and hero keep 16dp padding on both sides.
+
+## Item content
+
+The `item` snippet fills each item, so use `object-cover` media. It also gets `progress`, which
+runs from 0 when the item is small to 1 when it's large. Fade titles and other secondary content
+with it, since text belongs on large items only.
+
+Item content keeps the large width and stays centred while the item narrows, which gives the
+parallax.
+
+```svelte
+<Carousel items={albums} label="Recently played">
+  {#snippet item(album, { progress })}
+    <img src={album.cover} alt="" class="h-full w-full object-cover" />
+    <span style:opacity={progress}>{album.title}</span>
+  {/snippet}
+</Carousel>
+```
+
+## Interaction and accessibility
+
+- `label` names the carousel (`role="region"`, `aria-roledescription="carousel"`). It's required.
+- `onitemclick` makes items buttons and `itemHref` makes them links. `itemLabel` names each item;
+  it defaults to "n of total". A tapped item opening into its detail is a
+  [container transform](?path=/story/motion-transition-patterns--container-transform) that the app applies.
+- Tab reaches every item, including ones scrolled out of view. Focusing an item scrolls it into
+  the large slot. When items aren't interactive, the carousel itself takes focus so arrow keys
+  can scroll it.
+- Touch and trackpads scroll natively. A mouse can drag to scroll, and a drag doesn't count as
+  a click.
+- Before the carousel is measured, including during SSR, keyline layouts render as an
+  uncontained row.
+
+<Canvas of={CarouselStories.OutlinedAndDisabled} />
+
+## Not yet supported
+
+Right-to-left layouts.

package/dist/components/containers/carousel/Carousel.stories.svelte

@@ -0,0 +1,131 @@
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Carousel from './Carousel.svelte';
+
+  const { Story } = defineMeta({
+    title: 'Containers/Carousel',
+    component: Carousel,
+    argTypes: {
+      layout: {
+        control: 'select',
+        options: ['multiBrowse', 'hero', 'centeredHero', 'uncontained', 'fullScreen']
+      },
+      itemWidth: { control: 'number' },
+      snap: { control: 'boolean' },
+      outlined: { control: 'boolean' }
+    },
+    args: { layout: 'multiBrowse', itemWidth: 186, outlined: false }
+  });
+
+  type Photo = { title: string; from: string; to: string; ratio: number };
+
+  const tones = ['primary', 'secondary', 'tertiary'];
+  const photos: Photo[] = [
+    'Coast',
+    'Harbour',
+    'Dunes',
+    'Forest',
+    'Glacier',
+    'Canyon',
+    'Meadow',
+    'Reef',
+    'Summit',
+    'Delta'
+  ].map((title, i) => ({
+    title,
+    from: `var(--color-md-sys-color-${tones[i % 3]})`,
+    to: `var(--color-md-sys-color-${tones[(i + 1) % 3]}-container)`,
+    ratio: [16 / 9, 9 / 16, 1, 3 / 4][i % 4]
+  }));
+</script>
+
+<script lang="ts">
+  let opened = $state('');
+</script>
+
+{#snippet photo(p: Photo, { progress }: { index: number; progress: number })}
+  <div
+    class="p-spacing-200 flex h-full w-full items-end"
+    style="background: linear-gradient(135deg, {p.from}, {p.to})"
+  >
+    <span
+      class="md-sys-typescale-title-medium text-md-sys-color-on-primary"
+      style="opacity: {progress}">{p.title}</span
+    >
+  </div>
+{/snippet}
+
+<Story name="Playground">
+  {#snippet template(args)}
+    <div class="w-full max-w-xl">
+      <Carousel
+        items={photos}
+        item={photo}
+        label="Places"
+        layout={args.layout}
+        itemWidth={args.itemWidth}
+        snap={args.snap}
+        outlined={args.outlined}
+        class={args.layout === 'fullScreen' ? 'h-[32rem]' : undefined}
+      />
+    </div>
+  {/snippet}
+</Story>
+
+<Story name="Multi-browse" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel items={photos} item={photo} label="Places" onitemclick={(p) => (opened = p.title)} />
+    <p class="md-sys-typescale-body-medium mt-spacing-100 px-spacing-200">
+      {opened ? `Opened ${opened}` : 'Tap an item. Drag with the mouse, or Tab through the items.'}
+    </p>
+  </div>
+</Story>
+
+<Story name="Hero" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel items={photos} item={photo} label="Places" layout="hero" class="h-72" />
+  </div>
+</Story>
+
+<Story name="Centered hero" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel items={photos} item={photo} label="Places" layout="centeredHero" class="h-72" />
+  </div>
+</Story>
+
+<Story name="Uncontained" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel items={photos} item={photo} label="Places" layout="uncontained" />
+  </div>
+</Story>
+
+<Story name="Uncontained multi-aspect" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel
+      items={photos}
+      item={photo}
+      label="Places"
+      layout="uncontained"
+      itemWidth={(p) => Math.round(208 * p.ratio)}
+    />
+  </div>
+</Story>
+
+<Story name="Full-screen" asChild>
+  <div class="h-[36rem] w-80">
+    <Carousel items={photos} item={photo} label="Places" layout="fullScreen" class="h-full" />
+  </div>
+</Story>
+
+<Story name="Outlined and disabled" asChild>
+  <div class="w-full max-w-xl">
+    <Carousel
+      items={photos}
+      item={photo}
+      label="Places"
+      outlined
+      itemHref={() => '#'}
+      itemDisabled={(_, i) => i === 1}
+    />
+  </div>
+</Story>

package/dist/components/containers/carousel/Carousel.stories.svelte.d.ts

@@ -0,0 +1,4 @@
+import Carousel from './Carousel.svelte';
+declare const Carousel: import("svelte").Component<Record<string, never>, {}, "">;
+type Carousel = ReturnType<typeof Carousel>;
+export default Carousel;

package/dist/components/containers/carousel/Carousel.svelte

@@ -0,0 +1,194 @@
+<script lang="ts" generics="T">
+  import { Layer } from '../../../utils/index.js';
+  import clsx from 'clsx';
+  import { carousel } from './theme.js';
+  import { keylines, maxSteps, place, type KeylineLayout } from './keylines.js';
+  import type { CarouselProps } from './types.js';
+
+  let {
+    items,
+    item,
+    label,
+    layout = 'multiBrowse',
+    itemWidth,
+    snap = layout !== 'uncontained',
+    outlined = false,
+    onitemclick,
+    itemHref,
+    itemLabel = (_, i) => `${i + 1} of ${items.length}`,
+    itemDisabled,
+    class: className,
+    ...restProps
+  }: CarouselProps<T> = $props();
+
+  let scroller = $state<HTMLElement>();
+  let width = $state(0);
+  let scrollLeft = $state(0);
+
+  const isKeyline = $derived(
+    layout === 'multiBrowse' || layout === 'hero' || layout === 'centeredHero'
+  );
+  // Keyline layouts need the container width; until it's measured (and during SSR) they render
+  // as a plain uncontained row.
+  const k = $derived(
+    isKeyline && width > 0
+      ? keylines(
+          layout as KeylineLayout,
+          width - 32,
+          typeof itemWidth === 'number' ? itemWidth : undefined
+        )
+      : null
+  );
+  /** Scroll position in steps (one step moves an item by one slot). */
+  const f = $derived(k ? scrollLeft / k.step : 0);
+  const steps = $derived(k ? maxSteps(k, items.length) : 0);
+  const placements = $derived(k ? place(k, items.length, f) : []);
+  const vertical = $derived(layout === 'fullScreen');
+
+  const cls = $derived(
+    carousel({
+      layout: k || !isKeyline ? layout : 'uncontained',
+      keyline: !!k,
+      snap: snap && !vertical,
+      outlined,
+      interactive: !!onitemclick || !!itemHref
+    })
+  );
+
+  const widthOf = (data: T, i: number) =>
+    typeof itemWidth === 'function' ? itemWidth(data, i) : (itemWidth ?? (isKeyline ? 186 : 240));
+
+  function itemStyle(data: T, i: number): string {
+    if (vertical) return '';
+    if (!k) return `width:${widthOf(data, i)}px`;
+    const p = placements[i];
+    // Items outside the container stay in the DOM, parked just past either edge, so Tab still
+    // reaches them; focusing one scrolls it into a large slot.
+    const firstShown = placements.findIndex((q) => q !== null);
+    const x = p ? p.x : i < firstShown ? -(k.large + 64) : width;
+    return `width:${p ? p.size : k.small}px;transform:translateX(${x}px)`;
+  }
+
+  const progressOf = (i: number) => {
+    const p = placements[i];
+    if (!k || !p) return k ? 0 : 1;
+    return Math.min(1, Math.max(0, (p.size - k.small) / (k.large - k.small)));
+  };
+
+  function onscroll() {
+    if (scroller) scrollLeft = scroller.scrollLeft;
+  }
+
+  const reducedMotion = () => matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  function onfocusin(e: FocusEvent) {
+    if (!k || !scroller) return;
+    const el = (e.target as Element).closest<HTMLElement>('[data-index]');
+    if (!el) return;
+    const target = Math.min(steps, Math.max(0, Number(el.dataset.index) - k.focalIndex));
+    if (Math.abs(target - f) < 0.01) return;
+    scroller.scrollTo({ left: target * k.step, behavior: reducedMotion() ? 'auto' : 'smooth' });
+  }
+
+  // Mouse drag to scroll: touch and trackpads scroll natively, a mouse wheel only scrolls
+  // vertically. Snapping is paused while dragging and resumes (and settles) on release.
+  let dragged = false;
+  function onpointerdown(e: PointerEvent) {
+    if (e.pointerType !== 'mouse' || e.button !== 0 || !scroller) return;
+    const el = scroller;
+    const start = vertical ? e.clientY : e.clientX;
+    const startScroll = vertical ? el.scrollTop : el.scrollLeft;
+    dragged = false;
+
+    const move = (ev: PointerEvent) => {
+      const delta = (vertical ? ev.clientY : ev.clientX) - start;
+      if (!dragged && Math.abs(delta) < 4) return;
+      dragged = true;
+      el.style.scrollSnapType = 'none';
+      if (vertical) el.scrollTop = startScroll - delta;
+      else el.scrollLeft = startScroll - delta;
+    };
+    const up = () => {
+      el.style.scrollSnapType = '';
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  }
+
+  function onclickcapture(e: MouseEvent) {
+    // A drag that ends over an item isn't a tap on it.
+    if (dragged) {
+      e.preventDefault();
+      e.stopPropagation();
+      dragged = false;
+    }
+  }
+</script>
+
+{#snippet itemEl(data: T, i: number)}
+  {@const disabled = itemDisabled?.(data, i) ?? false}
+  {@const href = itemHref?.(data, i)}
+  {@const tag = href ? 'a' : onitemclick ? 'button' : 'div'}
+  <svelte:element
+    this={tag}
+    class={cls.item({ disabled })}
+    style={itemStyle(data, i)}
+    data-index={i}
+    href={href && !disabled ? href : undefined}
+    type={tag === 'button' ? 'button' : undefined}
+    disabled={tag === 'button' ? disabled : undefined}
+    aria-disabled={tag !== 'button' && disabled ? true : undefined}
+    role={tag === 'div' ? 'group' : undefined}
+    aria-roledescription={tag === 'div' ? 'slide' : undefined}
+    aria-label={itemLabel(data, i)}
+    onclick={onitemclick && !disabled ? () => onitemclick(data, i) : undefined}
+  >
+    {#if tag !== 'div' && !disabled}
+      <Layer />
+    {/if}
+    <div class={cls.content()} style={k ? `width:${k.large}px` : undefined}>
+      {@render item(data, { index: i, progress: progressOf(i) })}
+    </div>
+  </svelte:element>
+{/snippet}
+
+<div
+  class={cls.base({ class: clsx(className) })}
+  role="region"
+  aria-roledescription="carousel"
+  aria-label={label}
+  {...restProps}
+>
+  <!-- The scroller is a scroll container, focusable only when no item is (arrow keys scroll it). -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_static_element_interactions -->
+  <div
+    bind:this={scroller}
+    bind:clientWidth={width}
+    class={cls.scroller()}
+    tabindex={onitemclick || itemHref ? undefined : 0}
+    {onscroll}
+    {onfocusin}
+    {onpointerdown}
+    {onclickcapture}
+    ondragstart={(e) => e.preventDefault()}
+  >
+    {#if k}
+      <div class={cls.track()} style="width:{width + steps * k.step}px">
+        {#each { length: steps + 1 } as _, s (s)}
+          <div class={cls.snapPoint()} style="left:{s * k.step}px"></div>
+        {/each}
+        <div class={cls.viewport()} style="width:{width}px">
+          {#each items as data, i (i)}
+            {@render itemEl(data, i)}
+          {/each}
+        </div>
+      </div>
+    {:else}
+      {#each items as data, i (i)}
+        {@render itemEl(data, i)}
+      {/each}
+    {/if}
+  </div>
+</div>

package/dist/components/containers/carousel/Carousel.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { CarouselProps } from './types.js';
+declare function $$render<T>(): {
+    props: CarouselProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Carousel: $$IsomorphicComponent;
+type Carousel<T> = InstanceType<typeof Carousel<T>>;
+export default Carousel;

package/dist/components/containers/carousel/index.d.ts

@@ -0,0 +1,3 @@
+export * from './theme.js';
+export * from './types.js';
+export { default as Carousel } from './Carousel.svelte';

package/dist/components/containers/{stack → carousel}/index.js

@@ -3,5 +3,4 @@
 export * from './theme.js';
 export * from './types.js';
 // default exports for components in this folder
-export { default as HStack } from './HStack.svelte';
-export { default as VStack } from './VStack.svelte';
+export { default as Carousel } from './Carousel.svelte';

package/dist/components/containers/carousel/keylines.d.ts

@@ -0,0 +1,32 @@
+export declare const GAP = 8;
+export declare const SMALL_MIN = 40;
+export declare const SMALL_MAX = 56;
+export type KeylineLayout = 'multiBrowse' | 'hero' | 'centeredHero';
+export type Keylines = {
+    /** Large item width: the unmasked width of every item's content. */
+    large: number;
+    small: number;
+    /** Scroll distance that moves an item by one slot. */
+    step: number;
+    start: number[];
+    focal: number[];
+    end: number[];
+    /** Slot of the first large item in `focal`: where a focused item scrolls to. */
+    focalIndex: number;
+};
+/**
+ * Fits the slots for `layout` into `available` px (container width minus its 16dp padding).
+ * `preferredLarge` is the multi-browse large width to aim for.
+ */
+export declare function keylines(layout: KeylineLayout, available: number, preferredLarge?: number): Keylines;
+export type Placement = {
+    x: number;
+    size: number;
+};
+/**
+ * Where each of `count` items sits at scroll position `f` (in steps). Items outside the container
+ * get `null`. `x` is relative to the container's inner (padded) edge.
+ */
+export declare function place(k: Keylines, count: number, f: number): (Placement | null)[];
+/** Scroll positions (in steps) the carousel can come to rest at. */
+export declare const maxSteps: (k: Keylines, count: number) => number;

package/dist/components/containers/carousel/keylines.js

@@ -0,0 +1,88 @@
+/*
+  Keyline layout for the M3 carousel (https://m3.material.io/components/carousel/specs), after
+  Material Components' carousel (KeylineState / MultiBrowseCarouselStrategy).
+
+  A layout is a row of slot sizes that fills the container, e.g. multi-browse [L, L, M, S]. Scrolling
+  moves items through the slots one "step" (large width + gap) at a time; an item between two slots
+  takes an interpolated size, and items stack edge to edge with the gap between them. An item
+  leaving either end shrinks to the small size. The slot row itself also morphs: `start` at the
+  beginning of the scroll, `focal` in the middle, `end` at the end, so the last items become large.
+*/
+export const GAP = 8;
+export const SMALL_MIN = 40;
+export const SMALL_MAX = 56;
+const repeat = (n, v) => Array.from({ length: n }, () => v);
+/**
+ * Fits the slots for `layout` into `available` px (container width minus its 16dp padding).
+ * `preferredLarge` is the multi-browse large width to aim for.
+ */
+export function keylines(layout, available, preferredLarge = 186) {
+    const small = available >= 360 ? SMALL_MAX : SMALL_MIN;
+    const make = (large, start, focal, end, focalIndex = 0) => ({
+        large,
+        small,
+        step: large + GAP,
+        start,
+        focal,
+        end,
+        focalIndex
+    });
+    if (layout === 'hero') {
+        const L = Math.max(small, available - small - GAP);
+        return make(L, [L, small], [L, small], [small, L]);
+    }
+    if (layout === 'centeredHero') {
+        const L = Math.max(small, available - 2 * small - 2 * GAP);
+        return make(L, [L, small, small], [small, L, small], [small, small, L], 1);
+    }
+    // Multi-browse: n large + one medium + one small; the medium sits halfway between the two.
+    let best = { n: 1, L: 0, cost: Infinity };
+    for (let n = 1; n <= 8; n++) {
+        const L = (available - (n + 1) * GAP - small * 1.5) / (n + 0.5);
+        if (L <= small * 1.5)
+            break;
+        const cost = Math.abs(L - preferredLarge);
+        if (cost < best.cost)
+            best = { n, L, cost };
+    }
+    if (!Number.isFinite(best.cost))
+        return keylines('hero', available);
+    const { n, L } = best;
+    const M = (L + small) / 2;
+    const focal = [...repeat(n, L), M, small];
+    return make(L, focal, focal, [small, M, ...repeat(n, L)]);
+}
+const lerp = (a, b, t) => a + (b - a) * t;
+const clamp01 = (t) => Math.min(1, Math.max(0, t));
+/**
+ * Where each of `count` items sits at scroll position `f` (in steps). Items outside the container
+ * get `null`. `x` is relative to the container's inner (padded) edge.
+ */
+export function place(k, count, f) {
+    const V = k.focal.length;
+    const maxF = Math.max(0, count - V);
+    f = Math.min(maxF, Math.max(0, f));
+    // How far the slots morph from `start` into `focal`, then from `focal` into `end`.
+    const endSpan = Math.min(V - 1 - k.focal.lastIndexOf(k.large), maxF);
+    const startSpan = Math.min(k.focal.indexOf(k.large), maxF - endSpan);
+    const wStart = startSpan > 0 ? clamp01(f / startSpan) : 1;
+    const wEnd = endSpan > 0 ? clamp01((f - (maxF - endSpan)) / endSpan) : 0;
+    const slots = k.focal.map((s, i) => lerp(lerp(k.start[i], s, wStart), k.end[i], wEnd));
+    const sizeAt = (r) => {
+        if (r < 0)
+            return lerp(slots[0], k.small, -r);
+        const i = Math.floor(r);
+        return lerp(slots[i], i + 1 < V ? slots[i + 1] : k.small, r - i);
+    };
+    const out = Array.from({ length: count }, () => null);
+    const first = Math.floor(f);
+    let x = (first - f) * (k.small + GAP);
+    for (let i = first; i < count && i - f < V; i++) {
+        const size = sizeAt(i - f);
+        out[i] = { x, size };
+        x += size + GAP;
+    }
+    return out;
+}
+/** Scroll positions (in steps) the carousel can come to rest at. */
+export const maxSteps = (k, count) => Math.max(0, count - k.focal.length);