@acusti/dropdown 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -123,13 +123,17 @@ CSS-first sizing model:
 - The dropdown body is an anchored shell
 - The inner content region becomes scrollable only when the content exceeds
   the available space
-- Placement fallbacks are handled with `position-try-order: most-height`
+- The body opens in its authored direction whenever it fits there, falling
+  back through the other placements in order and only squeezing-to-scroll
+  when it fits nowhere at its natural size (see
+  [Changing the Default Direction](#changing-the-default-direction))
 
 This means the dropdown tends to:
 
 - stay content-sized when the contents are small
-- expand to the available viewport space when more room is needed
-- become scrollable when the contents exceed that space
+- open in the direction you asked for, as long as that side can hold it
+- expand to the available viewport space, and become scrollable, only when
+  the contents exceed the room the chosen side has
 
 Internally, the dropdown renders:
 
@@ -292,16 +296,33 @@ type Props = {
      */
     tabIndex?: number;
     /**
-     * Current value of the search input (requires isSearchable: true).
-     * Used for controlled components and change detection.
+     * The dropdown’s controlled value. Pass a bare identifier when an item’s
+     * stored value and its displayed label are the same, or a { label, value }
+     * pair when they differ (e.g. a human-readable label shown for a stored
+     * id) — the same { label, value } shape onSubmitItem reports back. Used for
+     * change detection (skipping onSubmitItem when the already-selected item is
+     * re-submitted); the label is shown as the search input’s value when
+     * isSearchable is true. A bare identifier resolves to its label from the
+     * matching child’s data-ukt-value in the body, so children whose value
+     * and label differ need no explicit label.
      */
-    value?: string;
+    value?: ItemValue | string;
 };
 ```
 
-### Item Type
+### Item Types
+
+Both types are exported alongside the component:
 
 ```ts
+/**
+ * A { label, value } pair naming an item: value is the stored value (the
+ * item’s data-ukt-value) and label is its displayed text. Accepted by the
+ * value prop when an item’s value and label differ; also the shape of an
+ * Item’s path entries.
+ */
+type ItemValue = { label: string; value: string };
+
 type Item = {
     element: HTMLElement | null;
     event: Event | React.SyntheticEvent<HTMLElement>;
@@ -310,7 +331,7 @@ type Item = {
      * 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 }>;
+    path: Array<ItemValue>;
     value: string;
 };
 ```
@@ -514,9 +535,9 @@ Example:
 
 ```css
 .settings-dropdown {
-    --uktdd-body-position-area: bottom span-left;
+    --uktdd-body-position-area: block-end span-inline-start;
     --uktdd-body-position-try-fallbacks:
-        --uktdd-top-right, --uktdd-bottom-left, --uktdd-top-left;
+        --uktdd-top-end, --uktdd-bottom-start, --uktdd-top-start;
     --uktdd-body-gap: 8px;
 }
 
@@ -528,6 +549,65 @@ Example:
 This approach keeps the public React API small while still allowing precise
 placement and sizing control when a product surface needs it.
 
+### Changing the Default Direction
+
+`--uktdd-body-position-area` and `--uktdd-body-position-try-fallbacks`
+always change together. `--uktdd-body-position-area` is the primary
+placement, used whenever it fits in the viewport — that’s what actually
+determines the direction a dropdown opens by default. The fallbacks list is
+only consulted when the primary placement doesn’t fit, so overriding it
+alone changes nothing in the common case where the primary already fits.
+Overriding the primary alone works, but leaves behind a fallback cascade
+tuned for the old primary — in a cramped viewport, the dropdown can fall
+back toward the direction you just moved away from.
+
+The four `@position-try` blocks the component ships (`--uktdd-top-start`,
+`--uktdd-top-end`, `--uktdd-bottom-start`, `--uktdd-bottom-end`) are named
+for the aligned edge, not the direction the body extends toward: `start`
+opens with the body’s inline-start edge flush with the trigger’s
+inline-start edge (extending toward inline-end), and `end` is the mirror
+image. This also means they’re RTL-safe — `start`/`end` follow the
+document’s writing direction the way `left`/`right` wouldn’t. The values
+pair `block-start`/`block-end` with `span-inline-start`/`span-inline-end`
+rather than `top`/`bottom` — `position-area` doesn’t allow mixing a
+physical keyword on one axis with a logical one on the other — though
+`block-start`/`block-end` read as `top`/`bottom` in the near-universal
+horizontal-tb writing mode.
+
+Pick the row matching the direction you want, and set both variables to its
+pair:
+
+| Direction                           | `--uktdd-body-position-area`    | `--uktdd-body-position-try-fallbacks`                         |
+| ----------------------------------- | ------------------------------- | ------------------------------------------------------------- |
+| Bottom, start-aligned (the default) | `block-end span-inline-end`     | `--uktdd-top-start, --uktdd-bottom-end, --uktdd-top-end`      |
+| Bottom, end-aligned                 | `block-end span-inline-start`   | `--uktdd-top-end, --uktdd-bottom-start, --uktdd-top-start`    |
+| Top, start-aligned                  | `block-start span-inline-end`   | `--uktdd-bottom-start, --uktdd-top-end, --uktdd-bottom-end`   |
+| Top, end-aligned                    | `block-start span-inline-start` | `--uktdd-bottom-end, --uktdd-top-start, --uktdd-bottom-start` |
+
+For example, to make a dropdown open upward and end-aligned (useful for a
+trigger pinned to the bottom of the viewport, near the inline-end edge):
+
+```css
+.bottom-toolbar-dropdown {
+    --uktdd-body-position-area: block-start span-inline-start;
+    --uktdd-body-position-try-fallbacks:
+        --uktdd-bottom-end, --uktdd-top-start, --uktdd-bottom-start;
+}
+```
+
+See the [`DirectionRecipes` story][] for a live demo of all four.
+
+[`DirectionRecipes` story]:
+    https://uikit.acusti.ca/?path=/docs/uikit-controls-Dropdown--docs#direction-recipes
+
+The primary placement wins whenever the body fits there at its natural
+size, then the fallbacks are tried in order — the body opens in the
+direction you asked for as long as that side can hold it, and never flips
+to the opposite side just because the viewport happens to have more empty
+space there. Only when the body fits in none of those placements does it
+size itself to the block-axis space its preferred side has and let the
+content scroll, so it never overflows the viewport or covers the trigger.
+
 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
@@ -548,9 +628,9 @@ the menu size itself from its contents.
 
 ```css
 .avatar-menu {
-    --uktdd-body-position-area: bottom span-left;
+    --uktdd-body-position-area: block-end span-inline-start;
     --uktdd-body-position-try-fallbacks:
-        --uktdd-top-right, --uktdd-top-left, --uktdd-bottom-right;
+        --uktdd-top-end, --uktdd-top-start, --uktdd-bottom-end;
 }
 ```
 
@@ -570,8 +650,9 @@ 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:
+width, so it flips cleanly and clamps to the viewport near an edge. The
+menu opens below by default and flips above only when it doesn’t fit below;
+list the flipped fallback so that flip is available:
 
 ```css
 .centered-menu {
@@ -620,7 +701,7 @@ 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
+  items (see the [`Item` type](#item-types) 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.
@@ -647,7 +728,7 @@ Like items, submenus are ultimately declared in the DOM. A nested
 ```html
 <li data-ukt-item aria-haspopup="menu" aria-expanded="false">
     Align
-    <ul data-ukt-submenu role="menu">
+    <ul data-ukt-submenu role="menu" popover="manual">
         …
     </ul>
 </li>
@@ -659,6 +740,9 @@ compiles to the attribute form. Rules for direct authoring:
 
 - the `data-ukt-submenu` element must be a descendant of its parent item
   element
+- the submenu discloses in the top layer as a popover; the component sets
+  `popover="manual"`, and the engine adds it if your markup omits it, so
+  you don’t manage `display` (visibility follows the popover open state)
 - 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
@@ -686,8 +770,12 @@ already discloses on hover intent — see [Submenus](#submenus) — so
 
 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:
+top-aligned, falling back to the opposite side when out of bounds. Like the
+body, a submenu renders in the top layer (`popover="manual"`), so its
+containing block is the viewport — no ancestor (including the body’s own
+top-layer box) can capture it and clip or shift its placement, which keeps
+it flush to the parent item’s edge across browsers. Placement custom
+properties follow the established naming scheme:
 
 - `--uktdd-submenu-position-area` (default: `inline-end span-block-end`)
 - `--uktdd-submenu-position-try-fallbacks`
@@ -709,18 +797,12 @@ 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;
-}
-```
+`aria-expanded="true"` marks open parent items. Submenu visibility is not a
+`display` rule you own: each submenu is a `popover="manual"` element the
+component shows and hides (via `showPopover`/`hidePopover`) as its parent
+item expands and collapses, so it discloses in the top layer and the UA’s
+`:popover-open` state controls whether it renders. Don’t set `display` on
+`[data-ukt-submenu]` — it would fight that state.
 
 Following macOS, the default styles distinguish the deepest active item —
 the one keyboard input operates on — from its ancestors on the active path.
@@ -879,6 +961,23 @@ 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.
 
+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
+around them receive `role="presentation"` so the listbox or menu owns its
+items directly rather than through an intervening list. A natively
+interactive item (a button, link, or input) or one with a role you set
+yourself keeps its own role.
+
+Opening also reveals the current selection: the item matching `props.value`
+becomes the active item (so keyboard navigation starts from the current
+selection) and is scrolled into view. In a searchable (listbox) dropdown it
+additionally receives `aria-selected="true"` (`aria-selected` isn’t valid
+on a `menuitem`) — unless you author `aria-selected` on items yourself, in
+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.
+
 Submenus and menubars extend the same pattern automatically:
 
 - parent items receive `aria-haspopup="menu"` and `aria-expanded`, and

package/dist/Dropdown.d.ts

@@ -7,10 +7,16 @@ export type Item = {
      * Ancestor parent items from the root level down to the item’s
      * immediate parent. Empty for top-level items.
      */
-    path: Array<ItemPathEntry>;
+    path: Array<ItemValue>;
     value: string;
 };
-export type ItemPathEntry = {
+/**
+ * A { label, value } pair naming an item: `value` is the stored value (the
+ * item’s data-ukt-value) and `label` is its displayed text. Accepted by the
+ * value prop when an item’s value and label differ; also the shape of an
+ * Item’s path entries.
+ */
+export type ItemValue = {
     label: string;
     value: string;
 };
@@ -82,10 +88,18 @@ export type Props = {
      */
     tabIndex?: number;
     /**
-     * Used as search input’s value if props.isSearchable === true
-     * Used to determine if value has changed to avoid triggering onSubmitItem if not
+     * The dropdown’s controlled value. Pass a bare identifier when an item’s
+     * stored value and its displayed label are the same, or a { label, value }
+     * pair when they differ (e.g. a human-readable label shown for a stored
+     * id) — the same { label, value } shape onSubmitItem reports back. The
+     * value determines whether the value has changed, to avoid triggering
+     * onSubmitItem when the already-selected item is re-submitted; the label is
+     * used as the search input’s value when props.isSearchable === true. A bare
+     * identifier is resolved to its label from the matching child’s
+     * data-ukt-value in the body — so children whose value and label differ
+     * need no explicit label; a { label, value } pair states it.
      */
-    value?: string;
+    value?: ItemValue | string;
 };
 type ChildrenTuple = [ReactNode, ReactNode] | readonly [ReactNode, ReactNode];
 type MaybeHTMLElement = HTMLElement | null;