@lumx/react 4.20.0-next.4 → 4.20.0

package/index.d.ts

@@ -1,7 +1,7 @@
 import { HorizontalAlignment as HorizontalAlignment$1, Orientation as Orientation$1, Alignment as Alignment$1, Size as Size$1, AspectRatio as AspectRatio$1, ColorPalette as ColorPalette$1, Kind as Kind$1, Emphasis as Emphasis$1, Theme as Theme$1 } from '@lumx/core/js/constants';
 export * from '@lumx/core/js/constants';
 import * as _lumx_core_js_types from '@lumx/core/js/types';
-import { ValueOf as ValueOf$1, GenericProps as GenericProps$1, HasTheme as HasTheme$1, PropsToOverride, HasAriaDisabled as HasAriaDisabled$1, HasRequiredLinkHref as HasRequiredLinkHref$1, HasClassName as HasClassName$1, HasCloseMode as HasCloseMode$1, JSXElement as JSXElement$1, CommonRef as CommonRef$1, Falsy, HeadingElement as HeadingElement$1, HasAriaLabelOrLabelledBy as HasAriaLabelOrLabelledBy$1, NamedProps } from '@lumx/core/js/types';
+import { ValueOf as ValueOf$1, GenericProps as GenericProps$1, HasTheme as HasTheme$1, PropsToOverride, HasAriaDisabled as HasAriaDisabled$1, HasRequiredLinkHref as HasRequiredLinkHref$1, HasClassName as HasClassName$1, HasCloseMode as HasCloseMode$1, JSXElement as JSXElement$1, CommonRef as CommonRef$1, Falsy, HeadingElement as HeadingElement$1, HasAriaLabelOrLabelledBy, NamedProps } from '@lumx/core/js/types';
 export * from '@lumx/core/js/types';
 import * as React$1 from 'react';
 import React__default, { Ref, ReactElement, ReactNode, SyntheticEvent, MouseEventHandler, KeyboardEventHandler, RefObject, SetStateAction, Key, CSSProperties, ElementType as ElementType$1, HTMLInputTypeAttribute, ComponentProps, ImgHTMLAttributes } from 'react';
@@ -226,24 +226,6 @@ type ColorVariant = ValueOf$1<typeof ColorVariant>;
 /** ColorPalette with all possible color variant combination */
 type ColorWithVariants = ColorPalette | Exclude<`${ColorPalette}-${ColorVariant}`, `light-D${number}` | `dark-D${number}`>;
 
-/**
- * Require either `aria-label` or `arial-labelledby` prop.
- * If none are set, the order will prioritize `aria-labelledby` over `aria-label` as it
- * needs a visible element.
- */
-type HasAriaLabelOrLabelledBy<T = string | undefined> = T extends string ? {
-    /**
-     * The id of the element to use as title of the dialog. Can be within or out of the dialog.
-     * Although it is not recommended, aria-label can be used instead if no visible element is available.
-     */
-    'aria-labelledby': T;
-    /** The label of the dialog. */
-    'aria-label'?: undefined;
-} : {
-    'aria-label': string;
-    'aria-labelledby'?: undefined;
-};
-
 interface HasClassName {
     /**
      * Class name forwarded to the root element of the component.
@@ -1231,6 +1213,10 @@ declare const ListDivider: Comp<ListDividerProps, HTMLLIElement>;
  * Defines the props of the component.
  */
 interface TextProps$1 extends HasClassName {
+    /**
+     * HTML id.
+     */
+    id?: string;
     /**
      * Color variant.
      */
@@ -2180,7 +2166,16 @@ declare namespace ComboboxProvider {
 
 /**
  * Hook to subscribe to a combobox event via the handle's subscriber system.
- * Re-subscribes when the handle changes (e.g. trigger mount/unmount).
+ *
+ * Uses `useSyncExternalStore` (shim, for React 17 support) reading the handle's synchronous
+ * `getSnapshot` — the correct pattern for an external (non-React) store. It reads the current
+ * value during commit, so a consumer doesn't miss changes that happened between its render and its
+ * subscription (e.g. options registered by child effects before this consumer subscribed, since
+ * `optionsChange` is not replayed on subscribe), and it is tearing-safe under concurrent rendering.
+ *
+ * The handle dispatches synchronously, so the store update fires within the triggering render/event
+ * (inside React's `act` in tests) rather than a deferred microtask. Re-subscribes when the handle
+ * changes (e.g. trigger mount/unmount).
  */
 declare function useComboboxEvent<K extends keyof ComboboxEventMap>(event: K, initialValue: ComboboxEventMap[K]): ComboboxEventMap[K];
 
@@ -2448,14 +2443,64 @@ interface DialogProps extends GenericProps$1, HasCloseMode$1, BaseDialogProps {
     /** Children */
     children?: React__default.ReactNode;
 }
+declare const Dialog: Comp<DialogProps, HTMLDivElement>;
+
 /**
- * Dialog component.
+ * Defines the props of the component.
+ */
+interface HeadingProps$1 extends Partial<TextProps$1> {
+    /**
+     * Display a specific heading level instead of the one provided by parent context provider.
+     */
+    as?: HeadingElement;
+}
+
+interface HeadingProps extends GenericProps$1, HeadingProps$1 {
+}
+/**
+ * Renders a heading component.
+ * Extends the `Text` Component with the heading level automatically computed based on
+ * the current level provided by the context.
+ */
+declare const Heading: Comp<HeadingProps, HTMLElement>;
+
+interface HeadingLevelProviderProps {
+    /** The heading level to start at. If left undefined, the parent context will be used, if any. */
+    level?: number;
+    /** The children to display */
+    children: ReactNode;
+}
+/**
+ * Provide a new heading level context.
+ */
+declare const HeadingLevelProvider: React.FC<HeadingLevelProviderProps>;
+
+declare const useHeadingLevel: () => {
+    level: number;
+    headingElement: _lumx_core_js_types.HeadingElement;
+};
+
+type DialogHeadingProps = HeadingProps;
+/**
+ * Names the enclosing dialog-like container (`Dialog`, `Lightbox`, `PopoverDialog`, ...).
  *
- * @param  props Component props.
- * @param  ref   Component ref.
- * @return React element.
+ * Thin wrapper over `Heading` that generates its own id (or uses the consumer-supplied `id`),
+ * and registers it with the nearest ids registry on mount so the container can link itself to
+ * this heading via `aria-labelledby`. Deregisters on unmount.
+ *
+ * Defaults its typography to `Typography.title` (overridable via the `typography` prop).
+ *
+ * If two `DialogHeading`s are rendered within the same container, the last one registered wins.
+ *
+ * @example
+ * <Dialog isOpen={isOpen}>
+ *     <header>
+ *         <Toolbar label={<DialogHeading>My dialog</DialogHeading>} />
+ *     </header>
+ *     ...
+ * </Dialog>
  */
-declare const Dialog: Comp<DialogProps, HTMLDivElement>;
+declare const DialogHeading: Comp<HeadingProps, HTMLElement>;
 
 /**
  * Defines the props of the component.
@@ -2845,41 +2890,6 @@ interface GenericBlock extends BaseGenericBlock {
 }
 declare const GenericBlock: GenericBlock;
 
-/**
- * Defines the props of the component.
- */
-interface HeadingProps$1 extends Partial<TextProps$1> {
-    /**
-     * Display a specific heading level instead of the one provided by parent context provider.
-     */
-    as?: HeadingElement;
-}
-
-interface HeadingProps extends GenericProps$1, HeadingProps$1 {
-}
-/**
- * Renders a heading component.
- * Extends the `Text` Component with the heading level automatically computed based on
- * the current level provided by the context.
- */
-declare const Heading: Comp<HeadingProps, HTMLElement>;
-
-interface HeadingLevelProviderProps {
-    /** The heading level to start at. If left undefined, the parent context will be used, if any. */
-    level?: number;
-    /** The children to display */
-    children: ReactNode;
-}
-/**
- * Provide a new heading level context.
- */
-declare const HeadingLevelProvider: React.FC<HeadingLevelProviderProps>;
-
-declare const useHeadingLevel: () => {
-    level: number;
-    headingElement: _lumx_core_js_types.HeadingElement;
-};
-
 type GridGutterSize = Extract<Size$1, 'regular' | 'big' | 'huge'>;
 /**
  * Defines the props of the component.
@@ -3391,6 +3401,8 @@ interface BaseLightboxProps extends HasClassName, HasTheme, Pick<AriaAttributes,
     isOpen?: boolean;
     /** Whether to keep the dialog open on clickaway or escape press. */
     preventAutoClose?: boolean;
+    /** Whether to keep the dialog open on clickaway (overridden by `preventAutoClose`). */
+    preventCloseOnClick?: boolean;
     /** Z-axis position. */
     zIndex?: number;
 }
@@ -3410,6 +3422,7 @@ interface LightboxProps extends GenericProps$1, ReactToJSX<BaseLightboxProps> {
     /** Children */
     children?: React.ReactNode;
 }
+
 /**
  * Lightbox component.
  *
@@ -3742,7 +3755,7 @@ type NavigationProps = React.ComponentProps<'nav'> & HasClassName$1 & HasTheme$1
     /** Content of the navigation. These components should be of type NavigationItem to be rendered */
     children?: React.ReactNode;
     orientation?: Orientation$1;
-} & HasAriaLabelOrLabelledBy$1;
+} & HasAriaLabelOrLabelledBy;
 type SubComponents = {
     Section: typeof NavigationSection;
     Item: typeof NavigationItem;
@@ -3781,18 +3794,24 @@ declare const Notification: Comp<NotificationProps, HTMLDivElement>;
 
 /**
  * PopoverDialog props.
- * The PopoverDialog has the same props as the Popover but requires an accessible label.
+ * The PopoverDialog has the same props as the Popover, plus optional accessible-name props.
+ * An accessible name can be provided via `label`, `aria-label`, `aria-labelledby`, or by
+ * rendering a `DialogHeading` inside the dialog (which names it via the internal label
+ * registry) - at least one of these should be used.
  */
-type PopoverDialogProps$1 = PopoverProps$1 & HasAriaLabelOrLabelledBy & {
+type PopoverDialogProps$1 = PopoverProps$1 & Pick<AriaAttributes, 'aria-label' | 'aria-labelledby'> & {
     /** Accessible label for the dialog (alternative to aria-label prop). */
     label?: string;
 };
 
 /**
  * PopoverDialog props.
- * The PopoverDialog has the same props as the Popover but requires an accessible label.
+ * The PopoverDialog has the same props as the Popover, plus optional accessible-name props
+ * (`label`/`aria-label`/`aria-labelledby`). An accessible name can also be provided by rendering
+ * a `DialogHeading` inside the dialog - at least one of these should be used.
  */
 type PopoverDialogProps = PopoverProps & Omit<PopoverDialogProps$1, keyof PopoverProps$1>;
+
 /**
  * PopoverDialog component.
  * Defines a popover that acts like a dialog:
@@ -5856,5 +5875,5 @@ declare const ThemeProvider: React__default.FC<{
 /** Get the theme in the current context. */
 declare function useTheme(): ThemeContextValue;
 
-export { AlertDialog, Autocomplete, AutocompleteMultiple, Avatar, Badge, BadgeWrapper, Button, ButtonEmphasis, ButtonGroup, CLASSNAME$2 as CLASSNAME, COMPONENT_NAME$2 as COMPONENT_NAME, Checkbox, Chip, ChipGroup, Combobox, CommentBlock, CommentBlockVariant, DEFAULT_PROPS, DatePicker, DatePickerControlled, DatePickerField, Dialog, Divider, DragHandle, Dropdown, ExpansionPanel, Flag, FlexBox, GenericBlock, GenericBlockGapSize, Grid, GridColumn, GridItem, Heading, HeadingLevelProvider, Icon, IconButton, ImageBlock, ImageBlockCaptionPosition, ImageLightbox, InlineList, InputHelper, InputLabel, Lightbox, Link, LinkPreview, List, ListDivider, ListItem, ListSection, ListSubheader, MenuButton, ListDivider as MenuDivider, MenuItem, Message, Mosaic, Navigation, Notification, Placement, Popover, PopoverDialog, PostBlock, Progress, ProgressCircular, ProgressLinear, ProgressTracker, ProgressTrackerProvider, ProgressTrackerStep, ProgressTrackerStepPanel, ProgressVariant, RadioButton, RadioGroup, RawInputText, RawInputTextarea, Select, SelectButton, SelectMultiple, SelectMultipleField, SelectTextField, SelectVariant, SelectionChipGroup, SideNavigation, SideNavigationItem, SkeletonCircle, SkeletonRectangle, SkeletonRectangleVariant, SkeletonTypography, Slider, Slides, Slideshow, SlideshowControls, SlideshowItem, Switch, CLASSNAME as TIME_PICKER_FIELD_CLASSNAME, COMPONENT_NAME as TIME_PICKER_FIELD_COMPONENT_NAME, Tab, TabList, TabListLayout, TabPanel, TabProvider, Table, TableBody, TableCell, TableCellVariant, TableCellVariant as TableCellVariantType, TableHeader, TableRow, Text, TextField, ThOrder, ThOrder as ThOrderType, ThemeProvider, Thumbnail, ThumbnailAspectRatio, ThumbnailObjectFit, ThumbnailVariant, TimePickerField, Toolbar, Tooltip, Uploader, UploaderVariant, UserBlock, clamp, useFocusPointStyle, useHeadingLevel, useTheme };
-export type { AlertDialogProps, AutocompleteMultipleProps, AutocompleteProps, AvatarProps, AvatarSize, BadgeProps, BadgeWrapperProps, BaseButtonProps, ButtonGroupProps, ButtonProps, ButtonSize, CheckboxProps, ChipGroupProps, ChipProps, ComboboxButtonProps, ComboboxInputProps, ComboboxListProps, ComboboxOptionActionProps, ComboboxOptionMoreInfoProps, ComboboxOptionProps, ComboboxOptionSkeletonProps, ComboboxPopoverComponentProps, ComboboxPopoverProps, ComboboxProviderProps, ComboboxSectionProps, ComboboxStateProps, CommentBlockProps, DatePickerControlledProps, DatePickerFieldProps, DatePickerProps, DialogProps, DialogSizes, DividerProps, DragHandleProps, DropdownProps, Elevation, ExpansionPanelProps, FlagProps, FlexBoxProps, FlexHorizontalAlignment, FlexVerticalAlignment, FocusPoint, GapSize, GenericBlockProps, GenericBlockSectionProps, GridColumnGapSize, GridColumnProps, GridItemProps, GridProps, HeadingLevelProviderProps, HeadingProps, IconButtonProps, IconProps, IconSizes, ImageBlockProps, ImageBlockSize, ImageLightboxProps, InlineListProps, InputHelperProps, InputLabelProps, LightboxProps, LinkPreviewProps, LinkProps, ListDividerProps, ListItemProps, ListItemSize, ListProps, ListSectionProps, ListSubheaderProps, MarginAutoAlignment, MenuButtonProps, ListDividerProps as MenuDividerProps, MenuItemActionProps, MenuItemProps, MessageProps, MosaicProps, MultipleSelectButtonProps, MultipleSelectTextFieldProps, NavigationProps, NotificationProps, Offset, PopoverDialogProps, PopoverHeight, PopoverProps, PopoverWidth, PostBlockProps, ProgressCircularProps, ProgressCircularSize, ProgressLinearProps, ProgressProps, ProgressTrackerProps, ProgressTrackerProviderProps, ProgressTrackerStepPanelProps, ProgressTrackerStepProps, RadioButtonProps, RadioGroupProps, RawInputTextProps, RawInputTextareaProps, SelectButtonProps, SelectListStatus as SelectButtonStatus, SelectButtonTranslations, SelectListStatus, SelectMultipleProps, SelectProps, SelectTextFieldProps, SelectListStatus as SelectTextFieldStatus, SelectTextFieldTranslations, SelectionChipGroupProps, SideNavigationItemProps, SideNavigationProps, SingleSelectButtonProps, SingleSelectTextFieldProps, SkeletonCircleProps, SkeletonRectangleProps, SkeletonTypographyProps, SliderProps, SlidesProps, SlideshowControlsProps, SlideshowItemProps, SlideshowProps, SwitchProps, TabListProps, TabPanelProps, TabProps, TabProviderProps, TableBodyProps, TableCellProps, TableHeaderProps, TableProps, TableRowProps, TextFieldProps, TextProps, ThumbnailProps, ThumbnailSize, TimePickerFieldProps, ToolbarProps, TooltipPlacement, TooltipProps, UploaderProps, UploaderSize, UserBlockProps, UserBlockSize };
+export { AlertDialog, Autocomplete, AutocompleteMultiple, Avatar, Badge, BadgeWrapper, Button, ButtonEmphasis, ButtonGroup, CLASSNAME$2 as CLASSNAME, COMPONENT_NAME$2 as COMPONENT_NAME, Checkbox, Chip, ChipGroup, Combobox, CommentBlock, CommentBlockVariant, DEFAULT_PROPS, DatePicker, DatePickerControlled, DatePickerField, Dialog, DialogHeading, Divider, DragHandle, Dropdown, ExpansionPanel, Flag, FlexBox, GenericBlock, GenericBlockGapSize, Grid, GridColumn, GridItem, Heading, HeadingLevelProvider, Icon, IconButton, ImageBlock, ImageBlockCaptionPosition, ImageLightbox, InlineList, InputHelper, InputLabel, Lightbox, Link, LinkPreview, List, ListDivider, ListItem, ListSection, ListSubheader, MenuButton, ListDivider as MenuDivider, MenuItem, Message, Mosaic, Navigation, Notification, Placement, Popover, PopoverDialog, PostBlock, Progress, ProgressCircular, ProgressLinear, ProgressTracker, ProgressTrackerProvider, ProgressTrackerStep, ProgressTrackerStepPanel, ProgressVariant, RadioButton, RadioGroup, RawInputText, RawInputTextarea, Select, SelectButton, SelectMultiple, SelectMultipleField, SelectTextField, SelectVariant, SelectionChipGroup, SideNavigation, SideNavigationItem, SkeletonCircle, SkeletonRectangle, SkeletonRectangleVariant, SkeletonTypography, Slider, Slides, Slideshow, SlideshowControls, SlideshowItem, Switch, CLASSNAME as TIME_PICKER_FIELD_CLASSNAME, COMPONENT_NAME as TIME_PICKER_FIELD_COMPONENT_NAME, Tab, TabList, TabListLayout, TabPanel, TabProvider, Table, TableBody, TableCell, TableCellVariant, TableCellVariant as TableCellVariantType, TableHeader, TableRow, Text, TextField, ThOrder, ThOrder as ThOrderType, ThemeProvider, Thumbnail, ThumbnailAspectRatio, ThumbnailObjectFit, ThumbnailVariant, TimePickerField, Toolbar, Tooltip, Uploader, UploaderVariant, UserBlock, clamp, useFocusPointStyle, useHeadingLevel, useTheme };
+export type { AlertDialogProps, AutocompleteMultipleProps, AutocompleteProps, AvatarProps, AvatarSize, BadgeProps, BadgeWrapperProps, BaseButtonProps, ButtonGroupProps, ButtonProps, ButtonSize, CheckboxProps, ChipGroupProps, ChipProps, ComboboxButtonProps, ComboboxInputProps, ComboboxListProps, ComboboxOptionActionProps, ComboboxOptionMoreInfoProps, ComboboxOptionProps, ComboboxOptionSkeletonProps, ComboboxPopoverComponentProps, ComboboxPopoverProps, ComboboxProviderProps, ComboboxSectionProps, ComboboxStateProps, CommentBlockProps, DatePickerControlledProps, DatePickerFieldProps, DatePickerProps, DialogHeadingProps, DialogProps, DialogSizes, DividerProps, DragHandleProps, DropdownProps, Elevation, ExpansionPanelProps, FlagProps, FlexBoxProps, FlexHorizontalAlignment, FlexVerticalAlignment, FocusPoint, GapSize, GenericBlockProps, GenericBlockSectionProps, GridColumnGapSize, GridColumnProps, GridItemProps, GridProps, HeadingLevelProviderProps, HeadingProps, IconButtonProps, IconProps, IconSizes, ImageBlockProps, ImageBlockSize, ImageLightboxProps, InlineListProps, InputHelperProps, InputLabelProps, LightboxProps, LinkPreviewProps, LinkProps, ListDividerProps, ListItemProps, ListItemSize, ListProps, ListSectionProps, ListSubheaderProps, MarginAutoAlignment, MenuButtonProps, ListDividerProps as MenuDividerProps, MenuItemActionProps, MenuItemProps, MessageProps, MosaicProps, MultipleSelectButtonProps, MultipleSelectTextFieldProps, NavigationProps, NotificationProps, Offset, PopoverDialogProps, PopoverHeight, PopoverProps, PopoverWidth, PostBlockProps, ProgressCircularProps, ProgressCircularSize, ProgressLinearProps, ProgressProps, ProgressTrackerProps, ProgressTrackerProviderProps, ProgressTrackerStepPanelProps, ProgressTrackerStepProps, RadioButtonProps, RadioGroupProps, RawInputTextProps, RawInputTextareaProps, SelectButtonProps, SelectListStatus as SelectButtonStatus, SelectButtonTranslations, SelectListStatus, SelectMultipleProps, SelectProps, SelectTextFieldProps, SelectListStatus as SelectTextFieldStatus, SelectTextFieldTranslations, SelectionChipGroupProps, SideNavigationItemProps, SideNavigationProps, SingleSelectButtonProps, SingleSelectTextFieldProps, SkeletonCircleProps, SkeletonRectangleProps, SkeletonTypographyProps, SliderProps, SlidesProps, SlideshowControlsProps, SlideshowItemProps, SlideshowProps, SwitchProps, TabListProps, TabPanelProps, TabProps, TabProviderProps, TableBodyProps, TableCellProps, TableHeaderProps, TableProps, TableRowProps, TextFieldProps, TextProps, ThumbnailProps, ThumbnailSize, TimePickerFieldProps, ToolbarProps, TooltipPlacement, TooltipProps, UploaderProps, UploaderSize, UserBlockProps, UserBlockSize };