@sarunyu/system-one 4.9.30 → 4.9.33

package/llms.txt

@@ -1,6 +1,6 @@
 # @sarunyu/system-one — AI usage guide
 
-React component library. Tailwind CSS v4 + CSS custom properties. 24 components.
+React component library. Tailwind CSS v4 + CSS custom properties. 30 components.
 Built for AI-powered UI generation (v0, Lovable, Figma Make, Cursor).
 
 **This file is the contract.** Read it top-to-bottom before generating any screen
@@ -12,7 +12,7 @@ that uses this library. The rules are non-negotiable.
 
 1. **Use library components for every element it provides.** Never recreate
    Button, Input, Tag, Dropdown, Card, Tab, Checkbox, Toggle, Radio, DateInput, TimeInput,
-   Table, SearchInput, TextArea, Chip, Modal, BottomSheet, Alert, Toast, Notification, Badge, Avatar, AvatarStack as raw HTML.
+   Table, SearchInput, TextArea, Chip, Modal, BottomSheet, Alert, Toast, Notification, Badge, Avatar, AvatarStack, Breadcrumb, Tooltip, Popover as raw HTML.
 2. **Never override a component's built-in styles.** Every library component manages its own colors, shadows, padding, radius, and typography internally. Only use `className` on library components for **layout** (`w-*`, `max-w-*`, `flex`, `grid`, `gap-*`, `m-*`, `col-span-*`). Never pass `bg-*`, `shadow-*`, `text-*`, `p-*`, `rounded-*`, or `border-*` in `className` on a library component.
 3. **Use design-token classes for color and typography.** Never `text-blue-600`,
    `bg-gray-100`, `text-[#3b82f6]`. The token table below is exhaustive — if a
@@ -142,6 +142,9 @@ import {
   Dropdown, DropdownMultiple, OptionList,
   Checkbox, Toggle, Radio,
   DateInput, TimeInput,
+  // Navigation
+  Breadcrumb,
+  Pagination, PaginationBanner, PaginationCarousel,
   // Display
   Avatar, AvatarStack,
   Tag, StatusTag, Chip,
@@ -154,7 +157,7 @@ import {
   Notification,
   Badge,
   // Overlay
-  Modal, BottomSheet,
+  Modal, BottomSheet, Tooltip, Popover,
   // Utility
   cn, useIsMobile,
 } from "@sarunyu/system-one";
@@ -868,6 +871,57 @@ Props: `items` (array of `{ type?, src?, alt?, initials? }`), `size?` (`"small"`
 
 ---
 
+### Breadcrumb
+
+Horizontal navigation trail rendered as a `<nav>` with `/` separators. The last item is always the current page (active state). Items with `href` render as anchor tags; items without render as plain text.
+
+```tsx
+<Breadcrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Products", href: "/products" },
+    { label: "Detail" },
+  ]}
+/>
+```
+
+Props: `items` (`BreadcrumbItem[]` — each has `label: string`, `href?: string`), `className?`.
+
+The last item in `items` is always treated as the current page — never pass `href` on it.
+
+---
+
+### Pagination
+
+Three variants for different scroll/paging patterns:
+
+| Component | Use for |
+|---|---|
+| `<Pagination>` | Numbered pages — datasets, search results, news lists |
+| `<PaginationBanner>` | Banner/hero slide dot indicator (active = wider pill) |
+| `<PaginationCarousel>` | Free-scroll carousel progress bar |
+
+```tsx
+// Numbered pagination
+<Pagination totalPages={10} currentPage={currentPage} onPageChange={setCurrentPage} />
+
+// Banner slide dots
+<PaginationBanner count={5} activeIndex={bannerIndex} onIndexChange={setBannerIndex} />
+
+// Carousel scrollbar — progress 0 (start) to 1 (end)
+<PaginationCarousel progress={scrollProgress} />
+<PaginationCarousel progress={0.5} trackWidth={60} />
+```
+
+**Numbered pagination** — when `totalPages > 5`, pages 4…(n-1) collapse behind a `…` button that opens a scrollable dropdown to jump to any hidden page. Do not use `<Pagination>` inside a horizontal card carousel — use `<PaginationCarousel>` instead.
+
+Props:
+- `Pagination` — `totalPages`, `currentPage`, `onPageChange?(page: number)`, `className?`
+- `PaginationBanner` — `count`, `activeIndex`, `onIndexChange?(index: number)`, `className?`
+- `PaginationCarousel` — `progress` (0–1, clamped), `trackWidth?` (default 40), `className?`
+
+---
+
 ### Notification
 
 Bell-icon trigger + popover panel showing grouped notification rows. Handles badge count, auto-clear on open, and keyboard navigation. Uses `<Badge variant="notification">` internally.
@@ -1069,6 +1123,80 @@ Props: `open`, `onOpenChange`, `trigger`, `headerType`, `showHeader`,
 
 ---
 
+### Tooltip
+
+Dark-bubble contextual hint shown on hover over any trigger element.
+`children` is the trigger (must be a single focusable element); `content` is the bubble text.
+
+```tsx
+<Tooltip content="Delete this item">
+  <Button variant="outline" size="icon-md" aria-label="Delete"><Trash size={16} /></Button>
+</Tooltip>
+
+<Tooltip content="This field is required" side="right" align="start">
+  <Input placeholder="Email" value={email} onChange={setEmail} />
+</Tooltip>
+
+<Tooltip content="Appears immediately" side="top" delayDuration={0}>
+  <Button variant="plain" size="md">Instant</Button>
+</Tooltip>
+```
+
+Props:
+- `children` — trigger element (`ReactNode`, required). Must be a single element that accepts `onPointerEnter` / `onFocus`.
+- `content` — bubble content (`ReactNode`, required).
+- `side` — `"top"` | `"bottom"` | `"left"` | `"right"`. Default `"top"`.
+- `align` — `"start"` | `"center"` | `"end"`. Default `"center"`.
+- `delayDuration` — ms before tooltip shows on hover. Default `300`.
+- `sideOffset` — gap in px between trigger and bubble. Default `6`.
+- `className?` — extra classes on the bubble (layout only — never override colors or padding).
+
+---
+
+### Popover
+
+Floating panel that opens on **click** over any trigger element. Pass the trigger as `children` and the panel body as `content`. Scrollbar is hidden inside the bubble by default.
+
+```tsx
+<Popover content={<div>Panel content here</div>}>
+  <Button variant="outline" size="md">Open</Button>
+</Popover>
+
+// Side and alignment
+<Popover side="top" align="center" content={<p className="text-sm text-foreground">Centered above</p>}>
+  <Button variant="outline" size="md">Top center</Button>
+</Popover>
+
+// Controlled state
+<Popover open={open} onOpenChange={setOpen} content={<p>Controlled</p>}>
+  <Button variant="outline" size="md">Open</Button>
+</Popover>
+
+// Rich content
+<Popover
+  content={
+    <div className="flex flex-col gap-2 min-w-48">
+      <p className="text-sm font-medium text-foreground">Account</p>
+      <OptionList options={menuItems} selectedValue={null} onSelect={handleSelect} />
+    </div>
+  }
+>
+  <Button variant="outline" size="md" leftIcon={<User size={16} />}>Account</Button>
+</Popover>
+```
+
+Props:
+- `children` — trigger element (`ReactNode`, required). Must be a single element.
+- `content` — panel body (`ReactNode`, required).
+- `side` — `"top"` | `"bottom"` | `"left"` | `"right"`. Default `"bottom"`.
+- `align` — `"start"` | `"center"` | `"end"`. Default `"start"`.
+- `sideOffset` — gap in px between trigger and panel. Default `4`.
+- `open` — controlled open state. Omit for uncontrolled usage.
+- `onOpenChange` — `(open: boolean) => void`.
+- `className?` — extra classes on the panel bubble (layout only — never override `bg-*` or `p-*`).
+
+---
+
 ### Modal vs BottomSheet — responsive rule
 
 **On mobile (< 768px), content-heavy / action-heavy modals MUST render as
@@ -1521,4 +1649,4 @@ Rules for custom components:
 - Border → `border-border` (or `border-divider` for light separators).
 - Typography → use `<h1>`…`<h4>` and body text inherits from `--foreground`.
 
-If the thing you're building is conceptually a button/input/tag/chip/tab/card/table — **do not build a custom one. Use the library's component.** The only reason to build custom is when the library truly doesn't cover the concept (e.g. a bespoke hero section, a custom chart, a breadcrumb).
+If the thing you're building is conceptually a button/input/tag/chip/tab/card/table/breadcrumb — **do not build a custom one. Use the library's component.** The only reason to build custom is when the library truly doesn't cover the concept (e.g. a bespoke hero section, a custom chart).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarunyu/system-one",
-  "version": "4.9.30",
+  "version": "4.9.33",
   "type": "module",
   "description": "A production-ready React design system built for AI-powered web generation tools (Figma Make, Lovable, V0). Tailwind CSS v4 + CSS custom properties for full theming support.",
   "keywords": [