npm - erp-pro-ui - Versions diffs - 0.1.1 → 0.1.3 - Mend

erp-pro-ui 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (432) hide show

package/README.md CHANGED Viewed

@@ -1,403 +1,627 @@
 # erp-pro-ui
-Premium UI component library for ERP and SaaS applications.
+Typed React 19 component library for ERP, admin, and SaaS products.
-## Features
+This package is designed to be consumed from a different project, not only inside this monorepo. It ships compiled styles, typed components, root imports, subpath imports, icons, helpers, machine-readable docs metadata, and a publishable npm package surface.
-- 🚀 **50+ Premium Components**: From basic buttons to complex data tables and charts.
-- 🎨 **Modern Aesthetics**: Sleek, glassmorphic, and highly interactive designs.
-- 📊 **Advanced Charts**: Customizable Neon Line Charts, Stacked Bar Charts, and more.
-- ⌨️ **Accessibility**: Built with accessibility and responsiveness in mind.
-- 🛠️ **Developer Friendly**: Fully typed with TypeScript and easy to integrate.
+Live docs: [daniel-heydari-dev.github.io/erp-pro-ui](https://daniel-heydari-dev.github.io/erp-pro-ui/)
+## What You Get
+- React 19 components for forms, overlays, navigation, data display, charts, typography, and visual effects.
+- Shared theme provider and toast provider for app-level wiring.
+- Flat public API with optional subpath imports for smaller consumer bundles.
+- Shared icon components from one folder and one barrel export.
+- Structured docs exports from `erp-pro-ui/docs` and `erp-pro-ui/catalog`.
 ## Installation
+Install the package and its required React peer dependencies:
 ```bash
-pnpm add erp-pro-ui
-# or
-npm install erp-pro-ui
-# or
-yarn add erp-pro-ui
+npm install erp-pro-ui react react-dom
 ```
-### Peer Dependencies
-Ensure you have the following peer dependencies installed:
+Install optional peers only if you use the components that need them:
 ```bash
-pnpm add framer-motion three @react-three/fiber @react-three/drei @tanstack/react-table recharts lucide-react
+npm install framer-motion @tanstack/react-table three
 ```
-### Font Setup (Geist)
+### Peer Dependency Guide
-Add to your HTML `<head>`:
+| Package                 | Required | Used by                                                                                              |
+| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `react`                 | Yes      | All components                                                                                       |
+| `react-dom`             | Yes      | All components                                                                                       |
+| `framer-motion`         | Optional | Dialog, Drawer, Toast, Carousel, AnimatedContent, GradualBlur, SpotlightCard, several visual effects |
+| `@tanstack/react-table` | Optional | DataTable                                                                                            |
+| `three`                 | Optional | 3D and visual effect components that depend on Three.js-backed rendering                             |
-```html
-<link rel="preconnect" href="https://fonts.googleapis.com" />
-<link
-  href="https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap"
-  rel="stylesheet"
-/>
+`recharts`, `clsx`, and `tailwind-merge` are regular package dependencies and do not need to be installed separately in the consuming app.
+## Setup In Another Project
+### 1. Import the package styles once
+In your global stylesheet:
+```css
+@import "tailwindcss";
+@import "erp-pro-ui/styles.css";
 ```
-In your Tailwind config, extend `fontFamily`:
+That single import already loads the packaged colors, fonts, foundations, and generated Tailwind v4 tokens. You do not need a local Tailwind theme extension just to use the library palette.
-```js
-fontFamily: {
-  geist: ['Geist', 'sans-serif'],
-}
+Prefer the semantic utilities and `--ds-*` tokens in new code. The older `--color-*` and `primary-*` aliases are still shipped as a migration surface, not as the preferred authoring API.
+If you only want the raw design tokens without the Tailwind bridge, import the internal token layer directly instead:
+```css
+@import "erp-pro-ui/tokens.css";
 ```
-## 🚀 Quick Start
+If you want just the token bridge and fonts without the rest of the library styles, import them directly instead:
 ```css
 @import "tailwindcss";
-@import "erp-pro-ui/styles.css";
+@import "erp-pro-ui/colors.css";
+@import "erp-pro-ui/fonts.css";
 ```
+### 2. Wrap the app with providers
+Use `ThemeProvider` if you want the built-in light/dark theme context. Use `ToastProvider` if you want to call `useToast()` anywhere in the app.
 ```tsx
-import { ThemeProvider, Button, Input, Typography } from "erp-pro-ui";
+import React from "react";
+import ReactDOM from "react-dom/client";
-function App() {
-  return (
+import { ThemeProvider, ToastProvider } from "erp-pro-ui";
+import "./styles.css";
+import { App } from "./App";
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
     <ThemeProvider>
-      <Typography variant="h1" gradient="ocean">
-        Welcome to ERP Pro
-      </Typography>
-      <Input label="Email" placeholder="you@company.com" />
-      <Button primary label="Get Started" />
+      <ToastProvider>
+        <App />
+      </ToastProvider>
     </ThemeProvider>
+  </React.StrictMode>,
+);
+```
+### 3. Start using components
+```tsx
+import { Button, Card, Input, Typography } from "erp-pro-ui";
+export function App() {
+  return (
+    <Card>
+      <Typography variant="h2">Welcome</Typography>
+      <Input label="Email" placeholder="you@company.com" />
+      <Button primary>Continue</Button>
+    </Card>
   );
 }
 ```
-## 🧱 Package Contract
+### Next.js note
-`erp-pro-ui` publishes reusable UI primitives and domain components.
+If you use Next.js, import `erp-pro-ui/styles.css` from your app-level global stylesheet and place `ThemeProvider` and `ToastProvider` in your shared app provider wrapper or root layout client boundary.
-- Import `tailwindcss` in your app stylesheet, then import `erp-pro-ui/styles.css` once to load the shared tokens and theme presets.
-- Use root imports for convenience: `import { Button, Dialog } from 'erp-pro-ui'`
-- Use subpath imports for leaner consumer bundles: `import { Button } from 'erp-pro-ui/button'`
-- Use `erp-pro-ui/docs` when another tool, app, or script needs structured install and component metadata.
-- Do not import from `src/**` or internal grouped folders; those paths are implementation details and may change between releases.
-- Composite showcase pages are intentionally excluded from the public API. Build those in your app by composing exported primitives.
+## Colors And Fonts In Another Project
-## 📚 Portable Docs Export
+The library now ships a two-layer theme contract so another project can use the same tokens without copying theme config:
-`erp-pro-ui` now ships a machine-readable docs surface at `erp-pro-ui/docs`.
+- `erp-pro-ui/tokens.css`: raw `--ds-*` tokens plus compatibility CSS variables
+- `erp-pro-ui/colors.css`: Tailwind v4 `@theme` bridge that generates semantic utilities
+- `erp-pro-ui/styles.css`: full package stylesheet, including fonts, tokens, bridge, foundations, and animations
-Use it when you need to power another docs site, custom CLI tooling, AI prompts,
-or project-specific scaffolding without reaching into the web app source.
+### Use the generated utility classes
-```tsx
-import {
-  getComponentDocByName,
-  libraryDocs,
-  searchComponentDocs,
-} from "erp-pro-ui/docs";
-const button = getComponentDocByName("Button");
-const chartComponents = searchComponentDocs("chart");
+After importing `erp-pro-ui/styles.css` or `erp-pro-ui/colors.css`, you can use the semantic Tailwind v4 utilities directly:
-console.log(libraryDocs.installSteps);
-console.log(button?.rootImport);
-console.log(chartComponents.map((component) => component.name));
+```tsx
+export function ThemePreview() {
+  return (
+    <section className="bg-surface text-fg border border-border rounded-2xl p-6 shadow-2 font-sans">
+      <h2 className="text-accent text-2xl font-semibold">
+        Semantic theme utilities
+      </h2>
+      <p className="text-fg-muted">
+        These classes come from erp-pro-ui. No local Tailwind theme extension is
+        required.
+      </p>
+      <div className="mt-4 flex gap-3">
+        <span className="bg-accent text-on-accent rounded-full px-3 py-1">
+          Accent
+        </span>
+        <span className="bg-accent-subtle text-accent rounded-full px-3 py-1">
+          Accent Subtle
+        </span>
+        <span className="bg-success-subtle text-success rounded-full px-3 py-1">
+          Success
+        </span>
+      </div>
+    </section>
+  );
+}
 ```
-The docs bundle includes:
-- package-level summary and feature highlights
-- install steps and peer dependency guidance
-- quick start examples
-- a complete component inventory with slugs, Storybook titles, docs URLs, and supported import paths
-- helpers for exact component lookup and component search
+### Use the CSS variables directly
-## 🤖 MCP Server
+You can also use the readable CSS variables in plain CSS, CSS Modules, or inline styles:
-For AI-assisted workflows, use the companion MCP package:
+```css
+.dashboard-shell {
+  background: var(--ds-color-bg-surface);
+  color: var(--ds-color-fg);
+  border: 1px solid var(--ds-color-border);
+  box-shadow: var(--ds-shadow-2);
+  font-family: var(--font-sans);
+}
-```bash
-npx -y erp-pro-ui-mcp-server
-```
+.dashboard-shell a {
+  color: var(--ds-color-accent);
+}
-Example MCP client configuration:
+.dashboard-shell .status-info {
+  color: var(--ds-color-info);
+}
-```json
-{
-  "mcpServers": {
-    "erp-pro-ui": {
-      "command": "npx",
-      "args": ["-y", "erp-pro-ui-mcp-server"]
-    }
-  }
+.dashboard-shell .chart-series {
+  stroke: var(--ds-chart-6);
 }
 ```
-The server exposes tools for library overview, component listing, component search,
-exact component docs lookup, installation guidance, readable resource URIs, and
-prompt templates for component selection and integration.
-## 🗂️ Internal Architecture
-The published API stays flat, while the source is organized by responsibility:
-```text
-src/
-  foundations/theme
-  components/forms
-  components/overlays
-  components/data-display
-  components/navigation
-  components/feedback
-  components/typography
-  components/effects
-  components/icons
-  components/spinners
-  utils
+### Chart color slots
+The library now ships fifteen dedicated chart slots in both token layers:
+- `--ds-chart-1` through `--ds-chart-15`
+- `--color-chart-1` through `--color-chart-15`
+When you pass chart colors from React, you can use any CSS color string, the CSS vars directly, or the built-in helper and shorthand token names:
+```tsx
+import { BarChart, getChartColorVar } from "erp-pro-ui";
+<BarChart
+  data={data}
+  categories={[
+    { key: "revenue", color: getChartColorVar(1) },
+    { key: "cost", color: "chart-6" },
+    { key: "profit", color: "var(--color-chart-10)" },
+  ]}
+/>;
 ```
-This keeps the codebase maintainable without forcing consumers to learn internal folder names.
-## 📋 Component Reference
-### Form Controls
-| Component               | Description                                                  |
-| ----------------------- | ------------------------------------------------------------ |
-| `Button`                | Primary/secondary button with size variants                  |
-| `Input`                 | Text input with label, validation states, and hover gradient |
-| `Textarea`              | Multi-line text input                                        |
-| `Select`                | Dropdown selection                                           |
-| `Checkbox`              | Checkbox with label                                          |
-| `Radio`                 | Radio button group                                           |
-| `Switch`                | Toggle switch                                                |
-| `OTPInput`              | One-time password input                                      |
-| `DatePicker`            | Calendar-based date picker                                   |
-| `Combobox`              | Searchable dropdown                                          |
-| `MultiSelectCombobox`   | Multi-value searchable dropdown                              |
-| `PasswordStrengthMeter` | Visual password strength indicator                           |
-| `Form`                  | Form wrapper with validation                                 |
-### Layout & Containers
-| Component   | Description                                                  |
-| ----------- | ------------------------------------------------------------ |
-| `Card`      | Content container card                                       |
-| `Accordion` | Expandable content panels                                    |
-| `Dialog`    | Modal dialog with variants, presets, and 10 animation styles |
-| `Drawer`    | Slide-out panel (left/right/top/bottom)                      |
-| `Tooltip`   | Hover tooltip                                                |
-| `HoverCard` | Rich content hover card                                      |
-| `Calendar`  | Calendar display                                             |
-| `Carousel`  | Content carousel/slider                                      |
-### Typography
-| Component    | Description                                                                                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Typography` | Semantic text with `h1`–`h6`, `body1`, `body2`, `caption`, `overline` variants. Supports `gradient`, `align`, `weight`, `tracking`, and `italic` props. |
-### Data Display
-| Component      | Description                                                                     |
-| -------------- | ------------------------------------------------------------------------------- |
-| `DataTable`    | Feature-rich table with sorting, filtering, column toggles, and filter profiles |
-| `Chip`         | Status/tag badge with `filled`, `outlined`, `ghost` variants                    |
-| `Stepper`      | Multi-step progress indicator (horizontal/vertical)                             |
-| `ColorPalette` | Color swatch display                                                            |
+`getChartColorVar(slot)` supports slots `1` through `15`. The chart components also normalize the shorthand `chart-6` form into the matching theme variable automatically.
-### Charts
+### Theme variable groups
-Built on [Recharts](https://recharts.org/), the chart components provide premium data visualization:
-| Component          | Type                          |
-| ------------------ | ----------------------------- |
-| `AreaChart`        | Gradient-filled area chart    |
-| `BarChart`         | Horizontal/vertical bar chart |
-| `PieChart`         | Pie and donut charts          |
-| `NeonLineChart`    | Glowing neon-style line chart |
-| `StackedBarChart`  | Stacked bar visualization     |
-| `ThinBreakdownBar` | Thin horizontal breakdown bar |
-### Feedback
-| Component                      | Description                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------- |
-| `Alert`                        | Banner alert with `default`, `destructive`, `success`, `warning`, `info` variants |
-| `ToastProvider` + `useToast()` | Toast notification system                                                         |
-| `Loading`                      | 8 loading variants: spinner, dots, pulse, bars, ring, bounce, wave, skeleton      |
-### Visual Effects
-| Component                     | Description                                       |
-| ----------------------------- | ------------------------------------------------- |
-| `BackgroundGradientAnimation` | Animated gradient background with 6 preset themes |
-| `SpotlightCard`               | Card with cursor-tracking spotlight effect        |
-| `AnimatedContent`             | Scroll-triggered entrance animations              |
-| `GradualBlur`                 | Progressive blur entrance effect                  |
-| `ChromaGrid`                  | Chromatic grid animation                          |
-| `SplashCursor`                | Interactive cursor splash effect                  |
-| `HoverBorderGradient`         | Animated gradient border on hover                 |
-| `SunToMoonButton`             | Animated theme toggle button                      |
-| `ASCIIText`                   | 3D ASCII text animation                           |
+The token system is split into stable layers:
-### Icons
+- Internal design-system tokens: `--ds-*`
+- Semantic utility aliases: `bg-surface`, `text-fg`, `border-border`, `bg-accent`, `text-on-accent`, `outline-focus`
+- Compatibility color variables: `--color-primary`, `--color-background-primary`, `--color-text-primary`, and the existing `primary-50` through `primary-900` theme scale
-30+ custom SVG icons available:
+For new components, use the semantic utility layer or the `--ds-*` variables directly. Keep the compatibility aliases for migration work and external consumers that still rely on the legacy contract.
-```tsx
-import { IconDashboard, IconSettings, IconUser } from "erp-pro-ui";
+### Theme switching
+If you use `ThemeProvider`, the library updates `data-brand` and `data-mode` for you. It still writes the old `data-theme` attribute for compatibility, but the new architecture treats brand and mode as separate axes.
-<IconDashboard className="w-5 h-5" />;
+If you do not use `ThemeProvider`, you can still switch manually in your app shell:
+```html
+<html data-brand="teal" data-mode="dark"></html>
 ```
-## 🎨 Theme System
+## Import Patterns
-Wrap your app with `ThemeProvider` for automatic dark/light mode:
+Use whichever public import style fits your project.
+### Root imports
 ```tsx
-import { ThemeProvider, useThemeContext } from "erp-pro-ui";
+import {
+  Button,
+  DataTable,
+  Dialog,
+  ThemeProvider,
+  ToastProvider,
+  Typography,
+} from "erp-pro-ui";
+```
-// In root
-<ThemeProvider>
-  <App />
-</ThemeProvider>;
+### Subpath imports
-// In any component
-const { mode, toggleMode, setMode } = useThemeContext();
+```tsx
+import { Button } from "erp-pro-ui/button";
+import { DataTable } from "erp-pro-ui/data-table";
+import { Dialog } from "erp-pro-ui/dialog";
+import { ThemeProvider } from "erp-pro-ui/theme";
+import { SearchIcon } from "erp-pro-ui/icons";
+import { Audio } from "erp-pro-ui/spinners";
 ```
-## 📖 Usage Examples
+### Structured docs and catalog exports
-### Dialog
+```tsx
+import { uiCatalogItems } from "erp-pro-ui/catalog";
+import {
+  getComponentDocByName,
+  libraryDocs,
+  searchComponentDocs,
+} from "erp-pro-ui/docs";
+```
+### Utilities
 ```tsx
-import { Dialog } from "erp-pro-ui";
-<Dialog
-  open={isOpen}
-  onOpenChange={setIsOpen}
-  title="Confirm Delete"
-  description="This action cannot be undone."
-  variant="destructive"
-  preset="confirm"
-  animation="scale"
-  onConfirm={() => handleDelete()}
-/>;
+import {
+  generateUniqueKey,
+  mergeClassNames,
+  validateEmail,
+} from "erp-pro-ui/utils";
 ```
-**Dialog Animations:** `fade`, `scale`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`, `elastic`, `bounce`, `flip`, `zoom`
+Only use the documented package exports. Do not import from `src/**` or internal folder paths.
-### Toast
+## Complete Starter Example
+This example shows the normal setup pattern in a separate app: theme provider, toast provider, input controls, status messaging, dialog usage, and shared layout components.
 ```tsx
-import { ToastProvider, useToast } from "erp-pro-ui";
+import { useState } from "react";
+import {
+  Alert,
+  Button,
+  Card,
+  Chip,
+  Dialog,
+  Input,
+  Select,
+  ToastProvider,
+  ThemeProvider,
+  Typography,
+  useToast,
+} from "erp-pro-ui";
+function DashboardDemo() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [email, setEmail] = useState("");
+  const { addToast } = useToast();
-// Wrap app
-<ToastProvider>
-  <App />
-</ToastProvider>;
+  return (
+    <div className="min-h-screen bg-neutral-50 p-6 dark:bg-neutral-950">
+      <div className="mx-auto flex max-w-4xl flex-col gap-6">
+        <div className="flex items-center justify-between">
+          <div>
+            <Typography variant="h1" gradient="ocean">
+              ERP Pro UI Demo
+            </Typography>
+            <Typography variant="body1">
+              Use the same package in any React 19 project.
+            </Typography>
+          </div>
+          <Chip variant="filled" color="success">
+            Ready
+          </Chip>
+        </div>
+        <Alert
+          variant="info"
+          title="Shared setup"
+          description="ThemeProvider and ToastProvider are already wired at the app root."
+        />
+        <Card className="space-y-4 p-6">
+          <Typography variant="h3">Create workspace</Typography>
+          <Input
+            label="Email"
+            placeholder="owner@company.com"
+            value={email}
+            onChange={(event) => setEmail(event.target.value)}
+          />
+          <Select
+            label="Plan"
+            placeholder="Choose a plan"
+            options={[
+              { value: "starter", label: "Starter" },
+              { value: "growth", label: "Growth" },
+              { value: "enterprise", label: "Enterprise" },
+            ]}
+          />
+          <div className="flex gap-3">
+            <Button
+              primary
+              onClick={() => {
+                addToast({
+                  type: "success",
+                  title: "Draft saved",
+                  message: "Workspace settings were saved locally.",
+                });
+              }}
+            >
+              Save draft
+            </Button>
+            <Button onClick={() => setDialogOpen(true)}>
+              Open review dialog
+            </Button>
+          </div>
+        </Card>
+        <Dialog
+          open={dialogOpen}
+          onOpenChange={setDialogOpen}
+          title="Review workspace"
+          description="Confirm that the workspace should be created."
+          preset="confirm"
+          variant="default"
+          onConfirm={() => {
+            setDialogOpen(false);
+            addToast({
+              type: "success",
+              title: "Workspace created",
+              message: "Your environment is ready to use.",
+            });
+          }}
+        />
+      </div>
+    </div>
+  );
+}
-// Use anywhere
-const { addToast } = useToast();
-addToast({ type: "success", title: "Saved!", message: "All changes saved." });
+export default function App() {
+  return (
+    <ThemeProvider>
+      <ToastProvider>
+        <DashboardDemo />
+      </ToastProvider>
+    </ThemeProvider>
+  );
+}
 ```
-### DataTable
+## Component Inventory
+The tables below document the public surface you can use from another project.
+### Providers, Shared Surfaces, and Package Utilities
+| Export                                                  | Public import                           | Notes                                       |
+| ------------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
+| `ThemeProvider`, `useThemeContext`                      | `erp-pro-ui` or `erp-pro-ui/theme`      | App theme context and mode switching        |
+| `ToastProvider`, `ToastItem`, `useToast`                | `erp-pro-ui` or `erp-pro-ui/toast`      | Global toast notifications                  |
+| `Typography`                                            | `erp-pro-ui` or `erp-pro-ui/typography` | Semantic text system                        |
+| all icons                                               | `erp-pro-ui` or `erp-pro-ui/icons`      | Shared React SVG icon components            |
+| `Audio`                                                 | `erp-pro-ui` or `erp-pro-ui/spinners`   | Audio wave spinner                          |
+| `generateUniqueKey`, `mergeClassNames`, `validateEmail` | `erp-pro-ui/utils`                      | Reusable package helpers                    |
+| `libraryDocs` and helpers                               | `erp-pro-ui/docs`                       | Machine-readable install and component docs |
+| `uiCatalogItems`                                        | `erp-pro-ui/catalog`                    | Component catalog metadata                  |
+### Form Components
+| Export                  | Subpath                              | Use it for                                            |
+| ----------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `Button`                | `erp-pro-ui/button`                  | Primary and secondary actions                         |
+| `Input`                 | `erp-pro-ui/input`                   | Text inputs with label, helper text, and icon support |
+| `InputState`            | `erp-pro-ui/input`                   | Input validation states                               |
+| `Textarea`              | `erp-pro-ui/textarea`                | Multi-line user input                                 |
+| `Select`                | `erp-pro-ui/select`                  | Fixed option dropdowns                                |
+| `Checkbox`              | `erp-pro-ui/checkbox`                | Multi-select and boolean inputs                       |
+| `Radio`                 | `erp-pro-ui/radio`                   | Single-choice form selections                         |
+| `Switch`                | `erp-pro-ui/switch`                  | Immediate on/off settings                             |
+| `Label`                 | `erp-pro-ui/label`                   | Accessible field labels                               |
+| `Calendar`              | `erp-pro-ui/calendar`                | Embedded calendar display                             |
+| `DatePicker`            | `erp-pro-ui/date-picker`             | Calendar-backed date inputs                           |
+| `Combobox`              | `erp-pro-ui/combobox`                | Searchable single-select control                      |
+| `MultiSelectCombobox`   | `erp-pro-ui/multi-select-combobox`   | Searchable multi-value selection                      |
+| `OTPInput`              | `erp-pro-ui/otp-input`               | Verification code entry                               |
+| `PasswordStrengthMeter` | `erp-pro-ui/password-strength-meter` | Password feedback UI                                  |
+| `Form`                  | `erp-pro-ui/form`                    | Form composition wrapper                              |
+### Navigation, Overlays, and Feedback
+| Export                                                                   | Subpath                 | Use it for                                              |
+| ------------------------------------------------------------------------ | ----------------------- | ------------------------------------------------------- |
+| `Accordion`                                                              | `erp-pro-ui/accordion`  | Collapsible sections                                    |
+| `Dialog`                                                                 | `erp-pro-ui/dialog`     | Confirmation flows and modal content                    |
+| `Drawer`                                                                 | `erp-pro-ui/drawer`     | Slide-over panels                                       |
+| `Tooltip`                                                                | `erp-pro-ui/tooltip`    | Short contextual help                                   |
+| `HoverCard`                                                              | `erp-pro-ui/hover-card` | Rich hover previews                                     |
+| `Carousel`                                                               | `erp-pro-ui/carousel`   | Horizontal content sliders                              |
+| `Stepper`                                                                | `erp-pro-ui/stepper`    | Multi-step workflow progress                            |
+| `Alert`                                                                  | `erp-pro-ui/alert`      | Inline success, warning, info, or destructive messaging |
+| `Loading`                                                                | `erp-pro-ui/loading`    | Unified loading API                                     |
+| `Spinner`, `Dots`, `Pulse`, `Bars`, `Ring`, `Bounce`, `Wave`, `Skeleton` | `erp-pro-ui/loading`    | Individual loading variants                             |
+| `SkeletonComponent`                                                      | root import only        | Root alias for the skeleton placeholder export          |
+### Data Display And Charts
+| Export                                                            | Subpath                    | Use it for                                        |
+| ----------------------------------------------------------------- | -------------------------- | ------------------------------------------------- |
+| `Card`                                                            | `erp-pro-ui/card`          | Panel and container layout                        |
+| `Chip`                                                            | `erp-pro-ui/chip`          | Tags, status pills, and labels                    |
+| `ColorPalette`                                                    | `erp-pro-ui/color-palette` | Design token or palette presentation              |
+| `DataTable`                                                       | `erp-pro-ui/data-table`    | Feature-rich tables with filtering and pagination |
+| `FilterDropdown`, `FilterButton`, `ColumnToggle`, `FilterProfile` | `erp-pro-ui/data-table`    | DataTable helper building blocks                  |
+| `AreaChart`                                                       | `erp-pro-ui/charts`        | Area chart visualizations                         |
+| `BarChart`                                                        | `erp-pro-ui/charts`        | Bar chart visualizations                          |
+| `PieChart`                                                        | `erp-pro-ui/charts`        | Pie and donut charts                              |
+| `NeonLineChart`                                                   | `erp-pro-ui/charts`        | Glowing line charts                               |
+| `StackedBarChart`                                                 | `erp-pro-ui/charts`        | Stacked comparisons                               |
+| `ThinBreakdownBar`                                                | `erp-pro-ui/charts`        | Compact segmented metric bars                     |
+### Visual Effects And Text Components
+| Export                        | Public import                              | Use it for                        |
+| ----------------------------- | ------------------------------------------ | --------------------------------- |
+| `AnimatedContent`             | `erp-pro-ui/animated-content`              | Entrance animation wrappers       |
+| `BackgroundGradientAnimation` | `erp-pro-ui/background-gradient-animation` | Full-section animated backgrounds |
+| `BorderBeam`                  | root import only                           | Beam border effect wrapper        |
+| `ButtonHoverBorderGradient`   | `erp-pro-ui/button-hover-border-gradient`  | CTA button with animated border   |
+| `ChromaGrid`                  | `erp-pro-ui/chroma-grid`                   | Animated background grid          |
+| `GradualBlur`                 | `erp-pro-ui/gradual-blur`                  | Progressive blur reveal           |
+| `HoverBorderGradient`         | `erp-pro-ui/hover-border-gradient`         | Hover border lighting treatment   |
+| `SplashCursor`                | `erp-pro-ui/splash-cursor`                 | Cursor effect overlay             |
+| `SpotlightCard`               | `erp-pro-ui/spotlight-card`                | Cursor-reactive premium card      |
+| `SunToMoonButton`             | `erp-pro-ui/sun-to-moon-button`            | Theme toggle control              |
+| `ASCIIText`                   | `erp-pro-ui/ascii-text`                    | Animated ASCII display text       |
+## Focused Usage Examples
+### Dialog and toast flow
 ```tsx
-import { DataTable, FilterDropdown, ColumnToggle } from "erp-pro-ui";
+import { Button, Dialog, ToastProvider, useToast } from "erp-pro-ui";
-<DataTable data={users} columns={columns} searchable sortable paginated />;
+function DeleteButton() {
+  const [open, setOpen] = useState(false);
+  const { addToast } = useToast();
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Delete record</Button>
+      <Dialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Delete record"
+        description="This action cannot be undone."
+        variant="destructive"
+        preset="confirm"
+        onConfirm={() => {
+          setOpen(false);
+          addToast({ type: "success", title: "Deleted" });
+        }}
+      />
+    </>
+  );
+}
 ```
-### Background Gradient
+### Data table
 ```tsx
-import { BackgroundGradientAnimation } from "erp-pro-ui";
-<BackgroundGradientAnimation
-  gradientBackgroundStart="rgb(0, 17, 82)"
-  gradientBackgroundEnd="rgb(108, 0, 162)"
-  firstColor="18, 113, 255"
-  secondColor="221, 74, 255"
-  thirdColor="100, 220, 255"
-  size="80%"
-  interactive
->
-  <h1>Your Content Here</h1>
-</BackgroundGradientAnimation>;
+import { DataTable } from "erp-pro-ui";
+const columns = [
+  { id: "name", label: "Name", visible: true },
+  { id: "email", label: "Email", visible: true },
+  { id: "role", label: "Role", visible: true },
+];
+const rows = [
+  { name: "Ava Stone", email: "ava@company.com", role: "Admin" },
+  { name: "Noah Reed", email: "noah@company.com", role: "Manager" },
+];
+<DataTable columns={columns} data={rows} searchPlaceholder="Search users" />;
 ```
-## 📂 Subpath Imports
+### Charts
+```tsx
+import { AreaChart, BarChart, PieChart } from "erp-pro-ui";
+const revenue = [
+  { name: "Jan", value: 2400 },
+  { name: "Feb", value: 3000 },
+  { name: "Mar", value: 2800 },
+];
+<AreaChart data={revenue} dataKey="value" xAxisKey="name" />;
+<BarChart data={revenue} dataKey="value" xAxisKey="name" />;
+<PieChart
+  data={[
+    { name: "ERP", value: 60 },
+    { name: "POS", value: 40 },
+  ]}
+/>;
+```
-For optimal bundle size, use subpath imports:
+### Icons
 ```tsx
-import { Button } from "erp-pro-ui/button";
-import { Dialog } from "erp-pro-ui/dialog";
-import { Input } from "erp-pro-ui/input";
-import { DataTable } from "erp-pro-ui/data-table";
-import { Calendar } from "erp-pro-ui/calendar";
+import { CloseIcon, RefreshIcon, SearchIcon } from "erp-pro-ui/icons";
+<div className="flex items-center gap-3">
+  <SearchIcon className="h-4 w-4" />
+  <RefreshIcon className="h-4 w-4" />
+  <CloseIcon className="h-4 w-4" />
+</div>;
 ```
-Subpath exports map to real build entries in `dist/`, so the documented import paths are the supported package boundary.
+## Companion Surfaces
-## 🧩 Composition Example
+### Structured docs bundle
-Complex pages should be assembled in the consuming app from exported primitives:
+Use `erp-pro-ui/docs` if you want to build your own docs page, CLI, codegen, or AI integration.
 ```tsx
 import {
-  AnimatedContent,
-  Button,
-  Carousel,
-  Dialog,
-  GradualBlur,
-} from "erp-pro-ui";
+  getComponentDocByName,
+  libraryDocs,
+  searchComponentDocs,
+} from "erp-pro-ui/docs";
-function MarketingShowcase() {
-  return (
-    <>
-      <GradualBlur>
-        <h1>Design System Showcase</h1>
-      </GradualBlur>
+const docs = getComponentDocByName("Dialog");
+const charts = searchComponentDocs("chart");
+console.log(libraryDocs.installSteps);
+console.log(docs?.subpathImport);
+console.log(charts.length);
+```
-      <AnimatedContent preset="scale">
-        <Carousel items={items} variant="glass" />
-      </AnimatedContent>
+### Catalog bundle
-      <Button primary label="Open Dialog" onClick={() => setOpen(true)} />
-      <Dialog open={open} onOpenChange={setOpen} title="Crystal Dialog" />
-    </>
-  );
-}
+Use `erp-pro-ui/catalog` if you only need the component list and public slugs.
+```tsx
+import { uiCatalogItems } from "erp-pro-ui/catalog";
+console.log(uiCatalogItems.map((item) => item.name));
 ```
-This pattern keeps the package lightweight while still supporting richer product-specific experiences.
+### MCP server
-## 🛠️ Development
+For AI-assisted tooling and editor integrations, use the companion package:
 ```bash
-# Install dependencies
-pnpm install
-# Type check
-pnpm typecheck
+npx -y erp-pro-ui-mcp-server
+```
-# Lint
-pnpm lint
+Example MCP client config:
-# Run Storybook
-pnpm storybook
+```json
+{
+  "mcpServers": {
+    "erp-pro-ui": {
+      "command": "npx",
+      "args": ["-y", "erp-pro-ui-mcp-server"]
+    }
+  }
+}
 ```
-## 🔌 Companion Packages
+## Development In This Repo
-- `erp-pro-ui`: the component library itself
-- `erp-pro-ui/docs`: structured docs metadata for scripts and external tools
-- `erp-pro-ui-mcp-server`: stdio MCP server for AI editors and agents
+```bash
+pnpm install
+pnpm --filter ./packages/ui build
+pnpm --filter ./packages/ui typecheck
+pnpm --filter ./packages/ui lint
+pnpm storybook
+```
-## 📄 License
+## License
 MIT