@asup/context-menu 1.5.2 → 2.0.0

package/README.md

@@ -10,84 +10,133 @@
 
 # @asup/context-menu
 
-REACT Context menu, because I couldn't quite find what I wanted.
+A small, highly-configurable React + TypeScript context menu component and helpers.
 
-## Installation
+Key points:
+
+- Works with React 19 (package is built and tested against React 19; React is a peer dependency).
+- TypeScript types included.
+- Lightweight and focused on accessibility and nested sub-menus.
+
+## Storybook
+
+Run Storybook to see interactive component examples and documentation.
+
+```powershell
+# install dependencies
+npm install
 
+# run Storybook
+npm run storybook
+
+# run tests
+npm run test
+
+# build library bundle
+npm run build
 ```
-# with npm
+
+## Installation
+
+Install from npm:
+
+```powershell
 npm install @asup/context-menu
 ```
 
+Note: React and ReactDOM are peer dependencies — install a compatible React version in your application.
+
 ## Usage
 
-Context menu provider, takes a list of available actions and renders a context menu on appropriate click.
-Sub menus can be added within each item.
-Wrap around the elements that need to have the menu.
+### ContextMenuHandler
+
+```tsx
+import { ContextMenuHandler, IMenuItem } from "@asup/context-menu";
 
+const menuItems: IMenuItem[] = [
+  { label: "Item 1", action: () => console.log("Item 1") },
+  {
+    label: "Item 2",
+    action: () => console.log("Item 2"),
+    group: [{ label: "Subitem 2.1", action: () => console.log("Subitem 2.1") }],
+  },
+  { label: "Item 3 (disabled)", disabled: true },
+];
+
+<ContextMenuHandler menuItems={menuItems}>
+  <div>Right click here to open the menu</div>
+</ContextMenuHandler>;
 ```
-import { ContextMenuProvider, IMenuItem } from '@asup/context-menu';
-
-<ContextMenuHandler
-  menuItems={[
-    {
-      label: 'Item 1',
-      action: () => {
-        console.log('Item 1 function run');
-      },
-    },
-    {
-      label: 'Item 2',
-      action: () => console.log('Item 2 function run'),
-      group: [
-        { label: 'Subitem 2.1', action: () => console.log('Item 2.1 function run') },
-      ],
-    },
-    {
-      label: 'Item 3',
-      action: () => console.log('Item 3 function run'),
-      disabled: true,
-    },
-  ]}
->
-  <Chilren
-    where the context menu is applied...
-  />
-</ContextMenuHandler>
 
+### AutoHeight
+
+Use `AutoHeight` to wrap content that may expand/contract — it will manage layout height for smoother transitions.
+
+```tsx
+import { AutoHeight } from "@asup/context-menu";
+
+<AutoHeight>
+  <div style={{ padding: 12 }}>
+    This content can change size; AutoHeight will help the layout adjust smoothly.
+  </div>
+</AutoHeight>;
 ```
 
+### ClickForMenu
+
+`ClickForMenu` attaches a click-based menu to any element (useful for toolbar buttons or inline actions).
+
+```tsx
+import { ClickForMenu, IMenuItem } from "@asup/context-menu";
+
+const clickItems: IMenuItem[] = [
+  { label: "Edit", action: () => console.log("Edit") },
+  { label: "Delete", action: () => console.log("Delete") },
+];
+
+<ClickForMenu menuItems={clickItems}>
+  <button type="button">Actions</button>
+</ClickForMenu>;
 ```
-import { ContextWindowStack, ContextWindow }
-
-// Context window stack needs to cover the application, or portion where context windows cannot clash with each other
-<ContextWindowStack>
- ...rest of app
-
-  <ContextWindow
-    id='window-1'
-    title={'Window 1'}
-    visible={visible}
-    style={ window styling, applied to the window div}
-    onOpen={ called function on opening}
-    onClose={ called function on closing (close cross in the window)}
-  >
-    {window contents}
-  </ContextWindow>
-
-  <ContextWindow
-    id='window-2'
-    title={'Window 2'}
-    visible={visible}
-    style={ window styling, applied to the window div}
-    onOpen={ called function on opening}
-    onClose={ called function on closing (close cross in the window)}
-  >
-    {window contents}
-  </ContextWindow>
-
- ...end of app
-
-</ContextWindowStack>
 
+### ContextWindow
+
+```tsx
+import { ContextWindow } from "@asup/context-menu";
+
+<ContextWindow
+  id="window-1"
+  title="Window 1"
+  visible={true}
+  onClose={() => {}}
+>
+  Window content
+</ContextWindow>;
 ```
+
+See the Storybook for interactive examples and more options.
+
+## Development
+
+Useful scripts (from `package.json`):
+
+- `npm run prepare` — run Husky (prepares Git hooks).
+- `npm run storybook` — start Storybook to view component examples.
+- `npm run build-storybook` — build a static Storybook site.
+- `npm run test` — run Jest and collect coverage (`jest --collectCoverage=true`).
+- `npm run test-watch` — run Jest in watch mode with coverage (`jest --watch --collectCoverage=true --maxWorkers=4`).
+- `npm run eslint` — run ESLint over `src` (pattern: `src/**/*.{js,jsx,ts,tsx}`).
+- `npm run build` — build the library bundle with Parcel. This script clears the Parcel cache before building (`parcel build src/main.ts`).
+
+## Contributing
+
+Contributions and PRs are welcome. Please follow the repository conventions (linting, types, and tests).
+
+1. Fork the repo and create a feature branch.
+2. Run `npm install`.
+3. Run and update tests: `npm run test`.
+4. Submit a PR and describe your changes.
+
+## License
+
+MIT — see the `LICENCE` file for details.

package/dist/cjs/main.js

@@ -40,7 +40,6 @@ $parcel$export($a68bd8a6c0fd98c2$exports, "ClickForMenu", function () { return $
 $parcel$export($a68bd8a6c0fd98c2$exports, "ContextMenu", function () { return $5150b66b01c99189$export$8dc6765e8be191c7; });
 $parcel$export($a68bd8a6c0fd98c2$exports, "ContextMenuHandler", function () { return $3c568ee547c732c3$export$ed4f9641643dc7e4; });
 $parcel$export($a68bd8a6c0fd98c2$exports, "ContextWindow", function () { return $46fb0088a1bbb6d8$export$1af8984c69ba1b24; });
-$parcel$export($a68bd8a6c0fd98c2$exports, "ContextWindowStack", function () { return $16208d559c772441$export$9f37482ccd50dad2; });
 
 
 
@@ -98,11 +97,16 @@ function $95149596d5a7ed2b$export$77bf000da9303d1(_param) {
         setTargetHeight
     ]);
     // Trigger height change on children update
-    (0, $gTuX4$react.useLayoutEffect)(()=>{
-        setTargetHeight();
+    const [, startTransition] = (0, $gTuX4$react.useTransition)();
+    (0, $gTuX4$react.useEffect)(()=>{
+        // Mark this update as non-urgent to avoid cascading render warnings
+        startTransition(()=>{
+            setTargetHeight();
+        });
     }, [
         setTargetHeight,
-        children
+        children,
+        startTransition
     ]);
     return /*#__PURE__*/ (0, $gTuX4$reactjsxruntime.jsx)("div", (0, $gTuX4$swchelperscjs_object_spread_propscjs._)((0, $gTuX4$swchelperscjs_object_spreadcjs._)({}, rest), {
         className: (0, (/*@__PURE__*/$parcel$interopDefault($796f463330153c24$exports))).autoHeightWrapper,
@@ -247,13 +251,25 @@ const $5150b66b01c99189$var$ESTIMATED_MENU_ITEM_HEIGHT = 34;
 const $5150b66b01c99189$var$ESTIMATED_MENU_PADDING = 4;
 const $5150b66b01c99189$var$ESTIMATED_MENU_WIDTH = 200;
 const $5150b66b01c99189$export$8dc6765e8be191c7 = /*#__PURE__*/ (0, $gTuX4$react.forwardRef)(({ visible: visible, entries: entries, xPos: xPos, yPos: yPos, toClose: toClose }, ref)=>{
-    // Check that menu can fit inside the window
-    let menuHeight = entries.length * $5150b66b01c99189$var$ESTIMATED_MENU_ITEM_HEIGHT + $5150b66b01c99189$var$ESTIMATED_MENU_PADDING;
-    let menuWidth = $5150b66b01c99189$var$ESTIMATED_MENU_WIDTH;
-    if (ref && typeof ref !== "function" && ref.current instanceof HTMLDivElement) {
-        menuHeight = ref.current.offsetHeight;
-        menuWidth = ref.current.offsetWidth;
-    }
+    // Measure menu size after mount/render to avoid accessing refs during render
+    const [menuHeight, setMenuHeight] = (0, $gTuX4$react.useState)(entries.length * $5150b66b01c99189$var$ESTIMATED_MENU_ITEM_HEIGHT + $5150b66b01c99189$var$ESTIMATED_MENU_PADDING);
+    const [menuWidth, setMenuWidth] = (0, $gTuX4$react.useState)($5150b66b01c99189$var$ESTIMATED_MENU_WIDTH);
+    (0, $gTuX4$react.useLayoutEffect)(()=>{
+        // Only measure when visible; ref access inside effect is allowed
+        if (visible && ref && typeof ref !== "function" && ref.current instanceof HTMLDivElement) {
+            setMenuHeight(ref.current.offsetHeight);
+            setMenuWidth(ref.current.offsetWidth);
+        }
+        // When not visible, fall back to estimates
+        if (!visible) {
+            setMenuHeight(entries.length * $5150b66b01c99189$var$ESTIMATED_MENU_ITEM_HEIGHT + $5150b66b01c99189$var$ESTIMATED_MENU_PADDING);
+            setMenuWidth($5150b66b01c99189$var$ESTIMATED_MENU_WIDTH);
+        }
+    }, [
+        visible,
+        entries,
+        ref
+    ]);
     const adjustedYPos = yPos + menuHeight > window.innerHeight ? Math.max(window.innerHeight - menuHeight - $5150b66b01c99189$var$ESTIMATED_MENU_PADDING, 0) : yPos;
     const adjustedXPos = xPos + menuWidth > window.innerWidth ? Math.max(window.innerWidth - menuWidth - $5150b66b01c99189$var$ESTIMATED_MENU_PADDING, 0) : xPos;
     return /*#__PURE__*/ (0, $gTuX4$reactjsxruntime.jsx)("div", {
@@ -531,7 +547,6 @@ const $3c568ee547c732c3$export$ed4f9641643dc7e4 = (_param)=>{
         "menuItems",
         "showLowMenu"
     ]);
-    var _divHandlderRef_current;
     // Check for higher content menu
     const higherContext = (0, $gTuX4$react.useContext)($3c568ee547c732c3$export$fc58dc71afe92de2);
     const thisMenuItems = (0, $gTuX4$react.useMemo)(()=>[
@@ -564,9 +579,34 @@ const $3c568ee547c732c3$export$ed4f9641643dc7e4 = (_param)=>{
     const [menuInDom, setMenuInDom] = (0, $gTuX4$react.useState)(false);
     const [mouseOverHandlerDiv, setMouseOverHandlerDiv] = (0, $gTuX4$react.useState)(false);
     const [mouseOverMenu, setMouseOverMenu] = (0, $gTuX4$react.useState)(false);
-    var _divHandlderRef_current_getBoundingClientRect;
-    // Get holder position
-    const divHandlerPos = (_divHandlderRef_current_getBoundingClientRect = (_divHandlderRef_current = divHandlderRef.current) === null || _divHandlderRef_current === void 0 ? void 0 : _divHandlderRef_current.getBoundingClientRect()) !== null && _divHandlderRef_current_getBoundingClientRect !== void 0 ? _divHandlderRef_current_getBoundingClientRect : null;
+    // Holder position - measured in an effect to avoid reading refs during render
+    const [divHandlerPos, setDivHandlerPos] = (0, $gTuX4$react.useState)(null);
+    (0, $gTuX4$react.useLayoutEffect)(()=>{
+        function updatePos() {
+            if (divHandlderRef.current) setDivHandlerPos(divHandlderRef.current.getBoundingClientRect());
+        }
+        // When the handler is hovered or the menu is mounted, ensure we have a fresh position
+        if (mouseOverHandlerDiv || menuInDom) updatePos();
+        // Attach listeners while the menu/low-menu may be visible so the position stays correct
+        if (mouseOverHandlerDiv || menuInDom) {
+            window.addEventListener("resize", updatePos);
+            // listen on capture to catch scrolls from ancestor elements as well
+            window.addEventListener("scroll", updatePos, true);
+            let ro = null;
+            if (typeof ResizeObserver !== "undefined" && divHandlderRef.current) {
+                ro = new ResizeObserver(()=>updatePos());
+                ro.observe(divHandlderRef.current);
+            }
+            return ()=>{
+                window.removeEventListener("resize", updatePos);
+                window.removeEventListener("scroll", updatePos, true);
+                if (ro) ro.disconnect();
+            };
+        }
+    }, [
+        mouseOverHandlerDiv,
+        menuInDom
+    ]);
     // Handle click off the menu
     const handleClick = (0, $gTuX4$react.useCallback)((e)=>{
         var _menuRef_current;
@@ -761,10 +801,12 @@ const $46fb0088a1bbb6d8$export$1af8984c69ba1b24 = (_param)=>{
     var _rest_style, _rest_style1, _rest_style2, _rest_style3;
     const divRef = (0, $gTuX4$react.useRef)(null);
     const windowRef = (0, $gTuX4$react.useRef)(null);
-    const [windowInDOM, setWindowInDOM] = (0, $gTuX4$react.useState)(false);
-    const [windowVisible, setWindowVisible] = (0, $gTuX4$react.useState)(false);
     const [zIndex, setZIndex] = (0, $gTuX4$react.useState)(minZIndex);
     const resizeListenerRef = (0, $gTuX4$react.useRef)(null);
+    // Track internal state: whether window is in DOM and whether it's been positioned
+    const [windowInDOM, setWindowInDOM] = (0, $gTuX4$react.useState)(false);
+    const [windowVisible, setWindowVisible] = (0, $gTuX4$react.useState)(false);
+    const [, startTransition] = (0, $gTuX4$react.useTransition)();
     // Position
     const windowPos = (0, $gTuX4$react.useRef)({
         x: 0,
@@ -826,37 +868,54 @@ const $46fb0088a1bbb6d8$export$1af8984c69ba1b24 = (_param)=>{
     }, [
         minZIndex
     ]);
-    // Update visibility
+    // Sync windowInDOM with visible prop using a layout effect to avoid ESLint warnings
+    // This effect derives state from props, which is acceptable when there's no synchronous setState
     (0, $gTuX4$react.useEffect)(()=>{
-        // Visible set, but not in DOM
-        if (visible && !windowInDOM) setWindowInDOM(true);
-        else if (visible && windowInDOM && !windowVisible) {
-            pushToTop();
-            setWindowVisible(visible);
-            onOpen === null || onOpen === void 0 ? void 0 : onOpen();
-            // Get starting position
-            if (divRef.current && windowRef.current) {
-                const parentPos = divRef.current.getBoundingClientRect();
-                const pos = windowRef.current.getBoundingClientRect();
-                const windowHeight = pos.bottom - pos.top;
-                windowRef.current.style.left = `${parentPos.left}px`;
-                windowRef.current.style.top = `${parentPos.bottom + windowHeight < window.innerHeight ? parentPos.bottom : Math.max(0, parentPos.top - windowHeight)}px`;
-                windowRef.current.style.transform = "";
-                windowPos.current = {
-                    x: 0,
-                    y: 0
-                };
-            }
+        if (visible && !windowInDOM) // Window should be in DOM when visible becomes true
+        startTransition(()=>{
+            setWindowInDOM(true);
+        });
+        else if (!visible && windowInDOM) // Window should leave DOM when visible becomes false
+        startTransition(()=>{
+            setWindowInDOM(false);
+            setWindowVisible(false);
+        });
+    }, [
+        visible,
+        windowInDOM,
+        startTransition
+    ]);
+    // Position and show window after it's added to DOM
+    (0, $gTuX4$react.useEffect)(()=>{
+        if (windowInDOM && !windowVisible && visible && divRef.current && windowRef.current) {
+            // Position the window
+            const parentPos = divRef.current.getBoundingClientRect();
+            const pos = windowRef.current.getBoundingClientRect();
+            const windowHeight = pos.bottom - pos.top;
+            windowRef.current.style.left = `${parentPos.left}px`;
+            windowRef.current.style.top = `${parentPos.bottom + windowHeight < window.innerHeight ? parentPos.bottom : Math.max(0, parentPos.top - windowHeight)}px`;
+            windowRef.current.style.transform = "";
+            windowPos.current = {
+                x: 0,
+                y: 0
+            };
             checkPosition();
-        } else if (!visible && windowVisible) setWindowVisible(false);
-        else if (!visible && windowInDOM) setWindowInDOM(false);
+            // Update z-index and make visible - use startTransition
+            const maxZ = $46fb0088a1bbb6d8$var$getMaxZIndex(minZIndex);
+            onOpen === null || onOpen === void 0 ? void 0 : onOpen();
+            startTransition(()=>{
+                setZIndex(maxZ + 1);
+                setWindowVisible(true);
+            });
+        }
     }, [
+        windowInDOM,
+        windowVisible,
+        visible,
         checkPosition,
+        minZIndex,
         onOpen,
-        pushToTop,
-        visible,
-        windowInDOM,
-        windowVisible
+        startTransition
     ]);
     // Cleanup effect to remove event listeners on unmount
     (0, $gTuX4$react.useEffect)(()=>{
@@ -952,39 +1011,6 @@ $46fb0088a1bbb6d8$export$1af8984c69ba1b24.displayName = "ContextWindow";
 
 
 
-const $16208d559c772441$var$SESSION_KEY = "context-menu.ContextWindowStack.rendered";
-const $16208d559c772441$export$9f37482ccd50dad2 = ({ children: children })=>{
-    (0, $gTuX4$react.useEffect)(()=>{
-        const doWarn = ()=>console.warn("ContextWindowStack is deprecated and no longer required. ContextWindow now manages z-index automatically. Please remove the ContextWindowStack wrapper from your code.");
-        try {
-            // Prefer sessionStorage so the warning lasts for the browser session.
-            if (typeof window !== "undefined" && window.sessionStorage) {
-                const already = window.sessionStorage.getItem($16208d559c772441$var$SESSION_KEY);
-                if (!already) {
-                    window.sessionStorage.setItem($16208d559c772441$var$SESSION_KEY, "1");
-                    doWarn();
-                }
-                return;
-            }
-        } catch (e) {
-        // sessionStorage may be unavailable (privacy mode). Fall through to global fallback.
-        }
-        // Fallback: use a global flag for environments where sessionStorage isn't available.
-        const g = globalThis;
-        if (!g.__ContextWindowStackRendered) {
-            g.__ContextWindowStackRendered = true;
-            doWarn();
-        }
-    }, []);
-    return /*#__PURE__*/ (0, $gTuX4$reactjsxruntime.jsx)((0, $gTuX4$reactjsxruntime.Fragment), {
-        children: children
-    });
-};
-$16208d559c772441$export$9f37482ccd50dad2.displayName = "ContextWindowStack";
-
-
-
-
 $parcel$exportWildcard(module.exports, $a68bd8a6c0fd98c2$exports);