@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/NumberInput/NumberInput.tsx

@@ -19,6 +19,7 @@
  */
 
 import {
+  use,
   useId,
   useState,
   useMemo,
@@ -51,13 +52,16 @@ import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 
 // Public padding tokens for the `number-input` theme target. A theme writes an
 // ordinary `padding` (in ANY spelling — the shorthand, `paddingBlock`, or a
@@ -203,7 +207,7 @@ const sizeStyles = stylex.create({
 
 export type NumberInputSize = keyof typeof sizeStyles;
 
-import {groupStyles} from '../InputGroup/groupStyles';
+import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 
 // Re-export shared types for convenience
 
@@ -261,7 +265,7 @@ interface NumberInputPropsBase extends Omit<
    * Whether the input is read-only.
    * The value is shown at full opacity and still submits with the form, but
    * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
-   * stays in the tab order — use it for a value the user should see and send
+   * keeps its form value — use it for a value the user should see and send
    * but not change. Stepping is off in every form while read-only: arrow keys,
    * the wheel, and the number steppers. `isDisabled` takes precedence when both
    * are set.
@@ -275,8 +279,8 @@ interface NumberInputPropsBase extends Omit<
    * keyboard and assistive technology. The field cannot be edited (it becomes
    * read-only) while disabled.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the reason
+   * is attached to the field itself.
    *
    * @example
    * ```
@@ -536,7 +540,7 @@ export function NumberInput({
   description,
   isOptional = false,
   isRequired = false,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   isReadOnly = false,
   disabledMessage,
   startIcon,
@@ -574,6 +578,7 @@ export function NumberInput({
   ref,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: NumberInputProps) {
   const {rest, container} = useFieldInputStyling('NumberInput', restProps, {
@@ -588,6 +593,7 @@ export function NumberInput({
   const size = useSize(sizeProp, 'md');
   const generatedID = useId();
   const id = idProp ?? generatedID;
+  const fieldLabelID = useId();
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
@@ -595,17 +601,27 @@ export function NumberInput({
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const inputGroup = useInputGroup();
+  const inputGroupState = use(InputGroupInternalContext);
+  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
   const [isFocused, setIsFocused] = useState(false);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
+  // Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
   // the input stays perceivable via aria-disabled instead of the native
   // disabled attribute. The field is made read-only so it can't be typed into,
   // and value mutation is blocked by the isDisabled guard in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
+  // A disabled field keeps its tab stop but, like a natively disabled one,
+  // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
+  const fieldProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container div is not naturally focusable; focusin bubbles up from
@@ -638,6 +654,12 @@ export function NumberInput({
     ],
     inputGroup,
   );
+  // A caller aria-labelledby names the input together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const inputLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+      : ariaLabelledBy;
 
   const parseInput = useCallback(
     (text: string) => parseNumberInput(text, {min, max, isIntegerOnly, locale}),
@@ -699,6 +721,12 @@ export function NumberInput({
       if (pendingInput === null) {
         return;
       }
+      if (isDisabled) {
+        // A field disabled mid-entry commits nothing; its draft is dropped, as
+        // a natively disabled field's was (spec:AST-085 FR2).
+        setPendingInput(null);
+        return;
+      }
 
       const decision = resolveNumberInputCommit(pendingInput, {
         min,
@@ -722,7 +750,17 @@ export function NumberInput({
         onChange(decision.value);
       }
     },
-    [hasClear, isIntegerOnly, locale, max, min, onChange, pendingInput, value],
+    [
+      hasClear,
+      isDisabled,
+      isIntegerOnly,
+      locale,
+      max,
+      min,
+      onChange,
+      pendingInput,
+      value,
+    ],
   );
 
   // Blur ends the edit and displays the resulting committed value.
@@ -780,6 +818,13 @@ export function NumberInput({
   // Handle keyboard events
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      if (isDisabled) {
+        // A read-only field still submits its form on Enter.
+        if (e.key === 'Enter') {
+          e.preventDefault();
+        }
+        return;
+      }
       // The field is type="text" for formatted display, so an IME can compose
       // into it: Enter commits the candidate and the arrows walk the candidate
       // window. The composing keydown fires before compositionend, so without
@@ -804,7 +849,7 @@ export function NumberInput({
       }
       onKeyDown?.(e);
     },
-    [commitPendingInput, onEnter, onKeyDown, stepValue],
+    [commitPendingInput, isDisabled, onEnter, onKeyDown, stepValue],
   );
 
   // React's delegated wheel listener can be passive, so use a native,
@@ -860,11 +905,12 @@ export function NumberInput({
       if (!e || e.detail === 0) {
         inputRef.current?.focus();
       } else {
-        // Defer focus restoration past the button's unmount task so iOS Safari
-        // and touch browsers don't jump the page scroll to 0 on tap.
-        requestAnimationFrame(() => {
-          inputRef.current?.focus({preventScroll: true});
-        });
+        // Focus inside the tap: iOS Safari brings up its keyboard only for a
+        // focus made while handling the touch, so a field the tap reaches
+        // unfocused gets its keyboard, as UIKit's clear button makes the
+        // field first responder. `preventScroll` keeps a scrolled page where
+        // it is.
+        inputRef.current?.focus({preventScroll: true});
       }
     },
     [hasClear, onChange],
@@ -889,6 +935,7 @@ export function NumberInput({
       }}
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
+      {...(inputGroup ? inputGroupItemProps : undefined)}
       {...mergeProps(
         themeProps('number-input', {
           size,
@@ -902,6 +949,7 @@ export function NumberInput({
           hasNumberSteppers && styles.wrapperWithNumberSteppers,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && inputDisabledFocusStyles.ring,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -914,7 +962,7 @@ export function NumberInput({
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
-        {...rest}
+        {...fieldProps}
         ref={mergedInputRef}
         id={id}
         name={isDisabled || formatValue ? undefined : htmlName}
@@ -928,12 +976,11 @@ export function NumberInput({
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        // With a disabledMessage the input keeps focusability via aria-disabled
-        // so the reason is focus-discoverable; readOnly + the handler guards
-        // keep the value from changing.
-        disabled={isDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={isReadOnly || showsDisabledMessage || undefined}
+        // A disabled input keeps its place in the tab order (spec:AST-085):
+        // aria-disabled instead of the native attribute, with readOnly + the
+        // handler guards keeping the value from changing.
+        aria-disabled={isDisabled ? 'true' : undefined}
+        readOnly={isReadOnly || isDisabled || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-valuemin={min ?? undefined}
@@ -952,7 +999,7 @@ export function NumberInput({
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }
-        aria-labelledby={ariaLabelledBy}
+        aria-labelledby={inputLabelledBy}
         {...stylex.props(
           styles.input,
           isDisabled && styles.inputDisabled,
@@ -992,10 +1039,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canIncrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canIncrement || undefined
+            }
             aria-label={t('@astryx.numberInput.incrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canIncrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(1);
             }}
@@ -1016,10 +1070,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canDecrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canDecrement || undefined
+            }
             aria-label={t('@astryx.numberInput.decrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canDecrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(-1);
             }}
@@ -1054,6 +1115,7 @@ export function NumberInput({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /** Real-browser and accessibility-tree binding evidence for NumberInput. */
 

package/src/Overlay/Overlay.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
 
   usage: {
     description:
-      'Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.',
+      'Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior. Host attributes and DOM handlers (id, data-*, aria-*) reach the root element.',
     bestPractices: [
       {
         guidance: true,
@@ -193,7 +193,7 @@ export const docsDense = {
   description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',
   usage: {
     description:
-      'Overlay layers compact actions or supporting content over media, cards, or bounded surfaces with optional dark/light scrim and hover/focus/controlled reveal.',
+      'Overlay layers compact actions or supporting content over media, cards, or bounded surfaces with optional dark/light scrim and hover/focus/controlled reveal. Host attributes and DOM handlers reach the root element.',
     bestPractices: [
       {guidance: true, description: 'Use for short contextual actions/labels tied to the underlying surface.'},
       {guidance: true, description: 'Keep content compact and legible over the scrim.'},

package/src/Overlay/Overlay.test.tsx

@@ -10,8 +10,8 @@
  * update tests to match new behavior
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {render, screen, renderHook} from '@testing-library/react';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {render, screen, renderHook, fireEvent} from '@testing-library/react';
 import {createRef} from 'react';
 import {Overlay} from './Overlay';
 import {useOverlay} from './useOverlay';
@@ -31,7 +31,7 @@ function getScrim(container: HTMLElement): HTMLElement {
  */
 function mockHoverNone(matches: boolean): () => void {
   const original = window.matchMedia;
-  window.matchMedia = ((query: string) => ({
+  window.matchMedia = (query: string) => ({
     matches: query.includes('hover: none') ? matches : false,
     media: query,
     onchange: null,
@@ -40,7 +40,7 @@ function mockHoverNone(matches: boolean): () => void {
     addEventListener: () => {},
     removeEventListener: () => {},
     dispatchEvent: () => false,
-  }));
+  });
   return () => {
     window.matchMedia = original;
   };
@@ -245,6 +245,74 @@ describe('Overlay', () => {
       expect(root.style.opacity).toBe('0.5');
     });
   });
+
+  describe('host attributes', () => {
+    // architecture:public-component-api INV5: host attributes reach the root
+    // element that owns the ref, the theme target and the styling props.
+    it('forwards data, ARIA and id attributes to the root div', () => {
+      const ref = createRef<HTMLDivElement>();
+      render(
+        <Overlay
+          ref={ref}
+          content={<span>c</span>}
+          id="hero-overlay"
+          data-testid="hero"
+          data-analytics-id="hero-card"
+          aria-describedby="hero-caption">
+          <div>b</div>
+        </Overlay>,
+      );
+      const root = screen.getByTestId('hero');
+      expect(root).toBe(ref.current);
+      expect(root).toHaveAttribute('data-analytics-id', 'hero-card');
+      expect(root).toHaveAttribute('id', 'hero-overlay');
+      expect(root).toHaveAttribute('aria-describedby', 'hero-caption');
+      expect(root).toHaveClass('astryx-overlay');
+    });
+
+    describe('on a touch device', () => {
+      let restore: () => void;
+      beforeEach(() => {
+        restore = mockHoverNone(true);
+      });
+      afterEach(() => restore());
+
+      it('runs a caller onClick and still toggles the hover overlay on tap', () => {
+        const onClick = vi.fn((event: {preventDefault: () => void}) => {
+          event.preventDefault();
+        });
+        const {container} = render(
+          <Overlay
+            showOn="hover"
+            content={<span>c</span>}
+            data-testid="hero"
+            onClick={onClick}>
+            <div>b</div>
+          </Overlay>,
+        );
+        expect(getScrim(container).hasAttribute('inert')).toBe(true);
+        fireEvent.click(screen.getByTestId('hero'));
+        expect(onClick).toHaveBeenCalledTimes(1);
+        // A caller preventDefault() does not cancel the built-in toggle.
+        expect(getScrim(container).hasAttribute('inert')).toBe(false);
+      });
+
+      it('runs a caller onMouseUp alongside the built-in handler', () => {
+        const onMouseUp = vi.fn();
+        render(
+          <Overlay
+            showOn="hover"
+            content={<span>c</span>}
+            data-testid="hero"
+            onMouseUp={onMouseUp}>
+            <div>b</div>
+          </Overlay>,
+        );
+        fireEvent.mouseUp(screen.getByTestId('hero'));
+        expect(onMouseUp).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
 });
 
 describe('useOverlay', () => {

package/src/Overlay/Overlay.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Overlay.tsx
- * @input Uses React, useOverlay
+ * @input Uses React, useOverlay; forwards host props to the container
  * @output Exports Overlay component
  * @position Overlay system component; thin wrapper over useOverlay
  *
@@ -17,7 +17,7 @@
 
 import type {ReactNode, Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
 import {useOverlay} from './useOverlay';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';
@@ -31,10 +31,7 @@ import type {
 } from './OverlayScrim';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
-export interface OverlayProps extends Pick<
-  BaseProps<HTMLDivElement>,
-  'xstyle' | 'className' | 'style'
-> {
+export interface OverlayProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the container element. */
   ref?: Ref<HTMLDivElement>;
   /** Base content (image, card, video, etc.). */
@@ -84,6 +81,9 @@ export function Overlay({
   className,
   style,
   ref,
+  onClick: onClickProp,
+  onMouseUp: onMouseUpProp,
+  ...rest
 }: OverlayProps) {
   const overlay = useOverlay({
     content,
@@ -114,6 +114,7 @@ export function Overlay({
 
   return (
     <div
+      {...rest}
       ref={useMergedRefs(ref, overlay.containerRef)}
       {...mergeProps(
         themeProps('overlay'),
@@ -121,8 +122,17 @@ export function Overlay({
         className,
         style,
       )}
-      onClick={overlay.containerProps.onClick}
-      onMouseUp={overlay.containerProps.onMouseUp}>
+      // The touch toggle runs before the caller's handler: Overlay promises no
+      // cancellation, so a caller preventDefault() cannot stop it
+      // (architecture:public-component-api INV7).
+      onClick={composeEventHandlers(
+        overlay.containerProps.onClick,
+        onClickProp,
+      )}
+      onMouseUp={composeEventHandlers(
+        overlay.containerProps.onMouseUp,
+        onMouseUpProp,
+      )}>
       {children}
       {overlay.element}
     </div>

package/src/Pagination/Pagination.test.tsx

@@ -965,7 +965,7 @@ describe('Pagination', () => {
         />,
       );
       const box = screen.getByRole('spinbutton', {name: 'Go to page'});
-      expect(box).toBeDisabled();
+      expect(box).toHaveAttribute('aria-disabled', 'true');
       // Disabled input never fires a change.
       await user.type(box, '5{Enter}');
       expect(onChange).not.toHaveBeenCalled();
@@ -999,7 +999,7 @@ describe('Pagination', () => {
       // editable box is inert rather than accepting entries it can't resolve.
       expect(
         screen.getByRole('spinbutton', {name: 'Go to page'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
     });
 
     it('renders the localized "Page" label by default and a custom pageLabel', () => {

package/src/Popover/Popover.doc.mjs

@@ -99,7 +99,8 @@ export const docs = {
         {
           name: 'label',
           type: 'string',
-          description: 'Accessible label for the popover dialog.',
+          description:
+            'Accessible label for the popover dialog. A sheet without one is named by the trigger\u2019s text.',
         },
         {
           name: 'role',
@@ -149,6 +150,13 @@ export const docs = {
             'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss={false}, since native light dismiss also closes on Escape.',
           default: 'true',
         },
+        {
+          name: 'presentation',
+          type: "'popover' | 'bottom-sheet' | 'adaptive'",
+          description:
+            "The surface that holds the content. 'popover' anchors it to the trigger, 'bottom-sheet' presents it in a modal BottomSheet labeled by label, and 'adaptive' uses the BottomSheet on a compact touch screen (a coarse pointer on a screen the theme counts as compact: narrower than its md width point or shorter than 500 px, so a phone in either orientation) and the anchored popover elsewhere. In a sheet, placement, alignment, width, role, isModal and hasAutoFocus do not apply, and xstyle, className and style style the sheet's panel; the sheet always light-dismisses (a tap outside it or a swipe down closes it, whatever hasLightDismiss says), Escape follows hasEscapeDismiss, and the fallback close stays hidden. The surface is chosen as it opens and kept until it closes.",
+          default: "'popover'",
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',
@@ -259,6 +267,12 @@ export const docs = {
         description:
           'Painted surface owned and themed by Popover through the canonical popover target.',
       },
+      {
+        name: 'Touch sheet',
+        required: false,
+        description:
+          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
+      },
       {
         name: 'Popover content',
         required: true,
@@ -348,7 +362,8 @@ export const docsZh = {
         {
           name: 'label',
           type: 'string',
-          description: '弹出框对话框的无障碍标签。',
+          description:
+            '弹出框对话框的无障碍标签。没有标签的底部面板以触发器的文本命名。',
         },
         {
           name: 'role',
@@ -397,6 +412,13 @@ export const docsZh = {
             '按 Escape 是否关闭弹出框。仅在 hasLightDismiss={false} 时生效，因为原生 light dismiss 行为同样响应 Escape。',
           default: 'true',
         },
+        {
+          name: 'presentation',
+          type: "'popover' | 'bottom-sheet' | 'adaptive'",
+          description:
+            "承载内容的界面。'popover' 锚定在触发器上，'bottom-sheet' 以模态 BottomSheet 呈现（由 label 命名），'adaptive' 在紧凑触屏（粗指针，且屏幕按主题定义为紧凑：宽度小于其 md 断点或高度小于 500 px，即任意方向的手机）上使用 BottomSheet，在其他设备上使用锚定的弹出框。在底部面板中，placement、alignment、width、role、isModal 和 hasAutoFocus 不生效，xstyle、className 和 style 作用于面板；底部面板始终支持轻触关闭（点按面板外部或向下轻扫即可关闭，不受 hasLightDismiss 影响），Escape 遵循 hasEscapeDismiss，后备关闭按钮保持隐藏。界面在打开时选定，并保持到关闭。",
+          default: "'popover'",
+        },
       ],
     },
   ],
@@ -463,6 +485,12 @@ export const docsZh = {
         description:
           'Painted surface owned and themed by Popover through the canonical popover target.',
       },
+      {
+        name: 'Touch sheet',
+        required: false,
+        description:
+          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
+      },
       {
         name: 'Popover content',
         required: true,
@@ -530,6 +558,12 @@ export const docsDense = {
         description:
           'Painted surface owned and themed by Popover through the canonical popover target.',
       },
+      {
+        name: 'Touch sheet',
+        required: false,
+        description:
+          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
+      },
       {
         name: 'Popover content',
         required: true,
@@ -573,6 +607,8 @@ export const docsDense = {
           'Outside click dismisses; false for explicit-dismiss surfaces (coachmarks).',
         hasEscapeDismiss:
           'Escape dismisses; full effect only with hasLightDismiss=false.',
+        presentation:
+          "Surface: 'popover' (anchored), 'bottom-sheet' (modal BottomSheet), or 'adaptive' (BottomSheet on a coarse pointer on a compact screen, popover elsewhere); chosen on open, kept until close.",
       },
     },
   ],