@astryxdesign/core 0.2.0-canary.ef849b1 → 0.2.0-canary.ef91556

package/README.md

@@ -75,10 +75,12 @@ astryx gap-report                   # report a missing capability
 
 ## Quick Start
 
+Astryx requires **React 19** or later (`react` and `react-dom` >= 19.0.0 are peer dependencies).
+
 Install Astryx and a theme:
 
 ```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
 ```
 
 Then pick your setup below based on your framework and styling approach.
@@ -226,7 +228,7 @@ export default function Page() {
 Use the pre-built dist alongside StyleX for your own styles.
 
 ```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
 ```
 
 **`src/app/globals.css`**
@@ -242,7 +244,7 @@ Providers and layout are the same as the Tailwind example (use `@astryxdesign/th
 ### Vite
 
 ```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
 ```
 
 Same CSS imports and providers as above. No build plugins needed; Astryx ships pre-built.

package/dist/AvatarGroup/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AAavD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,kBAAkB,EAAE,wBAAwB,EAC5C,SAAS,EACT,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CAuE9B;yBApFe,WAAW"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AAavD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,kBAAkB,EAAE,wBAAwB,EAC5C,SAAS,EACT,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CAmE9B;yBAhFe,WAAW"}

package/dist/AvatarGroup/AvatarGroup.js

@@ -87,11 +87,9 @@ export function AvatarGroup({
   }), [size, overlap, numericSize]);
 
   // The keyboard hint and roving tab stop only make sense once the group has
-  // interactive children. Detect their presence (and the writing direction for
-  // RTL-correct arrow navigation) from the rendered DOM after commit, matching
-  // how the codebase reads direction elsewhere (`getComputedStyle(el).direction`).
+  // interactive children. Detect their presence from the rendered DOM after
+  // commit. (Arrow-key direction is auto-detected inside useListFocus.)
   const [hasInteractiveItems, setHasInteractiveItems] = useState(false);
-  const [isRtl, setIsRtl] = useState(false);
 
   // Single tab stop + roving arrow focus over the group's interactive items.
   // `itemSelector` targets the shared `[data-avatar-item]` marker stamped on
@@ -105,8 +103,7 @@ export function AvatarGroup({
   } = useListFocus({
     itemSelector: '[data-avatar-item]',
     orientation: 'horizontal',
-    hasRovingTabIndex: true,
-    isRtl
+    hasRovingTabIndex: true
   });
   useIsomorphicLayoutEffect(() => {
     const root = listRef.current;
@@ -114,7 +111,6 @@ export function AvatarGroup({
       return;
     }
     setHasInteractiveItems(root.querySelector('[data-avatar-item]') != null);
-    setIsRtl(getComputedStyle(root).direction === 'rtl');
   });
   const hintId = useId();
   const describedBy = [ariaDescribedByFromProps, hasInteractiveItems ? hintId : null].filter(Boolean).join(' ') || undefined;

package/dist/Carousel/Carousel.d.ts

@@ -5,7 +5,9 @@
  * @position Horizontal scroll container with fade-edge overflow indication,
  *   optional prev/next buttons on the top layer, scroll-snap, a 1px
  *   visual bleed allowance for child selection indicators, and Shift + wheel
- *   mapping so mouse users can scroll horizontally. Exposes APG
+ *   mapping so mouse users can scroll horizontally. Supports optional
+ *   wrap-around looping and an imperative handle (handleRef) for programmatic
+ *   scroll control. Exposes APG
  *   carousel semantics: the root is a labelled region with
  *   aria-roledescription="carousel" and each item wrapper is a group with
  *   aria-roledescription="slide" named "Slide N of M".
@@ -18,8 +20,47 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 import type { SpacingStep } from '../utils/types';
+/**
+ * Imperative control surface for the Carousel, accessed via the `handleRef`
+ * prop. Methods drive the same native-scroll machinery as the built-in
+ * buttons, so they respect RTL, reduced-motion, and `hasLoop`.
+ */
+export interface CarouselHandle {
+    /**
+     * Scroll forward by roughly one viewport. With `hasLoop`, wraps to the
+     * start once the end is reached.
+     */
+    scrollNext(): void;
+    /**
+     * Scroll backward by roughly one viewport. With `hasLoop`, wraps to the
+     * end once the start is reached.
+     */
+    scrollPrev(): void;
+    /**
+     * Scroll the item at the given 0-based index to the start edge. The index
+     * is clamped to the item range, and only the carousel scrolls — the page
+     * position is left untouched.
+     */
+    scrollTo(index: number): void;
+    /**
+     * Whether there is scrollable content past the trailing edge. With
+     * `hasLoop`, returns true whenever the content overflows, since wrapping
+     * is always available. Reads live state — safe to call in an event handler.
+     */
+    canScrollNext(): boolean;
+    /**
+     * Whether there is scrollable content past the leading edge. With
+     * `hasLoop`, returns true whenever the content overflows. Reads live state.
+     */
+    canScrollPrev(): boolean;
+}
 export interface CarouselProps extends BaseProps<HTMLDivElement> {
     ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Imperative handle for programmatic scroll control. Exposes scrollNext,
+     * scrollPrev, scrollTo, and the canScrollNext/canScrollPrev queries.
+     */
+    handleRef?: React.Ref<CarouselHandle>;
     /** Carousel items — rendered in a horizontal scroll container. */
     children: ReactNode;
     /**
@@ -39,6 +80,16 @@ export interface CarouselProps extends BaseProps<HTMLDivElement> {
      * @default true
      */
     hasEdgeFade?: boolean;
+    /**
+     * Enable wrap-around scrolling. When the content overflows, pressing Next
+     * at the end scrolls back to the start, and Prev at the start scrolls to
+     * the end — for both the built-in buttons and the imperative handle. The
+     * navigation buttons stay visible at both edges instead of hiding, since a
+     * scroll is always available. Has no effect when the content fits without
+     * overflowing.
+     * @default false
+     */
+    hasLoop?: boolean;
     /**
      * Enable scroll-snap on items. Each direct child snaps to the start edge.
      * @default false
@@ -79,7 +130,7 @@ export interface CarouselProps extends BaseProps<HTMLDivElement> {
  * </Carousel>
  * ```
  */
-export declare function Carousel({ ref, children, gap, hasButtons, hasEdgeFade, hasSnap, padding, 'aria-label': ariaLabelFromProps, xstyle, className, style, 'data-testid': testId, ...htmlProps }: CarouselProps): import("react").JSX.Element;
+export declare function Carousel({ ref, handleRef, children, gap, hasButtons, hasEdgeFade, hasLoop, hasSnap, padding, 'aria-label': ariaLabelFromProps, xstyle, className, style, 'data-testid': testId, ...htmlProps }: CarouselProps): import("react").JSX.Element;
 export declare namespace Carousel {
     var displayName: string;
 }

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,KAAK,SAAS,EAMf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BA6Mf;yBA3Ne,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAiRf;yBAjSe,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -9,7 +9,9 @@
  * @position Horizontal scroll container with fade-edge overflow indication,
  *   optional prev/next buttons on the top layer, scroll-snap, a 1px
  *   visual bleed allowance for child selection indicators, and Shift + wheel
- *   mapping so mouse users can scroll horizontally. Exposes APG
+ *   mapping so mouse users can scroll horizontally. Supports optional
+ *   wrap-around looping and an imperative handle (handleRef) for programmatic
+ *   scroll control. Exposes APG
  *   carousel semantics: the root is a labelled region with
  *   aria-roledescription="carousel" and each item wrapper is a group with
  *   aria-roledescription="slide" named "Slide N of M".
@@ -19,7 +21,7 @@
  * - /apps/storybook/stories/Carousel.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/Carousel/ (showcase blocks)
  */
-import { useRef, useCallback, useEffect, Children, isValidElement } from 'react';
+import { useRef, useCallback, useEffect, useImperativeHandle, Children, isValidElement } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars, colorVars, shadowVars, radiusVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
@@ -31,6 +33,12 @@ import { isRtlElement } from "../hooks/isRtlElement.js";
 import { mergeProps, mergeRefs, rtlStyles } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
+
+/**
+ * Imperative control surface for the Carousel, accessed via the `handleRef`
+ * prop. Methods drive the same native-scroll machinery as the built-in
+ * buttons, so they respect RTL, reduced-motion, and `hasLoop`.
+ */
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 // =============================================================================
 // Styles
@@ -203,10 +211,12 @@ const paddingStyles = {
  */
 export function Carousel({
   ref,
+  handleRef,
   children,
   gap = 1,
   hasButtons = true,
   hasEdgeFade = true,
+  hasLoop = false,
   hasSnap = false,
   padding,
   'aria-label': ariaLabelFromProps,
@@ -222,7 +232,8 @@ export function Carousel({
   const {
     scrollRef,
     overflowStart,
-    overflowEnd
+    overflowEnd,
+    hasOverflow
   } = useScrollOverflow();
 
   // Children.toArray drops null/undefined/boolean children and assigns
@@ -277,22 +288,78 @@ export function Carousel({
     if (!el) {
       return;
     }
-    const firstChild = el.firstElementChild;
-    const itemWidth = firstChild ? firstChild.offsetWidth : 0;
-    const amount = el.clientWidth - itemWidth * 0.5;
     // Respect the user's reduced-motion preference — mirrors the CSS
     // scroll-behavior override so button-driven scrolling doesn't animate
     // for users who opted out of motion.
     const prefersReducedMotion = typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const behavior = prefersReducedMotion ? 'auto' : 'smooth';
+    // Under RTL the scroll axis is inverted (start is scrollLeft 0, the end
+    // is negative), so flip the physical delta sign.
+    const rtlSign = isRtlElement(el) ? -1 : 1;
+
+    // Wrap-around: when looping over overflowing content, a press that would
+    // run past an edge jumps to the opposite edge instead. Overshoot by the
+    // full scroll width in the opposite logical direction and let the browser
+    // clamp to the far edge — this reuses the same RTL sign convention as a
+    // normal scroll, so it stays direction-correct without special-casing.
+    if (hasLoop && hasOverflow) {
+      const atEnd = direction === 1 && !overflowEnd;
+      const atStart = direction === -1 && !overflowStart;
+      if (atEnd || atStart) {
+        el.scrollBy({
+          left: rtlSign * -direction * el.scrollWidth,
+          behavior
+        });
+        return;
+      }
+    }
+    const firstChild = el.firstElementChild;
+    const itemWidth = firstChild ? firstChild.offsetWidth : 0;
+    const amount = el.clientWidth - itemWidth * 0.5;
     el.scrollBy({
       // `direction` is the logical intent (-1 = toward content start, +1 =
-      // toward content end). Under RTL the scroll axis is inverted (start is
-      // scrollLeft 0, the end is negative), so flip the physical delta sign.
-      left: (isRtlElement(el) ? -1 : 1) * direction * Math.max(amount, itemWidth),
+      // toward content end).
+      left: rtlSign * direction * Math.max(amount, itemWidth),
+      behavior
+    });
+  }, [hasLoop, hasOverflow, overflowStart, overflowEnd]);
+  const scrollToIndex = useCallback(index => {
+    const el = scrollElRef.current;
+    const items = el?.children;
+    if (!el || !items || items.length === 0) {
+      return;
+    }
+    const clamped = Math.max(0, Math.min(index, items.length - 1));
+    const target = items[clamped];
+    const prefersReducedMotion = typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    // Bring the item to the start edge by scrolling the container by the
+    // measured gap between the item and the container edge. Using scrollBy
+    // (not scrollIntoView) keeps the scroll contained to the carousel and
+    // never moves ancestors or the page. In RTL the start edge is the right
+    // edge, so align the trailing edges instead of the leading ones.
+    const containerRect = el.getBoundingClientRect();
+    const itemRect = target.getBoundingClientRect();
+    const delta = isRtlElement(el) ? itemRect.right - containerRect.right : itemRect.left - containerRect.left;
+    el.scrollBy({
+      left: delta,
       behavior: prefersReducedMotion ? 'auto' : 'smooth'
     });
   }, []);
-  const fadeStyle = hasEdgeFade ? overflowStart && overflowEnd ? styles.fadeBoth : overflowStart ? styles.fadeStart : overflowEnd ? styles.fadeEnd : null : null;
+  useImperativeHandle(handleRef, () => ({
+    scrollNext: () => scrollBy(1),
+    scrollPrev: () => scrollBy(-1),
+    scrollTo: index => scrollToIndex(index),
+    // With loop, either direction is reachable whenever the content
+    // overflows; otherwise reflect the live per-edge overflow state.
+    canScrollNext: () => hasLoop ? hasOverflow : overflowEnd,
+    canScrollPrev: () => hasLoop ? hasOverflow : overflowStart
+  }), [scrollBy, scrollToIndex, hasLoop, hasOverflow, overflowStart, overflowEnd]);
+
+  // With loop, the buttons stay reachable at both edges as long as there's
+  // something to scroll; without loop they follow the per-edge overflow state.
+  const canScrollStart = hasLoop && hasOverflow ? true : overflowStart;
+  const canScrollEnd = hasLoop && hasOverflow ? true : overflowEnd;
+  const fadeStyle = hasEdgeFade ? hasLoop && hasOverflow || overflowStart && overflowEnd ? styles.fadeBoth : overflowStart ? styles.fadeStart : overflowEnd ? styles.fadeEnd : null : null;
 
   // Self-authored position styles (positioning: 'custom' below): a cover
   // centered on the anchor, sized to it — direction-neutral by construction.
@@ -341,7 +408,7 @@ export function Carousel({
           1: {
             className: "x78zum5 x6s0dn4 xl56j7k x1prclbq xjspbzw x14hfi27 x19991ni xuedmi6 xlr8y92 xuuh30 x1nyx83j xg01cxk x47corl"
           }
-        }[!!!overflowStart << 0],
+        }[!!!canScrollStart << 0],
         children: /*#__PURE__*/_jsx(Button, {
           icon: /*#__PURE__*/_jsx("span", {
             ...stylex.props(rtlStyles.mirror),
@@ -359,7 +426,7 @@ export function Carousel({
           // tab order and a11y tree while it's visually hidden, so
           // keyboard users don't land on an invisible control.
           ,
-          isDisabled: !overflowStart,
+          isDisabled: !canScrollStart,
           onClick: () => scrollBy(-1),
           xstyle: styles.buttonRadiusOverride
         })
@@ -371,7 +438,7 @@ export function Carousel({
           1: {
             className: "x78zum5 x6s0dn4 xl56j7k x1prclbq xjspbzw x14hfi27 x19991ni xuedmi6 xlr8y92 xitnhlw x36dvrd xg01cxk x47corl"
           }
-        }[!!!overflowEnd << 0],
+        }[!!!canScrollEnd << 0],
         children: /*#__PURE__*/_jsx(Button, {
           icon: /*#__PURE__*/_jsx("span", {
             ...stylex.props(rtlStyles.mirror),
@@ -387,7 +454,7 @@ export function Carousel({
           // See "Scroll left" — disabled while visually hidden so the
           // button stays mounted but out of the tab order / a11y tree.
           ,
-          isDisabled: !overflowEnd,
+          isDisabled: !canScrollEnd,
           onClick: () => scrollBy(1),
           xstyle: styles.buttonRadiusOverride
         })

package/dist/Carousel/index.d.ts

@@ -5,5 +5,5 @@
  * @position Public entry point for the Carousel module
  */
 export { Carousel } from './Carousel';
-export type { CarouselProps } from './Carousel';
+export type { CarouselProps, CarouselHandle } from './Carousel';
 //# sourceMappingURL=index.d.ts.map

package/dist/Carousel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Carousel/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Carousel/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EAAC,aAAa,EAAE,cAAc,EAAC,MAAM,YAAY,CAAC"}

package/dist/CommandPalette/CommandPaletteInput.d.ts

@@ -67,7 +67,7 @@ export interface CommandPaletteInputProps extends Omit<BaseProps<HTMLInputElemen
  * </CommandPalette>
  * ```
  */
-export declare function CommandPaletteInput({ value: controlledValue, onValueChange, placeholder: placeholderFromProps, label, hasAutoFocus, endContent, onChange, onKeyDown, ref, xstyle, ...props }: CommandPaletteInputProps): import("react").JSX.Element;
+export declare function CommandPaletteInput({ value: controlledValue, onValueChange, placeholder: placeholderFromProps, label, hasAutoFocus, endContent, onChange, onKeyDown, ref, xstyle, className, style, ...props }: CommandPaletteInputProps): import("react").JSX.Element;
 export declare namespace CommandPaletteInput {
     var displayName: string;
 }

package/dist/CommandPalette/CommandPaletteInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPaletteInput.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteInput.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAarE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA2D5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,WAAW,EAAE,oBAAoB,EACjC,KAAK,EACL,YAAmB,EACnB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,MAAM,EACN,GAAG,KAAK,EACT,EAAE,wBAAwB,+BAqF1B;yBAjGe,mBAAmB"}
+{"version":3,"file":"CommandPaletteInput.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteInput.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAarE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA2D5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,WAAW,EAAE,oBAAoB,EACjC,KAAK,EACL,YAAmB,EACnB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,wBAAwB,+BAuF1B;yBArGe,mBAAmB"}

package/dist/CommandPalette/CommandPaletteInput.js

@@ -65,6 +65,8 @@ export function CommandPaletteInput({
   onKeyDown,
   ref,
   xstyle,
+  className,
+  style,
   ...props
 }) {
   const t = useTranslator();
@@ -100,7 +102,7 @@ export function CommandPaletteInput({
     ctx?.onKeyDown(e);
   }, [ctx, onKeyDown]);
   return /*#__PURE__*/_jsxs("div", {
-    ...mergeProps(themeProps('command-palette-input'), stylex.props(styles.wrapper, xstyle)),
+    ...mergeProps(themeProps('command-palette-input'), stylex.props(styles.wrapper, xstyle), className, style),
     children: [/*#__PURE__*/_jsx("span", {
       ...{
         className: "x78zum5 x6s0dn4 x2lah0s xv1l7n4"

package/dist/ComplexSelector/ComplexSelector.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @file ComplexSelector.tsx
+ * @input Uses React, StyleX, Field, usePopover
+ * @output Exports ComplexSelector component for custom selector surfaces
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
+ * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
+ * - /packages/core/src/ComplexSelector/index.ts
+ * - /apps/storybook/stories/ComplexSelector.stories.tsx
+ */
+import React, { type ReactNode } from 'react';
+import type { StyleXStyles } from '@stylexjs/stylex';
+import type { BaseProps } from '../BaseProps';
+import { type FieldStatusVariant } from '../Field';
+import type { SizeValue } from '../utils/types';
+export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
+export interface ComplexSelectorRenderState {
+    /** Whether the selector surface is open. */
+    isOpen: boolean;
+    /** Whether changeAction/isLoading is pending. */
+    isBusy: boolean;
+    /** ID of the trigger button. */
+    triggerId: string;
+    /** ID of the popup content container. */
+    contentId: string;
+}
+export interface ComplexSelectorStatus {
+    type: 'warning' | 'error' | 'success';
+    message?: string;
+}
+export interface ComplexSelectorProps<Value> extends Omit<BaseProps<HTMLDivElement>, 'children' | 'onChange'> {
+    /** Label text for accessibility and the field label. */
+    label: string;
+    /** Current controlled value. */
+    value: Value;
+    /** Called when custom content commits a new value. */
+    onChange?: (value: Value) => void;
+    /** Optional async action after onChange; drives optimistic UI. */
+    changeAction?: (value: Value) => void | Promise<void>;
+    /** Custom selector surface content rendered inside a dialog popover. */
+    children: (value: Value, onChange: (value: Value) => void, close: () => void, state: ComplexSelectorRenderState) => ReactNode;
+    /** Label/content shown in the closed trigger. */
+    triggerLabel?: ReactNode;
+    /** Placeholder shown when triggerLabel is omitted. */
+    placeholder?: ReactNode;
+    /** Whether to visually hide the field label. */
+    isLabelHidden?: boolean;
+    /** Helper text displayed below the label. */
+    description?: string;
+    /** Marks the field optional. */
+    isOptional?: boolean;
+    /** Marks the field required. */
+    isRequired?: boolean;
+    /** Disables the selector. */
+    isDisabled?: boolean;
+    /** Shows loading state on the trigger. */
+    isLoading?: boolean;
+    /** Validation status. */
+    status?: ComplexSelectorStatus;
+    /** Status placement. */
+    statusVariant?: FieldStatusVariant;
+    /** Tooltip text displayed next to the label. */
+    labelTooltip?: string;
+    /** Trigger and field size. */
+    size?: ComplexSelectorSize;
+    /** Width of the field. */
+    width?: SizeValue;
+    /** Popup placement. */
+    placement?: 'above' | 'below' | 'start' | 'end';
+    /** StyleX styles for the popup content container. */
+    contentXstyle?: StyleXStyles;
+    /** Test ID for the trigger container. */
+    'data-testid'?: string;
+}
+/**
+ * A selector shell for rich, custom selection surfaces.
+ *
+ * ComplexSelector owns the field, trigger, popover, focus restore, and async
+ * change action flow. Consumers provide the dialog content as a render function,
+ * using the supplied `value`, `onChange`, and `close` helpers to compose the
+ * right accessible structure for the custom selector.
+ *
+ * @example
+ * ```
+ * <ComplexSelector
+ *   label="Fruit"
+ *   value={value}
+ *   onChange={setValue}
+ *   triggerLabel={`${value.fruit} ${value.ripeness}`}>
+ *   {(value, onChange, close) => (
+ *     <FruitGrid
+ *       value={value}
+ *       onChange={nextValue => {
+ *         onChange(nextValue);
+ *         close();
+ *       }}
+ *     />
+ *   )}
+ * </ComplexSelector>
+ * ```
+ */
+export declare function ComplexSelector<Value>({ label, value, onChange, changeAction, children, triggerLabel, placeholder: placeholderFromProps, isLabelHidden, description, isOptional, isRequired, isDisabled, isLoading, status, statusVariant, labelTooltip, size, width, placement, contentXstyle, xstyle, className, style, 'data-testid': testId, ...props }: ComplexSelectorProps<Value>): React.JSX.Element;
+export declare namespace ComplexSelector {
+    var displayName: string;
+}
+//# sourceMappingURL=ComplexSelector.d.ts.map

package/dist/ComplexSelector/ComplexSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComplexSelector.d.ts","sourceRoot":"","sources":["../../src/ComplexSelector/ComplexSelector.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAKZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAA4B,KAAK,kBAAkB,EAAC,MAAM,UAAU,CAAC;AAiB5E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAqG9C,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK,CAAE,SAAQ,IAAI,CACvD,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,UAAU,CACxB;IACC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,sDAAsD;IACtD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAClC,kEAAkE;IAClE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,wEAAwE;IACxE,QAAQ,EAAE,CACR,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAChC,KAAK,EAAE,MAAM,IAAI,EACjB,KAAK,EAAE,0BAA0B,KAC9B,SAAS,CAAC;IACf,iDAAiD;IACjD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,sDAAsD;IACtD,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,gDAAgD;IAChD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yBAAyB;IACzB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,wBAAwB;IACxB,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uBAAuB;IACvB,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;IAChD,qDAAqD;IACrD,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,EACrC,KAAK,EACL,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,WAAW,EAAE,oBAAoB,EACjC,aAAqB,EACrB,WAAW,EACX,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAiB,EACjB,MAAM,EACN,aAA0B,EAC1B,YAAY,EACZ,IAAW,EACX,KAAK,EACL,SAAmB,EACnB,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,oBAAoB,CAAC,KAAK,CAAC,qBA6J7B;yBAvLe,eAAe"}