@adamosuiteservices/ui 2.19.3 → 2.20.0

package/docs/components/layout/sticky-section.md

@@ -0,0 +1,248 @@
+# Sticky section
+
+## Description
+
+A **layout utility component** that uses the `IntersectionObserver` API to detect when a section has scrolled past the top of the visible viewport area. It exposes `isSticky` and `topOffset` to children via a React context and a render-prop pattern, allowing any descendant to adapt its appearance once the section "sticks".
+
+## Features
+
+- ✅ Automatic sticky detection via `IntersectionObserver` (no scroll listeners on the sticky element itself)
+- ✅ Render-prop pattern: `children(isSticky, topOffset)`
+- ✅ `useStickySection()` hook for deep descendants
+- ✅ Configurable top offset via `topOffset` (fixed value) or `offsetSelector` (measured from a DOM element)
+- ✅ Controlled mode: bypass internal detection by providing the `isSticky` prop
+- ✅ `onIsStickyChange` callback for side effects without owning the state
+- ✅ Defaults to measuring the library's `[data-slot='sidebar-top-bar']` so it works out of the box with `Sidebar`
+
+## Import
+
+```typescript
+import {
+  StickySection,
+  useStickySection,
+  type StickySectionProps,
+} from "@adamosuiteservices/ui/sticky-section";
+```
+
+## Basic usage
+
+### Render-prop pattern
+
+```tsx
+import { StickySection } from "@adamosuiteservices/ui/sticky-section";
+
+function PageHeader() {
+  return (
+    <StickySection>
+      {(isSticky, topOffset) => (
+        <header
+          style={{ top: isSticky ? topOffset : undefined }}
+          className={
+            isSticky ? "fixed left-0 right-0 shadow-md z-50" : "relative"
+          }
+        >
+          <h1>Page title</h1>
+        </header>
+      )}
+    </StickySection>
+  );
+}
+```
+
+### Hook pattern (deep consumers)
+
+```tsx
+import {
+  StickySection,
+  useStickySection,
+} from "@adamosuiteservices/ui/sticky-section";
+
+function Toolbar() {
+  const { isSticky, topOffset } = useStickySection();
+
+  return (
+    <div
+      style={{ top: isSticky ? topOffset : undefined }}
+      className={isSticky ? "fixed ..." : ""}
+    >
+      Actions
+    </div>
+  );
+}
+
+function Section() {
+  return (
+    <StickySection>
+      <Toolbar />
+      {/* other children */}
+    </StickySection>
+  );
+}
+```
+
+## Props
+
+| Prop               | Type                                                                 | Default                           | Description                                                                                          |
+| ------------------ | -------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `topOffset`        | `number`                                                             | —                                 | Fixed top offset in pixels. Skips `offsetSelector` measurement when provided.                        |
+| `offsetSelector`   | `string`                                                             | `"[data-slot='sidebar-top-bar']"` | CSS selector of the element whose height is used as the top offset. Ignored when `topOffset` is set. |
+| `isSticky`         | `boolean`                                                            | —                                 | Controlled sticky state. When provided, internal `IntersectionObserver` detection is bypassed.       |
+| `onIsStickyChange` | `(isSticky: boolean, topOffset: number) => void`                     | —                                 | Called whenever the sticky state changes.                                                            |
+| `children`         | `ReactNode \| ((isSticky: boolean, topOffset: number) => ReactNode)` | required                          | ReactNode or a render-prop function.                                                                 |
+
+## `useStickySection()` hook
+
+Returns the value of the nearest `StickySection` context.
+
+```typescript
+const { isSticky, topOffset } = useStickySection();
+```
+
+| Value       | Type      | Description                                             |
+| ----------- | --------- | ------------------------------------------------------- |
+| `isSticky`  | `boolean` | Whether the section is currently stuck to the top.      |
+| `topOffset` | `number`  | The computed top offset in pixels used by the observer. |
+
+Throws if called outside a `StickySection`.
+
+## Usage patterns
+
+### With the Sidebar component (default behaviour)
+
+No configuration needed. `StickySection` automatically measures the height of `[data-slot='sidebar-top-bar']` and applies it as the offset.
+
+```tsx
+import { Sidebar, SidebarTopBar } from "@adamosuiteservices/ui/sidebar";
+import { StickySection } from "@adamosuiteservices/ui/sticky-section";
+
+function Page() {
+  return (
+    <Sidebar>
+      <SidebarTopBar>…</SidebarTopBar>
+      <main>
+        <StickySection>
+          {(isSticky) => (
+            <div className={isSticky ? "sticky top-16 shadow" : ""}>
+              Page actions
+            </div>
+          )}
+        </StickySection>
+      </main>
+    </Sidebar>
+  );
+}
+```
+
+### With a custom top bar
+
+```tsx
+<div data-slot="main-header" className="sticky top-0 h-20 …">My app header</div>
+
+<StickySection offsetSelector="[data-slot='main-header']">
+  {(isSticky, topOffset) => (
+    <nav style={{ top: isSticky ? topOffset : undefined }} className={isSticky ? "fixed …" : ""}>
+      Sub-navigation
+    </nav>
+  )}
+</StickySection>
+```
+
+### With a fixed top offset
+
+```tsx
+<StickySection topOffset={80}>
+  {(isSticky, topOffset) => (
+    <div
+      style={{ top: isSticky ? topOffset : undefined }}
+      className={isSticky ? "fixed …" : ""}
+    >
+      Actions bar
+    </div>
+  )}
+</StickySection>
+```
+
+### Controlled mode
+
+```tsx
+const [pinned, setPinned] = useState(false);
+
+<StickySection isSticky={pinned} topOffset={64}>
+  <ActionBar />
+</StickySection>;
+```
+
+### Reacting to changes
+
+```tsx
+<StickySection
+  topOffset={64}
+  onIsStickyChange={(isSticky, topOffset) => {
+    analytics.track("sticky_change", { isSticky, topOffset });
+  }}
+>
+  <ActionBar />
+</StickySection>
+```
+
+## Behavior
+
+### Sentinel element
+
+`StickySection` places an invisible 1 px `<div>` (`position: absolute; top: 0`) at the very start of its render output. The `IntersectionObserver` watches this sentinel — when it leaves the viewport (factoring in `topOffset` via `rootMargin`), `isSticky` becomes `true`.
+
+### Top offset resolution order
+
+1. `topOffset` prop (explicit, takes priority)
+2. Height of the element matched by `offsetSelector` (measured via `useElementRect`)
+3. Fallback: `64` px
+
+### Controlled vs uncontrolled
+
+| Mode         | How to activate         | Behavior                                                                                |
+| ------------ | ----------------------- | --------------------------------------------------------------------------------------- |
+| Uncontrolled | Omit `isSticky` prop    | `IntersectionObserver` manages state internally.                                        |
+| Controlled   | Provide `isSticky` prop | Observer still fires `onIsStickyChange`, but internal `setInternalIsSticky` is skipped. |
+
+## Best practices
+
+### ✅ DO: Apply `position: fixed` inside the section
+
+```tsx
+<StickySection topOffset={64}>
+  {(isSticky, topOffset) => (
+    <div
+      style={{ top: isSticky ? topOffset : undefined }}
+      className={isSticky ? "fixed left-0 right-0 shadow z-50" : "relative"}
+    >
+      Toolbar
+    </div>
+  )}
+</StickySection>
+```
+
+### ❌ DON'T: Nest multiple `StickySection` components with conflicting selectors
+
+Each `StickySection` creates its own sentinel and observer. Nesting without explicit `topOffset`
+values can produce unexpected offsets. Prefer sibling sections or set explicit `topOffset` on nested ones.
+
+### ✅ DO: Wrap the layout section that owns the sticky header
+
+The sentinel must be the first rendered element inside the container that scrolls.
+
+### ❌ DON'T: Use `StickySection` for static layouts
+
+`IntersectionObserver` is set up on mount and torn down on unmount. Avoid mounting and unmounting
+the component rapidly in tight render loops.
+
+## Accessibility
+
+- `StickySection` renders one invisible `<div>` sentinel. It carries no semantic role and is not focusable.
+- The sticky visual state is purely presentational; ensure that no information is conveyed exclusively through the sticky appearance.
+- If the sticky element covers page content, verify that keyboard focus order is still logical and that overlapped content is reachable.
+
+## References
+
+- [MDN — IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
+- [MDN — rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)
+- [`useElementRect` hook](../../src/hooks/use-element-rect.ts)

package/llm.txt

@@ -1,6 +1,6 @@
 # Adamo UI Component Library - LLM Context
 
-> **CRITICAL**: This is a COMPLETE React component library with 49+ components. DO NOT create components that already exist. ALWAYS check this file first and use existing components.
+> **CRITICAL**: This is a COMPLETE React component library with 50+ components. DO NOT create components that already exist. ALWAYS check this file first and use existing components.
 
 ## 🚨 MOST IMPORTANT RULES
 
@@ -75,7 +75,7 @@ Before creating ANY component, verify it doesn't exist here. For implementation
 - **Separator** [`docs/components/ui/separator.md`] - `@adamosuiteservices/ui/separator`
 - **Scroll Area** [`docs/components/ui/scroll-area.md`] - `@adamosuiteservices/ui/scroll-area`
 
-### Other Components (7)
+### Other Components (8)
 - **Icon** [`docs/components/ui/icon.md`] - `@adamosuiteservices/ui/icon` (Material Symbols)
 - **Calendar** [`docs/components/ui/calendar.md`] - `@adamosuiteservices/ui/calendar`
 - **Date Picker Selector** [`docs/components/ui/date-picker-selector.md`] - `@adamosuiteservices/ui/date-picker-selector`
@@ -83,6 +83,7 @@ Before creating ANY component, verify it doesn't exist here. For implementation
 - **Kbd** [`docs/components/ui/kbd.md`] - `@adamosuiteservices/ui/kbd`
 - **Input OTP** [`docs/components/ui/input-otp.md`] - `@adamosuiteservices/ui/input-otp`
 - **Full Screen Loader** [`docs/components/layout/full-screen-loader.md`] - `@adamosuiteservices/ui/full-screen-loader`
+- **Sticky Section** [`docs/components/layout/sticky-section.md`] - `@adamosuiteservices/ui/sticky-section` (scroll-aware sticky detection with context + render-prop)
 
 ### Utilities
 - **cn()** - `@adamosuiteservices/ui/lib` - Merge Tailwind classes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "2.19.3",
+  "version": "2.20.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -42,6 +42,10 @@
       "types": "./dist/components/layout/full-screen-loader/index.d.ts",
       "import": "./dist/full-screen-loader.js"
     },
+    "./sticky-section": {
+      "types": "./dist/components/layout/sticky-section/index.d.ts",
+      "import": "./dist/sticky-section.js"
+    },
     "./accordion": {
       "types": "./dist/components/ui/accordion/accordion.d.ts",
       "import": "./dist/accordion.js"