@lumx/core 4.14.0-next.0 → 4.14.0-next.1

package/js/components/Popover/index.d.ts

@@ -0,0 +1,119 @@
+import type { JSXElement, HasTheme, HasClassName, HasCloseMode, CommonRef, LumxClassName } from '../../types';
+import { Elevation, FitAnchorWidth, Offset, Placement } from './constants';
+/**
+ * Shared popover props used by both React and Vue wrappers.
+ *
+ * Framework-specific props (ref types, children, callbacks) are added by each wrapper.
+ * The `anchorRef`, `boundaryRef`, `focusElement`, `parentElement`, `focusTrapZoneElement`
+ * are typed as `any` here because React uses `RefObject<HTMLElement>` while Vue uses
+ * raw `HTMLElement` — each framework narrows the type in its own props definition.
+ */
+export interface PopoverProps extends HasClassName, HasTheme, HasCloseMode {
+    /** Reference to the DOM element used to set the position of the popover. */
+    anchorRef?: CommonRef;
+    /** Customize the root element tag. */
+    as?: string;
+    /** Element which will act as boundary when opening the popover. */
+    boundaryRef?: CommonRef;
+    /** Whether a click anywhere out of the popover would close it. */
+    closeOnClickAway?: boolean;
+    /** Whether an escape key press would close the popover. */
+    closeOnEscape?: boolean;
+    /** Shadow elevation. */
+    elevation?: Elevation;
+    /**
+     * Manage popover width:
+     *   - `maxWidth`: popover not bigger than anchor
+     *   - `minWidth` or `true`: popover not smaller than anchor
+     *   - `width`: popover equal to the anchor.
+     */
+    fitToAnchorWidth?: FitAnchorWidth | boolean;
+    /** Shrink popover if even after flipping there is not enough space. */
+    fitWithinViewportHeight?: boolean;
+    /** Element to focus when opening the popover. */
+    focusElement?: CommonRef;
+    /** Whether the focus should go back on the anchor when popover closes and focus is within. */
+    focusAnchorOnClose?: boolean;
+    /** Whether we put an arrow or not. */
+    hasArrow?: boolean;
+    /** Whether the popover is open or not. */
+    isOpen: boolean;
+    /** Offset placement relative to anchor. */
+    offset?: Offset;
+    /** Reference to the parent element that triggered the popover. */
+    parentElement?: CommonRef;
+    /** Placement relative to anchor. */
+    placement?: Placement;
+    /** Whether the popover should be rendered into a portal. */
+    usePortal?: boolean;
+    /** The element in which the focus trap should be set. Default to popover. */
+    focusTrapZoneElement?: CommonRef;
+    /** Z-axis position. */
+    zIndex?: number;
+    /** Whether the popover should trap the focus within itself. */
+    withFocusTrap?: boolean;
+    /** On close callback (on click away or Escape pressed). Framework wrappers provide their own type. */
+    handleClose?(): void;
+}
+/**
+ * Internal UI rendering props for the core Popover component.
+ * These are passed by the framework wrappers after processing the behavioral PopoverProps.
+ */
+export interface PopoverUIProps extends HasClassName, HasTheme, HasCloseMode {
+    /** Customize the root element tag. */
+    as?: string;
+    /** Content. */
+    children: JSXElement;
+    /** Shadow elevation. */
+    elevation?: Elevation;
+    /** Whether we put an arrow or not. */
+    hasArrow?: boolean;
+    /** Whether the popover is open or not. */
+    isOpen: boolean;
+    /** Resolved position (from floating UI). */
+    position?: Placement;
+    /** Computed popover styles (from floating UI). */
+    popoverStyle?: any;
+    /** Computed arrow styles (from floating UI). */
+    arrowStyle?: any;
+    /** Ref for the popover root element. */
+    ref?: CommonRef;
+    /** Ref setter for the arrow element. */
+    arrowRef?: CommonRef;
+    /** Whether to render into a portal. */
+    usePortal?: boolean;
+    /** Click-away callback (when closeOnClickAway is true). */
+    clickAwayCallback?: any;
+    /** Refs for click-away detection. */
+    clickAwayRefs?: any;
+    /** Unmount sentinel (React-specific, optional). */
+    unmountSentinel?: JSXElement;
+}
+/** Injected framework-specific components. */
+export interface PopoverComponents {
+    /** Portal component for rendering outside the parent hierarchy. */
+    Portal: any;
+    /** ClickAwayProvider component for click-away detection. */
+    ClickAwayProvider: any;
+    /** ThemeProvider component for theme context isolation. */
+    ThemeProvider: any;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "Popover";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Component default props (used by framework wrappers).
+ */
+export declare const DEFAULT_PROPS: Partial<PopoverProps>;
+/**
+ * Popover core UI component.
+ *
+ * Framework-specific components (Portal, ClickAwayProvider, ThemeProvider) are passed
+ * as a second argument by the React/Vue wrappers.
+ */
+export declare const Popover: (props: PopoverUIProps, { Portal, ClickAwayProvider, ThemeProvider }: PopoverComponents) => import("react").JSX.Element | null;

package/js/components/PopoverDialog/Stories.d.ts

@@ -0,0 +1,44 @@
+import type { SetupStoriesOptions } from '@lumx/core/stories/types';
+/**
+ * Core stories for the PopoverDialog component.
+ *
+ * Stories are interactive (open/close state, focus trap, etc.) and require
+ * framework-specific rendering for anchor refs and state management.
+ * A `render` function is provided per framework to handle this.
+ *
+ * The render function receives all args, which can include:
+ * - `label`: Accessible label for the dialog (aria-label)
+ * - Any other PopoverDialog props
+ */
+export declare function setup({ component: PopoverDialog, render }: SetupStoriesOptions): {
+    meta: {
+        component: any;
+        render: any;
+        parameters: {
+            chromatic: {
+                disableSnapshot: boolean;
+            };
+        };
+        tags: string[];
+        argTypes: {
+            closeMode: {
+                control: {
+                    type: "select" | "inline-radio";
+                };
+                options: string[];
+                mapping: Record<string, string> | undefined;
+            };
+            anchorRef: {
+                control: boolean;
+            };
+            children: {
+                control: boolean;
+            };
+        };
+    };
+    WithIconButtonTrigger: {
+        args: {
+            label: string;
+        };
+    };
+};

package/js/components/PopoverDialog/index.d.ts

@@ -0,0 +1,22 @@
+import type { HasAriaLabelOrLabelledBy, LumxClassName } from '../../types';
+import type { PopoverProps } from '../Popover';
+/**
+ * PopoverDialog props.
+ * The PopoverDialog has the same props as the Popover but requires an accessible label.
+ */
+export type PopoverDialogProps = PopoverProps & HasAriaLabelOrLabelledBy & {
+    /** Accessible label for the dialog (alternative to aria-label prop). */
+    label?: string;
+};
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "PopoverDialog";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Component default props.
+ */
+export declare const DEFAULT_PROPS: Partial<PopoverDialogProps>;

package/js/components/RadioButton/Stories.d.ts

@@ -0,0 +1,78 @@
+import type { SetupStoriesOptions } from '@lumx/core/stories/types';
+/**
+ * Setup RadioButton stories for a specific framework (React or Vue).
+ * This function creates all the stories with the appropriate decorators.
+ * Framework-specific render functions or args can be injected via `overrides`.
+ */
+export declare function setup({ component: RadioButton, decorators: { withCombinations, withValueOnChange }, }: SetupStoriesOptions<{
+    decorators: 'withCombinations' | 'withValueOnChange';
+}>): {
+    meta: {
+        component: any;
+        render: (args: any) => import("react").JSX.Element;
+        decorators: ((story: any, context: any) => any)[];
+        argTypes: {
+            onChange: {
+                action: boolean;
+            };
+            name: {
+                control: boolean;
+            };
+            value: {
+                control: boolean;
+            };
+        };
+        args: {
+            isChecked: boolean;
+            name: string;
+            value: string;
+            helper?: string | undefined;
+            id?: string | undefined;
+            label?: import("react").ReactNode;
+            inputProps?: Record<string, any> | undefined;
+            inputRef?: import("../../types").CommonRef;
+            inputId?: string | undefined;
+            handleChange?: ((value?: string, name?: string, event?: any) => void) | undefined;
+            ref?: import("../../types").CommonRef;
+            theme?: import("../../constants").Theme | undefined;
+            className?: string | undefined;
+            'aria-disabled'?: import("../../types/Booleanish").Booleanish | undefined;
+            isDisabled?: boolean | undefined;
+            disabled?: boolean | undefined;
+            checked?: boolean | undefined;
+        };
+    };
+    /** Default radio button */
+    Default: {};
+    /** With label and helper */
+    LabelAndHelper: {
+        argTypes: {
+            label: {
+                control: string;
+            };
+            helper: {
+                control: string;
+            };
+        };
+        args: {
+            label: string;
+            helper: string;
+        };
+    };
+    /** Disabled */
+    Disabled: {
+        argTypes: {
+            isDisabled: {
+                control: boolean;
+            };
+            'aria-disabled': {
+                control: boolean;
+            };
+        };
+        args: {
+            label: string;
+            helper: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+    };
+};

package/js/components/RadioGroup/index.d.ts

@@ -0,0 +1,34 @@
+import type { JSXElement, LumxClassName, HasClassName, CommonRef } from '../../types';
+/**
+ * Defines the props of the component.
+ */
+export interface RadioGroupProps extends HasClassName {
+    /** RadioButton elements */
+    children?: JSXElement;
+    /** reference to the root element */
+    ref?: CommonRef;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "RadioGroup";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Component default props.
+ */
+export declare const DEFAULT_PROPS: Partial<RadioGroupProps>;
+/**
+ * RadioGroup component.
+ *
+ * @param  props Component props.
+ * @return JSX element.
+ */
+export declare const RadioGroup: {
+    (props: RadioGroupProps): import("react").JSX.Element;
+    displayName: string;
+    className: "lumx-radio-group";
+    defaultProps: Partial<RadioGroupProps>;
+};

package/js/components/SelectButton/Stories.d.ts

@@ -0,0 +1,135 @@
+import type { SetupStoriesOptions } from '@lumx/core/stories/types';
+export declare const FRUITS: {
+    category: string;
+    categoryIcon: string;
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+}[];
+export type Fruit = (typeof FRUITS)[number];
+/**
+ * Setup SelectButton stories for a specific framework (React or Vue).
+ */
+export declare function setup({ components: { SelectButton }, decorators: { withValueOnChange, withCombinations }, }: SetupStoriesOptions<{
+    components: {
+        SelectButton: any;
+    };
+    decorators: 'withValueOnChange' | 'withCombinations';
+}>): {
+    meta: {
+        component: any;
+        play({ canvas }: any): Promise<void>;
+    };
+    Default: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    WithSelectedValue: {
+        args: {
+            value: {
+                category: string;
+                categoryIcon: string;
+                id: string;
+                name: string;
+                icon: string;
+                description: string;
+            };
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    WithSections: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    WithDescriptions: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    Disabled: {
+        args: {
+            value: {
+                category: string;
+                categoryIcon: string;
+                id: string;
+                name: string;
+                icon: string;
+                description: string;
+            };
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    Loading: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    LoadingMore: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    ErrorState: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    MultipleSelection: {
+        args: {
+            value: never[];
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    MultipleWithPreselected: {
+        args: {
+            value: {
+                category: string;
+                categoryIcon: string;
+                id: string;
+                name: string;
+                icon: string;
+                description: string;
+            }[];
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    WithNbOptionMessage: {
+        args: {
+            value: undefined;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onChange }: any) => import("react").JSX.Element;
+    };
+    LabelDisplayModes: {
+        play: () => void;
+        argTypes: {
+            labelDisplayMode: {
+                control: boolean;
+            };
+            value: {
+                control: boolean;
+            };
+        };
+        render: ({ value, labelDisplayMode }: any) => import("react").JSX.Element;
+        decorators: ((story: any, context: any) => any)[];
+    };
+};

package/js/components/SelectButton/TestStories.d.ts

@@ -0,0 +1,37 @@
+import type { SetupStoriesOptions } from '@lumx/core/stories/types';
+/**
+ * Setup SelectButton test stories
+ */
+export declare function setup({ components: { SelectButton }, renderWithState, }: SetupStoriesOptions<{
+    components: {
+        SelectButton: any;
+    };
+    decorators: 'withValueOnChange';
+}> & {
+    renderWithState: (template: (props: any) => any) => any;
+}): {
+    meta: {
+        component: any;
+        tags: string[];
+        parameters: {
+            chromatic: {
+                disable: boolean;
+            };
+        };
+    };
+    ClickOutsideCloses: {
+        render: (args: any) => import("react").JSX.Element;
+        args: {
+            value: undefined;
+            onChange: () => void;
+        };
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    SelectionUpdates: {
+        render: () => any;
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    WithInfiniteScroll: {
+        play({ canvasElement }: any): Promise<void>;
+    };
+};

package/js/components/SelectButton/Tests.d.ts

@@ -0,0 +1,34 @@
+export declare const TRANSLATIONS: {
+    loadingMessage: string;
+    emptyMessage: string;
+    errorMessage: string;
+    errorTryReloadMessage: string;
+    nbOptionMessage: (n: number) => string;
+};
+type RenderResult = {
+    unmount: () => void;
+    container: HTMLElement;
+};
+/**
+ * Options to set up the SelectButton test suite.
+ * Injected by the framework-specific test file (React or Vue).
+ */
+export interface SelectButtonTestSetup {
+    components: {
+        SelectButton: any;
+        Combobox: any;
+    };
+    /**
+     * Render a SelectButton template with controlled state management.
+     *
+     * @param template    JSX render function receiving `{ value, onChange, ... }`.
+     * @param initialArgs Initial props (value, spies, etc.).
+     */
+    renderWithState: (template: (props: any) => any, initialArgs?: Record<string, any>) => RenderResult;
+}
+export declare function createTemplates(SelectButton: any): {
+    defaultTemplate: (props: any) => import("react").JSX.Element;
+    multiTemplate: (props: any) => import("react").JSX.Element;
+};
+export default function selectButtonTests({ components, renderWithState }: SelectButtonTestSetup): void;
+export {};

package/js/components/SelectButton/index.d.ts

@@ -0,0 +1,85 @@
+import type { LumxClassName } from '../../types';
+import type { ComboboxButtonLabelDisplayMode } from '../Combobox/ComboboxButton';
+import { BaseSelectComponents, BaseSelectProps, SelectButtonTranslations, SelectTextFieldStatus } from '../../utils/select/types';
+/**
+ * Defines the props for the core SelectButton template.
+ */
+export interface SelectButtonProps<O> extends BaseSelectProps<O> {
+    /**
+     * Selected value (single mode) or selected values (multi mode).
+     * The wrapper layer chooses the shape; the core just renders names.
+     */
+    value?: O | O[];
+    /**
+     * When `true`, sets `aria-multiselectable="true"` on the listbox so
+     * the dropdown stays open after each selection (combobox setup detects this attribute).
+     */
+    isMultiselectable?: boolean;
+    /** Button label (used for ARIA and when no selection). */
+    label: string;
+    /** Controls how the label/value is displayed in the button. */
+    labelDisplayMode?: ComboboxButtonLabelDisplayMode;
+    /**
+     * Props forwarded to Combobox.Button (button appearance, emphasis, size, etc.).
+     * Pass `renderButton` here to provide a custom button renderer — see
+     * `ComboboxButtonProps.renderButton`. Framework wrappers are responsible for
+     * defaulting any visual affordance (e.g. the dropdown chevron `rightIcon`).
+     */
+    buttonProps?: Record<string, any>;
+    /** Props forwarded to Combobox.Popover. */
+    popoverProps?: Record<string, any>;
+    /** Props forwarded to Combobox.List (e.g. ref). */
+    listProps?: Record<string, any>;
+    /** Callback on option selected (receives option id string). */
+    handleSelect?: (selectedOption: {
+        value: string;
+    }) => void;
+    /**
+     * Status of the dropdown list.
+     * - `'idle'` — Default state, no loading indicators.
+     * - `'loading'` — Full loading: shows skeleton placeholders, hides real options.
+     * - `'loadingMore'` — Paginated loading: appends a skeleton after existing options.
+     * - `'error'` — Error state: shows an error message in the dropdown.
+     * @default 'idle'
+     */
+    listStatus?: SelectTextFieldStatus;
+    /** Optional translations for screen-reader announcements (loading/empty/error/option count). */
+    translations?: SelectButtonTranslations;
+    /** Callback fired when the dropdown open state changes. */
+    onOpen?: (isOpen: boolean) => void;
+    /**
+     * Callback fired to load more items (infinite scroll).
+     * When provided together with an injected `InfiniteScroll` component, an invisible
+     * sentinel element is rendered after the options to trigger loading via IntersectionObserver.
+     */
+    onLoadMore?: () => void;
+    /** IntersectionObserver options forwarded to the InfiniteScroll sentinel. */
+    infiniteScrollOptions?: IntersectionObserverInit;
+}
+/**
+ * Injected framework-specific components for SelectButton rendering.
+ */
+export type SelectButtonComponents = BaseSelectComponents;
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "SelectButton";
+/**
+ * Component default class name.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * SelectButton core template.
+ * Renders a Combobox with a button trigger and a dropdown list of options.
+ *
+ * Framework-specific components are passed as a second argument by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const SelectButton: {
+    <O>(props: SelectButtonProps<O>, { Combobox, InfiniteScroll }: SelectButtonComponents): import("react").JSX.Element;
+    displayName: string;
+    className: "lumx-select-button";
+};