@adamosuiteservices/ui 2.19.2 → 2.20.0

package/dist/timeline.cjs

@@ -1,4 +1,4 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./jsx-runtime-BB_1_6y_.cjs"),a=require("./index-DoxiiusW.cjs"),R=require("./index-DCsgSkBj.cjs"),E=require("react");function T(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const n in t)if(n!=="default"){const r=Object.getOwnPropertyDescriptor(t,n);Object.defineProperty(e,n,r.get?r:{enumerable:!0,get:()=>t[n]})}}return e.default=t,Object.freeze(e)}const s=T(E),d=s.createContext({orientation:"vertical",scrollable:!1}),l=s.createContext({status:"pending"}),v=s.createContext(!1);function C({className:t,orientation:e="vertical",responsive:n=!0,children:r,...m}){const o=R.useMediaQuery("(max-width: 639px)"),c=e==="horizontal"&&n&&o?"vertical":e,u=e==="horizontal"&&!n,p=s.Children.toArray(r),f=i.jsxRuntimeExports.jsx("ol",{"data-slot":"timeline","data-orientation":c,className:a.cn("adm:flex",c==="vertical"?"adm:flex-col":"adm:flex-row adm:items-start",t),...m,children:p.map((x,j)=>{if(!s.isValidElement(x))return x;const b=p[j-1],h=s.isValidElement(b)?b.props.status??"pending":"pending";return i.jsxRuntimeExports.jsx(v.Provider,{value:h==="complete",children:x},j)})});return i.jsxRuntimeExports.jsx(d.Provider,{value:{orientation:c,scrollable:u},children:u?i.jsxRuntimeExports.jsx("div",{className:"adm:w-full adm:overflow-x-auto",children:f}):f})}function y({className:t,status:e="pending",...n}){const{orientation:r,scrollable:m}=s.useContext(d);return i.jsxRuntimeExports.jsx(l.Provider,{value:{status:e},children:i.jsxRuntimeExports.jsx("li",{"data-slot":"timeline-item","data-status":e,className:a.cn("adm:group adm:relative",r==="vertical"?"adm:flex adm:gap-4":a.cn("adm:flex adm:flex-1 adm:flex-col adm:items-center",m&&"adm:min-w-28"),t),...n})})}function g(){const{status:t}=s.useContext(l),e=t==="complete",n=t==="active";return i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-dot",className:a.cn("adm:relative adm:flex adm:size-5 adm:shrink-0 adm:items-center","adm:justify-center","adm:rounded-full adm:border","adm:transition-[color,box-shadow,background-color,border-color]",e&&"adm:border-primary adm:bg-primary",n&&"adm:border-primary adm:bg-background",!n&&!e&&"adm:border-border adm:bg-background"),children:[n&&i.jsxRuntimeExports.jsx("span",{className:"adm:size-2 adm:rounded-full adm:bg-primary"}),e&&i.jsxRuntimeExports.jsx("svg",{viewBox:"0 0 12 12",className:"adm:size-3",fill:"none","aria-hidden":!0,children:i.jsxRuntimeExports.jsx("path",{d:"M2 6l3 3 5-5",stroke:"white",strokeWidth:"1.5",strokeLinecap:"round",strokeLinejoin:"round"})})]})}function N({className:t,...e}){const{orientation:n}=s.useContext(d),{status:r}=s.useContext(l),m=s.useContext(v),o=r==="complete";return n==="vertical"?i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-indicator",className:a.cn("adm:flex adm:shrink-0 adm:flex-col adm:items-center",t),...e,children:[i.jsxRuntimeExports.jsx(g,{}),i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:my-1 adm:min-h-4 adm:w-px adm:flex-1","adm:group-last:hidden",o?"adm:bg-primary":"adm:bg-border")})]}):i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-indicator",className:a.cn("adm:flex adm:w-full adm:items-center",t),...e,children:[i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:h-px adm:flex-1","adm:group-first:invisible",m?"adm:bg-primary":"adm:bg-border")}),i.jsxRuntimeExports.jsx("div",{className:"adm:mx-1",children:i.jsxRuntimeExports.jsx(g,{})}),i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:h-px adm:flex-1","adm:group-last:hidden",o?"adm:bg-primary":"adm:bg-border")})]})}function w({className:t,...e}){const{orientation:n}=s.useContext(d),{status:r}=s.useContext(l);return i.jsxRuntimeExports.jsx("div",{"data-slot":"timeline-content",className:a.cn("adm:flex adm:flex-col adm:gap-3",n==="vertical"?`
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./jsx-runtime-BB_1_6y_.cjs"),a=require("./index-DoxiiusW.cjs"),R=require("./index-DCsgSkBj.cjs"),E=require("react");function T(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const n in t)if(n!=="default"){const r=Object.getOwnPropertyDescriptor(t,n);Object.defineProperty(e,n,r.get?r:{enumerable:!0,get:()=>t[n]})}}return e.default=t,Object.freeze(e)}const s=T(E),d=s.createContext({orientation:"vertical",scrollable:!1}),l=s.createContext({status:"pending"}),v=s.createContext(!1);function C({className:t,orientation:e="vertical",responsive:n=!0,children:r,...m}){const o=R.useMediaQuery("(max-width: 639px)"),c=e==="horizontal"&&n&&o?"vertical":e,u=e==="horizontal"&&!n,p=s.Children.toArray(r),f=i.jsxRuntimeExports.jsx("ol",{"data-slot":"timeline","data-orientation":c,className:a.cn("adm:flex",c==="vertical"?"adm:flex-col":"adm:flex-row adm:items-start",t),...m,children:p.map((x,j)=>{if(!s.isValidElement(x))return x;const b=p[j-1],h=s.isValidElement(b)?b.props.status??"pending":"pending";return i.jsxRuntimeExports.jsx(v.Provider,{value:h==="complete",children:x},j)})});return i.jsxRuntimeExports.jsx(d.Provider,{value:{orientation:c,scrollable:u},children:u?i.jsxRuntimeExports.jsx("div",{className:"adm:w-full adm:overflow-x-auto",children:f}):f})}function y({className:t,status:e="pending",...n}){const{orientation:r,scrollable:m}=s.useContext(d);return i.jsxRuntimeExports.jsx(l.Provider,{value:{status:e},children:i.jsxRuntimeExports.jsx("li",{"data-slot":"timeline-item","data-status":e,className:a.cn("adm:group adm:relative",r==="vertical"?"adm:flex adm:gap-4":a.cn("adm:flex adm:flex-1 adm:flex-col adm:items-center",m&&"adm:min-w-28"),t),...n})})}function g(){const{status:t}=s.useContext(l),e=t==="complete",n=t==="active";return i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-dot",className:a.cn("adm:relative adm:flex adm:size-5 adm:shrink-0 adm:items-center","adm:justify-center","adm:rounded-full adm:border","adm:transition-[color,box-shadow,background-color,border-color]",e&&"adm:border-primary adm:bg-primary",n&&"adm:border-primary adm:bg-background",!n&&!e&&"adm:border-border adm:bg-background"),children:[n&&i.jsxRuntimeExports.jsx("span",{className:"adm:size-2 adm:rounded-full adm:bg-primary"}),e&&i.jsxRuntimeExports.jsx("svg",{viewBox:"0 0 12 12",className:"adm:size-3",fill:"none","aria-hidden":!0,children:i.jsxRuntimeExports.jsx("path",{d:"M2 6l3 3 5-5",stroke:"white",strokeWidth:"1.5",strokeLinecap:"round",strokeLinejoin:"round"})})]})}function N({className:t,...e}){const{orientation:n}=s.useContext(d),{status:r}=s.useContext(l),m=s.useContext(v),o=r==="complete";return n==="vertical"?i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-indicator",className:a.cn("adm:flex adm:shrink-0 adm:flex-col adm:items-center",t),...e,children:[i.jsxRuntimeExports.jsx(g,{}),i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:my-1 adm:min-h-4 adm:w-px adm:flex-1","adm:group-last:hidden",o?"adm:bg-primary":"adm:bg-border")})]}):i.jsxRuntimeExports.jsxs("div",{"data-slot":"timeline-indicator",className:a.cn("adm:flex adm:w-full adm:items-center",t),...e,children:[i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:h-px adm:flex-1","adm:group-first:invisible",m?"adm:bg-primary":"adm:bg-border")}),i.jsxRuntimeExports.jsx("div",{className:"adm:mx-1",children:i.jsxRuntimeExports.jsx(g,{})}),i.jsxRuntimeExports.jsx("div",{className:a.cn("adm:h-px adm:flex-1","adm:group-last:invisible",o?"adm:bg-primary":"adm:bg-border")})]})}function w({className:t,...e}){const{orientation:n}=s.useContext(d),{status:r}=s.useContext(l);return i.jsxRuntimeExports.jsx("div",{"data-slot":"timeline-content",className:a.cn("adm:flex adm:flex-col adm:gap-3",n==="vertical"?`
             adm:min-w-0 adm:flex-1 adm:pb-4
             adm:group-last:pb-0
-          `:"adm:items-center adm:pt-3",r==="pending"?"adm:text-disabled-foreground":"adm:text-foreground",t),...e})}function k({className:t,...e}){return i.jsxRuntimeExports.jsx("p",{"data-slot":"timeline-title",className:a.cn("adm:text-sm adm:leading-5 adm:font-semibold",t),...e})}function O({className:t,...e}){return i.jsxRuntimeExports.jsx("p",{"data-slot":"timeline-description",className:a.cn("adm:text-sm adm:leading-5 adm:font-normal",t),...e})}function z({className:t,...e}){return i.jsxRuntimeExports.jsx("time",{"data-slot":"timeline-time",className:a.cn("adm:text-xs adm:leading-4",t),...e})}exports.Timeline=C;exports.TimelineContent=w;exports.TimelineDescription=O;exports.TimelineIndicator=N;exports.TimelineItem=y;exports.TimelineTime=z;exports.TimelineTitle=k;
+          `:"adm:items-center adm:pt-3 adm:text-center",r==="pending"?"adm:text-disabled-foreground":"adm:text-foreground",t),...e})}function k({className:t,...e}){return i.jsxRuntimeExports.jsx("p",{"data-slot":"timeline-title",className:a.cn("adm:text-sm adm:leading-5 adm:font-semibold",t),...e})}function O({className:t,...e}){return i.jsxRuntimeExports.jsx("p",{"data-slot":"timeline-description",className:a.cn("adm:text-sm adm:leading-5 adm:font-normal",t),...e})}function z({className:t,...e}){return i.jsxRuntimeExports.jsx("time",{"data-slot":"timeline-time",className:a.cn("adm:text-xs adm:leading-4",t),...e})}exports.Timeline=C;exports.TimelineContent=w;exports.TimelineDescription=O;exports.TimelineIndicator=N;exports.TimelineItem=y;exports.TimelineTime=z;exports.TimelineTitle=k;

package/dist/timeline.js

@@ -3,9 +3,9 @@ import { j as e } from "./jsx-runtime-BzflLqGi.js";
 import { c as i } from "./index-CRiPKpXj.js";
 import { u as C } from "./index-BBT2EGq8.js";
 import * as n from "react";
-const o = n.createContext({ orientation: "vertical", scrollable: !1 }), l = n.createContext({ status: "pending" }), h = n.createContext(!1);
-function w({ className: a, orientation: t = "vertical", responsive: d = !0, children: m, ...r }) {
-  const s = C("(max-width: 639px)"), c = t === "horizontal" && d && s ? "vertical" : t, u = t === "horizontal" && !d, p = n.Children.toArray(m), f = /* @__PURE__ */ e.jsx(
+const o = n.createContext({ orientation: "vertical", scrollable: !1 }), l = n.createContext({ status: "pending" }), j = n.createContext(!1);
+function w({ className: a, orientation: t = "vertical", responsive: m = !0, children: d, ...r }) {
+  const s = C("(max-width: 639px)"), c = t === "horizontal" && m && s ? "vertical" : t, u = t === "horizontal" && !m, p = n.Children.toArray(d), f = /* @__PURE__ */ e.jsx(
     "ol",
     {
       "data-slot": "timeline",
@@ -18,15 +18,15 @@ function w({ className: a, orientation: t = "vertical", responsive: d = !0, chil
       ...r,
       children: p.map((x, b) => {
         if (!n.isValidElement(x)) return x;
-        const v = p[b - 1], j = n.isValidElement(v) ? v.props.status ?? "pending" : "pending";
-        return /* @__PURE__ */ e.jsx(h.Provider, { value: j === "complete", children: x }, b);
+        const v = p[b - 1], h = n.isValidElement(v) ? v.props.status ?? "pending" : "pending";
+        return /* @__PURE__ */ e.jsx(j.Provider, { value: h === "complete", children: x }, b);
       })
     }
   );
   return /* @__PURE__ */ e.jsx(o.Provider, { value: { orientation: c, scrollable: u }, children: u ? /* @__PURE__ */ e.jsx("div", { className: "adm:w-full adm:overflow-x-auto", children: f }) : f });
 }
-function k({ className: a, status: t = "pending", ...d }) {
-  const { orientation: m, scrollable: r } = n.useContext(o);
+function k({ className: a, status: t = "pending", ...m }) {
+  const { orientation: d, scrollable: r } = n.useContext(o);
   return /* @__PURE__ */ e.jsx(l.Provider, { value: { status: t }, children: /* @__PURE__ */ e.jsx(
     "li",
     {
@@ -34,18 +34,18 @@ function k({ className: a, status: t = "pending", ...d }) {
       "data-status": t,
       className: i(
         "adm:group adm:relative",
-        m === "vertical" ? "adm:flex adm:gap-4" : i(
+        d === "vertical" ? "adm:flex adm:gap-4" : i(
           "adm:flex adm:flex-1 adm:flex-col adm:items-center",
           r && "adm:min-w-28"
         ),
         a
       ),
-      ...d
+      ...m
     }
   ) });
 }
 function g() {
-  const { status: a } = n.useContext(l), t = a === "complete", d = a === "active";
+  const { status: a } = n.useContext(l), t = a === "complete", m = a === "active";
   return /* @__PURE__ */ e.jsxs(
     "div",
     {
@@ -56,11 +56,11 @@ function g() {
         "adm:rounded-full adm:border",
         "adm:transition-[color,box-shadow,background-color,border-color]",
         t && "adm:border-primary adm:bg-primary",
-        d && "adm:border-primary adm:bg-background",
-        !d && !t && "adm:border-border adm:bg-background"
+        m && "adm:border-primary adm:bg-background",
+        !m && !t && "adm:border-border adm:bg-background"
       ),
       children: [
-        d && /* @__PURE__ */ e.jsx("span", { className: "adm:size-2 adm:rounded-full adm:bg-primary" }),
+        m && /* @__PURE__ */ e.jsx("span", { className: "adm:size-2 adm:rounded-full adm:bg-primary" }),
         t && /* @__PURE__ */ e.jsx("svg", { viewBox: "0 0 12 12", className: "adm:size-3", fill: "none", "aria-hidden": !0, children: /* @__PURE__ */ e.jsx(
           "path",
           {
@@ -76,8 +76,8 @@ function g() {
   );
 }
 function z({ className: a, ...t }) {
-  const { orientation: d } = n.useContext(o), { status: m } = n.useContext(l), r = n.useContext(h), s = m === "complete";
-  return d === "vertical" ? /* @__PURE__ */ e.jsxs(
+  const { orientation: m } = n.useContext(o), { status: d } = n.useContext(l), r = n.useContext(j), s = d === "complete";
+  return m === "vertical" ? /* @__PURE__ */ e.jsxs(
     "div",
     {
       "data-slot": "timeline-indicator",
@@ -120,7 +120,7 @@ function z({ className: a, ...t }) {
           {
             className: i(
               "adm:h-px adm:flex-1",
-              "adm:group-last:hidden",
+              "adm:group-last:invisible",
               s ? "adm:bg-primary" : "adm:bg-border"
             )
           }
@@ -130,18 +130,18 @@ function z({ className: a, ...t }) {
   );
 }
 function A({ className: a, ...t }) {
-  const { orientation: d } = n.useContext(o), { status: m } = n.useContext(l);
+  const { orientation: m } = n.useContext(o), { status: d } = n.useContext(l);
   return /* @__PURE__ */ e.jsx(
     "div",
     {
       "data-slot": "timeline-content",
       className: i(
         "adm:flex adm:flex-col adm:gap-3",
-        d === "vertical" ? `
+        m === "vertical" ? `
             adm:min-w-0 adm:flex-1 adm:pb-4
             adm:group-last:pb-0
-          ` : "adm:items-center adm:pt-3",
-        m === "pending" ? "adm:text-disabled-foreground" : "adm:text-foreground",
+          ` : "adm:items-center adm:pt-3 adm:text-center",
+        d === "pending" ? "adm:text-disabled-foreground" : "adm:text-foreground",
         a
       ),
       ...t

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/docs/components/ui/timeline.md

@@ -198,11 +198,16 @@ Renders as a `<time>` element with `text-xs`. Optional — omit when no timestam
 
 Each connector segment is split in two halves. The connector below a step (vertical) or the right half of a step (horizontal) is colored by whether **that step itself** is `complete`. The left half of a horizontal step is colored by whether the **previous step** was `complete`. This is managed internally via React context — no extra props are needed.
 
-### `group-last:hidden` and `group-first:invisible`
+### `group-last:invisible`, `group-last:hidden`, and `group-first:invisible`
 
 - The vertical connector of the last `TimelineItem` is hidden via `group-last:hidden` so no trailing line appears below the final step.
+- The horizontal right spacer of the last item uses `group-last:invisible` (takes space but is transparent) to keep the last dot center-aligned with the rest.
 - The horizontal left spacer of the first item uses `group-first:invisible` (takes space but is transparent) to keep the first dot center-aligned with the rest.
 
+### Horizontal text alignment
+
+`TimelineContent` applies `text-center` when `orientation="horizontal"` so that titles, descriptions, and timestamps are centered below each dot.
+
 ## Accessibility
 
 - The container renders as a semantic `<ol>` (ordered list), and each step is an `<li>`.

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.2",
+  "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"