@acusti/dropdown 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -190,20 +190,33 @@ is the one you want.
 ## Color Scheme
 
 The default colors are drawn from CSS system colors (`Canvas`,
-`CanvasText`, `Highlight`, `HighlightText`) and `color-mix()` blends
-against `CanvasText`, rather than fixed light-mode values, so the dropdown
-looks native in whichever color scheme is in effect.
-`--uktdd-body-box-shadow` is the exception — a fixed `rgba(0, 0, 0, 0.25)`
-rather than a scheme-aware mix, since mixing in `CanvasText` turns it into
-a diffuse white glow in dark mode instead of a shadow. `color-scheme` (set
-via `--uktdd-color-scheme`, default `inherit`) is left to inherit from the
-host page rather than forced to `light dark`: the popover is page content,
-not OS chrome, so it matches whatever scheme the page itself has opted into
-— light, if the page hasn’t adopted dark mode — rather than following the
-OS/browser preference regardless of the page. Set `--uktdd-color-scheme` to
-`light dark` (or `light`/`dark`) to follow the user’s preference
-irrespective of the host page instead. Override any of the
-`--uktdd-body-bg-color*` / `--uktdd-body-color*` /
+`CanvasText`, `Highlight`, `HighlightText`) rather than fixed light-mode
+values, so the dropdown looks native in whichever color scheme is in
+effect.
+
+The tints layered over the body — `--uktdd-body-bg-color-selected`,
+`--uktdd-body-border-color`, and `--uktdd-body-bg-color-path` — are
+`color-mix()` blends that derive from the body’s own foreground and
+background rather than from `CanvasText`/`Canvas` directly, so theming the
+surface carries them with it: set `--uktdd-body-color` and
+`--uktdd-body-bg-color` and the selected tint, hairline border, and
+active-path step all re-derive from the pair you set. That matters because
+a `var()` inside a custom property is substituted where that property is
+declared, so a `:root` default blended against `CanvasText` would freeze to
+the ambient color scheme before a consumer’s override could reach it — a
+dark menu on a light page would keep a black hairline it can’t show. Each
+one is still a plain custom property, so setting it directly overrides the
+derived default outright. `--uktdd-body-box-shadow` is the exception — a
+fixed `rgba(0, 0, 0, 0.25)` rather than a scheme-aware mix, since mixing in
+`CanvasText` turns it into a diffuse white glow in dark mode instead of a
+shadow. `color-scheme` (set via `--uktdd-color-scheme`, default `inherit`)
+is left to inherit from the host page rather than forced to `light dark`:
+the popover is page content, not OS chrome, so it matches whatever scheme
+the page itself has opted into — light, if the page hasn’t adopted dark
+mode — rather than following the OS/browser preference regardless of the
+page. Set `--uktdd-color-scheme` to `light dark` (or `light`/`dark`) to
+follow the user’s preference irrespective of the host page instead.
+Override any of the `--uktdd-body-bg-color*` / `--uktdd-body-color*` /
 `--uktdd-body-box-shadow` custom properties to theme it further.
 `--uktdd-menubar-trigger-bg-color-active` blends against `currentColor`
 instead, so it stays visible against a menubar trigger that the consumer
@@ -254,6 +267,16 @@ type Props = {
      */
     children: ReactNode | [ReactNode, ReactNode];
     className?: string;
+    /**
+     * Prevents the dropdown from opening via user interaction: pointer,
+     * Enter/Space, hover (props.openOnHover), typing in a custom trigger’s
+     * text input, and Menubar navigation onto it alike. The generated trigger
+     * carries the native disabled attribute; a custom trigger can be any
+     * element, so it receives aria-disabled instead. Inside a Menubar the
+     * member is skipped. A dropdown disabled while already open still closes
+     * normally (as does one started open with props.isOpenOnMount, which
+     * disabled doesn't override).
+     */
     disabled?: boolean;
     /**
      * Whether the dropdown contains items that can be selected.
@@ -1003,7 +1026,23 @@ import Dropdown, { Menubar } from '@acusti/dropdown';
 
 Menubar behaviors:
 
-- renders `role="menubar"`; each dropdown trigger is a menubar item
+- renders `role="menubar"`, and each member’s trigger is a real
+  `role="menuitem"` that the bar owns directly — the wrapper elements
+  between them are neutralized with `role="none"`, since a generic element
+  in between would leave the menubar owning no menu items at all. A
+  searchable member is exempt from the `menuitem` role: its trigger is a
+  `combobox`, so it keeps its own semantics rather than being mislabelled.
+  Its wrappers are still neutralized, but note that a `combobox` isn’t
+  valid menubar content in the first place — no markup arrangement fixes
+  that, so a search field belongs **outside** the `<Menubar>` (a container
+  mixing menus and other controls is a `toolbar`, not a menubar)
+- the bar’s **menu items share a single tab stop**, as the APG menubar
+  pattern expects: one `menuitem` trigger is tabbable and the rest are
+  reached with ←/→. The tab stop follows the trigger you last focused, so
+  tabbing away and back returns you where you were; it starts on (and falls
+  back to) the first enabled member. A searchable member sits outside this
+  — it’s a `combobox`, not a menu item, so it keeps its own native tab stop
+  and never takes the bar’s
 - at most one menu in the bar is open at a time
 - opening a trigger’s menu (by click or keyboard) engages the bar
   (menu-mode). While engaged, hovering or focusing another trigger switches
@@ -1015,6 +1054,10 @@ Menubar behaviors:
 - a deliberate dismissal — **Escape**, a click outside the bar, or
   selecting an item — leaves menu-mode, after which hovering a trigger no
   longer opens its menu until a menu is opened again to re-engage the bar
+- a `disabled` member is passed over rather than landed on, the way macOS
+  skips a disabled menu: ←/→ move to the next enabled trigger, hovering it
+  leaves the open menu alone, and if no other member is enabled the open
+  menu simply stays put
 - **←/→** 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
@@ -1054,7 +1097,8 @@ highlight into it.
 - **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 Up/Down**: Navigate between items in the current level; with ⌥ or
+  ⌘ held, jump to the first/last item of that 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
@@ -1062,7 +1106,9 @@ highlight into it.
 - **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
+- **Home/End**: Jump to first/last item in the current level. Like ←/→,
+  they stand down while a text input has focus (a searchable dropdown’s own
+  input, or one inside a custom trigger), where they move the caret instead
 - **Type characters**: Jump to the best-matching item in the current level
 
 For accessibility, the component focuses on semantic HTML structure and
@@ -1070,13 +1116,22 @@ keyboard navigation. It works best when you use appropriate HTML elements
 in your dropdown content (like `<ul>` and `<li>` for lists, `<button>`
 elements for actions, etc.).
 
+The ARIA it adds is a best effort from what it can control: it annotates
+the DOM it renders and the shapes it recognizes, but never overwrites a
+value you pass. So when you provide a completely custom trigger, it is
+possible to end up with ARIA that doesn’t hold together. The safest thing
+if you go full custom is to take over the ARIA as well.
+
 ### ARIA attributes
 
 The trigger automatically receives `aria-haspopup`, `aria-expanded`, and
-`aria-controls` pointing to the open body. The popup role is chosen based
-on the dropdown’s mode:
+`aria-controls` pointing to the open body. The component does its best to
+also apply the correct roles and attributes with custom triggers, but if
+you are customizing in that way, consider also providing the appropriate
+ARIA. The popup role is chosen based on the dropdown’s mode:
 
-- `aria-haspopup="listbox"` when `isSearchable` is true (combobox pattern)
+- `aria-haspopup="listbox"` when `isSearchable` is true (combobox pattern —
+  see below)
 - `aria-haspopup="menu"` when `hasItems` is true (the default)
 - `aria-haspopup="dialog"` when `hasItems={false}` (interactive content)
 
@@ -1085,6 +1140,34 @@ 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.
 
+The body is also named, via `aria-labelledby`, by whatever names the
+trigger — required for the `dialog` role and worth having on the others, so
+the popup is announced as “Alignment menu” rather than a bare “menu”. The
+name comes from `props.label` when you pass one (always text, and the same
+name the trigger takes), and otherwise from the trigger element itself. The
+component fills in the trigger’s `id` for this; a custom trigger with an
+`id` of its own keeps it, and the body points at that instead.
+
+Two shapes end up with no name, both because the trigger has none to give:
+
+- **A text input trigger.** `aria-labelledby` resolves a text input to its
+  _value_, so pointing the popup at one would name it after whatever the
+  user has typed. The component leaves the popup unnamed instead — for a
+  searchable dropdown’s trigger (a text input by definition, generated or
+  custom) and for a custom trigger that is itself an `<input>` or
+  `<textarea>`. A text input _nested_ inside a custom trigger leaks its
+  value the same way but isn’t detectable from the element alone, so it’s
+  on you to pass `props.label` there.
+- **An empty generated trigger**: single-child syntax with no `props.label`
+  renders a `<button>` with nothing in it, which has no accessible name of
+  its own to lend. This matters most for `hasItems={false}`, where the
+  popup is a `dialog` and an unnamed dialog is an ARIA violation.
+
+In both cases the trigger is unnamed too, and `props.label` fixes both at
+once. (A custom trigger’s own `aria-label` names the trigger, but the popup
+can’t inherit it — `aria-labelledby` would resolve the input to its value —
+so pass `props.label` when you want the popup named as well.)
+
 Item roles are filled in the same way when the body opens: items receive
 `role="option"` in a searchable (listbox) dropdown or `role="menuitem"` in
 a menu (always `menuitem` inside a submenu), and the `<ul>`/`<ol>` wrappers
@@ -1102,6 +1185,55 @@ which case the component leaves selection ARIA entirely to you, as with any
 ARIA you set. The persistent tint on the selected item is themeable via the
 `--uktdd-body-bg-color-selected` custom property.
 
+### The searchable trigger is a combobox
+
+A searchable dropdown’s trigger declares `role="combobox"` together with
+`aria-autocomplete="list"`, which describes what typing actually does here:
+suggestions appear in the popup, and nothing is completed inline in the
+input.
+
+For a custom trigger, the role is filled in only when the trigger element
+is a single-line text input. A trigger that merely wraps an input is left
+alone. Same with a `<textarea>`, since a combobox is single-line. (A
+textarea trigger still counts as a text input for naming, so it can’t name
+the popup either.) As always, a `role` or `aria-autocomplete` you set
+yourself wins.
+
+### The active item and `aria-activedescendant`
+
+DOM focus stays on the trigger for as long as the dropdown is open — the
+highlight moves via a `data-ukt-active` attribute rather than by moving
+focus. On its own that would make navigation silent to a screen reader, so
+the trigger carries `aria-activedescendant` pointing at the highlighted
+item, and it is kept in sync however the highlight moves: arrow keys,
+Home/End, typeahead, hover, diving into and out of submenus, and the
+reveal-on-open above. It’s removed when nothing is highlighted and when the
+dropdown closes, so it never dangles at an item that has unmounted.
+
+Pointing at an item means items need ids, and the component mints them from
+the same `useId` behind the trigger and body ids, suffixed with the item’s
+**index path** — its index at each level from the root level down. So
+`<bodyId>-2-1` is the second item of the submenu belonging to the third
+top-level item. An item with an `id` of your own keeps it and is pointed at
+as-is.
+
+Ids are minted when an item becomes active rather than in the open-time
+annotation pass, which means items rendered into an already-open body —
+async-loaded, or filtered by your own search — get one too, even though
+that pass doesn’t reach them.
+
+Because an index path is a snapshot of a position, a generated id is
+**re-derived every time its item becomes active**, so filtering or
+reordering an open body doesn’t leave items holding ids that describe where
+they used to be. Treat generated ids as internal: they’re minted and
+consumed within a single open, and they move as your list moves. Ids you
+set yourself are never touched or recomputed.
+
+The indices come from the navigable items, so a disabled item shifts the
+ids after it. If the highlighted item leaves the DOM entirely — filtered
+away while the body is open — the reference is cleared rather than left
+dangling.
+
 Submenus and menubars extend the same pattern automatically:
 
 - parent items receive `aria-haspopup="menu"` and `aria-expanded`, and

package/dist/Dropdown.d.ts

@@ -41,6 +41,16 @@ export type Props = {
      */
     children: ChildrenTuple | ReactElement;
     className?: string;
+    /**
+     * Prevents the dropdown from opening via user interaction: pointer,
+     * Enter/Space, hover (props.openOnHover), typing in a custom trigger’s
+     * text input, and Menubar navigation onto it alike. The generated trigger
+     * carries the native disabled attribute; a custom trigger can be any
+     * element, so it receives aria-disabled instead. Inside a Menubar the
+     * member is skipped. A dropdown disabled while already open still closes
+     * normally (as does one started open with props.isOpenOnMount, which
+     * disabled doesn't override).
+     */
     disabled?: boolean;
     hasItems?: boolean;
     isOpenOnMount?: boolean;