# Contentstack Venus Component Library

---

## 1. Overview

**Venus Components** is Contentstack's official React component library, providing a comprehensive collection of reusable UI components. It serves as the design system foundation for Contentstack's UI-React application and can be used to build UI Extensions and Contentstack-based applications.

**Key Features:**

- 100+ production-ready React components
- TypeScript support with full type definitions
- Design token system for consistent theming
- SCSS-based styling with customizable variables
- Comprehensive Storybook documentation
- Accessibility-focused (WCAG AA standards)
- Redux integration for stateful components
- Rich Text Editor components (Slate-based)
- Form components with Formik integration

---

## 2. Tech Stack

| Layer                    | Technology                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Language**             | TypeScript 5.3.3                                                                   |
| **Framework**            | React 18.3.1                                                                       |
| **Build Tool**           | Rollup 2.23.0 (main bundler)                                                       |
| **Module Bundler**       | Webpack 4.43.0 (Storybook only)                                                    |
| **Component Library**    | This is the Venus Components library itself                                        |
| **State Management**     | Redux 4.0.5 + React Redux 7.2.1                                                    |
| **Router**               | React Router DOM 5.2.0                                                             |
| **Testing**              | Jest 27.5.1 + React Testing Library 10.4.9                                         |
| **Code Quality**         | ESLint 8.47.0 + Prettier 2.0.4                                                     |
| **Component Docs**       | Storybook 6.5.14                                                                   |
| **Design Tokens**        | Style Dictionary 2.10.1                                                            |
| **Styling**              | SCSS/PostCSS + Design Tokens                                                       |
| **Forms**                | Formik 2.4.6                                                                       |
| **Rich Text Editor**     | Slate 0.77.2                                                                       |
| **HTTP Client**          | Axios 1.8.4                                                                        |
| **Date Handling**        | date-fns 2.15.0 + Moment.js 2.29.1                                                 |

---

## 3. Project Structure

```
venus-components/
├── .ai/                          # AI assistant configurations
│   ├── rules/                   # Coding standards and workflows (full docs)
│   ├── skills/                  # Domain-specific skill modules (full docs)
│   └── commands/                # Custom Cursor commands (full implementations)
├── .cursor/                      # Cursor IDE configurations
│   ├── rules/                   # Auto-loaded rule summaries (.mdc files)
│   ├── skills/                  # Skill reference (points to .ai/skills/)
│   └── commands/                # Command references (point to .ai/commands/)
├── bin/                          # CLI scripts for component creation
├── build/                        # Compiled output (generated, do not import from here)
│   ├── components/              # Compiled component files
│   ├── utils/                   # Compiled utility files
│   ├── main.css                 # Bundled CSS styles
│   ├── variables.css/js/scss    # Design token variables (built)
│   └── index.js/esm.js         # Bundle entry points
├── packages/                     # Monorepo packages
│   └── venus-mcp/               # MCP server for AI-assisted development
├── design-tokens/                # Design system token definitions (source)
│   ├── colors/                  # Color palette tokens
│   ├── typography/              # Font and text tokens
│   ├── spacing/                 # Spacing scale tokens
│   └── ...                      # Other design token categories
├── tokens/                       # Generated token files (import from here)
├── plop-templates/               # Component generation templates
├── scripts/                      # Build and utility scripts
├── src/                          # Source code
│   ├── components/              # All React components
│   ├── utils/                   # Utility functions and helpers
│   ├── static/                  # Static assets (fonts, images, styles)
│   ├── index.ts                 # Main entry point (private build)
│   └── publicIndex.ts           # Public API exports (public build)
├── test/                         # Test configuration and setup
│   ├── jest.config.js           # Jest configuration for components
│   └── jestRte.config.js        # Jest configuration for RTE
├── tools/                        # Build tools and configurations
│   └── .storybook/              # Storybook configuration
├── design-token-build.js         # Design token build script
├── package.json                  # Dependencies and scripts
├── rollup.config.js              # Rollup bundler configuration
└── tsconfig.json                 # TypeScript configuration
```

---

## 4. Getting Started

### Prerequisites

- **Node.js**: v18.0.0+ or v20.x
- **npm**: v8.19.3+
- **Git**: Latest version
- **React**: v16.8.6+ || v17 || v18 || v19 (peer dependency)

### Installation for Contributors

```bash
$ git clone https://github.com/contentstack/venus-components.git
$ cd venus-components
$ npm install --legacy-peer-deps
$ npm run storybook  # Opens at http://localhost:9001
$ npm run build
```

---

## 5. Development

### Available Scripts

```bash
# Development
$ npm run storybook              # Start Storybook at http://localhost:9001
$ npm run watch                  # Watch mode - rebuild on file changes

# Building
$ npm run build                  # All components for internal apps → /build
$ npm run public-build           # Public components only for npm (STORYBOOKMODE=public)
$ npm run build_tokens           # Generate design tokens

# Testing (Jest 27.5.1 + React Testing Library 10.4.9)
$ npm test                       # Run all tests
$ npm run test-jest-config       # Run standard component tests
$ npm run test-jest-rte-config   # Run Rich Text Editor tests
$ npm run test-watch             # Watch mode
$ npm run coverage               # Generate coverage report (target: 80%+)
# Requirements: React Testing Library (not Enzyme), test behavior not implementation
# See .ai/rules/unit-testing.md for complete guidelines

# Code Quality
$ npm run lint                   # Run ESLint
$ npm run commit                 # Commitizen for conventional commits

# MCP Server (AI Assistant)
$ cd packages/venus-mcp && npm run build  # Build MCP server
$ cd packages/venus-mcp && npm run dev    # Watch mode
$ cd packages/venus-mcp && npm start      # Run MCP server

# Utilities
$ npm run add                    # Create new component (interactive)
$ npm run clean-install          # Clean reinstall
```

### Coding Standards

Strict standards enforced through Cursor AI rules: TypeScript types required, React Testing Library mandatory, use SCSS design tokens (`$token-name`), add `data-test-id` to interactive elements, wrap async in try-catch.

See `.cursor/rules/` and `.ai/rules/`: `coding-standards.md`, `code-review-guidelines.md`, `unit-testing.md`, `snyk_rules.md`, `dev-workflow.md`

---

## 6. Using the Library in Your Project

### Installation for Consumers

```bash
$ npm i @contentstack/venus-components --save
```

### Import and Use

```tsx
import '@contentstack/venus-components/build/main.css'
import { Button, Table, Modal } from '@contentstack/venus-components'

<Button buttonType="primary" onClick={() => console.log('Clicked!')}>Click Me</Button>
```

### Design Tokens

**Consumers**:
```js
import { TokenName } from '@contentstack/venus-components/build/variables.js'
@import '@contentstack/venus-components/build/variables.css'
```

**Developers** (internal): Import from `tokens/` source, use SCSS variables:
```scss
@import '../../tokens/space';
.my-component { padding: $space-4; } // SCSS variables, not var(--space-4)
```

---

## 7. Git Workflow

### Commit Standards

Use `npm run commit` for Conventional Commits. Hooks run automatically: pre-commit (lint), pre-push (tests).

Types: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`

---

## 8. Cursor AI Features

**Rules** (`.ai/rules/`): Mandatory standards - coding standards, testing, code review, security, dev workflow.

**Skills** (`.ai/skills/`): Educational modules - Code Review, Debugging, Component Development, Storybook, MCP Server, JsonRTE, RichTextEditor, AssetPicker, Table, Forms.

**MCP Server** (`packages/venus-mcp/`): Model Context Protocol server enabling AI-assisted component discovery and code generation. Provides 7 tools for browsing 154+ components, accessing design tokens, generating UI patterns, and searching by functionality. See [Venus MCP README](packages/venus-mcp/README.md) and [MCP Server Skill](.ai/skills/mcp-server-skill/skill.md) for setup and usage.

**Commands** (`.ai/commands/`): Custom workflows - `/code-review` for PR reviews, `/debug` for structured debugging sessions, `/execute-tests` for running tests, `/update-mcp-server` for syncing component changes to MCP, `/snyk-fix` for security vulnerability fixes.

---

## 9. Troubleshooting

### Common Issues

**Peer dependency conflicts**: Use `npm install --legacy-peer-deps`

**Node.js compatibility**: Use v18 or v20 (NOT v22). Switch with `nvm install 20 && nvm use 20`

**OpenSSL error**: Already fixed via `NODE_OPTIONS='--openssl-legacy-provider'` in package.json

**Module errors**: Run `npm run clean-install`

**Test failures**: Run `npx jest --clearCache && npm test`

**Token updates**: Run `npm run build_tokens && npm run build`

---

## 10. Related Documentation

| Resource                  | Link                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------- |
| **Venus Components**      | [GitHub](https://github.com/contentstack/venus-components)                         |
| **UI-React**              | [GitHub - Internal](https://github.com/contentstack/UI-React)                      |
| **React Testing Library** | [Official Docs](https://testing-library.com/react)                                 |
| **Storybook**             | [Official Docs](https://storybook.js.org/)                                         |
| **TypeScript**            | [Official Docs](https://www.typescriptlang.org/)                                   |
| **Style Dictionary**      | [Official Docs](https://amzn.github.io/style-dictionary/)                          |
| **Rollup**                | [Official Docs](https://rollupjs.org/)                                             |