@astryxdesign/core 0.4.7-canary.d895769 → 0.4.7-canary.dd94f7f

package/dist/AspectRatio/AspectRatio.d.ts

@@ -34,6 +34,25 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
     ref?: React.Ref<HTMLDivElement>;
     /**
      * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+     *
+     * The ratio is emitted as a class-level declaration — never an inline
+     * style — so it can be made responsive:
+     * - StyleX consumers pass an `aspect-ratio` rule via `xstyle`, including
+     *   under `@media`/`@container` conditions.
+     * - Plain-CSS/Tailwind consumers override `aspect-ratio` from their own
+     *   (unlayered) rules: the compiled component styles live in the
+     *   `astryx-base` cascade layer, and unlayered CSS wins over layered
+     *   rules regardless of specificity.
+     *
+     * @example
+     * ```
+     * // 3:1 hero that becomes 3:2 when its container stacks
+     * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
+     *
+     * // CSS: @container gallery (max-width: 720px) {
+     * //   .gallery-hero { aspect-ratio: 3 / 2; }
+     * // }
+     * ```
      */
     ratio: number;
     /**
@@ -102,6 +121,11 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or

package/dist/AspectRatio/AspectRatio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AspectRatio.d.ts","sourceRoot":"","sources":["../../src/AspectRatio/AspectRatio.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IAErB;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,KAAmB,EACnB,GAAG,EACH,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,+BA2BlB;yBArCe,WAAW"}
+{"version":3,"file":"AspectRatio.d.ts","sourceRoot":"","sources":["../../src/AspectRatio/AspectRatio.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IAErB;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,KAAmB,EACnB,GAAG,EACH,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,+BA4BlB;yBAtCe,WAAW"}

package/dist/AspectRatio/AspectRatio.js

@@ -49,6 +49,23 @@ const styles = {
   }
 };
 
+// The ratio compiles to a CSS variable + a class-level declaration
+// (aspect-ratio: var(--x)) instead of a raw inline style, so consumer
+// overrides — `xstyle` rules, including ones inside @media/@container
+// queries — can still win. A raw inline `aspect-ratio` would beat any class
+// (same rationale as Grid's dynamic track values). Non-StyleX consumers
+// don't need a dedicated hook: the compiled declaration sits in the
+// `astryx-base` cascade layer, so any unlayered consumer rule wins
+// regardless of specificity.
+const dynamicStyles = {
+  ratio: ratio => [{
+    kOBAk4: ratio != null ? "x10y9f9r" : ratio,
+    $$css: true
+  }, {
+    "--x-aspectRatio": ratio != null ? ratio : undefined
+  }]
+};
+
 /**
  * AspectRatio component for maintaining a specific aspect ratio for its children.
  *
@@ -64,6 +81,11 @@ const styles = {
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or
@@ -102,10 +124,7 @@ export function AspectRatio({
     ref: ref,
     ...mergeProps(themeProps('aspect-ratio', {
       shape
-    }), stylex.props(styles.container, shape === 'ellipse' && styles.ellipse, xstyle), className, {
-      ...style,
-      aspectRatio: ratio
-    }),
+    }), stylex.props(styles.container, dynamicStyles.ratio(ratio), shape === 'ellipse' && styles.ellipse, xstyle), className, style),
     ...props,
     children: /*#__PURE__*/_jsx("div", {
       "data-astryx-aspect-ratio-override": fit,

package/dist/ButtonGroup/ButtonGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ButtonGroup.d.ts","sourceRoot":"","sources":["../../src/ButtonGroup/ButtonGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAI9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,sBAAsB,CAAC;AAOjE,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC;IAErC;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,KAAK,EACL,WAA0B,EAC1B,IAAI,EAAE,QAAQ,EACd,UAAkB,EAClB,SAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CAwC9B;yBAtDe,WAAW"}
+{"version":3,"file":"ButtonGroup.d.ts","sourceRoot":"","sources":["../../src/ButtonGroup/ButtonGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAI9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,sBAAsB,CAAC;AAOjE,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC;IAErC;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,KAAK,EACL,WAA0B,EAC1B,IAAI,EAAE,QAAQ,EACd,UAAkB,EAClB,SAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA+C9B;yBA7De,WAAW"}

package/dist/ButtonGroup/ButtonGroup.js

@@ -131,6 +131,13 @@ export function ButtonGroup({
     handleKeyDown
   } = useListFocus({
     itemSelector: 'button, [tabindex="0"]',
+    // A member's layer renders inline inside the group (useLayer does not
+    // portal it), so a key pressed in an open DropdownMenu bubbles here. The
+    // boundary is the group's own root or any layer, whichever is nearer to
+    // the target. Naming the group's own root is what keeps a group rendered
+    // inside a Popover or Toast working: bailing on any [popover] ancestor
+    // instead would swallow every arrow key it owns.
+    boundarySelector: '[role="group"], [popover]',
     orientation
   });
   const contextValue = useMemo(() => ({
@@ -146,7 +153,8 @@ export function ButtonGroup({
         ...props,
         ...mergeProps(themeProps('button-group', {
           size,
-          orientation
+          orientation,
+          elevation
         }), stylex.props(styles.group, orientation === 'vertical' && styles.vertical, elevationStyles[elevation], xstyle), className, style),
         role: "group",
         "aria-label": label,

package/dist/Table/plugins/pagination/useTablePagination.d.ts

@@ -88,6 +88,9 @@ export interface UseTablePaginationConfig {
     align?: 'start' | 'center' | 'end';
     /**
      * Accessible label for the pagination nav landmark.
+     * When `position` is 'both', the two navs get distinct names by suffixing
+     * this label — "{label} (top)" above and "{label} (bottom)" below — so
+     * same-type landmarks stay distinguishable to assistive technology.
      * @default 'Table pagination'
      */
     label?: string;

package/dist/Table/plugins/pagination/useTablePagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTablePagination.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/pagination/useTablePagination.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,aAAa,CAAC;AAgC7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,wBAAwB;IAGvC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAIrC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAIlB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAI3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAE1D;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAInC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,wBAAwB,GAC/B,WAAW,CAAC,CAAC,CAAC,CAmGhB"}
+{"version":3,"file":"useTablePagination.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/pagination/useTablePagination.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,aAAa,CAAC;AAgC7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,wBAAwB;IAGvC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAIrC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAIlB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAI3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAE1D;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAInC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,wBAAwB,GAC/B,WAAW,CAAC,CAAC,CAAC,CAgIhB"}

package/dist/Table/plugins/pagination/useTablePagination.js

@@ -116,6 +116,14 @@ export function useTablePagination(config) {
     label: labelFromProps
   } = config;
   const label = labelFromProps ?? t('@astryx.table.pagination.label');
+  // position='both' renders two nav landmarks; suffix the base label so each
+  // gets a unique accessible name (axe landmark-unique).
+  const labelAbove = t('@astryx.table.pagination.labelAbove', {
+    label
+  });
+  const labelBelow = t('@astryx.table.pagination.labelBelow', {
+    label
+  });
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
@@ -143,12 +151,16 @@ export function useTablePagination(config) {
   const configRef = useRef({
     paginationProps,
     position,
-    align
+    align,
+    labelAbove,
+    labelBelow
   });
   configRef.current = {
     paginationProps,
     position,
-    align
+    align,
+    labelAbove,
+    labelBelow
   };
 
   // Stable plugin object \u2014 created once, reads config via ref.
@@ -157,7 +169,9 @@ export function useTablePagination(config) {
       const {
         position: pos,
         paginationProps: props,
-        align: a
+        align: a,
+        labelAbove: above,
+        labelBelow: below
       } = configRef.current;
       if (pos === 'none') {
         return children;
@@ -172,7 +186,10 @@ export function useTablePagination(config) {
       const makeWrapper = side => /*#__PURE__*/_jsx("div", {
         ...stylex.props(styles.wrapper, side === 'below' && styles.marginTop, side === 'above' && styles.marginBottom, a === 'center' && styles.alignCenter, a === 'end' && styles.alignEnd, a === 'start' && styles.alignStart),
         children: /*#__PURE__*/_jsx(Pagination, {
-          ...props
+          ...props,
+          // Two navs with the same name are indistinguishable landmarks;
+          // give each side a unique name when both render.
+          label: pos === 'both' ? side === 'above' ? above : below : props.label
         })
       });
       return /*#__PURE__*/_jsxs(_Fragment, {

package/dist/astryx.css

@@ -11,6 +11,7 @@
   @property --x-126w13d { syntax: "*"; inherits: false;}
   @property --x-4drmnv { syntax: "*"; inherits: false;}
   @property --x-animationDelay { syntax: "*"; inherits: false;}
+  @property --x-aspectRatio { syntax: "*"; inherits: false;}
   @property --x-backgroundColor { syntax: "*"; inherits: false;}
   @property --x-borderWidth { syntax: "*"; inherits: false;}
   @property --x-bottom { syntax: "*"; inherits: false;}
@@ -616,6 +617,7 @@
   .xjyslct:not(#\#):not(#\#):not(#\#){appearance:none}
   .x1plog1:not(#\#):not(#\#):not(#\#){aspect-ratio:1}
   .xioom0i:not(#\#):not(#\#):not(#\#){aspect-ratio:var(--button-icon-only-aspect)}
+  .x10y9f9r:not(#\#):not(#\#):not(#\#){aspect-ratio:var(--x-aspectRatio)}
   .xvn2z4z:not(#\#):not(#\#):not(#\#){backdrop-filter:blur(12px)}
   .xlp1x4z:not(#\#):not(#\#):not(#\#){backface-visibility:hidden}
   .xx83zyx:not(#\#):not(#\#):not(#\#){background-clip:padding-box}

package/locales/en.json

@@ -813,7 +813,15 @@
   },
   "@astryx.table.pagination.label": {
     "defaultMessage": "Table pagination",
-    "description": "Screen-reader-only accessible name for the pagination `<nav>` appended below a data table. Kept separate from `@astryx.pagination.label` so translations may diverge."
+    "description": "Screen-reader-only accessible name for a table's pagination `<nav>` (rendered below and/or above the table per the plugin's position config). Kept separate from `@astryx.pagination.label` so translations may diverge. When position='both', this string is interpolated as the {label} value into `@astryx.table.pagination.labelAbove`/`labelBelow` — keep it compatible with those suffix templates."
+  },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "{label} (top)",
+    "description": "Accessible name for the pagination `<nav>` rendered above the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "{label} (bottom)",
+    "description": "Accessible name for the pagination `<nav>` rendered below the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
   },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "Select a time",

package/locales/pseudo.json

@@ -611,6 +611,12 @@
   "@astryx.table.pagination.label": {
     "defaultMessage": "⟦Ţàƀłé þàĝíñàţíóñ⟧"
   },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "⟦{label} (ţóþ)⟧"
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "⟦{label} (ƀóţţóɱ)⟧"
+  },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ à ţíɱé⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.7-canary.d895769",
+  "version": "0.4.7-canary.dd94f7f",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.4.7-canary.d895769",
+    "@astryxdesign/cli": "0.4.7-canary.dd94f7f",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -30,7 +31,7 @@ export const docs = {
     {
       name: 'ratio',
       type: 'number',
-      description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+      description: 'Aspect ratio as width/height (e.g. 16/9, 1). Emitted as a class-level declaration (never inline), so `xstyle` rules or unlayered consumer CSS can override it responsively.',
       required: true,
     },
     {
@@ -83,6 +84,7 @@ export const docsZh = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -94,7 +96,7 @@ export const docsZh = {
     ],
   },
   props: [
-    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。以类级声明输出（非内联样式），可通过 `xstyle` 规则或未分层的（unlayered）消费者 CSS 做响应式覆盖。', required: true},
     {
       name: 'shape',
       type: "'rectangle' | 'ellipse'",
@@ -133,6 +135,7 @@ export const docsDense = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -144,7 +147,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    ratio: 'width/height ratio (e.g. 16/9, 1)',
+    ratio: 'width/height ratio (e.g. 16/9, 1); class-level declaration (never inline) so xstyle/unlayered-CSS @container overrides win',
     shape: "container shape: 'rectangle' (default) | 'ellipse' (circle at ratio 1)",
     fit: "child layout: 'cover' fill+crop | 'contain' fill+letterbox | 'center' natural size; omitted = child styles itself",
     children: 'content positioned absolutely to fill container',

package/src/AspectRatio/AspectRatio.test.tsx

@@ -13,6 +13,20 @@ import {describe, it, expect, vi, beforeAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
+/**
+ * The ratio compiles to a class-level `aspect-ratio: var(--x-aspectRatio)`
+ * declaration with the value carried by a CSS variable (so xstyle/@media
+ * and unlayered consumer CSS overrides can win). `--x-aspectRatio` is the
+ * debug-mode variable name emitted for the `aspectRatio` property.
+ */
+function ratioVar(el: HTMLElement): string {
+  return el.style.getPropertyValue('--x-aspectRatio');
+}
+
+function ratioValue(ratio: number): string {
+  return String(ratio);
+}
+
 describe('AspectRatio', () => {
   it('renders with correct aspect ratio', () => {
     render(
@@ -22,7 +36,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     expect(element).toBeInTheDocument();
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
   });
 
   it('children fill the container', () => {
@@ -47,7 +61,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 4:3 ratio', () => {
@@ -58,7 +72,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 1:1 square ratio', () => {
@@ -68,7 +82,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
   });
 
   it('renders with 21:9 ultrawide ratio', () => {
@@ -79,7 +93,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
@@ -89,7 +103,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('ellipse');
   });
 
@@ -101,7 +115,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     // Ratio is preserved — the ellipse does not force 1:1.
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     expect(element.className).toContain('ellipse');
   });
 
@@ -112,7 +126,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('rectangle');
     // No ellipse border-radius when shape is the default rectangle
     expect(element.style.borderRadius).toBe('');
@@ -177,6 +191,38 @@ describe('AspectRatio', () => {
     expect(video).toBeInTheDocument();
   });
 
+  describe('responsive ratio', () => {
+    it('emits the ratio as a class-level declaration, not an inline style', () => {
+      render(
+        <AspectRatio ratio={3 / 1} data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // No inline aspect-ratio — the declaration lives in a class reading a
+      // CSS variable, so @media/@container rules (via xstyle, or via
+      // unlayered consumer CSS beating the astryx-base layer) can override
+      // it.
+      expect(element.style.aspectRatio).toBe('');
+      expect(ratioVar(element)).toBe(ratioValue(3 / 1));
+    });
+
+    it('lets a consumer inline style win over the class-level ratio', () => {
+      render(
+        <AspectRatio
+          ratio={3 / 1}
+          style={{aspectRatio: '3 / 2'}}
+          data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // The consumer's style prop passes through untouched (it is no longer
+      // merged with a component-owned inline aspect-ratio).
+      expect(element.style.aspectRatio).toBe('3 / 2');
+    });
+  });
+
   describe('fit', () => {
     it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="cover"', () => {
       render(
@@ -277,7 +323,7 @@ describe('AspectRatio', () => {
   });
 
   describe('style merging', () => {
-    it('keeps the consumer style and applies the ratio over it', () => {
+    it('keeps the consumer style and lets an inline ratio win', () => {
       render(
         <AspectRatio
           ratio={16 / 9}
@@ -288,7 +334,8 @@ describe('AspectRatio', () => {
       );
       const element = screen.getByTestId('aspect-ratio');
       expect(element.style.opacity).toBe('0.5');
-      expect(element.style.aspectRatio).toBe(String(16 / 9));
+      expect(element.style.aspectRatio).toBe('3 / 1');
+      expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     });
 
     it('keeps a consumer className beside the theme target', () => {

package/src/AspectRatio/AspectRatio.tsx

@@ -43,6 +43,25 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+   *
+   * The ratio is emitted as a class-level declaration — never an inline
+   * style — so it can be made responsive:
+   * - StyleX consumers pass an `aspect-ratio` rule via `xstyle`, including
+   *   under `@media`/`@container` conditions.
+   * - Plain-CSS/Tailwind consumers override `aspect-ratio` from their own
+   *   (unlayered) rules: the compiled component styles live in the
+   *   `astryx-base` cascade layer, and unlayered CSS wins over layered
+   *   rules regardless of specificity.
+   *
+   * @example
+   * ```
+   * // 3:1 hero that becomes 3:2 when its container stacks
+   * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
+   *
+   * // CSS: @container gallery (max-width: 720px) {
+   * //   .gallery-hero { aspect-ratio: 3 / 2; }
+   * // }
+   * ```
    */
   ratio: number;
 
@@ -132,6 +151,20 @@ const styles = stylex.create({
   },
 });
 
+// The ratio compiles to a CSS variable + a class-level declaration
+// (aspect-ratio: var(--x)) instead of a raw inline style, so consumer
+// overrides — `xstyle` rules, including ones inside @media/@container
+// queries — can still win. A raw inline `aspect-ratio` would beat any class
+// (same rationale as Grid's dynamic track values). Non-StyleX consumers
+// don't need a dedicated hook: the compiled declaration sits in the
+// `astryx-base` cascade layer, so any unlayered consumer rule wins
+// regardless of specificity.
+const dynamicStyles = stylex.create({
+  ratio: (ratio: number) => ({
+    aspectRatio: ratio,
+  }),
+});
+
 /**
  * AspectRatio component for maintaining a specific aspect ratio for its children.
  *
@@ -147,6 +180,11 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or
@@ -188,11 +226,12 @@ export function AspectRatio({
         themeProps('aspect-ratio', {shape}),
         stylex.props(
           styles.container,
+          dynamicStyles.ratio(ratio),
           shape === 'ellipse' && styles.ellipse,
           xstyle,
         ),
         className,
-        {...style, aspectRatio: ratio},
+        style,
       )}
       {...props}>
       {/* The marker attribute carries the fit value so the reset.css child

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-button-group', visualProps: ['size', 'orientation']},
+      {className: 'astryx-button-group', visualProps: ['size', 'orientation', 'elevation']},
     ],
   },
   components: [
@@ -46,6 +46,8 @@ export const docs = {
       {guidance: false, description: "Don't mix wildly different actions. A Save button next to a Delete button in the same group is confusing."},
       {guidance: false, description: "Don't use ButtonGroup for navigation. Use SegmentedControl or TabList for switching between views."},
       {guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},
+      {guidance: true, description: 'Name the group for what its buttons act on. The label is the group\u2019s accessible name and a screen reader reads it before each member.'},
+      {guidance: false, description: "Don't disable the group to show that an action is in flight. A disabled member drops focus, so a keyboard user loses their place; leave the group enabled and show progress on the button that started the work."},
     ],
     anatomy: [
       {name: 'Button', required: true, description: 'One or more Button or IconButton children that form the connected group.'},
@@ -84,6 +86,8 @@ export const docsZh = {
       {guidance: false, description: '不要混合差异很大的操作，将保存按钮和删除按钮放在同一组中会令人困惑。'},
       {guidance: false, description: '不要使用 ButtonGroup 进行导航，使用 SegmentedControl 或 TabList 切换视图。'},
       {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组，请并排放置并留有间隔。'},
+      {guidance: true, description: '按钮组的标签应说明这些按钮作用于什么。该标签是按钮组的无障碍名称，屏幕阅读器会在每个成员之前朗读它。'},
+      {guidance: false, description: '不要用禁用整个按钮组来表示操作进行中。禁用的成员会失去焦点，键盘用户会丢失位置；请保持按钮组可用，并在发起操作的按钮上显示进度。'},
     ],
     anatomy: [
       {name: '按钮', required: true, description: '一个或多个 Button 或 IconButton 子元素，形成连接的组。'},
@@ -105,6 +109,8 @@ export const docsDense = {
       {guidance: false, description: "Don't mix unrelated actions in one group."},
       {guidance: false, description: "Don't use for navigation. Use SegmentedControl or TabList."},
       {guidance: false, description: "Don't nest ButtonGroups."},
+      {guidance: true, description: 'Label the group for what its buttons act on; it is the accessible name.'},
+      {guidance: false, description: "Don't disable the group for an in-flight action; a disabled member drops focus."},
     ],
   },
   components: [

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -12,7 +12,8 @@
  */
 
 import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {transformSync} from '@babel/core';
 import stylexBabelPlugin from '@stylexjs/babel-plugin';
 import {readFileSync} from 'node:fs';
@@ -611,5 +612,188 @@ describe('ButtonGroup', () => {
         none.querySelector('[role="group"]')!.className,
       );
     });
+
+    it('exposes the elevation to a theme as a data attribute', () => {
+      render(
+        <ButtonGroup label="Actions" elevation="high">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+
+      expect(screen.getByRole('group')).toHaveAttribute(
+        'data-elevation',
+        'high',
+      );
+    });
+  });
+
+  // ===========================================================================
+  // Keyboard navigation
+  //
+  // The group wires useListFocus, so arrow keys move focus between members.
+  // The last two tests cover the boundary: a member can own a layer, whose
+  // keys belong to that layer, and the group itself can sit inside a layer,
+  // whose keys are still the group's own. Both must hold at once.
+  // ===========================================================================
+  describe('keyboard navigation', () => {
+    const clipboard = (
+      <ButtonGroup label="Actions">
+        <Button label="Copy" />
+        <Button label="Cut" />
+        <Button label="Paste" />
+      </ButtonGroup>
+    );
+
+    it('moves focus between members with the arrow keys, wrapping at the end', async () => {
+      const user = userEvent.setup();
+      render(clipboard);
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowRight}{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+
+      await user.keyboard('{ArrowLeft}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+    });
+
+    it('jumps to the first and last member with Home and End', async () => {
+      const user = userEvent.setup();
+      render(clipboard);
+
+      screen.getByRole('button', {name: 'Cut'}).focus();
+
+      await user.keyboard('{End}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+
+      await user.keyboard('{Home}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('uses the vertical arrows when the group is vertical', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Actions" orientation="vertical">
+          <Button label="Copy" />
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowDown}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowUp}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('follows visual direction in RTL', async () => {
+      const user = userEvent.setup();
+      // dir sits on the group because jsdom resolves computed direction from
+      // the element's own attribute, not from an ancestor.
+      render(
+        <ButtonGroup label="Actions" dir="rtl">
+          <Button label="Copy" />
+          <Button label="Cut" />
+          <Button label="Paste" />
+        </ButtonGroup>,
+      );
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowLeft}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('skips a disabled member', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" />
+          <Button label="Cut" isDisabled />
+          <Button label="Paste" />
+        </ButtonGroup>,
+      );
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+    });
+
+    it('leaves arrow keys to a member\u2019s open menu', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Approve action">
+          <Button label="Allow once" />
+          <DropdownMenu
+            hasChevron={false}
+            button={{label: 'Allow options', isIconOnly: true}}
+            items={[{label: 'Allow for 30 minutes'}, {label: 'Always allow'}]}
+          />
+        </ButtonGroup>,
+      );
+
+      await user.click(screen.getByRole('button', {name: /Allow options/}));
+      const item = screen.getByRole('menuitem', {
+        name: 'Allow for 30 minutes',
+        hidden: true,
+      });
+      item.focus();
+
+      // Assert positively: the menu item keeps focus. `.not.toHaveFocus()` on
+      // the group's buttons would also pass if the group had thrown focus
+      // somewhere else entirely.
+      fireEvent.keyDown(item, {key: 'ArrowRight'});
+      expect(item).toHaveFocus();
+
+      fireEvent.keyDown(item, {key: 'ArrowLeft'});
+      expect(item).toHaveFocus();
+
+      // End belongs to the menu's own list focus, so it lands on the last menu
+      // item rather than the group's last button.
+      fireEvent.keyDown(item, {key: 'End'});
+      expect(
+        screen.getByRole('menuitem', {name: 'Always allow', hidden: true}),
+      ).toHaveFocus();
+    });
+
+    it('still moves between its own members when the group sits inside a popover', async () => {
+      const user = userEvent.setup();
+      // A group rendered inside a Popover, ContextMenu, HoverCard or Toast has
+      // a `[popover]` ancestor, because that is how useLayer mounts a layer.
+      // A bare `popover` div is the same DOM fact without the layer harness.
+      render(
+        <div popover="manual">
+          <ButtonGroup label="Actions">
+            <Button label="Copy" />
+            <Button label="Cut" />
+            <Button label="Paste" />
+          </ButtonGroup>
+        </div>,
+      );
+
+      // A closed popover is display:none in jsdom, so its contents read as
+      // inaccessible; focus and key handling still work on them.
+      const button = (name: string) =>
+        screen.getByRole('button', {name, hidden: true});
+
+      button('Copy').focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(button('Cut')).toHaveFocus();
+
+      await user.keyboard('{End}');
+      expect(button('Paste')).toHaveFocus();
+
+      await user.keyboard('{Home}');
+      expect(button('Copy')).toHaveFocus();
+    });
   });
 });

package/src/ButtonGroup/ButtonGroup.tsx

@@ -172,6 +172,13 @@ export function ButtonGroup({
 
   const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
     itemSelector: 'button, [tabindex="0"]',
+    // A member's layer renders inline inside the group (useLayer does not
+    // portal it), so a key pressed in an open DropdownMenu bubbles here. The
+    // boundary is the group's own root or any layer, whichever is nearer to
+    // the target. Naming the group's own root is what keeps a group rendered
+    // inside a Popover or Toast working: bailing on any [popover] ancestor
+    // instead would swallow every arrow key it owns.
+    boundarySelector: '[role="group"], [popover]',
     orientation,
   });
 
@@ -187,7 +194,7 @@ export function ButtonGroup({
           ref={mergeRefs(ref, listRef)}
           {...props}
           {...mergeProps(
-            themeProps('button-group', {size, orientation}),
+            themeProps('button-group', {size, orientation, elevation}),
             stylex.props(
               styles.group,
               orientation === 'vertical' && styles.vertical,

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -229,7 +229,7 @@ describe('useTablePagination', () => {
       ).toBeTruthy();
     });
 
-    it('transformTableContext renders Pagination above and below', () => {
+    it('transformTableContext renders distinctly named Pagination above and below', () => {
       render(
         <PaginatedTable
           data={generateItems(30)}
@@ -237,10 +237,40 @@ describe('useTablePagination', () => {
           position="both"
         />,
       );
-      const navs = screen.getAllByRole('navigation', {
-        name: 'Table pagination',
+      const table = screen.getByRole('table');
+      // Each nav landmark gets a unique accessible name (axe landmark-unique)
+      const topNav = screen.getByRole('navigation', {
+        name: 'Table pagination (top)',
+      });
+      const bottomNav = screen.getByRole('navigation', {
+        name: 'Table pagination (bottom)',
       });
-      expect(navs).toHaveLength(2);
+      // Top nav comes before the table, bottom nav after it in DOM order
+      expect(
+        table.compareDocumentPosition(topNav) &
+          Node.DOCUMENT_POSITION_PRECEDING,
+      ).toBeTruthy();
+      expect(
+        table.compareDocumentPosition(bottomNav) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('position="both" interpolates a consumer label into distinct nav names', () => {
+      render(
+        <PaginatedTable
+          data={generateItems(30)}
+          pageSize={10}
+          position="both"
+          label="Users table"
+        />,
+      );
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (top)'}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (bottom)'}),
+      ).toBeInTheDocument();
     });
 
     it('transformTableContext does not render Pagination when position is none', () => {

package/src/Table/plugins/pagination/useTablePagination.tsx

@@ -164,6 +164,9 @@ export interface UseTablePaginationConfig {
 
   /**
    * Accessible label for the pagination nav landmark.
+   * When `position` is 'both', the two navs get distinct names by suffixing
+   * this label — "{label} (top)" above and "{label} (bottom)" below — so
+   * same-type landmarks stay distinguishable to assistive technology.
    * @default 'Table pagination'
    */
   label?: string;
@@ -211,6 +214,10 @@ export function useTablePagination<T extends Record<string, unknown>>(
     label: labelFromProps,
   } = config;
   const label = labelFromProps ?? t('@astryx.table.pagination.label');
+  // position='both' renders two nav landmarks; suffix the base label so each
+  // gets a unique accessible name (axe landmark-unique).
+  const labelAbove = t('@astryx.table.pagination.labelAbove', {label});
+  const labelBelow = t('@astryx.table.pagination.labelBelow', {label});
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
@@ -240,8 +247,20 @@ export function useTablePagination<T extends Record<string, unknown>>(
 
   // Keep current config in a ref so the plugin can read the latest values
   // without needing to recreate the plugin object on every change.
-  const configRef = useRef({paginationProps, position, align});
-  configRef.current = {paginationProps, position, align};
+  const configRef = useRef({
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  });
+  configRef.current = {
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  };
 
   // Stable plugin object \u2014 created once, reads config via ref.
   return useMemo(
@@ -251,6 +270,8 @@ export function useTablePagination<T extends Record<string, unknown>>(
           position: pos,
           paginationProps: props,
           align: a,
+          labelAbove: above,
+          labelBelow: below,
         } = configRef.current;
         if (pos === 'none') {
           return children;
@@ -277,7 +298,18 @@ export function useTablePagination<T extends Record<string, unknown>>(
               a === 'end' && styles.alignEnd,
               a === 'start' && styles.alignStart,
             )}>
-            <Pagination {...props} />
+            <Pagination
+              {...props}
+              // Two navs with the same name are indistinguishable landmarks;
+              // give each side a unique name when both render.
+              label={
+                pos === 'both'
+                  ? side === 'above'
+                    ? above
+                    : below
+                  : props.label
+              }
+            />
           </div>
         );
 

package/src/Table/useTablePagination.doc.mjs

@@ -72,6 +72,12 @@ export const docs = {
       description: 'Horizontal alignment of the pagination controls.',
       default: "'center'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: "Accessible name for the pagination nav landmark. With position='both' the two navs get distinct names — the label suffixed as '(top)' and '(bottom)' — so same-type landmarks stay unique (axe landmark-unique).",
+      default: "'Table pagination'",
+    },
   ],
 };
 
@@ -129,5 +135,6 @@ export const docsDense = {
     pageSize: 'Items per page. Default 10.',
     variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
     position: "Render position: 'below'|'above'|'both'|'none'.",
+    label: "Accessible name for the nav landmark; position='both' emits '<label> (top)' / '<label> (bottom)'.",
   },
 };

package/src/__tests__/apiContractDrift.test.tsx

@@ -1,80 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-import {docs as ButtonDocs} from '../Button/Button.doc.mjs';
-import {docs as ContextMenuDocs} from '../ContextMenu/ContextMenu.doc.mjs';
-import {docs as DialogDocs} from '../Dialog/Dialog.doc.mjs';
-import {docs as LinkDocs} from '../Link/Link.doc.mjs';
-import {docs as MoreMenuDocs} from '../MoreMenu/MoreMenu.doc.mjs';
-import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
-import {docs as PowerSearchDocs} from '../PowerSearch/PowerSearch.doc.mjs';
-import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
-import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
-import {docs as ToastDocs} from '../Toast/Toast.doc.mjs';
-import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
-
-// `docs` is the ComponentDoc union (single vs multi component); narrow it
-// for structural access to either the top-level props or the first
-// sub-component's props.
-function getProps(docs: unknown): {name: string}[] {
-  const doc = docs as {
-    props?: {name: string}[];
-    components?: {props?: {name: string}[]}[];
-  };
-  return doc.props || doc.components?.[0]?.props || [];
-}
-
-describe('API Contract Drift Audit (#4163)', () => {
-  it('documents Button link mode props', () => {
-    const props = getProps(ButtonDocs).map(p => p.name);
-    expect(props).toContain('href');
-    expect(props).toContain('as');
-    expect(props).toContain('target');
-    expect(props).toContain('rel');
-  });
-
-  it('documents Toast onDismiss callback', () => {
-    const props = getProps(ToastDocs).map(p => p.name);
-    expect(props).toContain('onDismiss');
-  });
-
-  it('documents ContextMenu and MoreMenu onOpenChange callback', () => {
-    const contextProps = getProps(ContextMenuDocs).map(p => p.name);
-    const moreProps = getProps(MoreMenuDocs).map(p => p.name);
-    expect(contextProps).toContain('onOpenChange');
-    expect(moreProps).toContain('onOpenChange');
-  });
-
-  it('documents Selector startIcon and isLoading props', () => {
-    const props = getProps(SelectorDocs).map(p => p.name);
-    expect(props).toContain('startIcon');
-    expect(props).toContain('isLoading');
-  });
-
-  it('documents TextInput and NumberInput onEnter / onKeyDown callbacks', () => {
-    const textProps = getProps(TextInputDocs).map(p => p.name);
-    const numProps = getProps(NumberInputDocs).map(p => p.name);
-    expect(textProps).toContain('onEnter');
-    expect(textProps).toContain('onKeyDown');
-    expect(numProps).toContain('onEnter');
-    expect(numProps).toContain('onKeyDown');
-  });
-
-  it('documents PowerSearch and Tokenizer onFocus / onBlur callbacks', () => {
-    const powerProps = getProps(PowerSearchDocs).map(p => p.name);
-    const tokProps = getProps(TokenizerDocs).map(p => p.name);
-    expect(powerProps).toContain('onFocus');
-    expect(powerProps).toContain('onBlur');
-    expect(tokProps).toContain('onFocus');
-    expect(tokProps).toContain('onBlur');
-  });
-
-  it('documents Link download / referrerPolicy and Dialog padding props', () => {
-    const linkProps = getProps(LinkDocs).map(p => p.name);
-    const dialogProps = getProps(DialogDocs).map(p => p.name);
-    expect(linkProps).toContain('download');
-    expect(linkProps).toContain('referrerPolicy');
-    expect(dialogProps).toContain('padding');
-  });
-});

package/src/__tests__/fieldContract.test.tsx

@@ -1,24 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-import {docs as FieldDocs} from '../Field/Field.doc.mjs';
-
-// `docs` is the ComponentDoc union (single vs multi component); narrow it
-// for structural access to either the top-level props or the first
-// sub-component's props.
-function getProps(docs: unknown): {name: string}[] {
-  const doc = docs as {
-    props?: {name: string}[];
-    components?: {props?: {name: string}[]}[];
-  };
-  return doc.props || doc.components?.[0]?.props || [];
-}
-
-describe('Field Component API Contract Drift (#4163)', () => {
-  it('documents Field labelID and isGroupLabel props', () => {
-    const props = getProps(FieldDocs).map(p => p.name);
-    expect(props).toContain('labelID');
-    expect(props).toContain('isGroupLabel');
-  });
-});

package/src/__tests__/inputWidthContract.test.tsx

@@ -1,69 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-import {docs as CheckboxInputDocs} from '../CheckboxInput/CheckboxInput.doc.mjs';
-import {docs as CheckboxListDocs} from '../CheckboxList/CheckboxList.doc.mjs';
-import {docs as DateInputDocs} from '../DateInput/DateInput.doc.mjs';
-import {docs as DateRangeInputDocs} from '../DateRangeInput/DateRangeInput.doc.mjs';
-import {docs as DateTimeInputDocs} from '../DateTimeInput/DateTimeInput.doc.mjs';
-import {docs as FileInputDocs} from '../FileInput/FileInput.doc.mjs';
-import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
-import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
-import {docs as RadioListDocs} from '../RadioList/RadioList.doc.mjs';
-import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
-import {docs as SliderDocs} from '../Slider/Slider.doc.mjs';
-import {docs as SwitchDocs} from '../Switch/Switch.doc.mjs';
-import {docs as TextAreaDocs} from '../TextArea/TextArea.doc.mjs';
-import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
-import {docs as TimeInputDocs} from '../TimeInput/TimeInput.doc.mjs';
-import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
-import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
-
-const inputDocsSuite = [
-  {name: 'CheckboxInput', docs: CheckboxInputDocs},
-  {name: 'CheckboxList', docs: CheckboxListDocs},
-  {name: 'DateInput', docs: DateInputDocs},
-  {name: 'DateRangeInput', docs: DateRangeInputDocs},
-  {name: 'DateTimeInput', docs: DateTimeInputDocs},
-  {name: 'FileInput', docs: FileInputDocs},
-  {name: 'MultiSelector', docs: MultiSelectorDocs},
-  {name: 'NumberInput', docs: NumberInputDocs},
-  {name: 'RadioList', docs: RadioListDocs},
-  {name: 'Selector', docs: SelectorDocs},
-  {name: 'Slider', docs: SliderDocs},
-  {name: 'Switch', docs: SwitchDocs},
-  {name: 'TextArea', docs: TextAreaDocs},
-  {name: 'TextInput', docs: TextInputDocs},
-  {name: 'TimeInput', docs: TimeInputDocs},
-  {name: 'Tokenizer', docs: TokenizerDocs},
-  {name: 'Typeahead', docs: TypeaheadDocs},
-];
-
-describe('Input Family width Prop Contract (#4163)', () => {
-  inputDocsSuite.forEach(({name, docs}) => {
-    it(`documents the width prop for ${name}`, () => {
-      // `docs` is the ComponentDoc union (single vs multi component); narrow it
-      // for structural access to either the top-level props or the first
-      // sub-component's props.
-      const doc = docs as {
-        props?: {name: string; type: string}[];
-        components?: {props?: {name: string; type: string}[]}[];
-      };
-      const propsList = (doc.props || doc.components?.[0]?.props) as {
-        name: string;
-        type: string;
-      }[];
-      expect(
-        propsList,
-        `${name}.doc.mjs must expose a props array`,
-      ).toBeDefined();
-      const widthProp = propsList.find(p => p.name === 'width');
-      expect(
-        widthProp,
-        `${name}.doc.mjs must document the width prop`,
-      ).toBeDefined();
-      expect(widthProp?.type).toBe('SizeValue');
-    });
-  });
-});

package/src/__tests__/structuralComponentContract.test.tsx

@@ -1,39 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-import {docs as CodeBlockDocs} from '../CodeBlock/CodeBlock.doc.mjs';
-import {docs as StackDocs} from '../Stack/Stack.doc.mjs';
-import {docs as ToolbarDocs} from '../Toolbar/Toolbar.doc.mjs';
-
-// `docs` is the ComponentDoc union (single vs multi component); narrow it
-// for structural access to either the top-level props or the first
-// sub-component's props.
-function getProps(docs: unknown): {name: string}[] {
-  const doc = docs as {
-    props?: {name: string}[];
-    components?: {props?: {name: string}[]}[];
-  };
-  return doc.props || doc.components?.[0]?.props || [];
-}
-
-describe('Structural Component API Contract Drift (#4163)', () => {
-  it('documents CodeBlock highlightMode prop', () => {
-    const props = getProps(CodeBlockDocs).map(p => p.name);
-    expect(props).toContain('highlightMode');
-  });
-
-  it('documents Toolbar dividers prop', () => {
-    const props = getProps(ToolbarDocs).map(p => p.name);
-    expect(props).toContain('dividers');
-  });
-
-  it('documents Stack direction and base props', () => {
-    const props = getProps(StackDocs).map(p => p.name);
-    expect(props).toContain('direction');
-    expect(props).toContain('gap');
-    expect(props).toContain('padding');
-    expect(props).toContain('width');
-    expect(props).toContain('height');
-  });
-});