@olwiba/ui 0.2.25 → 0.2.27

package/content/docs/app/app-shell.mdx

@@ -0,0 +1,71 @@
+---
+title: AppShell
+description: Full-page sidebar shell with collapsible nav, user menu, and header. Pass your nav items, brand, and user; get a consistent shell across every route.
+---
+
+<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="app-shell" shellPreview />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { AppShell } from "@olwiba/ui";
+import { LayoutDashboard, Plus, UserRound } from "lucide-react";
+import { Link } from "your-router"; // TanStack, Next.js, etc.
+
+export function AppLayout({ children }) {
+  return (
+    <AppShell
+      brand={{ name: "My App", href: "/" }}
+      navItems={[
+        { icon: LayoutDashboard, label: "Dashboard", href: "/dashboard", isActive: true },
+      ]}
+      action={{ icon: Plus, label: "New item", href: "/new" }}
+      user={{
+        email: "user@example.com",
+        plan: "free",
+        avatarFallback: <UserRound aria-hidden className="size-5" />,
+        onSignOut: () => signOut(),
+      }}
+      pageTitle="Dashboard"
+      renderLink={({ href, children }) => <Link to={href}>{children}</Link>}
+    >
+      {children}
+    </AppShell>
+  );
+}
+```
+
+Use `sidebarPosition="contained"` in docs sandboxes or embedded previews so the shell fits its parent rather than filling the viewport:
+
+```tsx
+<AppShell sidebarPosition="contained" />
+```
+
+## API Reference
+
+<APIReference name="AppShell" props={[
+  { name: "brand", type: "AppShellBrand", description: "App name, logo, and href for the sidebar header." },
+  { name: "navItems", type: "AppNavItem[]", description: "Primary navigation links rendered in the sidebar." },
+  { name: "action", type: "AppShellAction", description: "CTA button above nav items (e.g. New item, Quick create)." },
+  { name: "user", type: "AppShellUser", description: "User info and callbacks shown in the sidebar footer dropdown." },
+  { name: "pageTitle", type: "string", default: '"Dashboard"', description: "Title shown in the top header bar." },
+  { name: "headerStart", type: "ReactNode | ((controls: AppShellHeaderControls) => ReactNode)", description: "Header-start content. Its render form can expand the shell without importing the private sidebar context." },
+  { name: "sidebarFooterStart", type: "ReactNode", description: "Product chrome rendered above the user menu in the sidebar footer." },
+  { name: "sidebarContentKey", type: "string", description: "Remount key for animated sidebar identity or navigation-mode changes." },
+  { name: "sidebarContentClassName", type: "string", description: "Classes applied to the sidebar header, content, and footer." },
+  { name: "renderLink", type: "AppShellRenderLink", description: "Override link rendering for SPA navigation. Default: native <a>." },
+  { name: "collapsible", type: '"icon" | "offcanvas" | "none"', default: '"icon"', description: 'Sidebar collapse behaviour.' },
+  { name: "sidebarPosition", type: '"viewport" | "contained"', default: '"viewport"', description: 'Use "contained" for docs sandboxes or embedded previews; "viewport" for full-page app shells.' },
+  { name: "side", type: '"left" | "right"', default: '"left"', description: "Which side the sidebar sits on." },
+  { name: "children", type: "ReactNode", description: "Page content rendered in the main area." },
+]} />

package/content/docs/app/auth-section.mdx

@@ -0,0 +1,73 @@
+---
+title: AuthSection
+description: Sign in, sign up, forgot/reset password, and code verification — one form, five modes.
+---
+
+<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="auth-section" shellPreview />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { AuthSection } from "@olwiba/ui";
+
+// Centered (default)
+<AuthSection
+  onSubmit={(e) => { e.preventDefault(); signIn() }}
+  onSso={() => signInWithSso()}
+  signUpHref="/register"
+  forgotPasswordHref="/forgot-password"
+/>
+
+// Split layout with decorative panel
+<AuthSection
+  layout="split"
+  onSubmit={(e) => { e.preventDefault(); signIn() }}
+/>
+
+// Custom form
+<AuthSection layout="split">
+  <MyCustomForm />
+</AuthSection>
+
+// Forgot password
+<AuthSection mode="forgot-password" signInHref="/sign-in" onSubmit={handleForgotPassword} success={sent ? "Check your inbox for a reset link." : undefined} />
+
+// Reset password (reached via the emailed link)
+<AuthSection mode="reset-password" signInHref="/sign-in" onSubmit={handleResetPassword} />
+
+// Verify code (email verification or 2FA)
+<AuthSection mode="verify" destination={email} onSubmit={handleVerify} onResend={handleResend} />
+```
+
+Every mode shares the same `AuthSection`/`DefaultForm` — swap `mode` rather than reaching for a separate screen component per auth step.
+
+## API Reference
+
+<APIReference name="AuthSection" props={[
+  { name: "mode", type: '"signin" | "signup" | "forgot-password" | "reset-password" | "verify"', default: '"signin"', description: "Controls form title, fields, and footer text." },
+  { name: "layout", type: '"centered" | "split"', default: '"centered"', description: "Visual layout of the auth screen." },
+  { name: "children", type: "ReactNode", description: "Custom form content. Defaults to the built-in form." },
+  { name: "panel", type: "ReactNode", description: "Split layout only — custom content for the left decorative panel." },
+  { name: "onSubmit", type: "(e: FormEvent) => void", description: "Form submit handler." },
+  { name: "onSso", type: "() => void", description: "Shows a SSO button when provided (signin only)." },
+  { name: "signUpHref", type: "string", default: '"#"', description: "Link for the sign-up prompt (signin)." },
+  { name: "signInHref", type: "string", default: '"#"', description: "Link back to sign-in (signup / forgot-password / reset-password / verify)." },
+  { name: "forgotPasswordHref", type: "string", default: '"#"', description: "Link for the forgot password prompt (signin)." },
+  { name: "onResend", type: "() => void", description: "Re-sends the one-time code (verify)." },
+  { name: "destination", type: "string", description: "Address the code was sent to (verify)." },
+  { name: "codeLength", type: "number", default: "6", description: "Number of digits in the code (verify)." },
+  { name: "brand", type: "ReactNode", description: "Logo or brand mark shown above the form title." },
+  { name: "error", type: "string", description: "Error message shown below the form fields." },
+  { name: "success", type: "string", description: "Positive confirmation message shown below the form fields." },
+  { name: "className", type: "string", description: "Class applied to the outer wrapper." },
+]} />

package/content/docs/app/billing-panel.mdx

@@ -0,0 +1,38 @@
+---
+title: BillingPanel
+description: In-app billing summary — current plan, usage, payment method, and invoice history.
+---
+
+<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="billing-panel" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { BillingPanel } from "@olwiba/ui";
+
+<BillingPanel
+  planName="Pro"
+  planPrice="$29/mo"
+  renewalDate="March 12, 2026"
+  usage={[{ label: "Seats", used: 6, limit: 10 }]}
+  paymentMethod={{ brand: "Visa", last4: "4242", expiry: "08/27" }}
+  invoices={invoices}
+  onManagePlan={() => openPlanDialog()}
+/>
+```
+
+This is the account-side billing view — for marketing plan comparisons, use `PricingSection`/`UpgradePrompt` instead.
+
+## API Reference
+
+<APIReference name="BillingPanel" props={[]} />

package/content/docs/app/empty-state.mdx

@@ -0,0 +1,47 @@
+---
+title: EmptyState
+description: Zero-content placeholder with icon, heading, description, and an optional CTA button.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<ComponentPreview name="empty-state" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { EmptyState } from "@olwiba/ui";
+import { FolderOpen } from "lucide-react";
+
+<EmptyState
+  icon={FolderOpen}
+  title="No projects yet"
+  description="Create your first project to get started."
+  variant="card"
+  action={<Button>New project</Button>}
+  secondaryAction={<Button variant="ghost">Learn more</Button>}
+/>
+```
+
+## API Reference
+
+<APIReference name="EmptyState" props={[
+  { name: "icon", type: "LucideIcon", description: "Icon rendered above the heading." },
+  { name: "title", type: "string", description: "Primary heading." },
+  { name: "description", type: "ReactNode", description: "Supporting content below the heading." },
+  { name: "eyebrow", type: "ReactNode", description: "Optional compact label above the heading." },
+  { name: "action", type: "ReactNode", description: "Primary action." },
+  { name: "secondaryAction", type: "ReactNode", description: "Secondary action rendered alongside the primary action." },
+  { name: "variant", type: '"plain" | "card"', default: '"plain"', description: "Use card for route-level product empty states." },
+  { name: "compact", type: "boolean", default: "false", description: "Reduces the card presentation's height and padding." },
+  { name: "fill", type: "boolean", default: "false", description: "Fills a flex-sized parent." },
+  { name: "className", type: "string", description: "Class applied to the root element." },
+]} />

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

@@ -0,0 +1,31 @@
+---
+title: ErrorPage
+description: Full-page 404 / error fallback with navigation actions.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+<ComponentPreview name="error-page" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { ErrorPage } from "@olwiba/ui";
+
+// In a TanStack Router not-found route
+export const Route = createFileRoute("/404")({
+  component: () => <ErrorPage />,
+});
+```
+
+## API Reference
+
+`ErrorPage` takes no props — it renders a self-contained 404 screen with a Go back and Take me home action.

package/content/docs/app/index.mdx

@@ -0,0 +1,13 @@
+---
+title: App UI
+description: Shells and screens for application UIs — sidebar shell, auth, empty states, and error pages.
+---
+
+App UI components are the structural building blocks of a product interface. They're configured once and used across every route.
+
+| Component | Description |
+|-----------|-------------|
+| `AppShell` | Full-page sidebar shell with nav, user menu, and header |
+| `AuthSection` | Sign-in screen — centered or split layout |
+| `EmptyState` | Zero-content placeholder with icon, copy, and CTA |
+| `ErrorPage` | 404 / error fallback page |

package/content/docs/app/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "App UI",
+  "pages": ["index", "app-shell", "auth-section", "empty-state", "error-page", "settings-section", "team-members-panel", "billing-panel", "onboarding-wizard", "update-banner"]
+}

package/content/docs/app/onboarding-wizard.mdx

@@ -0,0 +1,41 @@
+---
+title: OnboardingWizard
+description: Stateful multi-step onboarding flow.
+---
+
+<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="onboarding-wizard" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { OnboardingWizard } from "@olwiba/ui";
+
+<OnboardingWizard
+  onComplete={() => router.push("/dashboard")}
+  steps={[
+    { id: "welcome", title: "Welcome", content: <WelcomeStep /> },
+    {
+      id: "workspace",
+      title: "Name your workspace",
+      content: <WorkspaceNameStep />,
+      onNext: () => (name.trim() ? true : "Give your workspace a name to continue."),
+    },
+  ]}
+/>
+```
+
+One component driven by a `steps` array — swap the array to reshape the flow rather than hand-building a new wizard per feature. `onNext` can return `false` or an error string to block advancing.
+
+## API Reference
+
+<APIReference name="OnboardingWizard" props={[]} />

package/content/docs/app/settings-section.mdx

@@ -0,0 +1,37 @@
+---
+title: SettingsSection
+description: One title/description/content row for building a settings page.
+---
+
+<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="settings-section" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { SettingsSection } from "@olwiba/ui";
+
+<div className="divide-y divide-border">
+  <SettingsSection title="Profile" description="This appears on your public profile.">
+    <MyProfileForm />
+  </SettingsSection>
+  <SettingsSection title="Delete workspace" description="This cannot be undone." danger>
+    <Button variant="destructive">Delete workspace</Button>
+  </SettingsSection>
+</div>
+```
+
+Stack a few inside a `divide-y` wrapper to build a full settings page — one block reused per row, rather than a bespoke layout each time.
+
+## API Reference
+
+<APIReference name="SettingsSection" props={[]} />

package/content/docs/app/team-members-panel.mdx

@@ -0,0 +1,35 @@
+---
+title: TeamMembersPanel
+description: Member list with role management and an invite dialog.
+---
+
+<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-members-panel" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { TeamMembersPanel } from "@olwiba/ui";
+
+<TeamMembersPanel
+  members={members}
+  onInvite={(email, role) => inviteMember(email, role)}
+  onRoleChange={(id, role) => updateRole(id, role)}
+  onRemove={(id) => removeMember(id)}
+/>
+```
+
+Built on top of `DataTable` — pass `roles` to customize the options offered in the invite dialog and per-row role menu.
+
+## API Reference
+
+<APIReference name="TeamMembersPanel" props={[]} />

package/content/docs/app/update-banner.mdx

@@ -0,0 +1,43 @@
+---
+title: UpdateBanner
+description: Slide-in banner that tells users a new deploy shipped and their tab is stale — poll a version endpoint, offer one-click refresh.
+---
+
+<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="update-banner" />
+
+## Usage
+
+Bake a build version into the client bundle (e.g. vite `define` with the git SHA), expose the same value from a `/api/version` endpoint, and mount the banner once in the root layout:
+
+```tsx
+import { UpdateBanner } from "@olwiba/ui";
+
+declare const __BUILD_VERSION__: string;
+
+<UpdateBanner
+  currentVersion={__BUILD_VERSION__}
+  fetchVersion={async () => {
+    const res = await fetch("/api/version", { cache: "no-store" });
+    return res.json();
+  }}
+/>
+```
+
+When a new deploy goes live, open tabs still run the old bundle; the next poll sees a different server version and the banner slides in. Refresh defaults to a full reload — pass `onRefresh` to hook a celebration or custom flow first.
+
+## API Reference
+
+<APIReference name="UpdateBanner" props={[
+  { name: "currentVersion", type: "string", description: "Version baked into the running bundle at build time." },
+  { name: "fetchVersion", type: "() => Promise<{ version: string }>", description: "Fetch the deployed version — the host app wires its own endpoint." },
+  { name: "intervalMs", type: "number", default: "300000", description: "Poll interval in ms." },
+  { name: "forceShow", type: "boolean", default: "false", description: "Force the banner visible (demos/testing)." },
+  { name: "onRefresh", type: "() => void", description: "Refresh click handler; defaults to window.location.reload()." },
+  { name: "message", type: "ReactNode", description: "Banner copy." },
+  { name: "buttonLabel", type: "string", default: '"Refresh now"', description: "Refresh button label." },
+  { name: "className", type: "string", description: "Class applied to the banner card." },
+]} />

package/content/docs/components/activity-feed.mdx

@@ -0,0 +1,42 @@
+---
+title: ActivityFeed
+description: Vertical activity timeline with avatar or icon markers connected by a rail.
+---
+
+<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="activity-feed" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { ActivityFeed } from "@olwiba/ui";
+
+<ActivityFeed
+  items={[
+    {
+      id: "1",
+      title: <><b>Ana</b> deployed to production</>,
+      description: "v0.1.16 · 12 commits",
+      timestamp: "2h ago",
+      avatar: "/avatars/ana.png",
+      initials: "AS",
+    },
+    { id: "2", title: "Subscription renewed", timestamp: "Yesterday", icon: <CreditCard /> },
+  ]}
+/>
+```
+
+Presentation-only: pass pre-formatted timestamps and rich `title` nodes from your own data layer. Items with `avatar` render an avatar marker; otherwise `icon` (or a default) renders in a bordered circle.
+
+## API Reference
+
+<APIReference name="ActivityFeed" props={[]} />

package/content/docs/components/chart.mdx

@@ -0,0 +1,47 @@
+---
+title: Chart
+description: Theme-aware line, area, bar, and donut charts — one component, type switches the form.
+---
+
+<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="chart" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { Chart } from "@olwiba/ui";
+
+<Chart
+  type="line"
+  data={revenue}
+  xKey="month"
+  series={[
+    { key: "mrr", label: "MRR" },
+    { key: "costs", label: "Costs" },
+  ]}
+  valueFormatter={(v) => `$${v.toLocaleString()}`}
+/>
+```
+
+Pick the form by the data's job: `line`/`area` for change over time, `bar` for magnitude comparison, `donut` for part-of-whole. Colors come from the `--chart-1..5` theme tokens in fixed order — series keep their color when others are filtered out. Override per series with `color`.
+
+Donut uses `xKey` for slice labels and `series[0].key` for values. More than 5 slices: fold the tail into an "Other" row in your data rather than adding hues.
+
+```tsx
+<Chart type="donut" data={plans} xKey="plan" series={[{ key: "users" }]} />
+```
+
+A legend renders automatically for multiple series (and donuts); a single named series doesn't need one. Tooltips are always on.
+
+## API Reference
+
+<APIReference name="Chart" props={[]} />

package/content/docs/components/command-menu.mdx

@@ -0,0 +1,41 @@
+---
+title: CommandMenu
+description: Global Cmd+K / Ctrl+K search palette.
+---
+
+<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="command-menu" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { CommandMenu } from "@olwiba/ui";
+import { LayoutDashboard, Settings } from "lucide-react";
+
+<CommandMenu
+  groups={[
+    {
+      heading: "Navigate",
+      items: [
+        { id: "dashboard", label: "Dashboard", icon: LayoutDashboard, onSelect: () => router.push("/dashboard") },
+        { id: "settings", label: "Settings", icon: Settings, onSelect: () => router.push("/settings") },
+      ],
+    },
+  ]}
+/>
+```
+
+Registers the Cmd+K (mac) / Ctrl+K (win) hotkey by default — pass `hotkey={false}` and your own `open`/`onOpenChange` if you'd rather trigger it from a button.
+
+## API Reference
+
+<APIReference name="CommandMenu" props={[]} />

package/content/docs/components/confirm-dialog.mdx

@@ -0,0 +1,26 @@
+---
+title: ConfirmDialog
+description: Modal confirmation dialog — UI shell for the useConfirm hook.
+---
+
+<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="confirm-dialog" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { ConfirmDialog } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="ConfirmDialog" props={[]} />

package/content/docs/components/context-menu.mdx

@@ -0,0 +1,26 @@
+---
+title: ContextMenu
+description: Right-click context menu with animated entry.
+---
+
+<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="context-menu" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { ContextMenu } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="ContextMenu" props={[]} />

package/content/docs/components/data-table.mdx

@@ -0,0 +1,40 @@
+---
+title: DataTable
+description: Sortable, paginated, optionally-selectable data table built on TanStack Table.
+---
+
+<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="data-table" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { DataTable, type DataTableColumn } from "@olwiba/ui";
+
+const columns: DataTableColumn<Project>[] = [
+  { accessorKey: "name", header: "Project" },
+  { accessorKey: "status", header: "Status" },
+];
+
+<DataTable
+  columns={columns}
+  data={projects}
+  searchKey="name"
+  toolbar={<Button size="sm">New project</Button>}
+/>
+```
+
+One component — toggle `searchKey`, `selectable`, and `pageSize` rather than reaching for a different table per use case. Columns are standard TanStack Table `ColumnDef`s, so sorting, custom cells, and accessors all work as usual.
+
+## API Reference
+
+<APIReference name="DataTable" props={[]} />