@bloomreach/react-banana-ui 1.40.0 → 1.42.0

package/dist/src/components/inputs/index.d.ts

@@ -7,6 +7,7 @@ export * from './input-field';
 export * from './radio';
 export * from './radio-field';
 export * from './radio-group';
+export * from './segmented-control';
 export * from './select-field';
 export * from './select-option';
 export * from './slider';

package/dist/src/components/inputs/segmented-control/index.d.ts

@@ -0,0 +1,2 @@
+export { default as SegmentedControl } from './segmented-control';
+export type { SegmentedControlItem, SegmentedControlProps } from './segmented-control.types';

package/dist/src/components/inputs/segmented-control/segmented-control.d.ts

@@ -0,0 +1,26 @@
+import { SegmentedControlProps } from './segmented-control.types';
+/**
+ * A radio-group-based control that presents a set of mutually exclusive choices
+ * as a row of equal-width segments with an animated thumb indicator that slides
+ * to the selected item.
+ *
+ * Supports controlled and uncontrolled usage, keyboard navigation (arrow keys,
+ * Home/End, Space/Enter), full-width layout, two sizes (`md` and `sm`),
+ * read-only and disabled states, icon-only segments, and native form
+ * participation via hidden radio inputs.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   items={[
+ *     { value: 'day', label: 'Day' },
+ *     { value: 'week', label: 'Week' },
+ *     { value: 'month', label: 'Month' },
+ *   ]}
+ *   defaultValue="day"
+ *   onChange={(value) => console.log(value)}
+ * />
+ * ```
+ */
+declare const SegmentedControl: import('react').ForwardRefExoticComponent<SegmentedControlProps & import('react').RefAttributes<HTMLDivElement>>;
+export default SegmentedControl;

package/dist/src/components/inputs/segmented-control/segmented-control.qa.stories.d.ts

@@ -0,0 +1,18 @@
+import { Args, Meta } from '@storybook/react-vite';
+import { Story } from './segmented-control.stories';
+import { SegmentedControlProps } from './segmented-control.types';
+type StoryArgs = Args & SegmentedControlProps;
+declare const meta: Meta<StoryArgs>;
+export default meta;
+export declare const DefaultQA: Story;
+export declare const ControlledQA: Story;
+export declare const WithIconsQA: Story;
+export declare const IconOnlyQA: Story;
+export declare const SmallSizeQA: Story;
+export declare const FullWidthQA: Story;
+export declare const DisabledGroupQA: Story;
+export declare const DisabledItemsQA: Story;
+export declare const TwoItemsQA: Story;
+export declare const FiveItemsQA: Story;
+export declare const ReadOnlyQA: Story;
+export declare const CombinedStories: Story;

package/dist/src/components/inputs/segmented-control/segmented-control.stories.d.ts

@@ -0,0 +1,18 @@
+import { default as SegmentedControl } from './segmented-control';
+import { Meta, StoryObj } from '@storybook/react-vite';
+declare const meta: Meta<typeof SegmentedControl>;
+export default meta;
+export type Story = StoryObj<typeof SegmentedControl>;
+export declare const Default: Story;
+export declare const Controlled: Story;
+export declare const Uncontrolled: Story;
+export declare const WithIcons: Story;
+export declare const IconOnly: Story;
+export declare const SmallSize: Story;
+export declare const FullWidth: Story;
+export declare const DisabledGroup: Story;
+export declare const DisabledItems: Story;
+export declare const TwoItems: Story;
+export declare const FiveItems: Story;
+export declare const ReadOnly: Story;
+export declare const FormIntegration: Story;

package/dist/src/components/inputs/segmented-control/segmented-control.types.d.ts

@@ -0,0 +1,93 @@
+import { FocusEventHandler, HTMLAttributes, ReactNode } from 'react';
+export interface SegmentedControlItem {
+    /**
+     * Accessible name for icon-only segments. Required when `label` is omitted.
+     */
+    ariaLabel?: string;
+    /**
+     * Whether this individual segment is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Icon element displayed before the label (or alone for icon-only segments).
+     */
+    icon?: ReactNode;
+    /**
+     * Text label displayed in the segment.
+     */
+    label?: string;
+    /**
+     * Unique value identifying this segment.
+     */
+    value: string;
+}
+export interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color' | 'onBlur' | 'onChange' | 'onFocus' | 'role' | 'tabIndex'> {
+    /**
+     * Accessible label for the radio group.
+     */
+    'aria-label'?: string;
+    /**
+     * ID of an element that labels the radio group.
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Additional CSS class applied to the root element.
+     */
+    className?: string;
+    /**
+     * The initially selected value (uncontrolled mode).
+     */
+    defaultValue?: string;
+    /**
+     * Disables the entire control and all segments.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Associates the hidden radio inputs with a `<form>` by its `id`.
+     */
+    form?: string;
+    /**
+     * When true, the control stretches to fill its container and distributes
+     * segments equally.
+     * @default false
+     */
+    fullWidth?: boolean;
+    /**
+     * The segments to render. Each item must have a unique `value`.
+     */
+    items: SegmentedControlItem[];
+    /**
+     * Name attribute for the hidden radio inputs, enabling form participation.
+     * Auto-generated if omitted.
+     */
+    name?: string;
+    /**
+     * Callback fired when a segment loses focus.
+     * The event bubbles to the control root.
+     */
+    onBlur?: FocusEventHandler<HTMLDivElement>;
+    /**
+     * Callback fired when the selected value changes.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * Callback fired when a segment receives focus.
+     * The event bubbles to the control root.
+     */
+    onFocus?: FocusEventHandler<HTMLDivElement>;
+    /**
+     * When true, the control displays its value but does not allow interaction.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Size of the control.
+     * @default 'md'
+     */
+    size?: 'md' | 'sm';
+    /**
+     * The currently selected value (controlled mode).
+     */
+    value?: string;
+}

package/dist/src/components/inputs/segmented-control/use-segmented-control.d.ts

@@ -0,0 +1,69 @@
+import { FocusEvent, ForwardedRef, KeyboardEvent, RefCallback } from 'react';
+import { SegmentedControlItem } from './segmented-control.types';
+/**
+ * CSS transform and width values used to position the sliding thumb or focus
+ * indicator absolutely over a specific segment element.
+ */
+interface IndicatorStyle {
+    /** CSS `translateX` value derived from the segment's `offsetLeft`. */
+    transform: string;
+    /** Pixel width derived from the segment's `offsetWidth`. */
+    width: string;
+}
+/** Parameters accepted by the `useSegmentedControl` hook. */
+interface UseSegmentedControlParameters {
+    /** Initial selected value for uncontrolled usage. */
+    defaultValue?: string;
+    /** When `true`, all interaction is suppressed. */
+    disabled: boolean;
+    /** Ordered list of segment descriptors. */
+    items: SegmentedControlItem[];
+    /** Base name for the hidden radio inputs; auto-generated when omitted. */
+    name?: string;
+    /** Callback fired when the selected value changes. */
+    onChange?: (value: string) => void;
+    /** When `true`, the selected value is displayed but cannot be changed. */
+    readOnly: boolean;
+    /** Forwarded ref from the `SegmentedControl` component. */
+    ref: ForwardedRef<HTMLDivElement>;
+    /** Currently selected value for controlled usage. */
+    value?: string;
+}
+/** Values returned by `useSegmentedControl` for consumption by `SegmentedControl`. */
+interface UseSegmentedControlReturn {
+    /** Style for the focus-ring indicator, or `null` when no segment is focused. */
+    focusIndicatorStyle: IndicatorStyle | null;
+    /** Capture-phase blur handler that clears the focused index when focus leaves the control. */
+    handleBlur: (event: FocusEvent<HTMLDivElement>) => void;
+    /** Capture-phase focus handler that tracks which segment item currently has focus. */
+    handleFocus: (event: FocusEvent<HTMLDivElement>) => void;
+    /** Keyboard handler supporting arrow navigation, Home/End, and Space/Enter activation. */
+    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    /** Selects a segment by value, guarded by disabled and read-only checks. */
+    handleSelect: (value: string, isItemDisabled: boolean) => void;
+    /** When `true`, suppresses the thumb CSS transition to prevent an unwanted initial animation. */
+    isThumbTransitionDisabled: boolean;
+    /** Merged ref combining the forwarded ref and the internal root ref. */
+    mergedRef: null | RefCallback<HTMLDivElement>;
+    /** Resolved `name` attribute shared by all hidden radio inputs in the group. */
+    resolvedName: string | undefined;
+    /** The currently selected segment value. */
+    selectedValue: string | undefined;
+    /** Stable callback to register or clear a segment element ref by its array index. */
+    setItemRef: (index: number, element: HTMLDivElement | null) => void;
+    /** Index of the segment that should receive `tabIndex={0}` for roving-tabindex navigation. */
+    tabbableIndex: number;
+    /** Style for the selected-item thumb indicator, or `null` when nothing is selected. */
+    thumbStyle: IndicatorStyle | null;
+}
+/**
+ * Encapsulates all state and event-handling logic for the `SegmentedControl`
+ * component, including:
+ * - Controlled/uncontrolled value management via `useControlledValue`
+ * - Roving-tabindex keyboard navigation
+ * - Animated thumb and focus-ring indicator positioning via synchronous DOM
+ *   measurements in a layout effect
+ * - `ResizeObserver`-based indicator recalculation on container resize
+ */
+declare const useSegmentedControl: (parameters: UseSegmentedControlParameters) => UseSegmentedControlReturn;
+export default useSegmentedControl;

package/dist/src/components/popovers/modal/modal/modal-transition.d.ts

@@ -0,0 +1,33 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { AnimationState } from './modal-utils';
+import { ModalWidth } from './modal.types';
+/** Props accepted by {@link ModalTransition}. */
+export interface ModalTransitionProps extends HTMLAttributes<HTMLDivElement> {
+    /** Content to render inside the animated wrapper. */
+    children: ReactNode;
+    /** Whether the modal is in the open (entered) state. */
+    in: boolean;
+    /** Called once when the enter transition starts. */
+    onEnter?: () => void;
+    /** Called once when the exit transition has fully completed. */
+    onExited?: () => void;
+    /** Called each time the animation phase changes. */
+    onStateChange?: (state: AnimationState) => void;
+    /** Width variant forwarded as a BEM modifier class on the wrapper element. */
+    width: ModalWidth;
+}
+/**
+ * Internal wrapper that drives the CSS enter/exit animation for the modal.
+ *
+ * Applies `data-entering` / `data-entered` / `data-exiting` / `data-exited`
+ * attributes and matching BEM modifier classes so that SCSS can target each
+ * animation phase independently.
+ *
+ * The exit transition is also guarded by a fallback `setTimeout` so that
+ * `onExited` fires reliably even when the CSS `transitionend` event is
+ * suppressed — for example under `prefers-reduced-motion` or in jsdom tests.
+ *
+ * @internal
+ */
+declare const ModalTransition: import('react').ForwardRefExoticComponent<ModalTransitionProps & import('react').RefAttributes<HTMLDivElement>>;
+export default ModalTransition;

package/dist/src/components/popovers/modal/modal/modal-utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Fallback buffer added to the exit timeout to account for timing imprecision
+ * when the CSS `transitionend` event does not fire (e.g. reduced-motion, test
+ * environments).
+ */
+export declare const EXIT_FALLBACK_BUFFER_MS = 20;
+/**
+ * Default animation duration used when the CSS transition duration cannot be
+ * determined from the computed style of the element.
+ */
+export declare const DEFAULT_ANIMATION_DURATION_MS = 200;
+/**
+ * Represents the four discrete phases of a CSS enter/exit animation cycle.
+ *
+ * - `entering` — transition has been triggered but has not yet started (first rAF)
+ * - `entered`  — element is fully visible
+ * - `exiting`  — exit transition is in progress
+ * - `exited`   — element is fully hidden
+ */
+export type AnimationState = 'entered' | 'entering' | 'exited' | 'exiting';
+/**
+ * Parses a CSS time value string into milliseconds.
+ *
+ * Handles both `ms` (e.g. `"200ms"`) and `s` (e.g. `"0.2s"`) units.
+ * Returns `0` for empty or unrecognised values.
+ *
+ * @param value - Raw CSS time string from `getComputedStyle`.
+ * @returns Duration in milliseconds.
+ */
+export declare const parseCssTimeToMs: (value: string) => number;
+/**
+ * Returns the maximum total transition time (duration + delay) across all CSS
+ * transitions applied to `element`, in milliseconds.
+ *
+ * When no positive transition time is found the function falls back to the
+ * `--rbui-modal-animation-duration` CSS custom property, and then to
+ * {@link DEFAULT_ANIMATION_DURATION_MS}.
+ *
+ * @param element - The DOM element whose computed style is inspected.
+ * @returns Maximum transition time in milliseconds.
+ */
+export declare const getMaxTransitionTimeMs: (element: HTMLDivElement | null) => number;
+/**
+ * Maps an {@link AnimationState} to a set of `data-*` attributes suitable for
+ * spreading onto a DOM element.
+ *
+ * Only the attribute corresponding to the current `animationState` is set to
+ * `true`; the remaining attributes are `undefined` so they are omitted from
+ * the rendered HTML.
+ *
+ * @param animationState - The current animation phase.
+ * @returns An object of `data-*` attribute key/value pairs.
+ */
+export declare const getAnimationStateAttributes: (animationState: AnimationState) => Record<string, true | undefined>;
+/**
+ * Returns a ref whose `.current` is always synchronised to the latest value of
+ * `value`.
+ *
+ * Useful for reading the most-recent version of a prop or callback inside a
+ * stable `useEffect` or `useCallback` without listing it as a dependency,
+ * avoiding stale-closure bugs.
+ *
+ * @param value - The value to keep up-to-date in the ref.
+ * @returns A mutable ref object whose `.current` mirrors `value`.
+ */
+export declare const useLatestRef: <T>(value: T) => {
+    current: T;
+};

package/dist/src/components/popovers/modal/modal/modal.d.ts

@@ -1,35 +1,30 @@
 import { ModalProps } from './modal.types';
 /**
- * Modal component lets you create dialogs that force the user to take action before continuing
+ * Modal component lets you create dialogs that force the user to take action
+ * before continuing.
+ *
+ * The modal traps focus while open, locks the page scroll, and renders its
+ * content inside a {@link Portal} so it sits above all other content in the
+ * stacking context.
  *
  * ## Usage
  *
  * ```tsx
- *   <Modal open>
- *     <ModalHeader>
- *       <ModalHeaderTitle>
- *         Modal header
- *       </ModalHeaderTitle>
- *     </ModalHeader>
- *     <ModalBody>
- *       Design systems bridge the gap between creativity and consistency, ensuring a harmonious user experience
- *       across platforms. By establishing a set of guidelines and components, they empower designers to craft
- *       cohesive digital environments.
- *     </ModalBody>
- *     <ModalFooter>
- *       <ModalFooterActions>
- *         <ModalCloseButton>
- *           Cancel
- *         </ModalCloseButton>
- *         <BrButton
- *           onClick={() => {}}
- *           type="primary"
- *         >
- *           Primary
- *         </BrButton>
- *       </ModalFooterActions>
- *     </ModalFooter>
- *   </Modal>
+ * <Modal open>
+ *   <ModalHeader>
+ *     <ModalHeaderTitle>Modal header</ModalHeaderTitle>
+ *   </ModalHeader>
+ *   <ModalBody>
+ *     Design systems bridge the gap between creativity and consistency,
+ *     ensuring a harmonious user experience across platforms.
+ *   </ModalBody>
+ *   <ModalFooter>
+ *     <ModalFooterActions>
+ *       <ModalCloseButton>Cancel</ModalCloseButton>
+ *       <BrButton onClick={() => {}} type="primary">Primary</BrButton>
+ *     </ModalFooterActions>
+ *   </ModalFooter>
+ * </Modal>
  * ```
  */
 declare const Modal: import('react').ForwardRefExoticComponent<ModalProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/components/popovers/modal/modal/use-modal-presence.d.ts

@@ -0,0 +1,32 @@
+import { AnimationState } from './modal-utils';
+/** Options accepted by {@link useModalPresence}. */
+interface UseModalPresenceOptions {
+    /** Whether the modal's DOM tree should be kept in the document after closing. */
+    keepMounted: boolean;
+    /** Whether the modal is currently open. */
+    open: boolean;
+}
+/** Return value of {@link useModalPresence}. */
+interface UseModalPresenceResult {
+    /** Current animation phase of the modal. */
+    animationState: AnimationState;
+    /** Callback to advance the animation state; also drives the mount/unmount lifecycle. */
+    handleAnimationStateChange: (state: AnimationState) => void;
+    /** Whether the modal's subtree should be rendered into the DOM. */
+    isMounted: boolean;
+}
+/**
+ * Manages the mounted/unmounted lifecycle and animation state of a modal.
+ *
+ * The modal is kept in the DOM while it is open or while `keepMounted` is
+ * `true`. Once the exit animation completes (i.e. `animationState` reaches
+ * `"exited"`) and `keepMounted` is `false`, the modal is unmounted.
+ *
+ * @param options - Configuration for keep-mounted behaviour and open state.
+ * @param options.keepMounted - Whether the modal DOM tree should be retained after closing.
+ * @param options.open - Whether the modal is currently open.
+ * @returns The current animation state, a state-change handler, and a flag
+ *   indicating whether the modal subtree should be mounted.
+ */
+export declare const useModalPresence: ({ keepMounted, open }: UseModalPresenceOptions) => UseModalPresenceResult;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bloomreach/react-banana-ui",
   "type": "module",
-  "version": "1.40.0",
+  "version": "1.42.0",
   "private": false,
   "repository": {
     "type": "git",