@astryxdesign/core 0.7.9-canary.9bd11b3 → 0.7.9-canary.cb2a34a

package/dist/AppShell/observeMainOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observeMainOverflow.d.ts","sourceRoot":"","sources":["../../src/AppShell/observeMainOverflow.ts"],"names":[],"mappings":"AAyCA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GACrC,MAAM,IAAI,CA2FZ"}
+{"version":3,"file":"observeMainOverflow.d.ts","sourceRoot":"","sources":["../../src/AppShell/observeMainOverflow.ts"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GACrC,MAAM,IAAI,CA2FZ"}

package/dist/AppShell/observeMainOverflow.js

@@ -4,20 +4,23 @@
 
 /**
  * @file observeMainOverflow.ts
- * @input AppShell's main region under `height="fill"`: its own scroll
- *   container, holding its content as direct children with no wrapper
+ * @input A scroll container that holds its content as direct children with
+ *   no wrapper: AppShell's main region under `height="fill"`, or a scrolling
+ *   LayoutContent, LayoutPanel or StackItem
  * @output observeMainOverflow(main, onChange): reports whether main's content
  *   overflows it on either axis, once at the start and on every change, and
  *   returns the function that stops observing
- * @position Internal to AppShell and never exported. AppShell makes main a
+ * @position Internal and never exported. AppShell makes main a
  *   keyboard stop only while it overflows (`spec:AST-025` FR12,
- *   `component:AppShell` FR4 and PR1). Main has no inner content box, so its
- *   content grows inside it without resizing it: its direct children's sizes
- *   are watched instead.
+ *   `component:AppShell` FR4 and PR1). useScrollRegionProps names a
+ *   scrolling region only while it overflows. Main has no inner content
+ *   box, so its content grows inside it without resizing it: its direct
+ *   children's sizes are watched instead.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/AppShell/AppShell.tsx
  * - /packages/core/src/AppShell/observeMainOverflow.test.ts
+ * - /packages/core/src/hooks/useScrollRegionProps.ts
  */
 import { getLogicalAxisMapping, measureLogicalScrollAxis } from "../hooks/scrollGeometry.js";
 import { observeMutations } from "../utils/sharedMutationObserver.js";

package/dist/InputGroup/InputGroup.d.ts

@@ -59,7 +59,8 @@ export interface InputGroupProps extends Omit<BaseProps<HTMLDivElement>, 'childr
      */
     size?: InputGroupSize;
     /**
-     * Status indicator applied to the group border.
+     * Validation status. Its message shows below the group. The group border
+     * does not change; a theme can style the row from `data-status`.
      */
     status?: InputStatus;
     /**
@@ -72,8 +73,8 @@ export interface InputGroupProps extends Omit<BaseProps<HTMLDivElement>, 'childr
     'data-testid'?: string;
 }
 /**
- * Groups an input with prefix/suffix addons in a visually connected
- * container with shared border and focus ring.
+ * Groups an input with prefix and suffix addons in one connected row. A
+ * focused member stays above its neighbours, so its focus ring shows in full.
  *
  * @example
  * ```

package/dist/InputGroup/InputGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InputGroup.d.ts","sourceRoot":"","sources":["../../src/InputGroup/InputGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG1D,OAAO,EAAQ,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAGjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AA0BhD,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,mDAAmD;IACnD,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,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,UAAU,EAAE,cAAsB,EAClC,UAAkB,EAClB,UAAkB,EAClB,IAAI,EAAE,QAAQ,EACd,MAAM,EACN,YAAY,EACZ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,eAAe,+BA8EjB;yBA/Fe,UAAU"}
+{"version":3,"file":"InputGroup.d.ts","sourceRoot":"","sources":["../../src/InputGroup/InputGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG1D,OAAO,EAAQ,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAGjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AA0BhD,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,mDAAmD;IACnD,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,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,UAAU,EAAE,cAAsB,EAClC,UAAkB,EAClB,UAAkB,EAClB,IAAI,EAAE,QAAQ,EACd,MAAM,EACN,YAAY,EACZ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,eAAe,+BA8EjB;yBA/Fe,UAAU"}

package/dist/InputGroup/InputGroup.js

@@ -57,8 +57,8 @@ const sizeStyles = {
   }
 };
 /**
- * Groups an input with prefix/suffix addons in a visually connected
- * container with shared border and focus ring.
+ * Groups an input with prefix and suffix addons in one connected row. A
+ * focused member stays above its neighbours, so its focus ring shows in full.
  *
  * @example
  * ```

package/dist/InputGroup/groupStyles.d.ts

@@ -33,7 +33,7 @@ export declare const groupStyles: Readonly<{
         readonly borderStartEndRadius: stylex.StyleXClassNameFor<"borderStartEndRadius", 0 | "8px">;
         readonly borderEndEndRadius: stylex.StyleXClassNameFor<"borderEndEndRadius", 0 | "8px">;
         readonly ':focus-within': stylex.StyleXClassNameFor<":focus-within", {
-            readonly zIndex: 1;
+            readonly zIndex: 2;
         }>;
     }>;
 }>;

package/dist/InputGroup/groupStyles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"groupStyles.d.ts","sourceRoot":"","sources":["../../src/InputGroup/groupStyles.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;CAEtB,CAAC;AA0BX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;EAwDtB,CAAC"}
+{"version":3,"file":"groupStyles.d.ts","sourceRoot":"","sources":["../../src/InputGroup/groupStyles.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;CAEtB,CAAC;AA0BX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;EA0DtB,CAAC"}

package/dist/InputGroup/groupStyles.js

@@ -62,7 +62,7 @@ export const groupStyles = {
     kVL7Gh: "xbiv7yw x1xrp5p4",
     kfmiAY: "x1ga7v0g x1ursdma",
     kT0f0o: "x16uus16 x1qa286i",
-    kXnDq0: "x1rm9qnc",
+    kXnDq0: "x1pc0aet",
     $$css: true
   }
 };

package/dist/Layout/LayoutContent.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file LayoutContent.tsx
- * @input Uses React StyleX, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutSlotsContext, useScrollRegionProps
  * @output Exports LayoutContent component and LayoutContentProps
  * @position Scrollable main content area for Layout. Wraps the primary body content
  *   with automatic scroll containment and context-aware padding.
@@ -35,6 +35,8 @@ export interface LayoutContentProps extends BaseProps<HTMLDivElement> {
     /**
      * Accessible label for the landmark.
      * Required when role is set and multiple landmarks of the same type exist.
+     * While the content scrolls, it also names the scrolling region, which
+     * otherwise takes a translated "Content".
      */
     label?: string;
     /**

package/dist/Layout/LayoutContent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LayoutContent.d.ts","sourceRoot":"","sources":["../../src/Layout/LayoutContent.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAqFhD,MAAM,WAAW,kBAAmB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACnE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,YAAmB,EACnB,OAAO,EACP,KAAK,EACL,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,kBAAkB,+BAkDpB;yBA7De,aAAa"}
+{"version":3,"file":"LayoutContent.d.ts","sourceRoot":"","sources":["../../src/Layout/LayoutContent.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAqFhD,MAAM,WAAW,kBAAmB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACnE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,YAAmB,EACnB,OAAO,EACP,KAAK,EACL,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,kBAAkB,+BAoDpB;yBA/De,aAAa"}

package/dist/Layout/LayoutContent.js

@@ -4,7 +4,7 @@
 
 /**
  * @file LayoutContent.tsx
- * @input Uses React StyleX, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutSlotsContext, useScrollRegionProps
  * @output Exports LayoutContent component and LayoutContentProps
  * @position Scrollable main content area for Layout. Wraps the primary body content
  *   with automatic scroll containment and context-aware padding.
@@ -19,6 +19,8 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars } from "../theme/tokens.stylex.js";
 import { LayoutSlotsContext } from "./LayoutSlotsContext.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { useScrollRegionProps } from "../hooks/useScrollRegionProps.js";
 import { mergeProps } from "../utils/mergeProps.js";
 import { themeProps } from "../utils/themeProps.js";
 import { paddingStyles, containerPaddingInlineVarStyles, containerPaddingBlockStartVarStyles, containerPaddingBlockEndVarStyles } from "./padding.stylex.js";
@@ -146,10 +148,16 @@ export function LayoutContent({
     hasEnd
   } = use(LayoutSlotsContext);
   const isZeroPadding = padding === 0;
+  const region = useScrollRegionProps({
+    isScrollable,
+    role,
+    label
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
   return /*#__PURE__*/_jsx("div", {
-    ref: ref,
-    role: role,
-    "aria-label": label,
+    ref: mergedRef,
+    role: region.role,
+    "aria-label": region['aria-label'],
     ...mergeProps(themeProps('layout-content'), stylex.props(styles.content,
     // Outer padding on container edges (unless content is full bleed)
     !hasStart && !isZeroPadding && padding == null && styles.noStart, !hasEnd && !isZeroPadding && padding == null && styles.noEnd, !hasHeader && !isZeroPadding && padding == null && styles.noHeader, !hasFooter && !isZeroPadding && padding == null && styles.noFooter, isScrollable && styles.scrollable, isZeroPadding && styles.fullBleed, padding != null && paddingStyles[padding], padding != null && containerPaddingInlineVarStyles[padding], padding != null && containerPaddingBlockStartVarStyles[padding], padding != null && containerPaddingBlockEndVarStyles[padding], !hasStart && !hasEnd && !isZeroPadding && styles.constrainedNoPanelsStart, !hasStart && !hasEnd && !isZeroPadding && styles.constrainedNoPanelsEnd, hasStart && !hasEnd && !isZeroPadding && styles.constrainedSingleStartPanel, !hasStart && hasEnd && !isZeroPadding && styles.constrainedSingleEndPanel, xstyle), className, style),

package/dist/Layout/LayoutPanel.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file LayoutPanel.tsx
- * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext,
+ *   useScrollRegionProps
  * @output Exports LayoutPanel component and LayoutPanelProps
  * @position Sidebar panel for Layout start/end slots. Use for navigation panels,
  *   settings sidebars, detail panels, or any fixed-width side content.
@@ -47,6 +48,8 @@ export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {
     /**
      * Accessible label for the landmark.
      * Required when role is set and multiple landmarks of the same type exist.
+     * While the panel scrolls, it also names the scrolling region, which
+     * otherwise takes a translated "Content".
      */
     label?: string;
     /**

package/dist/Layout/LayoutPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LayoutPanel.d.ts","sourceRoot":"","sources":["../../src/Layout/LayoutPanel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C,OAAO,KAAK,EAAC,SAAS,EAAE,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAmF9D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,UAAkB,EAClB,YAAmB,EACnB,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAkElB;yBAhFe,WAAW"}
+{"version":3,"file":"LayoutPanel.d.ts","sourceRoot":"","sources":["../../src/Layout/LayoutPanel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAE,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAmF9D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,UAAkB,EAClB,YAAmB,EACnB,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoElB;yBAlFe,WAAW"}

package/dist/Layout/LayoutPanel.js

@@ -4,7 +4,8 @@
 
 /**
  * @file LayoutPanel.tsx
- * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext,
+ *   useScrollRegionProps
  * @output Exports LayoutPanel component and LayoutPanelProps
  * @position Sidebar panel for Layout start/end slots. Use for navigation panels,
  *   settings sidebars, detail panels, or any fixed-width side content.
@@ -20,6 +21,8 @@ import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars } from "../theme/tokens.stylex.js";
 import { LayoutAreaContext } from "./LayoutAreaContext.js";
 import { LayoutSlotsContext } from "./LayoutSlotsContext.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { useScrollRegionProps } from "../hooks/useScrollRegionProps.js";
 import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { paddingStyles, containerPaddingInlineVarStyles, containerPaddingBlockStartVarStyles, containerPaddingBlockEndVarStyles } from "./padding.stylex.js";
@@ -160,6 +163,12 @@ export function LayoutPanel({
 
   // When no divider, collapse spacing for seamless visual flow
   const shouldCollapseSpacing = !hasDivider && !isZeroPadding && padding == null;
+  const region = useScrollRegionProps({
+    isScrollable,
+    role,
+    label
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   // Select divider style based on position
   const dividerStyle = isStartPanel ? styles.dividerEnd : isEndPanel ? styles.dividerStart : null;
@@ -167,9 +176,9 @@ export function LayoutPanel({
   // Select collapse style based on position (collapse the side where divider would be)
   const collapseStyle = isStartPanel ? styles.collapseEnd : isEndPanel ? styles.collapseStart : null;
   return /*#__PURE__*/_jsx("div", {
-    ref: ref,
-    role: role,
-    "aria-label": label,
+    ref: mergedRef,
+    role: region.role,
+    "aria-label": region['aria-label'],
     ...mergeProps(themeProps('layout-panel'), stylex.props(styles.panel, dynamicStyles.sizing(effectiveWidth ?? null),
     // Outer padding on container edges (unless component is full bleed)
     isStartPanel && !isZeroPadding && padding == null && styles.startPanel, isEndPanel && !isZeroPadding && padding == null && styles.endPanel, !hasHeader && !isZeroPadding && padding == null && styles.noHeader, !hasFooter && !isZeroPadding && padding == null && styles.noFooter, isScrollable && styles.scrollable, isZeroPadding && styles.fullBleed, padding != null && paddingStyles[padding], padding != null && containerPaddingInlineVarStyles[padding], padding != null && containerPaddingBlockStartVarStyles[padding], padding != null && containerPaddingBlockEndVarStyles[padding], hasDivider && dividerStyle, shouldCollapseSpacing && collapseStyle, xstyle), className, style),

package/dist/Stack/StackItem.d.ts

@@ -1,8 +1,10 @@
 /**
  * @file StackItem.tsx
- * @input Uses React, ElementType, stackItem utility
+ * @input Uses React, ElementType, stackItem utility, StackItemScrollRegion
  * @output Exports StackItem polymorphic component and StackItemProps
- * @position Layout/Stack component; uses stackItem.stylex.ts
+ * @position Layout/Stack component; uses stackItem.stylex.ts. A scrollable
+ *   `div` or `span` item renders through StackItemScrollRegion, which names
+ *   it while it scrolls.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
@@ -34,7 +36,9 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
      * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
      * region — it grows to fill the stack and scrolls its own overflow with
      * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
-     * and `LayoutPanel`.
+     * and `LayoutPanel`. While its content overflows, a `div` or `span` item
+     * is a group named by the caller's `aria-label`, or by a translated
+     * "Content". Another element keeps its own role.
      * @default false
      */
     isScrollable?: boolean;
@@ -62,7 +66,7 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
  * </HStack>
  * ```
  */
-export declare function StackItem({ crossAlignSelf, size, isScrollable, as: element, xstyle, className, style, children, ref, ...props }: StackItemProps): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+export declare function StackItem({ crossAlignSelf, size, isScrollable, as: element, xstyle, className, style, children, ref, ...props }: StackItemProps): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>> | import("react").FunctionComponentElement<import("../hooks/StackItemScrollRegion.js").StackItemScrollRegionProps>;
 export declare namespace StackItem {
     var displayName: string;
 }

package/dist/Stack/StackItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StackItem.d.ts","sourceRoot":"","sources":["../../src/Stack/StackItem.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAW,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAU5B,MAAM,WAAW,cAAe,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IAEzC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IAErB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EACxB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,EAAE,EAAE,OAAe,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,cAAc,0FAqBhB;yBAhCe,SAAS"}
+{"version":3,"file":"StackItem.d.ts","sourceRoot":"","sources":["../../src/Stack/StackItem.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAW,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAW5B,MAAM,WAAW,cAAe,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IAEzC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EACxB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,EAAE,EAAE,OAAe,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,cAAc,0MA8BhB;yBAzCe,SAAS"}

package/dist/Stack/StackItem.js

@@ -2,9 +2,11 @@
 
 /**
  * @file StackItem.tsx
- * @input Uses React, ElementType, stackItem utility
+ * @input Uses React, ElementType, stackItem utility, StackItemScrollRegion
  * @output Exports StackItem polymorphic component and StackItemProps
- * @position Layout/Stack component; uses stackItem.stylex.ts
+ * @position Layout/Stack component; uses stackItem.stylex.ts. A scrollable
+ *   `div` or `span` item renders through StackItemScrollRegion, which names
+ *   it while it scrolls.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
@@ -16,6 +18,7 @@ import * as stylex from '@stylexjs/stylex';
 import { stackItem } from "./stackItem.stylex.js";
 import { mergeProps } from "../utils/mergeProps.js";
 import { themeProps } from "../utils/themeProps.js";
+import { StackItemScrollRegion } from "../hooks/StackItemScrollRegion.js";
 const overflowStyles = {
   scrollable: {
     kVQacm: "xysyzu8",
@@ -52,12 +55,22 @@ export function StackItem({
     crossAlignSelf,
     size
   }), isScrollable && overflowStyles.scrollable, xstyle);
-  return /*#__PURE__*/createElement(element, {
-    ref: ref,
+  const elementProps = {
     ...mergeProps(themeProps('stack-item', {
       size
     }), stylexProps, className, style),
     ...props
+  };
+  if (isScrollable && (element === 'div' || element === 'span')) {
+    return /*#__PURE__*/createElement(StackItemScrollRegion, {
+      as: element,
+      ref,
+      elementProps
+    }, children);
+  }
+  return /*#__PURE__*/createElement(element, {
+    ref: ref,
+    ...elementProps
   }, children);
 }
 StackItem.displayName = 'StackItem';

package/dist/astryx.css

@@ -1633,7 +1633,7 @@
   .xttggg:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){transform:translateX(100%)}
   .x1nyx83j:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){transform:translateX(50%)}
   .x9cjr8z:popover-open:not(#\#):not(#\#):not(#\#){transform:translateY(0)}
-  .x1rm9qnc:focus-within:not(#\#):not(#\#):not(#\#){z-index:1}
+  .x1pc0aet:focus-within:not(#\#):not(#\#):not(#\#){z-index:2}
   .xf5goe6.xf5goe6:where(.astryx-input-group > [data-astryx-input-group-item]):focus-visible:not(#\#):not(#\#):not(#\#){z-index:2}
   .x151j4nw:has(input[aria-disabled="true"]:focus-visible):not(#\#):not(#\#):not(#\#){box-shadow:inset 0 0 0 2px var(--color-accent-muted)}
   .xwmge8v:has(> [aria-disabled="true"]:focus-visible):not(#\#):not(#\#):not(#\#){box-shadow:inset 0 0 0 2px var(--color-accent-muted)}

package/dist/hooks/StackItemScrollRegion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { type AriaRole, type ReactNode, type Ref } from 'react';
+export interface StackItemScrollRegionProps {
+    as: 'div' | 'span';
+    ref?: Ref<HTMLElement>;
+    elementProps: {
+        role?: AriaRole;
+        'aria-label'?: string;
+        [prop: string]: unknown;
+    };
+    children?: ReactNode;
+}
+export declare function StackItemScrollRegion({ as: element, ref, elementProps, children, }: StackItemScrollRegionProps): import("react").DetailedReactHTMLElement<{
+    ref: import("react").RefCallback<HTMLElement>;
+    role: AriaRole | undefined;
+    'aria-label': string | undefined;
+}, HTMLElement>;
+//# sourceMappingURL=StackItemScrollRegion.d.ts.map

package/dist/hooks/StackItemScrollRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StackItemScrollRegion.d.ts","sourceRoot":"","sources":["../../src/hooks/StackItemScrollRegion.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAI7E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,KAAK,GAAG,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IACvB,YAAY,EAAE;QACZ,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,qBAAqB,CAAC,EACpC,EAAE,EAAE,OAAO,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,GACT,EAAE,0BAA0B;;;;gBAiB5B"}

package/dist/hooks/StackItemScrollRegion.js

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { createElement } from 'react';
+import { useMergedRefs } from "./useMergedRefs.js";
+import { useScrollRegionProps } from "./useScrollRegionProps.js";
+export function StackItemScrollRegion({
+  as: element,
+  ref,
+  elementProps,
+  children
+}) {
+  const region = useScrollRegionProps({
+    isScrollable: true,
+    role: elementProps.role,
+    label: elementProps['aria-label']
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
+  return /*#__PURE__*/createElement(element, {
+    ...elementProps,
+    ref: mergedRef,
+    role: region.role,
+    'aria-label': region['aria-label']
+  }, children);
+}

package/dist/hooks/useScrollRegionProps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+import { type AriaRole, type RefCallback } from 'react';
+export interface ScrollRegionOptions {
+    /** Whether the region may scroll at all (`overflow: auto`). */
+    isScrollable: boolean;
+    /** The caller's role. It always wins, and takes no default name. */
+    role?: AriaRole;
+    /** The caller's accessible name. It always wins. */
+    label?: string;
+}
+export interface ScrollRegionProps {
+    ref: RefCallback<HTMLElement>;
+    role: AriaRole | undefined;
+    'aria-label': string | undefined;
+}
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export declare function useScrollRegionProps({ isScrollable, role, label, }: ScrollRegionOptions): ScrollRegionProps;
+//# sourceMappingURL=useScrollRegionProps.d.ts.map

package/dist/hooks/useScrollRegionProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollRegionProps.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollRegionProps.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAwB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,OAAO,CAAC;AAU7E,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAC9B,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,YAAY,EACZ,IAAI,EACJ,KAAK,GACN,EAAE,mBAAmB,GAAG,iBAAiB,CAsBzC"}

package/dist/hooks/useScrollRegionProps.js

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+import { useCallback, useState } from 'react';
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/hooks/useScrollRegionProps.generated.js";
+import { observeMainOverflow } from "../AppShell/observeMainOverflow.js";
+registerEnglishFallback(english);
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export function useScrollRegionProps({
+  isScrollable,
+  role,
+  label
+}) {
+  const t = useComponentTranslator();
+  const [overflows, setOverflows] = useState(false);
+  // A caller's role takes no default name, so its region is not observed.
+  const hasRole = role != null;
+  const ref = useCallback(element => {
+    if (element == null || !isScrollable || hasRole) {
+      setOverflows(false);
+      return undefined;
+    }
+    return observeMainOverflow(element, setOverflows);
+  }, [hasRole, isScrollable]);
+  const isGroup = !hasRole && isScrollable && overflows;
+  return {
+    ref,
+    role: role ?? (isGroup ? 'group' : undefined),
+    'aria-label': label ?? (isGroup ? t('@astryx.scrollRegion.label') : undefined)
+  };
+}

package/dist/i18n/generated-english/hooks/useScrollRegionProps.generated.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/hooks/useScrollRegionProps.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+declare const english: Readonly<Record<string, string>>;
+export default english;
+//# sourceMappingURL=useScrollRegionProps.generated.d.ts.map

package/dist/i18n/generated-english/hooks/useScrollRegionProps.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollRegionProps.generated.d.ts","sourceRoot":"","sources":["../../../../src/i18n/generated-english/hooks/useScrollRegionProps.generated.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,QAAA,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7C,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/i18n/generated-english/hooks/useScrollRegionProps.generated.js

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/hooks/useScrollRegionProps.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english = {
+  "@astryx.scrollRegion.label": "Content"
+};
+export default english;

package/dist/i18n/generated-locales/en.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en.generated.d.ts","sourceRoot":"","sources":["../../../src/i18n/generated-locales/en.generated.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,QAAA,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmqBpD,CAAC;AAEF,eAAe,cAAc,CAAC"}
+{"version":3,"file":"en.generated.d.ts","sourceRoot":"","sources":["../../../src/i18n/generated-locales/en.generated.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,QAAA,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoqBpD,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/i18n/generated-locales/en.generated.js

@@ -338,6 +338,7 @@ const runtimeCatalog = {
   '@astryx.banner.expand': 'Expand',
   '@astryx.button.loading': 'Loading',
   '@astryx.spinner.loading': 'Loading',
+  '@astryx.scrollRegion.label': 'Content',
   '@astryx.chatComposerDrawer.expand': 'Expand {label}',
   '@astryx.chatComposerDrawer.collapse': 'Collapse {label}',
   '@astryx.chatDictationButton.startDictation': 'Start dictation',

package/dist/i18n/generated-locales/pseudo.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pseudo.generated.d.ts","sourceRoot":"","sources":["../../../src/i18n/generated-locales/pseudo.generated.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,QAAA,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+qBpD,CAAC;AAEF,eAAe,cAAc,CAAC"}
+{"version":3,"file":"pseudo.generated.d.ts","sourceRoot":"","sources":["../../../src/i18n/generated-locales/pseudo.generated.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,QAAA,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgrBpD,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/i18n/generated-locales/pseudo.generated.js

@@ -338,6 +338,7 @@ const runtimeCatalog = {
   '@astryx.banner.expand': '⟦Éẋþàñð⟧',
   '@astryx.button.loading': '⟦Łóàðíñĝ⟧',
   '@astryx.spinner.loading': '⟦Łóàðíñĝ⟧',
+  '@astryx.scrollRegion.label': '⟦Çóñţéñţ⟧',
   '@astryx.chatComposerDrawer.expand': '⟦Éẋþàñð {label}⟧',
   '@astryx.chatComposerDrawer.collapse': '⟦Çółłàþšé {label}⟧',
   '@astryx.chatDictationButton.startDictation': '⟦Šţàřţ ðíçţàţíóñ⟧',

package/locales/en.json

@@ -1323,6 +1323,10 @@
     "defaultMessage": "Loading",
     "description": "Screen-reader-only default name for a standalone Spinner's role=\"status\" element, used when the consumer supplies neither `aria-label` nor a visible string label; also announced once when a busy input or selector starts loading, in place of its decorative Spinner. Present-progressive form. Kept separate from `button.loading` and `typeahead.loading` — translations may diverge."
   },
+  "@astryx.scrollRegion.label": {
+    "defaultMessage": "Content",
+    "description": "Accessible name of a scrolling content region (LayoutContent, LayoutPanel or StackItem) when the caller gives none. A screen reader announces it with the region's group role while the region scrolls."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."

package/locales/pseudo.json

@@ -992,6 +992,9 @@
   "@astryx.spinner.loading": {
     "defaultMessage": "⟦Łóàðíñĝ⟧"
   },
+  "@astryx.scrollRegion.label": {
+    "defaultMessage": "⟦Çóñţéñţ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.9-canary.9bd11b3",
+  "version": "0.7.9-canary.cb2a34a",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -870,9 +870,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.9-canary.9bd11b3",
-    "@astryxdesign/cli": "0.7.9-canary.9bd11b3",
-    "@astryxdesign/interaction-harness": "0.7.9-canary.9bd11b3",
+    "@astryxdesign/a11y-spec": "0.7.9-canary.cb2a34a",
+    "@astryxdesign/cli": "0.7.9-canary.cb2a34a",
+    "@astryxdesign/interaction-harness": "0.7.9-canary.cb2a34a",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/AppShell/observeMainOverflow.ts

@@ -4,20 +4,23 @@
 
 /**
  * @file observeMainOverflow.ts
- * @input AppShell's main region under `height="fill"`: its own scroll
- *   container, holding its content as direct children with no wrapper
+ * @input A scroll container that holds its content as direct children with
+ *   no wrapper: AppShell's main region under `height="fill"`, or a scrolling
+ *   LayoutContent, LayoutPanel or StackItem
  * @output observeMainOverflow(main, onChange): reports whether main's content
  *   overflows it on either axis, once at the start and on every change, and
  *   returns the function that stops observing
- * @position Internal to AppShell and never exported. AppShell makes main a
+ * @position Internal and never exported. AppShell makes main a
  *   keyboard stop only while it overflows (`spec:AST-025` FR12,
- *   `component:AppShell` FR4 and PR1). Main has no inner content box, so its
- *   content grows inside it without resizing it: its direct children's sizes
- *   are watched instead.
+ *   `component:AppShell` FR4 and PR1). useScrollRegionProps names a
+ *   scrolling region only while it overflows. Main has no inner content
+ *   box, so its content grows inside it without resizing it: its direct
+ *   children's sizes are watched instead.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/AppShell/AppShell.tsx
  * - /packages/core/src/AppShell/observeMainOverflow.test.ts
+ * - /packages/core/src/hooks/useScrollRegionProps.ts
  */
 
 import {

package/src/InputGroup/InputGroup.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
     ],
   },
   description:
-    'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
+    'Groups an input with prefix and suffix addons in one connected row. A focused member stays above its neighbours, so its focus ring shows in full.',
   props: [
     {
       name: 'children',
@@ -59,7 +59,7 @@ export const docs = {
     {
       name: 'isOptional',
       type: 'boolean',
-      description: 'Show "(optional)" indicator.',
+      description: 'Show the "Optional" indicator after the label.',
       default: 'false',
     },
     {
@@ -77,7 +77,8 @@ export const docs = {
     {
       name: 'status',
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
-      description: 'Status indicator applied to the group border.',
+      description:
+        'Validation status. Its message shows below the group. The group border does not change; a theme can style the row from `data-status`.',
     },
     {
       name: 'labelTooltip',

package/src/InputGroup/InputGroup.tsx

@@ -109,7 +109,8 @@ export interface InputGroupProps extends Omit<
   size?: InputGroupSize;
 
   /**
-   * Status indicator applied to the group border.
+   * Validation status. Its message shows below the group. The group border
+   * does not change; a theme can style the row from `data-status`.
    */
   status?: InputStatus;
 
@@ -125,8 +126,8 @@ export interface InputGroupProps extends Omit<
 }
 
 /**
- * Groups an input with prefix/suffix addons in a visually connected
- * container with shared border and focus ring.
+ * Groups an input with prefix and suffix addons in one connected row. A
+ * focused member stays above its neighbours, so its focus ring shows in full.
  *
  * @example
  * ```

package/src/InputGroup/groupStyles.ts

@@ -96,8 +96,10 @@ export const groupStyles = stylex.create({
       default: 0,
       [IS_LAST_ITEM]: radiusVars['--radius-element'],
     },
+    // Input wrappers already sit at z-index 1. A focused member goes one
+    // higher, so an unfocused input beside it cannot cover its focus ring.
     ':focus-within': {
-      zIndex: 1,
+      zIndex: 2,
     },
   },
 });

package/src/Layout/LayoutContent.doc.mjs

@@ -30,7 +30,8 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for the landmark element.',
+      description:
+        'Accessible label for the landmark element. While the region scrolls, it also names the scrolling region, which otherwise takes a translated "Content".',
     },
     {
       name: 'role',
@@ -66,7 +67,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '地标元素的无障碍标签。',
+      description:
+        '地标元素的无障碍标签。区域滚动时，它也为滚动区域命名；未提供时使用已翻译的“Content”（内容）。',
     },
     {
       name: 'role',
@@ -86,7 +88,8 @@ export const docsDense = {
     padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable:
       'Enable scrollable overflow. With arithmetic contentWidth values, the scrollport reaches open sides while context-aware insets align children.',
-    label: 'Accessible label for landmark element.',
+    label:
+      'Accessible label for landmark element; also names the region while it scrolls (default "Content").',
     role: 'ARIA landmark role.',
   },
 };

package/src/Layout/LayoutContent.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file LayoutContent.tsx
- * @input Uses React StyleX, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutSlotsContext, useScrollRegionProps
  * @output Exports LayoutContent component and LayoutContentProps
  * @position Scrollable main content area for Layout. Wraps the primary body content
  *   with automatic scroll containment and context-aware padding.
@@ -21,6 +21,8 @@ import {use} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
 import {mergeProps} from '../utils/mergeProps';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -132,6 +134,8 @@ export interface LayoutContentProps extends BaseProps<HTMLDivElement> {
   /**
    * Accessible label for the landmark.
    * Required when role is set and multiple landmarks of the same type exist.
+   * While the content scrolls, it also names the scrolling region, which
+   * otherwise takes a translated "Content".
    */
   label?: string;
 
@@ -192,12 +196,14 @@ export function LayoutContent({
   const {hasHeader, hasFooter, hasStart, hasEnd} = use(LayoutSlotsContext);
 
   const isZeroPadding = padding === 0;
+  const region = useScrollRegionProps({isScrollable, role, label});
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   return (
     <div
-      ref={ref}
-      role={role}
-      aria-label={label}
+      ref={mergedRef}
+      role={region.role}
+      aria-label={region['aria-label']}
       {...mergeProps(
         themeProps('layout-content'),
         stylex.props(

package/src/Layout/LayoutPanel.doc.mjs

@@ -53,7 +53,8 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for the landmark element.',
+      description:
+        'Accessible label for the landmark element. While the region scrolls, it also names the scrolling region, which otherwise takes a translated "Content".',
     },
     {
       name: 'role',
@@ -106,7 +107,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '地标元素的无障碍标签。',
+      description:
+        '地标元素的无障碍标签。区域滚动时，它也为滚动区域命名；未提供时使用已翻译的“Content”（内容）。',
     },
     {
       name: 'role',
@@ -139,7 +141,8 @@ export const docsDense = {
     padding:
       'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
-    label: 'Accessible label for landmark element.',
+    label:
+      'Accessible label for landmark element; also names the region while it scrolls (default "Content").',
     role: 'ARIA landmark role.',
     width:
       'Panel width. Numbers = pixels, strings as-is. Ignored when resizable provided; hook controls width.',

package/src/Layout/LayoutPanel.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file LayoutPanel.tsx
- * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext,
+ *   useScrollRegionProps
  * @output Exports LayoutPanel component and LayoutPanelProps
  * @position Sidebar panel for Layout start/end slots. Use for navigation panels,
  *   settings sidebars, detail panels, or any fixed-width side content.
@@ -22,6 +23,8 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {LayoutAreaContext} from './LayoutAreaContext';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
 import {mergeProps} from '../utils';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import type {ResizableProps} from '../Resizable/useResizable';
@@ -144,6 +147,8 @@ export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {
   /**
    * Accessible label for the landmark.
    * Required when role is set and multiple landmarks of the same type exist.
+   * While the panel scrolls, it also names the scrolling region, which
+   * otherwise takes a translated "Content".
    */
   label?: string;
 
@@ -235,6 +240,8 @@ export function LayoutPanel({
   // When no divider, collapse spacing for seamless visual flow
   const shouldCollapseSpacing =
     !hasDivider && !isZeroPadding && padding == null;
+  const region = useScrollRegionProps({isScrollable, role, label});
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   // Select divider style based on position
   const dividerStyle = isStartPanel
@@ -252,9 +259,9 @@ export function LayoutPanel({
 
   return (
     <div
-      ref={ref}
-      role={role}
-      aria-label={label}
+      ref={mergedRef}
+      role={region.role}
+      aria-label={region['aria-label']}
       {...mergeProps(
         themeProps('layout-panel'),
         stylex.props(

package/src/Stack/Stack.doc.mjs

@@ -524,7 +524,7 @@ export const docs = {
           name: 'isScrollable',
           type: 'boolean',
           description:
-            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel.',
+            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel. While its content overflows, a div or span item is a group named by aria-label, or by a translated "Content"; another element keeps its own role.',
           default: 'false',
         },
         {

package/src/Stack/StackItem.tsx

@@ -2,9 +2,11 @@
 
 /**
  * @file StackItem.tsx
- * @input Uses React, ElementType, stackItem utility
+ * @input Uses React, ElementType, stackItem utility, StackItemScrollRegion
  * @output Exports StackItem polymorphic component and StackItemProps
- * @position Layout/Stack component; uses stackItem.stylex.ts
+ * @position Layout/Stack component; uses stackItem.stylex.ts. A scrollable
+ *   `div` or `span` item renders through StackItemScrollRegion, which names
+ *   it while it scrolls.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
@@ -21,6 +23,7 @@ import {
 } from './stackItem.stylex';
 import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
+import {StackItemScrollRegion} from '../hooks/StackItemScrollRegion';
 
 const overflowStyles = stylex.create({
   scrollable: {
@@ -53,7 +56,9 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
    * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
    * region — it grows to fill the stack and scrolls its own overflow with
    * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
-   * and `LayoutPanel`.
+   * and `LayoutPanel`. While its content overflows, a `div` or `span` item
+   * is a group named by the caller's `aria-label`, or by a translated
+   * "Content". Another element keeps its own role.
    * @default false
    */
   isScrollable?: boolean;
@@ -102,18 +107,27 @@ export function StackItem({
     xstyle,
   );
 
+  const elementProps = {
+    ...mergeProps(
+      themeProps('stack-item', {size}),
+      stylexProps,
+      className,
+      style,
+    ),
+    ...props,
+  };
+
+  if (isScrollable && (element === 'div' || element === 'span')) {
+    return createElement(
+      StackItemScrollRegion,
+      {as: element, ref, elementProps},
+      children,
+    );
+  }
+
   return createElement(
     element,
-    {
-      ref: ref as Ref<Element>,
-      ...mergeProps(
-        themeProps('stack-item', {size}),
-        stylexProps,
-        className,
-        style,
-      ),
-      ...props,
-    },
+    {ref: ref as Ref<Element>, ...elementProps},
     children,
   );
 }

package/src/hooks/StackItemScrollRegion.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+
+import {createElement, type AriaRole, type ReactNode, type Ref} from 'react';
+import {useMergedRefs} from './useMergedRefs';
+import {useScrollRegionProps} from './useScrollRegionProps';
+
+export interface StackItemScrollRegionProps {
+  as: 'div' | 'span';
+  ref?: Ref<HTMLElement>;
+  elementProps: {
+    role?: AriaRole;
+    'aria-label'?: string;
+    [prop: string]: unknown;
+  };
+  children?: ReactNode;
+}
+
+export function StackItemScrollRegion({
+  as: element,
+  ref,
+  elementProps,
+  children,
+}: StackItemScrollRegionProps) {
+  const region = useScrollRegionProps({
+    isScrollable: true,
+    role: elementProps.role,
+    label: elementProps['aria-label'],
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
+  return createElement(
+    element,
+    {
+      ...elementProps,
+      ref: mergedRef,
+      role: region.role,
+      'aria-label': region['aria-label'],
+    },
+    children,
+  );
+}

package/src/hooks/useScrollRegionProps.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+
+import {useCallback, useState, type AriaRole, type RefCallback} from 'react';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/hooks/useScrollRegionProps.generated';
+import {observeMainOverflow} from '../AppShell/observeMainOverflow';
+
+registerEnglishFallback(english);
+
+export interface ScrollRegionOptions {
+  /** Whether the region may scroll at all (`overflow: auto`). */
+  isScrollable: boolean;
+  /** The caller's role. It always wins, and takes no default name. */
+  role?: AriaRole;
+  /** The caller's accessible name. It always wins. */
+  label?: string;
+}
+
+export interface ScrollRegionProps {
+  ref: RefCallback<HTMLElement>;
+  role: AriaRole | undefined;
+  'aria-label': string | undefined;
+}
+
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export function useScrollRegionProps({
+  isScrollable,
+  role,
+  label,
+}: ScrollRegionOptions): ScrollRegionProps {
+  const t = useComponentTranslator();
+  const [overflows, setOverflows] = useState(false);
+  // A caller's role takes no default name, so its region is not observed.
+  const hasRole = role != null;
+  const ref = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null || !isScrollable || hasRole) {
+        setOverflows(false);
+        return undefined;
+      }
+      return observeMainOverflow(element, setOverflows);
+    },
+    [hasRole, isScrollable],
+  );
+  const isGroup = !hasRole && isScrollable && overflows;
+  return {
+    ref,
+    role: role ?? (isGroup ? 'group' : undefined),
+    'aria-label':
+      label ?? (isGroup ? t('@astryx.scrollRegion.label') : undefined),
+  };
+}

package/src/i18n/generated-english/hooks/useScrollRegionProps.generated.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/hooks/useScrollRegionProps.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.scrollRegion.label": "Content"
+};
+
+export default english;

package/src/i18n/generated-locales/en.generated.ts

@@ -375,6 +375,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': 'Expand',
   '@astryx.button.loading': 'Loading',
   '@astryx.spinner.loading': 'Loading',
+  '@astryx.scrollRegion.label': 'Content',
   '@astryx.chatComposerDrawer.expand': 'Expand {label}',
   '@astryx.chatComposerDrawer.collapse': 'Collapse {label}',
   '@astryx.chatDictationButton.startDictation': 'Start dictation',

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -383,6 +383,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': '⟦Éẋþàñð⟧',
   '@astryx.button.loading': '⟦Łóàðíñĝ⟧',
   '@astryx.spinner.loading': '⟦Łóàðíñĝ⟧',
+  '@astryx.scrollRegion.label': '⟦Çóñţéñţ⟧',
   '@astryx.chatComposerDrawer.expand': '⟦Éẋþàñð {label}⟧',
   '@astryx.chatComposerDrawer.collapse': '⟦Çółłàþšé {label}⟧',
   '@astryx.chatDictationButton.startDictation': '⟦Šţàřţ ðíçţàţíóñ⟧',