@acusti/dropdown 0.57.0 → 1.0.0-alpha.0

package/README.md

@@ -7,9 +7,10 @@
 
 `Dropdown` is a React component that renders a menu-like UI with a trigger
 that the user clicks to disclose a dropdown anchored to that trigger. The
-body of the dropdown can include any DOM, and many dropdowns can be
-combined to form a multi-item menu, like the system menu in the top toolbar
-of macOS.
+body of the dropdown can include any DOM. Dropdowns also compose: nest a
+`Dropdown` inside another dropdown’s body to create a submenu, or wrap
+sibling dropdowns in the `Menubar` component to combine them into a
+multi-menu bar, like the system menu in the top toolbar of macOS.
 
 The three primary design goals for the existence of this component:
 
@@ -26,7 +27,12 @@ The three primary design goals for the existence of this component:
        `data-ukt-value="foo"` to specify that an element is a dropdown item
        and the value of that item at the same time (otherwise, the value is
        the text content of the dropdown item element)
-    4. To style your dropdowns, use CSS; there are a
+    4. To create a submenu, nest a `Dropdown` inside the dropdown body (or
+       author the equivalent [`data-ukt-submenu` markup](#submenus)
+       directly)
+    5. To combine dropdowns into a menubar, wrap them in
+       [`<Menubar>`](#menubar)
+    6. To style your dropdowns, use CSS; there are a
        [collection of CSS custom properties](https://github.com/acusti/uikit/blob/main/packages/dropdown/src/Dropdown.css)
        used internally to style them if that works best for you, or just
        override the minimal default CSS as appropriate
@@ -78,6 +84,36 @@ function CustomTrigger() {
 }
 ```
 
+```tsx
+import Dropdown, { Menubar } from '@acusti/dropdown';
+
+// Submenus (nested dropdowns) combined into a menubar
+function AppMenu() {
+    return (
+        <Menubar>
+            <Dropdown label="File">
+                <ul>
+                    <li data-ukt-item>New</li>
+                    <li data-ukt-item>Open…</li>
+                    <Dropdown label="Open Recent">
+                        <ul>
+                            <li data-ukt-item>project-a</li>
+                            <li data-ukt-item>project-b</li>
+                        </ul>
+                    </Dropdown>
+                </ul>
+            </Dropdown>
+            <Dropdown label="Edit">
+                <ul>
+                    <li data-ukt-item>Undo</li>
+                    <li data-ukt-item>Redo</li>
+                </ul>
+            </Dropdown>
+        </Menubar>
+    );
+}
+```
+
 ## Layout Model
 
 `Dropdown` uses CSS anchor positioning for placement and prefers a
@@ -125,12 +161,45 @@ For the most reliable anchor-positioning behavior:
 - prefer CSS variable overrides over custom `top`/`left`/`right` inset
   rules
 
+The body renders in the top layer using the
+[Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API),
+which is what makes the anchor positioning robust. A top-layer element’s
+containing block is always the viewport, so an ancestor with a `transform`,
+`scale`, `filter`, `backdrop-filter`, `perspective`,
+`will-change: transform`, or `contain` can’t capture the `position: fixed`
+body. Were the body a normal descendant instead, any such ancestor would
+become its containing block and its placement math would be measured
+against that box rather than the viewport — `position-try` fallbacks stop
+firing, and the base `position-area` can even resolve to the wrong side.
+Because the body is in the top layer, none of that applies and no
+consumer-side de-transforming is needed. The body uses `popover="manual"`,
+so this component keeps control of dismissal: outside-click, focus, and
+iframe handling are unchanged, and a searchable trigger’s input stays open
+while you interact with it.
+
 For placement recipes, see
 [Placement Customization](#placement-customization-with-css-variables)
 below. If your trigger sits near the right edge of the viewport, the
 [End-Aligned, Content-Sized Menu](#end-aligned-content-sized-menu) example
 is the one you want.
 
+## Browser Support
+
+`Dropdown` relies on two web-platform features, both now
+[Baseline](https://web.dev/baseline) across Chrome, Edge, Firefox, and
+Safari:
+
+- **CSS anchor positioning** (`anchor-name`, `position-area`,
+  `@position-try`) places and re-flows the body —
+  [Baseline 2026](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor-name)
+- the **Popover API** (`popover` plus `showPopover()`) renders the body in
+  the top layer —
+  [Baseline 2024](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+
+These are _newly available_ Baseline features: they work in up-to-date
+browser versions but not in ones predating that support, which the
+component requires.
+
 ## API Reference
 
 ### Props
@@ -160,11 +229,6 @@ type Props = {
     children: ReactNode | [ReactNode, ReactNode];
     className?: string;
     disabled?: boolean;
-    /**
-     * Group identifier string links dropdowns together into a menu
-     * (like macOS top menubar).
-     */
-    group?: string;
     /**
      * Whether the dropdown contains items that can be selected.
      * Defaults to true if children contain elements with data-ukt-item or data-ukt-value.
@@ -185,20 +249,18 @@ type Props = {
     keepOpenOnSubmit?: boolean;
     /**
      * Label content for the trigger button (when using single child syntax).
+     * For a nested (submenu) Dropdown, this is the parent item’s content.
      */
     label?: ReactNode;
-    /**
-     * Minimum height for the dropdown body in pixels. Defaults to 30.
-     */
-    minHeightBody?: number;
-    /**
-     * Minimum width for the dropdown body in pixels.
-     */
-    minWidthBody?: number;
     /**
      * Name attribute for the search input (requires isSearchable: true).
      */
     name?: string;
+    /**
+     * Called when the active (highlighted) item changes. Receives the
+     * same payload as onSubmitItem.
+     */
+    onActiveItem?: (payload: Item) => void;
     onClick?: (event: React.MouseEvent<HTMLElement>) => unknown;
     onClose?: () => unknown;
     onMouseDown?: (event: React.MouseEvent<HTMLElement>) => unknown;
@@ -236,6 +298,11 @@ type Item = {
     element: HTMLElement | null;
     event: Event | React.SyntheticEvent<HTMLElement>;
     label: string;
+    /**
+     * Ancestor parent items from the root level down to the item’s
+     * immediate parent. Empty for top-level items.
+     */
+    path: Array<{ label: string; value: string }>;
     value: string;
 };
 ```
@@ -406,7 +473,7 @@ CSS custom properties for the most common low-level placement controls:
 
 - `--uktdd-body-position-area`
 - `--uktdd-body-position-try-fallbacks`
-- `--uktdd-body-translate`
+- `--uktdd-body-gap` (space between the trigger and the body)
 - `--uktdd-body-min-height`
 - `--uktdd-body-min-width`
 - `--uktdd-body-max-height`
@@ -419,7 +486,7 @@ Example:
     --uktdd-body-position-area: bottom span-left;
     --uktdd-body-position-try-fallbacks:
         --uktdd-top-right, --uktdd-bottom-left, --uktdd-top-left;
-    --uktdd-body-translate: -8px 0;
+    --uktdd-body-gap: 8px;
 }
 
 .settings-dropdown .uktdropdown-body {
@@ -430,6 +497,18 @@ Example:
 This approach keeps the public React API small while still allowing precise
 placement and sizing control when a product surface needs it.
 
+Use `--uktdd-body-gap` for the space between the trigger and the body. It
+is applied as a symmetric `margin-block`, so the gap lands on whichever
+side the body attaches to and auto-reverses when `position-try` flips the
+body above the trigger. A margin establishes no containing block, so
+`--uktdd-body-gap` is safe on dropdowns with submenus.
+
+For an offset a gap can’t express — a horizontal nudge, or deliberately
+overlapping the trigger — set `translate` on `.uktdropdown-body` directly.
+A `translate` makes the body a containing block for its fixed-position
+submenus, which constrains and clips them, so reserve it for dropdowns
+without submenus.
+
 ### End-Aligned, Content-Sized Menu
 
 For menus attached to controls near the right edge of the viewport, such as
@@ -453,15 +532,281 @@ This keeps the menu:
 Avoid hardcoding width for this pattern unless the product explicitly needs
 a fixed-size menu.
 
-## Keyboard Navigation & Accessibility
+### Centered Menus
+
+To center a menu over its trigger, use a `span-all` tile, not a `center`
+tile. A `center` tile is only as wide as the trigger, so a body wider than
+the trigger always overflows it — and `position-try` refuses to select a
+fallback that overflows, so a `bottom center` → `top center` setup never
+flips. `span-all` centers over the trigger identically but spans the full
+width, so it flips cleanly and clamps to the viewport near an edge; the
+package’s `position-try-order: most-height` then picks the taller side:
+
+```css
+.centered-menu {
+    --uktdd-body-position-area: bottom span-all;
+    --uktdd-body-position-try-fallbacks: --centered-menu-top;
+}
+
+/* define the flipped fallback in your own CSS */
+@position-try --centered-menu-top {
+    position-area: top span-all;
+}
+```
+
+## Submenus
+
+A `Dropdown` is a disclosure node: a trigger plus a disclosed list.
+Disclosure nodes compose — nest them for depth (submenus), or wrap siblings
+in [`Menubar`](#menubar) for breadth (a menu bar). A submenu is nothing
+more than a `Dropdown` nested inside another dropdown’s body: the nested
+dropdown renders as a **parent item**, an item that discloses a child menu
+instead of submitting a value.
+
+```tsx
+import Dropdown from '@acusti/dropdown';
+
+function FormatMenu() {
+    return (
+        <Dropdown label="Format" onSubmitItem={applyFormat}>
+            <ul>
+                <li data-ukt-item>Bold</li>
+                <li data-ukt-item>Italic</li>
+                <Dropdown label="Align">
+                    <ul>
+                        <li data-ukt-value="left">Left</li>
+                        <li data-ukt-value="center">Center</li>
+                        <li data-ukt-value="right">Right</li>
+                    </ul>
+                </Dropdown>
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+Submenu semantics:
+
+- Parent items disclose; they never submit. `onSubmitItem` fires only for
+  leaf items, and the payload’s `path` reports the leaf’s ancestor parent
+  items (see the [`Item` type](#item-type) above), so leaves with the same
+  value in different submenus are distinguishable.
+- Submenus nest to arbitrary depth — a submenu body can itself contain
+  nested dropdowns.
+- A parent item highlights immediately when it becomes active — via pointer
+  or arrow keys — and discloses its submenu after a short intent delay,
+  with the highlight staying on the parent (macOS-style: moving quickly
+  past parent items never flashes their submenus open, but pausing on one
+  for even a moment shows its submenu). Activating a sibling closes it. →
+  opens the submenu immediately and moves the highlight into it — see
+  [Keyboard Navigation](#keyboard-navigation--accessibility).
+- A parent item’s open state is carried by its `aria-expanded` attribute,
+  which is also the styling hook for submenu visibility.
+- With the pointer, an open submenu tracks mouse intent: moving diagonally
+  from the parent item toward the submenu keeps it open even as the pointer
+  crosses sibling items along the way (the macOS “safe triangle” between
+  the pointer and the submenu’s near edge). Moving straight onto a sibling
+  — or pausing mid-diagonal — switches to that item as usual.
+
+### The `data-ukt-submenu` protocol
+
+Like items, submenus are ultimately declared in the DOM. A nested
+`Dropdown` renders this markup:
+
+```html
+<li data-ukt-item aria-haspopup="menu" aria-expanded="false">
+    Align
+    <ul data-ukt-submenu role="menu">
+        …
+    </ul>
+</li>
+```
+
+You can author that markup directly instead of nesting a `Dropdown`
+component; the two forms behave identically because the component form
+compiles to the attribute form. Rules for direct authoring:
+
+- the `data-ukt-submenu` element must be a descendant of its parent item
+  element
+- in a level whose items include a submenu, mark all of that level’s items
+  explicitly with `data-ukt-item` or `data-ukt-value`; purely flat levels —
+  including flat submenu bodies — fall back to the automatic item-detection
+  heuristic
+- a parent item’s label is its text content excluding the submenu subtree
+
+### Props on a nested Dropdown
+
+Most props keep their meaning, scoped to the submenu:
+
+- `label` (or the first of two children): the parent item’s content
+- `onSubmitItem`: fires for submissions within that subtree only
+- `onActiveItem`, `onOpen`, `onClose`: scoped to the submenu
+- `disabled`: disables the parent item
+- `className`/`style`: applied to the parent item element
+
+Props that only make sense at the top level (`allowCreate`, `allowEmpty`,
+`isOpenOnMount`, `isSearchable`, `keepOpenOnSubmit`, `name`, `placeholder`,
+`tabIndex`, `value`) are ignored on a nested dropdown and warn
+(unconditionally, matching the children-count misuse error).
+
+### Submenu placement and styling
+
+Submenus reuse the dropdown’s anchor-positioning layout model: the expanded
+parent item is the anchor, and the submenu opens at its inline-end,
+top-aligned, falling back to the opposite side when out of bounds.
+Placement custom properties follow the established naming scheme:
+
+- `--uktdd-submenu-position-area` (default: `inline-end span-block-end`)
+- `--uktdd-submenu-position-try-fallbacks`
+- `--uktdd-submenu-gap` (space between the parent item and the submenu;
+  applied as a symmetric `margin-inline`, the inline-axis counterpart to
+  `--uktdd-body-gap`, so it auto-reverses when the submenu flips to the
+  opposite side)
+
+Parent items render a macOS-style disclosure chevron, drawn in CSS with the
+item’s `::after` pseudo-element and colored with `currentColor` so it
+follows the item’s highlight color. Restyle or remove it by overriding
+`[aria-haspopup='menu']::after`.
+
+Submenu bodies set `color: var(--uktdd-body-color)` (default: `canvastext`)
+explicitly — without it, an active parent item’s highlight text color would
+inherit into its submenu’s items, because the submenu is the parent item’s
+DOM child. Set `--uktdd-body-color` alongside `--uktdd-body-bg-color` when
+theming menu colors.
+
+The active path is fully styleable: `data-ukt-active` marks one item per
+open level (a parent item stays active while you navigate its submenu), and
+`aria-expanded="true"` marks open parent items. The default submenu
+visibility rule, shown here for reference:
+
+```css
+[data-ukt-submenu] {
+    display: none;
+}
+
+[aria-expanded='true'] > [data-ukt-submenu] {
+    display: block;
+}
+```
+
+Following macOS, the default styles distinguish the deepest active item —
+the one keyboard input operates on — from its ancestors on the active path.
+The deepest item gets the primary highlight
+(`--uktdd-body-bg-color-hover`); an ancestor parent item — active with the
+highlight deeper inside its submenu, or with the pointer anywhere inside
+its open submenu, even over a separator or disabled item — gets a muted
+highlight (`--uktdd-body-bg-color-path`, gray by default). Surfacing back
+out with ← closes the submenu and restores the parent’s primary highlight.
+The default rule, shown here for reference:
+
+```css
+/* an active item is on the path — not deepest — while a deeper
+   highlight exists or the pointer is inside its submenu */
+[data-ukt-active]:has([data-ukt-submenu] [data-ukt-active]),
+[data-ukt-active]:has([data-ukt-submenu]:hover) {
+    background-color: var(--uktdd-body-bg-color-path);
+    color: var(--uktdd-body-color-path);
+}
+```
+
+### Nested non-menu dropdowns
 
-The dropdown implements full keyboard navigation:
+Nesting means submenu only for menus. A nested `Dropdown` with
+`hasItems={false}` isn’t a menu, so it renders as an independent anchored
+dropdown instead of a parent item — for example, an ℹ️ button next to an
+input in a form dropdown that opens an info popover about the input:
 
-- **Enter/Space**: Open dropdown or select highlighted item
-- **Escape**: Close dropdown
-- **Arrow Up/Down**: Navigate between items
-- **Home/End**: Jump to first/last item
-- **Type characters**: Search for items (when searchable)
+```tsx
+<Dropdown hasItems={false}>
+    Preferences
+    <div>
+        <label>
+            Width <input name="width" />
+        </label>
+        <Dropdown hasItems={false}>
+            <button aria-label="About width">ℹ️</button>
+            <p>Width accepts any CSS length.</p>
+        </Dropdown>
+    </div>
+</Dropdown>
+```
+
+The nested dropdown owns its own interactions: opening it, clicking inside
+it, and navigating it never close or submit the outer dropdown, and Escape
+closes the innermost open dropdown first — a second Escape closes the outer
+one.
+
+## Menubar
+
+`Menubar` combines sibling dropdowns into a single menu, like the system
+menu in the top toolbar of macOS. Each dropdown’s trigger becomes a menubar
+item. See the [Quick Start](#quick-start) for a complete example:
+
+```tsx
+import Dropdown, { Menubar } from '@acusti/dropdown';
+
+<Menubar>
+    <Dropdown label="File">…</Dropdown>
+    <Dropdown label="Edit">…</Dropdown>
+    <Dropdown label="View">…</Dropdown>
+</Menubar>;
+```
+
+Menubar behaviors:
+
+- renders `role="menubar"`; each dropdown trigger is a menubar item
+- at most one menu in the bar is open at a time
+- once any menu is open, hovering another trigger switches to that menu
+  without a click (matching macOS menubar behavior)
+- **←/→** move between menus, wrapping at the ends: with the bar focused
+  they move focus between triggers, and while a menu is open they slide the
+  open menu to the adjacent trigger — unless the active item is a parent
+  item, in which case **→** dives into its submenu instead
+- **↓/Enter/Space** open the focused trigger’s menu
+- **Escape** closes the open menu — including any open submenus — and
+  returns focus to its menubar item
+
+The trigger of the open menu gets an active-state background so it reads as
+selected, like the highlighted item in the macOS menu bar. The default
+tints over whatever background the trigger already has (via
+`--uktdd-menubar-trigger-bg-color-active`, applied to
+`.uktmenubar .uktdropdown.is-open .uktdropdown-trigger`), so it works
+regardless of how the trigger is styled; override the custom property, or
+the rule itself, to restyle it.
+
+`Menubar` supersedes the `group` prop that appeared in earlier versions of
+the `Props` type: `group` was a string-ID way to associate dropdowns that
+was never wired up, and composition expresses the relationship directly.
+
+## Keyboard Navigation & Accessibility
+
+The dropdown implements full keyboard navigation. The model has one rule:
+navigate along the current menu level’s axis, dive into a submenu
+perpendicular to it, surface back out with the opposite key. Menus are
+vertical, so ↑/↓ navigate and →/← dive/surface; a menubar is horizontal, so
+←/→ navigate and ↓ dives.
+
+Keys operate on the **current level**: the level of the deepest highlighted
+item. Note that this can be one level shallower than the deepest open
+submenu — pausing on a parent item discloses its submenu after a short
+intent delay while the highlight stays on the parent, and only → moves the
+highlight into it.
+
+- **Enter/Space**: Open the dropdown; with an item highlighted, select it
+  (leaf items) or open its submenu (parent items)
+- **Escape**: Close the dropdown entirely — including any open submenus —
+  and return focus to the trigger (macOS-style; use ← to back out one level
+  at a time)
+- **Arrow Up/Down**: Navigate between items in the current level
+- **Arrow Right**: Open the highlighted parent item’s submenu (if not
+  already disclosed) and highlight its first item; in a
+  [`Menubar`](#menubar), if the highlighted item is a leaf, slide to the
+  next menu instead
+- **Arrow Left**: Close the highlighted item’s level and return to its
+  parent item; in a `Menubar` with the highlight at the top level of a
+  menu, slide to the previous menu
+- **Home/End**: Jump to first/last item in the current level
+- **Type characters**: Jump to the best-matching item in the current level
 
 For accessibility, the component focuses on semantic HTML structure and
 keyboard navigation. It works best when you use appropriate HTML elements
@@ -482,3 +827,21 @@ The open body element also receives a matching `role` and an `id` so screen
 readers can associate the trigger with its popup. If your custom trigger
 already specifies any of these ARIA props, your values win — the component
 only fills in what you haven’t set.
+
+Submenus and menubars extend the same pattern automatically:
+
+- parent items receive `aria-haspopup="menu"` and `aria-expanded`, and
+  their submenu container receives `role="menu"` and a linked `id`
+- the `Menubar` container receives `role="menubar"`
+
+As with the trigger, any of these you specify yourself win.
+
+One deliberate deviation from the
+[APG menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/): APG
+specifies that Escape closes one menu level per press, while this component
+closes the whole menu at once (matching macOS native menus and Radix UI).
+Level-by-level closing is already covered by ←, so a one-level Escape would
+be redundant; closing everything preserves Escape’s universal “dismiss this
+context” meaning. The part of the APG guidance that matters for assistive
+technology is kept: closing the menu always returns focus to the element
+that opened it.

package/dist/Dropdown.d.ts

@@ -2,6 +2,15 @@ import { type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactEleme
 export type Item = {
     element: MaybeHTMLElement;
     event: Event | SyntheticEvent<HTMLElement>;
+    label: string;
+    /**
+     * Ancestor parent items from the root level down to the item’s
+     * immediate parent. Empty for top-level items.
+     */
+    path: Array<ItemPathEntry>;
+    value: string;
+};
+export type ItemPathEntry = {
     label: string;
     value: string;
 };
@@ -27,18 +36,15 @@ export type Props = {
     children: ChildrenTuple | ReactElement;
     className?: string;
     disabled?: boolean;
-    /**
-     * Group identifier string links dropdowns together into a menu
-     * (like macOS top menubar).
-     */
-    group?: string;
     hasItems?: boolean;
     isOpenOnMount?: boolean;
     isSearchable?: boolean;
     keepOpenOnSubmit?: boolean;
+    /**
+     * Label content for the trigger button (when using single child syntax).
+     * For a nested (submenu) Dropdown, this is the parent item’s content.
+     */
     label?: ReactNode;
-    minHeightBody?: number;
-    minWidthBody?: number;
     /**
      * Only usable in conjunction with {isSearchable: true}.
      * Used as search input’s name.
@@ -56,7 +62,12 @@ export type Props = {
      * Used as search input’s placeholder.
      */
     placeholder?: string;
-    style?: CSSProperties;
+    /**
+     * Applied to the dropdown root element. Also accepts the component’s CSS
+     * custom properties (e.g. `--uktdd-body-min-width`) for per-instance
+     * placement and sizing, which plain `CSSProperties` rejects.
+     */
+    style?: CSSProperties & Record<`--${string}`, string | number | undefined>;
     /**
      * Only usable in conjunction with {isSearchable: true}.
      * Used as search input’s tabIndex.
@@ -70,5 +81,5 @@ export type Props = {
 };
 type ChildrenTuple = [ReactNode, ReactNode] | readonly [ReactNode, ReactNode];
 type MaybeHTMLElement = HTMLElement | null;
-export default function Dropdown({ allowCreate, allowEmpty, children, className, disabled, hasItems, isOpenOnMount, isSearchable, keepOpenOnSubmit, label, minHeightBody, minWidthBody, name, onActiveItem, onClick, onClose, onMouseDown, onMouseUp, onOpen, onSubmitItem, placeholder, style: styleFromProps, tabIndex, value, }: Props): import("react").JSX.Element;
-export {};
+export default function Dropdown(props: Props): import("react").JSX.Element;
+export { default as Menubar, type MenubarProps } from './Menubar.js';