@dynamic-framework/ui-react 2.4.0 → 2.5.0

package/dist/index.esm.js

@@ -73,6 +73,12 @@ function useDisableBodyScrollEffect(disable) {
     }, [disable]);
 }
 
+/**
+ * @internal
+ * Creates a DOM `<div>` portal mount point and appends it to `document.body`.
+ * This hook is used exclusively by `DPortalContextProvider` and is **not** part
+ * of the public API. Use `useDPortalContext` instead.
+ */
 function usePortal(portalName) {
     const [hasPortal, setHasPortal] = useState(false);
     useEffect(() => {
@@ -139,20 +145,22 @@ function DPortalContextProvider({ portalName, children, availablePortals, }) {
     const { created } = usePortal(portalName);
     const [stack, { push, pop, isEmpty }] = useStackState([]);
     useDisableBodyScrollEffect(Boolean(stack.length));
-    const openPortal = useCallback((name, payload) => {
+    const openPortal = useCallback(
+    // eslint-disable-next-line prefer-arrow-callback
+    function openPortalImpl(name, payload) {
         var _a;
         if (!availablePortals) {
-            throw new Error(`there is no component for portal ${name.toString()}`);
+            throw new Error('openPortal was called but DContextProvider has no availablePortals configured. '
+                + 'Pass an availablePortals map to DContextProvider.');
         }
         const Component = availablePortals[name];
         if (!Component) {
-            throw new Error(`there is no component for portal ${name.toString()}`);
+            throw new Error(`No component registered for portal "${String(name)}". `
+                + `Ensure "${String(name)}" has an entry in the availablePortals map on DContextProvider.`);
         }
-        push({
-            name,
-            Component,
-            payload,
-        });
+        // K is a specific member of keyof T & string so the object satisfies
+        // InternalStackItem<T>, but TS can't verify generic-over-union assignability.
+        push({ name, Component, payload });
         (_a = document.activeElement) === null || _a === void 0 ? void 0 : _a.blur();
     }, [availablePortals, push]);
     const closePortal = useCallback(() => {
@@ -161,11 +169,12 @@ function DPortalContextProvider({ portalName, children, availablePortals, }) {
         }
         pop();
     }, [isEmpty, pop]);
+    const publicStack = useMemo(() => stack.map(({ name, payload }) => ({ name, payload })), [stack]);
     const value = useMemo(() => ({
-        stack,
+        stack: publicStack,
         openPortal,
         closePortal,
-    }), [stack, openPortal, closePortal]);
+    }), [publicStack, openPortal, closePortal]);
     const handleClose = useCallback((target) => {
         if (!(target instanceof HTMLDivElement)) {
             return;
@@ -221,10 +230,31 @@ function DPortalContextProvider({ portalName, children, availablePortals, }) {
                         jsx(Component, { name: name, payload: payload }, name),
                     ]) }) }), document.getElementById(portalName))] }));
 }
+/**
+ * Hook to open/close registered portals (modals, offcanvas, etc.).
+ *
+ * **Prerequisite**: must be called inside a `DContextProvider` configured with
+ * `portalName` and `availablePortals`. `DContextProvider` mounts
+ * `DPortalContextProvider` internally — consumers never use
+ * `DPortalContextProvider` directly.
+ *
+ * @template T - Map of portal name → payload shape (e.g. `ModalPayloads`).
+ *   Typing this generic gives you autocomplete on `openPortal` arguments.
+ * @returns `{ openPortal, closePortal, stack }` from the nearest portal context.
+ * @throws If called outside of `DContextProvider` / `DPortalContextProvider`.
+ *
+ * @requires DContextProvider
+ *
+ * @example
+ * ```tsx
+ * const { openPortal, closePortal } = useDPortalContext<ModalPayloads>();
+ * openPortal('confirm', { message: 'Are you sure?' });
+ * ```
+ */
 function useDPortalContext() {
     const context = useContext(DPortalContext);
     if (context === undefined) {
-        throw new Error('usePortalContext was used outside of PortalContextProvider');
+        throw new Error('useDPortalContext was used outside of DPortalContextProvider');
     }
     return context;
 }
@@ -280,10 +310,17 @@ const DEFAULT_STATE = {
         xxl: '',
     },
     setContext: () => { },
-    portalName: 'd-portal',
 };
 const DContext = createContext(DEFAULT_STATE);
-function DContextProvider({ language = DEFAULT_STATE.language, currency = DEFAULT_STATE.currency, icon = DEFAULT_STATE.icon, iconMap = DEFAULT_STATE.iconMap, portalName = DEFAULT_STATE.portalName, availablePortals, children, }) {
+/**
+ * Root context provider for Dynamic UI. Wrap your application with this
+ * component to configure icons, currency, language, and portal settings
+ * for all descendant Dynamic UI components.
+ *
+ * @template T - Map of portal name → payload shape (e.g. `{ modal: { title: string } }`).
+ *   Pass it once at the top level: `<DContextProvider<MyPortals> ...>`.
+ */
+function DContextProvider({ language = DEFAULT_STATE.language, currency = DEFAULT_STATE.currency, icon = DEFAULT_STATE.icon, iconMap = DEFAULT_STATE.iconMap, portalName = 'd-portal', availablePortals, children, }) {
     const [internalContext, setInternalContext,] = useState({
         language,
         currency,
@@ -307,12 +344,14 @@ function DContextProvider({ language = DEFAULT_STATE.language, currency = DEFAUL
     const value = useMemo(() => (Object.assign(Object.assign({}, internalContext), { setContext })), [internalContext, setContext]);
     return (jsx(DContext.Provider, { value: value, children: jsx(DPortalContextProvider, { portalName: portalName, availablePortals: availablePortals, children: children }) }));
 }
+/**
+ * Returns the Dynamic UI context value set by `DContextProvider`.
+ * Falls back to the library's built-in defaults when no `DContextProvider`
+ * is present in the tree — wrap your application with `DContextProvider`
+ * to customise icons, currency, language, and portal settings.
+ */
 function useDContext() {
-    const context = useContext(DContext);
-    if (context === undefined) {
-        throw new Error('useDContext was used outside of DContextProvider');
-    }
-    return context;
+    return useContext(DContext);
 }
 
 function subscribeToMediaQuery(query, callback) {
@@ -2379,12 +2418,34 @@ var DToast$1 = Object.assign(DToast, {
     Body: DToastBody,
 });
 
-function DToastContainer({ containerClassName, position = 'bottom-center', reverseOrder = false, containerStyle, toastOptions, gutter, }) {
+function DToastContainer({ containerClassName, position = 'bottom-center', reverseOrder = false, containerStyle, toastOptions, gutter = 8, }) {
     return (jsx(Toaster, { containerClassName: containerClassName, position: position, reverseOrder: reverseOrder, containerStyle: containerStyle, gutter: gutter, toastOptions: toastOptions }));
 }
 
+/**
+ * Hook that provides a `toast` function to dispatch DToast notifications.
+ *
+ * Prerequisites:
+ * - The calling component must be inside `DContextProvider` (provides icon context).
+ * - `DToastContainer` must be present somewhere in the component tree as a render target.
+ *
+ * @returns {{ toast }} Object containing a `toast` dispatcher function.
+ * @requires DContextProvider
+ * @requires DToastContainer
+ * @example
+ * const { toast } = useDToast();
+ * toast({ title: 'Saved', color: 'success' });
+ */
 function useDToast() {
     const { iconMap: { xLg, }, } = useDContext();
+    /**
+     * Dispatches a toast notification rendered as a `DToast` component.
+     * When `data` is a `ToastData` object, the default DToast layout is used.
+     * When `data` is a render function, full custom content is rendered instead.
+     * Returns the toast ID, which can be passed to `reactHotToast.dismiss(id)`.
+     * @param data - Toast content as `ToastData` or a render function for custom layouts.
+     * @param toastProps - Optional per-toast overrides: id, duration, position.
+     */
     const toast$1 = useCallback((data, toastProps) => {
         if (typeof data === 'function') {
             return toast.custom(data, toastProps);
@@ -2551,11 +2612,14 @@ function DCreditCard({ brand = 'visa', name, number, holderText = 'Card Holder',
 }
 
 const getItemClass = (action) => {
-    const base = `dropdown-item d-flex align-items-center 
-  ${action.color ? `dropdown-item-${action.color}` : ''} ${action.disabled ? 'disabled' : ''}`;
+    const base = classNames({
+        'dropdown-item d-flex align-items-center': true,
+        [`dropdown-item-${action.color}`]: !!action.color,
+        disabled: action.disabled,
+    });
     return base;
 };
-function DDropdown({ actions, dropdownToggle, className, }) {
+function DDropdown({ actions, dropdownToggle, className, classNameMenu, }) {
     const [open, setOpen] = useState(false);
     const dropdownRef = useRef(null);
     const [position, setPosition] = useState('down'); // 🆕
@@ -2597,14 +2661,14 @@ function DDropdown({ actions, dropdownToggle, className, }) {
     else {
         ToggleElement = (jsx(DButtonIcon, { variant: "link", stopPropagationEnabled: false, "aria-label": "Toggle Dropdown", "aria-haspopup": "menu", "aria-expanded": open, onClick: () => setOpen(!open), icon: "MoreVertical" }));
     }
-    return (jsxs("div", { className: `dropdown position-relative drop-${position} ${className}`, ref: dropdownRef, children: [ToggleElement, jsx("ul", { style: {
+    return (jsxs("div", { className: classNames(`dropdown drop-${position}`, className), ref: dropdownRef, children: [ToggleElement, jsx("ul", { style: {
                     position: 'absolute',
                     top: position === 'up' ? 'auto' : '100%',
                     bottom: position === 'up' ? '100%' : 'auto',
                     left: position === 'start' ? 'auto' : 0,
                     right: position === 'start' ? '0' : 'auto',
                     transform: 'translateY(4px)',
-                }, className: `dropdown-menu p-2 ${open ? 'show' : ''}`, children: actions.map((action, index) => {
+                }, className: classNames('dropdown-menu p-2', { show: open }, classNameMenu), children: actions.map((action, index) => {
                     if (action.isDivider) {
                         return (jsx("hr", { className: "dropdown-divider" }, index));
                     }
@@ -2861,5 +2925,5 @@ function DDataStateWrapper({ isLoading, isError, data, onRetry, renderLoading, r
     return jsx(Fragment, { children: children(data) });
 }
 
-export { DAlert, DAvatar, DBadge, DBox, DBoxFile, DButton, DButtonIcon, DCard$1 as DCard, DCardBody, DCardFooter, DCardHeader, DCarousel$1 as DCarousel, DCarouselSlide, DChip, DCollapse, DContext, DContextProvider, DCreditCard, DCurrencyText, DDataStateWrapper, DDatePicker, DDropdown, DErrorBoundary, DIcon, DIconBase, ForwardedDInput as DInput, DInputCheck, ForwardedDInputCounter as DInputCounter, ForwardedDInputCurrency as DInputCurrency, ForwardedDInputMask as DInputMask, ForwardedDInputPassword as DInputPassword, ForwardedDInputPhone as DInputPhone, DInputPin, ForwardedDInputRange as DInputRange, DInputSelect, DInputSwitch, DLayout$1 as DLayout, DLayoutPane, DListGroup$1 as DListGroup, DListGroupItem, DModal$1 as DModal, DModalBody, DModalFooter, DModalHeader, DOffcanvas$1 as DOffcanvas, DOffcanvasBody, DOffcanvasFooter, DOffcanvasHeader, DOtp, DPaginator, DPasswordStrengthMeter, DPopover, DProgress, DSelect$1 as DSelect, DStepper, DStepper$2 as DStepperDesktop, DStepper$1 as DStepperMobile, DTabContent, DTabs$1 as DTabs, DTimeline, DToast$1 as DToast, DToastContainer, DTooltip, DVoucher, changeQueryString, checkMediaQuery, configureI8n as configureI18n, formatCurrency, getCssVariable, getQueryString, subscribeToMediaQuery, useDContext, useDPortalContext, useDToast, useDisableBodyScrollEffect, useDisableInputWheel, useFormatCurrency, useInputCurrency, useItemSelection, useMediaBreakpointUpLg, useMediaBreakpointUpMd, useMediaBreakpointUpSm, useMediaBreakpointUpXl, useMediaBreakpointUpXs, useMediaBreakpointUpXxl, useMediaQuery, usePortal, useProvidedRefOrCreate, useStackState, useTabContext, validatePhoneNumber };
+export { DAlert, DAvatar, DBadge, DBox, DBoxFile, DButton, DButtonIcon, DCard$1 as DCard, DCardBody, DCardFooter, DCardHeader, DCarousel$1 as DCarousel, DCarouselSlide, DChip, DCollapse, DContext, DContextProvider, DCreditCard, DCurrencyText, DDataStateWrapper, DDatePicker, DDropdown, DErrorBoundary, DIcon, DIconBase, ForwardedDInput as DInput, DInputCheck, ForwardedDInputCounter as DInputCounter, ForwardedDInputCurrency as DInputCurrency, ForwardedDInputMask as DInputMask, ForwardedDInputPassword as DInputPassword, ForwardedDInputPhone as DInputPhone, DInputPin, ForwardedDInputRange as DInputRange, DInputSelect, DInputSwitch, DLayout$1 as DLayout, DLayoutPane, DListGroup$1 as DListGroup, DListGroupItem, DModal$1 as DModal, DModalBody, DModalFooter, DModalHeader, DOffcanvas$1 as DOffcanvas, DOffcanvasBody, DOffcanvasFooter, DOffcanvasHeader, DOtp, DPaginator, DPasswordStrengthMeter, DPopover, DProgress, DSelect$1 as DSelect, DStepper, DStepper$2 as DStepperDesktop, DStepper$1 as DStepperMobile, DTabContent, DTabs$1 as DTabs, DTimeline, DToast$1 as DToast, DToastContainer, DTooltip, DVoucher, changeQueryString, checkMediaQuery, configureI8n as configureI18n, formatCurrency, getCssVariable, getQueryString, subscribeToMediaQuery, useDContext, useDPortalContext, useDToast, useDisableBodyScrollEffect, useDisableInputWheel, useFormatCurrency, useInputCurrency, useItemSelection, useMediaBreakpointUpLg, useMediaBreakpointUpMd, useMediaBreakpointUpSm, useMediaBreakpointUpXl, useMediaBreakpointUpXs, useMediaBreakpointUpXxl, useMediaQuery, useProvidedRefOrCreate, useStackState, useTabContext, validatePhoneNumber };
 //# sourceMappingURL=index.esm.js.map