@ahrowe/ui 0.16.7 → 0.17.0

package/docs/Stepper.md

@@ -2,6 +2,8 @@
 
 **When to use:** Step progress indicator for multi-step forms, onboarding flows, and checkout wizards. Shows completed, current, and upcoming steps, and (vertically) can expand a collapsible body under the active step.
 
+**Keywords:** wizard steps, progress steps
+
 **Import:** `import { Stepper } from '@ahrowe/ui'`
 **Types:** `import type { StepperStep, StepperProps } from '@ahrowe/ui'`
 

package/docs/Sticky.md

@@ -2,6 +2,8 @@
 
 **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, scroll container, app shell, scrollable panel
+
 **Import:** `import { Sticky } from '@ahrowe/ui'`
 
 ```tsx
@@ -17,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 />
@@ -37,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.
 
@@ -46,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/docs/Switch.md

@@ -2,6 +2,8 @@
 
 **When to use:** Sliding boolean toggle — settings panels, feature flags, preference lists. Same shape as `Checkbox` but visually a track + thumb; prefer `Switch` when the effect is immediate (e.g. enabling a setting) and `Checkbox` for selections inside a form that gets submitted.
 
+**Keywords:** toggle switch, on off switch
+
 **Import:** `import { Switch } from '@ahrowe/ui'`
 
 ```tsx

package/docs/TabHeader.md

@@ -2,6 +2,8 @@
 
 **When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title and subtitle.
 
+**Keywords:** tabs navigation, tab bar
+
 **Import:** `import { TabHeader } from '@ahrowe/ui'`
 
 **Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to just its icon.

package/docs/Textarea.md

@@ -2,6 +2,8 @@
 
 **When to use:** Multiline text input — comments, descriptions, notes, code snippets, long-form content. Same API as `Input` but pre-configured for multiline.
 
+**Keywords:** multiline field, comment box, text area
+
 **Import:** `import { Textarea } from '@ahrowe/ui'`
 
 ```tsx

package/docs/ThemeProvider.md

@@ -2,6 +2,8 @@
 
 **When to use:** Required wrapper for the entire component library. Injects all CSS custom properties as inline styles so every component inside can use theme variables. Place it at or near the root of your app.
 
+**Keywords:** theming, dark mode
+
 **Import:** `import { ThemeProvider } from '@ahrowe/ui'`  
 **Types:** `import type { Theme, ThemeVariables } from '@ahrowe/ui'`
 

package/docs/Tilt.md

@@ -2,6 +2,8 @@
 
 **When to use:** Wrap content that should tilt toward the cursor in 3D. Pointer position drives a `rotateX`/`rotateY` tilt that flattens out near the center and ramps up (with an eased, non-linear curve) toward the edges. Use it for clean UI polish, like a row of pricing/plan cards that each tilt independently on hover, or as a low-level primitive for custom animation, like a hand of cards that all react to one shared cursor. Compose with `Flip` for a card that both tilts and flips.
 
+**Keywords:** hover tilt effect, parallax card
+
 **Import:** `import { Tilt, TiltGroup } from '@ahrowe/ui'`
 **Types:** `import type { TiltProps, TiltHandle, TiltGroupProps } from '@ahrowe/ui'`
 

package/docs/TimeInput.md

@@ -2,6 +2,8 @@
 
 **When to use:** Time-of-day selection — appointment times, opening hours, shift starts, reminders. Built on top of `Input`: the user can **type** the time directly (`1430` → `14:30`) or pick it on a **Material-style clock dial**. Renders as a text input with a floating label by default; can also be inline or modal, mirroring `DatePicker`.
 
+**Keywords:** time picker, clock input
+
 **Import:** `import { TimeInput } from '@ahrowe/ui'`
 
 The value is a `"HH:MM"` 24-hour string (e.g. `"09:30"`) everywhere — also when `use24Hour={false}` is set (that flag only changes the dial UI, not the stored value).

package/docs/Timeline.md

@@ -2,6 +2,8 @@
 
 **When to use:** A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs. Each entry can carry a title, timestamp, description, an icon or status colour, and arbitrary extra content.
 
+**Keywords:** history log
+
 **Import:** `import { Timeline, TimelineAlignment, TimelineItemStatus } from '@ahrowe/ui'`
 **Types:** `import type { TimelineItem, TimelineProps } from '@ahrowe/ui'`
 

package/docs/Toast.md

@@ -2,6 +2,8 @@
 
 **When to use:** Non-blocking notifications — save confirmations, error alerts, info messages, warnings. Toasts appear in a corner of the screen and auto-dismiss after a configurable duration.
 
+**Keywords:** snackbar, notification popup
+
 **Import:** `import { ToastProvider, showToast } from '@ahrowe/ui'`  
 **Types:** `import type { ToastOptions, ToastType, ToastPosition } from '@ahrowe/ui'`
 

package/docs/Tooltip.md

@@ -2,6 +2,8 @@
 
 **When to use:** Contextual help, info icons, field explanations, error pointers.
 
+**Keywords:** hint, help text, info bubble
+
 **Import:** `import { Tooltip } from '@ahrowe/ui'`
 
 ```tsx

package/docs/VirtualList.md

@@ -2,6 +2,8 @@
 
 **When to use:** Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM. Supports column definitions, row selection, multi-select, column visibility toggling, and infinite scroll.
 
+**Keywords:** data table, virtualized table
+
 **Import:** `import { VirtualList } from '@ahrowe/ui'`  
 **Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle } from '@ahrowe/ui'`
 

package/docs/Wizard.md

@@ -2,6 +2,8 @@
 
 **When to use:** Animated step container for multi-step forms and flows. Handles slide transitions between steps. Pair with `Stepper` for a progress indicator.
 
+**Keywords:** step flow
+
 **Import:** `import { Wizard } from '@ahrowe/ui'`
 
 ```tsx

package/package.json

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