@cascivo/react 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,20 @@
 <!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
 
-# @cascivo/react
+<div align="center">
+  <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="72" height="72" alt="cascivo logo"></a>
+  <h1>@cascivo/react</h1>
+  <p><strong>Prebuilt cascivo design system components — use without copying source</strong></p>
 
-> Prebuilt cascivo design system components — use without copying source
+[![npm](https://img.shields.io/npm/v/%40cascivo%2Freact?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/react)
+[![downloads](https://img.shields.io/npm/dm/%40cascivo%2Freact?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/react)
+[![license](https://img.shields.io/npm/l/%40cascivo%2Freact?style=flat-square&color=0079bf)](https://github.com/cascivo/cascivo/blob/main/LICENSE)
+![types](https://img.shields.io/badge/types-included-0079bf?style=flat-square&logo=typescript&logoColor=white)
 
-[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo)
+[npm](https://www.npmjs.com/package/@cascivo/react) · [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo)
+
+</div>
+
+---
 
 Every cascivo component, prebuilt as a normal installable library — for users
 who just want to **use** the design system without owning the source. If you
@@ -12,6 +22,36 @@ want to customize component internals, use the copy-paste flow instead
 (`npx cascivo add <component>`); both consume the same tokens and themes, and
 can coexist in one project.
 
+## Install
+
+```sh
+pnpm add @cascivo/react @cascivo/themes @preact/signals-react
+```
+
+**Peer dependencies** (install them in your app): `react >=18`, `react-dom >=18`,
+and `@preact/signals-react` — cascivo components are signal-driven, so the
+signals runtime is required. `@cascivo/themes` is optional but recommended; it
+supplies the tokens and themes the components read.
+
+Charts live in a separate package — add [`@cascivo/charts`](https://github.com/cascivo/cascivo/tree/main/packages/charts)
+for `LineChart`, `AreaChart`, `BarChart`, `Sparkline`, and more.
+
+### Framework setup (Next.js App Router)
+
+In a Server Component file (e.g. `app/layout.tsx`), import the CSS once:
+
+```tsx
+import '@cascivo/react/styles.css'
+import '@cascivo/themes/all'
+```
+
+Components ship with `'use client'` preserved in the bundle, so they work inside
+RSC without any extra wrapper.
+
+> **Note on the styles path:** the import specifier is `@cascivo/react/styles.css`,
+> which the package's export map points at the dist file `cascivo.css`. Always
+> import the `styles.css` specifier — never reference `cascivo.css` directly.
+
 ## Use
 
 ```tsx
@@ -71,17 +111,43 @@ declaration. Token names and aliases are documented in `TOKENS.md`.
 All components are client components (`'use client'` is preserved in the
 bundle), so the package works in Next.js App Router projects out of the box.
 
+## Guides
+
+- [Theming & branding](https://github.com/cascivo/cascivo/blob/main/docs/THEMING.md) — match a brand by overriding tokens (layer cascade, the `data-theme` specificity footgun, per-role radius/control-height tokens, a starter theme).
+- [Using cascivo with Preact](https://github.com/cascivo/cascivo/blob/main/docs/USING-WITH-PREACT.md) — `preact/compat` alias, tsconfig paths, peer deps, signals package. It works — this documents how.
+- [Compatibility & support matrix](https://github.com/cascivo/cascivo/blob/main/docs/COMPATIBILITY.md) — frameworks, browsers, the build-tooling baseline, and which package versions go together.
+- [Token reference](https://github.com/cascivo/cascivo/blob/main/docs/TOKENS.md) — every CSS custom property, canonical names, and aliases.
+
 ## Migrating from shadcn/ui?
 
-See [`MIGRATING-FROM-SHADCN.md`](https://github.com/urbanisierung/cascivo/blob/main/docs/MIGRATING-FROM-SHADCN.md)
+See [`MIGRATING-FROM-SHADCN.md`](https://github.com/cascivo/cascivo/blob/main/docs/MIGRATING-FROM-SHADCN.md)
 for the variant/prop mapping (e.g. Button `default/outline` → `primary/secondary`,
 there is no `outline`) and the CSS-setup delta vs Tailwind.
 
+## Gotchas — naming collisions
+
+A handful of exported component names shadow common DOM, browser, or Next.js
+globals. When you import them, alias the import (or import the cascivo name
+explicitly) to avoid clashing with the platform identifier:
+
+| cascivo export   | Collides with                             | Suggested alias                                            |
+| ---------------- | ----------------------------------------- | ---------------------------------------------------------- |
+| `Image`          | `next/image`, the DOM `Image` constructor | `import { Image as CascivoImage } from '@cascivo/react'`   |
+| `Link`           | `next/link`                               | `import { Link as CascivoLink } from '@cascivo/react'`     |
+| `Header`         | the `<header>` element / app headers      | `import { Header as CascivoHeader } from '@cascivo/react'` |
+| `Search`         | various router/search helpers             | `import { Search as CascivoSearch } from '@cascivo/react'` |
+| `User`, `Status` | domain models in many apps                | alias as needed                                            |
+| `Tag`            | exported as the cascivo `Tag` chip        | already namespaced — import directly                       |
+
+Editor auto-import will sometimes pick the wrong `Image`/`Link`; if styles or
+routing break after adding one of these, check that the import resolves to
+`@cascivo/react`.
+
 <!-- COMPONENT_INDEX:START -->
 
 ## Component index
 
-158 components, exported from `@cascivo/react`. Full props, examples, and live demos at [docs.cascivo.com](https://docs.cascivo.com).
+165 components, exported from `@cascivo/react`. Full props, examples, and live demos at [docs.cascivo.com](https://docs.cascivo.com).
 
 ### Inputs
 
@@ -128,6 +194,7 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 
 - **Alert** — Highlights a short, important message inline
 - **Avatar** — Displays a user image with initials fallback
+- **AvatarGroup** — Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip
 - **Badge** — Small status label or category indicator
 - **Blockquote** — Quoted passage with optional attribution footer
 - **Card** — Container for grouping related content
@@ -136,6 +203,7 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 - **Code** — Inline code span for identifiers, commands, and short snippets
 - **CodeSnippet** — Displays code (inline, single-line, or multi-line) with an optional copy button, lightweight built-in syntax highlighting for bash/css/js/ts, and an optional terminal-window look
 - **Collapsible** — A single disclosure region toggled open and closed by its trigger
+- **Comparison** — Reveals the difference between two layers with a draggable divider
 - **ConsoleApp** — Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content.
 - **ContainedList** — Labelled list of rows inside a bordered container
 - **DashboardCharts** — Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.
@@ -144,6 +212,7 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 - **EmptyDashboard** — Dashboard page showing an empty state with a call-to-action button.
 - **EmptyState** — Placeholder for views that have no data to display
 - **Heading** — Section heading with semantic level decoupled from visual size
+- **Image** — Image with load state, blur-up placeholder, graceful fallback, and optional zoom
 - **Item** — Generic content row primitive with media, content, and action regions
 - **Kbd** — Displays a keyboard key or shortcut
 - **List** — Styled unordered or ordered list with ListItem
@@ -151,6 +220,8 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 - **NotificationCenter** — A list of notification alerts with a mark-all-read action.
 - **PageWithBreadcrumb** — A centered content page with a breadcrumb navigation and page header.
 - **Prose** — Wrapper that styles raw descendant HTML — headings, lists, code, quotes, tables
+- **QrCode** — Encodes a URL or short text into a scannable SVG QR code
+- **RelativeTime** — Displays a date as a localized phrase relative to now, auto-updating
 - **Separator** — Visual or semantic divider between content
 - **SettingsFormPage** — Settings page with profile form inside a two-column settings layout.
 - **SidebarApp** — Full app shell with collapsible side navigation and top header.
@@ -163,6 +234,7 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 - **Text** — Body text with size, weight, and muted variants
 - **Timeline** — Ordered sequence of events with status markers and a connector line
 - **TreeView** — Hierarchical, expandable tree of nodes with keyboard navigation and selection
+- **User** — Identity composite: an avatar with a name, description, and optional action slot
 - **UsersTablePage** — Full users management page with table, search, and invite action.
 - **VisuallyHidden** — Hides content visually while keeping it available to screen readers
 
@@ -202,6 +274,7 @@ there is no `outline`) and the CSS-setup delta vs Tailwind.
 - **Steps** — Visual progress indicator for multi-step flows with horizontal and vertical orientations
 - **Switcher** — App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers
 - **Tabs** — Switch between related panels of content
+- **Toc** — Table of contents with scroll-spy highlighting of the active section
 
 ### Layout
 
@@ -272,4 +345,6 @@ pnpm add @cascivo/react
 
 ---
 
-[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/urbanisierung/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/urbanisierung/cascivo/blob/main/registry.json) · MIT
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/cascivo/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/cascivo/cascivo/blob/main/registry.json) · MIT
+
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="28" height="28" alt="cascivo"></a></div>