pixelize-design-library 2.4.2-beta.9 → 3.0.0

package/dist/Components/Drawer/Drawer.js

@@ -1,14 +1,15 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DrawerFooter = exports.DrawerBody = exports.DrawerHeader = void 0;
+exports.UNNAMED_DRAWER_WARNING = exports.DrawerFooter = exports.DrawerBody = exports.DrawerHeader = void 0;
 exports.default = Drawer;
 const jsx_runtime_1 = require("react/jsx-runtime");
-const react_1 = __importDefault(require("react"));
+const react_1 = require("react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const surfaceRaised_1 = require("../../Theme/tokens/builders/surfaceRaised");
+const dialogNaming_1 = require("../Modal/dialogNaming");
+const warnDroppedSlotChildren_1 = require("../Modal/warnDroppedSlotChildren");
 const react_2 = require("@chakra-ui/react");
+const findSlot_1 = require("../Common/findSlot");
 const DrawerHeader = ({ children }) => {
     return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
 };
@@ -21,13 +22,31 @@ const DrawerFooter = ({ children }) => {
     return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
 };
 exports.DrawerFooter = DrawerFooter;
-function Drawer({ isOpen, onClose, placement = "right", size = "xl", id, variant = "solid", children, }) {
+exports.UNNAMED_DRAWER_WARNING = "[pixelize-design-library] Drawer: no DrawerHeader, aria-label or aria-labelledby, so screen readers announce it as an unnamed dialog.";
+const useUnnamedWarning = (isUnnamed) => {
+    const warned = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (process.env.NODE_ENV === "production" || !isUnnamed || warned.current)
+            return;
+        warned.current = true;
+        console.warn(exports.UNNAMED_DRAWER_WARNING);
+    }, [isUnnamed]);
+};
+function DialogContent({ label, labelledBy, ...props }) {
+    return ((0, jsx_runtime_1.jsx)(dialogNaming_1.DialogNaming, { label: label, labelledBy: labelledBy, children: (0, jsx_runtime_1.jsx)(react_2.DrawerContent, { ...props }) }));
+}
+/** Slide-in dialog; content must sit in DrawerHeader, DrawerBody or DrawerFooter slots. */
+function Drawer({ isOpen, onClose, placement = "right", size = "xl", id, variant, vaiant, initialFocusRef, finalFocusRef, closeOnOverlayClick, closeOnEsc, contentProps, hideCloseButton, portalChildren, children, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }) {
+    var _a, _b, _c;
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
-    const isReactElement = (child) => {
-        return child !== null && typeof child === "object" && "type" in child;
-    };
-    const header = react_1.default.Children.toArray(children).find((child) => isReactElement(child) && child.type === exports.DrawerHeader);
-    const body = react_1.default.Children.toArray(children).find((child) => isReactElement(child) && child.type === exports.DrawerBody);
-    const footer = react_1.default.Children.toArray(children).find((child) => isReactElement(child) && child.type === exports.DrawerFooter);
-    return ((0, jsx_runtime_1.jsxs)(react_2.Drawer, { isOpen: isOpen, placement: placement, onClose: onClose, size: size, variant: variant, id: id, children: [(0, jsx_runtime_1.jsx)(react_2.DrawerOverlay, {}), (0, jsx_runtime_1.jsxs)(react_2.DrawerContent, { bg: colors.background[50], children: [(0, jsx_runtime_1.jsx)(react_2.DrawerCloseButton, {}), header && ((0, jsx_runtime_1.jsx)(react_2.DrawerHeader, { borderBottomWidth: "1px", children: header })), (0, jsx_runtime_1.jsx)(react_2.DrawerBody, { children: body && body }), footer && (0, jsx_runtime_1.jsx)(react_2.DrawerFooter, { borderTopWidth: "1px", children: footer })] })] }));
+    const headerSlot = (0, findSlot_1.findSlot)(children, exports.DrawerHeader);
+    const bodySlot = (0, findSlot_1.findSlot)(children, exports.DrawerBody);
+    const footerSlot = (0, findSlot_1.findSlot)(children, exports.DrawerFooter);
+    (0, warnDroppedSlotChildren_1.warnDroppedSlotChildren)("Drawer", children, [exports.DrawerHeader, exports.DrawerBody, exports.DrawerFooter]);
+    useUnnamedWarning(isOpen &&
+        !headerSlot &&
+        !(ariaLabel === null || ariaLabel === void 0 ? void 0 : ariaLabel.trim()) &&
+        !(ariaLabelledBy === null || ariaLabelledBy === void 0 ? void 0 : ariaLabelledBy.trim()) &&
+        !((_a = contentProps === null || contentProps === void 0 ? void 0 : contentProps["aria-label"]) === null || _a === void 0 ? void 0 : _a.trim()));
+    return ((0, jsx_runtime_1.jsxs)(react_2.Drawer, { isOpen: isOpen, placement: placement, onClose: onClose, size: size, variant: (_b = variant !== null && variant !== void 0 ? variant : vaiant) !== null && _b !== void 0 ? _b : "solid", id: id, initialFocusRef: initialFocusRef, finalFocusRef: finalFocusRef, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, children: [(0, jsx_runtime_1.jsx)(react_2.DrawerOverlay, {}), (0, jsx_runtime_1.jsxs)(DialogContent, { ...contentProps, label: ariaLabel, labelledBy: ariaLabelledBy, children: [!hideCloseButton && (0, jsx_runtime_1.jsx)(react_2.DrawerCloseButton, {}), headerSlot && ((0, jsx_runtime_1.jsx)(react_2.DrawerHeader, { borderBottomWidth: "1px", borderColor: (0, surfaceRaised_1.raisedRule)(colors), ...headerSlot.props, children: headerSlot })), (0, jsx_runtime_1.jsx)(react_2.DrawerBody, { ...((_c = bodySlot === null || bodySlot === void 0 ? void 0 : bodySlot.props) !== null && _c !== void 0 ? _c : {}), children: bodySlot }), footerSlot && ((0, jsx_runtime_1.jsx)(react_2.DrawerFooter, { borderTopWidth: "1px", borderColor: (0, surfaceRaised_1.raisedRule)(colors), ...footerSlot.props, children: footerSlot })), portalChildren] })] }));
 }

package/dist/Components/Drawer/DrawerProps.d.ts

@@ -1,7 +1,27 @@
-import { DrawerProps as ChakraDrawerProps } from "@chakra-ui/react";
-export type DrawerProps = Pick<ChakraDrawerProps, "isOpen" | "onClose" | "placement" | "size" | "id" | "variant"> & {
+import { DrawerProps as ChakraDrawerProps, DrawerContentProps, ModalHeaderProps, ModalBodyProps, ModalFooterProps } from "@chakra-ui/react";
+/** Only DrawerHeader/Body/Footer children render, matched by type through nested Fragments; any other child is dropped (dev console.warn) — use `portalChildren`. */
+export type DrawerProps = Pick<ChakraDrawerProps, "isOpen" | "onClose" | "placement" | "size" | "id" | "variant" | "initialFocusRef" | "finalFocusRef" | "closeOnOverlayClick" | "closeOnEsc"> & {
+    /** Defaults to "xl". */
     size?: "xs" | "sm" | "md" | "lg" | "xl" | "full";
+    /** Defaults to "right". */
     placement?: "top" | "right" | "bottom" | "left";
+    /** @deprecated Typo of `variant`, kept as an alias; `variant` wins if both are set. */
     vaiant?: "solid" | "outline" | "ghost" | "link";
     children?: React.ReactNode;
+    /** Spread onto DrawerContent, e.g. to set width or padding. */
+    contentProps?: DrawerContentProps;
+    /** Drops the built-in close button, for a drawer dismissed only by its own footer action. */
+    hideCloseButton?: boolean;
+    /** Rendered inside the drawer's dialog after the slots (so live regions stay announced); nested dialogs portal out and keep focus here. Unmounts with the drawer. */
+    portalChildren?: React.ReactNode;
+    /** Names the dialog instead of the whole header, for a header that holds fields or buttons. */
+    "aria-label"?: string;
+    /** Id of the element that names the dialog, e.g. a heading inside the header; wins over `aria-label`. */
+    "aria-labelledby"?: string;
 };
+/** Chakra style props (padding, borderBottom, gap, sx, ...) spread onto the rendered DrawerHeader; omit to keep theme defaults. Chakra's Drawer reuses Modal's header part internally. */
+export type DrawerHeaderSlotProps = ModalHeaderProps;
+/** Chakra style props (padding, gap, sx, ...) spread onto the rendered DrawerBody; omit to keep theme defaults. */
+export type DrawerBodySlotProps = ModalBodyProps;
+/** Chakra style props (padding, borderTop, gap, sx, ...) spread onto the rendered DrawerFooter; omit to keep theme defaults. */
+export type DrawerFooterSlotProps = ModalFooterProps;

package/dist/Components/Dropdown/DropDown.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { DropdownProps } from "./DropdownProps";
+/** Menu-button that triggers labelled actions — nothing is "selected"/persisted; for picking a value from a list, use `Select`. */
 declare const Dropdown: React.ForwardRefExoticComponent<DropdownProps & React.RefAttributes<HTMLDivElement>>;
 export default Dropdown;

package/dist/Components/Dropdown/DropDown.js

@@ -5,26 +5,46 @@ const react_1 = require("react");
 const react_2 = require("@chakra-ui/react");
 const framer_motion_1 = require("framer-motion");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const surfaceRaised_1 = require("../../Theme/tokens/builders/surfaceRaised");
 const scrollbar_1 = require("../../Theme/tokens/builders/scrollbar");
+const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
+const optionRowInk_1 = require("../Select/optionRowInk");
+const useExclusiveOverlay_1 = require("../../Hooks/useExclusiveOverlay");
 const lucide_react_1 = require("lucide-react");
 const rafThrottle_1 = require("../../Utils/rafThrottle");
+const controlSizes_1 = require("../../Theme/tokens/primitives/controlSizes");
+const optionRowSizes_1 = require("../../Theme/tokens/primitives/optionRowSizes");
+const motion_1 = require("../../Theme/tokens/primitives/motion");
+const borderWidths_1 = require("../../Theme/tokens/primitives/borderWidths");
+const motion_2 = require("../../Theme/chakra/motion");
+const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
+const activationKey_1 = require("../Common/activationKey");
+const useOutsideMouseDown_1 = require("../../Hooks/useOutsideMouseDown");
 const MotionBox = (0, framer_motion_1.motion)((0, react_1.forwardRef)((props, ref) => ((0, jsx_runtime_1.jsx)(react_2.Box, { ref: ref, ...props }))));
-// Size scale (mirrors the Button sizes). `btn` is the Chakra Button size.
 const SIZE_MAP = {
-    xs: { btn: "xs", fontSize: "0.75rem", py: 1, px: 2.5, img: "1rem", chevron: 13, minW: "8rem", gap: 1.5 },
-    sm: { btn: "sm", fontSize: "0.8125rem", py: 1.5, px: 3, img: "1.05rem", chevron: 14, minW: "9rem", gap: 2 },
-    md: { btn: "md", fontSize: "0.875rem", py: 2, px: 3, img: "1.15rem", chevron: 16, minW: "11rem", gap: 2 },
-    lg: { btn: "lg", fontSize: "0.9375rem", py: 2.5, px: 3.5, img: "1.25rem", chevron: 18, minW: "12rem", gap: 2.5 },
-    xl: { btn: "lg", fontSize: "1.0625rem", py: 3, px: 4, img: "1.4rem", chevron: 20, minW: "13rem", gap: 3 },
+    xs: { btn: "xs", img: "1rem", chevron: controlSizes_1.BUTTON_SIZES.xs.iconSize, minW: "8rem", gap: 1.5, rowSize: "xs" },
+    sm: { btn: "sm", img: "1rem", chevron: controlSizes_1.BUTTON_SIZES.sm.iconSize, minW: "9rem", gap: 2, rowSize: "sm" },
+    md: { btn: "md", img: "1.125rem", chevron: controlSizes_1.BUTTON_SIZES.md.iconSize, minW: "11rem", gap: 2, rowSize: "md" },
+    lg: { btn: "lg", img: "1.25rem", chevron: controlSizes_1.BUTTON_SIZES.lg.iconSize, minW: "12rem", gap: 2.5, rowSize: "lg" },
+    xl: { btn: "lg", img: "1.4rem", chevron: 20, minW: "13rem", gap: 3, rowSize: "lg" },
 };
+const TRIGGER_TRANSITION = (0, motion_1.transitionFor)(["background-color", "border-color", "color", "box-shadow"]);
+const ROW_TRANSITION = (0, motion_1.transitionFor)(["background-color", "color"]);
+const CHEVRON_TRANSITION = (0, motion_1.transitionFor)(["transform"], "base");
+const isTypeaheadKey = (e) => e.key.length === 1 && e.key !== " " && !e.ctrlKey && !e.metaKey && !e.altKey;
+/** Menu-button that triggers labelled actions — nothing is "selected"/persisted; for picking a value from a list, use `Select`. */
 const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, options, handleOptionSelect, dropdownType = "button", text, DropdownIcon, isVisibleIconShow = true, buttonProps, headStyle, ListStyle, ItemStyle, LabelStyle, ImageStyle, size, optionsSize, divider = false, ariaLabel, }, ref) => {
-    var _a, _b;
+    var _a;
     const theme = (0, useCustomTheme_1.useCustomTheme)();
-    const { isOpen, onOpen, onToggle, onClose } = (0, react_2.useDisclosure)();
+    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.listRowBackgrounds)(theme.colors), [theme.colors]);
+    const { isOpen, onOpen, onClose } = (0, react_2.useDisclosure)();
+    const requestExclusiveOpen = (0, useExclusiveOverlay_1.useExclusiveOverlay)(isOpen, onClose);
     const dropdownRef = (0, react_1.useRef)(null);
     const menuRef = (0, react_1.useRef)(null);
     const [menuPos, setMenuPos] = (0, react_1.useState)({ top: 0, left: 0, width: 0 });
-    const s = (_b = SIZE_MAP[(_a = size !== null && size !== void 0 ? size : optionsSize) !== null && _a !== void 0 ? _a : "md"]) !== null && _b !== void 0 ? _b : SIZE_MAP.md;
+    const s = SIZE_MAP[(_a = size !== null && size !== void 0 ? size : optionsSize) !== null && _a !== void 0 ? _a : "sm"];
+    const rowSpec = (0, optionRowSizes_1.optionRowSpec)(s.rowSize);
+    const prefersReducedMotion = (0, framer_motion_1.useReducedMotion)();
     const menuId = (0, react_1.useId)();
     // Roving-tabindex keyboard nav for the menu (ARIA APG menu-button pattern):
     // real DOM focus moves through the items, so no aria-activedescendant is needed.
@@ -42,14 +62,22 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
     const openAndFocus = (index) => {
         var _a;
         if (isOpen) {
-            // Already open (trigger still holds focus, e.g. after Enter/Space) — the
-            // portal is already mounted, so focus directly; no need to wait a frame,
-            // and the effect below only reacts to isOpen *changing* anyway.
+            // NOTE: already open — portal is already mounted, so focus directly, no frame wait needed.
             setActiveIndex(index);
             (_a = itemRefs.current[index]) === null || _a === void 0 ? void 0 : _a.focus();
         }
         else {
             pendingFocusIndex.current = index;
+            requestExclusiveOpen();
+            onOpen();
+        }
+    };
+    const handleToggle = () => {
+        if (isOpen) {
+            onClose();
+        }
+        else {
+            requestExclusiveOpen();
             onOpen();
         }
     };
@@ -59,9 +87,7 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
             pendingFocusIndex.current = null;
             if (idx !== null) {
                 setActiveIndex(idx);
-                // Chakra's <Portal> mounts its children a tick after this effect runs
-                // (it resolves its target node via its own effect first), so the menu
-                // item ref isn't attached yet here — a frame gets us past that.
+                // NOTE: Chakra's Portal mounts children a tick late, so the item ref isn't attached yet — a frame gets past that.
                 requestAnimationFrame(() => { var _a; return (_a = itemRefs.current[idx]) === null || _a === void 0 ? void 0 : _a.focus(); });
             }
         }
@@ -86,17 +112,14 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
             e.preventDefault();
             onClose();
         }
-        else if (e.key === "Enter" || e.key === " ") {
-            // Explicit rather than relying on native button activation: the text
-            // trigger is a styled Flex (no default action to rely on), and jsdom's
-            // `fireEvent` does not simulate a real browser's Enter/Space-activates-
-            // button default action either.
+        else if ((0, activationKey_1.isActivationKey)(e)) {
+            // NOTE: explicit — the trigger is a styled Flex with no native button activation to rely on.
             e.preventDefault();
-            onToggle();
+            handleToggle();
         }
     };
     const handleMenuKeyDown = (e) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         if (options.length === 0)
             return;
         if (e.key === "ArrowDown" || e.key === "ArrowUp") {
@@ -125,17 +148,24 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
         else if (e.key === "Tab") {
             onClose();
         }
+        else if (isTypeaheadKey(e)) {
+            const char = e.key.toLowerCase();
+            const order = options.map((_, i) => (activeIndex + 1 + i) % options.length);
+            const match = order.find((i) => options[i].label.toLowerCase().startsWith(char));
+            if (match !== undefined) {
+                setActiveIndex(match);
+                (_d = itemRefs.current[match]) === null || _d === void 0 ? void 0 : _d.focus();
+            }
+        }
     };
     const handleItemKeyDown = (e, optionId, optionLabel) => {
-        if (e.key === "Enter" || e.key === " ") {
+        if ((0, activationKey_1.isActivationKey)(e)) {
             e.preventDefault();
             handleListItemClick(optionId, optionLabel);
             focusTrigger();
         }
     };
-    // The menu is portaled to <body> (so it sits above everything). Anchor it to
-    // the trigger, then clamp to the viewport so it never overflows off-screen
-    // (e.g. when the trigger sits near the right or bottom edge).
+    // NOTE: menu is portaled to body — anchor to the trigger, then clamp to viewport so it never overflows.
     const updateMenuPos = (0, react_1.useCallback)(() => {
         var _a, _b;
         if (!dropdownRef.current)
@@ -180,22 +210,7 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
             window.removeEventListener("resize", onReposition);
         };
     }, [isOpen, updateMenuPos]);
-    (0, react_1.useEffect)(() => {
-        const handleClickOutside = (event) => {
-            var _a, _b;
-            const target = event.target;
-            // Ignore clicks on the trigger or inside the (portaled) menu.
-            if ((_a = dropdownRef.current) === null || _a === void 0 ? void 0 : _a.contains(target))
-                return;
-            if ((_b = menuRef.current) === null || _b === void 0 ? void 0 : _b.contains(target))
-                return;
-            onClose();
-        };
-        document.addEventListener("mousedown", handleClickOutside);
-        return () => {
-            document.removeEventListener("mousedown", handleClickOutside);
-        };
-    }, [onClose]);
+    (0, useOutsideMouseDown_1.useOutsideMouseDown)([dropdownRef, menuRef], () => onClose(), { enabled: isOpen });
     const setMenuRef = (node) => {
         menuRef.current = node;
         if (typeof ref === "function")
@@ -206,32 +221,32 @@ const Dropdown = (0, react_1.forwardRef)(({ dropDownButtonStyle, ButtonText, opt
         if (node)
             updateMenuPos();
     };
-    const Chevron = isVisibleIconShow ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", transition: "transform 0.2s ease", transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevron }) })) : undefined;
+    const Chevron = isVisibleIconShow ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", transition: CHEVRON_TRANSITION, transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", sx: (0, motion_2.reducedMotionSx)(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevron }) })) : undefined;
     const dropDownToggleOption = () => {
-        const ButtonToggle = ((0, jsx_runtime_1.jsx)(react_2.Button, { ref: buttonTriggerRef, onClick: onToggle, onKeyDown: handleTriggerKeyDown, size: s.btn, colorScheme: "primary", borderRadius: "lg", fontWeight: 600, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": menuId, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (ButtonText ? undefined : "Open menu"), rightIcon: Chevron, sx: { transition: "all 0.15s ease", ...(dropDownButtonStyle) }, ...buttonProps, children: (0, jsx_runtime_1.jsxs)(react_2.Box, { as: "span", display: "inline-flex", alignItems: "center", gap: DropdownIcon && ButtonText ? s.gap : 0, children: [DropdownIcon, ButtonText] }) }));
-        const TextToggle = ((0, jsx_runtime_1.jsxs)(react_2.Flex, { ref: textTriggerRef, onClick: onToggle, onKeyDown: handleTriggerKeyDown, align: "center", gap: 1.5, cursor: "pointer", fontSize: s.fontSize, fontWeight: 500, color: theme.colors.text[700], transition: "color 0.15s ease", _hover: { color: theme.colors.accentText }, style: dropDownButtonStyle, role: "button", tabIndex: 0, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": menuId, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (text ? undefined : "Open menu"), children: [DropdownIcon, text, Chevron] }));
+        const ButtonToggle = ((0, jsx_runtime_1.jsx)(react_2.Button, { ref: buttonTriggerRef, onClick: handleToggle, onKeyDown: handleTriggerKeyDown, size: s.btn, colorScheme: "primary", borderRadius: "lg", fontWeight: 600, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": menuId, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (ButtonText ? undefined : "Open menu"), rightIcon: Chevron, sx: { transition: TRIGGER_TRANSITION, ...(0, motion_2.reducedMotionSx)(), ...dropDownButtonStyle }, ...buttonProps, children: (0, jsx_runtime_1.jsxs)(react_2.Box, { as: "span", display: "inline-flex", alignItems: "center", gap: DropdownIcon && ButtonText ? s.gap : 0, children: [DropdownIcon, ButtonText] }) }));
+        const TextToggle = ((0, jsx_runtime_1.jsxs)(react_2.Flex, { ref: textTriggerRef, onClick: handleToggle, onKeyDown: handleTriggerKeyDown, align: "center", gap: 1.5, cursor: "pointer", fontSize: rowSpec.fontSize, fontWeight: 500, color: theme.colors.text[700], borderRadius: "md", transition: ROW_TRANSITION, _hover: { color: theme.colors.accentText }, sx: { ...(0, focusRing_styles_1.focusVisibleStyles)(theme.colors), ...(0, motion_2.reducedMotionSx)() }, style: dropDownButtonStyle, role: "button", tabIndex: 0, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": menuId, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (text ? undefined : "Open menu"), children: [DropdownIcon, text, Chevron] }));
         return dropdownType === "button" ? ButtonToggle : TextToggle;
     };
     const DropdownContentRender = () => {
-        var _a;
-        return ((0, jsx_runtime_1.jsx)(react_2.List, { id: menuId, role: "menu", onKeyDown: handleMenuKeyDown, bg: theme.colors.background[50], border: `0.063rem solid ${theme.colors.boxborder[200]}`, borderRadius: "xl", boxShadow: (_a = theme.shadows) === null || _a === void 0 ? void 0 : _a.lg, py: 1.5, mt: "0.375rem", minWidth: s.minW, maxH: "18rem", overflowY: "auto", overflowX: "hidden", sx: (0, scrollbar_1.scrollbarStyles)(theme.colors, "overlay"), style: ListStyle, children: options.map((option, index) => ((0, jsx_runtime_1.jsxs)(react_2.ListItem, { ref: (node) => {
+        const hoverTint = rowBackgrounds.active;
+        return ((0, jsx_runtime_1.jsx)(react_2.List, { id: menuId, role: "menu", onKeyDown: handleMenuKeyDown, bg: theme.colors.surfaceRaised, border: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${theme.colors.boxborder[200]}`, borderRadius: "xl", boxShadow: theme.shadows.lg, py: 1.5, mt: "0.375rem", minWidth: s.minW, maxH: "18rem", overflowY: "auto", overflowX: "hidden", sx: (0, scrollbar_1.scrollbarStyles)(theme.colors, "overlay"), style: ListStyle, children: options.map((option, index) => ((0, jsx_runtime_1.jsxs)(react_2.ListItem, { ref: (node) => {
                     itemRefs.current[index] = node;
                 }, role: "menuitem", tabIndex: index === activeIndex ? 0 : -1, onClick: () => {
                     handleListItemClick(option.id, option.label);
                     focusTrigger();
-                }, onKeyDown: (e) => handleItemKeyDown(e, option.id, option.label), mx: 1.5, px: s.px, py: s.py, borderRadius: "md", display: "flex", alignItems: "center", gap: 2, cursor: "pointer", color: theme.colors.text[700], transition: "background 0.12s ease, color 0.12s ease", _hover: {
-                    bg: theme.colors.primary.opacity[8],
-                    color: theme.colors.accentText,
-                }, _focus: {
-                    bg: theme.colors.primary.opacity[8],
-                    color: theme.colors.accentText,
+                }, onKeyDown: (e) => handleItemKeyDown(e, option.id, option.label), mx: rowSpec.mx, px: rowSpec.px, py: rowSpec.py, minH: rowSpec.minH, borderRadius: optionRowSizes_1.OPTION_ROW_RADIUS, display: "flex", alignItems: "center", gap: rowSpec.gap, fontSize: rowSpec.fontSize, cursor: "pointer", color: (0, optionRowInk_1.optionRowInk)(theme.colors, false), transition: ROW_TRANSITION, _hover: { bg: hoverTint }, _focus: { bg: hoverTint, outline: "none" }, _focusVisible: {
+                    bg: hoverTint,
+                    boxShadow: (0, focusRing_styles_1.insetFocusRingShadow)(theme.colors),
                 }, borderBottom: divider
-                    ? `0.063rem solid ${theme.colors.boxborder[200]}`
-                    : undefined, sx: { "&:last-child": { borderBottom: "none" } }, style: ItemStyle, fontWeight: 500, children: [(option === null || option === void 0 ? void 0 : option.image) && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: option.image, boxSize: s.img, flexShrink: 0, color: theme.colors.textMuted, style: ImageStyle })), (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", fontSize: s.fontSize, isTruncated: true, 
-                        // fontWeight={400}
-                        style: LabelStyle, children: option.label })] }, option.id))) }));
+                    ? `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(theme.colors)}`
+                    : undefined, sx: { "&:last-child": { borderBottom: "none" }, ...(0, motion_2.reducedMotionSx)() }, style: ItemStyle, fontWeight: 500, children: [option.image && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: option.image, boxSize: s.img, flexShrink: 0, color: theme.colors.textMuted, style: ImageStyle })), (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", fontSize: rowSpec.fontSize, isTruncated: true, style: LabelStyle, children: option.label })] }, option.id))) }));
     };
-    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { ref: dropdownRef, position: "relative", display: "inline-block", children: [dropDownToggleOption(), isOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsx)(MotionBox, { ref: setMenuRef, position: "fixed", top: `${menuPos.top}px`, left: `${menuPos.left}px`, minW: `${menuPos.width}px`, zIndex: 1500, initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, style: headStyle, children: DropdownContentRender() }) }))] }));
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { ref: dropdownRef, position: "relative", display: "inline-block", children: [dropDownToggleOption(), isOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsx)(MotionBox, { ref: setMenuRef, position: "fixed", zIndex: "popover", initial: prefersReducedMotion ? false : { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, style: {
+                        top: `${menuPos.top}px`,
+                        left: `${menuPos.left}px`,
+                        minWidth: `${menuPos.width}px`,
+                        ...headStyle,
+                    }, children: DropdownContentRender() }) }))] }));
 });
 Dropdown.displayName = "Dropdown";
 exports.default = Dropdown;

package/dist/Components/Dropdown/DropdownProps.d.ts

@@ -1,23 +1,39 @@
 import { ButtonProps } from "@chakra-ui/react";
+/** Action-menu Dropdown (role="menu"): rows fire an action, nothing is "selected" or persisted. For picking a value use `Select`. */
 export type DropdownProps = {
+    /** Rendered only for the default dropdownType="button" — has no effect under dropdownType="text" (use `text` there). */
     ButtonText?: string;
+    /** Menu rows in order; `id` and `label` are passed to `handleOptionSelect`, and `image` adds a leading icon. */
     options: Option[];
+    /** Fires on click, Enter or Space; the menu closes and focus returns to the trigger. */
     handleOptionSelect: (id: string | number, label: string) => void;
+    /** "button" renders a filled primary button; "text" a plain-text trigger. Defaults to "button". */
     dropdownType?: "button" | "text";
+    /** Trigger label for dropdownType="text" only; ignored for "button" (use `ButtonText`). */
     text?: string;
+    /** Leading icon inside the trigger, before the label; works with both trigger types. */
     DropdownIcon?: JSX.Element;
+    /** Styles the trigger — merged into `sx` for "button", inline `style` for "text". */
     dropDownButtonStyle?: React.CSSProperties;
+    /** Shows the rotating chevron on the trigger. Defaults to true. */
     isVisibleIconShow?: boolean;
+    /** Spread last onto the "button" trigger, so it can override size/colorScheme; ignored for "text". */
     buttonProps?: ButtonProps;
+    /** Inline style on the portaled, fixed-position menu wrapper. */
     headStyle?: React.CSSProperties;
+    /** Inline style on the menu list (the bordered, scrolling panel). */
     ListStyle?: React.CSSProperties;
+    /** Inline style on every menu row. */
     ItemStyle?: React.CSSProperties;
+    /** Inline style on each row's label text. */
     LabelStyle?: React.CSSProperties;
+    /** Inline style on each row's `image` icon; ignored for options without one. */
     ImageStyle?: React.CSSProperties;
-    /** Overall size of the trigger + options (like Button sizes). */
+    /** Trigger on the button scale, menu rows on the option-row scale; defaults to `sm`. `xl` renders an `lg` trigger. */
     size?: "xs" | "sm" | "md" | "lg" | "xl";
     /** @deprecated Use `size` instead. Kept for backward compatibility. */
     optionsSize?: "sm" | "md" | "lg";
+    /** Draws a separator line between menu rows. */
     divider?: boolean;
     /** Accessible name for the trigger when it renders icon-only (no `ButtonText`/`text`). */
     ariaLabel?: string;
@@ -25,6 +41,7 @@ export type DropdownProps = {
 type Option = {
     id: string | number;
     label: string;
+    /** Icon component reference (e.g. `Star`), not a rendered element like `<Star />` — passed to Chakra's `as`. */
     image?: React.ElementType;
 };
 export {};

package/dist/Components/Editor/Editor.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { EditorProps } from "./EditorProps";
+/** Lazy-loaded Jodit wrapper — a `config.theme` or `config.popupRoot` you pass overrides this library's own dark-mode/popup fix; omit both keys. */
 declare const Editor: React.NamedExoticComponent<EditorProps>;
 export default Editor;

package/dist/Components/Editor/Editor.js

@@ -32,13 +32,27 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = __importStar(require("react"));
 const react_2 = require("@chakra-ui/react");
+const FieldMessage_1 = __importDefault(require("../Common/FieldMessage"));
+const ErrorMessage_1 = __importDefault(require("../Common/ErrorMessage"));
+const FormLabel_1 = require("../Common/FormLabel");
+const useFieldIds_1 = require("../Common/useFieldIds");
+const EditorFieldBar_1 = __importDefault(require("./EditorFieldBar"));
+const MakeDynamicDialog_1 = __importDefault(require("./MakeDynamicDialog"));
+const editorTokens_1 = require("./editorTokens");
+const editorTokenStyles_1 = require("./editorTokenStyles");
+const editorLabels_1 = require("./editorLabels");
+const useEditorBridge_1 = require("./useEditorBridge");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const accentText_1 = require("../../Theme/tokens/builders/accentText");
 const joditThemeVars_1 = require("./joditThemeVars");
+const joditAccessibility_1 = require("./joditAccessibility");
 // Loaded on render, not on import: jodit-react's browser bundle touches `self` at module
 // scope, which crashes any Node/SSR consumer importing this package's barrel.
 const JoditEditor = react_1.default.lazy(async () => {
@@ -46,8 +60,26 @@ const JoditEditor = react_1.default.lazy(async () => {
     const mod = (await Promise.resolve().then(() => __importStar(require("jodit-react"))));
     return { default: ((_a = mod.default) !== null && _a !== void 0 ? _a : mod) };
 });
-const Editor = react_1.default.memo(function Editor({ value, key, config, editorRef, className, onChange, onBlur, }) {
+/** Lazy-loaded Jodit wrapper — a `config.theme` or `config.popupRoot` you pass overrides this library's own dark-mode/popup fix; omit both keys. */
+const Editor = react_1.default.memo(function Editor({ value, key, config, editorRef, className, onChange, onBlur, label, isRequired, helperText, error, errorMessage, mergeFields, tokenSyntax = editorTokens_1.DEFAULT_TOKEN_SYNTAX, showMakeDynamic, toolbarButtons, onUnknownTokens, apiRef, onReady, labels, "data-testid": testId, }) {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
+    const text = (0, react_1.useMemo)(() => (0, editorLabels_1.resolveEditorLabels)(labels), [labels]);
+    const { joditValue, attachEditor, api, instance, unknown } = (0, useEditorBridge_1.useEditorBridge)({
+        value,
+        onChange,
+        onBlur,
+        mergeFields,
+        syntax: tokenSyntax,
+        chipLabel: text.fieldChip,
+        apiRef,
+        onReady,
+        onUnknownTokens,
+    });
+    const hasFields = mergeFields !== undefined;
+    const options = (0, react_1.useMemo)(() => (0, editorTokens_1.fieldOptions)(mergeFields !== null && mergeFields !== void 0 ? mergeFields : [], tokenSyntax), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(mergeFields), tokenSyntax.open, tokenSyntax.close]);
+    const [dynamicText, setDynamicText] = (0, react_1.useState)(null);
     // Jodit portals dialogs/toolbar-dropdown popups (search & replace, image/link properties,
     // font-size list, ...) to `document.body` by default (`Dialog.destination` /
     // `getPopupViewRoot`), outside this wrapper's DOM subtree — so the CSS custom properties
@@ -58,6 +90,10 @@ const Editor = react_1.default.memo(function Editor({ value, key, config, editor
     const stableConfig = (0, react_1.useMemo)(() => ({
         theme: (0, accentText_1.isDarkCanvas)(theme.colors.backgroundColor.main) ? "dark" : "default",
         popupRoot,
+        // Off by default, Jodit ships every toolbar button unreachable by keyboard.
+        allowTabNavigation: true,
+        // NOTE: Jodit's default -1 keeps the editing surface out of the Tab order.
+        tabIndex: 0,
         // `config` spread as `Record<string, unknown>`: mixing a literal `popupRoot` key with a
         // spread of the raw `DeepPartial<Config>` type (Jodit's huge recursive config type) blows
         // past TS's type-instantiation depth limit (TS2589) — the cast avoids that without
@@ -71,6 +107,35 @@ const Editor = react_1.default.memo(function Editor({ value, key, config, editor
     // feeds our actual active colors into those variables, scoped to this instance (see
     // `joditThemeVars.ts`).
     const themeVars = (0, react_1.useMemo)(() => (0, joditThemeVars_1.getJoditThemeVars)(theme.colors, (0, accentText_1.isDarkCanvas)(theme.colors.backgroundColor.main)), [theme]);
-    return ((0, jsx_runtime_1.jsx)(react_2.Box, { ref: setPopupRoot, sx: themeVars, children: (0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: null, children: (0, jsx_runtime_1.jsx)(JoditEditor, { config: stableConfig, value: value, ref: editorRef, className: className, onChange: onChange, onBlur: onBlur }, key) }) }));
+    // Jodit rebuilds its own toolbar DOM (resize, mode change), so re-run on every mutation.
+    (0, react_1.useEffect)(() => {
+        if (!popupRoot)
+            return;
+        (0, joditAccessibility_1.applyJoditAccessibilityFixes)(popupRoot);
+        const observer = new MutationObserver(() => (0, joditAccessibility_1.applyJoditAccessibilityFixes)(popupRoot));
+        observer.observe(popupRoot, { childList: true, subtree: true });
+        return () => observer.disconnect();
+    }, [popupRoot]);
+    const unknownActive = hasFields && unknown.length > 0 && !(error && errorMessage);
+    const ids = (0, useFieldIds_1.useFieldIds)(undefined, { error, errorMessage, helperText });
+    const describedBy = unknownActive ? ids.errorId : ids.describedBy;
+    const invalid = Boolean(error) || unknownActive;
+    const isReadOnly = Boolean(stableConfig === null || stableConfig === void 0 ? void 0 : stableConfig.readonly);
+    (0, react_1.useEffect)(() => {
+        if (!instance)
+            return;
+        const el = instance.editor;
+        const set = (name, val) => val === undefined ? el.removeAttribute(name) : el.setAttribute(name, val);
+        set("role", "textbox");
+        set("aria-multiline", "true");
+        set("aria-labelledby", label ? ids.labelId : undefined);
+        set("aria-label", label ? undefined : text.editor);
+        set("aria-describedby", describedBy);
+        set("aria-invalid", invalid ? "true" : undefined);
+        set("aria-required", isRequired ? "true" : undefined);
+        set("aria-readonly", isReadOnly ? "true" : undefined);
+    }, [instance, label, text.editor, ids.labelId, describedBy, invalid, isRequired, isReadOnly]);
+    const showFieldBar = hasFields || Boolean(toolbarButtons === null || toolbarButtons === void 0 ? void 0 : toolbarButtons.length);
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { "data-testid": testId, children: [label && ((0, jsx_runtime_1.jsxs)(react_2.Box, { as: "label", id: ids.labelId, display: "block", onClick: () => api.focus(), ...(0, FormLabel_1.fieldLabelStyles)(theme.colors), children: [label, isRequired && ((0, jsx_runtime_1.jsx)("span", { "aria-hidden": true, style: { color: theme.colors.semanticText.error, marginLeft: "0.125rem" }, children: "*" }))] })), showFieldBar && ((0, jsx_runtime_1.jsx)(EditorFieldBar_1.default, { options: options, labels: text, api: api, isDisabled: !instance || isReadOnly, showFieldMenu: hasFields, showMakeDynamic: hasFields && (showMakeDynamic !== null && showMakeDynamic !== void 0 ? showMakeDynamic : true), buttons: toolbarButtons !== null && toolbarButtons !== void 0 ? toolbarButtons : [], onMakeDynamic: () => setDynamicText(api.getSelectionText()) })), (0, jsx_runtime_1.jsx)(react_2.Box, { ref: setPopupRoot, sx: { ...themeVars, ...(0, editorTokenStyles_1.chipStyles)(theme.colors), ...(0, editorTokenStyles_1.frameFocusStyles)(theme.colors) }, children: (0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: null, children: popupRoot && ((0, jsx_runtime_1.jsx)(JoditEditor, { config: stableConfig, value: joditValue, ref: editorRef, editorRef: attachEditor, className: className }, key)) }) }), unknownActive ? ((0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { id: ids.errorId, errorMessage: text.unknownTokens(unknown.join(", ")) })) : ((0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })), hasFields && ((0, jsx_runtime_1.jsx)(MakeDynamicDialog_1.default, { selectedText: dynamicText, options: options, labels: text, countFor: api.countOccurrences, onReplace: api.replaceAll, onClose: () => setDynamicText(null) }))] }));
 });
 exports.default = Editor;

package/dist/Components/Editor/EditorFieldBar.d.ts

@@ -0,0 +1,15 @@
+import type { OptionProp } from "../Select/SelectProps";
+import type { EditorApi, EditorToolbarButton } from "./EditorProps";
+import type { ResolvedEditorLabels } from "./editorLabels";
+type EditorFieldBarProps = {
+    options: OptionProp[];
+    labels: ResolvedEditorLabels;
+    api: EditorApi;
+    isDisabled: boolean;
+    showFieldMenu: boolean;
+    showMakeDynamic: boolean;
+    buttons: EditorToolbarButton[];
+    onMakeDynamic: () => void;
+};
+export default function EditorFieldBar({ options, labels, api, isDisabled, showFieldMenu, showMakeDynamic, buttons, onMakeDynamic, }: EditorFieldBarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/Components/Editor/EditorFieldBar.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = EditorFieldBar;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("@chakra-ui/react");
+const lucide_react_1 = require("lucide-react");
+const Button_1 = __importDefault(require("../Button/Button"));
+const Select_1 = __importDefault(require("../Select/Select"));
+function EditorFieldBar({ options, labels, api, isDisabled, showFieldMenu, showMakeDynamic, buttons, onMakeDynamic, }) {
+    return ((0, jsx_runtime_1.jsxs)(react_1.Flex, { role: "toolbar", "aria-label": labels.toolbar, gap: 2, wrap: "wrap", align: "center", mb: 2, children: [showFieldMenu && ((0, jsx_runtime_1.jsx)(react_1.Box, { width: { base: "100%", sm: "16rem" }, children: (0, jsx_runtime_1.jsx)(Select_1.default, { native: false, "aria-label": labels.insertField, placeholder: labels.insertField, options: options, value: "", noOptionsMessage: labels.noFields, isDisabled: isDisabled, onChange: (option) => {
+                        if (!option)
+                            return;
+                        api.insertField(String(option.id));
+                        window.setTimeout(api.focus, 0);
+                    }, "data-testid": "editor-insert-field" }) })), showMakeDynamic && ((0, jsx_runtime_1.jsx)(Button_1.default, { variant: "outline", colorScheme: "gray", leftIcon: (0, jsx_runtime_1.jsx)(lucide_react_1.WandSparkles, { size: 16, "aria-hidden": true }), label: labels.makeDynamic, onClick: onMakeDynamic, isDisabled: isDisabled, "data-testid": "editor-make-dynamic" })), buttons.map((button) => ((0, jsx_runtime_1.jsx)(Button_1.default, { variant: "ghost", colorScheme: "gray", leftIcon: button.icon ? (0, jsx_runtime_1.jsx)(react_1.Icon, { as: button.icon, boxSize: 4, "aria-hidden": true }) : undefined, label: button.label, onClick: () => button.onClick(api), isDisabled: isDisabled || button.isDisabled, "data-testid": `editor-button-${button.id}` }, button.id)))] }));
+}