@ahrowe/ui 0.16.8 → 0.17.1

package/docs/FloatingMenu.md

@@ -54,7 +54,7 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 
 **Slots:** `root` `trigger` `menu` `menuContainer`
 
-**Positioning:** the menu is portaled and tracks the trigger across scroll and resize, flipping above it when there's no room below. It re-measures whenever `content` changes size while open, so a menu holding a list that grows or shrinks (filtering, async loading) stays anchored to the trigger and re-evaluates whether it still needs to open upward.
+**Positioning:** the menu is portaled and tracks the trigger across scroll and resize, flipping above it when there's no room below. It re-measures whenever `content` changes size while open, so a menu holding a list that grows or shrinks (filtering, async loading) stays anchored to the trigger and re-evaluates whether it still needs to open upward. It's also shifted horizontally to stay within the viewport — a trigger near the left or right edge of the screen no longer lets the menu overflow off-screen, regardless of `align`.
 
 **Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
 

package/docs/InputDropdown.md

@@ -68,4 +68,4 @@ interface InputDropdownItem {
 
 **Slots:** `root` `dropdown` `item`
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/Sticky.md

@@ -2,7 +2,7 @@
 
 **When to use:** Pin a piece of content to the top of the viewport once the page scrolls past it — section headers, toolbars, filter bars, table headers. The content sticks while its original position is above the fold and releases the moment that position scrolls back into view. A placeholder preserves the original space, so nothing below jumps when it detaches.
 
-**Keywords:** sticky header, pinned toolbar
+**Keywords:** sticky header, pinned toolbar, scroll container, app shell, scrollable panel
 
 **Import:** `import { Sticky } from '@ahrowe/ui'`
 
@@ -19,6 +19,23 @@ import { Sticky } from '@ahrowe/ui';
   <FilterBar />
 </Sticky>
 
+// Stick below a header that isn't a Sticky itself — offset tracks its live height
+const headerRef = useRef<HTMLElement>(null);
+<header ref={headerRef}>...</header>
+<Sticky offsetElement={headerRef}>
+  <FilterBar />
+</Sticky>
+
+// App-shell layout: a separately-scrollable content pane below a header that's
+// outside that scroll container. Stick to the pane's own top edge instead of the
+// browser viewport's, so it naturally stops below the header with no offset needed
+<div style={{ height: '100vh', overflowY: 'auto' }}>
+  <Sticky stickToScrollParent offsetTop={0}>
+    <FilterBar />
+  </Sticky>
+  <Content />
+</div>
+
 // React to the stuck state (e.g. add a shadow)
 <Sticky onStuckChange={(stuck) => setElevated(stuck)}>
   <Toolbar />
@@ -39,7 +56,9 @@ import { Sticky } from '@ahrowe/ui';
 </Sticky>
 ```
 
-**How it works:** while stuck, the content switches to `position: fixed` (measured to keep the same width and horizontal position) and a placeholder of the same height takes its place in the flow. It tracks scroll on the window *and* any ancestor scroll container, so it works inside scrollable panels too — it always pins to the top of the viewport (offset by `offsetTop`).
+**How it works:** while stuck, the content switches to `position: fixed` (measured to keep the same width and horizontal position) and a placeholder of the same height takes its place in the flow. It tracks scroll on the window *and* any ancestor scroll container, so it works inside scrollable panels too. By default it pins to the top of the browser viewport (offset by `offsetTop`), regardless of any scroll container it's nested in — set `stickToScrollParent` to pin to that container's own top edge instead (see below).
+
+**`stickToScrollParent`:** by default `Sticky` always pins relative to the browser viewport, which can overlap other fixed/pinned chrome (e.g. an app header) that sits outside the element's own scroll container. Set `stickToScrollParent` to pin relative to the nearest ancestor with its own scrollbar (`overflow-y: auto`/`scroll`/`overlay`) instead — found once on mount by walking up from the root. Falls back to the viewport if no scrollable ancestor is found. Combine with `offsetTop` for extra spacing from that container's top (e.g. its own internal header).
 
 **Stacking:** every mounted `Sticky` coordinates automatically, no extra markup needed. When more than one is stuck at the same time, a later one (in DOM order) that horizontally overlaps an earlier stuck one pins below it — `offsetTop` plus the overlapping ones' heights — instead of both landing on the same spot. Stickies that don't overlap horizontally (e.g. two half-width ones side by side under a full-width one) land at the same `top`, next to each other, rather than pushing each other down.
 
@@ -48,7 +67,9 @@ import { Sticky } from '@ahrowe/ui';
 | Prop | Type | Description |
 |------|------|-------------|
 | `children` | `ReactNode` | The content to make sticky |
-| `offsetTop` | `number` | Distance in px from the top of the viewport the content sticks to (default `0`) |
+| `offsetTop` | `number` | Distance in px from the top of the viewport the content sticks to (default `0`). Ignored if `offsetElement` is set |
+| `offsetElement` | `RefObject<HTMLElement \| null>` | Element to stick below (e.g. a fixed/pinned header outside this library) — its live height is used as the offset instead of a fixed `offsetTop` |
+| `stickToScrollParent` | `boolean` | Stick to the top of the nearest scrollable ancestor instead of the browser viewport (default `false`). Falls back to the viewport if no scrollable ancestor is found |
 | `zIndex` | `number` | z-index applied while stuck (default `20`) |
 | `disabled` | `boolean` | Disable sticking — content stays in normal flow |
 | `onStuckChange` | `(isStuck: boolean) => void` | Fired whenever the stuck state flips |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.16.8",
+  "version": "0.17.1",
   "publishConfig": {
     "access": "public"
   },