@zentauri-ui/zentauri-components 1.4.5 → 1.4.7

package/README.md

@@ -6,24 +6,25 @@ A React UI kit for building product interfaces with Tailwind CSS. Components are
 
 The library targets **React 18+** apps that use **Tailwind CSS v4** (or an equivalent setup where Tailwind can scan this package via `@source`). Styling uses utility classes; **class-variance-authority** powers variant APIs (size, appearance, and similar props), with **clsx** and **tailwind-merge** for predictable `className` composition. **Framer Motion** backs motion where a feature ships animated variants, and **react-icons** is used for iconography where applicable.
 
-Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@zentauri-ui/zentauri-components/ui/<area>` for static UI, `@zentauri-ui/zentauri-components/ui/<area>/animated` where a motion bundle exists, and `@zentauri-ui/zentauri-components/hooks/<entry>` for React hooks (and shared helpers under `hooks/utils`). Base UI entries do **not** re-export animated components; motion lives on its own entry so optional `framer-motion` usage stays tree-shakeable and chunk-friendly. Each entry resolves to its own ESM (`.mjs`), CJS (`.js`), and types (`.d.ts`) so bundlers pull only what you import. Most apps rely on Tailwind scanning the package sources (see installation); a separate CSS import is not required for that setup.
+Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@zentauri-ui/zentauri-components/ui/<area>` for static UI, `@zentauri-ui/zentauri-components/ui/<area>/animated` where a motion bundle exists, `@zentauri-ui/zentauri-components/charts/<type>` for Recharts-powered chart primitives, and `@zentauri-ui/zentauri-components/hooks/<entry>` for React hooks (and shared helpers under `hooks/utils`). Base UI entries do **not** re-export animated components; motion lives on its own entry so optional `framer-motion` usage stays tree-shakeable and chunk-friendly. Each entry resolves to its own ESM (`.mjs`), CJS (`.js`), and types (`.d.ts`) so bundlers pull only what you import. Most apps rely on Tailwind scanning the package sources (see installation); a separate CSS import is not required for that setup.
 
 ## Package exports
 
-| Subpath                                         | Description                                                                                                                                 |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@zentauri-ui/zentauri-components/ui/<name>`   | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.           |
-| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).     |
-| `@zentauri-ui/zentauri-components/hooks/<entry>` | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**). |
+| Subpath                                               | Description                                                                                                                                    |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zentauri-ui/zentauri-components/ui/<name>`          | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.             |
+| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).              |
+| `@zentauri-ui/zentauri-components/charts/<type>`      | Responsive Recharts chart entry for `area`, `bar`, `bubble`, or `line`, with shared variants, palettes, and exported chart prop types.         |
+| `@zentauri-ui/zentauri-components/hooks/<entry>`      | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**). |
 
-The UI `<name>` segment matches the folder under `src/ui/` (for example `accordion`, `select`, `empty-state`, `buttons` for `Button`, `inputs` for `Input`). The hooks `<entry>` is the file stem (for example `useMediaQuery`, `usePagination`) or `utils`.
+The UI `<name>` segment matches the folder under `src/ui/` (for example `accordion`, `select`, `empty-state`, `buttons` for `Button`, `inputs` for `Input`, `typography` for `Heading` / `Text` and related primitives). The hooks `<entry>` is the file stem (for example `useMediaQuery`, `usePagination`) or `utils`.
 
 Only a subset of UI areas publish a `/animated` entry (see **Components**). Some motion entries also re-export non-motion pieces from the same feature so you can import one motion subpath for a whole flow; others pair a base `ui/<name>` import with a small set of `*Animated` exports from `ui/<name>/animated`—use the `animated/index.ts` for that area as the source of truth.
 
 ## Animated components (`ui/<name>/animated`)
 
 - **Why a separate subpath:** animated modules import **framer-motion**. Keeping them on `…/ui/<name>/animated` avoids pulling motion into pages that only use the static `…/ui/<name>` entry and keeps server/client boundaries predictable in app routers.
-- **When to install `framer-motion`:** add it when your app imports any `@zentauri-ui/zentauri-components/ui/*/animated` path (see **Optional: animations and icons** under installation).
+- **When to install `framer-motion`:** add it when your app imports any `@zentauri-ui/zentauri-components/ui/*/animated` path (see **Optional: animations, icons, and charts** under installation).
 
 Published motion entries (same `<name>` as the base UI folder):
 
@@ -38,70 +39,174 @@ Published motion entries (same `<name>` as the base UI folder):
 
 ## Components
 
-Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` when the **Base** column lists a path. When the **Animated** column lists a path, motion components and preset helpers come from `@zentauri-ui/zentauri-components/ui/<subpath>/animated` (they are not exported from the base entry). **Spinner** has no static bundle—use only the animated subpath.
-
-| Area           | Base subpath `…/ui/…` | Animated subpath `…/ui/…/animated` |
-| -------------- | --------------------- | ------------------------------------ |
-| Accordion      | `accordion`           | `accordion/animated`                 |
-| Alert          | `alert`               | `alert/animated`                     |
-| Avatar         | `avatar`              | `avatar/animated`                    |
-| Badge          | `badge`               | `badge/animated`                     |
-| Breadcrumb     | `breadcrumb`          | —                                    |
-| Button         | `buttons`             | `buttons/animated`                   |
-| Card           | `card`                | `card/animated`                      |
-| Divider        | `divider`             | `divider/animated`                   |
-| Drawer         | `drawer`              | `drawer/animated`                    |
-| Dropdown       | `dropdown`            | —                                    |
-| Empty state    | `empty-state`         | `empty-state/animated`               |
-| File upload    | `file-upload`         | —                                    |
-| Input          | `inputs`              | `inputs/animated`                    |
-| Modal          | `modal`               | `modal/animated`                     |
-| Pagination     | `pagination`          | —                                    |
-| Progress       | `progress`            | `progress/animated`                  |
-| Search         | `search`              | -                                    |
-| Select         | `select`              | —                                    |
-| Skeleton       | `skeleton`            | `skeleton/animated`                  |
-| Slider         | `slider`              | —                                    |
-| Spinner        | —                     | `spinner/animated`                   |
-| Stepper        | `stepper`             | —                                    |
-| Table          | `table`               | `table/animated`                     |
-| Tabs           | `tabs`                | `tabs/animated`                      |
-| Toast          | `toast`               | `toast/animated`                     |
-| Toggle         | `toggle`              | `toggle/animated`                    |
-| Tooltip        | `tooltip`             | `tooltip/animated`                   |
+Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` when the **Base** column lists a path. Charts use `@zentauri-ui/zentauri-components/charts/<type>`. When the **Animated** column lists a path, motion components and preset helpers come from `@zentauri-ui/zentauri-components/ui/<subpath>/animated` (they are not exported from the base entry). **Spinner** has no static bundle—use only the animated subpath.
+
+| Area        | Base subpath    | Animated subpath `…/ui/…/animated` |
+| ----------- | --------------- | ---------------------------------- |
+| Accordion   | `accordion`     | `accordion/animated`               |
+| Alert       | `alert`         | `alert/animated`                   |
+| Avatar      | `avatar`        | `avatar/animated`                  |
+| Badge       | `badge`         | `badge/animated`                   |
+| Breadcrumb  | `breadcrumb`    | —                                  |
+| Button      | `buttons`       | `buttons/animated`                 |
+| Card        | `card`          | `card/animated`                    |
+| Charts      | `charts/<type>` | —                                  |
+| Divider     | `divider`       | `divider/animated`                 |
+| Drawer      | `drawer`        | `drawer/animated`                  |
+| Dropdown    | `dropdown`      | —                                  |
+| Empty state | `empty-state`   | `empty-state/animated`             |
+| File upload | `file-upload`   | —                                  |
+| Input       | `inputs`        | `inputs/animated`                  |
+| Modal       | `modal`         | `modal/animated`                   |
+| Pagination  | `pagination`    | —                                  |
+| Progress    | `progress`      | `progress/animated`                |
+| Search      | `search`        | -                                  |
+| Select      | `select`        | —                                  |
+| Skeleton    | `skeleton`      | `skeleton/animated`                |
+| Slider      | `slider`        | —                                  |
+| Spinner     | —               | `spinner/animated`                 |
+| Stepper     | `stepper`       | —                                  |
+| Table       | `table`         | `table/animated`                   |
+| Tabs        | `tabs`          | `tabs/animated`                    |
+| Toast       | `toast`         | `toast/animated`                   |
+| Toggle      | `toggle`        | `toggle/animated`                  |
+| Tooltip     | `tooltip`       | `tooltip/animated`                 |
+| Typography  | `typography`    | —                                  |
+
+## Typography
+
+Import from `@zentauri-ui/zentauri-components/ui/typography`. This entry is **static only** (no `/animated` subpath).
+
+**Components:** `Heading`, `Text`, `List` (with `List.Item`, also exported as `ListItem`), `Blockquote`, `InlineCode`, `CodeBlock`.
+
+**Types:** `HeadingProps`, `TextProps`, `ListProps`, `ListItemProps`, `BlockquoteProps`, `InlineCodeProps`, `CodeBlockProps`, `HeadingLevel`, `TextElement`, `TypographyTone`, `UnorderedMarker`.
+
+**Tone (`tone` prop):** `default`, `muted`, `primary`, `secondary`, `accent`, `destructive`, `info`, `success`, `warning`, `error`, and gradient presets: `gradient-pink-violet`, `gradient-cyan-violet`, `gradient-cyan-blue`, `gradient-cyan-green`, `gradient-cyan-orange`, `gradient-cyan-red`, `gradient-cyan-purple`, `gradient-cyan-pink`. Tones align with kit accent colors (slate / cyan / violet baseline).
+
+**Heading:** `level` is required (`1`–`6`) and picks the semantic tag (`h1`–`h6`). Optional `displayLevel` overrides only the visual scale (still the same tag). Optional `bold`, `italic`, `underline`, `strikethrough`.
+
+**Text:** Optional `as` (`p`, `span`, `div`, `label`; default `p`). `size` is `sm`, `base`, or `lg` (default `base`). Optional `highlight` plus the same emphasis flags as headings where applicable.
+
+**List:** `ordered` renders an `<ol>` (decimal markers); omit or `false` for `<ul>`. Unordered lists accept `marker`: `disc`, `circle`, or `none`.
+
+**Blockquote:** Optional `attribution` renders a footer label (separate from the HTML `cite` attribute).
+
+**Code samples:** `InlineCode` styles inline `code`; `CodeBlock` renders a `pre` with an inner `code` (pass string or fragment children, not another `code` element) and optional `language` for `aria-label`.
+
+**CVA helpers (composition):** `headingLevelVariants`, `textSizeVariants`, `typographyToneVariants`, `unorderedListMarkerVariants`, `orderedListVariants`.
+
+```tsx
+import {
+  Blockquote,
+  CodeBlock,
+  Heading,
+  InlineCode,
+  List,
+  Text,
+} from "@zentauri-ui/zentauri-components/ui/typography";
+
+export function ArticleIntro() {
+  return (
+    <>
+      <Heading level={2} displayLevel={1} tone="gradient-cyan-violet">
+        Feature title
+      </Heading>
+      <Text as="p" size="sm" tone="muted">
+        Supporting copy with <InlineCode tone="accent">inline code</InlineCode>.
+      </Text>
+      <List marker="disc" tone="default">
+        <List.Item>First item</List.Item>
+        <List.Item>Second item</List.Item>
+      </List>
+      <List ordered tone="muted">
+        <List.Item>Step one</List.Item>
+        <List.Item>Step two</List.Item>
+      </List>
+      <Blockquote tone="secondary" attribution="Docs">
+        Quoted guidance for the reader.
+      </Blockquote>
+      <CodeBlock language="tsx" tone="muted">
+        {`export const app = () => null;`}
+      </CodeBlock>
+    </>
+  );
+}
+```
+
+## Charts
+
+Import the chart you need from `@zentauri-ui/zentauri-components/charts/<type>`, or vendor it with `zentauri-components add charts/<type>`. It is built on **Recharts**, so install `recharts` when you use these entries.
+
+**Components:** `AreaChart`, `BarChart`, `BubbleChart`, `LineChart`.
+
+**Types:** `AreaChartProps`, `BarChartProps`, `BubbleChartProps`, `LineChartProps`, plus shared `ChartSeries`, `ChartDatum`, `ChartColor`, `ChartMargin`, and `ChartSharedStatic`.
+
+**Chart entries:** `charts/area`, `charts/bar`, `charts/bubble`, `charts/line`.
+
+**Variants:** `appearance` (`default`, `muted`, `outline`, `glass`) and `density` (`compact`, `comfortable`, `spacious`). Color presets are exported via `chartPalette` and `chartColorValues`.
+
+```tsx
+import {
+  AreaChart,
+  type ChartSeries,
+} from "@zentauri-ui/zentauri-components/charts/area";
+
+const data = [
+  { month: "Jan", revenue: 4200, signups: 240 },
+  { month: "Feb", revenue: 5100, signups: 280 },
+  { month: "Mar", revenue: 6800, signups: 360 },
+];
+
+const series: ChartSeries[] = [
+  { dataKey: "revenue", name: "Revenue", color: "cyan" },
+  { dataKey: "signups", name: "Signups", color: "emerald" },
+];
+
+export function RevenueChart() {
+  return (
+    <AreaChart
+      xKey="month"
+      data={data}
+      series={series}
+      appearance="outline"
+      showLegend
+    />
+  );
+}
+```
 
 ## React hooks
 
 Hooks live in `src/hooks/`. Each hook is a separate published entry under `@zentauri-ui/zentauri-components/hooks/<name>` (same pattern as UI areas). Types are exported where the implementation defines them (for example `UseDisclosureResult`, `PaginationPageItem`). For class-name merging and pagination helpers used alongside hooks, import from `@zentauri-ui/zentauri-components/hooks/utils`.
 
-| Hook / module              | Subpath `…/hooks/…`           | Notes (selected exports) |
-| -------------------------- | ----------------------------- | -------------------------- |
-| `useBodyScrollLock`        | `useBodyScrollLock`           | Locks document scroll while open |
-| `useClickOutside`          | `useClickOutside`             | `ClickOutsideEventType`, `UseClickOutsideParams` |
-| `useClipboard`             | `useClipboard`                | `UseClipboardResult` |
-| `useControllableState`     | `useControllableState`        | `UseControllableStateParams` |
-| `useDebouncedValue`        | `useDebouncedValue`           | Debounced state from a value |
-| `useDisclosure`            | `useDisclosure`               | `UseDisclosureParams`, `UseDisclosureResult` |
-| `useDocumentTitle`         | `useDocumentTitle`            | `UseDocumentTitleParams` |
-| `useFocusManagement`       | `useFocusManagement`          | Focus trap / focus moves for overlays |
-| `useHover`                 | `useHover`                    | Pointer hover state |
-| `useInView`                | `useInView`                   | `UseInViewParams` |
-| `useIntersectionObserver`  | `useIntersectionObserver`     | `UseIntersectionObserverParams` |
-| `useIsomorphicLayoutEffect`| `useIsomorphicLayoutEffect`   | `useLayoutEffect` safe for SSR |
-| `useIsMounted`             | `useIsMounted`                | Ref / flag after mount |
-| `useLocalStorage`          | `useLocalStorage`             | `UseLocalStorageResult` |
-| `useMediaQuery`            | `useMediaQuery`               | Match CSS media queries |
-| `useNetworkStatus`         | `useNetworkStatus`            | Online / offline |
-| `usePageVisibility`        | `usePageVisibility`           | Document visibility API |
-| `usePagination`            | `usePagination`               | `buildPaginationItems`, `BuildPaginationItemsParams`, `PaginationPageItem` |
-| `usePrefersColorScheme`    | `usePrefersColorScheme`       | `ColorSchemePreference` |
-| `usePrefersReducedMotion`  | `usePrefersReducedMotion`     | `prefers-reduced-motion` |
-| `useResizeObserver`        | `useResizeObserver`           | `ElementSize` |
-| `useSessionStorage`        | `useSessionStorage`           | `UseSessionStorageResult` |
-| `useThrottledCallback`     | `useThrottledCallback`        | Throttled callback ref |
-| `useToggle`                | `useToggle`                   | Boolean toggle state |
-| `useWindowSize`            | `useWindowSize`               | `WindowSize` |
-| `cn`, `clampPage`, `range` | `utils`                       | Shared helpers from `src/lib/utils.ts` |
+| Hook / module               | Subpath `…/hooks/…`         | Notes (selected exports)                                                   |
+| --------------------------- | --------------------------- | -------------------------------------------------------------------------- |
+| `useBodyScrollLock`         | `useBodyScrollLock`         | Locks document scroll while open                                           |
+| `useClickOutside`           | `useClickOutside`           | `ClickOutsideEventType`, `UseClickOutsideParams`                           |
+| `useClipboard`              | `useClipboard`              | `UseClipboardResult`                                                       |
+| `useControllableState`      | `useControllableState`      | `UseControllableStateParams`                                               |
+| `useDebouncedValue`         | `useDebouncedValue`         | Debounced state from a value                                               |
+| `useDisclosure`             | `useDisclosure`             | `UseDisclosureParams`, `UseDisclosureResult`                               |
+| `useDocumentTitle`          | `useDocumentTitle`          | `UseDocumentTitleParams`                                                   |
+| `useFocusManagement`        | `useFocusManagement`        | Focus trap / focus moves for overlays                                      |
+| `useHover`                  | `useHover`                  | Pointer hover state                                                        |
+| `useInView`                 | `useInView`                 | `UseInViewParams`                                                          |
+| `useIntersectionObserver`   | `useIntersectionObserver`   | `UseIntersectionObserverParams`                                            |
+| `useIsomorphicLayoutEffect` | `useIsomorphicLayoutEffect` | `useLayoutEffect` safe for SSR                                             |
+| `useIsMounted`              | `useIsMounted`              | Ref / flag after mount                                                     |
+| `useLocalStorage`           | `useLocalStorage`           | `UseLocalStorageResult`                                                    |
+| `useMediaQuery`             | `useMediaQuery`             | Match CSS media queries                                                    |
+| `useNetworkStatus`          | `useNetworkStatus`          | Online / offline                                                           |
+| `usePageVisibility`         | `usePageVisibility`         | Document visibility API                                                    |
+| `usePagination`             | `usePagination`             | `buildPaginationItems`, `BuildPaginationItemsParams`, `PaginationPageItem` |
+| `usePrefersColorScheme`     | `usePrefersColorScheme`     | `ColorSchemePreference`                                                    |
+| `usePrefersReducedMotion`   | `usePrefersReducedMotion`   | `prefers-reduced-motion`                                                   |
+| `useResizeObserver`         | `useResizeObserver`         | `ElementSize`                                                              |
+| `useSessionStorage`         | `useSessionStorage`         | `UseSessionStorageResult`                                                  |
+| `useThrottledCallback`      | `useThrottledCallback`      | Throttled callback ref                                                     |
+| `useToggle`                 | `useToggle`                 | Boolean toggle state                                                       |
+| `useWindowSize`             | `useWindowSize`             | `WindowSize`                                                               |
+| `cn`, `clampPage`, `range`  | `utils`                     | Shared helpers from `src/lib/utils.ts`                                     |
 
 #### Hook import example
 
@@ -153,23 +258,23 @@ pnpm add react react-dom class-variance-authority clsx tailwind-merge
 yarn add react react-dom class-variance-authority clsx tailwind-merge
 ```
 
-#### Optional: animations and icons
+#### Optional: animations, icons, and charts
 
-Add **`framer-motion`** when you import any `@zentauri-ui/zentauri-components/ui/<name>/animated` entry (including **Spinner**, which is only published under `ui/spinner/animated`). Add **`react-icons`** when using icon sets from that package.
+Add **`framer-motion`** when you import any `@zentauri-ui/zentauri-components/ui/<name>/animated` entry (including **Spinner**, which is only published under `ui/spinner/animated`). Add **`react-icons`** when using icon sets from that package. Add **`recharts`** when you import any `@zentauri-ui/zentauri-components/charts/<type>` entry or vendor charts with the CLI.
 
 ```bash
-npm install framer-motion react-icons
+npm install framer-motion react-icons recharts
 ```
 
 ```bash
-pnpm add framer-motion react-icons
+pnpm add framer-motion react-icons recharts
 ```
 
 ```bash
-yarn add framer-motion react-icons
+yarn add framer-motion react-icons recharts
 ```
 
-Published `dist/` files **import** these packages; they are **not** vendored inside `@zentauri-ui/zentauri-components`. Static `ui/<name>` bundles do not depend on `framer-motion`; only `ui/<name>/animated` entries do. Your app installs peers via `dependencies` where needed, and your bundler resolves them from `node_modules`.
+Published `dist/` files **import** these packages; they are **not** vendored inside `@zentauri-ui/zentauri-components`. Static `ui/<name>` bundles do not depend on `framer-motion`; only `ui/<name>/animated` entries do. Chart bundles are isolated to `charts/<type>` entries and depend on `recharts`. Your app installs peers via `dependencies` where needed, and your bundler resolves them from `node_modules`.
 
 ### Next.js: smaller route chunks
 
@@ -181,7 +286,7 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   experimental: {
-    optimizePackageImports: ["framer-motion", "react-icons"],
+    optimizePackageImports: ["framer-motion", "react-icons", "recharts"],
   },
 };
 
@@ -230,6 +335,7 @@ import {
 ```tsx
 import { useDisclosure } from "@zentauri-ui/zentauri-components/hooks/useDisclosure";
 import { Button } from "@zentauri-ui/zentauri-components/ui/buttons";
+import { AreaChart } from "@zentauri-ui/zentauri-components/charts/area";
 ```
 
 #### Imports (animated / Framer Motion)
@@ -275,9 +381,9 @@ import { Spinner } from "@zentauri-ui/zentauri-components/ui/spinner/animated";
 
 ## CLI — copy component source into your app
 
-The package ships a small **Node CLI** (`zentauri-components` and `zentauri-ui` point to the same `cli/index.mjs`) that copies **selected** folders from this package’s `src/ui` and `src/hooks` into your repository—similar to shadcn/ui. You keep the files, control paths via `components.json`, and imports are rewritten to your path aliases (`@/components/ui`, `@/hooks`, `@/lib/utils`, and so on).
+The package ships a small **Node CLI** (`zentauri-components` and `zentauri-ui` point to the same `cli/index.mjs`) that copies **selected** folders from this package’s `src/ui`, `src/charts`, and `src/hooks` into your repository—similar to shadcn/ui. You keep the files, control paths via `components.json`, and imports are rewritten to your path aliases (`@/components/ui`, `@/hooks`, `@/lib/utils`, and so on).
 
-Which UI folders are valid for `add` is driven by **`cli/registry.json`**: a generated manifest listing every addable directory name (matching `src/ui/<name>`) plus optional **`nameAliases`** so the CLI accepts friendly tokens (for example `button` → `buttons`).
+Which UI folders are valid for `add` is driven by **`cli/registry.json`**: a generated manifest listing every addable directory name (matching `src/ui/<name>` plus chart entries like `src/charts/area`) plus optional **`nameAliases`** so the CLI accepts friendly tokens (for example `button` → `buttons`).
 
 ### Commands
 
@@ -286,6 +392,7 @@ Call the published binary by name after the package (recommended so `npx` does n
 ```bash
 npx @zentauri-ui/zentauri-components init
 npx @zentauri-ui/zentauri-components add buttons inputs
+npx @zentauri-ui/zentauri-components add charts/area charts/line
 npx @zentauri-ui/zentauri-components -h
 ```
 
@@ -311,11 +418,11 @@ node node_modules/@zentauri-ui/zentauri-components/cli/index.mjs add accordion
 node node_modules/@zentauri-ui/zentauri-components/cli/index.mjs add hook useWindowSize
 ```
 
-| Command | What it does |
-| ------- | -------------- |
-| `init` | Writes **`components.json`** in the current working directory (or `--cwd`) with default `aliases` and `resolvedPaths`. Refuses to overwrite an existing file. |
-| `add <names...>` | Walks up from `--cwd` (default `.`) to find `components.json`, then copies each resolved **UI** folder under `src/ui`, pulls in hooks those files depend on (including transitive hook imports), and creates **`lib/utils`** at `resolvedPaths.utils` from the package template if it is missing. |
-| `add hook <names...>` | Same config lookup; copies only **hook** folders listed under `registry.hooks` (from `hooksEntryNames` in `tsup.config.ts`), including transitive sibling-hook imports. Does not copy UI unless a hook’s imports require you to add a component separately (for example `usePagination` imports types from `ui/pagination`). |
+| Command               | What it does                                                                                                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `init`                | Writes **`components.json`** in the current working directory (or `--cwd`) with default `aliases` and `resolvedPaths`. Refuses to overwrite an existing file.                                                                                                                                                                              |
+| `add <names...>`      | Walks up from `--cwd` (default `.`) to find `components.json`, then copies each resolved **UI** folder under `src/ui` or chart entry under `src/charts/<type>`, pulls in hooks those files depend on (including transitive hook imports), and creates **`lib/utils`** at `resolvedPaths.utils` from the package template if it is missing. |
+| `add hook <names...>` | Same config lookup; copies only **hook** folders listed under `registry.hooks` (from `hooksEntryNames` in `tsup.config.ts`), including transitive sibling-hook imports. Does not copy UI unless a hook’s imports require you to add a component separately (for example `usePagination` imports types from `ui/pagination`).               |
 
 Global flags: `-h` / `--help`, `-v` / `--version`, `--cwd <dir>` (relative to `process.cwd()`).
 
@@ -340,7 +447,7 @@ Defaults look like this; edit `resolvedPaths` and `aliases` so they match your a
 
 ### Registry (`cli/registry.json`)
 
-- **`components`**: sorted list of folder names under **`src/ui/`** that `add` may copy. The file is **generated**; the canonical build list lives in **`tsup.config.ts`** as `uiComponentNames`, and the generator always ensures **`spinner`** is included so the CLI stays aligned with the animated-only spinner bundle.
+- **`components`**: sorted list of folder names under **`src/ui/`**, plus chart entries from **`src/charts/<type>`**, that `add` may copy. The file is **generated**; the canonical build list lives in **`tsup.config.ts`** as `uiComponentNames` and `chartEntryNames`, and the generator always ensures **`spinner`** is included so the CLI stays aligned with the animated-only spinner bundle.
 - **`hooks`**: sorted list of folder names under **`src/hooks/`** that `add hook` may copy; generated from **`hooksEntryNames`** in **`tsup.config.ts`** (same entries as published `…/hooks/<name>` subpaths).
 - **`nameAliases`**: optional map from a CLI token to a real folder name. Today: `button` → `buttons`, `input` → `inputs` (matching common singular names while folders stay plural).
 
@@ -355,10 +462,10 @@ After `add`, imports inside copied `.ts`/`.tsx` files are rewritten using your `
 
 ### When to use the CLI vs npm imports
 
-| Approach | Best when |
-| -------- | ----------- |
-| **`npm` + package `exports`** (earlier sections) | You want versioned dependencies, smallest app-owned surface, and tree-shaken `dist/` entries. |
-| **`init` / `add`** | You want vendored source under your repo (customize primitives, match shadcn-style workflows, or lock file-level behavior). |
+| Approach                                         | Best when                                                                                                                   |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| **`npm` + package `exports`** (earlier sections) | You want versioned dependencies, smallest app-owned surface, and tree-shaken `dist/` entries.                               |
+| **`init` / `add`**                               | You want vendored source under your repo (customize primitives, match shadcn-style workflows, or lock file-level behavior). |
 
 Tailwind still needs to see the classes your **copied** files use—point `@source` at those paths (for example your `src/components/ui`) rather than only at `node_modules/@zentauri-ui/zentauri-components` if you no longer rely on scanning the published package.
 
@@ -370,13 +477,14 @@ https://zentauri-ui.vercel.app/
 
 From this package directory in the monorepo:
 
-- `pnpm build` (or `npm run build`) — production bundle via `tsup` (Rollup treeshake + `scripts/prepend-use-client.mjs` via `onSuccess` so each UI entry under `dist/ui/`, including `dist/ui/<name>/animated.*`, starts with `"use client"` where needed)
+- `pnpm build` (or `npm run build`) — production bundle via `tsup` (Rollup treeshake + `scripts/prepend-use-client.mjs` via `onSuccess` so each UI entry under `dist/ui/`, the chart entry under `dist/charts/`, and `dist/ui/<name>/animated.*` starts with `"use client"` where needed)
 - `pnpm dev` — `tsup` watch mode (same `onSuccess` hook after each rebuild)
 - `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // covered 300+ test cases in total
-- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`** and **`hooksEntryNames`** from `tsup.config.ts`, merges in **`spinner`**, applies fixed **`nameAliases`**, and writes **`cli/registry.json`** (`components` + `hooks`). Run this after adding or renaming UI areas or hook entries so the CLI stays in sync (the script prints counts).
+- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`** and **`hooksEntryNames`** from `tsup.config.ts`, merges in **`spinner`**, applies fixed **`nameAliases`**, and writes **`cli/registry.json`** (`components` + `hooks`). Run this after adding or renaming UI/chart areas or hook entries so the CLI stays in sync (the script prints counts).
 - **`prepack`** — invokes `generate:registry` automatically before `npm pack` / publish so the published tarball always ships an up-to-date registry alongside `cli/index.mjs`.
 
 ## Github Release log
+
 https://github.com/ShubhamTiwari909/zentauri-ui/releases
 
 ## NOTE:

package/cli/index.mjs

@@ -20,12 +20,13 @@
  *        ├── cli/index.mjs      ← this file (entry when run via bin)
  *        ├── cli/registry.json  ← list of installable component folder names
  *        └── src/ui/<name>/     ← source copied by `add`
+ *        └── src/charts/<type>/ ← chart source copied by `add charts/area` etc.
  *        └── src/hooks/<name>/  ← hooks pulled in as dependencies
  *        └── src/lib/utils.ts   ← template for `cn()` etc. if missing in app
  * ```
  *
  * - **packageRoot**: directory of the published `components` package (parent of
- *   `cli/`). Used to read `registry.json`, `src/ui`, `src/hooks`, `src/lib`.
+ *   `cli/`). Used to read `registry.json`, `src/ui`, `src/charts`, `src/hooks`, `src/lib`.
  * - **configDir**: directory containing `components.json` (may differ from
  *   `--cwd` when the config is found by walking up from `cwd`).
  *
@@ -88,7 +89,7 @@ import {
   copyFile,
   readdir,
 } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 
@@ -102,7 +103,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 /**
  * Root of the components package (`…/packages/components`), i.e. parent of `cli/`.
- * All reads from `src/ui`, `src/hooks`, `registry.json`, and `package.json` are
+ * All reads from `src/ui`, `src/charts`, `src/hooks`, `registry.json`, and `package.json` are
  * relative to this path — not the consumer’s project root.
  */
 const packageRoot = join(__dirname, "..");
@@ -189,7 +190,9 @@ If npx does not pick the right binary:
  * isTestFile("foo.test.utils.ts"); // true (substring ".test.")
  */
 function isTestFile(name) {
-  return /\.(?:test|spec)\.(?:tsx?|jsx?)$/.test(name) || name.includes(".test.");
+  return (
+    /\.(?:test|spec)\.(?:tsx?|jsx?)$/.test(name) || name.includes(".test.")
+  );
 }
 
 /**
@@ -303,7 +306,11 @@ function validateConfig(cfg) {
       "components.json must define aliases.utils, aliases.hooks, and aliases.ui",
     );
   }
-  if (!cfg.resolvedPaths?.ui || !cfg.resolvedPaths?.utils || !cfg.resolvedPaths?.hooks) {
+  if (
+    !cfg.resolvedPaths?.ui ||
+    !cfg.resolvedPaths?.utils ||
+    !cfg.resolvedPaths?.hooks
+  ) {
     throw new Error(
       "components.json must define resolvedPaths.ui, resolvedPaths.utils, and resolvedPaths.hooks",
     );
@@ -312,7 +319,7 @@ function validateConfig(cfg) {
 
 /**
  * Maps CLI input (any casing, optional registry alias) to a canonical folder name
- * under `src/ui/<name>` in the package.
+ * under `src/ui/<name>` or `src/charts/<type>`.
  *
  * Resolution order:
  * 1. Exact key in `registry.nameAliases`
@@ -416,12 +423,12 @@ async function collectHookTransitiveClosure(packageRoot, seedHooks) {
 }
 
 /**
- * Copies `packageRoot/src/ui/<componentName>` into
+ * Copies `packageRoot/src/ui/<componentName>` or `packageRoot/src/charts/<type>` into
  * `<configDir>/<resolvedPaths.ui>/<componentName>`, skipping tests, rewriting
  * imports in TS/JS files, and collecting hook folder names referenced by those
  * files for later copying.
  *
- * @param {string} componentName — resolved registry name (directory under `src/ui`)
+ * @param {string} componentName — resolved registry name (directory under `src/ui`, or `charts/<type>`)
  * @param {object} config — validated `components.json`
  * @param {string} configDir — dirname(components.json)
  * @param {string} packageRoot — package containing source
@@ -433,18 +440,29 @@ async function collectHookTransitiveClosure(packageRoot, seedHooks) {
  * // src/components/ui/buttons/Button.tsx
  * // with imports pointing at @/lib/utils, @/hooks/useX, etc.
  */
-async function copyUiComponent(
-  componentName,
-  config,
-  configDir,
-  packageRoot,
-) {
-  const srcRoot = join(packageRoot, "src", "ui", componentName);
+async function copyUiComponent(componentName, config, configDir, packageRoot) {
+  const isChartEntry = componentName.startsWith("charts/");
+  const srcRoot = isChartEntry
+    ? join(packageRoot, "src", "charts")
+    : join(packageRoot, "src", "ui", componentName);
   if (!existsSync(srcRoot)) {
-    throw new Error(`Missing package source: ${relative(packageRoot, srcRoot)}`);
+    throw new Error(
+      `Missing package source: ${relative(packageRoot, srcRoot)}`,
+    );
   }
-  const destRoot = join(configDir, config.resolvedPaths.ui, componentName);
-  const files = await walkFiles(srcRoot);
+  const destRoot = isChartEntry
+    ? join(configDir, config.resolvedPaths.ui, "charts")
+    : join(configDir, config.resolvedPaths.ui, componentName);
+  const files = (await walkFiles(srcRoot)).filter((absSrc) => {
+    if (!isChartEntry) {
+      return true;
+    }
+    const relFromChartsRoot = relative(srcRoot, absSrc);
+    return (
+      relFromChartsRoot.startsWith("shared/") ||
+      relFromChartsRoot.startsWith(`${componentName.slice("charts/".length)}/`)
+    );
+  });
   const usedHooks = new Set();
 
   for (const absSrc of files) {
@@ -594,8 +612,7 @@ async function cmdAdd(names, cwd) {
   validateConfig(config);
 
   const registry = loadRegistry();
-  const hookMode =
-    names.length > 0 && names[0].toLowerCase() === "hook";
+  const hookMode = names.length > 0 && names[0].toLowerCase() === "hook";
   const payload = hookMode ? names.slice(1) : names;
 
   if (hookMode && payload.length === 0) {
@@ -604,9 +621,10 @@ async function cmdAdd(names, cwd) {
     );
     process.exitCode = 1;
     return;
-  }  
+  }
 
   if (hookMode) {
+    await ensureUtilsFile(config, configDir, packageRoot);
     const resolvedHooks = payload.map((n) => resolveHookName(n, registry));
     const finalHooks = await collectHookTransitiveClosure(
       packageRoot,
@@ -622,6 +640,8 @@ async function cmdAdd(names, cwd) {
 
   const resolvedNames = payload.map((n) => resolveComponentName(n, registry));
 
+  await ensureUtilsFile(config, configDir, packageRoot);
+
   const allHooks = new Set();
   for (const name of resolvedNames) {
     console.log(`Adding ${name}…`);
@@ -631,10 +651,9 @@ async function cmdAdd(names, cwd) {
     }
   }
 
-  const finalHooks = await collectHookTransitiveClosure(
-    packageRoot,
-    [...allHooks],
-  );
+  const finalHooks = await collectHookTransitiveClosure(packageRoot, [
+    ...allHooks,
+  ]);
 
   for (const h of finalHooks) {
     console.log(`Adding hook ${h}…`);
@@ -685,7 +704,7 @@ async function main() {
     return;
   }
 
-  const cwd = values.cwd ? join(process.cwd(), values.cwd) : process.cwd();
+  const cwd = values.cwd ? resolve(process.cwd(), values.cwd) : process.cwd();
   const cmd = positionals[0];
   const rest = positionals.slice(1);
 

package/cli/registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "description": "Addable UI components (src/ui) and hooks (src/hooks). Generated by scripts/generate-registry.mjs.",
+  "description": "Addable UI components (src/ui), chart entries (src/charts/*), and hooks (src/hooks). Generated by scripts/generate-registry.mjs.",
   "components": [
     "accordion",
     "alert",
@@ -9,6 +9,10 @@
     "breadcrumb",
     "buttons",
     "card",
+    "charts/area",
+    "charts/bar",
+    "charts/bubble",
+    "charts/line",
     "divider",
     "drawer",
     "dropdown",
@@ -28,7 +32,8 @@
     "tabs",
     "toast",
     "toggle",
-    "tooltip"
+    "tooltip",
+    "typography"
   ],
   "hooks": [
     "useBodyScrollLock",
@@ -59,6 +64,10 @@
   ],
   "nameAliases": {
     "button": "buttons",
+    "chart-area": "charts/area",
+    "chart-bar": "charts/bar",
+    "chart-bubble": "charts/bubble",
+    "chart-line": "charts/line",
     "input": "inputs"
   }
 }