@olwiba/ui 0.2.29 → 0.2.30

package/content/docs/app/error-page.mdx

@@ -28,4 +28,16 @@ export const Route = createFileRoute("/404")({
 
 ## API Reference
 
-`ErrorPage` takes no props — it renders a self-contained 404 screen with a Go back and Take me home action.
+Every part of the screen has a default, so `<ErrorPage />` on its own is a complete 404. Pass
+`statusCode`, `title` and `description` to reuse it for 403 or 500, and `links` when you can
+guess where the visitor was actually heading.
+
+<APIReference name="ErrorPage" props={[
+  { name: "statusCode", type: "string", default: '"404"', description: "The numerals shown above the title." },
+  { name: "title", type: "string", default: '"Page not found"', description: "Heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "action", type: "{ label: string; href: string }", default: '{ label: "Take me home", href: "/" }', description: "Primary action." },
+  { name: "backAction", type: "{ label: string; href?: string; onClick?: () => void }", default: '{ label: "Go back" }', description: "Secondary action. Give it an href or an onClick — the default carries neither, so the button renders but does nothing until you do." },
+  { name: "links", type: "ErrorPageLink[]", description: "\"Maybe you were looking for\" links below the actions." },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render links through your router instead of a plain anchor." },
+]} />

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

@@ -14,3 +14,22 @@ description: Contact form section for marketing pages.
 ```tsx
 import { ContactSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+Every prop has a default, so `<ContactSection />` renders a complete section. The form manages
+its own submitted state — `onSubmit` runs first, and the success panel replaces the form whether
+or not it resolves, so surface delivery failures yourself.
+
+<APIReference name="ContactSection" props={[
+  { name: "badge", type: "string", default: '"Contact"', description: "Badge above the title." },
+  { name: "title", type: "string", default: '"Let\'s talk"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "contactInfo", type: "ContactInfoItem[]", description: "Address, phone and similar, shown as a row above the form. Each item takes a `label`, a `value` and an optional Lucide `icon`." },
+  { name: "privacyHref", type: "string", description: "Links the privacy note under the submit button. Omit it and no note is shown." },
+  { name: "successTitle", type: "string", default: '"Message sent"', description: "Heading of the panel that replaces the form." },
+  { name: "successDescription", type: "string", default: "See source", description: "Copy in the success panel." },
+  { name: "sendAnotherLabel", type: "string", default: '"Send another"', description: "Label of the button that restores the form." },
+  { name: "onSubmit", type: "(event: React.FormEvent<HTMLFormElement>) => void | Promise<void>", description: "Awaited before the success panel appears. The section never posts anywhere on its own." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -29,3 +29,20 @@ import { CtaSection } from "@olwiba/ui";
   icon={<Rocket className="size-72" strokeWidth={0.75} />}
 />
 ```
+
+## API Reference
+
+`icon` and the single pill CTA only apply to `variant="showcase"`; `secondaryCta` is dropped
+there, so put the one action that matters in `primaryCta`.
+
+<APIReference name="CtaSection" props={[
+  { name: "heading", type: "string", description: "The headline. Required." },
+  { name: "primaryCta", type: "{ label: string; href: string }", description: "Primary action. Required." },
+  { name: "description", type: "string", description: "Copy under the headline." },
+  { name: "secondaryCta", type: "{ label: string; href: string }", description: "Secondary action. Default variant only." },
+  { name: "footnote", type: "string", description: "Small print under the buttons." },
+  { name: "variant", type: '"default" | "showcase"', default: '"default"', description: "Badge icon and radial glow, or a large watermark icon with a scroll reveal." },
+  { name: "icon", type: "React.ReactNode", default: "<Rocket />", description: "Watermark icon behind the content. Showcase only." },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render CTAs through your router instead of a plain anchor." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -14,3 +14,17 @@ description: Accordion FAQ section for marketing pages.
 ```tsx
 import { FaqSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`items` is the only prop without a default. Answers are rendered as plain text inside a
+single-open [Accordion](/docs/components/accordion), so keep them to a paragraph and link out
+for anything longer.
+
+<APIReference name="FaqSection" props={[
+  { name: "items", type: "Array<{ question: string; answer: string }>", description: "The questions. Required." },
+  { name: "title", type: "string", default: '"Frequently asked questions"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "badge", type: "string", default: '"FAQ"', description: "Badge above the title." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -21,3 +21,17 @@ import { FeaturesSection } from "@olwiba/ui";
 ```
 
 `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.
+
+## API Reference
+
+`icon` on each feature is a Lucide component, passed uninstantiated — `{ icon: Zap }`, not
+`{ icon: <Zap /> }`.
+
+<APIReference name="FeaturesSection" props={[
+  { name: "features", type: "Array<{ icon: LucideIcon; title: string; description: string; href?: string }>", description: "The cards. A feature with an `href` becomes a link. Required." },
+  { name: "title", type: "string", default: '"Everything you need to ship fast"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "badge", type: "string", default: '"Features"', description: "Badge above the title." },
+  { name: "layout", type: '"grid" | "carousel"', default: '"grid"', description: "How the cards are arranged." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

package/content/docs/marketing/footer.mdx

@@ -14,3 +14,18 @@ description: Site footer with links and branding.
 ```tsx
 import { Footer } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`brand` is the only required prop. `status.label` is a `ReactNode` rather than a string on
+purpose: a real status pill usually carries per-service detail in a tooltip, and typing it as a
+string forced callers to smuggle that through a cast.
+
+<APIReference name="Footer" props={[
+  { name: "brand", type: "{ name: string; logo?: ReactNode; href?: string }", description: "Wordmark, optional mark, and where it links. Required." },
+  { name: "navLinks", type: "Array<{ label: string; href: string }>", description: "The link row." },
+  { name: "socialLinks", type: "Array<{ label: string; href: string; icon: ReactNode }>", description: "Icon links. `label` is the accessible name." },
+  { name: "legal", type: "string", description: "Copyright line." },
+  { name: "status", type: "{ label: ReactNode; operational?: boolean }", description: "Live status pill. `operational` picks the dot colour." },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render links through your router instead of a plain anchor." },
+]} />

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

@@ -14,3 +14,24 @@ description: Above-the-fold hero section with headline, supporting copy, and CTA
 ```tsx
 import { HeroSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`heading` and `description` are required; everything else is opt-in. `primarySlot` replaces the
+primary button entirely — reach for it when the product itself can start in the hero rather than
+one page later.
+
+<APIReference name="HeroSection" props={[
+  { name: "heading", type: "string", description: "The headline. Required." },
+  { name: "description", type: "string", description: "Supporting copy under the headline. Required." },
+  { name: "badge", type: "string", description: "Small badge above the headline." },
+  { name: "primaryCta", type: "{ label: string; href: string }", description: "Primary button. Ignored when `primarySlot` is given." },
+  { name: "secondaryCta", type: "{ label: string; href: string }", description: "Secondary button, and it survives `primarySlot`." },
+  { name: "primarySlot", type: "React.ReactNode", description: "Your own control in place of the primary button — a search field, an email capture. Full-width above the secondary CTA on small screens." },
+  { name: "heroImage", type: "React.ReactNode", description: "What fills the media column." },
+  { name: "media", type: '"image" | "phone" | "none"', default: '"image"', description: "How the media column is framed, or whether there is one." },
+  { name: "phoneSize", type: '"sm" | "md" | "lg"', default: '"lg"', description: 'Phone frame size when media is "phone".' },
+  { name: "avatarUrls", type: "string[]", description: "Stacked avatars beside the social proof line." },
+  { name: "socialProofText", type: "string", description: "The line beside the avatars." },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render CTAs through your router instead of a plain anchor." },
+]} />

package/content/docs/marketing/navbar.mdx

@@ -14,3 +14,17 @@ description: Responsive top navigation bar for marketing sites.
 ```tsx
 import { Navbar } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`controls` sits between the nav and the CTAs and is meant for icon buttons —
+`ModeSwitchMinimal`, `ThemeSwitchMinimal` and the like. Anything with a label belongs in
+`navLinks` or `cta` instead.
+
+<APIReference name="Navbar" props={[
+  { name: "brand", type: "{ name: string; logo?: React.ReactNode; href?: string }", description: "Wordmark, optional mark, and where it links. Required." },
+  { name: "navLinks", type: "Array<{ label: string; href: string }>", description: "The links. Required." },
+  { name: "cta", type: "{ primary?: { label: string; href: string }; secondary?: { label: string; href: string } }", description: "Buttons at the right end." },
+  { name: "controls", type: "React.ReactNode[]", description: "Icon buttons rendered right of the nav and left of the CTAs." },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render links through your router instead of a plain anchor." },
+]} />

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

@@ -14,3 +14,22 @@ description: Email capture form section for marketing pages.
 ```tsx
 import { NewsletterSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`privacyHref` defaults to `"#"`, which is a link that goes nowhere. Point it at your real policy
+before this section ships.
+
+<APIReference name="NewsletterSection" props={[
+  { name: "onSubscribe", type: "(email: string) => void | Promise<void>", description: "Awaited before the success panel appears. The section never posts anywhere on its own." },
+  { name: "badge", type: "string", default: '"Newsletter"', description: "Badge above the title." },
+  { name: "title", type: "string", default: '"Stay in the loop"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "placeholder", type: "string", default: '"you@company.com"', description: "Email field placeholder." },
+  { name: "submitLabel", type: "string", default: '"Subscribe"', description: "Submit button label." },
+  { name: "privacyHref", type: "string", default: '"#"', description: "Target of the privacy link under the field." },
+  { name: "privacyLabel", type: "string", default: '"Privacy Policy"', description: "Text of that link." },
+  { name: "successTitle", type: "string", default: '"You\'re on the list."', description: "Heading of the panel that replaces the form." },
+  { name: "successDescription", type: "string", default: '"We\'ll be in touch soon."', description: "Copy in the success panel." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -23,10 +23,10 @@ Pass `columns={2}` or `columns={3}` when the surrounding page needs an explicit
 
 ## 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. |
+<APIReference name="PostList" props={[
+  { name: "posts", type: "PostCardProps[]", description: "Posts rendered as PostCard items. Required." },
+  { name: "renderLink", type: "AppShellRenderLink", description: "Render links through your router instead of a plain anchor." },
+  { name: "emptyMessage", type: "string", default: '"No posts published yet."', description: "Shown instead of the grid when `posts` is empty." },
+  { name: "columns", type: "2 | 3", default: "automatic", description: "Maximum columns at the widest breakpoint. Setting it disables the automatic short-list balancing." },
+  { name: "className", type: "string", description: "Additional classes on the grid container." },
+]} />

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

@@ -14,3 +14,30 @@ description: Pricing cards with plan details and feature comparison.
 ```tsx
 import { PricingSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+The cadence toggle's state lives inside the section, so `onSelectPlan` is how you find out which
+billing period was selected when a CTA is pressed. Without it the CTAs are inert.
+
+<APIReference name="PricingSection" props={[
+  { name: "plans", type: "PricingPlan[]", description: "The tiers. Required." },
+  { name: "onSelectPlan", type: "(plan: PricingPlan, cadence?: string) => void", description: "Called when a plan's CTA is pressed, with the cadence currently selected." },
+  { name: "title", type: "string", default: '"Simple, transparent pricing"', description: "Section heading." },
+  { name: "description", type: "string", default: '"Start for free. Scale as you grow. No hidden fees."', description: "Copy under the heading." },
+  { name: "badge", type: "React.ReactNode", default: '"Pricing"', description: "Badge above the title." },
+  { name: "mode", type: '"subscription" | "one-time"', default: '"subscription"', description: "Whether prices are recurring. Not the surface treatment — see `surface`." },
+  { name: "cadences", type: "PricingCadence[]", default: "Monthly / Annual", description: "Billing periods sold. One entry renders no toggle; two or more render a tab each." },
+  { name: "defaultCadence", type: "string", default: "first cadence", description: "Which cadence opens selected." },
+  { name: "currency", type: "string", default: '"$"', description: "Symbol prepended to computed prices. Ignored by plans with `priceDisplay`." },
+  { name: "saveBadge", type: "string", default: '"Save 34%"', description: "Fallback savings badge when no `periodsPerYear` is given." },
+  { name: "highlightedBadgeLabel", type: "string", default: '"Founding member"', description: "Badge on highlighted plans with no active countdown. Pass an empty string for none." },
+  { name: "foundingDeadline", type: "string", description: "Runs a countdown on the highlighted plan until this date." },
+  { name: "footnote", type: "string", description: "Small print below the cards." },
+  { name: "isAuthenticated", type: "boolean", description: "Lets plan CTAs read as upgrade rather than sign-up." },
+  { name: "pendingPlanName", type: "string", description: "Marks one plan busy while its checkout is created." },
+  { name: "renderPlanFooter", type: "(plan: PricingPlan) => React.ReactNode", description: "Rendered below each plan's CTA." },
+  { name: "priceEffect", type: 'PricingCardProps["priceEffect"]', default: "UI mode decides", description: 'How a price transitions when the cadence changes. Pass "roll" for an odometer.' },
+  { name: "renderLink", type: "AppShellRenderLink", default: "anchor", description: "Render CTAs through your router instead of a plain anchor." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -14,3 +14,16 @@ description: Key metrics display section for marketing pages.
 ```tsx
 import { StatsSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`value` is a string rather than a number so the section never has to guess at formatting —
+`"99.9%"`, `"12k"` and `"<50ms"` all render as written.
+
+<APIReference name="StatsSection" props={[
+  { name: "stats", type: "Array<{ value: string; label: string; description?: string }>", description: "The figures. Required." },
+  { name: "title", type: "string", default: '"Built for scale, used in production"', description: "Section heading." },
+  { name: "description", type: "string", description: "Copy under the heading. No default — omit it and nothing renders there." },
+  { name: "badge", type: "string", default: '"By the numbers"', description: "Badge above the title." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -14,3 +14,16 @@ description: Team member grid for about and marketing pages.
 ```tsx
 import { TeamSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+`members` has a placeholder default so the section renders before you have the copy. Replace it
+before shipping — the built-in people are not yours.
+
+<APIReference name="TeamSection" props={[
+  { name: "members", type: "TeamMember[]", default: "placeholder team", description: "Each takes `name`, `role`, `bio`, `initials`, an optional `avatar` URL and optional `social` handles." },
+  { name: "badge", type: "string", default: '"Team"', description: "Badge above the title." },
+  { name: "title", type: "string", default: '"The people behind Olwiba"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

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

@@ -14,3 +14,16 @@ description: Customer quote grid for marketing pages.
 ```tsx
 import { TestimonialsSection } from "@olwiba/ui";
 ```
+
+## API Reference
+
+Give each testimonial either an `avatar` or `initials` — with neither, the card falls back to an
+empty circle.
+
+<APIReference name="TestimonialsSection" props={[
+  { name: "testimonials", type: "Array<{ quote: string; name: string; role: string; company?: string; avatar?: string; initials?: string; rating?: number }>", description: "The quotes. Required." },
+  { name: "title", type: "string", default: '"Trusted by teams shipping real products"', description: "Section heading." },
+  { name: "description", type: "string", default: "See source", description: "Copy under the heading." },
+  { name: "badge", type: "string", default: '"Testimonials"', description: "Badge above the title." },
+  { name: "surface", type: '"card" | "soft" | "plain"', default: '"card"', description: "How the section sits on the page. Falls back to MarketingSurfaceProvider." },
+]} />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/ui",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,9 @@
     "start": "bun run server.ts",
     "types:check": "fumadocs-mdx && tsc --noEmit",
     "iso:generate": "bun scripts/generate-iso-previews.ts",
-    "email:generate": "bun scripts/generate-email-previews.ts"
+    "email:generate": "bun scripts/generate-email-previews.ts",
+    "env:check": "dx env-check",
+    "docs:check": "dx docs-check"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -70,9 +72,9 @@
   },
   "devDependencies": {
     "@content-collections/mdx": "^0.2.2",
-    "@olwiba/cn": "0.1.39",
-    "@olwiba/docs": "0.1.45",
-    "@olwiba/dx": "0.0.24",
+    "@olwiba/cn": "0.1.40",
+    "@olwiba/docs": "0.1.46",
+    "@olwiba/dx": "0.0.28",
     "@react-email/render": "^2.1.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-router": "1.154.8",