@cascivo/react 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cascivo/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Prebuilt cascivo design system components — use without copying source",
   "keywords": [
@@ -13,13 +13,13 @@
     "signals",
     "ui"
   ],
-  "homepage": "https://github.com/urbanisierung/cascivo/tree/main/packages/react#readme",
-  "bugs": "https://github.com/urbanisierung/cascivo/issues",
+  "homepage": "https://github.com/cascivo/cascivo/tree/main/packages/react#readme",
+  "bugs": "https://github.com/cascivo/cascivo/issues",
   "license": "MIT",
   "author": "urbanisierung",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/urbanisierung/cascivo.git",
+    "url": "git+https://github.com/cascivo/cascivo.git",
     "directory": "packages/react"
   },
   "files": [
@@ -36,15 +36,16 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./styles.css": "./dist/cascivo.css"
+    "./styles.css": "./dist/cascivo.css",
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@cascivo/core": "^0.1.0",
-    "@cascivo/i18n": "^0.1.0"
+    "@cascivo/core": "^0.1.2",
+    "@cascivo/i18n": "^0.1.2"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/readme.body.md

@@ -4,6 +4,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
@@ -63,17 +93,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
 
@@ -120,6 +176,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
@@ -128,6 +185,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.
@@ -136,6 +194,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
@@ -143,6 +202,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.
@@ -155,6 +216,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
 
@@ -194,6 +256,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