@capra/core 1.11.1 → 1.13.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as React$2 from "react";
-import React$1, { HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy } from "react";
+import React$1, { HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy, ReactNode } from "react";
 import { BreadcrumbProps as BreadcrumbProps$1, BreadcrumbsProps as BreadcrumbsProps$1, ButtonProps as ButtonProps$1, ComboBoxRenderProps, DatePickerProps, DateRangePickerProps, DateValue, DisclosureProps, Focusable, Key, LinkProps as LinkProps$1, ListBoxItemProps, PopoverProps as PopoverProps$1, PressEvent, RouterProvider } from "react-aria-components";
 import { SvgIcon } from "@capra/icons";
 import { SvgLogo } from "@capra/icons/logos";
@@ -125,6 +125,11 @@ declare const TextInput: React$2.ForwardRefExoticComponent<{
   trailingSlot?: React$2.ReactNode;
 } & StylingOverrideProps & Omit<Omit<React$2.DetailedHTMLProps<React$2.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "className" | "size" | "style"> & React$2.RefAttributes<HTMLInputElement>>;
 //#endregion
+//#region src/components/input-helpers/ChildrenOrFunction.d.ts
+type ChildrenOrFunction$1<T> = ReactNode | ((values: T & {
+  defaultChildren: ReactNode | undefined;
+}) => ReactNode);
+//#endregion
 //#region src/components/input-helpers/fieldLayout.d.ts
 type FieldLayoutProps = {
   /** Helper text below the field. Replaced by error message when status is error. Use for requirements, disclaimers. */
@@ -139,9 +144,7 @@ type FieldLayoutProps = {
 type AutocompleteItem = {
   value: string;
 };
-type ChildrenOrFunction<T> = React$1.ReactNode | ((values: T & {
-  defaultChildren: React$1.ReactNode | undefined;
-}) => React$1.ReactNode);
+type ChildrenOrFunction<T> = ChildrenOrFunction$1<T>;
 type AutocompleteFieldProps = {
   /** Whether to show a clear button for the input. */
   canClear?: boolean;
@@ -735,6 +738,125 @@ declare const DatePickerField: React$2.ForwardRefExoticComponent<FieldLayoutProp
   isInvalid?: boolean;
 } & React$2.RefAttributes<HTMLDivElement>>;
 //#endregion
+//#region src/components/SelectField/SelectField.d.ts
+type SelectionMode = 'single' | 'multiple';
+type DefaultItem = {
+  id: Key;
+  label: string;
+  /** Optional icon rendered before the label. */
+  icon?: SvgIcon;
+};
+/** A group of `DefaultItem`s, rendered as a labeled section. Enables defining sections via `items` instead of JSX children. */
+type DefaultSection = {
+  /** Unique key for the section. */
+  id: Key;
+  /** Visible header label. Omit for an unlabeled group (then pass `aria-label`). */
+  label?: string;
+  /** Accessible name when there is no visible header. */
+  'aria-label'?: string;
+  /** Options within this section. */
+  children: Iterable<DefaultItem>;
+};
+type DefaultItemOrSection = DefaultItem | DefaultSection;
+type ItemRenderer<T extends object> = (item: T) => React$2.ReactElement;
+type ItemsChildren<T extends object> = React$2.ReactNode | ItemRenderer<T>;
+type SelectFieldProps<T extends object = DefaultItemOrSection, M extends SelectionMode = 'single'> = FieldLayoutProps & StylingOverrideProps & {
+  /** Visual status of the trigger. `danger` marks the field invalid for accessibility and helper text treatment. @default 'default' */
+  appearance?: Appearance$2;
+  /** Trigger size variant. @default 'md' */
+  size?: Size$3;
+  /** Optional content rendered before the selected value, such as an icon. Pass a single node or group multiple nodes in a fragment or array. */
+  leadingSlot?: React$2.ReactNode;
+  /** Placeholder text shown in the trigger when there is no selection. Omit to render an empty trigger instead of a default placeholder. */
+  placeholder?: string;
+  /** Disables the field and prevents opening the listbox. */
+  disabled?: boolean;
+  /** Marks the field as required and shows the required indicator on the label. */
+  required?: boolean;
+  /** HTML `id` for the field root; associates the label, trigger, and helper text. */
+  id?: string;
+  /** Form field `name` used for native form submission. */
+  name?: string;
+  /** Whether to focus the trigger on mount. */
+  autoFocus?: boolean;
+  /** Selection behavior for the field. @default 'single' */
+  selectionMode?: M;
+  /** Controlled selected key, or selected keys when `selectionMode` is `multiple`. */
+  value?: M extends 'multiple' ? Iterable<Key> : Key | null;
+  /** Uncontrolled initial selected key, or keys when `selectionMode` is `multiple`. */
+  defaultValue?: M extends 'multiple' ? Iterable<Key> : Key | null;
+  /** Called when the selection changes. Receives a `Set` of keys in multiple selection mode. */
+  onChange?: (value: M extends 'multiple' ? Set<Key> : Key | null) => void;
+  /** Controlled open state for the options popover. */
+  isOpen?: boolean;
+  /** Uncontrolled initial open state for the options popover. */
+  defaultOpen?: boolean;
+  /** Called when the options popover opens or closes. */
+  onOpenChange?: (isOpen: boolean) => void;
+  /** When true, renders a search input in the popover to filter options. */
+  canSearch?: boolean;
+  /** Placeholder text for the in-popover search input when `canSearch` is true. */
+  searchPlaceholder?: string;
+  /** Whether the popover should be at least as wide as the trigger. @default true */
+  shouldAutoSizeDropdown?: boolean;
+  /** Accessible name when a visible `label` is not provided. */
+  'aria-label'?: string;
+  /** Id of an element that labels the field when a visible `label` is not used. */
+  'aria-labelledby'?: string;
+  /** Id of an element that describes the field, such as external helper or error text. */
+  'aria-describedby'?: string;
+  /** Data source for dynamic option rendering. Omit to render static `SelectField.Item` children instead. */
+  items?: Iterable<T>;
+  /** Key(s) of options that cannot be selected, focused, or otherwise interacted with. */
+  disabledKeys?: Iterable<Key>;
+  /** Static `SelectField.Item` children, or a render function for each item in `items`. Defaults to rendering each item's `id` and `label` when `items` is provided and `children` is omitted. */
+  children?: ItemsChildren<T>;
+};
+type SelectFieldItemProps = {
+  /** Unique key for the option. */
+  id: Key;
+  /** Text used for typeahead and accessibility name computation. */
+  textValue?: string;
+  /** Disables the option, preventing selection, focus, and interaction. */
+  isDisabled?: boolean;
+  /**
+   * Extra inset for the row. When omitted, items inside {@link SelectField.Section} with a {@link SelectField.Header} indent automatically.
+   */
+  indent?: boolean;
+  /** The object value this item represents. Set automatically when using dynamic collections via `items`. */
+  value?: object;
+  /** Content rendered for the option label. */
+  children: React$2.ReactNode;
+};
+type SelectFieldHeaderProps = StylingOverrideProps & {
+  /**
+   * Optional id for `aria-labelledby` on {@link SelectField.Section}. When omitted inside a section, an id is assigned automatically.
+   */
+  id?: string;
+  /** Header label. */
+  label?: React$2.ReactNode;
+  /** Children for compound usage. */
+  children?: React$2.ReactNode;
+};
+type SelectFieldSectionProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLElement>, 'role'> & {
+  /**
+   * Groups {@link SelectField.Item} rows. Use with an optional {@link SelectField.Header} to label the group.
+   * If there is no header, pass `aria-label` (or `aria-labelledby`) so the group has an accessible name.
+   */
+  children?: React$2.ReactNode;
+};
+declare function SelectFieldItem(props: SelectFieldItemProps): React$2.JSX.Element;
+declare function SelectFieldHeader(props: SelectFieldHeaderProps): React$2.JSX.Element;
+declare function SelectFieldSection(props: SelectFieldSectionProps): React$2.JSX.Element;
+/**
+ * Composed select field with Capra label/helper text layout, single and multiple selection, and an optional popover search input.
+ */
+declare const SelectField: (<T extends object = DefaultItemOrSection, M extends SelectionMode = "single">(props: SelectFieldProps<T, M> & React$2.RefAttributes<HTMLDivElement>) => React$2.ReactElement | null) & {
+  Item: typeof SelectFieldItem;
+  Header: typeof SelectFieldHeader;
+  Section: typeof SelectFieldSection;
+};
+//#endregion
 //#region src/components/DateRangePickerField/DateRangePickerField.d.ts
 /** Visible placeholders for empty start/end when the field is not focus-within. */
 type DateRangePickerFieldPlaceholder = readonly [string, string];
@@ -1741,7 +1863,7 @@ declare const Toast: ToastAPI & {
 };
 //#endregion
 //#region src/components/Menu/Menu.d.ts
-type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.ComponentPropsWithoutRef<As>, 'className' | 'as' | 'children' | 'href' | 'onClick' | 'disabled' | 'type' | 'role'> & StylingOverrideProps & {
+type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.ComponentPropsWithoutRef<As>, 'className' | 'as' | 'children' | 'href' | 'onClick' | 'disabled' | 'type' | 'role'> & RoutedLinkProps & StylingOverrideProps & {
   /**
    * The component to use for the item. Default is either 'a' or 'button' based on the presence of the href prop.
    */
@@ -1758,10 +1880,6 @@ type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.Componen
    * Accessible name when it differs from the visible `label` (e.g. tab position and selection state). Passed to the menu item as `aria-label`.
    */
   ariaLabel?: string;
-  /**
-   * URL for the default native `<a>` (full document navigation). With `as={Link}` from your router, use that component’s props (`to`, `href`, …) instead or in addition.
-   */
-  href?: string;
   /**
    * Whether the item is disabled.
    */
@@ -1908,8 +2026,9 @@ interface MenuProps extends StylingOverrideProps {
   panelPadding?: 'default' | 'none';
   /**
    * Gap along the main axis between the trigger and the menu panel (React Aria `Popover` `offset`).
-   * Use a small value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).
-   * @default 0
+   * Defaults to 2px to match `spacing.xs`; `Popover` positioning takes a number, so the token cannot be applied via CSS.
+   * Use a smaller value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).
+   * @default 2
    */
   popoverOffset?: number;
   /**
@@ -1972,7 +2091,7 @@ declare const tabNavPlacements: readonly ['horizontal', 'vertical'];
 type TabNavPlacement = (typeof tabNavPlacements)[number];
 declare const tabNavItemVariants: readonly ['default', 'dropdown'];
 type TabNavItemVariant = (typeof tabNavItemVariants)[number];
-interface TabNavSubItemType {
+interface TabNavSubItemType extends RoutedLinkProps {
   /** Unique key for the sub-item. */
   key: string;
   /** Visible text in the submenu row (dropdown or vertical list). */
@@ -1983,10 +2102,17 @@ interface TabNavSubItemType {
   href?: string;
   /** Whether the sub-item is disabled. */
   disabled?: boolean;
-  /** Click handler. Use e.preventDefault() in demos to prevent navigation. */
+  /**
+   * Press handler.
+   */
+  onPress?: () => void;
+  /**
+   * Click handler. Use e.preventDefault() in demos to prevent navigation.
+   * @deprecated Use `onPress` instead.
+   */
   onClick?: (e: React$2.MouseEvent) => void;
 }
-interface TabNavItemType {
+interface TabNavItemType extends RoutedLinkProps {
   /**
    * Unique key for the tab.
    */
@@ -1995,11 +2121,6 @@ interface TabNavItemType {
   name: React$2.ReactNode;
   /** Optional accessible name for the tab (maps to `aria-label` on the control). */
   'aria-label'?: string;
-  /**
-   * Link URL. When provided, the tab navigates to this URL on click.
-   * Required for tabs without subItems.
-   */
-  href?: string;
   /**
    * Whether the tab is disabled.
    */
@@ -2028,8 +2149,13 @@ type TabNavProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLDivEle
    * Key of the currently active tab (for visual styling). Typically derived from the current URL.
    */
   activeKey?: string;
+  /**
+   * Callback when a tab link is pressed (before navigation).
+   */
+  onTabPress?: (key: string) => void;
   /**
    * Callback when a tab link is clicked (before navigation).
+   * @deprecated Use `onTabPress` instead.
    */
   onTabClick?: (key: string, event: React$2.MouseEvent) => void;
   /**
@@ -2056,7 +2182,7 @@ type TabNavProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLDivEle
    */
   wrap?: boolean;
 };
-declare function TabNav({ activeKey, onTabClick, items, tabPlacement, centered, tabBarExtraSlot, wrap, FORCE__className: classNameOverride, 'aria-label': ariaLabel, ...props }: TabNavProps): React$2.JSX.Element;
+declare function TabNav({ activeKey, onTabPress, onTabClick, items, tabPlacement, centered, tabBarExtraSlot, wrap, FORCE__className: classNameOverride, 'aria-label': ariaLabel, ...props }: TabNavProps): React$2.JSX.Element;
 declare namespace TabNav {
   var displayName: string;
 }
@@ -2250,4 +2376,4 @@ declare const Label: React$2.ForwardRefExoticComponent<{
   trailingSlot?: React$2.ReactNode;
 } & StylingOverrideProps & Omit<Omit<React$2.DetailedHTMLProps<React$2.LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>, "ref">, "className" | "style"> & React$2.RefAttributes<HTMLLabelElement>>;
 //#endregion
-export { Alert, type AlertProps, Anchor, type AnchorProps, AutocompleteField, type AutocompleteFieldProps, Badge, BadgeLayout, type BadgeProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Card, Checkbox, type CheckboxProps, Collapse, type CollapseProps, CustomTooltipTrigger, type CustomTooltipTriggerProps, DatePickerField, type DatePickerFieldProps, DateRangePickerField, type DateRangePickerFieldPlaceholder, type DateRangePickerFieldProps, Divider, type DividerProps, type DividerType, Drawer, type DrawerPlacement, type DrawerProps, EmptyState, type EmptyStateProps, IconButton, type IconButtonProps, InputRow, type InputRowAddonProps, type InputRowProps, Label, type LabelProps, Link, type LinkProps, ListItem, type ListItemProps, Menu, type MenuDividerProps, type MenuHeaderProps, type MenuItemProps, type MenuListProps, type MenuPanelPadding, type MenuProps, type MenuSectionProps, type MenuSubmenuProps, Modal, type ModalProps, NumberField, type NumberFieldProps, Pagination, type PaginationProps, PasswordField, type PasswordFieldProps, Pill, type PillProps, Popover, type PopoverProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, RadioTile, type RadioTileProps, Ribbon, type RibbonProps, type RoutedLinkProps, RouterProvider, SKELETON_SIZE, SKELETON_SIZE_TOKENS, Skeleton, type SkeletonElementProps, SkeletonGroup, type SkeletonGroupButtonProps, type SkeletonGroupInputProps, type SkeletonGroupNodeProps, type SkeletonParagraphProps, type SkeletonProps, type SkeletonSize, type SkeletonTitleProps, Spinner, type SpinnerProps, type StylingOverrideProps, Switch, type SwitchProps, TabNav, type TabNavItemType, type TabNavItemVariant, type TabNavPlacement, type TabNavProps, type TabNavSubItemType, Tag, type TagColor, type TagProps, Text, TextArea, type TextAreaAutoSize, type TextAreaProps, TextField, type TextFieldProps, type TextProps, Toast, type ToastOptions, type ToastPosition, type ToastType, Tooltip, type TooltipProps, TopNav, type TopNavCenterProps, type TopNavEndProps, type TopNavProps, type TopNavStartProps, Tree, type TreeItemType, type TreeProps, VerticalNavigation, type VerticalNavigationCollapseProps, type VerticalNavigationFooterProps, type VerticalNavigationItemListProps, type VerticalNavigationItemProps, type VerticalNavigationProps, VisuallyHidden, type VisuallyHiddenProps, submenuPanelClassName, tagColors };
+export { Alert, type AlertProps, Anchor, type AnchorProps, AutocompleteField, type AutocompleteFieldProps, Badge, BadgeLayout, type BadgeProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Card, Checkbox, type CheckboxProps, Collapse, type CollapseProps, CustomTooltipTrigger, type CustomTooltipTriggerProps, DatePickerField, type DatePickerFieldProps, DateRangePickerField, type DateRangePickerFieldPlaceholder, type DateRangePickerFieldProps, Divider, type DividerProps, type DividerType, Drawer, type DrawerPlacement, type DrawerProps, EmptyState, type EmptyStateProps, IconButton, type IconButtonProps, InputRow, type InputRowAddonProps, type InputRowProps, Label, type LabelProps, Link, type LinkProps, ListItem, type ListItemProps, Menu, type MenuDividerProps, type MenuHeaderProps, type MenuItemProps, type MenuListProps, type MenuPanelPadding, type MenuProps, type MenuSectionProps, type MenuSubmenuProps, Modal, type ModalProps, NumberField, type NumberFieldProps, Pagination, type PaginationProps, PasswordField, type PasswordFieldProps, Pill, type PillProps, Popover, type PopoverProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, RadioTile, type RadioTileProps, Ribbon, type RibbonProps, type RoutedLinkProps, RouterProvider, SKELETON_SIZE, SKELETON_SIZE_TOKENS, SelectField, type SelectFieldHeaderProps, type SelectFieldItemProps, type SelectFieldProps, type SelectFieldSectionProps, Skeleton, type SkeletonElementProps, SkeletonGroup, type SkeletonGroupButtonProps, type SkeletonGroupInputProps, type SkeletonGroupNodeProps, type SkeletonParagraphProps, type SkeletonProps, type SkeletonSize, type SkeletonTitleProps, Spinner, type SpinnerProps, type StylingOverrideProps, Switch, type SwitchProps, TabNav, type TabNavItemType, type TabNavItemVariant, type TabNavPlacement, type TabNavProps, type TabNavSubItemType, Tag, type TagColor, type TagProps, Text, TextArea, type TextAreaAutoSize, type TextAreaProps, TextField, type TextFieldProps, type TextProps, Toast, type ToastOptions, type ToastPosition, type ToastType, Tooltip, type TooltipProps, TopNav, type TopNavCenterProps, type TopNavEndProps, type TopNavProps, type TopNavStartProps, Tree, type TreeItemType, type TreeProps, VerticalNavigation, type VerticalNavigationCollapseProps, type VerticalNavigationFooterProps, type VerticalNavigationItemListProps, type VerticalNavigationItemProps, type VerticalNavigationProps, VisuallyHidden, type VisuallyHiddenProps, submenuPanelClassName, tagColors };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as React$2 from "react";
-import React$1, { HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy } from "react";
+import React$1, { HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy, ReactNode } from "react";
 import { SvgIcon } from "@capra/icons";
 import { BreadcrumbProps as BreadcrumbProps$1, BreadcrumbsProps as BreadcrumbsProps$1, ButtonProps as ButtonProps$1, ComboBoxRenderProps, DatePickerProps, DateRangePickerProps, DateValue, DisclosureProps, Focusable, Key, LinkProps as LinkProps$1, ListBoxItemProps, PopoverProps as PopoverProps$1, PressEvent, RouterProvider } from "react-aria-components";
 import { SvgLogo } from "@capra/icons/logos";
@@ -125,6 +125,11 @@ declare const TextInput: React$2.ForwardRefExoticComponent<{
   trailingSlot?: React$2.ReactNode;
 } & StylingOverrideProps & Omit<Omit<React$2.DetailedHTMLProps<React$2.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "className" | "size" | "style"> & React$2.RefAttributes<HTMLInputElement>>;
 //#endregion
+//#region src/components/input-helpers/ChildrenOrFunction.d.ts
+type ChildrenOrFunction$1<T> = ReactNode | ((values: T & {
+  defaultChildren: ReactNode | undefined;
+}) => ReactNode);
+//#endregion
 //#region src/components/input-helpers/fieldLayout.d.ts
 type FieldLayoutProps = {
   /** Helper text below the field. Replaced by error message when status is error. Use for requirements, disclaimers. */
@@ -139,9 +144,7 @@ type FieldLayoutProps = {
 type AutocompleteItem = {
   value: string;
 };
-type ChildrenOrFunction<T> = React$1.ReactNode | ((values: T & {
-  defaultChildren: React$1.ReactNode | undefined;
-}) => React$1.ReactNode);
+type ChildrenOrFunction<T> = ChildrenOrFunction$1<T>;
 type AutocompleteFieldProps = {
   /** Whether to show a clear button for the input. */
   canClear?: boolean;
@@ -735,6 +738,125 @@ declare const DatePickerField: React$2.ForwardRefExoticComponent<FieldLayoutProp
   isInvalid?: boolean;
 } & React$2.RefAttributes<HTMLDivElement>>;
 //#endregion
+//#region src/components/SelectField/SelectField.d.ts
+type SelectionMode = 'single' | 'multiple';
+type DefaultItem = {
+  id: Key;
+  label: string;
+  /** Optional icon rendered before the label. */
+  icon?: SvgIcon;
+};
+/** A group of `DefaultItem`s, rendered as a labeled section. Enables defining sections via `items` instead of JSX children. */
+type DefaultSection = {
+  /** Unique key for the section. */
+  id: Key;
+  /** Visible header label. Omit for an unlabeled group (then pass `aria-label`). */
+  label?: string;
+  /** Accessible name when there is no visible header. */
+  'aria-label'?: string;
+  /** Options within this section. */
+  children: Iterable<DefaultItem>;
+};
+type DefaultItemOrSection = DefaultItem | DefaultSection;
+type ItemRenderer<T extends object> = (item: T) => React$2.ReactElement;
+type ItemsChildren<T extends object> = React$2.ReactNode | ItemRenderer<T>;
+type SelectFieldProps<T extends object = DefaultItemOrSection, M extends SelectionMode = 'single'> = FieldLayoutProps & StylingOverrideProps & {
+  /** Visual status of the trigger. `danger` marks the field invalid for accessibility and helper text treatment. @default 'default' */
+  appearance?: Appearance$2;
+  /** Trigger size variant. @default 'md' */
+  size?: Size$3;
+  /** Optional content rendered before the selected value, such as an icon. Pass a single node or group multiple nodes in a fragment or array. */
+  leadingSlot?: React$2.ReactNode;
+  /** Placeholder text shown in the trigger when there is no selection. Omit to render an empty trigger instead of a default placeholder. */
+  placeholder?: string;
+  /** Disables the field and prevents opening the listbox. */
+  disabled?: boolean;
+  /** Marks the field as required and shows the required indicator on the label. */
+  required?: boolean;
+  /** HTML `id` for the field root; associates the label, trigger, and helper text. */
+  id?: string;
+  /** Form field `name` used for native form submission. */
+  name?: string;
+  /** Whether to focus the trigger on mount. */
+  autoFocus?: boolean;
+  /** Selection behavior for the field. @default 'single' */
+  selectionMode?: M;
+  /** Controlled selected key, or selected keys when `selectionMode` is `multiple`. */
+  value?: M extends 'multiple' ? Iterable<Key> : Key | null;
+  /** Uncontrolled initial selected key, or keys when `selectionMode` is `multiple`. */
+  defaultValue?: M extends 'multiple' ? Iterable<Key> : Key | null;
+  /** Called when the selection changes. Receives a `Set` of keys in multiple selection mode. */
+  onChange?: (value: M extends 'multiple' ? Set<Key> : Key | null) => void;
+  /** Controlled open state for the options popover. */
+  isOpen?: boolean;
+  /** Uncontrolled initial open state for the options popover. */
+  defaultOpen?: boolean;
+  /** Called when the options popover opens or closes. */
+  onOpenChange?: (isOpen: boolean) => void;
+  /** When true, renders a search input in the popover to filter options. */
+  canSearch?: boolean;
+  /** Placeholder text for the in-popover search input when `canSearch` is true. */
+  searchPlaceholder?: string;
+  /** Whether the popover should be at least as wide as the trigger. @default true */
+  shouldAutoSizeDropdown?: boolean;
+  /** Accessible name when a visible `label` is not provided. */
+  'aria-label'?: string;
+  /** Id of an element that labels the field when a visible `label` is not used. */
+  'aria-labelledby'?: string;
+  /** Id of an element that describes the field, such as external helper or error text. */
+  'aria-describedby'?: string;
+  /** Data source for dynamic option rendering. Omit to render static `SelectField.Item` children instead. */
+  items?: Iterable<T>;
+  /** Key(s) of options that cannot be selected, focused, or otherwise interacted with. */
+  disabledKeys?: Iterable<Key>;
+  /** Static `SelectField.Item` children, or a render function for each item in `items`. Defaults to rendering each item's `id` and `label` when `items` is provided and `children` is omitted. */
+  children?: ItemsChildren<T>;
+};
+type SelectFieldItemProps = {
+  /** Unique key for the option. */
+  id: Key;
+  /** Text used for typeahead and accessibility name computation. */
+  textValue?: string;
+  /** Disables the option, preventing selection, focus, and interaction. */
+  isDisabled?: boolean;
+  /**
+   * Extra inset for the row. When omitted, items inside {@link SelectField.Section} with a {@link SelectField.Header} indent automatically.
+   */
+  indent?: boolean;
+  /** The object value this item represents. Set automatically when using dynamic collections via `items`. */
+  value?: object;
+  /** Content rendered for the option label. */
+  children: React$2.ReactNode;
+};
+type SelectFieldHeaderProps = StylingOverrideProps & {
+  /**
+   * Optional id for `aria-labelledby` on {@link SelectField.Section}. When omitted inside a section, an id is assigned automatically.
+   */
+  id?: string;
+  /** Header label. */
+  label?: React$2.ReactNode;
+  /** Children for compound usage. */
+  children?: React$2.ReactNode;
+};
+type SelectFieldSectionProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLElement>, 'role'> & {
+  /**
+   * Groups {@link SelectField.Item} rows. Use with an optional {@link SelectField.Header} to label the group.
+   * If there is no header, pass `aria-label` (or `aria-labelledby`) so the group has an accessible name.
+   */
+  children?: React$2.ReactNode;
+};
+declare function SelectFieldItem(props: SelectFieldItemProps): React$2.JSX.Element;
+declare function SelectFieldHeader(props: SelectFieldHeaderProps): React$2.JSX.Element;
+declare function SelectFieldSection(props: SelectFieldSectionProps): React$2.JSX.Element;
+/**
+ * Composed select field with Capra label/helper text layout, single and multiple selection, and an optional popover search input.
+ */
+declare const SelectField: (<T extends object = DefaultItemOrSection, M extends SelectionMode = "single">(props: SelectFieldProps<T, M> & React$2.RefAttributes<HTMLDivElement>) => React$2.ReactElement | null) & {
+  Item: typeof SelectFieldItem;
+  Header: typeof SelectFieldHeader;
+  Section: typeof SelectFieldSection;
+};
+//#endregion
 //#region src/components/DateRangePickerField/DateRangePickerField.d.ts
 /** Visible placeholders for empty start/end when the field is not focus-within. */
 type DateRangePickerFieldPlaceholder = readonly [string, string];
@@ -1741,7 +1863,7 @@ declare const Toast: ToastAPI & {
 };
 //#endregion
 //#region src/components/Menu/Menu.d.ts
-type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.ComponentPropsWithoutRef<As>, 'className' | 'as' | 'children' | 'href' | 'onClick' | 'disabled' | 'type' | 'role'> & StylingOverrideProps & {
+type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.ComponentPropsWithoutRef<As>, 'className' | 'as' | 'children' | 'href' | 'onClick' | 'disabled' | 'type' | 'role'> & RoutedLinkProps & StylingOverrideProps & {
   /**
    * The component to use for the item. Default is either 'a' or 'button' based on the presence of the href prop.
    */
@@ -1758,10 +1880,6 @@ type MenuItemProps<As extends React$2.ElementType = 'a'> = Omit<React$2.Componen
    * Accessible name when it differs from the visible `label` (e.g. tab position and selection state). Passed to the menu item as `aria-label`.
    */
   ariaLabel?: string;
-  /**
-   * URL for the default native `<a>` (full document navigation). With `as={Link}` from your router, use that component’s props (`to`, `href`, …) instead or in addition.
-   */
-  href?: string;
   /**
    * Whether the item is disabled.
    */
@@ -1908,8 +2026,9 @@ interface MenuProps extends StylingOverrideProps {
   panelPadding?: 'default' | 'none';
   /**
    * Gap along the main axis between the trigger and the menu panel (React Aria `Popover` `offset`).
-   * Use a small value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).
-   * @default 0
+   * Defaults to 2px to match `spacing.xs`; `Popover` positioning takes a number, so the token cannot be applied via CSS.
+   * Use a smaller value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).
+   * @default 2
    */
   popoverOffset?: number;
   /**
@@ -1972,7 +2091,7 @@ declare const tabNavPlacements: readonly ['horizontal', 'vertical'];
 type TabNavPlacement = (typeof tabNavPlacements)[number];
 declare const tabNavItemVariants: readonly ['default', 'dropdown'];
 type TabNavItemVariant = (typeof tabNavItemVariants)[number];
-interface TabNavSubItemType {
+interface TabNavSubItemType extends RoutedLinkProps {
   /** Unique key for the sub-item. */
   key: string;
   /** Visible text in the submenu row (dropdown or vertical list). */
@@ -1983,10 +2102,17 @@ interface TabNavSubItemType {
   href?: string;
   /** Whether the sub-item is disabled. */
   disabled?: boolean;
-  /** Click handler. Use e.preventDefault() in demos to prevent navigation. */
+  /**
+   * Press handler.
+   */
+  onPress?: () => void;
+  /**
+   * Click handler. Use e.preventDefault() in demos to prevent navigation.
+   * @deprecated Use `onPress` instead.
+   */
   onClick?: (e: React$2.MouseEvent) => void;
 }
-interface TabNavItemType {
+interface TabNavItemType extends RoutedLinkProps {
   /**
    * Unique key for the tab.
    */
@@ -1995,11 +2121,6 @@ interface TabNavItemType {
   name: React$2.ReactNode;
   /** Optional accessible name for the tab (maps to `aria-label` on the control). */
   'aria-label'?: string;
-  /**
-   * Link URL. When provided, the tab navigates to this URL on click.
-   * Required for tabs without subItems.
-   */
-  href?: string;
   /**
    * Whether the tab is disabled.
    */
@@ -2028,8 +2149,13 @@ type TabNavProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLDivEle
    * Key of the currently active tab (for visual styling). Typically derived from the current URL.
    */
   activeKey?: string;
+  /**
+   * Callback when a tab link is pressed (before navigation).
+   */
+  onTabPress?: (key: string) => void;
   /**
    * Callback when a tab link is clicked (before navigation).
+   * @deprecated Use `onTabPress` instead.
    */
   onTabClick?: (key: string, event: React$2.MouseEvent) => void;
   /**
@@ -2056,7 +2182,7 @@ type TabNavProps = StylingOverrideProps & Omit<React$2.HTMLAttributes<HTMLDivEle
    */
   wrap?: boolean;
 };
-declare function TabNav({ activeKey, onTabClick, items, tabPlacement, centered, tabBarExtraSlot, wrap, FORCE__className: classNameOverride, 'aria-label': ariaLabel, ...props }: TabNavProps): React$2.JSX.Element;
+declare function TabNav({ activeKey, onTabPress, onTabClick, items, tabPlacement, centered, tabBarExtraSlot, wrap, FORCE__className: classNameOverride, 'aria-label': ariaLabel, ...props }: TabNavProps): React$2.JSX.Element;
 declare namespace TabNav {
   var displayName: string;
 }
@@ -2250,4 +2376,4 @@ declare const Label: React$2.ForwardRefExoticComponent<{
   trailingSlot?: React$2.ReactNode;
 } & StylingOverrideProps & Omit<Omit<React$2.DetailedHTMLProps<React$2.LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>, "ref">, "className" | "style"> & React$2.RefAttributes<HTMLLabelElement>>;
 //#endregion
-export { Alert, type AlertProps, Anchor, type AnchorProps, AutocompleteField, type AutocompleteFieldProps, Badge, BadgeLayout, type BadgeProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Card, Checkbox, type CheckboxProps, Collapse, type CollapseProps, CustomTooltipTrigger, type CustomTooltipTriggerProps, DatePickerField, type DatePickerFieldProps, DateRangePickerField, type DateRangePickerFieldPlaceholder, type DateRangePickerFieldProps, Divider, type DividerProps, type DividerType, Drawer, type DrawerPlacement, type DrawerProps, EmptyState, type EmptyStateProps, IconButton, type IconButtonProps, InputRow, type InputRowAddonProps, type InputRowProps, Label, type LabelProps, Link, type LinkProps, ListItem, type ListItemProps, Menu, type MenuDividerProps, type MenuHeaderProps, type MenuItemProps, type MenuListProps, type MenuPanelPadding, type MenuProps, type MenuSectionProps, type MenuSubmenuProps, Modal, type ModalProps, NumberField, type NumberFieldProps, Pagination, type PaginationProps, PasswordField, type PasswordFieldProps, Pill, type PillProps, Popover, type PopoverProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, RadioTile, type RadioTileProps, Ribbon, type RibbonProps, type RoutedLinkProps, RouterProvider, SKELETON_SIZE, SKELETON_SIZE_TOKENS, Skeleton, type SkeletonElementProps, SkeletonGroup, type SkeletonGroupButtonProps, type SkeletonGroupInputProps, type SkeletonGroupNodeProps, type SkeletonParagraphProps, type SkeletonProps, type SkeletonSize, type SkeletonTitleProps, Spinner, type SpinnerProps, type StylingOverrideProps, Switch, type SwitchProps, TabNav, type TabNavItemType, type TabNavItemVariant, type TabNavPlacement, type TabNavProps, type TabNavSubItemType, Tag, type TagColor, type TagProps, Text, TextArea, type TextAreaAutoSize, type TextAreaProps, TextField, type TextFieldProps, type TextProps, Toast, type ToastOptions, type ToastPosition, type ToastType, Tooltip, type TooltipProps, TopNav, type TopNavCenterProps, type TopNavEndProps, type TopNavProps, type TopNavStartProps, Tree, type TreeItemType, type TreeProps, VerticalNavigation, type VerticalNavigationCollapseProps, type VerticalNavigationFooterProps, type VerticalNavigationItemListProps, type VerticalNavigationItemProps, type VerticalNavigationProps, VisuallyHidden, type VisuallyHiddenProps, submenuPanelClassName, tagColors };
+export { Alert, type AlertProps, Anchor, type AnchorProps, AutocompleteField, type AutocompleteFieldProps, Badge, BadgeLayout, type BadgeProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Card, Checkbox, type CheckboxProps, Collapse, type CollapseProps, CustomTooltipTrigger, type CustomTooltipTriggerProps, DatePickerField, type DatePickerFieldProps, DateRangePickerField, type DateRangePickerFieldPlaceholder, type DateRangePickerFieldProps, Divider, type DividerProps, type DividerType, Drawer, type DrawerPlacement, type DrawerProps, EmptyState, type EmptyStateProps, IconButton, type IconButtonProps, InputRow, type InputRowAddonProps, type InputRowProps, Label, type LabelProps, Link, type LinkProps, ListItem, type ListItemProps, Menu, type MenuDividerProps, type MenuHeaderProps, type MenuItemProps, type MenuListProps, type MenuPanelPadding, type MenuProps, type MenuSectionProps, type MenuSubmenuProps, Modal, type ModalProps, NumberField, type NumberFieldProps, Pagination, type PaginationProps, PasswordField, type PasswordFieldProps, Pill, type PillProps, Popover, type PopoverProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, RadioTile, type RadioTileProps, Ribbon, type RibbonProps, type RoutedLinkProps, RouterProvider, SKELETON_SIZE, SKELETON_SIZE_TOKENS, SelectField, type SelectFieldHeaderProps, type SelectFieldItemProps, type SelectFieldProps, type SelectFieldSectionProps, Skeleton, type SkeletonElementProps, SkeletonGroup, type SkeletonGroupButtonProps, type SkeletonGroupInputProps, type SkeletonGroupNodeProps, type SkeletonParagraphProps, type SkeletonProps, type SkeletonSize, type SkeletonTitleProps, Spinner, type SpinnerProps, type StylingOverrideProps, Switch, type SwitchProps, TabNav, type TabNavItemType, type TabNavItemVariant, type TabNavPlacement, type TabNavProps, type TabNavSubItemType, Tag, type TagColor, type TagProps, Text, TextArea, type TextAreaAutoSize, type TextAreaProps, TextField, type TextFieldProps, type TextProps, Toast, type ToastOptions, type ToastPosition, type ToastType, Tooltip, type TooltipProps, TopNav, type TopNavCenterProps, type TopNavEndProps, type TopNavProps, type TopNavStartProps, Tree, type TreeItemType, type TreeProps, VerticalNavigation, type VerticalNavigationCollapseProps, type VerticalNavigationFooterProps, type VerticalNavigationItemListProps, type VerticalNavigationItemProps, type VerticalNavigationProps, VisuallyHidden, type VisuallyHiddenProps, submenuPanelClassName, tagColors };