@keenmate/web-multiselect 2.0.0-rc04 → 2.0.0-rc06

package/README.md

@@ -21,90 +21,19 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - Custom rendering callbacks for options, badges, and group headers.
 - Form integration via standard hidden inputs (FormData-compatible).
 
-## What's New in v2.0.0-rc04
-
-**Phone search — one-tap clear and a keyboard that gets out of the way** — The
-full-screen search sheet gained the two things it was missing on touch. A clear button
-now sits at the trailing edge of the search field (a distinct Lucide `search-x` glyph,
-so it doesn't read as a second close ✕) to wipe the term in one tap and restore the full
-list. And the soft keyboard, which used to stay pinned open once you focused the field,
-now tucks away on the three natural "done typing" gestures — scrolling the list, tapping
-an option, or pressing Enter/Search — while never dismissing itself mid-type from a
-programmatic scroll-to-match.
-
-**A close button you can make your own** — The full-screen close ✕ is now a themeable
-chip: the new `--ms-fullscreen-close-bg`, `--ms-fullscreen-close-border`, and
-`--ms-fullscreen-close-border-radius` variables turn the bare glyph into a bordered
-button (à la a command-palette close) while the defaults keep it a plain round ✕. Its
-tap target was also fixed — the previously-dead padding around the button in the sheet's
-top-trailing corner (the natural place to reach) now dismisses the sheet, without ever
-stealing taps from the first option row or the search field.
-
-**Right presentation on every device, via core rc07** — This release pins
-`@keenmate/web-components-core` at `1.0.0-rc07` and adopts its reworked
-`resolvePresentation` / `classifyDevice` API. Behavior is unchanged — full-screen on
-phones, floating on tablet and desktop — with one refinement from the new capability
-gate: a narrowed desktop window (fine pointer, hover) now stays `desktop` and keeps its
-floating dropdown at any width, instead of ever flipping to the full-screen sheet.
-
-See `CHANGELOG.md` for the full list.
-
-## What's New in v2.0.0-rc03
-
-**Full-screen dropdown on phones (`mobile-presentation`).** On a phone, a dropdown
-that floats next to the input fights the on-screen keyboard. `<web-multiselect>`
-now detects phones and, by default (`mobile-presentation="auto"`), presents the
-open dropdown as a **full-screen overlay** with its own search field and close (✕)
-button — while desktop and tablets keep the familiar floating panel, unchanged. A
-"phone" is a touch-primary device whose **shorter** viewport side is `< 600px`
-(the Material `sw600dp` line), so a phone in **landscape** still gets the overlay
-and tablets never do. The **selected-items popover** goes full-screen on phones
-too, with a matching header. The phone view is scaled up ~1.2× for comfortable
-touch targets via the `--ms-fullscreen-rem` knob (default `12px` vs the base
-`--ms-rem: 10px`) — one value grows rows, text, checkboxes, header and search
-together. Override the mode per instance with `mobile-presentation="floating"`
-(anchored panel everywhere) or `"fullscreen"` (force the overlay on any device —
-handy for previews). Theme it with the new `--ms-fullscreen-*` CSS variables.
+## What's New in v2.0.0-rc06
 
-```html
-<!-- auto (default): full-screen on phones, floating on desktop/tablet -->
-<web-multiselect mobile-presentation="auto"></web-multiselect>
+- **Tree search — `search-mode="navigate"` now works on trees** — Navigate mode (keep the whole list on screen and jump focus between matches instead of filtering it down) was silently ignored on tree data: the tree search path always collapsed the hierarchy to matches + ancestors and cleared the match set *before* the navigate branch could run, so `search-mode="navigate"` on a `path-member` tree did nothing. It now honors the mode — the always-expanded tree stays fully visible, matching rows get the highlight, focus jumps to the first match, and the match set powers `Ctrl`+`ArrowUp`/`ArrowDown` on desktop plus the fullscreen `N of M` match navigator (count + prev/next) on touch, which now shows for trees too. Filter mode (the default) is unchanged.
 
-<!-- never go full-screen -->
-<web-multiselect mobile-presentation="floating"></web-multiselect>
+- **Fullscreen overlay — no longer slips under the system bar on pages with horizontal overflow** — A host page that overflows sideways (e.g. an unbreakable-wide token in a heading) makes the mobile browser shrink-to-fit — it zooms the page out so the overflow fits, splitting the visual viewport from the layout viewport. Because the fullscreen dropdown and selected-items popover are `position: fixed` (anchored to the layout viewport), that zoom left them inset from the physical screen and their top edge slid under the status/nav bar — easily misread as a safe-area issue, but `env(safe-area-inset-*)` is `0` in that state. Opening a fullscreen sheet now clamps `overflow-x: hidden` on `<html>` (restored on close), which removes the overflow so the browser drops the zoom and the sheet sits flush — regardless of the host page. No-op when the page doesn't overflow, and touches only `<html>` so it doesn't fight core's body scroll-lock.
 
-<!-- always full-screen (preview the mobile view on desktop) -->
-<web-multiselect mobile-presentation="fullscreen"></web-multiselect>
-```
+- **Fullscreen selected-items popover — Back gesture closes it instead of leaving the page** — The options dropdown already traps the Android Back gesture so it dismisses the fullscreen sheet rather than navigating away, but the selected-items popover — which also goes fullscreen on phones — skipped that guard, so a Back gesture fell through to a real `history(-1)` and left the page (losing the selection view and any unsaved state). The popover now pushes and consumes the same history entry as the dropdown, and the shared handler closes whichever overlay is open. Floating popovers are unaffected.
+
+- **Search results — the current match no longer nudges the row sideways** — The leading accent bar on the current match was a real `border-inline-start` that existed only in the matched state, so the checkbox and label jumped ~3px inward the instant a row became the match — content visibly "walked" as you stepped between results. The bar is now an out-of-flow `::before` overlay pinned to the leading edge, so it paints the same accent without touching the row's box model. Still themeable via `--ms-option-border-matched` and RTL-mirrored.
+
+## What's New in v2.0.0-rc05
 
-This is powered by device/viewport/orientation detection in
-[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core)
-(via `BlissElement`'s `environmentChanged` hook), which this release pins at
-**1.0.0-rc06** — rc04 also **dropped `loglevel`** as a transitive runtime
-dependency. The floating dropdown additionally gains a viewport-width safety cap so
-a wide panel can't overflow the screen edge.
-
-**Right-to-left, done properly — including runtime switching.** Give the element (or
-any ancestor) `dir="rtl"` and the whole component mirrors: the toggle and in-input
-counter move to the left, checkboxes sit on the right of each row, badges reverse,
-and the full-screen overlay mirrors too (search/close swap sides, the match
-navigator flips). RTL is now built on CSS **logical properties** driven by the
-inherited direction, which fixes cases that silently never worked before — the
-dropdown, hint, and selected-popover live in the shadow root, so the old `.ms--rtl`
-override rules never reached them. And flipping `dir` at runtime — an app-wide
-language switch — re-mirrors the live picker without a rebuild (via core rc06's new
-`directionChanged` hook).
-
-**Friendlier phone browsing.** The full-screen sheet opens with the **keyboard
-closed** by default, so you can scan long lists and reach the bottom action buttons
-before typing (opt into immediate type-to-filter with `fullscreen-autofocus="true"`).
-The phone **Back gesture** now closes the sheet instead of navigating the page away.
-In `search-mode="navigate"`, an on-screen **match navigator** (an `N of M` count plus
-prev/next buttons) stands in for the desktop `Ctrl`+`Arrow` match-stepping that touch
-can't do — and the focused match now stays visible above the keyboard instead of
-scrolling behind it. Tapping an option no longer pops the keyboard mid-browse.
-
-See `CHANGELOG.md` for the full list.
+- **Full-screen overlays — content no longer clipped under landscape system bars** — Rotating a phone to landscape with the full-screen dropdown (or the selected-items popover) open used to push the search field and option rows *under* the Android navigation bar and camera cutout — the field looked "too wide for the screen" and each row's leading edge was hidden. Cause: the sheets are `width: 100vw` (the full physical width) with no safe-area handling. They now set `box-sizing: border-box` and inset their content box by `env(safe-area-inset-{top,right,bottom,left})` on all four edges — the background stays edge-to-edge (full-bleed, no corner gaps) while the header · list · actions column is pulled into the visible region, and the fullscreen toast lifts above the bottom safe area. `env()` resolves to `0` unless the host page opts into edge-to-edge, so this is a no-op on non-cutout / letterboxed pages — a fix where needed, never a regression. Consumer note: for the insets to engage the host page must set `<meta name="viewport" content="… viewport-fit=cover">` (the mobile examples/tests now do).
 
 ## Demos & docs
 

package/custom-elements.json

@@ -541,6 +541,15 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "overflowXClamp",
+              "type": {
+                "text": "{ html: string } | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
             {
               "kind": "field",
               "name": "keyboardInsetCleanup",
@@ -1178,6 +1187,17 @@
               ],
               "description": "Tree mode: derive the visible list from an **external** set of matched\r\noptions — e.g. the results returned by `searchCallback` — keeping each\r\nmatch's ancestors so indentation stays coherent. This is the async-search\r\nanalogue of `rebuildTreeVisible`: the matching is done by the caller (their\r\nown index/engine) instead of a local substring test, but ancestor\r\npreservation and `treeNodes`/`filteredOptions` index-alignment still happen\r\nhere. Pass all options to show the whole tree."
             },
+            {
+              "kind": "method",
+              "name": "rebuildTreeVisibleForNavigate",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "Tree + `search-mode=\"navigate\"`: keep the ENTIRE tree visible (the tree is always\r\nfully expanded, so `flatNodes` is the whole thing) and record which visible rows\r\nmatch the term in `matchingIndices` — the flat-list navigate behavior, but over\r\n`treeNodes`. Filter mode collapses the hierarchy to matches + ancestors; navigate\r\nmode instead leaves the structure intact so the user can jump between matches\r\n(Ctrl+Arrow on desktop, the fullscreen navigator on touch). Returns the index of\r\nthe first match, or -1 (no term / no matches), so the caller can set focus."
+            },
             {
               "kind": "method",
               "name": "detectRTL",
@@ -1971,6 +1991,28 @@
               },
               "description": "Restore page scroll (no-op if it wasn't locked)."
             },
+            {
+              "kind": "method",
+              "name": "clampDocumentOverflowX",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Clip the host document's horizontal overflow while a fullscreen sheet is open.\r\n\r\nA page that overflows horizontally (e.g. an unbreakable-wide token in a heading)\r\nmakes the mobile browser SHRINK-TO-FIT: it zooms the page out so the overflow fits,\r\nwhich desyncs the visual viewport from the layout viewport. Our fullscreen sheet is\r\n`position: fixed` — anchored to the LAYOUT viewport — so under that zoom it no longer\r\nlands flush against the physical screen edges, and the top slips under the system bar\r\n(looks like \"the bar covers the sheet\"). This is NOT a safe-area problem; safe-area\r\ninsets are 0 in that state. Clamping `overflow-x: hidden` on <html>/<body> removes the\r\noverflow, so the browser drops the zoom and the sheet sits flush. Complements\r\nlockBodyScroll() (vertical axis); the saved inline value is restored on close.\r\n\r\nOnly <html> is touched (not <body>): clipping the root's horizontal overflow is\r\nenough to collapse the scrollWidth and cancel the shrink-to-fit, and it avoids\r\nconflicting with core's lockBodyScroll(), which owns <body>'s `overflow`. Idempotent."
+            },
+            {
+              "kind": "method",
+              "name": "releaseDocumentOverflowX",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Restore the <html> `overflow-x` clamped by clampDocumentOverflowX() (no-op if unset)."
+            },
             {
               "kind": "method",
               "name": "observeKeyboardInset",

package/dist/index.d.ts

@@ -783,6 +783,7 @@ export declare class WebMultiSelect<T = any> {
     private fullscreenNavPrev;
     private fullscreenNavNext;
     private bodyScrollUnlock;
+    private overflowXClamp;
     private keyboardInsetCleanup;
     private overlayHistoryActive;
     private readonly onOverlayPopstate;
@@ -916,6 +917,16 @@ export declare class WebMultiSelect<T = any> {
      * here. Pass all options to show the whole tree.
      */
     private rebuildTreeVisibleFromMatches;
+    /**
+     * Tree + `search-mode="navigate"`: keep the ENTIRE tree visible (the tree is always
+     * fully expanded, so `flatNodes` is the whole thing) and record which visible rows
+     * match the term in `matchingIndices` — the flat-list navigate behavior, but over
+     * `treeNodes`. Filter mode collapses the hierarchy to matches + ancestors; navigate
+     * mode instead leaves the structure intact so the user can jump between matches
+     * (Ctrl+Arrow on desktop, the fullscreen navigator on touch). Returns the index of
+     * the first match, or -1 (no term / no matches), so the caller can set focus.
+     */
+    private rebuildTreeVisibleForNavigate;
     /**
      * (Re)compute `isRTL` from the host's `dir` (or an RTL ancestor) and derive the
      * direction-mirrored badges position. Pure state — callers apply the DOM effects
@@ -1098,6 +1109,26 @@ export declare class WebMultiSelect<T = any> {
     private lockBodyScroll;
     /** Restore page scroll (no-op if it wasn't locked). */
     private unlockBodyScroll;
+    /**
+     * Clip the host document's horizontal overflow while a fullscreen sheet is open.
+     *
+     * A page that overflows horizontally (e.g. an unbreakable-wide token in a heading)
+     * makes the mobile browser SHRINK-TO-FIT: it zooms the page out so the overflow fits,
+     * which desyncs the visual viewport from the layout viewport. Our fullscreen sheet is
+     * `position: fixed` — anchored to the LAYOUT viewport — so under that zoom it no longer
+     * lands flush against the physical screen edges, and the top slips under the system bar
+     * (looks like "the bar covers the sheet"). This is NOT a safe-area problem; safe-area
+     * insets are 0 in that state. Clamping `overflow-x: hidden` on <html>/<body> removes the
+     * overflow, so the browser drops the zoom and the sheet sits flush. Complements
+     * lockBodyScroll() (vertical axis); the saved inline value is restored on close.
+     *
+     * Only <html> is touched (not <body>): clipping the root's horizontal overflow is
+     * enough to collapse the scrollWidth and cancel the shrink-to-fit, and it avoids
+     * conflicting with core's lockBodyScroll(), which owns <body>'s `overflow`. Idempotent.
+     */
+    private clampDocumentOverflowX;
+    /** Restore the <html> `overflow-x` clamped by clampDocumentOverflowX() (no-op if unset). */
+    private releaseDocumentOverflowX;
     /**
      * While the fullscreen dropdown is open, keep it sitting above the soft keyboard.
      * Delegates to core's `observeKeyboardInset` (which tracks `window.visualViewport`