@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/nav-menu.js

@@ -0,0 +1,683 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import * as Aglyn from "@aglyn/aglyn";
+import { mdiChevronDown, mdiFormDropdown, mdiViewGridOutline } from "@aglyn/shared-data-mdi";
+import { MdiIcon } from "@aglyn/shared-ui-jsx";
+import Box from "@mui/material/Box";
+import Button from "@mui/material/Button";
+import ClickAwayListener from "@mui/material/ClickAwayListener";
+import Paper from "@mui/material/Paper";
+import Stack from "@mui/material/Stack";
+import Typography from "@mui/material/Typography";
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { generatePresetId } from "../utils/generate-preset-id.js";
+import { isLeafSelectedWithin, parseLeafNodeId } from "./drawer.js";
+// Component ids are persisted in screen documents; never rename.
+export const NAV_MENU_ID = 'muiNavMenu';
+export const MEGA_MENU_ID = 'muiMegaMenu';
+/** Hover close grace period so the pointer can cross into the panel. */ const HOVER_CLOSE_DELAY_MS = 150;
+/**
+ * Mounted menus in mount order (AGL-568). Broadcast commands (no target
+ * node id) are answered by the FIRST registered menu only, mirroring the
+ * drawer bus, so a page with one menu needs no wiring at all.
+ */ const mountedMenus = [];
+/**
+ * The panel sx per mega-menu width preset. Wide/full center under the
+ * trigger with the 50%/translate trick, so no measuring is needed and
+ * SSR markup is stable.
+ */ export function megaMenuPanelSx(panelWidth) {
+    switch(panelWidth){
+        case 'full':
+            return {
+                width: '100vw',
+                maxWidth: '100vw',
+                left: '50%',
+                transform: 'translateX(-50%)',
+                borderRadius: 0
+            };
+        case 'wide':
+            return {
+                width: 'min(90vw, 720px)',
+                left: '50%',
+                transform: 'translateX(-50%)'
+            };
+        default:
+            return {
+                minWidth: 280,
+                left: 0
+            };
+    }
+}
+/**
+ * Trigger typography (AGL-1198). A menu label sits in a nav beside plain
+ * links, so it reads as navigation, not as a call to action — MUI's
+ * uppercase Button transform shouts "PRODUCT" next to "Pricing". The
+ * default lives on the WRAPPER and the Button inherits it, so an author
+ * who does want uppercase can set it in STYLES → Typography on the
+ * element and have it win; before this there was no way to change it at
+ * all, because the Button is internal to the element.
+ */ const TRIGGER_SHELL_SX = {
+    position: 'relative',
+    display: 'inline-flex',
+    textTransform: 'none'
+};
+/**
+ * The rest of the same argument, generalized (AGL-2542).
+ *
+ * `textTransform` was one symptom of a whole button's worth of them. The
+ * trigger still arrived as a `Button`: 0.875rem where the links beside it
+ * were 15px, `min-width: 64px` padding "Docs" out to a width its own text
+ * never asked for, and `6px 8px` of padding widening the visual gap on two
+ * items out of five. In a nav laid out on a flat gap, that is a rhythm one
+ * element breaks and no author can fix — the Button is internal, so a font
+ * size set in STYLES lands on the wrapper and MUI's own class outranks it.
+ *
+ * So every typographic property is handed back to the wrapper the same way
+ * `textTransform` was, and the button chrome that has no meaning on a nav
+ * item is dropped. The element now renders as what it is — a label in a nav
+ * — and STYLES → Typography on it reaches the label, which is the control an
+ * author was reaching for when they found there wasn't one.
+ *
+ * `endIcon`'s negative right margin goes with the padding it was tucking
+ * into; left at -4px against zero padding, the chevron would hang outside
+ * the element and break the gap it just stopped breaking.
+ *
+ * ⚠️ Padding is where the hover target came from, and a hover-opened menu is
+ * only as reachable as its trigger. It belongs on the WRAPPER now — which is
+ * both what an author can actually edit and what `onMouseLeave` measures, so
+ * padding added there enlarges the target instead of merely looking like it.
+ */ const TRIGGER_SX = {
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontWeight: 'inherit',
+    lineHeight: 'inherit',
+    letterSpacing: 'inherit',
+    textTransform: 'inherit',
+    color: 'inherit',
+    minWidth: 0,
+    padding: 0,
+    '& .MuiButton-endIcon': {
+        marginRight: 0
+    }
+};
+const MenuShell = /*#__PURE__*/ forwardRef((props, ref)=>{
+    const { label, editorHint, panelSx, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "label",
+        "editorHint",
+        "panelSx",
+        "sx",
+        "children"
+    ]);
+    // Node styles ride the sx prop the renderer merges; keep them by
+    // composing with the shell's own layout sx (stack.ts pattern).
+    const nodeSx = Array.isArray(sx) ? sx : sx ? [
+        sx
+    ] : [];
+    const { editorInert } = Aglyn.useScreenLink(undefined);
+    const [open, setOpen] = useState(false);
+    // True while the menu is open BECAUSE a hover interaction opened it —
+    // only then does pointer leave close the menu.
+    const hoverOpenRef = useRef(false);
+    const closeTimer = useRef(null);
+    // The renderer stamps the node id on every leaf; commands target it.
+    const nodeId = useMemo(()=>parseLeafNodeId(rest['data-aglyn']), // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        rest['data-aglyn']
+    ]);
+    const cancelClose = useCallback(()=>{
+        if (closeTimer.current) {
+            clearTimeout(closeTimer.current);
+            closeTimer.current = null;
+        }
+    }, []);
+    const closeNow = useCallback(()=>{
+        cancelClose();
+        hoverOpenRef.current = false;
+        setOpen(false);
+    }, [
+        cancelClose
+    ]);
+    const scheduleClose = useCallback(()=>{
+        cancelClose();
+        closeTimer.current = setTimeout(closeNow, HOVER_CLOSE_DELAY_MS);
+    }, [
+        cancelClose,
+        closeNow
+    ]);
+    // Menu command bus enrollment (AGL-568): mirrors the drawer exactly —
+    // live surfaces only, keyed by node id, broadcasts answered by the
+    // first mounted menu.
+    useEffect(()=>{
+        if (editorInert || !nodeId) return undefined;
+        mountedMenus.push(nodeId);
+        const unsubscribe = Aglyn.subscribeMenuCommands((detail)=>{
+            // Match on the un-namespaced suffix (AGL-573): a command authored on
+            // a layout-scoped menu carries the raw canvas id while this menu's
+            // live id is `layout__`-namespaced (or vice versa) — leafIdsMatch
+            // compares them equal without re-authoring the persisted action.
+            const targeted = detail.nodeId ? Aglyn.leafIdsMatch(detail.nodeId, nodeId) : mountedMenus[0] === nodeId;
+            if (!targeted) return;
+            cancelClose();
+            if (detail.command === 'close') {
+                hoverOpenRef.current = false;
+                setOpen(false);
+                return;
+            }
+            // open/toggle: remember hover provenance so pointer leave closes
+            // hover-opened menus (and never click/command-opened ones).
+            hoverOpenRef.current = Boolean(detail.hover);
+            if (detail.command === 'open') setOpen(true);
+            else setOpen((value)=>!value);
+        });
+        return ()=>{
+            unsubscribe();
+            cancelClose();
+            const index = mountedMenus.indexOf(nodeId);
+            if (index >= 0) mountedMenus.splice(index, 1);
+        };
+    }, [
+        editorInert,
+        nodeId,
+        cancelClose
+    ]);
+    if (editorInert) {
+        // Editor affordance (AGL-571): collapsed trigger by default — exactly
+        // what the live site shows — expanding to the editable panel only while
+        // the menu subtree holds the selection.
+        const authoring = isLeafSelectedWithin(rest);
+        return /*#__PURE__*/ _jsxs(Box, _extends({
+            ref: ref
+        }, rest, {
+            // Relative so the authoring panel drops UNDER the trigger as an
+            // overlay (AGL-830). The old inline-block expanded the panel in the
+            // toolbar's flow, shoving and overlapping the other nav items in a
+            // horizontal app bar; positioning it like the live popup keeps the
+            // bar intact while the panel stays selectable and editable in place.
+            sx: [
+                TRIGGER_SHELL_SX,
+                ...nodeSx
+            ],
+            children: [
+                /*#__PURE__*/ _jsx(Button, {
+                    color: "inherit",
+                    "aria-expanded": authoring || undefined,
+                    endIcon: /*#__PURE__*/ _jsx(MdiIcon, {
+                        path: mdiChevronDown.path
+                    }),
+                    sx: TRIGGER_SX,
+                    children: label
+                }),
+                authoring ? /*#__PURE__*/ _jsxs(Paper, {
+                    elevation: 4,
+                    "aria-label": label,
+                    sx: [
+                        {
+                            position: 'absolute',
+                            top: '100%',
+                            mt: 0.5,
+                            zIndex: (theme)=>theme.zIndex.modal,
+                            p: 1,
+                            border: '1px dashed',
+                            borderColor: 'divider'
+                        },
+                        panelSx
+                    ],
+                    children: [
+                        /*#__PURE__*/ _jsx(Typography, {
+                            variant: "caption",
+                            color: "text.secondary",
+                            sx: {
+                                display: 'block',
+                                mb: 0.5,
+                                px: 1
+                            },
+                            children: editorHint
+                        }),
+                        children
+                    ]
+                }) : null
+            ]
+        }));
+    }
+    return /*#__PURE__*/ _jsx(ClickAwayListener, {
+        onClickAway: ()=>open && closeNow(),
+        children: /*#__PURE__*/ _jsxs(Box, _extends({
+            ref: ref
+        }, rest, {
+            // Hover-close choreography (AGL-568): the panel renders inside
+            // this wrapper (no portal), so trigger + panel share one
+            // enter/leave pair. Only hover-opened menus follow the pointer
+            // out; enter always cancels a pending close so the pointer can
+            // travel between trigger and panel.
+            onMouseEnter: cancelClose,
+            onMouseLeave: ()=>{
+                if (hoverOpenRef.current) scheduleClose();
+            },
+            onKeyDown: (event)=>{
+                if (event.key === 'Escape') closeNow();
+            },
+            sx: [
+                TRIGGER_SHELL_SX,
+                ...nodeSx
+            ],
+            children: [
+                /*#__PURE__*/ _jsx(Button, {
+                    color: "inherit",
+                    "aria-haspopup": "true",
+                    "aria-expanded": open || undefined,
+                    endIcon: /*#__PURE__*/ _jsx(MdiIcon, {
+                        path: mdiChevronDown.path
+                    }),
+                    sx: TRIGGER_SX,
+                    onClick: ()=>{
+                        // Zero-config default: the trigger click-toggles its menu;
+                        // a click also "pins" a hover-opened menu.
+                        cancelClose();
+                        hoverOpenRef.current = false;
+                        setOpen((value)=>!value);
+                    },
+                    children: label
+                }),
+                open ? /*#__PURE__*/ _jsx(Paper, {
+                    elevation: 4,
+                    "aria-label": label,
+                    sx: [
+                        {
+                            position: 'absolute',
+                            top: '100%',
+                            zIndex: (theme)=>theme.zIndex.modal,
+                            p: 1
+                        },
+                        panelSx
+                    ],
+                    children: children
+                }) : null
+            ]
+        }))
+    });
+});
+MenuShell.displayName = 'AglynMenuShell';
+/**
+ * Strips the pre-AGL-568 "Open on" attribute persisted docs may still
+ * carry. Behavior configuration rides the interactions system now; the
+ * stored value is ignored silently — no migrations, no warnings — and
+ * must never leak onto the DOM.
+ */ function stripLegacyTrigger(rest) {
+    delete rest['trigger'];
+}
+/**
+ * Dropdown nav item (AGL-562): a labeled nav button whose children —
+ * screen links, buttons, anything — open in a dropdown panel. Clicking
+ * the trigger toggles it; interactions drive it over the menu command
+ * bus (AGL-568). SSR ships the menu closed; no window access happens at
+ * render.
+ */ const NavMenu = /*#__PURE__*/ forwardRef((props, ref)=>{
+    const { label, children } = props, rest = _object_without_properties_loose(props, [
+        "label",
+        "children"
+    ]);
+    stripLegacyTrigger(rest);
+    return /*#__PURE__*/ _jsx(MenuShell, _extends({
+        ref: ref,
+        label: label || 'Menu',
+        editorHint: "Dropdown items — shown in a menu on the live site",
+        panelSx: {
+            minWidth: 220,
+            left: 0
+        }
+    }, rest, {
+        children: /*#__PURE__*/ _jsx(Stack, {
+            spacing: 0.5,
+            sx: {
+                alignItems: 'stretch'
+            },
+            children: children
+        })
+    }));
+});
+NavMenu.displayName = 'AglynNavMenu';
+/**
+ * Mega menu (AGL-562): a SaaS-style wide panel anchored under a nav
+ * item with a free-form canvas slot — columns of links, promos,
+ * whatever the author drops in. Click-toggles like the dropdown; the
+ * SaaS hover-open convention is one interaction away ("On hover → Open
+ * menu", AGL-568) and then closes itself on pointer leave.
+ */ export const MegaMenu = /*#__PURE__*/ forwardRef((props, ref)=>{
+    const { label, panelWidth, children } = props, rest = _object_without_properties_loose(props, [
+        "label",
+        "panelWidth",
+        "children"
+    ]);
+    stripLegacyTrigger(rest);
+    return /*#__PURE__*/ _jsx(MenuShell, _extends({
+        ref: ref,
+        label: label || 'Menu',
+        editorHint: "Mega menu panel — opens under the nav item on the live site",
+        panelSx: _extends({
+            p: 3
+        }, megaMenuPanelSx(panelWidth || 'auto'))
+    }, rest, {
+        children: children
+    }));
+});
+MegaMenu.displayName = 'AglynMegaMenu';
+export const navMenuSchema = {
+    $id: NAV_MENU_ID,
+    pluginId: BUNDLE_ID,
+    displayName: 'Dropdown Menu',
+    description: 'A nav item that opens a dropdown of links beneath it.',
+    category: Aglyn.ComponentCategory.NAVIGATION,
+    icon: {
+        path: mdiFormDropdown.path,
+        sx: {
+            color: '#2196f3'
+        }
+    },
+    // Open/close behavior deliberately has NO attribute (AGL-568): click
+    // toggles by default and everything else is authored as an
+    // interaction (e.g. "On hover → Open menu").
+    attributes: [
+        {
+            name: 'label',
+            description: 'Text on the nav item that opens the dropdown.',
+            component: Aglyn.FieldComponentType.TEXT_FIELD,
+            label: 'Label'
+        }
+    ]
+};
+export const megaMenuSchema = {
+    $id: MEGA_MENU_ID,
+    pluginId: BUNDLE_ID,
+    displayName: 'Mega Menu',
+    description: 'A nav item that opens a wide panel — columns of links, promos, whatever you build.',
+    category: Aglyn.ComponentCategory.NAVIGATION,
+    icon: {
+        path: mdiViewGridOutline.path,
+        sx: {
+            color: '#2196f3'
+        }
+    },
+    // Open/close behavior deliberately has NO attribute (AGL-568) — see
+    // navMenuSchema.
+    attributes: [
+        {
+            name: 'label',
+            description: 'Text on the nav item that opens the panel.',
+            component: Aglyn.FieldComponentType.TEXT_FIELD,
+            label: 'Label'
+        },
+        {
+            name: 'panelWidth',
+            description: 'How wide the opened panel is.',
+            component: Aglyn.FieldComponentType.SELECT,
+            label: 'Panel width',
+            // `auto` is the `MegaMenuPanelWidth` member `megaMenuPanelSx` already
+            // switches on, so the sentinel names the case that existed in code
+            // but not in the option list (AGL-1451); `''` could not persist
+            // (AGL-1191), so a wide panel could not be narrowed again.
+            options: [
+                {
+                    value: 'auto',
+                    label: 'Fit content'
+                },
+                {
+                    value: 'wide',
+                    label: 'Wide (720px)'
+                },
+                {
+                    value: 'full',
+                    label: 'Full width'
+                }
+            ]
+        }
+    ]
+};
+const navLink = (label)=>({
+        $id: null,
+        componentId: 'muiScreenLink',
+        pluginId: BUNDLE_ID,
+        props: {
+            children: label,
+            color: 'inherit'
+        }
+    });
+const megaColumn = (title, links)=>({
+        $id: null,
+        componentId: 'muiStack',
+        pluginId: BUNDLE_ID,
+        props: {
+            spacing: 0.5
+        },
+        // Styling goes on the node's own sx, never in props (AGL-1346) — that is
+        // the record the Styles panel edits.
+        sx: {
+            minWidth: 180,
+            alignItems: 'flex-start'
+        },
+        nodes: [
+            {
+                $id: null,
+                componentId: 'muiTypography',
+                pluginId: BUNDLE_ID,
+                props: {
+                    variant: 'overline',
+                    color: 'text.secondary',
+                    children: title
+                }
+            },
+            ...links.map(navLink)
+        ]
+    });
+export const navMenuPresets = [
+    {
+        $id: generatePresetId(NAV_MENU_ID),
+        type: Aglyn.NodeType.PRESET,
+        displayName: 'Dropdown Menu',
+        pluginId: BUNDLE_ID,
+        description: 'Nav item that opens a dropdown of links',
+        category: Aglyn.ComponentCategory.NAVIGATION,
+        icon: navMenuSchema.icon,
+        data: {
+            $id: null,
+            componentId: NAV_MENU_ID,
+            pluginId: BUNDLE_ID,
+            props: {
+                label: 'More'
+            },
+            nodes: [
+                navLink('About'),
+                navLink('Blog'),
+                navLink('Contact')
+            ]
+        }
+    },
+    // Primitive dropdown scaffold (AGL-589): the same result as the menu
+    // elements but built from a Stack + Button + hidden panel, with the
+    // hover choreography (grace delay, Esc/outside-click dismissal)
+    // pre-wired as real interactions the user can edit or remove. The
+    // panel carries `aglyn-hidden` so it starts closed on the live site;
+    // the canvas shows it for editing (the hidden style only injects at
+    // runtime).
+    {
+        $id: generatePresetId('muiStack', 'dropdown-panel'),
+        type: Aglyn.NodeType.PRESET,
+        displayName: 'Dropdown Panel',
+        pluginId: BUNDLE_ID,
+        description: 'Trigger + hover panel built from primitives — opens on hover, ' + 'closes on leave with a grace delay, dismisses on Esc or outside ' + 'click; the wiring arrives as editable interactions',
+        category: Aglyn.ComponentCategory.NAVIGATION,
+        icon: {
+            path: mdiFormDropdown.path,
+            sx: {
+                color: '#2196f3'
+            }
+        },
+        data: {
+            $id: null,
+            presetRef: 'wrapper',
+            componentId: 'muiStack',
+            pluginId: BUNDLE_ID,
+            props: {},
+            sx: {
+                position: 'relative',
+                display: 'inline-flex'
+            },
+            nodes: [
+                {
+                    $id: null,
+                    presetRef: 'trigger',
+                    componentId: 'muiButton',
+                    pluginId: BUNDLE_ID,
+                    props: {
+                        children: 'Explore',
+                        color: 'inherit'
+                    }
+                },
+                {
+                    $id: null,
+                    presetRef: 'panel',
+                    componentId: 'muiStack',
+                    pluginId: BUNDLE_ID,
+                    props: {
+                        className: 'aglyn-hidden',
+                        direction: 'row',
+                        spacing: 4
+                    },
+                    // The panel's whole positioning. It lived in `props.sx` on the
+                    // documents this preset seeded, where the Styles panel could
+                    // neither show nor clear it (AGL-1339/AGL-1346); a fresh insert
+                    // now puts it where a click can reach it. Same keys, same order,
+                    // and `node.sx` composes last — the panel renders identically.
+                    sx: {
+                        position: 'absolute',
+                        top: '100%',
+                        left: 0,
+                        zIndex: 1300,
+                        paddingTop: 3,
+                        paddingRight: 3,
+                        paddingBottom: 3,
+                        paddingLeft: 3,
+                        minWidth: 560,
+                        flexWrap: 'wrap',
+                        backgroundColor: 'background.paper',
+                        color: 'text.primary',
+                        boxShadow: 8,
+                        borderRadius: 1
+                    },
+                    nodes: [
+                        megaColumn('Shop', [
+                            'New arrivals',
+                            'Best sellers',
+                            'Sale'
+                        ]),
+                        megaColumn('Company', [
+                            'About',
+                            'Careers',
+                            'Press'
+                        ]),
+                        megaColumn('Support', [
+                            'Help center',
+                            'Contact'
+                        ])
+                    ]
+                }
+            ]
+        },
+        interactionTemplates: [
+            {
+                name: 'Dropdown panel — open on hover',
+                event: 'elementHoverEnter',
+                triggerRef: 'wrapper',
+                steps: [
+                    {
+                        type: 'showElement',
+                        targetRef: 'panel',
+                        dismissOn: [
+                            'escape',
+                            'outsideClick'
+                        ]
+                    }
+                ]
+            },
+            {
+                name: 'Dropdown panel — close on hover leave',
+                event: 'elementHoverLeave',
+                triggerRef: 'wrapper',
+                steps: [
+                    {
+                        type: 'hideElement',
+                        targetRef: 'panel',
+                        delayMs: 250
+                    }
+                ]
+            }
+        ]
+    },
+    {
+        $id: generatePresetId(MEGA_MENU_ID),
+        type: Aglyn.NodeType.PRESET,
+        displayName: 'Mega Menu',
+        pluginId: BUNDLE_ID,
+        description: 'Wide panel with columns of links; add a hover interaction to ' + 'open it on hover',
+        category: Aglyn.ComponentCategory.NAVIGATION,
+        icon: megaMenuSchema.icon,
+        data: {
+            $id: null,
+            componentId: MEGA_MENU_ID,
+            pluginId: BUNDLE_ID,
+            props: {
+                label: 'Products',
+                panelWidth: 'wide'
+            },
+            nodes: [
+                {
+                    $id: null,
+                    componentId: 'muiStack',
+                    pluginId: BUNDLE_ID,
+                    props: {
+                        direction: 'row',
+                        spacing: 4
+                    },
+                    sx: {
+                        flexWrap: 'wrap'
+                    },
+                    nodes: [
+                        megaColumn('Shop', [
+                            'New arrivals',
+                            'Best sellers',
+                            'Sale'
+                        ]),
+                        megaColumn('Company', [
+                            'About',
+                            'Careers',
+                            'Press'
+                        ]),
+                        megaColumn('Support', [
+                            'Help center',
+                            'Contact'
+                        ])
+                    ]
+                }
+            ]
+        }
+    }
+];
+export default NavMenu;
+
+//# sourceMappingURL=nav-menu.js.map