@diabolic/hangover 0.1.1 → 0.1.3

package/README.md

@@ -77,6 +77,7 @@ Root provider. All state lives here.
 | `darkMode` | `boolean` | `false` | Enable dark mode. Applies `hangoverDropdown--dark` CSS class which overrides all color tokens. |
 | `searchQuery` | `string` | — | Controlled search query. When provided, the internal search state is kept in sync with this value. Use together with `onEvent` (`type: "search"`) to handle changes. |
 | `defaultSearchQuery` | `string` | `""` | Uncontrolled initial search query. Only applied on first render. |
+| `useTranslationFunction` | `(text, payload?) => string` | — | Translation hook. When provided, **every** user-facing string — including built-in defaults — is routed through this function. See [Translation](#translation). |
 | `onEvent` | `(event) => any` | — | Central event handler. See [Events](#events). |
 | `ref` | `React.Ref` | — | Exposes imperative API. See [Imperative API](#imperative-api). |
 | `...rest` | `any` | — | Any additional props (e.g. `data-*`, `className`, `style`) are forwarded to the root `<div>`. |
@@ -274,6 +275,7 @@ const config = {
   defaultGroupExpanded: boolean | 'first',
   hideOnSelection: boolean,
   onEvent: ({ type, payload, prev }) => any,
+  useTranslationFunction: (text, payload) => string,
   // ...any extra props are spread onto <Dropdown>
 
   // Trigger — required
@@ -488,6 +490,58 @@ trigger.addEventListener('HO:select', (e) => {
 
 ---
 
+## Translation
+
+Pass a `useTranslationFunction` to `<Dropdown>` to localize the UI. When
+provided, **every** user-facing string is routed through it — including
+built-in defaults like `"Search"`, `"Select all"`, `"No results"` and
+`"Nothing to show here"`, as well as your own labels (group names, item
+labels, nav items, section/panel titles).
+
+The function receives the original string and returns the translated one:
+
+```jsx
+const translations = {
+  'Search': 'Ara',
+  'Select all': 'Tümünü seç',
+  'No results': 'Sonuç yok',
+  'Nothing to show here': 'Gösterilecek bir şey yok',
+  'Fruits': 'Meyveler',
+  'Apple': 'Elma',
+}
+
+<Dropdown useTranslationFunction={(text) => translations[text] ?? text}>
+  {/* ... */}
+</Dropdown>
+```
+
+### Dynamic values
+
+When a string contains dynamic values, they are passed as a payload object
+in the **second argument** instead of being concatenated into the string.
+The default string uses `{placeholder}` tokens that map to payload keys:
+
+```jsx
+<Dropdown
+  useTranslationFunction={(text, payload) => {
+    // e.g. text = "{label} — {action}", payload = { label: "Fruits", action: "collapse" }
+    if (text === '{label} — {action}') {
+      return `${payload.label}: ${payload.action === 'collapse' ? 'kapat' : 'aç'}`
+    }
+    return translations[text] ?? text
+  }}
+>
+  {/* ... */}
+</Dropdown>
+```
+
+If no `useTranslationFunction` is provided, strings render as-is and any
+`{placeholder}` tokens are interpolated from the payload automatically.
+
+> Also available via [`fromConfig`](#fromconfig--config-driven-rendering) as `useTranslationFunction`.
+
+---
+
 ## Imperative API
 
 Attach a `ref` to `<Dropdown>` to control it programmatically from **outside** the tree:

package/dist/index.cjs.js

@@ -34,7 +34,8 @@ function DropdownTrigger({
   const {
     triggerRef,
     isOpen,
-    fireEvent
+    fireEvent,
+    t
   } = useDropdownContext();
   const child = react.Children.only(children);
   function handleClick(e) {
@@ -49,12 +50,14 @@ function DropdownTrigger({
     }
     child.props.onClick?.(e);
   }
+  const childChildren = child.props.children;
+  const translatedChildren = typeof childChildren === 'string' ? t(childChildren) : childChildren;
   return /*#__PURE__*/react.cloneElement(child, {
     ref: triggerRef,
     onClick: handleClick,
     'aria-expanded': isOpen,
     'aria-haspopup': 'dialog'
-  });
+  }, translatedChildren);
 }
 
 /**
@@ -342,6 +345,7 @@ function useOutsideClick(refs, callback) {
 function DropdownPanel({
   placement = 'bottom-start',
   offset = 8,
+  title,
   anchor,
   component: Comp,
   children,
@@ -353,7 +357,8 @@ function DropdownPanel({
     triggerRef,
     fireEvent,
     hasNav,
-    darkMode
+    darkMode,
+    t
   } = useDropdownContext();
   const panelRef = react.useRef(null);
   const anchorRef = anchor ?? triggerRef;
@@ -391,20 +396,24 @@ function DropdownPanel({
     placement: actualPlacement,
     style: style,
     className: classNames,
+    title: t(title),
     ...rest,
     children: children
-  }) : /*#__PURE__*/jsxRuntime.jsx("div", {
+  }) : /*#__PURE__*/jsxRuntime.jsxs("div", {
     ref: panelRef,
     className: classNames,
     style: style,
     role: "dialog",
     "aria-modal": "true",
-    "aria-label": "Dropdown",
+    "aria-label": t('Dropdown'),
     ...rest,
-    children: /*#__PURE__*/jsxRuntime.jsx("div", {
+    children: [title && /*#__PURE__*/jsxRuntime.jsx("div", {
+      className: "hangoverDropdown-panel-title",
+      children: t(title)
+    }), /*#__PURE__*/jsxRuntime.jsx("div", {
       className: "hangoverDropdown-panel-inner",
       children: children
-    })
+    })]
   });
   return /*#__PURE__*/reactDom.createPortal(content, document.body);
 }
@@ -437,7 +446,8 @@ function DropdownNavItem({
     displayMode,
     contentRef,
     sectionRefs,
-    registerNavLabel
+    registerNavLabel,
+    t
   } = useDropdownContext();
   const isActive = activeNavId === id;
   react.useEffect(() => {
@@ -493,7 +503,7 @@ function DropdownNavItem({
       handleClick();
       userOnClick?.();
     },
-    title: typeof children === 'string' ? children : undefined,
+    title: typeof children === 'string' ? t(children) : undefined,
     "data-ho-active": isActive,
     ...navItemRest,
     children: [icon && /*#__PURE__*/jsxRuntime.jsx("span", {
@@ -502,7 +512,7 @@ function DropdownNavItem({
       children: renderIcon(icon)
     }), /*#__PURE__*/jsxRuntime.jsx("span", {
       className: "hangoverDropdown-nav-item-label",
-      children: children
+      children: typeof children === 'string' ? t(children) : children
     })]
   });
 }
@@ -615,12 +625,15 @@ function DefaultSearchIcon() {
  *
  * Props:
  *  searchPlaceholder  string (default "Search")
+ *  emptyText          string (default "Nothing to show here") — shown when
+ *                     Content has no children; the search bar is hidden too
  *  title              string — overrides active nav label as section title
  *  component          custom wrapper component
  *  children           DropdownSection / DropdownGroup / DropdownItem elements
  */
 function DropdownContent({
   searchPlaceholder = 'Search',
+  emptyText = 'Nothing to show here',
   component: Comp,
   children,
   ...rest
@@ -631,7 +644,8 @@ function DropdownContent({
     contentRef,
     displayMode,
     activeNavId,
-    setScrollSpyActive
+    setScrollSpyActive,
+    t
   } = useDropdownContext();
 
   // Scroll spy: update active nav based on scroll position
@@ -686,8 +700,9 @@ function DropdownContent({
       query: e.target.value
     });
   }
+  const isEmpty = react.Children.count(children) === 0;
   const inner = /*#__PURE__*/jsxRuntime.jsxs(jsxRuntime.Fragment, {
-    children: [/*#__PURE__*/jsxRuntime.jsxs("label", {
+    children: [!isEmpty && /*#__PURE__*/jsxRuntime.jsxs("label", {
       className: "hangoverDropdown-search",
       children: [/*#__PURE__*/jsxRuntime.jsx("span", {
         className: "hangoverDropdown-search-icon",
@@ -695,8 +710,8 @@ function DropdownContent({
       }), /*#__PURE__*/jsxRuntime.jsx("input", {
         type: "text",
         className: "hangoverDropdown-search-input",
-        placeholder: searchPlaceholder,
-        "aria-label": searchPlaceholder,
+        placeholder: t(searchPlaceholder),
+        "aria-label": t(searchPlaceholder),
         value: searchQuery,
         onChange: handleSearch
       })]
@@ -704,7 +719,10 @@ function DropdownContent({
       role: "listbox",
       className: `hangoverDropdown-list${displayMode === 'tab' ? ' isTabMode' : ''}${displayMode === 'tab' && activeNavId === '__all__' ? ' isAllActive' : ''}`,
       ref: contentRef,
-      children: children
+      children: isEmpty ? /*#__PURE__*/jsxRuntime.jsx("div", {
+        className: "hangoverDropdown-content-empty",
+        children: t(emptyText)
+      }) : children
     })]
   });
   if (Comp) {
@@ -734,7 +752,8 @@ function DropdownSection({
     activeNavId,
     displayMode,
     registerSectionRef,
-    hasNav
+    hasNav,
+    t
   } = useDropdownContext();
   const sectionRef = react.useRef(null);
   const forId = forProp || forIdProp || '__all__';
@@ -799,7 +818,7 @@ function DropdownSection({
         children: [title && hasNav && !(displayMode === 'tab' && activeNavId === '__all__') && /*#__PURE__*/jsxRuntime.jsx("div", {
           className: `hangoverDropdown-section-title${hasGroups ? ' isClickable' : ''}`,
           onClick: hasGroups ? handleToggleAll : undefined,
-          "aria-label": hasGroups ? allExpanded ? 'Collapse all groups' : 'Expand all groups' : undefined,
+          "aria-label": hasGroups ? allExpanded ? t('Collapse all groups') : t('Expand all groups') : undefined,
           role: hasGroups ? 'button' : undefined,
           tabIndex: hasGroups ? 0 : undefined,
           onKeyDown: hasGroups ? e => {
@@ -809,7 +828,7 @@ function DropdownSection({
             }
           } : undefined,
           children: /*#__PURE__*/jsxRuntime.jsx("span", {
-            children: title
+            children: t(title)
           })
         }), children]
       })
@@ -3025,7 +3044,8 @@ function DropdownItem({
     selectedItem,
     checkedItems,
     searchQuery,
-    fireEvent
+    fireEvent,
+    t
   } = useDropdownContext();
   const groupCtx = react.useContext(GroupContext);
   const groupLabel = groupCtx?.groupLabel ?? '';
@@ -3063,6 +3083,7 @@ function DropdownItem({
       fireEvent('select', {
         id,
         label,
+        groupId,
         groupLabel
       });
     }
@@ -3113,7 +3134,7 @@ function DropdownItem({
     "aria-checked": type === 'checkbox' ? isChecked : undefined,
     tabIndex: 0,
     className: classNames,
-    title: label || undefined,
+    title: label ? t(label) : undefined,
     onClick: () => {
       handleClick();
       userOnClick?.();
@@ -3130,7 +3151,7 @@ function DropdownItem({
       children: renderIcon(icon)
     }), /*#__PURE__*/jsxRuntime.jsx("span", {
       className: "hangoverDropdown-item-label",
-      children: children
+      children: typeof children === 'string' ? t(children) : children
     }), actionsNode && /*#__PURE__*/jsxRuntime.jsx("span", {
       className: "hangoverDropdown-item-actions",
       onClick: e => e.stopPropagation(),
@@ -3229,7 +3250,8 @@ function DropdownGroup({
     displayMode,
     activeNavId,
     registerGroupItems,
-    searchQuery
+    searchQuery,
+    t
   } = useDropdownContext();
 
   // Determine initial expanded state
@@ -3318,7 +3340,7 @@ function DropdownGroup({
     role: "checkbox",
     "aria-checked": selectAllChecked,
     tabIndex: 0,
-    title: "Select all",
+    title: t('Select all'),
     className: `hangoverDropdown-item isCheckboxType${selectAllChecked ? ' isChecked' : ''}`,
     onClick: handleSelectAll,
     onKeyDown: e => {
@@ -3329,7 +3351,7 @@ function DropdownGroup({
     },
     children: [/*#__PURE__*/jsxRuntime.jsx("span", {
       className: "hangoverDropdown-item-label",
-      children: "Select all"
+      children: t('Select all')
     }), /*#__PURE__*/jsxRuntime.jsx("span", {
       className: `hangoverDropdown-item-check-icon${selectAllChecked ? ' isVisible' : ''}`,
       children: selectAllChecked && /*#__PURE__*/jsxRuntime.jsx("svg", {
@@ -3350,10 +3372,10 @@ function DropdownGroup({
   const visibleItemIds = react.useMemo(() => {
     const searchableItems = react.Children.toArray(children).map(child => ({
       id: child?.props?.id,
-      label: typeof child?.props?.children === 'string' ? child.props.children : ''
+      label: typeof child?.props?.children === 'string' ? t(child.props.children) : ''
     }));
     return getMatchingItemIds(searchableItems, searchQuery);
-  }, [children, searchQuery]);
+  }, [children, searchQuery, t]);
   const groupContextValue = {
     groupLabel: label,
     groupId,
@@ -3371,8 +3393,11 @@ function DropdownGroup({
       }
     },
     "aria-expanded": isExpanded,
-    "aria-label": `${label} — ${isExpanded ? 'collapse' : 'expand'}`,
-    title: label,
+    "aria-label": t('{label} — {action}', {
+      label,
+      action: t(isExpanded ? 'collapse' : 'expand')
+    }),
+    title: t(label),
     children: [/*#__PURE__*/jsxRuntime.jsx("div", {
       className: "hangoverDropdown-group-header-accent"
     }), /*#__PURE__*/jsxRuntime.jsx("div", {
@@ -3384,7 +3409,7 @@ function DropdownGroup({
           children: renderIcon(icon)
         }), /*#__PURE__*/jsxRuntime.jsx("span", {
           className: "hangoverDropdown-group-header-label",
-          children: label
+          children: t(label)
         }), /*#__PURE__*/jsxRuntime.jsx("span", {
           className: "hangoverDropdown-group-header-chevron",
           children: /*#__PURE__*/jsxRuntime.jsx(Chevron, {})
@@ -3398,14 +3423,14 @@ function DropdownGroup({
     className: `hangoverDropdown-group-items-wrap${isExpanded ? ' isExpanded' : ''}`,
     children: /*#__PURE__*/jsxRuntime.jsxs("div", {
       role: "group",
-      "aria-label": label,
+      "aria-label": t(label),
       className: "hangoverDropdown-group-items",
       children: [showSelectAll && selectAllPosition === 'top' && selectAllItem, hasChildren ? hasVisibleItems ? children : /*#__PURE__*/jsxRuntime.jsx("div", {
         className: "hangoverDropdown-group-empty",
-        children: noResultsText
+        children: t(noResultsText)
       }) : /*#__PURE__*/jsxRuntime.jsx("div", {
         className: "hangoverDropdown-group-empty",
-        children: emptyText
+        children: t(emptyText)
       }), showSelectAll && selectAllPosition === 'bottom' && selectAllItem]
     })
   });
@@ -3717,9 +3742,10 @@ const Dropdown$1 = /*#__PURE__*/react.forwardRef(function Dropdown({
   hideOnSelection: hideOnSelectionProp = true,
   onEvent: onEventProp,
   fromConfig,
-  darkMode = false,
+  darkMode: darkModeProp = false,
   searchQuery: searchQueryProp,
-  defaultSearchQuery = '',
+  defaultSearchQuery: defaultSearchQueryProp = '',
+  useTranslationFunction: useTranslationFunctionProp,
   children,
   ...rest
 }, ref) {
@@ -3728,6 +3754,23 @@ const Dropdown$1 = /*#__PURE__*/react.forwardRef(function Dropdown({
   const defaultGroupExpanded = fromConfig?.defaultGroupExpanded ?? defaultGroupExpandedProp;
   const hideOnSelection = fromConfig?.hideOnSelection ?? hideOnSelectionProp;
   const onEvent = fromConfig?.onEvent ?? onEventProp;
+  const darkMode = fromConfig?.darkMode ?? darkModeProp;
+  const defaultSearchQuery = fromConfig?.defaultSearchQuery ?? defaultSearchQueryProp;
+  const controlledSearchQuery = fromConfig?.searchQuery ?? searchQueryProp;
+  const translationFn = fromConfig?.useTranslationFunction ?? useTranslationFunctionProp;
+
+  // Translation helper. Every user-facing string is routed through this.
+  // - With a translation function: returns translationFn(str, payload).
+  // - Without one: returns the string, interpolating any {placeholder}
+  //   tokens from the optional payload object.
+  const t = react.useCallback((str, payload) => {
+    if (typeof str !== 'string') return str;
+    if (typeof translationFn === 'function') return translationFn(str, payload);
+    if (payload) {
+      return str.replace(/\{(\w+)\}/g, (match, key) => key in payload ? payload[key] : match);
+    }
+    return str;
+  }, [translationFn]);
   const [isOpen, setIsOpen] = react.useState(defaultOpen);
   const [selectedItem, setSelectedItem] = react.useState(null);
   const [checkedItems, setCheckedItems] = react.useState(() => new Map());
@@ -3737,10 +3780,10 @@ const Dropdown$1 = /*#__PURE__*/react.forwardRef(function Dropdown({
   const [hasNav, setHasNav] = react.useState(false);
 
   // Controlled searchQuery — sync internal state whenever the prop changes
-  const isControlledSearch = searchQueryProp !== undefined;
+  const isControlledSearch = controlledSearchQuery !== undefined;
   react.useEffect(() => {
-    if (isControlledSearch) setSearchQuery(searchQueryProp);
-  }, [isControlledSearch, searchQueryProp]);
+    if (isControlledSearch) setSearchQuery(controlledSearchQuery);
+  }, [isControlledSearch, controlledSearchQuery]);
   const triggerRef = react.useRef(null);
   const contentRef = react.useRef(null); // scroll container inside DropdownContent
   const firstGroupClaimedRef = react.useRef(false);
@@ -4005,6 +4048,8 @@ const Dropdown$1 = /*#__PURE__*/react.forwardRef(function Dropdown({
     hasNav,
     darkMode,
     setHasNav,
+    // i18n
+    t,
     // Refs
     triggerRef,
     contentRef,
@@ -4024,7 +4069,7 @@ const Dropdown$1 = /*#__PURE__*/react.forwardRef(function Dropdown({
     registerSectionRef
   }), [isOpen, selectedItem, checkedItems, activeNavId, activeNavLabel, searchQuery, hasNav, displayMode, defaultGroupExpanded, darkMode,
   // all others are stable references
-  fireEvent, registerGroupItems, setScrollSpyActive, registerNavLabel, registerSectionRef]);
+  fireEvent, registerGroupItems, setScrollSpyActive, registerNavLabel, registerSectionRef, t]);
   const resolvedChildren = (() => {
     if (fromConfig && children) {
       console.warn('[Dropdown] `fromConfig` and `children` cannot be used together. ' + '`fromConfig` takes precedence — `children` will be ignored.');

package/dist/index.esm.js

@@ -30,7 +30,8 @@ function DropdownTrigger({
   const {
     triggerRef,
     isOpen,
-    fireEvent
+    fireEvent,
+    t
   } = useDropdownContext();
   const child = Children.only(children);
   function handleClick(e) {
@@ -45,12 +46,14 @@ function DropdownTrigger({
     }
     child.props.onClick?.(e);
   }
+  const childChildren = child.props.children;
+  const translatedChildren = typeof childChildren === 'string' ? t(childChildren) : childChildren;
   return /*#__PURE__*/cloneElement(child, {
     ref: triggerRef,
     onClick: handleClick,
     'aria-expanded': isOpen,
     'aria-haspopup': 'dialog'
-  });
+  }, translatedChildren);
 }
 
 /**
@@ -338,6 +341,7 @@ function useOutsideClick(refs, callback) {
 function DropdownPanel({
   placement = 'bottom-start',
   offset = 8,
+  title,
   anchor,
   component: Comp,
   children,
@@ -349,7 +353,8 @@ function DropdownPanel({
     triggerRef,
     fireEvent,
     hasNav,
-    darkMode
+    darkMode,
+    t
   } = useDropdownContext();
   const panelRef = useRef(null);
   const anchorRef = anchor ?? triggerRef;
@@ -387,20 +392,24 @@ function DropdownPanel({
     placement: actualPlacement,
     style: style,
     className: classNames,
+    title: t(title),
     ...rest,
     children: children
-  }) : /*#__PURE__*/jsx("div", {
+  }) : /*#__PURE__*/jsxs("div", {
     ref: panelRef,
     className: classNames,
     style: style,
     role: "dialog",
     "aria-modal": "true",
-    "aria-label": "Dropdown",
+    "aria-label": t('Dropdown'),
     ...rest,
-    children: /*#__PURE__*/jsx("div", {
+    children: [title && /*#__PURE__*/jsx("div", {
+      className: "hangoverDropdown-panel-title",
+      children: t(title)
+    }), /*#__PURE__*/jsx("div", {
       className: "hangoverDropdown-panel-inner",
       children: children
-    })
+    })]
   });
   return /*#__PURE__*/createPortal(content, document.body);
 }
@@ -433,7 +442,8 @@ function DropdownNavItem({
     displayMode,
     contentRef,
     sectionRefs,
-    registerNavLabel
+    registerNavLabel,
+    t
   } = useDropdownContext();
   const isActive = activeNavId === id;
   useEffect(() => {
@@ -489,7 +499,7 @@ function DropdownNavItem({
       handleClick();
       userOnClick?.();
     },
-    title: typeof children === 'string' ? children : undefined,
+    title: typeof children === 'string' ? t(children) : undefined,
     "data-ho-active": isActive,
     ...navItemRest,
     children: [icon && /*#__PURE__*/jsx("span", {
@@ -498,7 +508,7 @@ function DropdownNavItem({
       children: renderIcon(icon)
     }), /*#__PURE__*/jsx("span", {
       className: "hangoverDropdown-nav-item-label",
-      children: children
+      children: typeof children === 'string' ? t(children) : children
     })]
   });
 }
@@ -611,12 +621,15 @@ function DefaultSearchIcon() {
  *
  * Props:
  *  searchPlaceholder  string (default "Search")
+ *  emptyText          string (default "Nothing to show here") — shown when
+ *                     Content has no children; the search bar is hidden too
  *  title              string — overrides active nav label as section title
  *  component          custom wrapper component
  *  children           DropdownSection / DropdownGroup / DropdownItem elements
  */
 function DropdownContent({
   searchPlaceholder = 'Search',
+  emptyText = 'Nothing to show here',
   component: Comp,
   children,
   ...rest
@@ -627,7 +640,8 @@ function DropdownContent({
     contentRef,
     displayMode,
     activeNavId,
-    setScrollSpyActive
+    setScrollSpyActive,
+    t
   } = useDropdownContext();
 
   // Scroll spy: update active nav based on scroll position
@@ -682,8 +696,9 @@ function DropdownContent({
       query: e.target.value
     });
   }
+  const isEmpty = Children.count(children) === 0;
   const inner = /*#__PURE__*/jsxs(Fragment, {
-    children: [/*#__PURE__*/jsxs("label", {
+    children: [!isEmpty && /*#__PURE__*/jsxs("label", {
       className: "hangoverDropdown-search",
       children: [/*#__PURE__*/jsx("span", {
         className: "hangoverDropdown-search-icon",
@@ -691,8 +706,8 @@ function DropdownContent({
       }), /*#__PURE__*/jsx("input", {
         type: "text",
         className: "hangoverDropdown-search-input",
-        placeholder: searchPlaceholder,
-        "aria-label": searchPlaceholder,
+        placeholder: t(searchPlaceholder),
+        "aria-label": t(searchPlaceholder),
         value: searchQuery,
         onChange: handleSearch
       })]
@@ -700,7 +715,10 @@ function DropdownContent({
       role: "listbox",
       className: `hangoverDropdown-list${displayMode === 'tab' ? ' isTabMode' : ''}${displayMode === 'tab' && activeNavId === '__all__' ? ' isAllActive' : ''}`,
       ref: contentRef,
-      children: children
+      children: isEmpty ? /*#__PURE__*/jsx("div", {
+        className: "hangoverDropdown-content-empty",
+        children: t(emptyText)
+      }) : children
     })]
   });
   if (Comp) {
@@ -730,7 +748,8 @@ function DropdownSection({
     activeNavId,
     displayMode,
     registerSectionRef,
-    hasNav
+    hasNav,
+    t
   } = useDropdownContext();
   const sectionRef = useRef(null);
   const forId = forProp || forIdProp || '__all__';
@@ -795,7 +814,7 @@ function DropdownSection({
         children: [title && hasNav && !(displayMode === 'tab' && activeNavId === '__all__') && /*#__PURE__*/jsx("div", {
           className: `hangoverDropdown-section-title${hasGroups ? ' isClickable' : ''}`,
           onClick: hasGroups ? handleToggleAll : undefined,
-          "aria-label": hasGroups ? allExpanded ? 'Collapse all groups' : 'Expand all groups' : undefined,
+          "aria-label": hasGroups ? allExpanded ? t('Collapse all groups') : t('Expand all groups') : undefined,
           role: hasGroups ? 'button' : undefined,
           tabIndex: hasGroups ? 0 : undefined,
           onKeyDown: hasGroups ? e => {
@@ -805,7 +824,7 @@ function DropdownSection({
             }
           } : undefined,
           children: /*#__PURE__*/jsx("span", {
-            children: title
+            children: t(title)
           })
         }), children]
       })
@@ -3021,7 +3040,8 @@ function DropdownItem({
     selectedItem,
     checkedItems,
     searchQuery,
-    fireEvent
+    fireEvent,
+    t
   } = useDropdownContext();
   const groupCtx = useContext(GroupContext);
   const groupLabel = groupCtx?.groupLabel ?? '';
@@ -3059,6 +3079,7 @@ function DropdownItem({
       fireEvent('select', {
         id,
         label,
+        groupId,
         groupLabel
       });
     }
@@ -3109,7 +3130,7 @@ function DropdownItem({
     "aria-checked": type === 'checkbox' ? isChecked : undefined,
     tabIndex: 0,
     className: classNames,
-    title: label || undefined,
+    title: label ? t(label) : undefined,
     onClick: () => {
       handleClick();
       userOnClick?.();
@@ -3126,7 +3147,7 @@ function DropdownItem({
       children: renderIcon(icon)
     }), /*#__PURE__*/jsx("span", {
       className: "hangoverDropdown-item-label",
-      children: children
+      children: typeof children === 'string' ? t(children) : children
     }), actionsNode && /*#__PURE__*/jsx("span", {
       className: "hangoverDropdown-item-actions",
       onClick: e => e.stopPropagation(),
@@ -3225,7 +3246,8 @@ function DropdownGroup({
     displayMode,
     activeNavId,
     registerGroupItems,
-    searchQuery
+    searchQuery,
+    t
   } = useDropdownContext();
 
   // Determine initial expanded state
@@ -3314,7 +3336,7 @@ function DropdownGroup({
     role: "checkbox",
     "aria-checked": selectAllChecked,
     tabIndex: 0,
-    title: "Select all",
+    title: t('Select all'),
     className: `hangoverDropdown-item isCheckboxType${selectAllChecked ? ' isChecked' : ''}`,
     onClick: handleSelectAll,
     onKeyDown: e => {
@@ -3325,7 +3347,7 @@ function DropdownGroup({
     },
     children: [/*#__PURE__*/jsx("span", {
       className: "hangoverDropdown-item-label",
-      children: "Select all"
+      children: t('Select all')
     }), /*#__PURE__*/jsx("span", {
       className: `hangoverDropdown-item-check-icon${selectAllChecked ? ' isVisible' : ''}`,
       children: selectAllChecked && /*#__PURE__*/jsx("svg", {
@@ -3346,10 +3368,10 @@ function DropdownGroup({
   const visibleItemIds = useMemo(() => {
     const searchableItems = Children.toArray(children).map(child => ({
       id: child?.props?.id,
-      label: typeof child?.props?.children === 'string' ? child.props.children : ''
+      label: typeof child?.props?.children === 'string' ? t(child.props.children) : ''
     }));
     return getMatchingItemIds(searchableItems, searchQuery);
-  }, [children, searchQuery]);
+  }, [children, searchQuery, t]);
   const groupContextValue = {
     groupLabel: label,
     groupId,
@@ -3367,8 +3389,11 @@ function DropdownGroup({
       }
     },
     "aria-expanded": isExpanded,
-    "aria-label": `${label} — ${isExpanded ? 'collapse' : 'expand'}`,
-    title: label,
+    "aria-label": t('{label} — {action}', {
+      label,
+      action: t(isExpanded ? 'collapse' : 'expand')
+    }),
+    title: t(label),
     children: [/*#__PURE__*/jsx("div", {
       className: "hangoverDropdown-group-header-accent"
     }), /*#__PURE__*/jsx("div", {
@@ -3380,7 +3405,7 @@ function DropdownGroup({
           children: renderIcon(icon)
         }), /*#__PURE__*/jsx("span", {
           className: "hangoverDropdown-group-header-label",
-          children: label
+          children: t(label)
         }), /*#__PURE__*/jsx("span", {
           className: "hangoverDropdown-group-header-chevron",
           children: /*#__PURE__*/jsx(Chevron, {})
@@ -3394,14 +3419,14 @@ function DropdownGroup({
     className: `hangoverDropdown-group-items-wrap${isExpanded ? ' isExpanded' : ''}`,
     children: /*#__PURE__*/jsxs("div", {
       role: "group",
-      "aria-label": label,
+      "aria-label": t(label),
       className: "hangoverDropdown-group-items",
       children: [showSelectAll && selectAllPosition === 'top' && selectAllItem, hasChildren ? hasVisibleItems ? children : /*#__PURE__*/jsx("div", {
         className: "hangoverDropdown-group-empty",
-        children: noResultsText
+        children: t(noResultsText)
       }) : /*#__PURE__*/jsx("div", {
         className: "hangoverDropdown-group-empty",
-        children: emptyText
+        children: t(emptyText)
       }), showSelectAll && selectAllPosition === 'bottom' && selectAllItem]
     })
   });
@@ -3713,9 +3738,10 @@ const Dropdown$1 = /*#__PURE__*/forwardRef(function Dropdown({
   hideOnSelection: hideOnSelectionProp = true,
   onEvent: onEventProp,
   fromConfig,
-  darkMode = false,
+  darkMode: darkModeProp = false,
   searchQuery: searchQueryProp,
-  defaultSearchQuery = '',
+  defaultSearchQuery: defaultSearchQueryProp = '',
+  useTranslationFunction: useTranslationFunctionProp,
   children,
   ...rest
 }, ref) {
@@ -3724,6 +3750,23 @@ const Dropdown$1 = /*#__PURE__*/forwardRef(function Dropdown({
   const defaultGroupExpanded = fromConfig?.defaultGroupExpanded ?? defaultGroupExpandedProp;
   const hideOnSelection = fromConfig?.hideOnSelection ?? hideOnSelectionProp;
   const onEvent = fromConfig?.onEvent ?? onEventProp;
+  const darkMode = fromConfig?.darkMode ?? darkModeProp;
+  const defaultSearchQuery = fromConfig?.defaultSearchQuery ?? defaultSearchQueryProp;
+  const controlledSearchQuery = fromConfig?.searchQuery ?? searchQueryProp;
+  const translationFn = fromConfig?.useTranslationFunction ?? useTranslationFunctionProp;
+
+  // Translation helper. Every user-facing string is routed through this.
+  // - With a translation function: returns translationFn(str, payload).
+  // - Without one: returns the string, interpolating any {placeholder}
+  //   tokens from the optional payload object.
+  const t = useCallback((str, payload) => {
+    if (typeof str !== 'string') return str;
+    if (typeof translationFn === 'function') return translationFn(str, payload);
+    if (payload) {
+      return str.replace(/\{(\w+)\}/g, (match, key) => key in payload ? payload[key] : match);
+    }
+    return str;
+  }, [translationFn]);
   const [isOpen, setIsOpen] = useState(defaultOpen);
   const [selectedItem, setSelectedItem] = useState(null);
   const [checkedItems, setCheckedItems] = useState(() => new Map());
@@ -3733,10 +3776,10 @@ const Dropdown$1 = /*#__PURE__*/forwardRef(function Dropdown({
   const [hasNav, setHasNav] = useState(false);
 
   // Controlled searchQuery — sync internal state whenever the prop changes
-  const isControlledSearch = searchQueryProp !== undefined;
+  const isControlledSearch = controlledSearchQuery !== undefined;
   useEffect(() => {
-    if (isControlledSearch) setSearchQuery(searchQueryProp);
-  }, [isControlledSearch, searchQueryProp]);
+    if (isControlledSearch) setSearchQuery(controlledSearchQuery);
+  }, [isControlledSearch, controlledSearchQuery]);
   const triggerRef = useRef(null);
   const contentRef = useRef(null); // scroll container inside DropdownContent
   const firstGroupClaimedRef = useRef(false);
@@ -4001,6 +4044,8 @@ const Dropdown$1 = /*#__PURE__*/forwardRef(function Dropdown({
     hasNav,
     darkMode,
     setHasNav,
+    // i18n
+    t,
     // Refs
     triggerRef,
     contentRef,
@@ -4020,7 +4065,7 @@ const Dropdown$1 = /*#__PURE__*/forwardRef(function Dropdown({
     registerSectionRef
   }), [isOpen, selectedItem, checkedItems, activeNavId, activeNavLabel, searchQuery, hasNav, displayMode, defaultGroupExpanded, darkMode,
   // all others are stable references
-  fireEvent, registerGroupItems, setScrollSpyActive, registerNavLabel, registerSectionRef]);
+  fireEvent, registerGroupItems, setScrollSpyActive, registerNavLabel, registerSectionRef, t]);
   const resolvedChildren = (() => {
     if (fromConfig && children) {
       console.warn('[Dropdown] `fromConfig` and `children` cannot be used together. ' + '`fromConfig` takes precedence — `children` will be ignored.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diabolic/hangover",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A headless-style, compound React dropdown/field-picker component library",
   "license": "MIT",
   "author": "bugrakaan",
@@ -27,7 +27,6 @@
       "import": "./dist/index.esm.js",
       "require": "./dist/index.cjs.js"
     },
-    "prepublishOnly": "npm run build",
     "./styles": "./dist/hangover.css"
   },
   "files": [
@@ -49,6 +48,8 @@
     "dev": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && rollup -c -w",
     "lint": "eslint \"src/**/*.{js,jsx}\"",
     "lint:fix": "eslint --fix \"src/**/*.{js,jsx}\"",
+    "export": "node scripts/export-component.mjs",
+    "prepublishOnly": "npm run build",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"
   },
@@ -60,8 +61,8 @@
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@storybook/addon-docs": "^10.3.6",
-    "@storybook/react-vite": "^10.3.6",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
     "eslint": "^9.39.4",
     "eslint-plugin-react": "^7.37.5",
     "react": "^18.2.0",
@@ -69,7 +70,8 @@
     "rollup": "^4.13.0",
     "rollup-plugin-scss": "^4.0.0",
     "sass": "^1.99.0",
-    "storybook": "^10.3.6"
+    "storybook": "^10.4.6",
+    "eslint-plugin-storybook": "10.4.6"
   },
   "dependencies": {
     "fuse.js": "^7.3.0"