@astryxdesign/core 0.6.0 → 0.6.1

package/src/Typeahead/BaseTypeahead.tsx

@@ -38,6 +38,7 @@ import {TypeaheadItem} from './TypeaheadItem';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
 import {
+  borderVars,
   colorVars,
   spacingVars,
   radiusVars,
@@ -45,7 +46,13 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {getKey, groupItems, mergeProps} from '../utils';
+import {
+  characterCount,
+  composeEventHandlers,
+  getKey,
+  groupItems,
+  mergeProps,
+} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
@@ -98,7 +105,7 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   maxMenuItems?: number;
 
-  /** Fixed dropdown width in pixels. Never shrinks below the anchor width. */
+  /** Requested dropdown width in pixels before viewport clamping. */
   menuWidth?: number;
 
   /**
@@ -107,8 +114,8 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    * for a result set that cannot be meaningful yet — and the user does not
    * see "no results" for a query that was never searched.
    *
-   * Measured with `String.length` (UTF-16 code units), like every other
-   * length check in the library.
+   * Measured by grapheme cluster, so one visible character counts once even
+   * when JavaScript represents it with multiple UTF-16 code units.
    *
    * @default 1 — every non-empty query is searched.
    */
@@ -130,8 +137,10 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    * When disabled with a reason, keeps the input focusable via `aria-disabled`
    * (instead of the native `disabled` attribute) and `readOnly` so an
    * associated disabled-reason tooltip stays discoverable by keyboard and
-   * assistive technology. Value mutation is still blocked by the `isDisabled`
-   * guards. Consumers (Typeahead) own the tooltip and wrapper.
+   * assistive technology. Query and text mutation are blocked, but an
+   * already-open highlighted option can still be selected with Enter after a
+   * transition into this state. Consumers (Typeahead) own the tooltip and
+   * wrapper.
    * @default false
    */
   isFocusableDisabled?: boolean;
@@ -182,17 +191,20 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
   debounceMs?: number;
 
   /**
-   * ID for the input element (for label association).
+   * Legacy input-specific alias for the native `id` prop. When provided, this
+   * alias takes precedence; otherwise the native prop is preserved.
    */
   inputId?: string;
 
   /**
-   * Additional aria-describedby IDs.
+   * Legacy input-specific alias for native `aria-describedby`. When provided,
+   * this alias takes precedence; otherwise the native prop is preserved.
    */
   ariaDescribedBy?: string;
 
   /**
-   * Additional aria-labelledby IDs.
+   * Legacy input-specific alias for native `aria-labelledby`. When provided,
+   * this alias takes precedence; otherwise the native prop is preserved.
    */
   ariaLabelledBy?: string;
 
@@ -202,12 +214,13 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
   inputXStyle?: StyleXStyles;
 
   /**
-   * Tab-order override for the input element. Typeahead passes `-1` while
-   * its selected-value token is shown: the input is visually collapsed
-   * (width 0 / opacity 0) but must stay programmatically focusable for
-   * token edit/clear interactions, so removing it from the Tab order is
-   * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input
-   * remains focusable via `.focus()` regardless of this value.
+   * Legacy input-specific alias for native `tabIndex`. When provided, this
+   * alias takes precedence; otherwise the native prop is preserved. Typeahead
+   * passes `-1` while its selected-value token is shown: the input is visually
+   * collapsed (width 0 / opacity 0) but must stay programmatically focusable
+   * for token edit/clear interactions, so removing it from the Tab order is
+   * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input remains
+   * focusable via `.focus()` regardless of this value.
    */
   inputTabIndex?: number;
 
@@ -236,6 +249,10 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
 // Styles
 // =============================================================================
 
+const TYPEAHEAD_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const TYPEAHEAD_POSITION_AREA_MAX_INLINE_SIZE = `calc(100% - max(${TYPEAHEAD_VIEWPORT_GUTTER}, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px)))`;
+const TYPEAHEAD_POSITION_AREA_MAX_INLINE_SIZE_FALLBACK = `calc(100% - ${TYPEAHEAD_VIEWPORT_GUTTER})`;
+
 const styles = stylex.create({
   input: {
     display: 'block',
@@ -267,7 +284,12 @@ const styles = stylex.create({
     padding: spacingVars['--spacing-1'],
   },
   popover: {
+    boxSizing: 'border-box',
     minWidth: 'anchor-size(width)',
+    maxInlineSize: stylex.firstThatWorks(
+      TYPEAHEAD_POSITION_AREA_MAX_INLINE_SIZE,
+      TYPEAHEAD_POSITION_AREA_MAX_INLINE_SIZE_FALLBACK,
+    ),
   },
   popoverCustomWidth: (width: number) => ({
     width: `${width}px`,
@@ -299,6 +321,18 @@ const styles = stylex.create({
   },
   itemHighlighted: {
     backgroundColor: colorVars['--color-overlay-hover'],
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    outlineStyle: {
+      default: null,
+      '@media (forced-colors: active)': 'solid',
+    },
+    outlineWidth: {
+      default: null,
+      '@media (forced-colors: active)': borderVars['--border-width'],
+    },
   },
   itemSelected: {
     fontWeight: fontWeightVars['--font-weight-medium'],
@@ -307,6 +341,11 @@ const styles = stylex.create({
     display: 'flex',
     flex: 1,
     minWidth: 0,
+    overflow: 'hidden',
+  },
+  defaultItem: {
+    minWidth: 0,
+    width: '100%',
   },
   emptyState: {
     padding: spacingVars['--spacing-3'],
@@ -355,7 +394,8 @@ const itemSizeStyles = stylex.create({
  * untouched state, and `hasEntriesOnFocus` owns what happens there.
  */
 function isBelowMinQueryLength(query: string, minQueryLength: number): boolean {
-  return query.length > 0 && query.length < minQueryLength;
+  const length = characterCount(query);
+  return length > 0 && length < minQueryLength;
 }
 
 // =============================================================================
@@ -376,6 +416,7 @@ function isBelowMinQueryLength(query: string, minQueryLength: number): boolean {
  *   searchSource={source}
  *   value={selected}
  *   onChange={setSelected}
+ *   aria-label="Search frameworks"
  *   anchorRef={wrapperRef}
  *   placeholder="Search..."
  * />
@@ -407,7 +448,18 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   onKeyDown: externalOnKeyDown,
   debounceMs = 150,
   size = 'md',
+  xstyle,
+  className,
+  style,
+  onPointerDown: onPointerDownProp,
+  onFocus: onFocusProp,
+  onBlur: onBlurProp,
+  id: nativeInputId,
+  'aria-describedby': nativeAriaDescribedBy,
+  'aria-labelledby': nativeAriaLabelledBy,
+  tabIndex: nativeInputTabIndex,
   ref,
+  ...rest
 }: BaseTypeaheadProps<T>) {
   const t = useTranslator();
   const placeholder =
@@ -416,7 +468,12 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     emptySearchResultsTextFromProps ??
     t('@astryx.typeahead.emptySearchResults');
   const generatedId = useId();
-  const inputId = externalInputId ?? generatedId;
+  // Keep the released input-specific aliases authoritative when a caller uses
+  // them, but do not let an omitted alias erase the equivalent native BaseProp.
+  const inputId = externalInputId ?? nativeInputId ?? generatedId;
+  const inputAriaDescribedBy = ariaDescribedBy ?? nativeAriaDescribedBy;
+  const inputAriaLabelledBy = ariaLabelledBy ?? nativeAriaLabelledBy;
+  const resolvedInputTabIndex = inputTabIndex ?? nativeInputTabIndex;
   const listboxId = useId();
 
   const inputRef = useRef<HTMLInputElement>(null);
@@ -943,6 +1000,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   return (
     <>
       <input
+        {...rest}
         ref={useMergedRefs(ref, inputRef, fallbackAnchorRef)}
         id={inputId}
         type="text"
@@ -958,13 +1016,13 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         }
         aria-autocomplete="list"
         aria-busy={isLoading || undefined}
-        aria-describedby={ariaDescribedBy}
-        aria-labelledby={ariaLabelledBy}
+        aria-describedby={inputAriaDescribedBy}
+        aria-labelledby={inputAriaLabelledBy}
         aria-disabled={isFocusableDisabled ? 'true' : undefined}
-        tabIndex={inputTabIndex}
+        tabIndex={resolvedInputTabIndex}
         value={query}
         onChange={handleInputChange}
-        onPointerDown={() => {
+        onPointerDown={composeEventHandlers(() => {
           pointerActiveRef.current = true;
           document.addEventListener(
             'click',
@@ -973,23 +1031,29 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
             },
             {once: true},
           );
-        }}
-        onFocus={handleFocus}
-        onBlur={handleBlur}
+        }, onPointerDownProp)}
+        onFocus={composeEventHandlers(handleFocus, onFocusProp)}
+        onBlur={composeEventHandlers(handleBlur, onBlurProp)}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
         // When a disabled-reason tooltip is shown the input keeps focusability
         // via aria-disabled + readOnly instead of the native disabled
-        // attribute; value mutation stays blocked by the isDisabled guards.
+        // attribute. Query and text mutation are blocked, but an already-open
+        // highlighted option can still be selected with Enter after transition.
         disabled={isDisabled && !isFocusableDisabled}
         readOnly={isFocusableDisabled || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         autoComplete="off"
-        {...stylex.props(
-          styles.input,
-          isDisabled && styles.inputDisabled,
-          inputXStyle,
+        {...mergeProps(
+          stylex.props(
+            styles.input,
+            isDisabled && styles.inputDisabled,
+            inputXStyle,
+            xstyle,
+          ),
+          className,
+          style,
         )}
       />
       {isLoading && busyLane == null && (
@@ -1008,6 +1072,8 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           )}>
           {results.length === 0 && hasSearched ? (
             <div
+              role="option"
+              aria-disabled="true"
               {...mergeProps(
                 themeProps('typeahead-empty-state'),
                 stylex.props(styles.emptyState),
@@ -1040,7 +1106,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
                       {renderItem ? (
                         renderItem(item)
                       ) : (
-                        <TypeaheadItem item={item} />
+                        <TypeaheadItem
+                          item={item}
+                          xstyle={styles.defaultItem}
+                        />
                       )}
                     </span>
                     {isSelected && (

package/src/hooks/index.ts

@@ -56,6 +56,19 @@ export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
 export {useScrollOverflow} from './useScrollOverflow';
 export type {ScrollOverflowState} from './useScrollOverflow';
 
+export {useScrollableArea} from './useScrollableArea';
+export type {
+  ScrollAxis,
+  ScrollAxisState,
+  ScrollOverscroll,
+  ScrollStickyContainment,
+  ScrollKeyboardAccess,
+  ScrollableAreaState,
+  ScrollableElementProps,
+  UseScrollableAreaOptions,
+  UseScrollableAreaResult,
+} from './useScrollableArea';
+
 export {useScrollLock} from './useScrollLock';
 
 export {useEntryAnimation} from './useEntryAnimation';

package/src/hooks/scrollGeometry.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Shared geometry primitives for logical-axis scroll ownership. */
+
+export const SCROLL_OVERFLOW_TOLERANCE = 1;
+
+export type LogicalScrollAxis = 'inline' | 'block';
+export type PhysicalScrollAxis = 'x' | 'y';
+
+export interface LogicalAxisMapping {
+  inline: PhysicalScrollAxis;
+  block: PhysicalScrollAxis;
+  inlineReversed: boolean;
+  blockReversed: boolean;
+}
+
+export interface MeasuredScrollAxisState {
+  isScrollable: boolean;
+  atStart: boolean;
+  atEnd: boolean;
+}
+
+export interface LogicalOverflowGeometry {
+  inline: boolean;
+  block: boolean;
+}
+
+const INACTIVE_AXIS_STATE: MeasuredScrollAxisState = {
+  isScrollable: false,
+  atStart: true,
+  atEnd: true,
+};
+
+export function getLogicalAxisMapping(
+  writingMode: string,
+  direction: string,
+): LogicalAxisMapping {
+  const mode = writingMode.toLowerCase();
+  const isVertical = mode.startsWith('vertical') || mode.startsWith('sideways');
+  const isRtl = direction === 'rtl';
+
+  if (!isVertical) {
+    return {
+      inline: 'x',
+      block: 'y',
+      inlineReversed: isRtl,
+      blockReversed: false,
+    };
+  }
+
+  // sideways-lr runs its natural inline direction from bottom to top. The
+  // other vertical/sideways modes run top to bottom; `direction` reverses each.
+  const inlineReversed = mode === 'sideways-lr' ? !isRtl : isRtl;
+  const blockReversed = mode.endsWith('-rl');
+
+  return {
+    inline: 'y',
+    block: 'x',
+    inlineReversed,
+    blockReversed,
+  };
+}
+
+export function isScrollCapableOverflow(value: string): boolean {
+  return value === 'auto' || value === 'scroll' || value === 'overlay';
+}
+
+function physicalMetrics(
+  element: HTMLElement,
+  physicalAxis: PhysicalScrollAxis,
+): {
+  clientExtent: number;
+  contentExtent: number;
+  offset: number;
+  overflow: string;
+} {
+  const computedStyle = getComputedStyle(element);
+  if (physicalAxis === 'x') {
+    return {
+      clientExtent: element.clientWidth,
+      contentExtent: element.scrollWidth,
+      offset: element.scrollLeft,
+      overflow: computedStyle.overflowX,
+    };
+  }
+  return {
+    clientExtent: element.clientHeight,
+    contentExtent: element.scrollHeight,
+    offset: element.scrollTop,
+    overflow: computedStyle.overflowY,
+  };
+}
+
+function isMeasurable(
+  element: HTMLElement,
+  computedStyle: CSSStyleDeclaration,
+) {
+  return (
+    element.isConnected &&
+    computedStyle.display !== 'none' &&
+    element.clientWidth > 0 &&
+    element.clientHeight > 0
+  );
+}
+
+export function measureLogicalOverflowGeometry(
+  element: HTMLElement,
+  logicalAxis: LogicalScrollAxis,
+  mapping: LogicalAxisMapping,
+): boolean | null {
+  const computedStyle = getComputedStyle(element);
+  if (!isMeasurable(element, computedStyle)) {
+    return null;
+  }
+
+  const physicalAxis = mapping[logicalAxis];
+  const clientExtent =
+    physicalAxis === 'x' ? element.clientWidth : element.clientHeight;
+  const contentExtent =
+    physicalAxis === 'x' ? element.scrollWidth : element.scrollHeight;
+  return contentExtent - clientExtent > SCROLL_OVERFLOW_TOLERANCE;
+}
+
+export function measureLogicalScrollAxis(
+  element: HTMLElement,
+  logicalAxis: LogicalScrollAxis,
+  mapping: LogicalAxisMapping,
+): MeasuredScrollAxisState | null {
+  const computedStyle = getComputedStyle(element);
+  if (!isMeasurable(element, computedStyle)) {
+    return null;
+  }
+
+  const physicalAxis = mapping[logicalAxis];
+  const metrics = physicalMetrics(element, physicalAxis);
+  const maxOffset = metrics.contentExtent - metrics.clientExtent;
+  if (
+    !isScrollCapableOverflow(metrics.overflow) ||
+    maxOffset <= SCROLL_OVERFLOW_TOLERANCE
+  ) {
+    return INACTIVE_AXIS_STATE;
+  }
+
+  const isReversed = mapping[`${logicalAxis}Reversed`];
+  const logicalOffset = Math.min(
+    maxOffset,
+    Math.max(0, isReversed ? Math.abs(metrics.offset) : metrics.offset),
+  );
+
+  return {
+    isScrollable: true,
+    atStart: logicalOffset <= SCROLL_OVERFLOW_TOLERANCE,
+    atEnd: logicalOffset >= maxOffset - SCROLL_OVERFLOW_TOLERANCE,
+  };
+}

package/src/hooks/scrollOwnerRegistry.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Private DOM registry used by future axis-aware Sticky consumers. */
+
+export interface RegisteredScrollAxisState {
+  isScrollable: boolean;
+  atStart: boolean;
+  atEnd: boolean;
+}
+
+export interface RegisteredScrollOwnerState {
+  inline: RegisteredScrollAxisState;
+  block: RegisteredScrollAxisState;
+}
+
+const owners = new WeakMap<HTMLElement, RegisteredScrollOwnerState>();
+
+export function registerScrollOwner(
+  element: HTMLElement,
+  state: RegisteredScrollOwnerState,
+): void {
+  owners.set(element, state);
+}
+
+export function unregisterScrollOwner(element: HTMLElement): void {
+  owners.delete(element);
+}
+
+export function getRegisteredScrollOwnerState(
+  element: HTMLElement,
+): RegisteredScrollOwnerState | undefined {
+  return owners.get(element);
+}
+
+export function findNearestScrollOwner(
+  element: Element,
+  axis: 'inline' | 'block',
+): HTMLElement | null {
+  let candidate = element.parentElement;
+  while (candidate != null) {
+    if (owners.get(candidate)?.[axis].isScrollable === true) {
+      return candidate;
+    }
+    candidate = candidate.parentElement;
+  }
+  return null;
+}

package/src/hooks/useFocusTrap.ts

@@ -5,8 +5,8 @@
 /**
  * @file useFocusTrap.ts
  * @input Uses React useCallback, useEffect, useRef
- * @output Exports useFocusTrap hook for trapping focus within a container and
- *   restoring focus to the previously-focused element on deactivation
+ * @output Exports useFocusTrap, the deprecated Escape-state shim, and an
+ *   internal compatibility-signal hook
  * @position Core hook; used by dialogs, modals, date pickers
  *
  * Based on WAI-ARIA dialog pattern:
@@ -41,6 +41,25 @@ export function hasActiveFocusTrapEscape(): boolean {
   return activeEscapeTrapCount > 0;
 }
 
+/**
+ * Keep the deprecated `hasActiveFocusTrapEscape` signal accurate for a focus
+ * trap whose Escape is coordinated by another registration in the shared
+ * stack. This hook is intentionally internal (not re-exported from `hooks`): it
+ * preserves the released read-only compatibility signal without creating a
+ * second dismissal owner.
+ */
+export function useFocusTrapEscapeCompatibilitySignal(isActive: boolean): void {
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+    activeEscapeTrapCount += 1;
+    return () => {
+      activeEscapeTrapCount -= 1;
+    };
+  }, [isActive]);
+}
+
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
@@ -213,15 +232,7 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
     getContainer: () => containerRef.current,
   });
 
-  useEffect(() => {
-    if (!isEscapeTrap) {
-      return;
-    }
-    activeEscapeTrapCount += 1;
-    return () => {
-      activeEscapeTrapCount -= 1;
-    };
-  }, [isEscapeTrap]);
+  useFocusTrapEscapeCompatibilitySignal(isEscapeTrap);
 
   /**
    * Focus the first focusable element.

package/src/hooks/useFocusTrapEscapeShim.test.tsx

@@ -9,9 +9,10 @@
  * @position Testing; guards the deprecated public shim in useFocusTrap.ts
  *
  * The shim is public API. Its answer must not change now that Escape moved to
- * the shared stack: `BottomSheetSwitcher` gates its own dismissal on it, so a
- * shim that also counts tooltips, hover cards and dialogs tells the sheet a
- * trap is above it when none is, and the sheet stops closing.
+ * the shared stack: existing consumers still observe whether an
+ * Escape-participating focus trap is active. Families that never trapped focus
+ * stay out of this count; BottomSheetSwitcher preserves its historical modal
+ * signal without registering a second dismissal owner.
  *
  * SYNC: When useFocusTrap.ts changes, update tests to match new behavior
  */

package/src/hooks/useScrollableArea.doc.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useScrollableArea',
+  displayName: 'useScrollableArea',
+  keywords: [
+    'scroll',
+    'overflow',
+    'logical axis',
+    'keyboard',
+    'overscroll',
+    'sticky',
+    'resize',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseScrollableAreaOptions',
+      description:
+        'Logical scroll intent, keyboard owner, overscroll policy, and fitting Sticky containment.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'getViewportProps',
+      type: '<E extends HTMLElement>(props?: ScrollableElementProps<E>) => ScrollableElementProps<E>',
+      description:
+        'Consumes caller viewport props, xstyle, and refs; composes fitting/active overflow, Sticky containment, accessibility, chaining, and owner registration.',
+    },
+    {
+      name: 'getContentProps',
+      type: '<E extends HTMLElement>(props?: ScrollableElementProps<E>) => ScrollableElementProps<E>',
+      description:
+        'Composes caller content-box props and refs with content observation.',
+    },
+    {
+      name: 'state',
+      type: 'ScrollableAreaState',
+      description:
+        'Stable inline and block effective-scroll and logical-edge state.',
+    },
+  ],
+  usage: {
+    description:
+      'Adds canonical axis-aware scroll behavior to structure owned by the caller. An axis is effective only when its computed overflow is scroll-capable and geometry exceeds the shared 1px tolerance. Both viewport and content boxes are observed.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pass already-resolved props and refs through both prop getters, then spread each returned object once.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use viewport keyboard ownership only when the viewport itself should enter the tab order; provide a concise accessible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use content keyboard ownership when an existing focusable descendant gives keyboard users access to all overflowed content.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass caller `xstyle` through `getViewportProps`; the getter composes it with fitting clip, active overflow, and Sticky containment.',
+      },
+      {
+        guidance: false,
+        description:
+          'Attach only the viewport getter. A real observed content box is required for live overflow changes.',
+      },
+    ],
+  },
+  relatedComponents: ['ScrollableArea'],
+  relatedHooks: ['useScrollOverflow'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'layout',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Composes logical-axis scrolling into caller-owned viewport/content elements with stable effective-axis and edge state.',
+  paramDescriptions: {
+    options:
+      'axis, keyboard owner, allow/contain overscroll policy, and fitting Sticky containment.',
+  },
+  returnDescriptions: {
+    getViewportProps:
+      'safe viewport prop/ref/xstyle composition with behavior-owned overflow, accessibility, and chaining.',
+    getContentProps: 'safe observed content-box prop/ref composition.',
+    state: 'inline/block isScrollable, atStart, and atEnd state.',
+  },
+  usage: {
+    description:
+      'Use for existing structures that need ScrollableArea behavior without another wrapper.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Spread each prop getter result once on its owner element.',
+      },
+      {guidance: false, description: 'Skip the real content-box getter.'},
+    ],
+  },
+};