@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/AppShell/observeMainOverflow.ts

@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file observeMainOverflow.ts
+ * @input AppShell's main region under `height="fill"`: its own scroll
+ *   container, holding its content as direct children with no wrapper
+ * @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
+ *   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.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/AppShell/AppShell.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.test.ts
+ */
+
+import {
+  getLogicalAxisMapping,
+  measureLogicalScrollAxis,
+} from '../hooks/scrollGeometry';
+import {observeMutations} from '../utils/sharedMutationObserver';
+import {observeResize} from '../utils/sharedResizeObserver';
+
+/**
+ * Main's content: layout attributes, text and children, all the way down.
+ * One shared observer serves every registration with these options.
+ */
+const CONTENT_MUTATIONS: MutationObserverInit = {
+  attributes: true,
+  attributeFilter: ['class', 'dir', 'hidden', 'style'],
+  characterData: true,
+  childList: true,
+  subtree: true,
+};
+
+/**
+ * Calls `onChange` with whether `main`'s content overflows it on either axis:
+ * once with the first measurement, then whenever the answer changes. Signals
+ * coalesce into one measurement per frame. A hidden, disconnected or
+ * zero-size main is unknown rather than fitting: the last answer stands until
+ * a later signal measures it.
+ */
+export function observeMainOverflow(
+  main: HTMLElement,
+  onChange: (overflows: boolean) => void,
+): () => void {
+  let isActive = true;
+  let frame: number | null = null;
+  let overflows: boolean | null = null;
+
+  const measure = () => {
+    frame = null;
+    if (!isActive) {
+      return;
+    }
+    const computedStyle = getComputedStyle(main);
+    const mapping = getLogicalAxisMapping(
+      computedStyle.writingMode,
+      computedStyle.direction,
+    );
+    const inline = measureLogicalScrollAxis(main, 'inline', mapping);
+    const block = measureLogicalScrollAxis(main, 'block', mapping);
+    if (inline == null || block == null) {
+      return;
+    }
+    const next = inline.isScrollable || block.isScrollable;
+    if (next !== overflows) {
+      overflows = next;
+      onChange(next);
+    }
+  };
+
+  const scheduleMeasure = () => {
+    if (isActive && frame == null) {
+      frame = window.requestAnimationFrame(measure);
+    }
+  };
+
+  // Main keeps its size while its content grows; its children do not. Each
+  // direct child's size is watched, following the children as they change.
+  const childObservers = new Map<Element, () => void>();
+  const syncChildObservers = () => {
+    const children = new Set(Array.from(main.children));
+    for (const [child, stop] of childObservers) {
+      if (!children.has(child)) {
+        stop();
+        childObservers.delete(child);
+      }
+    }
+    for (const child of children) {
+      if (!childObservers.has(child)) {
+        childObservers.set(child, observeResize(child, scheduleMeasure));
+      }
+    }
+  };
+  const onContentChange = () => {
+    syncChildObservers();
+    scheduleMeasure();
+  };
+
+  measure();
+  syncChildObservers();
+  const stopObservingMain = observeResize(main, scheduleMeasure);
+  const stopObservingContent = observeMutations(
+    main,
+    CONTENT_MUTATIONS,
+    onContentChange,
+  );
+  window.addEventListener('resize', scheduleMeasure);
+  window.visualViewport?.addEventListener('resize', scheduleMeasure);
+  main.addEventListener('load', scheduleMeasure, true);
+  main.addEventListener('transitionend', scheduleMeasure);
+  main.addEventListener('animationend', scheduleMeasure);
+  const fonts = document.fonts;
+  fonts?.addEventListener?.('loadingdone', scheduleMeasure);
+  void fonts?.ready.then(scheduleMeasure);
+
+  return () => {
+    isActive = false;
+    if (frame != null) {
+      window.cancelAnimationFrame(frame);
+      frame = null;
+    }
+    stopObservingMain();
+    stopObservingContent();
+    for (const stop of childObservers.values()) {
+      stop();
+    }
+    childObservers.clear();
+    window.removeEventListener('resize', scheduleMeasure);
+    window.visualViewport?.removeEventListener('resize', scheduleMeasure);
+    main.removeEventListener('load', scheduleMeasure, true);
+    main.removeEventListener('transitionend', scheduleMeasure);
+    main.removeEventListener('animationend', scheduleMeasure);
+    fonts?.removeEventListener?.('loadingdone', scheduleMeasure);
+  };
+}

package/src/Avatar/Avatar.spec.md

@@ -122,17 +122,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                    |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | The root is a relative, non-shrinking inline-flex box of the resolved size with the shape's radius; it carries the `avatar` target, which reflects `size` and `shape`. A clipped content area fills it with the same radius and suppresses text selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR2 | The content area shows `src` while it has not failed, then `fallbackSrc` while it has not failed, then initials when the name yields any, then a default person icon at 60% of the box. Each image renders with empty `alt` and `object-fit: cover`. A failure is tracked per source, so a changed `src` or `fallbackSrc` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR3 | Initials are the first letter, digit, or emoji of the first and last words of the trimmed `name`, uppercased; leading punctuation in a word is skipped, words with none are dropped, one qualifying word yields one initial, and grapheme clusters are never split. A whitespace-only name counts as absent. Initials and the default icon paint on the `avatar-fallback` target (reflecting `size`) with `--color-neutral`, secondary text, body family, medium weight, and initials at 40% of the box.                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR4 | A truthy `status` renders in an absolutely positioned slot outside the clipped content area. On a circle it centers on the circle's edge at the bottom inline-end 45° point; on other shapes it sits at the bottom inline-end corner, offset outward by a quarter of its size. Placement mirrors in right-to-left documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
-| FR5 | The resolved name is `alt`, else `name` (blank strings count as absent), composed with the status label as the translated "{name}, {status}" when both exist; a status label alone also names the avatar. The status label comes from a string `label` on the passed element, read on every render, and from a label an AvatarStatusDot reports at any wrapper depth, which wins and updates the root before paint without a second render.                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests |
-| FR6 | `href` renders the shared link component (or `as`) with `target` and `rel`; otherwise `onClick` renders a `button type="button"`; otherwise the root is a `div`. Link and button roots carry the `data-avatar-item` marker and the shared focus-visible outline; `onClick` attaches to the link or button. In development, an interactive avatar whose only name is a status label, or that has no name and no caller `aria-label`/`aria-labelledby`, logs a warning.                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-| FR7 | The tooltip shows the trimmed custom string, else the meaningful `name`, placed above, on hover and keyboard focus; `tooltip={false}` or a blank result shows none. A static avatar with a tooltip and outside a group gets `tabIndex={0}` so keyboard users can reveal it. A custom string is added to `aria-describedby` after any caller value; the default name tooltip is not, because it repeats the name. Implementation gap: a grouped link or button avatar that is not the group's tab stop stops opening its tooltip on focus after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount (Current-state impact). | Current source and tests |
-| FR8 | Inside an AvatarGroup in the same layer (`spec:AST-038` FR7, FR8), the group's size and shape win over the avatar's own props; the root gains a 2px surface-colored ring outside its box and the group's negative inline-start overlap; a static avatar adds no tooltip tab stop, and link and button roots keep the `data-avatar-item` marker so they join the group's roving set. An avatar in a hover card, popover, or other layer opened from a group keeps its own size and shape, gets no ring or overlap, and keeps its tooltip tab stop; a link or button avatar there still carries the marker, so the group's roving focus, which selects marked elements in its DOM subtree, still includes it.                                                                                                      | Current source and tests |
-| FR9 | `ref` reaches the root of every variant. Supported DOM, ARIA, data, and event props reach the root after the derived ARIA, so a caller `aria-label`, `role`, or `aria-hidden` wins (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. Implementation gap: on the static root the component sets `tabIndex` after caller props, so a caller `tabIndex` is replaced (Current-state impact).                                                                                                                                                                                                                                                                                                                | Current source and tests |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a relative, non-shrinking inline-flex box of the resolved size with the shape's radius; it carries the `avatar` target, which reflects `size` and `shape`. A clipped content area fills it with the same radius and suppresses text selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
+| FR2 | The content area shows `src` while it has not failed, then `fallbackSrc` while it has not failed, then initials when the name yields any, then a default person icon at 60% of the box. Each image renders with empty `alt` and `object-fit: cover`. A failure is tracked per source, so a changed `src` or `fallbackSrc` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
+| FR3 | Initials are the first letter, digit, or emoji of the first and last words of the trimmed `name`, uppercased; leading punctuation in a word is skipped, words with none are dropped, one qualifying word yields one initial, and grapheme clusters are never split. A whitespace-only name counts as absent. Initials and the default icon paint on the `avatar-fallback` target (reflecting `size`) with `--color-neutral`, secondary text, body family, medium weight, and initials at 40% of the box. In forced colors, a lone Avatar's initials and default icon take the surrounding color (`currentColor`): the forced foreground by default, and the system color of a control that paints one around it (GrayText, HighlightText); inside an AvatarGroup they keep the forced foreground on the group's ring. | Current source and tests |
+| FR4 | A truthy `status` renders in an absolutely positioned slot outside the clipped content area. On a circle it centers on the circle's edge at the bottom inline-end 45° point; on other shapes it sits at the bottom inline-end corner, offset outward by a quarter of its size. Placement mirrors in right-to-left documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
+| FR5 | The resolved name is `alt`, else `name` (blank strings count as absent), composed with the status label as the translated "{name}, {status}" when both exist; a status label alone also names the avatar. The status label comes from a string `label` on the passed element, read on every render, and from a label an AvatarStatusDot reports at any wrapper depth, which wins and updates the root before paint without a second render.                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
+| FR6 | `href` renders the shared link component (or `as`) with `target` and `rel`; otherwise `onClick` renders a `button type="button"`; otherwise the root is a `div`. Link and button roots carry the `data-avatar-item` marker and the shared focus-visible outline; `onClick` attaches to the link or button. In development, an interactive avatar whose only name is a status label, or that has no name and no caller `aria-label`/`aria-labelledby`, logs a warning.                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+| FR7 | The tooltip shows the trimmed custom string, else the meaningful `name`, placed above, on hover and keyboard focus; `tooltip={false}` or a blank result shows none. A static avatar with a tooltip and outside a group gets `tabIndex={0}` so keyboard users can reveal it. A custom string is added to `aria-describedby` after any caller value; the default name tooltip is not, because it repeats the name. Implementation gap: a grouped link or button avatar that is not the group's tab stop stops opening its tooltip on focus after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount (Current-state impact).      | Current source and tests |
+| FR8 | Inside an AvatarGroup in the same layer (`spec:AST-038` FR7, FR8), the group's size and shape win over the avatar's own props; the root gains a 2px surface-colored ring outside its box and the group's negative inline-start overlap; a static avatar adds no tooltip tab stop, and link and button roots keep the `data-avatar-item` marker so they join the group's roving set. An avatar in a hover card, popover, or other layer opened from a group keeps its own size and shape, gets no ring or overlap, and keeps its tooltip tab stop; a link or button avatar there still carries the marker, so the group's roving focus, which selects marked elements in its DOM subtree, still includes it.                                                                                                           | Current source and tests |
+| FR9 | `ref` reaches the root of every variant. Supported DOM, ARIA, data, and event props reach the root after the derived ARIA, so a caller `aria-label`, `role`, or `aria-hidden` wins (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. Implementation gap: on the static root the component sets `tabIndex` after caller props, so a caller `tabIndex` is replaced (Current-state impact).                                                                                                                                                                                                                                                                                                                     | Current source and tests |
 
 ### Allowed variation
 
@@ -227,17 +227,17 @@ no root part, so no anatomy-theming block is declared.
 
 ## Verification map
 
-| Contract           | Verification                                                                                                                                                | Representative states                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                    | Audit section           |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
-| FR1–FR3            | `Avatar.test.tsx` fallback, initials, retry, and target tests                                                                                               | Photo, failure, initials, punctuation, emoji, blank name; `lg` box | A wrong initials-or-icon fallback, split grapheme, lost retry, missing target, or wrong `lg` box size fails. Gap: no test sets `src` and `fallbackSrc` together, so the `src`-first order is unchecked, and sizes other than `lg` and numeric sizes are visible only in `Avatar.stories.tsx`.                                                                      | `audit:Avatar/behavior` |
-| FR4                | `Avatar.test.tsx` shape and status tests; `Avatar.stories.tsx` status fixtures                                                                              | Every shape with a status; RTL                                     | A missing status slot fails. Gap: the tests assert presence only, so the slot's position, mirroring, and offset are visible only in the rendered fixtures.                                                                                                                                                                                                         | `audit:Avatar/layout`   |
-| FR5, AR1, AR2, PR1 | `Avatar.test.tsx` status-name and wrapper suites                                                                                                            | Direct, wrapped, changing, removed labels                          | A lost composed name, extra render, or stale label fails.                                                                                                                                                                                                                                                                                                          | `audit:Avatar/a11y`     |
-| FR6, AR3           | `Avatar.test.tsx` interactivity suite                                                                                                                       | Link, button, static, dev warnings                                 | A wrong root, a missing marker, or a missing warning fails. Gap: no test checks the focus-visible outline.                                                                                                                                                                                                                                                         | `audit:Avatar/behavior` |
-| FR7, AR4, AR5      | `Avatar.test.tsx` name-tooltip suite                                                                                                                        | Default, custom, disabled, blank                                   | A missing tab stop, a duplicated description, or a lost ref fails. Gap: no test covers a grouped avatar's tooltip after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount. | `audit:Avatar/a11y`     |
-| FR8                | `Avatar.test.tsx` group shape tests; `AvatarGroup.test.tsx` size-cascade, overlap, and roving suites; `layerScopedContext.test.tsx` AvatarGroup layer tests | Inside a group; in a layer opened from a group; outside a group    | An avatar size or shape prop winning inside a group, a lost overlap, an interactive avatar missing from the roving set, or a static avatar in a layer losing its tooltip tab stop fails. Gap: no test asserts the ring, or size and shape inside a layer.                                                                                                          | `audit:Avatar/behavior` |
-| FR9, AR6           | `Avatar.test.tsx` consumer-ARIA override suite                                                                                                              | Static and interactive roots                                       | A derived value replacing a caller `aria-label`, `role`, or `aria-hidden` fails. Gap: no test covers a caller `tabIndex`.                                                                                                                                                                                                                                          | `audit:Avatar/a11y`     |
-| AR1–AR3, AR5       | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                            | Named, decorative, status-composed, interactive                    | Gap: no accessibility-tree check proves the computed roles, names, or description; the unit tests query the DOM.                                                                                                                                                                                                                                                   | `audit:Avatar/a11y`     |
-| AR7                | `Avatar.stories.tsx` interactive and size fixtures in a browser                                                                                             | Interactive avatars at every size                                  | Gap: no automated target-size check; the undersized targets are the recorded gap.                                                                                                                                                                                                                                                                                  | `audit:Avatar/a11y`     |
+| Contract           | Verification                                                                                                                                                | Representative states                                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                              | Audit section           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| FR1–FR3            | `Avatar.test.tsx` fallback, initials, retry, and target tests; `AvatarForcedColors.a11y.chromium.spec.ts` in real Chromium with forced colors emulated      | Photo, failure, initials, punctuation, emoji, blank name; `lg` box; forced colors alone, inside GrayText and HighlightText, and grouped | A wrong initials-or-icon fallback, split grapheme, lost retry, missing target, wrong `lg` box size, or forced-colors initials that miss the surrounding system color (lone) or leave the forced foreground (grouped) fails. Gap: no test sets `src` and `fallbackSrc` together, so the `src`-first order is unchecked, and sizes other than `lg` and numeric sizes are visible only in `Avatar.stories.tsx`. | `audit:Avatar/behavior` |
+| FR4                | `Avatar.test.tsx` shape and status tests; `Avatar.stories.tsx` status fixtures                                                                              | Every shape with a status; RTL                                                                                                          | A missing status slot fails. Gap: the tests assert presence only, so the slot's position, mirroring, and offset are visible only in the rendered fixtures.                                                                                                                                                                                                                                                   | `audit:Avatar/layout`   |
+| FR5, AR1, AR2, PR1 | `Avatar.test.tsx` status-name and wrapper suites                                                                                                            | Direct, wrapped, changing, removed labels                                                                                               | A lost composed name, extra render, or stale label fails.                                                                                                                                                                                                                                                                                                                                                    | `audit:Avatar/a11y`     |
+| FR6, AR3           | `Avatar.test.tsx` interactivity suite                                                                                                                       | Link, button, static, dev warnings                                                                                                      | A wrong root, a missing marker, or a missing warning fails. Gap: no test checks the focus-visible outline.                                                                                                                                                                                                                                                                                                   | `audit:Avatar/behavior` |
+| FR7, AR4, AR5      | `Avatar.test.tsx` name-tooltip suite                                                                                                                        | Default, custom, disabled, blank                                                                                                        | A missing tab stop, a duplicated description, or a lost ref fails. Gap: no test covers a grouped avatar's tooltip after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount.                                           | `audit:Avatar/a11y`     |
+| FR8                | `Avatar.test.tsx` group shape tests; `AvatarGroup.test.tsx` size-cascade, overlap, and roving suites; `layerScopedContext.test.tsx` AvatarGroup layer tests | Inside a group; in a layer opened from a group; outside a group                                                                         | An avatar size or shape prop winning inside a group, a lost overlap, an interactive avatar missing from the roving set, or a static avatar in a layer losing its tooltip tab stop fails. Gap: no test asserts the ring, or size and shape inside a layer.                                                                                                                                                    | `audit:Avatar/behavior` |
+| FR9, AR6           | `Avatar.test.tsx` consumer-ARIA override suite                                                                                                              | Static and interactive roots                                                                                                            | A derived value replacing a caller `aria-label`, `role`, or `aria-hidden` fails. Gap: no test covers a caller `tabIndex`.                                                                                                                                                                                                                                                                                    | `audit:Avatar/a11y`     |
+| AR1–AR3, AR5       | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                            | Named, decorative, status-composed, interactive                                                                                         | Gap: no accessibility-tree check proves the computed roles, names, or description; the unit tests query the DOM.                                                                                                                                                                                                                                                                                             | `audit:Avatar/a11y`     |
+| AR7                | `Avatar.stories.tsx` interactive and size fixtures in a browser                                                                                             | Interactive avatars at every size                                                                                                       | Gap: no automated target-size check; the undersized targets are the recorded gap.                                                                                                                                                                                                                                                                                                                            | `audit:Avatar/a11y`     |
 
 ## Decision log
 

package/src/Avatar/Avatar.tsx

@@ -193,6 +193,19 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-medium'],
     textTransform: 'uppercase',
   },
+  // After `fallback` on a lone Avatar: in forced colors its initials and
+  // default icon take the color around them, which the browser forces to
+  // CanvasText, so a control that paints itself disabled (GrayText) or
+  // selected (HighlightText) carries them with it; an
+  // authored color would be forced to CanvasText whatever the control shows.
+  // A grouped face keeps it: its ring's opaque fill is forced to Canvas, so
+  // only CanvasText is sure to read on it.
+  loneFallback: {
+    color: {
+      default: colorVars['--color-text-secondary'],
+      '@media (forced-colors: active)': 'currentColor',
+    },
+  },
   status: {
     position: 'absolute',
   },
@@ -784,6 +797,7 @@ export function Avatar({
               themeProps('avatar-fallback', {size: resolvedSize}),
               stylex.props(
                 styles.fallback,
+                avatarGroup == null && styles.loneFallback,
                 dynamicStyles.fontSize(numericSize),
               ),
             )}>
@@ -794,7 +808,10 @@ export function Avatar({
           <div
             {...mergeProps(
               themeProps('avatar-fallback', {size: resolvedSize}),
-              stylex.props(styles.fallback),
+              stylex.props(
+                styles.fallback,
+                avatarGroup == null && styles.loneFallback,
+              ),
             )}>
             <DefaultIcon size={numericSize} />
           </div>

package/src/Badge/Badge.doc.mjs

@@ -20,7 +20,7 @@ export const docs = {
       type: 'ReactNode',
       required: true,
       description:
-        'Badge text content. A badge is one line, so a label wider than the space available is cut with an ellipsis rather than escaping its container; a string or number label is also set as the badge\'s title so the full text stays reachable on hover.',
+        'Badge text content. A badge is one line and at least as tall as that line of its label, so it grows with its text (a larger text size); a label wider than the space available is cut with an ellipsis rather than escaping its container; a string or number label is also set as the badge\'s title so the full text stays reachable on hover.',
     },
     {
       name: 'icon',

package/src/Badge/Badge.tsx

@@ -26,6 +26,7 @@ import {
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {isRenderable} from '../utils/isRenderable';
 import type {BadgeVariantMap} from './index';
 
 /**
@@ -46,7 +47,7 @@ const styles = stylex.create({
     lineHeight: typeScaleVars['--text-supporting-leading'],
     fontWeight: fontWeightVars['--font-weight-medium'],
     whiteSpace: 'nowrap',
-    // A badge is one line by construction — fixed height, `nowrap` — so a
+    // A badge is one line by construction — one line tall, `nowrap` — so a
     // label wider than the space available has to go somewhere. Without these
     // it went *outside* its container: `nowrap` with nothing to clip it
     // neither wraps nor truncates, it just escapes, and lands on whatever sits
@@ -56,6 +57,16 @@ const styles = stylex.create({
     maxWidth: '100%',
     minWidth: 0,
   },
+  // Never shorter than one line of its label: when the text grows (a larger
+  // text size), the pill grows with the label instead of the label spilling
+  // out of it. A minimum rather than a new height, so
+  // the theme's height (`--spacing-5`, or a theme's own, such as Butter's
+  // 30px) holds at the default size, where the line fits. Only with a label:
+  // a color-only badge has no text to hold and keeps the component:Badge FR1
+  // geometry at every text size.
+  grows: {
+    minHeight: '1lh',
+  },
   // The ellipsis goes on the label rather than the badge itself, because
   // `text-overflow` needs a block container and taking the root off
   // `inline-flex` to get one would cost the icon its centring. The label is a
@@ -238,13 +249,20 @@ export function Badge({
       : typeof label === 'string' && label.length > 0
         ? label
         : undefined;
+  // Whether the label renders anything, which is when the badge grows with it.
+  const hasLabel = isRenderable(label);
 
   return (
     <span
       ref={ref}
       {...mergeProps(
         themeProps('badge', {variant}),
-        stylex.props(styles.base, variants[variant], xstyle),
+        stylex.props(
+          styles.base,
+          hasLabel && styles.grows,
+          variants[variant],
+          xstyle,
+        ),
         className,
         style,
       )}

package/src/BottomSheet/BottomSheet.tsx

@@ -99,7 +99,7 @@ import {
 } from '../theme/tokens.stylex';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useScrollLock} from '../hooks/useScrollLock';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {useModalOutlet} from '../Layer/modalOutlet';

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -48,7 +48,8 @@ import {
   sizeVars,
   spacingVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, themeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
+import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';

package/src/BottomSheet/useSheetGestures.ts

@@ -235,6 +235,33 @@ function isBlockScroller(element: HTMLElement): boolean {
   return overflowY === 'auto' || overflowY === 'scroll';
 }
 
+/**
+ * Whether a gesture that lands on `target` began inside another layer
+ * rendered in this sheet's content — a `<dialog>` between the target and the
+ * body. A sheet opened from inside a sheet's content, a Dialog opened there,
+ * renders its dialog as a descendant of the host's body, so its pointer and
+ * touch events bubble through the host's gesture listeners. That gesture is
+ * the layer's own: the host must neither arm a drag on it nor take pointer
+ * capture for it, which would cancel the drag the layer's own handle began
+ * (`component:BottomSheet` FR7: a swipe reaches only the top sheet of a
+ * stack; FR6: a covered sheet is blocked).
+ */
+export function isInsideNestedLayer(
+  target: EventTarget | null,
+  body: HTMLElement,
+): boolean {
+  for (
+    let element = target instanceof Element ? target : null;
+    element != null && element !== body;
+    element = element.parentElement
+  ) {
+    if (element.localName === 'dialog') {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * The scrollers a gesture that lands on `target` can scroll, innermost first
  * and the body last: every scrollable box between the target and the body,
@@ -1328,10 +1355,13 @@ export function useSheetGestures({
     if (event.button !== 0 || !event.isPrimary) {
       return;
     }
-    const scrollers = scrollChainUnder(
-      event.target,
-      event.currentTarget as HTMLElement,
-    );
+    const body = event.currentTarget as HTMLElement;
+    // A gesture inside a layer this sheet hosts belongs to that layer.
+    if (isInsideNestedLayer(event.target, body)) {
+      armedBodyRef.current = null;
+      return;
+    }
+    const scrollers = scrollChainUnder(event.target, body);
     if (!chainAtTop(scrollers)) {
       armedBodyRef.current = null;
       return;
@@ -1465,8 +1495,9 @@ export function useSheetGestures({
       // At the top, a pull DOWN hands off (collapse); at the bottom, a pull UP
       // hands off (expand). A gesture that starts mid-content is an ordinary
       // scroll, but it is tracked all the same: the scroller can run out of
-      // content while the finger is still down (see onTouchMove).
-      if (!touch) {
+      // content while the finger is still down (see onTouchMove). A touch
+      // inside a layer this sheet hosts is that layer's, never tracked here.
+      if (!touch || isInsideNestedLayer(event.target, body)) {
         touchDragRef.current = null;
         return;
       }

package/src/Button/Button.tsx

@@ -43,8 +43,8 @@ import {
   shadowVars,
   focusVars,
 } from '../theme/tokens.stylex';
-import {Spinner} from '../Spinner';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {Spinner} from '../Spinner/Spinner';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
 import {IconDefaultSizeProvider} from '../Icon/IconDefaultSizeContext';
 import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 
@@ -57,7 +57,7 @@ import {
   groupStyles as inputGroupStyles,
   inputGroupItemProps,
 } from '../InputGroup/groupStyles';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
@@ -65,7 +65,7 @@ import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import type {ButtonVariantMap} from './index';
 
 /**