feat(carousel): add hasLoop wrap-around and handleRef imperative control

[freddymeta]

Summary

Adds two capabilities to Carousel, both re-expressed in terms of its existing native-scroll machinery (no scroll engine introduced):

hasLoop?: boolean (default false)

Wrap-around scrolling. Pressing Next at the end returns to the start, and Prev at the start jumps to the end — for both the built-in navigation buttons and the imperative handle. The buttons stay active at both edges instead of hiding, since a scroll is always available. Only engages when the content actually overflows (a single-screen carousel is a no-op).

handleRef?: React.Ref<CarouselHandle>

An imperative handle for programmatic scroll control, following the established handleRef + {Name}Handle convention used by Tokenizer, Calendar, PowerSearch, and others (keeps the DOM ref intact).

interface CarouselHandle {
  scrollNext(): void;
  scrollPrev(): void;
  scrollTo(index: number): void;   // scrolls the item to the start edge; clamped
  canScrollNext(): boolean;        // live state
  canScrollPrev(): boolean;
}

const carousel = useRef<CarouselHandle>(null);

<Carousel handleRef={carousel} hasSnap hasButtons={false}>
  {items.map(i => <Card key={i.id} {...i} />)}
</Carousel>
<Button label="Next" onClick={() => carousel.current?.scrollNext()} />

Design notes

• Wrap-around, not clone-based infinite. hasLoop implements bounded wrap-around by overshooting toward the opposite edge and letting the browser clamp — the honest native-scroll equivalent of a looping carousel. Clone-based seamless infinite scrolling is intentionally out of scope; the prop is forward-compatible with a future 'infinite' mode if it's ever needed.
• canScroll* are methods, not getters. Matching how other handles expose reads (getValue(), getCollapseState()), they read live overflow state so callers can query them from an event handler.
• scrollTo(index) stays contained. It scrolls the carousel container by a measured delta rather than calling scrollIntoView, so it never moves ancestors or the page. RTL-aware.
• RTL and prefers-reduced-motion behavior is inherited from the existing scroll logic.
• The interface stays compact (11 props); the legacy component is untouched.

Testing

• packages/core/src/Carousel/Carousel.test.tsx: 23 tests pass (7 new — loop wrap-around both directions, buttons stay enabled at edges under loop, no-wrap when content fits, handle scrollNext/Prev/scrollTo, live canScroll*, loop reachability).
• Typecheck clean, lint clean, sync/exports/changeset checks pass.
• Storybook: added Loop and Imperative Control stories.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 1, 2026 6:32am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Carousel _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	423	-
Complexity	N/A	Very High (48)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.9KB	1.3KB

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}