@nexub/mcp 0.0.0-stage → 1.7.0

package/dist/skill/references/components/link.md

@@ -0,0 +1,38 @@
+# Link
+
+Styled anchor link with variant and external support.
+
+- Package: `@nexub/react` · Category: Inline Primitives · Status: stable
+- Import: `import { Link } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/link
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'muted' \| 'underline'` |  | Visual style of the link. |
+| `external` | `boolean` |  | Opens the link in a new tab with appropriate rel attributes. |
+| `href` | `string` |  | The URL the link points to. |
+| `asChild` | `boolean` |  | Merges props onto the immediate child element (Radix Slot). |
+
+## Example: Default
+
+```tsx
+<Link href="#">View documentation</Link>
+```
+
+## Example: Variants
+
+```tsx
+<div style={{ display: 'flex', gap: '16px' }}>
+  <Link href="#" variant="default">Default</Link>
+  <Link href="#" variant="muted">Muted</Link>
+  <Link href="#" variant="underline">Underline</Link>
+</div>
+```
+
+## Example: External
+
+```tsx
+<Link href="#" external>Open in new tab</Link>
+```

package/dist/skill/references/components/list-detail.md

@@ -0,0 +1,27 @@
+# List Detail
+
+The list-detail layout: side by side at 720px+ of its own width (a container query), one pane at a time below.
+
+- Package: `@nexub/patterns` · Category: Layout · Status: beta
+- Import: `import { ListDetail } from '@nexub/patterns';`
+- Docs: https://nexub-ds-docs.pages.dev/patterns/list-detail
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `list / detail` (required) | `ReactNode` |  | The two panes. |
+| `showDetail` | `boolean` | `false` | When narrow, show the detail instead of the list (set it on selection). |
+| `onBack` | `() => void` |  | Back button, shown only when narrow. |
+| `listWidth` | `'sm' \| 'md' \| 'lg'` | `'md'` | Fixed list width when both panes show (288 / 320 / 400px). |
+
+## Example: Default
+
+```tsx
+<ListDetail
+  showDetail={selected !== null}
+  onBack={() => setSelected(null)}
+  list={<MessageList onSelect={setSelected} />}
+  detail={<Message id={selected} />}
+/>
+```

package/dist/skill/references/components/media-card.md

@@ -0,0 +1,61 @@
+# Media Card
+
+An image card with a glass caption over a soft scrim. With `href`, the whole card is one link.
+
+- Package: `@nexub/react` · Category: Layout · Status: beta
+- Import: `import { MediaCard } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/media-card
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` (required) | `string` |  | Image URL. Loaded lazily. |
+| `alt` (required) | `string` |  | Image description. Pass '' when the image is decorative. |
+| `ratio` | `'16/9' \| '4/3' \| '1/1' \| '3/4'` | `'16/9'` | Aspect ratio of the image box. |
+| `title` | `ReactNode` |  | Caption title, rendered as an h3. |
+| `description` | `ReactNode` |  | Caption text under the title. |
+| `eyebrow` | `ReactNode` |  | Small label above the title. |
+| `href` | `string` |  | Makes the whole card one link, stretched from the title (so it needs `title`). Adds the hover lift and image zoom. |
+| `children` | `ReactNode` |  | Actions under the caption. They stay clickable above the stretched link. |
+
+## Example: With link
+
+```tsx
+<MediaCard
+  src="/covers/lisbon.jpg"
+  alt=""
+  eyebrow="Guide"
+  title="A weekend in Lisbon"
+  description="Where to eat, walk and stay."
+  href="/guides/lisbon"
+/>
+```
+
+## Example: Without link, with actions
+
+```tsx
+<MediaCard src="/covers/q3.jpg" alt="" title="Q3 brand shoot" description="48 photos">
+  <Button size="sm" variant="tonal">Open</Button>
+  <Button size="sm" variant="text">Share</Button>
+</MediaCard>
+```
+
+## Example: Ratios
+
+```tsx
+<MediaCard ratio="16/9" src={src} alt="" title="16/9" />
+<MediaCard ratio="4/3" src={src} alt="" title="4/3" />
+<MediaCard ratio="1/1" src={src} alt="" title="1/1" />
+<MediaCard ratio="3/4" src={src} alt="" title="3/4" />
+```
+
+## Accessibility
+
+- Roles: link (when `href` is set), heading level 3 (title)
+- `Tab`: Focuses the link (the card shows the focus ring), then any actions.
+- `Enter`: Follows the link.
+- With `href`, the link’s name is the title only, not the whole caption.
+- Most card images repeat the title, so `alt=""` is usually right.
+
+Related: [card](card.md)

package/dist/skill/references/components/message-bubble.md

@@ -0,0 +1,68 @@
+# Message Bubble
+
+One message in a conversation. User messages sit in a bubble at the end; assistant replies run full width. MessageActions adds copy, feedback and regenerate.
+
+- Package: `@nexub/react` · Category: AI · Status: beta
+- Import: `import { MessageBubble } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/message-bubble
+
+## When to use
+
+- Each turn in a chat or assistant thread, inside Conversation.
+- MessageActions under assistant replies the user may want to copy, rate or retry.
+
+## When not to use
+
+- Comment threads and activity logs: use ActivityFeed or NotificationItem.
+- Model output as HTML: render text or React elements as children, never `dangerouslySetInnerHTML`.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `from` (required) | `'user' \| 'assistant' \| 'system'` |  | Who sent it. Sets layout and the default accessible name. |
+| `avatar` | `ReactNode` |  | Assistant only: shown at the inline start. |
+| `name` | `string` |  | Accessible name of the message. Defaults to "You said" or "Assistant said". |
+| `status` | `'sending' \| 'error'` |  | `sending` sets `aria-busy`; `error` shows "Failed to send". |
+| `onRetry` | `() => void` |  | With `status="error"`, adds a Retry button. |
+| `messages` | `Partial<MessageStrings>` |  | Local string overrides. |
+| `MessageActions text` | `string` |  | Text Copy puts on the clipboard. |
+| `MessageActions copy` | `boolean` | `true` | Set false to hide Copy. |
+| `MessageActions feedback / defaultFeedback / onFeedback` | `'up' \| 'down' \| null` |  | Thumbs up/down appear when `onFeedback` is set. Pressing the active one clears it. |
+| `MessageActions onRegenerate` | `() => void` |  | Shows Regenerate when set. |
+
+## Example: Conversation
+
+Hover or focus the assistant reply to show its actions.
+
+```tsx
+<MessageBubble from="user">How do I cancel my subscription?</MessageBubble>
+<MessageBubble from="assistant" avatar={<Avatar size="sm" fallback={<Sparkles />} />}>
+  <p>Open Settings, then Billing, and choose Cancel plan. You keep access until the end of the billing period.</p>
+  <MessageActions
+    text="Open Settings, then Billing, and choose Cancel plan."
+    onFeedback={(value) => logFeedback(value)}
+    onRegenerate={() => regenerate()}
+  />
+</MessageBubble>
+<MessageBubble from="system">Conversation moved to Billing support</MessageBubble>
+```
+
+## Example: Failed to send
+
+```tsx
+<MessageBubble from="user" status="error" onRetry={() => resend()}>
+  Can I get a refund for last month?
+</MessageBubble>
+```
+
+## Accessibility
+
+- Roles: article (each message), alert (send error), button (actions)
+- `Tab`: Moves through the action buttons; focusing one reveals the row.
+- `Space / Enter`: Activates an action. Feedback buttons toggle.
+- Each message is an `article` named "You said" or "Assistant said", so users can jump between messages.
+- Feedback buttons expose `aria-pressed`. Copy announces "Copied" through a status region.
+- The action row is only visually hidden until hover; it stays in the tab order and accessibility tree.
+
+Related: [streaming-text](streaming-text.md), [conversation](conversation.md), [citation](citation.md)

package/dist/skill/references/components/money-input.md

@@ -0,0 +1,30 @@
+# Money Input
+
+An amount field: locale-aware parsing as you type, grouped on blur, the currency symbol leading.
+
+- Package: `@nexub/react` · Category: Form & Input · Status: beta
+- Import: `import { MoneyInput } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/money-input
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `currency` (required) | `string` |  | ISO 4217 code, e.g. "EUR". |
+| `locale` | `string` |  | BCP 47 locale for separators. Defaults to the user's. |
+| `value / defaultValue` | `number \| null` |  | The amount, or null when empty. |
+| `onValueChange` | `(value: number \| null) => void` |  | Parsed amount, rounded to the minor unit, as the person types. |
+
+## Example: Default
+
+```tsx
+<MoneyInput aria-label="Amount to send" currency="USD" defaultValue={1250} onValueChange={setAmount} />
+```
+
+## Example: German separators
+
+```tsx
+<MoneyInput aria-label="Betrag" currency="EUR" locale="de-DE" defaultValue={1234.5} />
+```
+
+Related: [amount](amount.md), [number-input](number-input.md), [input](input.md)

package/dist/skill/references/components/motion-collapse.md

@@ -0,0 +1,57 @@
+# Collapse
+
+Expands and collapses content along the block axis.
+
+- Package: `@nexub/react` · Category: Motion · Status: stable
+- Import: `import { MotionCollapse } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/motion-collapse
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` (required) | `boolean` |  | When true, expands the content to its natural height. When false, collapses it to zero height. |
+| `duration` | `'instant' \| 'fast' \| 'normal' \| 'slow' \| 'slower'` | `'normal'` | Controls the animation speed using the design token scale. |
+| `easing` | `'linear' \| 'in' \| 'out' \| 'in-out' \| 'out-expo' \| 'spring'` | `'out'` | Easing curve applied to the animation. |
+| `unmountOnExit` | `boolean` | `false` | Removes the element from the DOM after the collapse animation completes. |
+| `as` | `React.ElementType` | `'div'` | The HTML element or component to render as the wrapper. |
+| `children` (required) | `React.ReactNode` |  | Content to expand and collapse. |
+
+## Example: Default
+
+```tsx
+<Collapse in={true}>
+  <div style={{ padding: '16px', background: 'var(--color-bg-subtle)', borderRadius: 'var(--radius-md)' }}>
+    Collapsed content
+  </div>
+</Collapse>
+```
+
+## Example: Toggle
+
+```tsx
+function CollapseToggle() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      <Button variant="outline" onClick={() => setOpen((o) => !o)}>
+        {open ? 'Collapse' : 'Expand'}
+      </Button>
+      <Collapse in={open} unmountOnExit>
+        <div
+          style={{
+            padding: '16px',
+            background: 'var(--color-bg-subtle)',
+            borderRadius: 'var(--radius-md)',
+            color: 'var(--color-text-secondary)',
+            fontSize: '0.875rem',
+          }}
+        >
+          This section smoothly expands and collapses along the vertical axis.
+          It preserves the natural document flow by animating the block size.
+        </div>
+      </Collapse>
+    </div>
+  );
+}
+```

package/dist/skill/references/components/motion-fade.md

@@ -0,0 +1,64 @@
+# Fade
+
+Animates opacity between 0 and 1 based on the `in` prop.
+
+- Package: `@nexub/react` · Category: Motion · Status: stable
+- Import: `import { MotionFade } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/motion-fade
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` (required) | `boolean` |  | When true, fades content in. When false, fades it out. |
+| `duration` | `'instant' \| 'fast' \| 'normal' \| 'slow' \| 'slower'` | `'normal'` | Controls the animation speed using the design token scale. |
+| `easing` | `'linear' \| 'in' \| 'out' \| 'in-out' \| 'out-expo' \| 'spring'` | `'out'` | Easing curve applied to the animation. |
+| `unmountOnExit` | `boolean` | `false` | Removes the element from the DOM after the exit animation completes. |
+| `as` | `React.ElementType` | `'div'` | The HTML element or component to render as the wrapper. |
+| `children` (required) | `React.ReactNode` |  | Content to animate. |
+
+## Example: Default
+
+```tsx
+<Fade in={true}>
+  <Card>Faded in content</Card>
+</Fade>
+```
+
+## Example: Toggle
+
+```tsx
+function FadeToggle() {
+  const [visible, setVisible] = React.useState(true);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Button variant="outline" onClick={() => setVisible((v) => !v)}>
+        {visible ? 'Fade out' : 'Fade in'}
+      </Button>
+      <Fade in={visible} duration="normal" easing="out" unmountOnExit>
+        <Card style={{ padding: '16px' }}>
+          This content fades in and out. Toggle the button to animate it.
+        </Card>
+      </Fade>
+    </div>
+  );
+}
+```
+
+## Example: Slow with spring easing
+
+```tsx
+function SlowFade() {
+  const [visible, setVisible] = React.useState(true);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Button variant="outline" onClick={() => setVisible((v) => !v)}>Toggle</Button>
+      <Fade in={visible} duration="slow" easing="spring">
+        <div style={{ padding: '16px', background: 'var(--color-bg-subtle)', borderRadius: 'var(--radius-md)' }}>
+          Slow spring fade animation.
+        </div>
+      </Fade>
+    </div>
+  );
+}
+```

package/dist/skill/references/components/motion-scale.md

@@ -0,0 +1,54 @@
+# Scale
+
+Scales content in/out from its center.
+
+- Package: `@nexub/react` · Category: Motion · Status: stable
+- Import: `import { MotionScale } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/motion-scale
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` (required) | `boolean` |  | When true, scales content in from 0 to 1. When false, scales it back down to 0. |
+| `duration` | `'instant' \| 'fast' \| 'normal' \| 'slow' \| 'slower'` | `'normal'` | Controls the animation speed using the design token scale. |
+| `easing` | `'linear' \| 'in' \| 'out' \| 'in-out' \| 'out-expo' \| 'spring'` | `'out'` | Easing curve applied to the animation. |
+| `unmountOnExit` | `boolean` | `false` | Removes the element from the DOM after the exit animation completes. |
+| `as` | `React.ElementType` | `'div'` | The HTML element or component to render as the wrapper. |
+| `children` (required) | `React.ReactNode` |  | Content to animate. |
+
+## Example: Default
+
+```tsx
+<Scale in={true}>
+  <Card>Scaled content</Card>
+</Scale>
+```
+
+## Example: Toggle
+
+```tsx
+function ScaleToggle() {
+  const [visible, setVisible] = React.useState(true);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Button variant="outline" onClick={() => setVisible((v) => !v)}>
+        {visible ? 'Scale out' : 'Scale in'}
+      </Button>
+      <Scale in={visible} duration="fast" easing="spring" unmountOnExit>
+        <div
+          style={{
+            padding: '24px',
+            background: 'var(--color-bg-subtle)',
+            borderRadius: 'var(--radius-md)',
+            textAlign: 'center',
+            color: 'var(--color-text-secondary)',
+          }}
+        >
+          Pop!
+        </div>
+      </Scale>
+    </div>
+  );
+}
+```

package/dist/skill/references/components/motion-slide.md

@@ -0,0 +1,60 @@
+# Slide
+
+Slides content in from a direction based on the `in` prop.
+
+- Package: `@nexub/react` · Category: Motion · Status: stable
+- Import: `import { MotionSlide } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/motion-slide
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` (required) | `boolean` |  | When true, slides content in. When false, slides it out. |
+| `direction` | `'up' \| 'down' \| 'left' \| 'right'` | `'up'` | The direction from which the content slides in. |
+| `duration` | `'instant' \| 'fast' \| 'normal' \| 'slow' \| 'slower'` | `'normal'` | Controls the animation speed using the design token scale. |
+| `easing` | `'linear' \| 'in' \| 'out' \| 'in-out' \| 'out-expo' \| 'spring'` | `'out'` | Easing curve applied to the animation. |
+| `unmountOnExit` | `boolean` | `false` | Removes the element from the DOM after the exit animation completes. |
+| `as` | `React.ElementType` | `'div'` | The HTML element or component to render as the wrapper. |
+| `children` (required) | `React.ReactNode` |  | Content to animate. |
+
+## Example: Default
+
+```tsx
+<Slide in={true} direction="up">
+  <Card>Slid in from bottom</Card>
+</Slide>
+```
+
+## Example: Directions
+
+```tsx
+function SlideDirections() {
+  const [visible, setVisible] = React.useState(true);
+  const [direction, setDirection] = React.useState('up');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+        {['up', 'down', 'left', 'right'].map((dir) => (
+          <Button
+            key={dir}
+            variant={direction === dir ? 'primary' : 'outline'}
+            size="sm"
+            onClick={() => { setDirection(dir); setVisible(true); }}
+          >
+            {dir}
+          </Button>
+        ))}
+        <Button variant="ghost" size="sm" onClick={() => setVisible((v) => !v)}>
+          Toggle
+        </Button>
+      </div>
+      <Slide in={visible} direction={direction} unmountOnExit>
+        <div style={{ padding: '16px', background: 'var(--color-bg-subtle)', borderRadius: 'var(--radius-md)' }}>
+          Sliding in from {direction}.
+        </div>
+      </Slide>
+    </div>
+  );
+}
+```

package/dist/skill/references/components/navigation-rail.md

@@ -0,0 +1,29 @@
+# Navigation Rail
+
+Navigation for medium-width windows: icons over labels, with an active pill behind the icon.
+
+- Package: `@nexub/react` · Category: Navigation · Status: beta
+- Import: `import { NavigationRail } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/navigation-rail
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Root header` | `ReactNode` |  | Slot above the items, e.g. a primary action. |
+| `Root aria-label` | `string` | `'Main'` | Name of the nav landmark. |
+| `Item icon / label` (required) | `ReactNode` |  | Icon in the indicator pill; label below. |
+| `Item active` | `boolean` |  | Marks the current page (aria-current="page"). |
+| `Item asChild` | `boolean` |  | Use your router link as the item; pass it as the only child. |
+
+## Example: Default
+
+```tsx
+<NavigationRail.Root aria-label="Workspace">
+  <NavigationRail.Item href="/" icon={<Home />} label="Home" active />
+  <NavigationRail.Item href="/files" icon={<Folder />} label="Files" />
+  <NavigationRail.Item href="/settings" icon={<Settings />} label="Settings" />
+</NavigationRail.Root>
+```
+
+Related: [sidebar](sidebar.md), [top-nav](top-nav.md)

package/dist/skill/references/components/notification-item.md

@@ -0,0 +1,29 @@
+# NotificationItem
+
+Single notification row for notification panels or dropdowns.
+
+- Package: `@nexub/patterns` · Category: Feedback · Status: stable
+- Import: `import { NotificationItem } from '@nexub/patterns';`
+- Docs: https://nexub-ds-docs.pages.dev/patterns/notification-item
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  | Notification title. |
+| `description` | `string` |  | Supporting text. |
+| `timestamp` | `string` |  | Relative time string. |
+| `unread` | `boolean` | `false` | Applies unread indicator styling. |
+| `avatar` | `React.ReactNode` |  | Avatar for the notification actor. |
+| `onClick` | `() => void` |  | Click handler for the item. |
+
+## Example: Default
+
+```tsx
+<NotificationItem
+  title="New comment on your post"
+  description="Alex left a comment on 'Design System v2'"
+  timestamp="5 min ago"
+  unread
+/>
+```

package/dist/skill/references/components/number-input.md

@@ -0,0 +1,30 @@
+# Number Input
+
+A numeric input with increment and decrement controls, supporting min/max clamping and step.
+
+- Package: `@nexub/react` · Category: Form & Input · Status: stable
+- Import: `import { NumberInput } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/number-input
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` |  | Controlled value of the input. |
+| `min` | `number` |  | Minimum allowed value. |
+| `max` | `number` |  | Maximum allowed value. |
+| `step` | `number` | `1` | Amount to increment or decrement on each step. |
+| `disabled` | `boolean` |  | Disables the input and its controls. |
+| `size` | `'sm' \| 'md' \| 'lg'` |  | Controls font size and padding. |
+
+## Example: Default
+
+```tsx
+<NumberInput defaultValue={0} />
+```
+
+## Example: With range
+
+```tsx
+<NumberInput defaultValue={5} min={0} max={10} />
+```

package/dist/skill/references/components/number-ticker.md

@@ -0,0 +1,44 @@
+# Number Ticker
+
+A number whose digits roll to new values on the spatial spring. The first render never animates.
+
+- Package: `@nexub/react` · Category: Data Display · Status: beta
+- Import: `import { NumberTicker } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/number-ticker
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `number \| string \| NumberTickerPart[]` |  | A number (formatted with `format` and `locale`), an already-formatted string, or styled parts. |
+| `format` | `Intl.NumberFormatOptions` |  | Formatting for a number `value`. |
+| `locale` | `string` |  | BCP 47 locale. Defaults to the user's. |
+| `aria-live` | `'off' \| 'polite'` | `'off'` | Announce changes to screen readers. Use `polite` only for values the user is waiting on. |
+
+## Example: Formatted number
+
+Each digit is a 0–9 strip; separators and symbols stay still.
+
+```tsx
+const [n, setN] = React.useState(12480);
+
+<NumberTicker value={n} format={{ maximumFractionDigits: 0 }} className="text-title-lg" />
+<Button size="sm" variant="outlined" onClick={() => setN(Math.round(Math.random() * 100000))}>
+  Change
+</Button>
+```
+
+## Example: Amount
+
+`Amount animate` uses the ticker and keeps the quieter symbol and minor units.
+
+```tsx
+<Amount value={balance} currency="USD" size="display" animate />
+```
+
+## Accessibility
+
+- The full value is read as one string; the rolling digits are hidden from assistive tech.
+- Under reduced motion digits change instantly.
+
+Related: [amount](amount.md), [stat-card](stat-card.md)

package/dist/skill/references/components/pagination.md

@@ -0,0 +1,52 @@
+# Pagination
+
+Page navigation control with prev/next and page number buttons.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { Pagination } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/pagination
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `page` (required) | `number` |  | The currently active page (1-indexed). |
+| `totalItems` (required) | `number` |  | Total number of items across all pages. |
+| `pageSize` | `number` | `10` | Number of items per page. Used to calculate total page count. |
+| `siblingCount` | `number` | `1` | Number of page buttons to show on each side of the current page. |
+| `onPageChange` (required) | `(page: number) => void` |  | Callback invoked with the new page number when the user navigates. |
+| `showFirstLast` | `boolean` | `true` | Whether to show First and Last page navigation buttons. |
+| `disabled` | `boolean` | `false` | Disables all pagination controls. |
+
+## Example: Default
+
+```tsx
+function DefaultPagination() {
+  const [page, setPage] = React.useState(3);
+  return (
+    <Pagination
+      page={page}
+      totalItems={100}
+      pageSize={10}
+      onPageChange={setPage}
+    />
+  );
+}
+```
+
+## Example: Large dataset
+
+```tsx
+function LargeDatasetPagination() {
+  const [page, setPage] = React.useState(5);
+  return (
+    <Pagination
+      page={page}
+      totalItems={500}
+      pageSize={20}
+      siblingCount={2}
+      onPageChange={setPage}
+    />
+  );
+}
+```