@dt-dds/react-dropdown 1.0.0-beta.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daimler Truck AG.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Dropdown Package
+
+The Dropdown Menu provides the users with a box that can receive any content. It also provides an Option component.
+
+## Dropdown Usage
+
+```jsx
+import { Dropdown } from '@dt-dds/react';
+
+const OPTIONS = [
+  { text: 'Option 1', value: '1' },
+  { text: 'Option 2', value: '2' },
+];
+
+export const App = () => {
+  return (
+    <Dropdown>
+      {options.map((option) => (
+        <Dropdown.Option key={option.value}>{option.text}</Dropdown.Option>
+      ))}
+    </Dropdown>
+  );
+};
+```
+
+## Properties
+
+### Dropdown
+
+| Property     | Type                             | Default    | Description                                                                 |
+| ------------ | -------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| `children`   | `ReactNode`                      | —          | Child components/content to be rendered inside the dropdown.                |
+| `style`      | `React.CSSProperties`            | —          | Inline styles merged **after** computed positioning styles.                 |
+| `dataTestId` | `string`                         | `dropdown` | Customizable test identifier applied to the dropdown root element.          |
+| `isOpen`     | `boolean`                        | `false`    | Controls visibility. When `false`, the element is hidden via `aria-hidden`. |
+| `anchorRef`  | `RefObject<HTMLElement \| null>` | -          | Reference to the anchor element used for positioning.                       |
+| `matchWidth` | `boolean`                        | `true`     | If `true`, the dropdown width matches the anchor width.                     |
+| `offsetX`    | `number`                         | `4`        | Horizontal offset (px) for `left`/`right` placements.                       |
+| `offsetY`    | `number`                         | `4`        | Vertical offset (px) for `top`/`bottom` placements.                         |
+| `onClose`    | `() => void`                     | —          | Called when a click is detected outside the dropdown/anchor.                |
+| `as`         | `keyof JSX.IntrinsicElements`    | `"div"`    | Underlying HTML element (e.g., `"ul"` for list semantics).                  |
+| `placement`  | `DropdownPlacement`              | `bottom`   | Dropdown position.                                                          |
+| `...rest`    | `HTMLAttributes`                 | —          | Standard HTML attributes.                                                   |
+
+### Dropdown.Option
+
+| Property        | Type                                         | Default           | Description                                                             |
+| --------------- | -------------------------------------------- | ----------------- | ----------------------------------------------------------------------- |
+| `style`         | `React.CSSProperties`                        | —                 | Inline styles for the option element.                                   |
+| `children`      | `ReactNode`                                  | —                 | Content of the option.                                                  |
+| `dataTestId`    | `string`                                     | `dropdown-option` | Customizable test identifier for the option element.                    |
+| `isDisabled`    | `boolean`                                    | `false`           | When `true`, sets `aria-disabled` and blocks click/keyboard activation. |
+| `isSelected`    | `boolean`                                    | `false`           | Reflects selection state via `aria-selected` and styling.               |
+| `isHighlighted` | `boolean`                                    | `false`           | Adds `data-highlighted="true"` for hover/active row styling.            |
+| `isMulti`       | `boolean`                                    | `false`           | Optional styling hint for multi-select contexts (no selection logic).   |
+| `onClick`       | `(event: MouseEvent<HTMLLIElement>) => void` | —                 | Click handler.                                                          |
+| `...rest`       | `HTMLAttributes`                             | —                 | Standard HTML attributes.                                               |
+
+## Stack
+
+- [TypeScript](https://www.typescriptlang.org/) for static type checking
+- [React](https://reactjs.org/) — JavaScript library for user interfaces
+- [Emotion](https://emotion.sh/docs/introduction) — for writing css styles with JavaScript
+- [Storybook](https://storybook.js.org/) — UI component environment powered by Vite
+- [Jest](https://jestjs.io/) - JavaScript Testing Framework
+- [React Testing Library](https://testing-library.com/) - to test UI components in a user-centric way
+- [ESLint](https://eslint.org/) for code linting
+- [Prettier](https://prettier.io) for code formatting
+- [Tsup](https://github.com/egoist/tsup) — TypeScript bundler powered by esbuild
+- [Yarn](https://yarnpkg.com/) from managing packages
+
+## Commands
+
+- `yarn build` - Build the package
+- `yarn dev` - Run the package locally
+- `yarn lint` - Lint all files within this package
+- `yarn test` - Run all unit tests
+- `yarn test:report` - Open the test coverage report
+- `yarn test:update:snapshot` - Run all unit tests and update the snapshot
+
+## Compilation
+
+Running `yarn build` from the root of the package will use [tsup](https://tsup.egoist.dev/) to compile the raw TypeScript and React code to plain JavaScript.
+
+The `/dist` folder contains the compiled output.
+
+```bash
+dropdown
+└── dist
+    ├── index.d.ts  <-- Types
+    ├── index.js    <-- CommonJS version
+    └── index.mjs   <-- ES Modules version
+    ...
+```
+
+## Versioning
+
+Follows [semantic versioning](https://semver.org/)
+
+## &copy; License
+
+Licensed under [MIT License](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import { CustomTheme } from '@dt-dds/themes';
+import * as react from 'react';
+import { AnchorHTMLAttributes, ElementType, MouseEvent, HTMLAttributes, RefObject } from 'react';
+import { BaseProps } from '@dt-dds/react-core';
+
+interface DropdownOptionProps extends BaseProps, Omit<AnchorHTMLAttributes<HTMLElement>, 'onClick'> {
+    isDisabled?: boolean;
+    isSelected?: boolean;
+    isHighlighted?: boolean;
+    isMulti?: boolean;
+    as?: ElementType;
+    onClick?: (e: MouseEvent<HTMLElement>) => void;
+}
+declare const DropdownOption: react.ForwardRefExoticComponent<DropdownOptionProps & react.RefAttributes<HTMLLIElement>>;
+
+type DropdownVariant = 'outlined' | 'bottom-line';
+type DropdownFill = 'default' | 'contrast' | 'light';
+type DropdownPlacement = 'bottom' | 'top' | 'left' | 'right';
+
+interface DropdownProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    isOpen?: boolean;
+    anchorRef: RefObject<HTMLElement | null>;
+    matchWidth?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    onClose?: () => void;
+    as?: keyof JSX.IntrinsicElements;
+    placement?: DropdownPlacement;
+    isFocusable?: boolean;
+}
+declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLElement>> & {
+    Option: react.ForwardRefExoticComponent<DropdownOptionProps & react.RefAttributes<HTMLLIElement>>;
+};
+
+declare module '@emotion/react' {
+    interface Theme extends CustomTheme {
+    }
+}
+
+export { Dropdown, type DropdownFill, DropdownOption, type DropdownOptionProps, type DropdownPlacement, type DropdownProps, type DropdownVariant };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { CustomTheme } from '@dt-dds/themes';
+import * as react from 'react';
+import { AnchorHTMLAttributes, ElementType, MouseEvent, HTMLAttributes, RefObject } from 'react';
+import { BaseProps } from '@dt-dds/react-core';
+
+interface DropdownOptionProps extends BaseProps, Omit<AnchorHTMLAttributes<HTMLElement>, 'onClick'> {
+    isDisabled?: boolean;
+    isSelected?: boolean;
+    isHighlighted?: boolean;
+    isMulti?: boolean;
+    as?: ElementType;
+    onClick?: (e: MouseEvent<HTMLElement>) => void;
+}
+declare const DropdownOption: react.ForwardRefExoticComponent<DropdownOptionProps & react.RefAttributes<HTMLLIElement>>;
+
+type DropdownVariant = 'outlined' | 'bottom-line';
+type DropdownFill = 'default' | 'contrast' | 'light';
+type DropdownPlacement = 'bottom' | 'top' | 'left' | 'right';
+
+interface DropdownProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    isOpen?: boolean;
+    anchorRef: RefObject<HTMLElement | null>;
+    matchWidth?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    onClose?: () => void;
+    as?: keyof JSX.IntrinsicElements;
+    placement?: DropdownPlacement;
+    isFocusable?: boolean;
+}
+declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLElement>> & {
+    Option: react.ForwardRefExoticComponent<DropdownOptionProps & react.RefAttributes<HTMLLIElement>>;
+};
+
+declare module '@emotion/react' {
+    interface Theme extends CustomTheme {
+    }
+}
+
+export { Dropdown, type DropdownFill, DropdownOption, type DropdownOptionProps, type DropdownPlacement, type DropdownProps, type DropdownVariant };

package/dist/index.js

@@ -0,0 +1,403 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  Dropdown: () => Dropdown,
+  DropdownOption: () => DropdownOption
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Dropdown.tsx
+var import_react3 = require("react");
+var import_focus_trap_react = require("focus-trap-react");
+var import_react_core2 = require("@dt-dds/react-core");
+
+// src/components/option/DropdownOption.tsx
+var import_react = require("react");
+
+// src/components/option/DropdownOption.styled.ts
+var import_styled = __toESM(require("@emotion/styled"));
+var DropdownOptionStyled = import_styled.default.li`
+  ${({ theme }) => `
+    ${theme.fontStyles.bodyMdRegular};
+
+    display: block;
+    color: ${theme.palette.content.default};
+    padding: ${theme.spacing.spacing_40} ${theme.spacing.spacing_50};   
+    list-style: none;
+    text-overflow: ellipsis;
+    overflow-x: hidden;
+    text-wrap: nowrap;
+
+    &:not([aria-disabled="true"]) {
+      &[aria-selected="true"], &[aria-selected="true"] span {
+        ${theme.fontStyles.bodyMdBold};
+      }
+
+      &:hover, &[data-highlighted="true"] {
+        background: ${theme.palette.accent.light};
+        cursor: pointer;
+      }
+
+      &:focus-visible {
+        outline: 2px solid ${theme.palette.primary.default};
+        outline-offset: -2px; 
+      }
+    }
+
+    &[aria-disabled="true"] {
+      color: ${theme.palette.content.light};
+      cursor: not-allowed;
+
+      &[aria-selected="true"] {
+        background-color: ${theme.palette.surface.light};
+      }
+    }
+  `}
+`;
+
+// src/components/option/DropdownOption.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var DropdownOption = (0, import_react.forwardRef)(
+  (_a, ref) => {
+    var _b = _a, {
+      dataTestId,
+      children,
+      style,
+      isDisabled,
+      isSelected = false,
+      isHighlighted = false,
+      onClick
+    } = _b, rest = __objRest(_b, [
+      "dataTestId",
+      "children",
+      "style",
+      "isDisabled",
+      "isSelected",
+      "isHighlighted",
+      "onClick"
+    ]);
+    const testId = dataTestId != null ? dataTestId : "dropdown-option";
+    const handleClick = (e) => {
+      if (isDisabled) {
+        e.preventDefault();
+        e.stopPropagation();
+        return;
+      }
+      onClick == null ? void 0 : onClick(e);
+    };
+    const handleKeyDown = (e) => {
+      if (e.code === "Enter" || e.code === "Space") {
+        e.preventDefault();
+        onClick == null ? void 0 : onClick(e);
+      }
+    };
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      DropdownOptionStyled,
+      __spreadProps(__spreadValues(__spreadValues({
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        tabIndex: isDisabled ? -1 : 0
+      }, !isSelected && { role: "menuitem" }), rest), {
+        "aria-disabled": isDisabled,
+        "aria-selected": isSelected,
+        "data-highlighted": isHighlighted,
+        "data-testid": testId,
+        ref,
+        style,
+        children
+      })
+    );
+  }
+);
+
+// src/Dropdown.styled.ts
+var import_styled2 = __toESM(require("@emotion/styled"));
+var DropdownStyled = import_styled2.default.div`
+  list-style-type: none;
+  width: 100%;
+  overflow: auto;
+`;
+
+// src/hooks/useFloatingPosition.ts
+var import_react2 = require("react");
+var import_react_core = require("@dt-dds/react-core");
+function basePos({
+  placement,
+  anchor,
+  menuWidth,
+  menuHeight,
+  offsetX,
+  offsetY
+}) {
+  switch (placement) {
+    case "bottom":
+      return { top: anchor.bottom + offsetY, left: anchor.left + offsetX };
+    case "top":
+      return {
+        top: anchor.top - offsetY - menuHeight,
+        left: anchor.left + offsetX
+      };
+    case "right":
+      return { top: anchor.top + offsetY, left: anchor.right + offsetX };
+    case "left":
+      return {
+        top: anchor.top + offsetY,
+        left: anchor.left - offsetX - menuWidth
+      };
+  }
+}
+function useFloatingPosition(anchorEl, open, {
+  offsetX = 0,
+  offsetY = 4,
+  matchWidth = true,
+  minViewportPadding = 8,
+  placement = "bottom",
+  menuRef
+} = {}) {
+  const [style, setStyle] = (0, import_react2.useState)({
+    visibility: "hidden",
+    position: "fixed"
+  });
+  (0, import_react2.useLayoutEffect)(() => {
+    if (!open || !(anchorEl == null ? void 0 : anchorEl.current)) {
+      setStyle({
+        visibility: "hidden",
+        position: "fixed"
+      });
+      return;
+    }
+    const anchorElement = anchorEl == null ? void 0 : anchorEl.current;
+    const menuElement = menuRef == null ? void 0 : menuRef.current;
+    const updatePosition = () => {
+      var _a, _b;
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      const anchor = anchorElement.getBoundingClientRect();
+      const menuRect = menuElement == null ? void 0 : menuElement.getBoundingClientRect();
+      const menuWidth = matchWidth ? anchor.width : (_a = menuRect == null ? void 0 : menuRect.width) != null ? _a : anchor.width;
+      const menuHeight = (_b = menuRect == null ? void 0 : menuRect.height) != null ? _b : 0;
+      let { top, left } = basePos({
+        placement,
+        anchor,
+        menuWidth,
+        menuHeight,
+        offsetX,
+        offsetY
+      });
+      const maxLeft = Math.max(
+        minViewportPadding,
+        vw - menuWidth - minViewportPadding
+      );
+      const maxTop = Math.max(
+        minViewportPadding,
+        vh - menuHeight - minViewportPadding
+      );
+      left = Math.max(minViewportPadding, Math.min(left, maxLeft));
+      top = Math.max(minViewportPadding, Math.min(top, maxTop));
+      setStyle({
+        position: "fixed",
+        top,
+        left,
+        width: matchWidth ? anchor.width : void 0,
+        maxWidth: matchWidth ? anchor.width : 300,
+        boxSizing: "border-box",
+        zIndex: import_react_core.DROPDOWN_MENU_Z_INDEX
+      });
+    };
+    updatePosition();
+    const ro = new ResizeObserver(updatePosition);
+    ro.observe(anchorElement);
+    if (anchorElement) {
+      ro.observe(anchorElement);
+    }
+    const opts = { passive: true };
+    window.addEventListener("scroll", updatePosition, opts);
+    window.addEventListener("resize", updatePosition, opts);
+    return () => {
+      ro.disconnect();
+      window.removeEventListener("scroll", updatePosition, opts);
+      window.removeEventListener("resize", updatePosition, opts);
+    };
+  }, [
+    menuRef,
+    anchorEl,
+    open,
+    placement,
+    offsetX,
+    offsetY,
+    matchWidth,
+    minViewportPadding
+  ]);
+  return { style };
+}
+
+// src/utils/set-ref.ts
+var setRef = (target, node) => {
+  if (!target) {
+    return;
+  }
+  if (typeof target === "function") {
+    target(node);
+    return;
+  }
+  target.current = node;
+};
+
+// src/Dropdown.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var Dropdown = Object.assign(
+  (0, import_react3.forwardRef)(
+    (_a, forwardedRef) => {
+      var _b = _a, {
+        children,
+        style,
+        dataTestId = "dropdown",
+        isOpen = false,
+        anchorRef,
+        matchWidth = true,
+        offsetX,
+        offsetY,
+        as = "div",
+        onClose,
+        placement,
+        isFocusable = true
+      } = _b, rest = __objRest(_b, [
+        "children",
+        "style",
+        "dataTestId",
+        "isOpen",
+        "anchorRef",
+        "matchWidth",
+        "offsetX",
+        "offsetY",
+        "as",
+        "onClose",
+        "placement",
+        "isFocusable"
+      ]);
+      const localMenuRef = (0, import_react3.useRef)(null);
+      const setMenuRef = (0, import_react3.useCallback)(
+        (node) => {
+          localMenuRef.current = node;
+          setRef(forwardedRef, node);
+        },
+        [forwardedRef]
+      );
+      const { style: floatingStyle } = useFloatingPosition(
+        anchorRef,
+        isOpen,
+        {
+          matchWidth,
+          offsetX,
+          offsetY,
+          placement,
+          menuRef: localMenuRef
+        }
+      );
+      (0, import_react_core2.useClickOutside)({
+        refs: [localMenuRef, anchorRef],
+        handler: () => onClose == null ? void 0 : onClose()
+      });
+      const dropdownNode = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        DropdownStyled,
+        __spreadProps(__spreadValues(__spreadValues({
+          as,
+          "data-testid": dataTestId,
+          ref: setMenuRef,
+          role: "menu",
+          style: __spreadValues(__spreadValues({}, floatingStyle), style)
+        }, rest), !isFocusable && {
+          onMouseDown: (e) => e.preventDefault()
+        }), {
+          children
+        })
+      );
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react_core2.Portal, { isOpen: true, children: isFocusable ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        import_focus_trap_react.FocusTrap,
+        {
+          active: isOpen,
+          focusTrapOptions: {
+            initialFocus: () => {
+              var _a2;
+              return (_a2 = localMenuRef == null ? void 0 : localMenuRef.current) != null ? _a2 : false;
+            },
+            fallbackFocus: () => document.body,
+            escapeDeactivates: true,
+            allowOutsideClick: true,
+            onDeactivate: () => {
+              onClose == null ? void 0 : onClose();
+            },
+            tabbableOptions: { displayCheck: "none" }
+          },
+          children: dropdownNode
+        }
+      ) : dropdownNode });
+    }
+  ),
+  {
+    Option: DropdownOption
+  }
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Dropdown,
+  DropdownOption
+});