@astryxdesign/core 0.2.0-canary.11b423e → 0.2.0-canary.15ccc97

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/ContextMenu/ContextMenu.d.ts

@@ -96,7 +96,7 @@ export type ContextMenuProps = ContextMenuDataProps | ContextMenuCompoundProps;
  * </ContextMenu>
  * ```
  */
-export declare function ContextMenu({ children, menuWidth, size, label: labelFromProps, isDisabled, onOpenChange, ref, className, style, xstyle, triggerXstyle, 'data-testid': testId, ...props }: ContextMenuProps): React.JSX.Element;
+export declare function ContextMenu({ children, menuWidth, size, label: labelFromProps, isDisabled, onOpenChange, ref, className, style, xstyle, triggerXstyle, 'data-testid': testId, ...rest }: ContextMenuProps): React.JSX.Element;
 export declare namespace ContextMenu {
     var displayName: string;
 }

package/dist/ContextMenu/ContextMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextMenu.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/ContextMenu.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AA0BrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAqDtC,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAMnD,UAAU,oBAAqB,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,oBAAqB,SAAQ,oBAAoB;IACzD,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAW,EACX,KAAK,EAAE,cAAc,EACrB,UAAkB,EAClB,YAAY,EACZ,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EACb,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,gBAAgB,qBA4RlB;yBA1Se,WAAW"}
+{"version":3,"file":"ContextMenu.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/ContextMenu.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AA0BrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAqDtC,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAMnD,UAAU,oBAAqB,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,oBAAqB,SAAQ,oBAAoB;IACzD,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAW,EACX,KAAK,EAAE,cAAc,EACrB,UAAkB,EAClB,YAAY,EACZ,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EACb,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,gBAAgB,qBAwSlB;yBAtTe,WAAW"}

package/dist/ContextMenu/ContextMenu.js

@@ -131,12 +131,20 @@ export function ContextMenu({
   xstyle,
   triggerXstyle,
   'data-testid': testId,
-  ...props
+  ...rest
 }) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.contextMenu.label');
-  const items = ('items' in props ? props.items : undefined) ?? [];
-  const menuContent = 'menuContent' in props ? props.menuContent : undefined;
+  // Separate content props (union discriminant) from DOM pass-through attrs.
+  // The union means exactly one of items/menuContent exists in rest; destructure
+  // both so triggerProps contains only DOM-safe attributes.
+  const {
+    items: itemsProp,
+    menuContent: menuContentProp,
+    ...triggerProps
+  } = rest;
+  const items = itemsProp ?? [];
+  const menuContent = menuContentProp;
   const menuId = useId();
   // Cursor point in the trigger's local coordinate space (offset from the
   // trigger's top-left, in-flow). Stored here and written to the zero-size
@@ -325,12 +333,13 @@ export function ContextMenu({
     closeMenu,
     menuSize: size
   }), [closeMenu, size]);
-  const resolvedMenuContent = props.items !== undefined ? renderDropdownItems(items) : menuContent;
+  const resolvedMenuContent = itemsProp !== undefined ? renderDropdownItems(items) : menuContent;
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsxs("div", {
       ref: mergeRefs(ref, triggerRef),
       onContextMenu: handleContextMenu,
       ...longPressHandlers,
+      ...triggerProps,
       "data-testid": testId,
       ...stylex.props(styles.trigger, ...(triggerXstyle ? Array.isArray(triggerXstyle) ? triggerXstyle : [triggerXstyle] : [])),
       children: [children, /*#__PURE__*/_jsx("span", {

package/dist/DropdownMenu/DropdownMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAS,KAAK,WAAW,EAAC,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAetC,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAQtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAyC5C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAC5B,oBAAoB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAMnE,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEnE,UAAU,qBAAsB,SAAQ,SAAS;IAC/C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,qBAAsB,SAAQ,qBAAqB;IAC3D,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,yBAA0B,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAC3B,qBAAqB,GAAG,yBAAyB,CAAC;AA+BpD,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,gBAAgB,EAC5B,YAAY,EACZ,SAAS,EACT,OAAO,EACP,UAAiB,EACjB,SAAmB,EACnB,SAAmB,EACnB,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAqRnB;yBAnSe,YAAY"}
+{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAS,KAAK,WAAW,EAAC,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAetC,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAQtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAyC5C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAC5B,oBAAoB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAMnE,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEnE,UAAU,qBAAsB,SAAQ,SAAS;IAC/C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,qBAAsB,SAAQ,qBAAqB;IAC3D,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,yBAA0B,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAC3B,qBAAqB,GAAG,yBAAyB,CAAC;AA+BpD,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,gBAAgB,EAC5B,YAAY,EACZ,SAAS,EACT,OAAO,EACP,UAAiB,EACjB,SAAmB,EACnB,SAAmB,EACnB,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAwRnB;yBAtSe,YAAY"}

package/dist/DropdownMenu/DropdownMenu.js

@@ -160,27 +160,21 @@ export function DropdownMenu({
   // Close menu + return focus to trigger
   const handleLayerHide = useCallback(() => {
     lastHideTimeRef.current = Date.now();
-    if (isControlled) {
-      onOpenChange?.(false);
-    } else {
+    onOpenChange?.(false);
+    if (!isControlled) {
       setInternalIsOpen(false);
     }
     buttonRef.current?.focus();
   }, [isControlled, onOpenChange]);
 
-  // Track whether to focus the first item when the menu opens
+  // Defer item focus until the layer has committed open, so focus restore
+  // captures the trigger instead of the first menu item.
   const shouldFocusOnOpenRef = useRef(false);
   const handleLayerShow = useCallback(() => {
-    if (isControlled) {
-      onOpenChange?.(true);
-    } else {
+    onOpenChange?.(true);
+    if (!isControlled) {
       setInternalIsOpen(true);
     }
-    if (shouldFocusOnOpenRef.current) {
-      shouldFocusOnOpenRef.current = false;
-      // focusFirst is called via openAndFocus below — defer to rAF
-      // so the popover content is rendered before we query for items
-    }
   }, [isControlled, onOpenChange]);
   const popover = usePopover({
     onHide: handleLayerHide,
@@ -223,17 +217,26 @@ export function DropdownMenu({
     getCurrentIndex: () => getMenuItems().findIndex(el => el === document.activeElement || el.contains(document.activeElement))
   });
 
-  // Sync controlled open state → popover, and focus first item on open
+  // Sync controlled open state → popover.
   useEffect(() => {
     if (isControlled) {
       if (controlledIsOpen && !popover.isOpen) {
+        shouldFocusOnOpenRef.current = true;
         popover.show();
-        requestAnimationFrame(() => focusFirst());
       } else if (!controlledIsOpen && popover.isOpen) {
         popover.hide();
       }
     }
-  }, [controlledIsOpen, isControlled, popover, focusFirst]);
+  }, [controlledIsOpen, isControlled, popover]);
+
+  // Move focus into the menu only after the layer has committed open.
+  useEffect(() => {
+    if (!popover.isOpen || !shouldFocusOnOpenRef.current) {
+      return;
+    }
+    shouldFocusOnOpenRef.current = false;
+    requestAnimationFrame(() => focusFirst());
+  }, [popover.isOpen, focusFirst]);
 
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(e => {
@@ -267,9 +270,9 @@ export function DropdownMenu({
     listNavKeyDown(e);
   }, [listNavKeyDown, closeMenu, typeahead, ownsEvent]);
   const openAndFocus = useCallback(() => {
+    shouldFocusOnOpenRef.current = true;
     popover.show();
-    requestAnimationFrame(() => focusFirst());
-  }, [popover, focusFirst]);
+  }, [popover]);
   const handleButtonClick = useCallback(() => {
     // If the menu was just closed by light dismiss (e.g. iOS Safari fires
     // pointerdown → hide before the trigger's click), the click would

package/dist/Icon/globalIconRegistry.d.ts

@@ -16,6 +16,16 @@ import type { DefinedTheme } from '../theme/defineTheme';
  * visual representation. Themes provide the actual icon components.
  */
 export type IconName = 'close' | 'chevronDown' | 'chevronLeft' | 'chevronRight' | 'check' | 'success' | 'error' | 'warning' | 'info' | 'calendar' | 'clock' | 'externalLink' | 'menu' | 'moreHorizontal' | 'search' | 'arrowUp' | 'arrowDown' | 'arrowsUpDown' | 'funnel' | 'eyeSlash' | 'viewColumns' | 'copy' | 'checkDouble' | 'wrench' | 'stop' | 'microphone';
+/**
+ * A semantic icon name — either one of the built-in {@link IconName}s or an
+ * arbitrary string key contributed by a library/app.
+ *
+ * The `(string & {})` intersection keeps the built-in names available for
+ * autocomplete while still allowing any string, so downstream libraries can
+ * register and resolve their own keys (e.g. `'richtext:bold'`) without having
+ * to widen the core `IconName` union.
+ */
+export type ExtendedIconName = IconName | (string & {});
 /**
  * Icon registry mapping semantic names to React nodes.
  */
@@ -34,8 +44,17 @@ export type IconRegistrySource = DefinedTheme | string | null | undefined;
  * import { brandIcons } from './brand-icons';
  * registerIcons(brandIcons);
  * ```
+ *
+ * Libraries may also register their own extension keys (any string), so a
+ * theme can override them the same way it overrides built-in icons:
+ * @example
+ * ```
+ * // In a library that ships its own icons:
+ * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
+ * // resolve with getIcon('richtext:bold')
+ * ```
  */
-export declare function registerIcons(icons: Partial<IconRegistry>): void;
+export declare function registerIcons(icons: Partial<Record<ExtendedIconName, ReactNode>>): void;
 /**
  * Get a snapshot of the full icon registry, with registered icons overriding
  * built-in defaults.
@@ -50,8 +69,29 @@ export declare function getIconRegistry(source?: IconRegistrySource): Readonly<I
  *
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
+ *
+ * Accepts extension keys (any string) in addition to the built-in
+ * {@link IconName}s — useful for library-contributed icons. For a
+ * caller-supplied fallback when a key isn't registered, use
+ * {@link getExtendedIcon}.
+ */
+export declare function getIcon(name: ExtendedIconName, source?: IconRegistrySource): ReactNode;
+/**
+ * Resolve an extension icon by an arbitrary string key, falling back to a
+ * caller-supplied default when nothing is registered.
+ *
+ * This is the seam libraries use to make their own icons themeable: ship the
+ * inline SVG as `fallback`, resolve through this function, and a theme can
+ * override the key via {@link registerIcons} without the library having to
+ * widen the core {@link IconName} union.
+ *
+ * @example
+ * ```
+ * // Library default, overridable by a theme registering 'richtext:bold':
+ * getExtendedIcon('richtext:bold', <BoldGlyph />)
+ * ```
  */
-export declare function getIcon(name: IconName, source?: IconRegistrySource): ReactNode;
+export declare function getExtendedIcon(name: ExtendedIconName, fallback?: ReactNode, source?: IconRegistrySource): ReactNode;
 /**
  * Reset the global registry. For testing only.
  * @internal

package/dist/Icon/globalIconRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAQvD;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAsB1E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAOhE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,YAAY,CAAC,CAexB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,QAAQ,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAGX;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}
+{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAQvD;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAsB1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,GAClD,IAAI,CAON;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,YAAY,CAAC,CAkBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAOX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAQX;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}