@ssa-ui-kit/core 3.3.0 → 3.4.0

package/dist/components/Dropdown/Dropdown.d.ts

@@ -5,8 +5,13 @@ import { DropdownProps } from './types';
  *
  * A flexible dropdown component that allows users to select one option from
  * a list of choices. Uses a compound component pattern with DropdownOption
- * children. Provides keyboard navigation, accessibility features, and click-outside
- * to close functionality.
+ * children. Provides keyboard navigation, accessibility features, click-outside
+ * to close functionality, and automatic viewport-aware placement of the options list.
+ *
+ * On every open the component measures available space below the toggle button
+ * and flips the list upward when there is not enough room, preventing the list
+ * from being clipped by the viewport edge. This behavior can be overridden via
+ * dropdownProps.dropdownPosition.
  *
  * Component structure:
  * - Dropdown (root container with context)
@@ -57,14 +62,15 @@ import { DropdownProps } from './types';
  *
  * @example
  * ```tsx
- * // With custom props for sub-components
+ * // With custom props for sub-components and forced upward placement
  * <Dropdown
  *   selectedItem={selected}
  *   onChange={handleChange}
  *   dropdownProps={{
  *     base: { id: 'my-dropdown' },
  *     toggleButton: { 'data-testid': 'dropdown-toggle' },
- *     toggleButtonArrow: { className: 'custom-arrow' }
+ *     toggleButtonArrow: { className: 'custom-arrow' },
+ *     dropdownPosition: DropdownPositions.top,
  *   }}
  * >
  *   {options.map(opt => (

package/dist/components/Dropdown/types.d.ts

@@ -3,6 +3,11 @@ import { Interpolation, Theme } from '@emotion/react';
 import { DropdownOptionProps } from '../DropdownOptions';
 import { CommonProps } from '../../types/emotion';
 import { IconProps } from '../Icon/types';
+export declare enum DropdownPositions {
+    top = "top",
+    bottom = "bottom",
+    auto = "auto"
+}
 /**
  * Props that are controlled by Dropdown component
  * These props cannot be passed via dropdownProps.toggleButton
@@ -13,7 +18,8 @@ export type ControlledButtonProps = 'onClick' | 'onFocus' | 'disabled' | 'type'
  *
  * A select-like dropdown component that allows users to choose one option from
  * a list. Uses compound component pattern with DropdownOption children.
- * Provides keyboard navigation, accessibility, and customizable styling.
+ * Provides keyboard navigation, accessibility, customizable styling, and
+ * automatic viewport-aware placement of the options list.
  *
  * @example
  * ```tsx
@@ -34,6 +40,18 @@ export type ControlledButtonProps = 'onClick' | 'onFocus' | 'disabled' | 'type'
  *   ))}
  * </Dropdown>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Force the list to always open upward (e.g. component near the bottom of the page)
+ * <Dropdown
+ *   selectedItem={selected}
+ *   onChange={handleChange}
+ *   dropdownProps={{ dropdownPosition: DropdownPositions.top }}
+ * >
+ *   ...
+ * </Dropdown>
+ * ```
  */
 export interface DropdownProps<P extends DropdownOptionProps> extends CommonProps {
     /**
@@ -109,6 +127,15 @@ export interface DropdownProps<P extends DropdownOptionProps> extends CommonProp
         };
         /** Props for the arrow icon SVG element */
         toggleButtonArrow?: Omit<IconProps, 'name' | 'size'>;
+        /**
+         * Controls the opening direction of the options list.
+         * - DropdownPositions.auto: opens downward by default; flips upward automatically when
+         *   there is insufficient space below the toggle in the viewport
+         * - DropdownPositions.top: always opens upward
+         * - DropdownPositions.bottom: always opens downward
+         * @default DropdownPositions.auto
+         */
+        dropdownPosition?: DropdownPositions;
     };
 }
 /**
@@ -130,4 +157,14 @@ export interface DropdownContextType {
      * Max height (px) of the options list
      */
     maxHeight?: number;
+    /**
+     * Ref attached to the options list element
+     * Used by Dropdown to measure actual list height for placement calculation
+     */
+    listRef?: React.RefObject<HTMLUListElement | null>;
+    /**
+     * Resolved placement of the options list
+     * Computed by Dropdown based on dropdownPosition prop and available viewport space
+     */
+    placement?: 'top' | 'bottom';
 }

package/dist/components/DropdownOptions/DropdownOptions.d.ts

@@ -5,6 +5,11 @@ import { DropdownItemsListProps } from './types';
  * Renders the scrollable list of options that appears when the dropdown is open.
  * Provides proper ARIA attributes for accessibility and keyboard navigation.
  *
+ * Placement (opening upward or downward) is driven entirely by the parent
+ * Dropdown via context — this component does not calculate position itself.
+ * A ref is attached to the list element so Dropdown can measure its actual
+ * rendered height when determining the correct placement on each open.
+ *
  * @category Form Controls
  * @subcategory Selection
  *

package/dist/components/Pagination/components/RowsPerPageDropdown/RowsPerPageDropdown.d.ts

@@ -40,4 +40,4 @@ import { RowsPerPageDropdownProps } from './types';
  * - Keyboard navigation support
  * - Screen reader friendly
  */
-export declare const RowsPerPageDropdown: ({ selectedItem, rowsPerPageList, rowsPerPageText, ...rest }: RowsPerPageDropdownProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const RowsPerPageDropdown: ({ selectedItem, rowsPerPageList, rowsPerPageText, dropdownPosition, ...rest }: RowsPerPageDropdownProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Pagination/components/RowsPerPageDropdown/types.d.ts

@@ -1,4 +1,5 @@
 import { CommonProps } from '../../../../types/emotion';
+import { DropdownPositions } from '../../../index';
 /**
  * Props for the RowsPerPageDropdown component
  *
@@ -45,4 +46,13 @@ export interface RowsPerPageDropdownProps extends CommonProps {
         id: number;
         value: number;
     }>;
+    /**
+     * Controls the opening direction of the options list.
+     * - DropdownPositions.auto: opens downward by default; flips upward automatically when
+     *   there is insufficient space below the toggle in the viewport
+     * - DropdownPositions.top: always opens upward
+     * - DropdownPositions.bottom: always opens downward
+     * @default DropdownPositions.auto
+     */
+    dropdownPosition?: DropdownPositions;
 }

package/dist/components/Pagination/types.d.ts

@@ -87,8 +87,11 @@ export interface PaginationProps extends CommonProps {
      */
     isPageFromCountVisible?: boolean;
     /**
-     * Props for the rows per page dropdown
-     * Only used when isRowPerPageVisible is true
+     * Props for the rows per page dropdown.
+     * Only used when isRowPerPageVisible is true.
+     * Use rowPerPageProps.dropdownPosition to control the opening direction
+     * ('auto' | 'top' | 'bottom'). Defaults to 'auto', which flips the list
+     * upward automatically when there is insufficient space below the toggle.
      */
     rowPerPageProps?: RowsPerPageDropdownProps;
     /**

package/dist/index.js

@@ -17033,7 +17033,9 @@ const DropdownContext = /*#__PURE__*/external_react_namespaceObject.createContex
   onChange: () => {
     /* noop */
   },
-  maxHeight: 200
+  maxHeight: 200,
+  listRef: undefined,
+  placement: 'bottom'
 });
 function useDropdownContext() {
   return external_react_namespaceObject.useContext(DropdownContext);
@@ -17074,7 +17076,9 @@ function DropdownOptions_EMOTION_STRINGIFIED_CSS_ERROR_() { return "You have tri
 
 const DropdownOptionsBase = /*#__PURE__*/base_default()("ul",  true ? {
   target: "e1qg2z4z0"
-} : 0)("position:absolute;width:100%;min-width:max-content;list-style:none;margin:4px 0 0;padding:0;background:", ({
+} : 0)("position:absolute;width:100%;min-width:max-content;list-style:none;padding:0;", ({
+  placement = 'bottom'
+}) => placement === 'top' ? 'bottom: 100%; top: auto; margin: 0 0 4px;' : 'top: 100%; bottom: auto; margin: 4px 0 0;', " background:", ({
   theme
 }) => theme.colors.white, ";border-radius:8px;max-height:", ({
   maxHeight = 200
@@ -17102,6 +17106,11 @@ const noItemsMsg = {
  * Renders the scrollable list of options that appears when the dropdown is open.
  * Provides proper ARIA attributes for accessibility and keyboard navigation.
  *
+ * Placement (opening upward or downward) is driven entirely by the parent
+ * Dropdown via context — this component does not calculate position itself.
+ * A ref is attached to the list element so Dropdown can measure its actual
+ * rendered height when determining the correct placement on each open.
+ *
  * @category Form Controls
  * @subcategory Selection
  *
@@ -17135,7 +17144,9 @@ const DropdownOptions = ({
   const {
     onChange,
     activeItem,
-    maxHeight
+    maxHeight,
+    listRef,
+    placement
   } = useDropdownContext();
   const childrenArray = external_react_default().Children.toArray(children).filter(Boolean);
 
@@ -17169,11 +17180,13 @@ const DropdownOptions = ({
     }, noItemsMsg.id));
   }
   return (0,jsx_runtime_namespaceObject.jsx)(DropdownOptionsBase, {
+    ref: listRef,
     role: "listbox",
     tabindex: "-1",
     id: id,
     "aria-labelledby": ariaLabelledby,
     maxHeight: maxHeight,
+    placement: placement,
     children: options
   });
 };
@@ -17223,6 +17236,64 @@ const Avatar = /*#__PURE__*/base_default()("div",  true ? {
   image
 }) => `url(${image})`, " center/contain no-repeat;" + ( true ? "" : 0));
 /* harmony default export */ const Avatar_Avatar = (Avatar);
+;// ./src/components/Dropdown/types.ts
+let DropdownPositions = /*#__PURE__*/function (DropdownPositions) {
+  DropdownPositions["top"] = "top";
+  DropdownPositions["bottom"] = "bottom";
+  DropdownPositions["auto"] = "auto";
+  return DropdownPositions;
+}({});
+
+/**
+ * Props that are controlled by Dropdown component
+ * These props cannot be passed via dropdownProps.toggleButton
+ */
+
+/**
+ * Props for the Dropdown component
+ *
+ * A select-like dropdown component that allows users to choose one option from
+ * a list. Uses compound component pattern with DropdownOption children.
+ * Provides keyboard navigation, accessibility, customizable styling, and
+ * automatic viewport-aware placement of the options list.
+ *
+ * @example
+ * ```tsx
+ * const items = [
+ *   { id: 1, value: 'Option 1' },
+ *   { id: 2, value: 'Option 2' },
+ * ];
+ *
+ * <Dropdown
+ *   selectedItem={items[0]}
+ *   onChange={(item) => console.log(item)}
+ *   placeholder="Select an option"
+ * >
+ *   {items.map(item => (
+ *     <DropdownOption key={item.id} value={item.id}>
+ *       {item.value}
+ *     </DropdownOption>
+ *   ))}
+ * </Dropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Force the list to always open upward (e.g. component near the bottom of the page)
+ * <Dropdown
+ *   selectedItem={selected}
+ *   onChange={handleChange}
+ *   dropdownProps={{ dropdownPosition: DropdownPositions.top }}
+ * >
+ *   ...
+ * </Dropdown>
+ * ```
+ */
+
+/**
+ * Dropdown context value
+ * Provides selection state and change handler to child DropdownOption components
+ */
 ;// ./src/components/Dropdown/Dropdown.tsx
 
 function Dropdown_EMOTION_STRINGIFIED_CSS_ERROR_() { return "You have tried to stringify object returned from `css` function. It isn't supposed to be used directly (e.g. as value of the `className` prop), but rather handed to emotion so it can handle it (e.g. as value of `css` prop)."; }
@@ -17235,6 +17306,7 @@ function Dropdown_EMOTION_STRINGIFIED_CSS_ERROR_() { return "You have tried to s
 
 
 
+
 const DropdownBase = /*#__PURE__*/base_default()("div",  true ? {
   target: "eizhqtp1"
 } : 0)( true ? {
@@ -17253,8 +17325,13 @@ const SelectedContent = /*#__PURE__*/base_default()("span",  true ? {
  *
  * A flexible dropdown component that allows users to select one option from
  * a list of choices. Uses a compound component pattern with DropdownOption
- * children. Provides keyboard navigation, accessibility features, and click-outside
- * to close functionality.
+ * children. Provides keyboard navigation, accessibility features, click-outside
+ * to close functionality, and automatic viewport-aware placement of the options list.
+ *
+ * On every open the component measures available space below the toggle button
+ * and flips the list upward when there is not enough room, preventing the list
+ * from being clipped by the viewport edge. This behavior can be overridden via
+ * dropdownProps.dropdownPosition.
  *
  * Component structure:
  * - Dropdown (root container with context)
@@ -17305,14 +17382,15 @@ const SelectedContent = /*#__PURE__*/base_default()("span",  true ? {
  *
  * @example
  * ```tsx
- * // With custom props for sub-components
+ * // With custom props for sub-components and forced upward placement
  * <Dropdown
  *   selectedItem={selected}
  *   onChange={handleChange}
  *   dropdownProps={{
  *     base: { id: 'my-dropdown' },
  *     toggleButton: { 'data-testid': 'dropdown-toggle' },
- *     toggleButtonArrow: { className: 'custom-arrow' }
+ *     toggleButtonArrow: { className: 'custom-arrow' },
+ *     dropdownPosition: DropdownPositions.top,
  *   }}
  * >
  *   {options.map(opt => (
@@ -17347,14 +17425,19 @@ const Dropdown = ({
   maxHeight = 200,
   dropdownProps: componentProps
 }) => {
+  const {
+    dropdownPosition = DropdownPositions.auto
+  } = componentProps ?? {};
   const theme = (0,react_namespaceObject.useTheme)();
   const dropdownRef = (0,external_react_namespaceObject.useRef)(null);
+  const listRef = (0,external_react_namespaceObject.useRef)(null);
   const dropdownId = (0,external_react_namespaceObject.useId)();
   const options = [];
   const [isFocused, setIsFocused] = (0,external_react_namespaceObject.useState)(false);
   const [isOpen, setIsOpen] = (0,external_react_namespaceObject.useState)(isInitOpen || false);
   const [colors, setColors] = (0,external_react_namespaceObject.useState)([]);
   const [activeItem, setActiveItem] = (0,external_react_namespaceObject.useState)(selectedItem);
+  const [placement, setPlacement] = (0,external_react_namespaceObject.useState)('bottom');
   const onChange = item => {
     const innerItem = options.filter(option => option.value === item)[0];
     setIsOpen(false);
@@ -17387,6 +17470,17 @@ const Dropdown = ({
       setIsOpen(false);
     }
   }, [isDisabled]);
+  (0,external_react_namespaceObject.useLayoutEffect)(() => {
+    if (!isOpen || !dropdownRef.current) return;
+    if (dropdownPosition !== DropdownPositions.auto) {
+      setPlacement(dropdownPosition);
+      return;
+    }
+    const rect = dropdownRef.current.getBoundingClientRect();
+    const listHeight = listRef.current?.offsetHeight || maxHeight;
+    const spaceBelow = window.innerHeight - rect.bottom;
+    setPlacement(spaceBelow < listHeight ? 'top' : 'bottom');
+  }, [isOpen]);
   const childrenArray = external_react_default().Children.toArray(children).filter(Boolean);
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -17401,8 +17495,10 @@ const Dropdown = ({
   const contextValue = external_react_default().useMemo(() => ({
     onChange,
     activeItem,
-    maxHeight
-  }), [onChange, activeItem, maxHeight]);
+    maxHeight,
+    listRef,
+    placement
+  }), [onChange, activeItem, maxHeight, placement]);
   const value = activeItem ? activeItem.label || activeItem.children || activeItem.value || activeItem || placeholder : placeholder;
   const rawAvatar = activeItem && activeItem.avatar;
   const selectedAvatar = rawAvatar != null ? typeof rawAvatar === 'string' ? (0,jsx_runtime_namespaceObject.jsx)(Avatar_Avatar, {
@@ -49630,6 +49726,7 @@ const RowsPerPageDropdown = ({
   selectedItem = DEFAULT_PER_PAGE_VALUE,
   rowsPerPageList = ROWS_PER_PAGE_LIST,
   rowsPerPageText = 'Rows per page',
+  dropdownPosition,
   ...rest
 }) => {
   const theme = (0,react_namespaceObject.useTheme)();
@@ -49675,7 +49772,8 @@ const RowsPerPageDropdown = ({
               stroke: theme.colors.greyDarker
             }
           }
-        }
+        },
+        dropdownPosition
       },
       ...rest,
       children: rowsPerPageList.map(item => (0,jsx_runtime_namespaceObject.jsx)(DropdownOption_DropdownOption, {