@astryxdesign/core 0.7.6 → 0.7.7-canary.36f8ea1

package/src/AppShell/AppShell.tsx

@@ -471,6 +471,38 @@ const styles = stylex.create({
     top: 0,
     zIndex: 1,
   },
+  // The insets are zero unless the page sets `viewport-fit=cover`. The header
+  // background goes under the status bar and to the screen sides, as a UIKit
+  // bar does.
+  headerSafeAreaTop: {
+    paddingBlockStart: 'env(safe-area-inset-top, 0px)',
+  },
+  // The insets are physical sides, so a right-to-left context swaps them on
+  // the inline sides.
+  headerSafeAreaSides: {
+    paddingInlineStart: {
+      default: 'env(safe-area-inset-left, 0px)',
+      ':is([dir="rtl"] *)': 'env(safe-area-inset-right, 0px)',
+    },
+    paddingInlineEnd: {
+      default: 'env(safe-area-inset-right, 0px)',
+      ':is([dir="rtl"] *)': 'env(safe-area-inset-left, 0px)',
+    },
+  },
+  // In `auto`, the banner's wrapper and the phone top bar both stick. Below a
+  // banner, the bar sticks under the top inset, so its items stay clear of the
+  // status bar.
+  headerStickyBelowTopInset: {
+    top: 'env(safe-area-inset-top, 0px)',
+  },
+  // Main adds the bottom inset to the padding that LayoutContent publishes for
+  // `contentPadding`. The published value excludes the inset, so a bleed child
+  // subtracts only `contentPadding`. Main is border-box, so a child that fills
+  // it ends above the inset.
+  mainSafeAreaEnd: {
+    paddingBlockEnd:
+      'calc(var(--container-padding-block-end, 0px) + env(safe-area-inset-bottom, 0px))',
+  },
   // Sticky sideNav for auto height mode — sticks within the wrapper.
   // This div replaces the panel as the direct flex child of the middle
   // (horizontal) container, so it needs the same flex properties that
@@ -891,7 +923,12 @@ export function AppShell({
       role="banner"
       {...mergeProps(
         themeProps('app-shell-header', {variant}),
-        stylex.props(headerAreaStyle, isAuto && styles.headerSticky),
+        stylex.props(
+          headerAreaStyle,
+          isAuto && styles.headerSticky,
+          styles.headerSafeAreaTop,
+          styles.headerSafeAreaSides,
+        ),
       )}>
       {headerInner}
     </div>
@@ -1184,6 +1221,7 @@ export function AppShell({
         drawsMainFocusRing
           ? [focusOutlineStyles.focusVisible, styles.mainScrollRegionInset]
           : styles.mainFocusTarget,
+        styles.mainSafeAreaEnd,
       ]}>
       {children}
     </LayoutContent>
@@ -1230,7 +1268,15 @@ export function AppShell({
         role={headerContent == null ? 'banner' : undefined}
         {...mergeProps(
           themeProps('app-shell-header', {variant}),
-          stylex.props(headerAreaStyle, isAuto && styles.headerSticky),
+          stylex.props(
+            headerAreaStyle,
+            isAuto && styles.headerSticky,
+            styles.headerSafeAreaSides,
+            // Under a banner, the banner's wrapper pads the top inset. This top
+            // bar takes only the side insets.
+            headerContent == null && styles.headerSafeAreaTop,
+            isAuto && headerContent != null && styles.headerStickyBelowTopInset,
+          ),
         )}>
         <LayoutHeader padding={0} hasDivider={navHasDividers}>
           <div

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -675,10 +675,23 @@ export function BottomSheetPanel({
     if (motion == null) {
       return;
     }
-    startedMotionRef.current = null;
+    // React can run this effect again for the same motion, for example when
+    // a Suspense boundary shows this content again. The passive effect below
+    // does not run again then, so the motion it started stays started, and a
+    // completion completes at once instead of waiting for that effect.
+    if (startedMotionRef.current !== motion) {
+      startedMotionRef.current = null;
+    }
     pendingMotionCompleteRef.current = null;
+    const complete = () => {
+      if (startedMotionRef.current === motion) {
+        onMotionCompleteRef.current?.(motion);
+      } else {
+        pendingMotionCompleteRef.current = motion;
+      }
+    };
     if (motion === 'entering' && reactivatedEntranceRef.current) {
-      pendingMotionCompleteRef.current = motion;
+      complete();
       return;
     }
     // What ends a motion: the fade is opacity, and the entrance, alignment and
@@ -690,13 +703,7 @@ export function BottomSheetPanel({
     return waitForTransition(
       elementRef.current,
       motion === 'fading' || crossFadeMotion ? 'opacity' : 'transform',
-      () => {
-        if (startedMotionRef.current === motion) {
-          onMotionCompleteRef.current?.(motion);
-        } else {
-          pendingMotionCompleteRef.current = motion;
-        }
-      },
+      complete,
     );
   }, [motion, isCrossFade]);
   // The snap is transform-only; the layout height reconciles when it lands.

package/src/Chat/Chat.doc.mjs

@@ -35,6 +35,7 @@ export const docs = {
     vars: [
       {name: '--_chat-composer-radius', description: 'Border radius of the composer body. Inner elements derive their radius concentrically.', default: 'var(--radius-chat)', private: true},
       {name: '--_chat-composer-padding', description: 'Padding of the composer body. Used in the concentric radius calculation.', default: 'var(--spacing-3)', private: true},
+      {name: '--_chat-avatar-offset', description: 'Top offset of a message avatar: the name row spacing when a bubble in the message shows a name, else 0px. Each message sets it from its own content. Not a theming lever.', default: '0px', private: true},
       {name: '--_button-radius', description: 'Concentric button radius inside the composer.', default: 'max(var(--radius-element), calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))', private: true, derived: true, formula: 'max(var(--radius-element), calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))'},
     ],
     derived: [

package/src/Chat/ChatComposerInput.doc.mjs

@@ -157,6 +157,13 @@ export const docs = {
       description:
         'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected; Enter never submits mid-composition.',
     },
+    {
+      name: 'enterKeyHint',
+      type: "'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'",
+      description:
+        'What the Return key of a touch keyboard says (the native enterkeyhint). Enter sends the message, so it defaults to send and iOS shows its Send key. When onKeyDown makes Enter insert a line break on touch keyboards, pass enter so the key shows Return again.',
+      default: "'send'",
+    },
   ],
 };
 
@@ -187,6 +194,8 @@ export const docsZh = {
     onSubmit: '用户不按 Shift 按 Enter 时调用。序列化值包含标记占位符。',
     onKeyDown:
       '在内置 Enter/历史处理之前（在打开的触发菜单之后）调用的按键处理器。平台特定按键的接缝：调用 event.preventDefault() 可抑制默认提交（例如触控键盘上插入换行），或自行处理事件以添加行为（例如 Cmd/Ctrl+Enter 提交）。始终尊重输入法组字状态——组字过程中 Enter 永不提交。',
+    enterKeyHint:
+      '触屏键盘回车键上显示的内容（原生 enterkeyhint）。Enter 会发送消息，因此默认为 send，iOS 显示“发送”键。当 onKeyDown 让触屏键盘上的 Enter 插入换行时，传入 enter 让按键恢复为回车。',
   },
 };
 
@@ -219,5 +228,7 @@ export const docsDense = {
       'Enter w/o Shift handler; serialized value includes token placeholders',
     onKeyDown:
       'keydown handler before built-in Enter/history (after trigger menu); preventDefault() to suppress default submit (touch newline) or act on event to add behavior (Cmd/Ctrl+Enter). IME composition always respected',
+    enterKeyHint:
+      'touch keyboard Return key label (enterkeyhint); default send since Enter sends; pass enter when onKeyDown makes Enter a newline on touch',
   },
 };

package/src/Chat/ChatComposerInput.tsx

@@ -68,6 +68,7 @@ import {
 import {Badge, type BadgeProps} from '../Badge';
 import {useChatComposerContext} from './ChatContext';
 import {themeProps} from '../utils/themeProps';
+import type {EnterKeyHint} from '../Field/textEntryTraits';
 import {
   registerEnglishFallback,
   useComponentTranslator,
@@ -247,6 +248,14 @@ export interface ChatComposerInputProps extends Omit<
    * never submits while a composition is in progress.
    */
   onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
+  /**
+   * What the Return key of a touch keyboard says (the native
+   * `enterkeyhint`). Enter sends the message, so the key says so: iOS shows
+   * its Send key. When `onKeyDown` makes Enter insert a line break on touch
+   * keyboards, pass `'enter'` so the key shows Return again.
+   * @default 'send'
+   */
+  enterKeyHint?: EnterKeyHint;
 }
 
 // =============================================================================
@@ -373,6 +382,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     onFiles,
     onSubmit = composerCtx?.onSubmit,
     onKeyDown: onKeyDownProp,
+    enterKeyHint = 'send',
     xstyle,
     className,
     style,
@@ -941,6 +951,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
         // Explicit in both states: losing editability must not lose focus.
         tabIndex={0}
         contentEditable={!isDisabled}
+        enterKeyHint={enterKeyHint}
         suppressContentEditableWarning
         onInput={handleInput}
         onClick={handleEditorClick}

package/src/Chat/ChatMessage.tsx

@@ -118,7 +118,7 @@ const styles = stylex.create({
   // Judged from this article (parent-relative), never from siblings, so the
   // global stylesheet keeps no sibling-relative :has().
   avatarOffset: {
-    [chatMessageVars.avatarOffset]: {
+    [chatMessageVars['--_chat-avatar-offset']]: {
       default: '0px',
       ':has([data-chat-name])': spacingVars['--spacing-5'],
     },
@@ -128,7 +128,7 @@ const styles = stylex.create({
     flexShrink: 0,
     // The avatar lines up with a bubble's name row when the message holds
     // one; the article sets the offset (see chatMessageVars).
-    marginBlockStart: chatMessageVars.avatarOffset,
+    marginBlockStart: chatMessageVars['--_chat-avatar-offset'],
   },
   contentColumn: {
     display: 'flex',

package/src/Chat/chatMessage.vars.stylex.ts

@@ -5,14 +5,14 @@ import * as stylex from '@stylexjs/stylex';
 /**
  * Per-message values ChatMessage sets on its article for its own slots.
  *
- * `avatarOffset` is the avatar's top spacing: the name row's spacing when a
- * bubble in this message renders a name, else none. Each article sets it from
- * its own `:has([data-chat-name])`, a parent-relative rule: a sibling-relative
- * `:has(~ …)` in the global stylesheet makes WebKit re-check every earlier
- * sibling on each insertion into any container, so filling one grows
- * quadratically. A message nested in another sets its own value, so it never
- * inherits the outer message's.
+ * `--_chat-avatar-offset` is the avatar's top spacing: the name row's spacing
+ * when a bubble in this message renders a name, else none. Each article sets
+ * it from its own `:has([data-chat-name])`, a parent-relative rule: a
+ * sibling-relative `:has(~ …)` in the global stylesheet makes WebKit re-check
+ * every earlier sibling on each insertion into any container, so filling one
+ * grows quadratically. A message nested in another sets its own value, so it
+ * never inherits the outer message's.
  */
 export const chatMessageVars = stylex.defineVars({
-  avatarOffset: '0px',
+  '--_chat-avatar-offset': '0px',
 });

package/src/Drawer/Drawer.tsx

@@ -77,6 +77,7 @@ import {LayerDepthProvider, useLayerDismissal} from '../Layer';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
+import {useModalOutlet} from '../Layer/modalOutlet';
 import {layerClickBoundary} from '../Layer/layerClickBoundary';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {composeEventHandlers, mergeProps, themeProps} from '../utils';
@@ -497,6 +498,11 @@ export function Drawer({
     setIsRendered,
   });
 
+  // Toasts outside an open modal are inert, so the open drawer hosts them.
+  // It releases them when its exit starts.
+  // showModal() must run first, so keep this call after useDrawerDialogPresence.
+  useModalOutlet(dialogRef, isOpen && hasScrim);
+
   const handleDismiss = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);

package/src/DropdownMenu/useMenuOverflow.ts

@@ -4,31 +4,62 @@
 
 /**
  * @file useMenuOverflow.ts
- * @input Menu element ref, rendered content, and open state
+ * @input Menu element ref, rendered content, open state, and optionally the
+ *   overflow its owner expects from the content alone
  * @output Returns whether the open menu overflows its block-size constraint
  * @position Shared responsive helper for DropdownMenu and DropdownMenuSubMenu
  */
 
-import {useCallback, useState, type ReactNode, type RefObject} from 'react';
+import {
+  useCallback,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 
-/** Detect block-axis overflow without making a fitting menu a scroll container. */
+/**
+ * Detect block-axis overflow without making a fitting menu a scroll container.
+ *
+ * `expectedOverflow` is the answer the owner can give before any measure (a
+ * long option list cannot fit). Until a measure of the same `content` says
+ * otherwise, it is the result, so the first open already renders the right
+ * class: a class that flips after the open measure restyles the whole list
+ * a second time. A measure still runs on every open and corrects a wrong
+ * guess.
+ */
 export function useMenuOverflow(
   menuRef: RefObject<HTMLElement | null>,
   content: ReactNode,
   isOpen: boolean,
+  expectedOverflow?: boolean,
 ): boolean {
-  const [hasOverflow, setHasOverflow] = useState(false);
+  // The content each measure stands for, kept only for an owner that gives
+  // an expected answer (a caller whose content is a new element on every
+  // render compares nothing); set before the measuring effects run.
+  const contentRef = useRef<ReactNode>(null);
+  useIsomorphicLayoutEffect(() => {
+    contentRef.current = expectedOverflow === undefined ? null : content;
+  });
+  const [measured, setMeasured] = useState<{
+    content: ReactNode;
+    hasOverflow: boolean;
+  } | null>(null);
 
   const measureOverflow = useCallback(() => {
     const menu = menuRef.current;
     if (!menu) {
       return;
     }
-    const nextHasOverflow = menu.scrollHeight > menu.clientHeight + 1;
+    const hasOverflow = menu.scrollHeight > menu.clientHeight + 1;
     // eslint-disable-next-line @eslint-react/set-state-in-effect -- DOM overflow measurement controls whether this menu becomes a scroll container
-    setHasOverflow(current =>
-      current === nextHasOverflow ? current : nextHasOverflow,
+    setMeasured(current =>
+      current != null &&
+      current.hasOverflow === hasOverflow &&
+      Object.is(current.content, contentRef.current)
+        ? current
+        : {content: contentRef.current, hasOverflow},
     );
   }, [menuRef]);
 
@@ -73,5 +104,10 @@ export function useMenuOverflow(
     }
   }, [content, isOpen, measureOverflow]);
 
-  return hasOverflow;
+  if (expectedOverflow === undefined) {
+    return measured?.hasOverflow ?? false;
+  }
+  return measured != null && Object.is(measured.content, content)
+    ? measured.hasOverflow
+    : expectedOverflow;
 }

package/src/Link/Link.tsx

@@ -98,6 +98,9 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     borderStyle: 'none',
     padding: 0,
+    // Browsers centre a button's text; a wrapped label lines up as an
+    // anchor's does.
+    textAlign: 'inherit',
     pointerEvents: 'auto',
     position: 'relative',
   },

package/src/Selector/Selector.tsx

@@ -46,6 +46,7 @@ import {
 } from '../Field';
 import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
 import {useKeepLayerOpenProps, type LayerPlacement} from '../Layer/useLayer';
 import {InternalInputClearButton} from '../Field/InputClearButton';
 import {Spinner} from '../Spinner';
@@ -113,6 +114,14 @@ import english from '../i18n/generated-english/Selector/Selector.generated';
 
 registerEnglishFallback(english);
 
+/**
+ * A guess, confirmed by the open measure: more options than this overflow
+ * the popover listbox's 300 px block size even at 24 px rows, under the
+ * smallest default row (28 px). A wrong guess (a theme with shorter rows, a
+ * taller bottom sheet) costs only the measure's correction.
+ */
+const MOST_ROWS_THAT_FIT = 12;
+
 const styles = stylex.create({
   // Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
   triggerContainer: {
@@ -350,7 +359,21 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     paddingInline: spacingVars['--spacing-1'],
     opacity: 1,
-    transition: `opacity ${durationVars['--duration-fast']}`,
+    // Under Reduce Motion the list appears at once on a fine pointer, and
+    // takes the shared cross-fade on a coarse one.
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        reducedMotionFadeConsts.duration,
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        '0s',
+    },
+    transitionTimingFunction: {
+      default: 'ease',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        reducedMotionFadeConsts.easing,
+    },
   },
   dropdownInput: {
     // The input trigger's text inset includes its border. Mirror that extra
@@ -376,7 +399,8 @@ const styles = stylex.create({
   },
   dropdownHidden: {
     opacity: 0,
-    transition: 'none',
+    // A longhand: the shorthand would lose to the list's longhands.
+    transitionProperty: 'none',
   },
 
   // Popover container (for anchor positioning)
@@ -1407,10 +1431,13 @@ export function Selector<T extends SelectorOptionType>(
     return match == null ? -1 : Number(match[1]);
   }, []);
   // Re-measured when the option set changes; the count is the dependency.
+  // A list longer than the most rows that can fit cannot fit, so it starts
+  // as a scroll container and the open measure only confirms it.
   const listboxHasOverflow = useMenuOverflow(
     listboxRef,
     filteredItems.length,
     surface.isOpen,
+    filteredItems.length > MOST_ROWS_THAT_FIT,
   );
   const listboxPress = useMenuPress({
     menuRef: listboxRef,

package/src/Slider/Slider.doc.mjs

@@ -237,12 +237,14 @@ export const docs = {
     {
       name: 'containerClassName',
       type: 'string',
-      description: 'Class name for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Class name for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'containerStyle',
       type: 'CSSProperties',
-      description: 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Inline styles for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'controlXstyle',
@@ -295,7 +297,7 @@ export const docs = {
     ],
     anatomy,
     description:
-      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
+      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage. Under a finger, on any touch device, it tracks as UISlider does: only the thumb takes a drag, through a target larger than it, the value follows the finger’s travel rather than jumping to it, a release coasts on before `onChangeEnd`, a swipe from the track scrolls the page, and a tap on the track or a mark sets the value when the finger lifts (the thumb springs there). A mouse drag on a thumb tracks the same way, past the same 10 px in any direction, with no lift or coast; a mouse press on the track moves the thumb there, and only a primary click presses. A pen drags as a finger does, claiming only along the track, and its drag ends at the release with no coast. A wheel or a trackpad scroll over the slider goes to whatever scrolls under it.',
     bestPractices: [
       {
         guidance: true,
@@ -508,7 +510,7 @@ export const docsZh = {
   usage: {
     anatomy,
     description:
-      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
+      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage. Under a finger, on any touch device, it tracks as UISlider does: only the thumb takes a drag, through a target larger than it, the value follows the finger’s travel rather than jumping to it, a release coasts on before `onChangeEnd`, a swipe from the track scrolls the page, and a tap on the track or a mark sets the value when the finger lifts (the thumb springs there). A mouse drag on a thumb tracks the same way, past the same 10 px in any direction, with no lift or coast; a mouse press on the track moves the thumb there, and only a primary click presses. A pen drags as a finger does, claiming only along the track, and its drag ends at the release with no coast. A wheel or a trackpad scroll over the slider goes to whatever scrolls under it.',
     bestPractices: [
       {
         guidance: true,
@@ -544,7 +546,7 @@ export const docsDense = {
   usage: {
     anatomy,
     description:
-      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
+      'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage. Under a finger, on any touch device, it tracks as UISlider does: only the thumb takes a drag, through a target larger than it, the value follows the finger’s travel rather than jumping to it, a release coasts on before `onChangeEnd`, a swipe from the track scrolls the page, and a tap on the track or a mark sets the value when the finger lifts (the thumb springs there). A mouse drag on a thumb tracks the same way, past the same 10 px in any direction, with no lift or coast; a mouse press on the track moves the thumb there, and only a primary click presses. A pen drags as a finger does, claiming only along the track, and its drag ends at the release with no coast. A wheel or a trackpad scroll over the slider goes to whatever scrolls under it.',
     bestPractices: [
       {
         guidance: true,
@@ -574,10 +576,12 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    containerXstyle: 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+    containerXstyle:
+      'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
     containerClassName: 'Class name for the field container.',
     containerStyle: 'Inline styles for the field container.',
-    controlXstyle: 'StyleX styles for the visual control box (border, background, icons); not the native input.',
+    controlXstyle:
+      'StyleX styles for the visual control box (border, background, icons); not the native input.',
     controlClassName: 'Class name for the visual control box.',
     controlStyle: 'Inline styles for the visual control box.',
     label: 'Label text (always rendered for a11y).',