@olwiba/ui 0.2.25 → 0.2.27

package/content/docs/components/dock.mdx

@@ -0,0 +1,26 @@
+---
+title: Dock
+description: macOS-style icon dock with hover magnification animation.
+---
+
+<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="dock" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { Dock } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="Dock" props={[]} />

package/content/docs/components/feature-card.mdx

@@ -0,0 +1,26 @@
+---
+title: FeatureCard
+description: Icon, title, and description card with hover lift effect.
+---
+
+<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="feature-card" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { FeatureCard } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="FeatureCard" props={[]} />

package/content/docs/components/file-upload.mdx

@@ -0,0 +1,35 @@
+---
+title: FileUpload
+description: Drag-and-drop file picker with a validated upload queue.
+---
+
+<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="file-upload" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { FileUpload } from "@olwiba/ui";
+
+<FileUpload
+  multiple
+  accept="image/png,image/jpeg"
+  maxSizeMb={5}
+  hint="PNG or JPG, up to 5MB each"
+/>
+```
+
+Progress and status are presentation-only — wire `files`/`onFilesChange` to your own upload layer to drive them, or leave the component uncontrolled and use `onFilesAdded` to kick off your own request per file.
+
+## API Reference
+
+<APIReference name="FileUpload" props={[]} />

package/content/docs/components/full-page-spinner.mdx

@@ -0,0 +1,44 @@
+---
+title: FullPageSpinner
+description: A centered full-page loading state for route-level suspense boundaries.
+---
+
+<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="full-page-spinner" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { FullPageSpinner } from "@olwiba/ui";
+```
+
+```tsx
+<FullPageSpinner />
+<FullPageSpinner message="Loading your workspace..." />
+```
+
+Use as a route-level suspense fallback:
+
+```tsx
+import { Suspense } from "react";
+
+<Suspense fallback={<FullPageSpinner message="Loading..." />}>
+  <Routes />
+</Suspense>
+```
+
+## API Reference
+
+<APIReference name="FullPageSpinner" props={[
+  { name: "message", type: "string", default: "-" },
+  { name: "className", type: "string", default: "-" },
+]} />

package/content/docs/components/glass-card.mdx

@@ -0,0 +1,26 @@
+---
+title: GlassCard
+description: Frosted glass surface card with backdrop blur and translucent border.
+---
+
+<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="glass-card" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { GlassCard } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="GlassCard" props={[]} />

package/content/docs/components/image-card.mdx

@@ -0,0 +1,26 @@
+---
+title: ImageCard
+description: Card with background image, gradient overlay, and content slot.
+---
+
+<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="image-card" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { ImageCard } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="ImageCard" props={[]} />

package/content/docs/components/index.mdx

@@ -0,0 +1,49 @@
+---
+title: Components
+description: Interactive and card components provided by @olwiba/ui.
+---
+
+Smaller, focused components built on `@olwiba/cn` primitives.
+
+## Interactive
+
+| Component | Description |
+|-----------|-------------|
+| [Spotlight](/docs/components/spotlight) | Command palette with keyboard shortcut trigger and search |
+| [Dock](/docs/components/dock) | macOS-style icon dock with hover magnification |
+| [ContextMenu](/docs/components/context-menu) | Right-click context menu |
+| [ConfirmDialog](/docs/components/confirm-dialog) | Modal confirmation dialog — pairs with the `useConfirm` hook |
+
+## Data
+
+| Component | Description |
+|-----------|-------------|
+| [DataTable](/docs/components/data-table) | Sortable, paginated data table with optional search and selection |
+| [LoadMore](/docs/components/load-more) | Cursor-pagination footer with infinite scroll or a manual fallback |
+
+## Cards
+
+| Component | Description |
+|-----------|-------------|
+| [GlassCard](/docs/components/glass-card) | Frosted glass surface with backdrop blur |
+| [FeatureCard](/docs/components/feature-card) | Icon, title, and description card |
+| [StatCard](/docs/components/stat-card) | Metric card with value, label, and trend indicator |
+| [TestimonialCard](/docs/components/testimonial-card) | Quote card with avatar and attribution |
+| [PricingCard](/docs/components/pricing-card) | Single pricing tier with feature list and CTA |
+| [ImageCard](/docs/components/image-card) | Card with background image and content overlay |
+
+## Utility
+
+| Component | Description |
+|-----------|-------------|
+| [Spinner](/docs/components/spinner) | Loading spinner |
+| [FullPageSpinner](/docs/components/full-page-spinner) | Centered full-page loading state |
+| [PageHeader](/docs/components/page-header) | Page title with description and action slot |
+| [Suspensed](/docs/components/suspensed) | React.Suspense with a spinner fallback |
+| [ThemeSwitchMinimal](/docs/components/theme-switch-minimal) | Dark / light mode toggle |
+| [ThemeColorUpdater](/docs/components/theme-color-updater) | Syncs a color theme to `data-theme` on `<html>` |
+| [VersionBanner](/docs/components/version-banner) | Dismissible version announcement banner |
+| [RegisterHotkeys](/docs/components/register-hotkeys) | Declarative global keyboard shortcut registration |
+| [RootErrorFallback](/docs/components/root-error-fallback) | Full-page error boundary fallback |
+| [Kbd](/docs/components/kbd) | Keyboard shortcut badge |
+| [OlwibaUIContext](/docs/components/olwiba-ui-context) | Context provider for shared app state |

package/content/docs/components/load-more.mdx

@@ -0,0 +1,34 @@
+---
+title: LoadMore
+description: Cursor-pagination footer with guarded infinite scroll and a manual fallback.
+---
+
+<div className="flex flex-col md:flex-row items-center justify-start gap-2 mb-2">
+  <CopyCommandButton command="bun add @olwiba/ui" />
+</div>
+
+## Usage
+
+```tsx
+import { LoadMore } from "@olwiba/ui";
+
+<LoadMore
+  hasNextPage={query.hasNextPage}
+  isFetchingNextPage={query.isFetchingNextPage}
+  fetchNextPage={query.fetchNextPage}
+  label="projects"
+/>
+```
+
+Use `auto={false}` when the content above has its own client-side pager. An always-visible sentinel below a paginated table would otherwise fetch every cursor page into memory immediately.
+
+## API Reference
+
+<APIReference name="LoadMore" props={[
+  { name: "hasNextPage", type: "boolean", description: "Removes the footer when the cursor is exhausted." },
+  { name: "isFetchingNextPage", type: "boolean", description: "Guards duplicate requests and controls loading feedback." },
+  { name: "fetchNextPage", type: "() => void | Promise<unknown>", description: "Loads the next cursor page." },
+  { name: "auto", type: "boolean", default: "true", description: "Use infinite scroll when true, or a manual button when false." },
+  { name: "label", type: "string", default: '"more"', description: "Plural noun used in the manual button label." },
+  { name: "rootMargin", type: "string", default: '"400px"', description: "IntersectionObserver prefetch margin." },
+]} />

package/content/docs/components/meta.json

@@ -0,0 +1,35 @@
+{
+  "title": "Components",
+  "pages": [
+    "index",
+    "spotlight",
+    "dock",
+    "context-menu",
+    "confirm-dialog",
+    "command-menu",
+    "data-table",
+    "load-more",
+    "chart",
+    "file-upload",
+    "notify",
+    "notifications-popover",
+    "activity-feed",
+    "glass-card",
+    "feature-card",
+    "stat-card",
+    "testimonial-card",
+    "pricing-card",
+    "image-card",
+    "spinner",
+    "full-page-spinner",
+    "page-header",
+    "suspensed",
+    "theme-switch-minimal",
+    "theme-color-updater",
+    "version-banner",
+    "register-hotkeys",
+    "root-error-fallback",
+    "kbd",
+    "olwiba-ui-context"
+  ]
+}

package/content/docs/components/notifications-popover.mdx

@@ -0,0 +1,34 @@
+---
+title: NotificationsPopover
+description: Bell button with unread badge and a persistent notification inbox.
+---
+
+<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="notifications-popover" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { NotificationsPopover } from "@olwiba/ui";
+
+<NotificationsPopover
+  notifications={notifications}
+  onMarkAllRead={() => markAllRead()}
+  onNotificationClick={(n) => { markRead(n.id); router.push(n.href); }}
+/>
+```
+
+Complements `notify()` toasts: a toast announces an event as it happens, this popover holds the history. Presentation-only — pass `notifications` from your own data layer and persist read state in the callbacks. Unread items get a dot, a subtle background, and count toward the bell badge.
+
+## API Reference
+
+<APIReference name="NotificationsPopover" props={[]} />

package/content/docs/components/notify.mdx

@@ -0,0 +1,40 @@
+---
+title: notify
+description: Rich toast notifications on top of sonner — one component, several variants.
+---
+
+<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="notify" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { notify } from "@olwiba/ui";
+import { Toaster } from "@olwiba/cn";
+
+// Mount once, e.g. in your root layout
+<Toaster />
+
+// Fire from anywhere
+notify({ variant: "success", title: "Deploy complete", description: "Your project is live." });
+notify({
+  variant: "message",
+  title: "New comment",
+  action: { label: "Reply", onClick: () => {} },
+});
+```
+
+`notify()` renders `NotificationToast` through sonner's `toast.custom` — swap the `variant` and pass `avatar`/`action`/`secondaryAction` rather than reaching for a different toast component per shape.
+
+## API Reference
+
+<APIReference name="NotifyOptions" props={[]} />

package/content/docs/components/olwiba-ui-context.mdx

@@ -0,0 +1,69 @@
+---
+title: OlwibaUIContext
+description: React context provider that supplies shared app state (isMobile) to the component tree.
+---
+
+<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="olwiba-ui-context" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { OlwibaUIProvider, useOlwibaUI } from "@olwiba/ui";
+```
+
+Wrap your app root — `isMobile` is auto-detected via `useIsMobile()` from `@olwiba/cn`:
+
+```tsx
+<OlwibaUIProvider>
+  <App />
+</OlwibaUIProvider>
+```
+
+Pass `mode` when an external store owns the current mode. The provider treats it as a controlled value and reacts when it changes:
+
+```tsx
+<OlwibaUIProvider mode={mode}>
+  <App />
+</OlwibaUIProvider>
+```
+
+When `mode` is omitted, the provider starts at `default` and descendants may change it through `setMode` from `useOlwibaUI()`.
+
+Override with a server-detected value to avoid hydration flicker:
+
+```tsx
+<OlwibaUIProvider isMobile={serverDetectedMobile}>
+  <App />
+</OlwibaUIProvider>
+```
+
+Read the value from any child component:
+
+```tsx
+function Sidebar() {
+  const { isMobile } = useOlwibaUI();
+  return isMobile ? <MobileNav /> : <DesktopSidebar />;
+}
+```
+
+## API Reference
+
+<APIReference name="OlwibaUIProvider" props={[
+  { name: "children", type: "ReactNode", default: "-" },
+  { name: "isMobile", type: "boolean", default: "auto-detected" },
+  { name: "mode", type: "'default' | 'playful' | 'smooth'", default: "internally managed from 'default'" },
+]} />
+
+<APIReference name="useOlwibaUI" props={[
+  { name: "isMobile", type: "boolean", default: "-" },
+]} />

package/content/docs/components/page-header.mdx

@@ -0,0 +1,42 @@
+---
+title: PageHeader
+description: A consistent top-of-page header with title, optional description, and an action slot.
+---
+
+<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="page-header" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { PageHeader } from "@olwiba/ui";
+```
+
+```tsx
+<PageHeader
+  title="Team members"
+  description="Manage who has access to this workspace."
+>
+  <Button>Invite member</Button>
+</PageHeader>
+```
+
+`children` sit in a flex row aligned to the right of the title — ideal for primary CTAs or toolbar buttons.
+
+## API Reference
+
+<APIReference name="PageHeader" props={[
+  { name: "title", type: "string", default: "-" },
+  { name: "description", type: "string", default: "-" },
+  { name: "className", type: "string", default: "-" },
+  { name: "children", type: "ReactNode", default: "-" },
+]} />

package/content/docs/components/pricing-card.mdx

@@ -0,0 +1,26 @@
+---
+title: PricingCard
+description: Single pricing tier card with feature list and 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>
+
+<Sandbox id="pricing-card" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { PricingCard } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="PricingCard" props={[]} />

package/content/docs/components/register-hotkeys.mdx

@@ -0,0 +1,50 @@
+---
+title: RegisterHotkeys
+description: Declaratively register global keyboard shortcuts with modifier support.
+---
+
+<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="register-hotkeys" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { RegisterHotkeys, type Hotkey } from "@olwiba/ui";
+```
+
+```tsx
+const hotkeys: Hotkey[] = [
+  { key: 'k', meta: true, handler: () => openSearch(), description: 'Open search' },
+  { key: 'Escape', handler: () => closeModal(), description: 'Close' },
+  { key: '?', shift: true, handler: () => showHelp(), description: 'Show help' },
+];
+
+<RegisterHotkeys hotkeys={hotkeys} />
+```
+
+Attaches a single `keydown` listener on `document` — renders nothing, cleans up on unmount. Modifier matching is exact: `{ meta: true }` only fires when Meta is held and Ctrl/Shift/Alt are not.
+
+## API Reference
+
+<APIReference name="RegisterHotkeys" props={[
+  { name: "hotkeys", type: "Hotkey[]", default: "-" },
+]} />
+
+<APIReference name="Hotkey" props={[
+  { name: "key", type: "string", default: "-" },
+  { name: "ctrl", type: "boolean", default: "false" },
+  { name: "meta", type: "boolean", default: "false" },
+  { name: "shift", type: "boolean", default: "false" },
+  { name: "alt", type: "boolean", default: "false" },
+  { name: "handler", type: "() => void", default: "-" },
+  { name: "description", type: "string", default: "-" },
+]} />

package/content/docs/components/root-error-fallback.mdx

@@ -0,0 +1,39 @@
+---
+title: RootErrorFallback
+description: A full-page error fallback for React error boundaries.
+---
+
+<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="root-error-fallback" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { RootErrorFallback } from "@olwiba/ui";
+```
+
+Compatible with `react-error-boundary`'s `FallbackComponent` prop out of the box:
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+<ErrorBoundary FallbackComponent={RootErrorFallback}>
+  <App />
+</ErrorBoundary>
+```
+
+## API Reference
+
+<APIReference name="RootErrorFallback" props={[
+  { name: "error", type: "Error", default: "-" },
+  { name: "resetErrorBoundary", type: "() => void", default: "-" },
+]} />

package/content/docs/components/spotlight.mdx

@@ -0,0 +1,26 @@
+---
+title: Spotlight
+description: Command palette shell with keyboard shortcut trigger and search input.
+---
+
+<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="spotlight" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { Spotlight } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="Spotlight" props={[]} />

package/content/docs/components/stat-card.mdx

@@ -0,0 +1,26 @@
+---
+title: StatCard
+description: Metric card with value, label, and optional trend indicator.
+---
+
+<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="stat-card" />
+
+## Installation
+
+```sh
+bun add @olwiba/ui
+```
+
+## Usage
+
+```tsx
+import { StatCard } from "@olwiba/ui";
+```
+
+## API Reference
+
+<APIReference name="StatCard" props={[]} />