pixelize-design-library 2.4.2 → 3.0.0

package/dist/esm/Components/DatePicker/dayStates.js

@@ -0,0 +1,68 @@
+import { recessOn } from "../../Theme/tokens/builders/planeStep.js";
+// Ascending precedence — when a day carries several keys, a later one's visual overrides an earlier one's.
+export const DAY_STATE_KEYS = [
+    "weekly-off",
+    "holiday",
+    "optional-holiday",
+    "excluded",
+    "disabled",
+];
+// NOTE: token roles per THEME-CONTRACT.md, not raw rungs — e.g. holiday uses semanticText, never semantic[500].
+const VISUALS = {
+    "weekly-off": (colors) => ({
+        cellBg: recessOn(colors.backgroundColor.muted, colors.surfaceRaised),
+        color: colors.textMuted,
+    }),
+    holiday: (colors) => ({
+        color: colors.semanticText.info,
+        markerColor: colors.semanticText.info,
+    }),
+    "optional-holiday": (colors) => ({
+        color: colors.semanticText.warning,
+        markerColor: colors.semanticText.warning,
+        border: `1px dashed ${colors.semanticText.warning}`,
+    }),
+    excluded: (colors) => ({
+        color: colors.textMuted,
+        strikethrough: true,
+    }),
+    disabled: (colors) => ({
+        color: colors.disabled[500],
+        blocksSelection: true,
+    }),
+};
+export const isDayStateKey = (key) => DAY_STATE_KEYS.includes(key);
+/** Merges every recognised state in `DAY_STATE_KEYS` order, so precedence never depends on caller order. */
+export const resolveDayStateVisual = (states, colors) => {
+    const visual = {};
+    for (const key of DAY_STATE_KEYS) {
+        if (states.includes(key))
+            Object.assign(visual, VISUALS[key](colors));
+    }
+    return visual;
+};
+/** Base class on every day button once `dayStates` is supplied. Consumers may style off it. */
+export const DAY_CLASS = "pxl-calendar-day";
+const slug = (key) => key
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** `["Onam", "holiday"]` → `"pxl-calendar-day pxl-calendar-day--onam pxl-calendar-day--holiday"`. */
+export const dayStateClassName = (states) => [
+    DAY_CLASS,
+    ...states
+        .map(slug)
+        .filter(Boolean)
+        .map((key) => `${DAY_CLASS}--${key}`),
+].join(" ");
+/** Human phrasing for the accessible name — every key, styled or not, in the caller's own order. */
+export const describeDayStates = (states) => states
+    .map((state) => (isDayStateKey(state) ? state.replace(/-/g, " ") : state.trim()))
+    .filter(Boolean)
+    .join(", ");
+// The day's accessible name, date spelled out then states, so marking is heard, not only seen.
+export const dayAccessibleName = (formattedDate, states) => {
+    const described = describeDayStates(states);
+    return described ? `${formattedDate}, ${described}` : formattedDate;
+};

package/dist/esm/Components/DatePicker/pickerField.js

@@ -0,0 +1,24 @@
+import { fieldHoverBorder } from "../Common/fieldStyles.js";
+/** Canonical `isDisabled`/`placeholder` win over their deprecated aliases. */
+export const resolvePickerAliases = ({ isDisabled, disabled, placeholder, placeholderText }) => {
+    var _a;
+    return ({
+        isDisabled: (_a = isDisabled !== null && isDisabled !== void 0 ? isDisabled : disabled) !== null && _a !== void 0 ? _a : false,
+        placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : placeholderText,
+    });
+};
+/** A read-only field that opens a picker still gets the field's hover border. */
+export const readOnlyTriggerSx = (colors) => ({
+    _readOnly: { _hover: { borderColor: fieldHoverBorder(colors) } },
+});
+// NOTE: case matters in date-fns — MM is month, mm is minutes; lowercasing made dd/MM/yyyy a datetime.
+export const formatHasTime = (format) => /[Hh]|mm|ss/.test(format);
+export const inferPickerTypeFromFormat = (format) => {
+    const hasTime = formatHasTime(format);
+    const hasDate = /d/i.test(format) && /M/.test(format) && /y/i.test(format);
+    if (hasTime && hasDate)
+        return "datetime";
+    if (hasTime)
+        return "time";
+    return "date";
+};

package/dist/esm/Components/DatePicker/valueFormat.js

@@ -0,0 +1,15 @@
+import { format, parse, isValid } from "date-fns";
+const ISO_FORMATS = {
+    date: "yyyy-MM-dd",
+    time: "HH:mm",
+    datetime: "yyyy-MM-dd'T'HH:mm:ss",
+};
+export const isoFormatFor = (pickerType) => ISO_FORMATS[pickerType];
+// Local time, no offset — a malformed/empty string yields null rather than an Invalid Date.
+export const parseIsoValue = (value, pickerType) => {
+    if (!value)
+        return null;
+    const parsed = parse(value, isoFormatFor(pickerType), new Date());
+    return isValid(parsed) ? parsed : null;
+};
+export const formatIsoValue = (date, pickerType) => format(date, isoFormatFor(pickerType));

package/dist/esm/Components/DescriptionList/DescriptionList.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Flex, Grid, Text } from "@chakra-ui/react";
+import { useCustomTheme } from "../../Theme/useCustomTheme.js";
+import Skeletons from "../Skeletons/Skeletons.js";
+import CopyButton from "../CopyButton/CopyButton.js";
+const DEFAULT_COLUMNS = { base: 1, md: 2 };
+const toTemplateColumns = (columns) => Object.fromEntries(Object.entries(columns).map(([bp, count]) => [bp, `repeat(${count}, minmax(0, 1fr))`]));
+const isMissing = (value) => value === null || value === undefined || value === "";
+/** Label/value read grid: semantic dl/dt/dd, "stacked" (label above) or "inline" (label left, value right). */
+const DescriptionList = ({ items, columns = DEFAULT_COLUMNS, layout = "stacked", emptyValue = "—", isLoading = false, loadingRows = 6, ...rest }) => {
+    const { colors } = useCustomTheme();
+    const templateColumns = toTemplateColumns(columns);
+    if (isLoading) {
+        return (_jsx(Grid, { ...rest, role: "group", "aria-busy": "true", "aria-label": "Loading", templateColumns: templateColumns, columnGap: 5, rowGap: 4, children: Array.from({ length: loadingRows }, (_, index) => (_jsxs(Flex, { direction: "column", gap: 1.5, children: [_jsx(Skeletons, { type: "skeleton", height: 3, width: "40%" }), _jsx(Skeletons, { type: "skeleton", height: 4, width: "75%" })] }, index))) }));
+    }
+    return (_jsx(Grid, { ...rest, as: "dl", m: 0, templateColumns: templateColumns, columnGap: 5, rowGap: 4, children: items.map((item, index) => {
+            const displayValue = isMissing(item.value) ? emptyValue : item.value;
+            const canCopy = item.copyable && typeof item.value === "string" && item.value !== "";
+            const copyTooltip = typeof item.label === "string" ? `Copy ${item.label}` : "Copy";
+            const Value = (_jsxs(Flex, { as: "dd", m: 0, align: "center", gap: 1, minW: 0, children: [_jsx(Text, { fontSize: "sm", color: colors.text[800], textAlign: layout === "inline" ? "right" : "left", noOfLines: layout === "inline" ? 1 : undefined, overflowWrap: layout === "inline" ? undefined : "anywhere", children: displayValue }), canCopy && _jsx(CopyButton, { value: item.value, size: "xs", tooltip: copyTooltip })] }));
+            const itemProps = layout === "inline"
+                ? { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 3 }
+                : {};
+            return (_jsxs(Box, { minW: 0, gridColumn: item.span ? `span ${item.span}` : undefined, ...itemProps, children: [_jsx(Text, { as: "dt", fontSize: "xs", color: colors.textMuted, mb: layout === "inline" ? 0 : 0.5, children: item.label }), Value] }, index));
+        }) }));
+};
+export default DescriptionList;

package/dist/esm/Components/DescriptionList/DescriptionListProps.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/Components/DetailSections/DetailSections.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Flex, Text } from "@chakra-ui/react";
+import { Check, Dot } from "lucide-react";
+import Accordion from "../Accordion/Accordion.js";
+import Tabs from "../Tabs/Tabs.js";
+import SpecTable from "../SpecTable/SpecTable.js";
+import { useCustomTheme } from "../../Theme/useCustomTheme.js";
+import { transitionFor } from "../../Theme/tokens/primitives/motion.js";
+import { tonalHover } from "../CheckoutKit/tonalHover.js";
+const DEFAULT_LABELS = {
+    description: "Description",
+    highlights: "Highlights",
+    specifications: "Specifications",
+    care: "Care",
+    shipping: "Shipping & returns",
+    legal: "Legal & manufacturer info",
+    netQuantity: "Net quantity",
+    manufacturer: "Manufactured / packed by",
+    originCountry: "Country of origin",
+    mrp: "MRP",
+    customerCare: "Customer care",
+    mrpIncludesTaxes: "Maximum retail price, inclusive of all taxes",
+};
+const hasContent = (node) => node !== undefined && node !== null && node !== false && node !== "";
+const legalRows = (legal, text) => {
+    const fields = [legal.netQuantity, legal.manufacturer, legal.originCountry, legal.mrpNote, legal.customerCare];
+    if (!fields.some(Boolean))
+        return [];
+    const rows = [
+        [text.netQuantity, legal.netQuantity],
+        [text.manufacturer, legal.manufacturer],
+        [text.originCountry, legal.originCountry],
+        [text.mrp, legal.mrpNote || text.mrpIncludesTaxes],
+        [text.customerCare, legal.customerCare],
+    ];
+    return rows.flatMap(([label, value]) => (value ? [{ label, value }] : []));
+};
+const BulletList = ({ items, icon }) => {
+    const { colors } = useCustomTheme();
+    return (_jsx(Flex, { as: "ul", direction: "column", gap: 2, m: 0, p: 0, listStyleType: "none", children: items.map((item, i) => (_jsxs(Flex, { as: "li", align: "flex-start", gap: 2, color: colors.text[800], children: [_jsx(Box, { as: "span", "aria-hidden": true, display: "inline-flex", flexShrink: 0, mt: "0.1875rem", color: colors.accentText, children: icon === "check" ? _jsx(Check, { size: 16, strokeWidth: 2.25 }) : _jsx(Dot, { size: 16, strokeWidth: 6 }) }), _jsx(Box, { as: "span", minW: 0, overflowWrap: "anywhere", children: item })] }, `${item}-${i}`))) }));
+};
+/** Long-form product information: description, highlights, specifications, care, shipping and returns, and legal-metrology info. */
+const DetailSections = ({ description, highlights, specs, care, shipping, legal, sections, layout = "accordion", defaultOpenIds, specCollapsedCount, labels, "data-testid": testId, }) => {
+    const { colors } = useCustomTheme();
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const body = { fontSize: "sm", lineHeight: 1.7, color: colors.text[800] };
+    const careList = typeof care === "string" ? null : care;
+    const legalSpecs = legal ? legalRows(legal, text) : [];
+    const builtIn = [
+        description ? { id: "description", title: text.description, content: _jsx(Text, { ...body, children: description }) } : null,
+        (highlights === null || highlights === void 0 ? void 0 : highlights.length) ? { id: "highlights", title: text.highlights, content: _jsx(BulletList, { items: highlights, icon: "check" }) } : null,
+        (specs === null || specs === void 0 ? void 0 : specs.length)
+            ? { id: "specs", title: text.specifications, content: _jsx(SpecTable, { items: specs, collapsedCount: specCollapsedCount }) }
+            : null,
+        (care === null || care === void 0 ? void 0 : care.length)
+            ? {
+                id: "care",
+                title: text.care,
+                content: careList ? _jsx(BulletList, { items: careList, icon: "dot" }) : _jsx(Text, { ...body, children: care }),
+            }
+            : null,
+        hasContent(shipping) ? { id: "shipping", title: text.shipping, content: _jsx(Box, { ...body, children: shipping }) } : null,
+        legalSpecs.length ? { id: "legal", title: text.legal, content: _jsx(SpecTable, { items: legalSpecs }) } : null,
+    ];
+    const BUILT_IN_IDS = ["description", "highlights", "specs", "care", "shipping", "legal"];
+    const overrides = new Map((sections !== null && sections !== void 0 ? sections : []).map((s) => [s.id, s]));
+    const merged = [
+        ...builtIn.flatMap((section, i) => {
+            const replacement = overrides.get(BUILT_IN_IDS[i]);
+            const picked = replacement !== null && replacement !== void 0 ? replacement : section;
+            return picked ? [picked] : [];
+        }),
+        ...(sections !== null && sections !== void 0 ? sections : []).filter((s) => !BUILT_IN_IDS.includes(s.id)),
+    ];
+    if (merged.length === 0)
+        return null;
+    if (layout === "tabs") {
+        return (_jsx(Box, { "data-testid": testId, children: _jsx(Tabs, { variant: "line", "aria-label": "Product details", items: merged.map((s) => ({
+                    id: s.id,
+                    label: s.title,
+                    content: (_jsx(Box, { id: `detail-section-${s.id}`, "data-section-id": s.id, pt: 4, children: s.content })),
+                })) }) }));
+    }
+    const openIds = defaultOpenIds !== null && defaultOpenIds !== void 0 ? defaultOpenIds : [merged[0].id];
+    const defaultIndex = merged.flatMap((s, i) => (openIds.includes(s.id) ? [i] : []));
+    return (_jsx(Box, { "data-testid": testId, children: _jsx(Accordion, { allowMultiple: true, defaultIndex: defaultIndex, items: merged.map((s) => ({
+                header: (_jsx(Text, { as: "span", color: colors.header[900], children: s.title })),
+                content: s.content,
+                itemProps: {
+                    id: `detail-section-${s.id}`,
+                    "data-section-id": s.id,
+                    border: "none",
+                    borderRadius: "xl",
+                    bg: colors.background[100],
+                    mb: 2,
+                },
+                buttonProps: {
+                    px: 4,
+                    py: 3.5,
+                    fontSize: "md",
+                    bg: "transparent",
+                    transition: transitionFor(["background-color"]),
+                    _hover: { bg: tonalHover(colors) },
+                },
+                panelProps: { px: 4, pt: 1, pb: 5, color: colors.text[800] },
+            })) }) }));
+};
+export default DetailSections;

package/dist/esm/Components/DetailSections/DetailSectionsProps.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/Components/Divider/Divider.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Divider as ChakraDivider } from "@chakra-ui/react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
-const VeritcalDivider = () => {
+/** Always vertical, fixed size/color, zero props; not interchangeable with Primitives' Divider. */
+const VerticalDivider = () => {
     const { colors } = useCustomTheme();
     return (_jsx(ChakraDivider, { orientation: "vertical", height: 5, borderWidth: 1.2, borderColor: colors.boxborder[500] }));
 };
-export default VeritcalDivider;
+export default VerticalDivider;

package/dist/esm/Components/Drawer/Drawer.js

@@ -1,7 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React from "react";
+import { useEffect, useRef } from "react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
+import { raisedRule } from "../../Theme/tokens/builders/surfaceRaised.js";
+import { DialogNaming } from "../Modal/dialogNaming.js";
+import { warnDroppedSlotChildren } from "../Modal/warnDroppedSlotChildren.js";
 import { Drawer as ChakraDrawer, DrawerBody as ChakraDrawerBody, DrawerFooter as ChakraDrawerFooter, DrawerHeader as ChakraDrawerHeader, DrawerOverlay, DrawerContent, DrawerCloseButton, } from "@chakra-ui/react";
+import { findSlot } from "../Common/findSlot.js";
 export const DrawerHeader = ({ children }) => {
     return _jsx(_Fragment, { children: children });
 };
@@ -11,13 +15,31 @@ export const DrawerBody = ({ children }) => {
 export const DrawerFooter = ({ children }) => {
     return _jsx(_Fragment, { children: children });
 };
-export default function Drawer({ isOpen, onClose, placement = "right", size = "xl", id, variant = "solid", children, }) {
+export const 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 = useRef(false);
+    useEffect(() => {
+        if (process.env.NODE_ENV === "production" || !isUnnamed || warned.current)
+            return;
+        warned.current = true;
+        console.warn(UNNAMED_DRAWER_WARNING);
+    }, [isUnnamed]);
+};
+function DialogContent({ label, labelledBy, ...props }) {
+    return (_jsx(DialogNaming, { label: label, labelledBy: labelledBy, children: _jsx(DrawerContent, { ...props }) }));
+}
+/** Slide-in dialog; content must sit in DrawerHeader, DrawerBody or DrawerFooter slots. */
+export default 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 } = useCustomTheme();
-    const isReactElement = (child) => {
-        return child !== null && typeof child === "object" && "type" in child;
-    };
-    const header = React.Children.toArray(children).find((child) => isReactElement(child) && child.type === DrawerHeader);
-    const body = React.Children.toArray(children).find((child) => isReactElement(child) && child.type === DrawerBody);
-    const footer = React.Children.toArray(children).find((child) => isReactElement(child) && child.type === DrawerFooter);
-    return (_jsxs(ChakraDrawer, { isOpen: isOpen, placement: placement, onClose: onClose, size: size, variant: variant, id: id, children: [_jsx(DrawerOverlay, {}), _jsxs(DrawerContent, { bg: colors.background[50], children: [_jsx(DrawerCloseButton, {}), header && (_jsx(ChakraDrawerHeader, { borderBottomWidth: "1px", children: header })), _jsx(ChakraDrawerBody, { children: body && body }), footer && _jsx(ChakraDrawerFooter, { borderTopWidth: "1px", children: footer })] })] }));
+    const headerSlot = findSlot(children, DrawerHeader);
+    const bodySlot = findSlot(children, DrawerBody);
+    const footerSlot = findSlot(children, DrawerFooter);
+    warnDroppedSlotChildren("Drawer", children, [DrawerHeader, DrawerBody, 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 (_jsxs(ChakraDrawer, { 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: [_jsx(DrawerOverlay, {}), _jsxs(DialogContent, { ...contentProps, label: ariaLabel, labelledBy: ariaLabelledBy, children: [!hideCloseButton && _jsx(DrawerCloseButton, {}), headerSlot && (_jsx(ChakraDrawerHeader, { borderBottomWidth: "1px", borderColor: raisedRule(colors), ...headerSlot.props, children: headerSlot })), _jsx(ChakraDrawerBody, { ...((_c = bodySlot === null || bodySlot === void 0 ? void 0 : bodySlot.props) !== null && _c !== void 0 ? _c : {}), children: bodySlot }), footerSlot && (_jsx(ChakraDrawerFooter, { borderTopWidth: "1px", borderColor: raisedRule(colors), ...footerSlot.props, children: footerSlot })), portalChildren] })] }));
 }

package/dist/esm/Components/Dropdown/DropDown.js

@@ -1,28 +1,48 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useRef, useState } from "react";
+import { forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { Box, Flex, Button, useDisclosure, List, ListItem, Portal, } from "@chakra-ui/react";
-import { motion } from "framer-motion";
+import { motion, useReducedMotion } from "framer-motion";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
+import { raisedRule } from "../../Theme/tokens/builders/surfaceRaised.js";
 import { scrollbarStyles } from "../../Theme/tokens/builders/scrollbar.js";
+import { listRowBackgrounds } from "../../Theme/tokens/builders/rowStates.js";
+import { optionRowInk } from "../Select/optionRowInk.js";
+import { useExclusiveOverlay } from "../../Hooks/useExclusiveOverlay.js";
 import { ChevronDown } from "lucide-react";
 import { rafThrottle } from "../../Utils/rafThrottle.js";
+import { BUTTON_SIZES } from "../../Theme/tokens/primitives/controlSizes.js";
+import { optionRowSpec, OPTION_ROW_RADIUS } from "../../Theme/tokens/primitives/optionRowSizes.js";
+import { transitionFor } from "../../Theme/tokens/primitives/motion.js";
+import { BORDER_WIDTHS } from "../../Theme/tokens/primitives/borderWidths.js";
+import { reducedMotionSx } from "../../Theme/chakra/motion.js";
+import { focusVisibleStyles, insetFocusRingShadow } from "../../Theme/chakra/focusRing.styles.js";
+import { isActivationKey } from "../Common/activationKey.js";
+import { useOutsideMouseDown } from "../../Hooks/useOutsideMouseDown.js";
 const MotionBox = motion(forwardRef((props, ref) => (_jsx(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: BUTTON_SIZES.xs.iconSize, minW: "8rem", gap: 1.5, rowSize: "xs" },
+    sm: { btn: "sm", img: "1rem", chevron: BUTTON_SIZES.sm.iconSize, minW: "9rem", gap: 2, rowSize: "sm" },
+    md: { btn: "md", img: "1.125rem", chevron: BUTTON_SIZES.md.iconSize, minW: "11rem", gap: 2, rowSize: "md" },
+    lg: { btn: "lg", img: "1.25rem", chevron: 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 = transitionFor(["background-color", "border-color", "color", "box-shadow"]);
+const ROW_TRANSITION = transitionFor(["background-color", "color"]);
+const CHEVRON_TRANSITION = 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 = 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 = useCustomTheme();
-    const { isOpen, onOpen, onToggle, onClose } = useDisclosure();
+    const rowBackgrounds = useMemo(() => listRowBackgrounds(theme.colors), [theme.colors]);
+    const { isOpen, onOpen, onClose } = useDisclosure();
+    const requestExclusiveOpen = useExclusiveOverlay(isOpen, onClose);
     const dropdownRef = useRef(null);
     const menuRef = useRef(null);
     const [menuPos, setMenuPos] = 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 = optionRowSpec(s.rowSize);
+    const prefersReducedMotion = useReducedMotion();
     const menuId = 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.
@@ -40,14 +60,22 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
     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();
         }
     };
@@ -57,9 +85,7 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
             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(); });
             }
         }
@@ -84,17 +110,14 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
             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 (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") {
@@ -123,17 +146,24 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
         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 (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 = useCallback(() => {
         var _a, _b;
         if (!dropdownRef.current)
@@ -178,22 +208,7 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
             window.removeEventListener("resize", onReposition);
         };
     }, [isOpen, updateMenuPos]);
-    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]);
+    useOutsideMouseDown([dropdownRef, menuRef], () => onClose(), { enabled: isOpen });
     const setMenuRef = (node) => {
         menuRef.current = node;
         if (typeof ref === "function")
@@ -204,32 +219,32 @@ const Dropdown = forwardRef(({ dropDownButtonStyle, ButtonText, options, handleO
         if (node)
             updateMenuPos();
     };
-    const Chevron = isVisibleIconShow ? (_jsx(Box, { as: "span", display: "inline-flex", transition: "transform 0.2s ease", transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", children: _jsx(ChevronDown, { size: s.chevron }) })) : undefined;
+    const Chevron = isVisibleIconShow ? (_jsx(Box, { as: "span", display: "inline-flex", transition: CHEVRON_TRANSITION, transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", sx: reducedMotionSx(), children: _jsx(ChevronDown, { size: s.chevron }) })) : undefined;
     const dropDownToggleOption = () => {
-        const ButtonToggle = (_jsx(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: _jsxs(Box, { as: "span", display: "inline-flex", alignItems: "center", gap: DropdownIcon && ButtonText ? s.gap : 0, children: [DropdownIcon, ButtonText] }) }));
-        const TextToggle = (_jsxs(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 = (_jsx(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, ...reducedMotionSx(), ...dropDownButtonStyle }, ...buttonProps, children: _jsxs(Box, { as: "span", display: "inline-flex", alignItems: "center", gap: DropdownIcon && ButtonText ? s.gap : 0, children: [DropdownIcon, ButtonText] }) }));
+        const TextToggle = (_jsxs(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: { ...focusVisibleStyles(theme.colors), ...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 (_jsx(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: scrollbarStyles(theme.colors, "overlay"), style: ListStyle, children: options.map((option, index) => (_jsxs(ListItem, { ref: (node) => {
+        const hoverTint = rowBackgrounds.active;
+        return (_jsx(List, { id: menuId, role: "menu", onKeyDown: handleMenuKeyDown, bg: theme.colors.surfaceRaised, border: `${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: scrollbarStyles(theme.colors, "overlay"), style: ListStyle, children: options.map((option, index) => (_jsxs(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: OPTION_ROW_RADIUS, display: "flex", alignItems: "center", gap: rowSpec.gap, fontSize: rowSpec.fontSize, cursor: "pointer", color: optionRowInk(theme.colors, false), transition: ROW_TRANSITION, _hover: { bg: hoverTint }, _focus: { bg: hoverTint, outline: "none" }, _focusVisible: {
+                    bg: hoverTint,
+                    boxShadow: 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) && (_jsx(Box, { as: option.image, boxSize: s.img, flexShrink: 0, color: theme.colors.textMuted, style: ImageStyle })), _jsx(Box, { as: "span", fontSize: s.fontSize, isTruncated: true, 
-                        // fontWeight={400}
-                        style: LabelStyle, children: option.label })] }, option.id))) }));
+                    ? `${BORDER_WIDTHS.hairline} solid ${raisedRule(theme.colors)}`
+                    : undefined, sx: { "&:last-child": { borderBottom: "none" }, ...reducedMotionSx() }, style: ItemStyle, fontWeight: 500, children: [option.image && (_jsx(Box, { as: option.image, boxSize: s.img, flexShrink: 0, color: theme.colors.textMuted, style: ImageStyle })), _jsx(Box, { as: "span", fontSize: rowSpec.fontSize, isTruncated: true, style: LabelStyle, children: option.label })] }, option.id))) }));
     };
-    return (_jsxs(Box, { ref: dropdownRef, position: "relative", display: "inline-block", children: [dropDownToggleOption(), isOpen && (_jsx(Portal, { children: _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 (_jsxs(Box, { ref: dropdownRef, position: "relative", display: "inline-block", children: [dropDownToggleOption(), isOpen && (_jsx(Portal, { children: _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";
 export default Dropdown;