@bloomreach/react-banana-ui 1.41.0 → 1.42.1

package/dist/src/components/inputs/select-field/select-field.stories.d.ts

@@ -19,3 +19,4 @@ export declare const FieldsInRow: Story;
 export declare const OptionWithLabel: Story;
 export declare const NoneOption: Story;
 export declare const DisabledOptions: Story;
+export declare const SelectWithDisabledOptions: Story<string, true>;

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.41.0",
+  "version": "1.42.1",
   "private": false,
   "repository": {
     "type": "git",