@ahrowe/ui 0.16.8 → 0.17.0

package/dist/types/package/common/sticky/sticky.d.ts

@@ -1,2 +1,2 @@
 import { StickyProps } from './sticky.types';
-export default function Sticky({ children, offsetTop, zIndex, disabled, onStuckChange, className, style, classNames, styles: slotStyles, ...rest }: StickyProps): import("react/jsx-runtime").JSX.Element;
+export default function Sticky({ children, offsetTop, offsetElement, stickToScrollParent, zIndex, disabled, onStuckChange, className, style, classNames, styles: slotStyles, ...rest }: StickyProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/package/common/sticky/sticky.types.d.ts

@@ -3,8 +3,12 @@ import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type StickySlots = 'root' | 'placeholder' | 'content';
 export interface StickyProps extends HtmlProps {
     children?: React.ReactNode;
-    /** Distance (px) from the top of the viewport the content sticks to. Default 0. */
+    /** Distance (px) from the top of the viewport the content sticks to. Default 0. Ignored if `offsetElement` is set. */
     offsetTop?: number;
+    /** Element (e.g. a pinned header) to stick below instead of a fixed `offsetTop` — its live height is used as the offset. */
+    offsetElement?: React.RefObject<HTMLElement | null>;
+    /** Stick to the top of the nearest scrollable ancestor instead of the browser viewport. Falls back to the viewport if no scrollable ancestor is found. */
+    stickToScrollParent?: boolean;
     /** z-index applied to the content while stuck. Default 20. */
     zIndex?: number;
     /** Disable sticking entirely — content stays in normal flow. */

package/dist/types/package/common/sticky/stickyStack.d.ts

@@ -10,6 +10,11 @@ export interface StickyStackMetrics {
     left: number;
     width: number;
     contentHeight: number;
+    /** The element this entry sticks relative to (its scroll parent), or null for the viewport.
+     *  Stacking only considers overlap between entries sharing the same container — two Stickies
+     *  in unrelated scroll panels should never push each other down just because they happen to
+     *  share horizontal DOM coordinates. */
+    container: HTMLElement | null;
 }
 export interface StickyStackEntry {
     node: HTMLElement;

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.0",
   "publishConfig": {
     "access": "public"
   },