@olwiba/ui 0.2.25 → 0.2.26

package/content/docs/hooks/use-intersection-observer.mdx

@@ -0,0 +1,26 @@
+---
+title: useIntersectionObserver
+description: Returns a ref and a boolean for scroll-triggered visibility detection.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="use-intersection-observer" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { useIntersectionObserver } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="useIntersectionObserver" props={[]} />

package/content/docs/hooks/use-local-storage.mdx

@@ -0,0 +1,26 @@
+---
+title: useLocalStorage
+description: Persisted state backed by localStorage with SSR safety.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="use-local-storage" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { useLocalStorage } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="useLocalStorage" props={[]} />

package/content/docs/hooks/use-media-query.mdx

@@ -0,0 +1,26 @@
+---
+title: useMediaQuery
+description: Returns true/false for any CSS media query string.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="use-media-query" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { useMediaQuery } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="useMediaQuery" props={[]} />

package/content/docs/hooks/use-mounted.mdx

@@ -0,0 +1,39 @@
+---
+title: useMounted
+description: Detect when the component has mounted on the client.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { useMounted } from "@olwiba/ui";
+```
+
+```tsx
+function MyComponent() {
+  const mounted = useMounted();
+
+  if (!mounted) return <div>Loading...</div>;
+
+  // Safe to access browser APIs after mount
+  return <div>Window width: {window.innerWidth}px</div>;
+}
+```
+
+Useful for SSR hydration mismatches, safely accessing `window`/`document`, and triggering entrance animations after mount.
+
+## API Reference
+
+<APIReference name="useMounted → returns" props={[
+  { name: "mounted", type: "boolean", default: "false" },
+]} />

package/content/docs/hooks/use-pagination.mdx

@@ -0,0 +1,26 @@
+---
+title: usePagination
+description: Page and offset state management — pairs with data tables and lists.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="use-pagination" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { usePagination } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="usePagination" props={[]} />

package/content/docs/hooks/use-scrolled-past.mdx

@@ -0,0 +1,44 @@
+---
+title: useScrolledPast
+description: Returns true when the page has scrolled past a given Y threshold in pixels.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { useScrolledPast } from "@olwiba/ui";
+```
+
+```tsx
+function StickyHeader() {
+  const scrolledPast = useScrolledPast(100);
+
+  return (
+    <header className={scrolledPast ? 'shadow-md bg-background' : 'bg-transparent'}>
+      ...
+    </header>
+  );
+}
+```
+
+Uses a passive scroll listener — no impact on scroll performance. Fires immediately on mount and cleans up on unmount.
+
+## API Reference
+
+<APIReference name="useScrolledPast" props={[
+  { name: "threshold", type: "number", default: "-" },
+]} />
+
+<APIReference name="useScrolledPast → returns" props={[
+  { name: "scrolledPast", type: "boolean", default: "false" },
+]} />

package/content/docs/index.mdx

@@ -0,0 +1,68 @@
+---
+title: Get Started
+description: App-level components, page sections, and hooks built on @olwiba/cn primitives.
+---
+
+## What is @olwiba/ui?
+
+`@olwiba/ui` provides configured page sections, app shells, and hooks that extend `@olwiba/cn` primitives into reusable patterns. Think Tailwind UI — components organized by domain that you drop into your project and wire up.
+
+## Package chain
+
+1. **@olwiba/cn** — Base primitives (Button, Card, Dialog, Sidebar, etc.)
+2. **@olwiba/ui** — Configured sections, shells, motion, and hooks built on CN
+
+## Installation
+
+<CopyCommandButton command="bun add @olwiba/ui @olwiba/cn" />
+
+```toml
+# bunfig.toml
+[install.scopes]
+"@olwiba" = { url = "https://npm.olwiba.com/", token = "..." }
+```
+
+## Quick start
+
+```tsx
+import { OlwibaUIProvider, AppShell } from "@olwiba/ui";
+
+export function Root() {
+  return (
+    <OlwibaUIProvider>
+      <AppShell
+        brand={{ name: "My App", href: "/" }}
+        navItems={[{ icon: LayoutDashboard, label: "Dashboard", href: "/dashboard" }]}
+        user={{ email: "user@example.com", onSignOut: () => signOut() }}
+      >
+        <Outlet />
+      </AppShell>
+    </OlwibaUIProvider>
+  );
+}
+```
+
+## What's included
+
+### App UI
+Shells and screens for application UIs — `AppShell`, `AuthSection`, `EmptyState`, `ErrorPage`.
+
+### Marketing
+Page sections and navigation for marketing sites — `HeroSection`, `FeaturesSection`, `PricingSection`, `Navbar`, `Footer`, and more.
+
+### Overlays
+Background treatments — `Backdrop` with mesh, radial, aurora, grid, noise, and glow variants.
+
+### Motion
+Animation primitives — `FadeIn`, `StaggerChildren`, `CountUp`, `PageTransition`.
+
+### Components
+Smaller interactive and card components — `Spotlight`, `Dock`, `ConfirmDialog`, card variants, utility components.
+
+### Hooks
+`useMounted`, `useConfirm`, `useControlledOpen`, `useCopyToClipboard`, `useDebounce`, `useIntersectionObserver`, `useLocalStorage`, `useMediaQuery`, `usePagination`, `useScrolledPast`.
+
+## Something not right?
+
+- 🪲 [Report a bug](https://github.com/Olwiba/olwibaUI/issues/new?template=bug_report.md)
+- ✨ [Request a feature](https://github.com/Olwiba/olwibaUI/issues/new?template=feature_request.md)

package/content/docs/marketing/contact-section.mdx

@@ -0,0 +1,16 @@
+---
+title: ContactSection
+description: Contact form section for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="contact-section" shellPreview />
+
+## Usage
+
+```tsx
+import { ContactSection } from "@olwiba/ui";
+```

package/content/docs/marketing/cta-section.mdx

@@ -0,0 +1,31 @@
+---
+title: CtaSection
+description: Call-to-action band for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="cta-section" shellPreview />
+
+## Usage
+
+```tsx
+import { CtaSection } from "@olwiba/ui";
+```
+
+## Variants
+
+```tsx
+// Default — badge icon, radial glow, primary + secondary CTAs
+<CtaSection heading="Ready to ship?" description="Start free." primaryCta={{ label: "Get started", href: "/signup" }} />
+
+// Showcase — large watermark icon with a scroll reveal, single pill CTA
+<CtaSection
+  variant="showcase"
+  heading="Launch your next app"
+  primaryCta={{ label: "Start building", href: "/signup" }}
+  icon={<Rocket className="size-72" strokeWidth={0.75} />}
+/>
+```

package/content/docs/marketing/faq-section.mdx

@@ -0,0 +1,16 @@
+---
+title: FaqSection
+description: Accordion FAQ section for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="faq-section" shellPreview />
+
+## Usage
+
+```tsx
+import { FaqSection } from "@olwiba/ui";
+```

package/content/docs/marketing/features-section.mdx

@@ -0,0 +1,23 @@
+---
+title: FeaturesSection
+description: Feature grid or list section for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="features-section" shellPreview />
+
+## Usage
+
+```tsx
+import { FeaturesSection } from "@olwiba/ui";
+
+<FeaturesSection features={features} />
+
+// Horizontally scrolling cards instead of a grid
+<FeaturesSection features={features} layout="carousel" />
+```
+
+`layout="carousel"` renders the same cards in a scroll-snap [Carousel](/docs/mechanics/carousel) with prev/next controls. To carousel your own content outside a section, use the `Carousel` mechanic directly.

package/content/docs/marketing/footer.mdx

@@ -0,0 +1,16 @@
+---
+title: Footer
+description: Site footer with links and branding.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="footer" height={447} />
+
+## Usage
+
+```tsx
+import { Footer } from "@olwiba/ui";
+```

package/content/docs/marketing/hero-section.mdx

@@ -0,0 +1,16 @@
+---
+title: HeroSection
+description: Above-the-fold hero section with headline, supporting copy, and CTA.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="hero-section" shellPreview />
+
+## Usage
+
+```tsx
+import { HeroSection } from "@olwiba/ui";
+```

package/content/docs/marketing/index.mdx

@@ -0,0 +1,22 @@
+---
+title: Marketing
+description: Page sections and navigation components for marketing sites.
+---
+
+Drop-in sections for building marketing pages. Each component is self-contained — import the ones you need and compose them into a page.
+
+| Component | Description |
+|-----------|-------------|
+| `Navbar` | Responsive top navigation bar |
+| `Footer` | Site footer with links and branding |
+| `HeroSection` | Above-the-fold hero with headline, CTA, and visual |
+| `PostList` | Responsive post grid with balanced short-list defaults |
+| `FeaturesSection` | Feature grid or list |
+| `CtaSection` | Call-to-action band |
+| `PricingSection` | Pricing cards with feature comparison |
+| `TestimonialsSection` | Customer quotes |
+| `TeamSection` | Team member grid |
+| `FaqSection` | Accordion FAQ |
+| `StatsSection` | Key metrics display |
+| `NewsletterSection` | Email capture form |
+| `ContactSection` | Contact form |

package/content/docs/marketing/meta.json

@@ -0,0 +1,20 @@
+{
+  "title": "Marketing",
+  "pages": [
+    "index",
+    "navbar",
+    "footer",
+    "hero-section",
+    "post-list",
+    "features-section",
+    "cta-section",
+    "pricing-section",
+    "testimonials-section",
+    "team-section",
+    "faq-section",
+    "stats-section",
+    "newsletter-section",
+    "contact-section",
+    "steps-section"
+  ]
+}

package/content/docs/marketing/navbar.mdx

@@ -0,0 +1,16 @@
+---
+title: Navbar
+description: Responsive top navigation bar for marketing sites.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="navbar" shellPreview />
+
+## Usage
+
+```tsx
+import { Navbar } from "@olwiba/ui";
+```

package/content/docs/marketing/newsletter-section.mdx

@@ -0,0 +1,16 @@
+---
+title: NewsletterSection
+description: Email capture form section for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="newsletter-section" shellPreview />
+
+## Usage
+
+```tsx
+import { NewsletterSection } from "@olwiba/ui";
+```

package/content/docs/marketing/post-list.mdx

@@ -0,0 +1,32 @@
+---
+title: PostList
+description: Responsive blog-post grid with balanced defaults for short collections.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="post-list" shellPreview />
+
+## Usage
+
+```tsx
+import { PostList } from "@olwiba/ui";
+
+<PostList posts={posts} />
+```
+
+`PostList` uses three columns for larger collections. One- and two-post collections are narrower and centered automatically, so a short list does not look like a partially empty grid.
+
+Pass `columns={2}` or `columns={3}` when the surrounding page needs an explicit grid contract. An explicit `columns` value disables the automatic short-list width treatment; `className` remains available for page-specific sizing.
+
+## API Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `posts` | `PostCardProps[]` | — | Posts rendered as `PostCard` items. |
+| `renderLink` | `AppShellRenderLink` | — | Optional router-aware link renderer. |
+| `emptyMessage` | `string` | `"No posts published yet."` | Message shown for an empty collection. |
+| `columns` | `2 \| 3` | Automatic | Explicit maximum column count. |
+| `className` | `string` | — | Additional classes for the grid container. |

package/content/docs/marketing/pricing-section.mdx

@@ -0,0 +1,16 @@
+---
+title: PricingSection
+description: Pricing cards with plan details and feature comparison.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="pricing-section" shellPreview />
+
+## Usage
+
+```tsx
+import { PricingSection } from "@olwiba/ui";
+```

package/content/docs/marketing/stats-section.mdx

@@ -0,0 +1,16 @@
+---
+title: StatsSection
+description: Key metrics display section for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="stats-section" shellPreview />
+
+## Usage
+
+```tsx
+import { StatsSection } from "@olwiba/ui";
+```

package/content/docs/marketing/steps-section.mdx

@@ -0,0 +1,60 @@
+---
+title: StepsSection
+description: How-it-works steps — horizontal row by default, or a numbered vertical timeline with a fading accent line.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="steps-section" shellPreview />
+
+## Usage
+
+Default variant — horizontal on desktop, vertical on mobile:
+
+```tsx
+import { StepsSection } from "@olwiba/ui";
+
+<StepsSection
+  title="From zero to shipped"
+  steps={[
+    { emoji: "✍️", title: "Sign up", description: "Create an account in seconds." },
+    { emoji: "🚀", title: "Ship", description: "Go live with confidence." },
+  ]}
+/>
+```
+
+Timeline variant — numbered circles on a vertical accent line whose ends fade out. Groups chain with interstitial content (the line fades out after a group and fades back in before the next), and numbering continues across groups:
+
+```tsx
+<StepsSection
+  variant="timeline"
+  title="Up and running in minutes"
+  groups={[
+    {
+      steps: [
+        { title: "Create your account", description: "Sign up with your email." },
+        { title: "Add your first monitor", description: <>Send <code>!bot start</code> to activate.</> },
+      ],
+      after: <CtaCard />,
+    },
+    {
+      steps: [{ title: "Found what you needed?", description: "Cancel anytime." }],
+    },
+  ]}
+/>
+```
+
+Step descriptions are `ReactNode` — code chips, forms, and demo cards all work inline.
+
+## API Reference
+
+<APIReference name="StepsSection" props={[
+  { name: "steps", type: "StepItem[]", description: "Steps for the default variant (or a single timeline group)." },
+  { name: "variant", type: '"default" | "timeline"', default: '"default"', description: "Layout variant." },
+  { name: "groups", type: "StepGroup[]", description: "Timeline only — step groups with optional `after` content; overrides steps." },
+  { name: "badge", type: "string", default: '"How it works"', description: "Badge above the title." },
+  { name: "title", type: "string", default: '"From zero to shipped"', description: "Section heading." },
+  { name: "description", type: "string", description: "Copy under the heading." },
+]} />

package/content/docs/marketing/team-section.mdx

@@ -0,0 +1,16 @@
+---
+title: TeamSection
+description: Team member grid for about and marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="team-section" shellPreview />
+
+## Usage
+
+```tsx
+import { TeamSection } from "@olwiba/ui";
+```

package/content/docs/marketing/testimonials-section.mdx

@@ -0,0 +1,16 @@
+---
+title: TestimonialsSection
+description: Customer quote grid for marketing pages.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="testimonials-section" shellPreview />
+
+## Usage
+
+```tsx
+import { TestimonialsSection } from "@olwiba/ui";
+```

package/content/docs/mechanics/carousel.mdx

@@ -0,0 +1,42 @@
+---
+title: Carousel
+description: Scroll-snap carousel behavior — wrap any children in a horizontal track with prev/next controls.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<Sandbox id="carousel" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { Carousel, FeatureCard } from "@olwiba/ui";
+
+<Carousel ariaLabel="Platform features">
+  {features.map((f) => (
+    <FeatureCard key={f.title} icon={f.icon} title={f.title} description={f.description} />
+  ))}
+</Carousel>
+```
+
+Carousel is a mechanic, not a section — each child becomes one snap slide, so feed it cards, images, or whole blocks. Control slide width with `itemClassName`:
+
+```tsx
+<Carousel itemClassName="w-[220px]">
+  {screenshots.map((s) => <ImageCard key={s.id} src={s.src} alt={s.alt} />)}
+</Carousel>
+```
+
+For a ready-made feature carousel inside a marketing section, use `FeaturesSection` with `layout="carousel"` instead.
+
+## API Reference
+
+<APIReference name="Carousel" props={[]} />