@cdx-ui/primitives 0.1.6 → 0.2.0

package/src/color-slider/utils.ts

@@ -0,0 +1,79 @@
+import type { Color } from '../color';
+import type { ColorSliderConfiguration } from './types';
+
+const HUE_STOPS = [0, 60, 120, 180, 240, 300, 360] as const;
+
+export function clampColorSliderValue(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function getColorSliderRange({ colorSpace, channel }: ColorSliderConfiguration): {
+  min: number;
+  max: number;
+} {
+  if (colorSpace === 'rgb') {
+    return { min: 0, max: 255 };
+  }
+  if (channel === 'hue') {
+    return { min: 0, max: 360 };
+  }
+  return { min: 0, max: 100 };
+}
+
+export function getColorSliderChannelValue(
+  color: Color,
+  configuration: ColorSliderConfiguration,
+): number {
+  if (configuration.colorSpace === 'rgb') {
+    return color.getChannel('rgb', configuration.channel);
+  }
+  if (configuration.colorSpace === 'hsl') {
+    return color.getChannel('hsl', configuration.channel);
+  }
+  return color.getChannel('hsb', configuration.channel);
+}
+
+export function withColorSliderChannel(
+  color: Color,
+  configuration: ColorSliderConfiguration,
+  value: number,
+): Color {
+  if (configuration.colorSpace === 'rgb') {
+    return color.withChannel('rgb', configuration.channel, value);
+  }
+  if (configuration.colorSpace === 'hsl') {
+    return color.withChannel('hsl', configuration.channel, value);
+  }
+  return color.withChannel('hsb', configuration.channel, value);
+}
+
+export function formatColorSliderValue(
+  value: number,
+  configuration: ColorSliderConfiguration,
+): string {
+  const formatted = Number.isInteger(value) ? String(value) : value.toFixed(1);
+  if (configuration.channel === 'hue') {
+    return `${formatted}°`;
+  }
+  if (configuration.colorSpace !== 'rgb') {
+    return `${formatted}%`;
+  }
+  return formatted;
+}
+
+export function getColorSliderGradientColors(
+  color: Color,
+  configuration: ColorSliderConfiguration,
+): readonly string[] {
+  if (configuration.channel === 'hue') {
+    return HUE_STOPS.map((value) =>
+      withColorSliderChannel(color, configuration, value).toString('hex'),
+    );
+  }
+
+  const { min, max } = getColorSliderRange(configuration);
+  return [
+    withColorSliderChannel(color, configuration, min).toString('hex'),
+    withColorSliderChannel(color, configuration, max).toString('hex'),
+  ];
+}

package/src/color-swatch-picker/ColorSwatchPickerItem.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, useEffect, useMemo, type ComponentRef } from 'react';
+import { Pressable } from 'react-native';
+import { RadioRoot } from '../radio';
+import { ColorSwatchPickerItemProvider, useColorSwatchPickerContext } from './context';
+import type { IColorSwatchPickerItemProps } from './types';
+
+export interface ColorSwatchPickerItemProps extends IColorSwatchPickerItemProps {
+  asChild?: boolean;
+}
+
+export const ColorSwatchPickerItem = forwardRef<
+  ComponentRef<typeof Pressable>,
+  ColorSwatchPickerItemProps
+>(
+  (
+    {
+      asChild,
+      color,
+      isDisabled,
+      disabled,
+      accessibilityLabel,
+      'aria-label': ariaLabelProp,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const { registerColor } = useColorSwatchPickerContext();
+    const colorValue = color.toString('hex');
+    const label = ariaLabelProp ?? accessibilityLabel ?? colorValue;
+    const contextValue = useMemo(() => ({ color }), [color]);
+
+    useEffect(() => registerColor(color), [color, registerColor]);
+
+    return (
+      <ColorSwatchPickerItemProvider value={contextValue}>
+        <RadioRoot
+          ref={ref}
+          asChild={asChild}
+          value={colorValue}
+          isDisabled={!!(isDisabled || disabled)}
+          disabled={disabled}
+          aria-label={label}
+          accessibilityLabel={label}
+          {...props}
+        >
+          {children}
+        </RadioRoot>
+      </ColorSwatchPickerItemProvider>
+    );
+  },
+);
+
+ColorSwatchPickerItem.displayName = 'ColorSwatchPickerItem';

package/src/color-swatch-picker/ColorSwatchPickerRoot.tsx

@@ -0,0 +1,94 @@
+import { forwardRef, useCallback, useMemo, useRef, type ComponentRef } from 'react';
+import { View } from 'react-native';
+import { useControllableState } from '@cdx-ui/utils';
+import { RadioGroup } from '../radio';
+import { useOptionalColorPickerContext } from '../color-picker';
+import type { Color } from '../color';
+import { ColorSwatchPickerProvider } from './context';
+import type { IColorSwatchPickerProps } from './types';
+
+export interface ColorSwatchPickerRootProps extends IColorSwatchPickerProps {
+  asChild?: boolean;
+}
+
+export const ColorSwatchPickerRoot = forwardRef<
+  ComponentRef<typeof View>,
+  ColorSwatchPickerRootProps
+>(
+  (
+    {
+      asChild,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      isDisabled,
+      accessibilityLabel,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const picker = useOptionalColorPickerContext();
+    const usesPickerContext =
+      picker !== null && valueProp === undefined && defaultValue === undefined;
+
+    const [localValue, setLocalValue] = useControllableState<Color>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: onValueChange,
+    });
+
+    const value = usesPickerContext ? picker.value : localValue;
+    const colorsRef = useRef(new Map<string, Color>());
+
+    const registerColor = useCallback((color: Color) => {
+      const key = color.toString('hex');
+      colorsRef.current.set(key, color);
+
+      return () => {
+        if (colorsRef.current.get(key) === color) {
+          colorsRef.current.delete(key);
+        }
+      };
+    }, []);
+
+    const handleValueChange = useCallback(
+      (key: string) => {
+        const color = colorsRef.current.get(key);
+
+        if (!color) {
+          return;
+        }
+
+        if (usesPickerContext) {
+          onValueChange?.(color);
+          picker.onValueChange(color);
+          return;
+        }
+
+        setLocalValue(color);
+      },
+      [onValueChange, picker, setLocalValue, usesPickerContext],
+    );
+
+    const contextValue = useMemo(() => ({ registerColor }), [registerColor]);
+
+    return (
+      <ColorSwatchPickerProvider value={contextValue}>
+        <RadioGroup
+          ref={ref}
+          asChild={asChild}
+          value={value?.toString('hex')}
+          onChange={handleValueChange}
+          isDisabled={isDisabled}
+          aria-label={props['aria-label'] ?? accessibilityLabel}
+          {...props}
+        >
+          {children}
+        </RadioGroup>
+      </ColorSwatchPickerProvider>
+    );
+  },
+);
+
+ColorSwatchPickerRoot.displayName = 'ColorSwatchPickerRoot';

package/src/color-swatch-picker/context.tsx

@@ -0,0 +1,22 @@
+import { createContext as createReactContext, useContext } from 'react';
+import { createContext } from '@cdx-ui/utils';
+import type { ColorSwatchPickerContextValue, ColorSwatchPickerItemContextValue } from './types';
+
+export const [ColorSwatchPickerProvider, useColorSwatchPickerContext] =
+  createContext<ColorSwatchPickerContextValue>('ColorSwatchPickerContext');
+
+const ColorSwatchPickerItemContext = createReactContext<ColorSwatchPickerItemContextValue | null>(
+  null,
+);
+
+export const ColorSwatchPickerItemProvider = ColorSwatchPickerItemContext.Provider;
+
+export function useColorSwatchPickerItemContext(): ColorSwatchPickerItemContextValue {
+  const context = useContext(ColorSwatchPickerItemContext);
+
+  if (!context) {
+    throw new Error('ColorSwatchPicker item slots must be used within ColorSwatchPicker.Item');
+  }
+
+  return context;
+}

package/src/color-swatch-picker/index.ts

@@ -0,0 +1,4 @@
+export { ColorSwatchPickerRoot, type ColorSwatchPickerRootProps } from './ColorSwatchPickerRoot';
+export { ColorSwatchPickerItem, type ColorSwatchPickerItemProps } from './ColorSwatchPickerItem';
+export { useColorSwatchPickerContext, useColorSwatchPickerItemContext } from './context';
+export type { IColorSwatchPickerItemProps, IColorSwatchPickerProps } from './types';

package/src/color-swatch-picker/types.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+import type { Color } from '../color';
+
+export interface IColorSwatchPickerProps extends Omit<ViewProps, 'children'> {
+  value?: Color;
+  defaultValue?: Color;
+  onValueChange?: (value: Color) => void;
+  isDisabled?: boolean;
+  children?: ReactNode;
+}
+
+export interface IColorSwatchPickerItemProps extends Omit<PressableProps, 'children'> {
+  color: Color;
+  isDisabled?: boolean;
+  isHovered?: boolean;
+  isActive?: boolean;
+  isFocused?: boolean;
+  isFocusVisible?: boolean;
+  children?: ReactNode;
+}
+
+export interface ColorSwatchPickerContextValue {
+  registerColor: (color: Color) => () => void;
+}
+
+export interface ColorSwatchPickerItemContextValue {
+  color: Color;
+}

package/src/dialog/DialogContent.tsx

@@ -14,20 +14,26 @@ export interface DialogContentProps extends IDialogContentProps {}
  * - ARIA role, aria-modal, aria-labelledby/describedby
  * - FocusScope (focus trap + restore + auto-focus)
  * - Escape key dismissal (web)
- * - Android hardware back button dismissal (native)
+ * - Android hardware back button: calls the context `backHandlerRef` when set, otherwise dismisses (native)
  * - data-state attribute for CSS transition targeting
  *
  * Unstyled — the styled layer applies centering, background, border-radius, etc.
  */
 export const DialogContent = forwardRef<ComponentRef<typeof View>, DialogContentProps>(
   ({ asChild = false, forceMount = false, children, ...props }, ref) => {
-    const { open, onOpenChange, closeOnEscKey, nativeID, role } = useDialog();
+    const { open, onOpenChange, closeOnEscKey, nativeID, role, backHandlerRef } = useDialog();
 
     const handleClose = useCallback(() => {
       onOpenChange(false);
     }, [onOpenChange]);
 
-    useEscapeKey(open && closeOnEscKey, handleClose, {
+    const handleEscape = useCallback(() => {
+      if (closeOnEscKey) onOpenChange(false);
+    }, [closeOnEscKey, onOpenChange]);
+
+    // Registered regardless of `closeOnEscKey` so a non-dismissible dialog still
+    // owns Escape while topmost instead of letting it reach the overlay beneath.
+    useEscapeKey(open, handleEscape, {
       id: nativeID,
       groupId: nativeID,
       layer: 'modal',
@@ -46,14 +52,16 @@ export const DialogContent = forwardRef<ComponentRef<typeof View>, DialogContent
 
       const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
         if (!isTopmost('back')) return false;
-        handleClose();
+        const onBack = backHandlerRef.current;
+        if (onBack) onBack();
+        else handleClose();
         return true;
       });
 
       return () => {
         backHandler.remove();
       };
-    }, [handleClose, isTopmost, open]);
+    }, [backHandlerRef, handleClose, isTopmost, open]);
 
     if (!forceMount && !open) {
       return null;

package/src/dialog/DialogPopup.tsx

@@ -47,7 +47,13 @@ export const DialogPopup = forwardRef<ComponentRef<typeof View>, DialogPopupProp
       onOpenChange(false);
     }, [onOpenChange]);
 
-    useEscapeKey(open && closeOnEscKey, handleClose, {
+    const handleEscape = useCallback(() => {
+      if (closeOnEscKey) onOpenChange(false);
+    }, [closeOnEscKey, onOpenChange]);
+
+    // Registered regardless of `closeOnEscKey` so a non-dismissible dialog still
+    // owns Escape while topmost instead of letting it reach the overlay beneath.
+    useEscapeKey(open, handleEscape, {
       id: nativeID,
       groupId: nativeID,
       layer: 'modal',

package/src/dialog/DialogRoot.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, useCallback, useId, useMemo, type ComponentRef } from 'react';
+import { forwardRef, useCallback, useId, useMemo, useRef, type ComponentRef } from 'react';
 import { View, type ViewProps } from 'react-native';
 import { useControllableState } from '@cdx-ui/utils';
 import { Slot } from '../slot';
@@ -40,6 +40,7 @@ export const DialogRoot = forwardRef<ComponentRef<typeof View>, DialogRootProps>
 
     const id = useId();
     const nativeID = `dialog-${id}`;
+    const backHandlerRef = useRef<(() => void) | undefined>(undefined);
 
     const contextValue = useMemo(
       () => ({
@@ -49,6 +50,7 @@ export const DialogRoot = forwardRef<ComponentRef<typeof View>, DialogRootProps>
         closeOnEscKey,
         nativeID,
         role,
+        backHandlerRef,
       }),
       [open, setOpen, closeOnBackdropPress, closeOnEscKey, nativeID, role],
     );

package/src/dialog/types.ts

@@ -8,6 +8,11 @@ export interface IDialogContextType {
   readonly closeOnEscKey: boolean;
   readonly nativeID: string;
   readonly role: 'dialog' | 'alertdialog';
+  /**
+   * @internal Set by a header that owns step navigation. When set, Android back
+   * calls it instead of closing the dialog. Escape always closes.
+   */
+  readonly backHandlerRef: React.RefObject<(() => void) | undefined>;
 }
 
 export interface IDialogRootProps {
@@ -16,6 +21,12 @@ export interface IDialogRootProps {
   readonly onOpenChange?: (open: boolean) => void;
   readonly defaultOpen?: boolean;
   readonly closeOnBackdropPress?: boolean;
+  /**
+   * Close when Escape is pressed. Web only. When `false`, an open dialog still
+   * consumes Escape while topmost, so overlays beneath it stay open. Android's
+   * hardware back button dismisses independently of this prop.
+   * @default true
+   */
   readonly closeOnEscKey?: boolean;
   readonly role?: 'dialog' | 'alertdialog';
   readonly children: React.ReactNode;
@@ -38,6 +49,7 @@ export interface IDialogOverlayProps extends PressableProps {
 
 export interface IDialogContentProps extends ViewProps {
   readonly asChild?: boolean;
+  /** Keep the popup mounted while the dialog is closed. @default false */
   readonly forceMount?: boolean;
   /**
    * Whether the content shifts up to clear the on-screen keyboard (native only).

package/src/field/types.tsx

@@ -23,7 +23,7 @@ export interface IFieldRootProps extends ViewProps {
   readonly isInvalid?: boolean;
   /** If true, the field is marked as required. Shows asterisk on label. */
   readonly isRequired?: boolean;
-  /** If true, the field is disabled. */
+  /** If true, the field is disabled. Nested controls that read field context are disabled as well. */
   readonly isDisabled?: boolean;
   /** If true, the field is read-only. */
   readonly isReadOnly?: boolean;

package/src/form/types.tsx

@@ -6,8 +6,14 @@ import type React from 'react';
  * for API compatibility but silently ignored.
  */
 export interface InterfaceFormRootProps {
+  /** Called when the form is submitted. Web only; ignored on native. */
   onSubmit?: (e: React.SyntheticEvent) => void;
+  /**
+   * HTML `action` URL, or a function that receives the submitted `FormData`.
+   * Web only; ignored on native.
+   */
   action?: string | ((formData: FormData) => void | Promise<void>);
+  /** HTTP method. Web only; ignored on native. */
   method?: string;
 }
 

package/src/index.ts

@@ -3,6 +3,12 @@ export * from './breadcrumbs';
 export * from './button';
 export * from './chip';
 export * from './checkbox';
+export * from './color';
+export * from './color-area';
+export * from './color-field';
+export * from './color-picker';
+export * from './color-slider';
+export * from './color-swatch-picker';
 export * from './dialog';
 export * from './drawer';
 export * from './field';
@@ -80,4 +86,5 @@ export {
 export { mapViewPropsToDom, type MapViewPropsToDomOptions } from './utils/mapViewPropsToDom';
 export { assignRef } from './utils/assignRef';
 export { createPortalFn } from './utils/createPortal';
+export { useHasTextAncestor } from './utils/textAncestor';
 export { Slot } from './slot';

package/src/input/types.ts

@@ -60,6 +60,7 @@ interface IInputBaseProps extends TextInputProps {
 }
 
 interface IInputTextProps extends IInputBaseProps {
+  /** @default 'text' */
   type?: 'text' | 'password';
 }
 

package/src/link/types.ts

@@ -16,11 +16,11 @@ export type LinkAction = 'navigate' | 'push' | 'replace';
 
 export interface ILinkProps extends PressableProps {
   /**
-   * URL that should be opened on Link press
+   * URL or route path opened on press. Omit when the link only runs `onPress`.
    */
   href?: string | undefined;
   /**
-   * Callback that will be invoked on Link press
+   * Invoked on press before navigation. Does not replace navigation.
    */
   onPress?: ((event?: GestureResponderEvent) => void) | null | undefined;
   /**

package/src/list-item/types.ts

@@ -29,8 +29,9 @@ export interface InterfaceListItemProps extends ViewProps, IListItemPressablePas
    */
   crossAlign?: ListItemCrossAlign;
   /**
-   * Merge interaction props onto a single child instead of rendering the default pressable root.
-   * Intended for use with `onPress`.
+   * Merge props onto a single child (for example `Link`) instead of rendering `View` or `Pressable`.
+   * The child's `onPress` is kept unless this component also passes `onPress`.
+   * `isDisabled` suppresses press on the child.
    */
   asChild?: boolean;
 }

package/src/portal/portal.tsx

@@ -130,7 +130,21 @@ export function PortalProvider({ children }: Readonly<{ children: React.ReactNod
 
 // --------------------------------------------------
 
-export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
+export interface PortalHostProps {
+  /** Host name that `Portal` targets through `hostName`. @default the shared default host */
+  name?: string;
+  /**
+   * Web only. Element that receives the portal content instead of `document.body`.
+   *
+   * Use it to keep overlays inside an embedded surface, such as a device preview. Fixed
+   * overlays stay inside the container only when an ancestor of it creates a containing
+   * block for fixed descendants, for example through a `transform`. While `null`, such as
+   * before a callback ref attaches, the host renders nothing. Ignored on native.
+   */
+  container?: Element | null;
+}
+
+export function PortalHost({ name = DEFAULT_PORTAL_HOST, container }: PortalHostProps) {
   const registry = React.useContext(PortalRegistryContext) ?? fallbackPortalRegistry;
   const hostId = React.useRef(Symbol()).current;
 
@@ -167,7 +181,8 @@ export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
   );
 
   if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
-    return createPortalFn(content, document.body);
+    if (container === null) return null;
+    return createPortalFn(content, container ?? document.body);
   }
 
   return content;

package/src/progress-bar/types.ts

@@ -5,17 +5,22 @@ export type ProgressDataState = 'complete' | 'indeterminate' | 'loading';
 
 export interface InterfaceProgressProps extends Omit<ViewProps, 'children'> {
   /**
-   * Current value in the range [0, max], or `null` for indeterminate progress.
-   * Omit or use a number for determinate progress; default is `0`.
+   * Current value in the range `[0, max]`, or `null` for indeterminate progress.
+   * Values below `0` clamp to `0`; values above `max` clamp to `max`.
+   * Non-finite values (such as `NaN`) are treated as `0`.
+   * @default 0
    */
   readonly value?: number | null;
   /**
-   * Maximum value (minimum is always 0).
+   * Maximum value. The minimum is always `0`.
+   * A `max` of `0` or less is treated as complete.
    * @default 100
    */
   readonly max?: number;
   /**
-   * Optional label for `accessibilityValue.text` when determinate.
+   * Screen-reader text for determinate progress (`accessibilityValue.text`).
+   * Defaults to a rounded percentage of `max`, such as `"45%"`.
+   * No effect when `value` is `null`, or when `accessibilityValue` is set.
    */
   readonly getValueLabel?: (value: number, max: number) => string;
   readonly children?: ReactNode;

package/src/radio/types.ts

@@ -3,8 +3,10 @@ import type { PressableProps } from 'react-native';
 export interface IRadioProps extends PressableProps {
   /** Required — identifies this item's value within a Radio.Group. */
   value: string;
+  /** Disables this item without disabling the rest of the group. */
   isDisabled?: boolean;
   isInvalid?: boolean;
+  /** Focusable, but the selection cannot be changed. */
   isReadOnly?: boolean;
   isHovered?: boolean;
   isFocused?: boolean;

package/src/react-native-web.d.ts

@@ -0,0 +1,6 @@
+declare module 'react-native-web/dist/exports/Text/TextAncestorContext' {
+  import type { Context } from 'react';
+
+  const TextAncestorContext: Context<boolean>;
+  export default TextAncestorContext;
+}

package/src/select/SelectContent.tsx

@@ -2,7 +2,7 @@ import React, { forwardRef, useCallback, useRef, type ComponentRef } from 'react
 import { Platform, View } from 'react-native';
 import { FadeIn, FadeOut } from 'react-native-reanimated';
 import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
-import { OverlayContainer, useAnchoredOverlay, useDismissOverlay } from '../overlay';
+import { OverlayContainer, useAnchoredOverlay, useDismissOverlay, useEscapeKey } from '../overlay';
 import { Slot } from '../slot';
 import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
 import { useSelectContext } from './context';
@@ -76,6 +76,7 @@ export const SelectContent = forwardRef<ComponentRef<typeof View>, SelectContent
     const mergedRef = mergeRefs(ref, focusOnMount as unknown as React.Ref<View>, floatingRef);
 
     useDismissOverlay(overlayOpen, contentRef, [triggerRef], dismiss);
+    useEscapeKey(overlayOpen, dismiss);
 
     const { handleKeyDown } = useListboxNavigation({
       items,

package/src/slider/useSliderPointer.ts

@@ -97,6 +97,9 @@ export function useWebSliderDrag({
         return;
       }
 
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+
       const trackSize = orientation === 'horizontal' ? layout.width : layout.height;
       const travel = getThumbTravel(trackSize, thumbSize);
       if (travel <= 0) {

package/src/switch/types.ts

@@ -7,11 +7,11 @@ export interface IInterfaceSwitchProps {
    */
   onValueChange?: (value: boolean) => void;
   /**
-   * If true, set the Switch to the checked state.
+   * Alias for `value`. `value` takes precedence when both are set.
    */
   isChecked?: boolean;
   /**
-   * The current value of the switch.
+   * Controlled on/off state. Takes precedence over `isChecked`.
    */
   value?: boolean;
   /**
@@ -19,11 +19,11 @@ export interface IInterfaceSwitchProps {
    */
   isDisabled?: boolean;
   /**
-   * If true, the switch will be disabled.
+   * Alias for `isDisabled`. Either prop disables the switch.
    */
   disabled?: boolean;
   /**
-   * If true, the switch will be initially checked.
+   * Initial state when uncontrolled. No effect when `value` or `isChecked` is set.
    */
   defaultValue?: boolean;
   /**

package/src/tabs/types.ts

@@ -13,7 +13,8 @@ export interface ITabsProps {
   onValueChange?: (value: string) => void;
   /**
    * `automatic` (default) selects a tab as soon as it receives focus via arrow keys.
-   * `manual` only moves focus on arrow keys — the consumer must press Enter/Space to select.
+   * `manual` only moves focus — press Enter or Space to select. Web only; native
+   * selection follows press. Use `manual` when rendering the next panel is expensive.
    */
   activationMode?: TabsActivationMode;
   /**
@@ -21,6 +22,7 @@ export interface ITabsProps {
    * `vertical` uses ArrowUp/ArrowDown, per the ARIA APG tabs pattern.
    */
   orientation?: TabsOrientation;
+  /** Disables every tab. Disable a single tab with `disabled` on that `Tabs.Tab`. */
   disabled?: boolean;
   children?: ReactNode;
 }
@@ -63,7 +65,10 @@ export interface ITabProps extends PressableProps {
 export interface ITabPanelProps extends ViewProps {
   /** Required — correlates this panel with its `Tabs.Tab` counterpart. */
   value: string;
-  /** Unmount when inactive instead of keeping the panel hidden in the DOM. */
+  /**
+   * Unmount when inactive instead of keeping the panel mounted and hidden.
+   * The default keeps it mounted so the tab's `aria-controls` target stays in the tree.
+   */
   unmountWhenInactive?: boolean;
   children?: ReactNode;
 }