@cere/cere-design-system 0.0.8 → 0.0.11

package/.agent/README.md

@@ -0,0 +1,154 @@
+# Cere Design System - AI Agent Context
+
+This folder contains documentation and context optimized for AI agents to effectively work with the Cere Design System.
+
+## Files
+
+### `rules/COMPONENTS.md`
+**Comprehensive component reference** for AI agents building applications with the Cere Design System.
+
+This file provides:
+- Complete listing of all 70+ available components
+- Detailed props and usage examples for each component
+- TypeScript type information
+- Theme and styling guidelines
+- Best practices and common patterns
+- Installation and setup instructions
+
+**Use Case:** Feed this document to AI agents (like Claude, GPT-4, etc.) as context when building React applications. The agent will have immediate access to all component APIs, props, and usage patterns without needing to search documentation or source code.
+
+### `rules/AGENTS.md`
+Development guidelines and architecture documentation for AI agents working on the design system codebase itself.
+
+### `rules/guidelines.md`
+General coding guidelines and conventions.
+
+## Usage Examples
+
+### For Building Applications
+
+When using an AI agent to build a React application with the Cere Design System:
+
+1. **Include the context**: Upload or paste `rules/COMPONENTS.md` into your AI conversation
+2. **Reference components**: Ask the agent to build UI using specific components from the design system
+3. **Get accurate code**: The agent will generate TypeScript/React code with correct imports, props, and patterns
+
+Example prompts:
+```
+"Build a login form using TextField, LoadingButton, and Alert components"
+"Create a dashboard with Grid, Card, ChartWidget, and MetricsChart"
+"Implement a data table with pagination using Table and Pagination components"
+```
+
+#### Injecting Context into Project Prompts
+
+You can provide the component reference to AI agents in several ways:
+
+**Method 1: Direct File Reference (Recommended)**
+```bash
+# After installing the package, reference the file directly
+cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
+```
+
+Then paste the output into your AI conversation or include it in your project's AI configuration.
+
+**Method 2: Project .cursorrules or .agent Files**
+
+Create a rule file in your project root that references the design system components:
+
+`.cursorrules` or `.agent/rules/design-system.md`:
+```markdown
+# Design System Components
+
+When building UI components, use the Cere Design System.
+
+Available components reference:
+
+{PASTE CONTENTS OF node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md HERE}
+```
+
+**Method 3: Dynamic Import Script**
+
+Create a script to automatically inject the context:
+
+`scripts/inject-design-system-context.sh`:
+```bash
+#!/bin/bash
+# Inject Cere Design System component reference into project AI context
+
+COMPONENTS_FILE="node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md"
+OUTPUT_FILE=".agent/rules/cere-components.md"
+
+if [ -f "$COMPONENTS_FILE" ]; then
+  echo "Copying Cere Design System component reference..."
+  mkdir -p .agent/rules
+  cp "$COMPONENTS_FILE" "$OUTPUT_FILE"
+  echo "✓ Component reference available at $OUTPUT_FILE"
+else
+  echo "Error: Design system not found. Run 'npm install' first."
+  exit 1
+fi
+```
+
+Make it executable and run after installation:
+```bash
+chmod +x scripts/inject-design-system-context.sh
+npm install && ./scripts/inject-design-system-context.sh
+```
+
+**Method 4: Package.json Postinstall Hook**
+
+Automatically copy the component reference after package installation:
+
+`package.json`:
+```json
+{
+  "scripts": {
+    "postinstall": "mkdir -p .agent/rules && cp node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md .agent/rules/cere-components.md || true"
+  }
+}
+```
+
+**Method 5: AI Tool Configuration**
+
+For tools like Cursor, Cline, or Windsurf, add to your configuration:
+
+`.cursor/rules` or `.windsurfrules`:
+```
+When building React components, always use components from @cere/cere-design-system.
+Refer to the complete component API documentation at:
+node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
+```
+
+### For Package Installation
+
+After installing the package:
+```bash
+npm install @cere/cere-design-system
+```
+
+The `.agent` folder will be available at:
+```
+node_modules/@cere/cere-design-system/.agent/
+```
+
+You can reference it in AI agent contexts or documentation tools.
+
+## Benefits
+
+- **Faster Development**: AI agents have immediate access to all component APIs
+- **Consistency**: Ensures AI-generated code follows design system patterns
+- **Type Safety**: All TypeScript types and interfaces are documented
+- **Best Practices**: Common patterns and usage guidelines included
+- **Complete Reference**: No need to browse Storybook or source code during AI-assisted development
+
+## Updating
+
+This documentation is maintained alongside the component source code. When components are added or updated, the `COMPONENTS.md` file should be updated to reflect the changes.
+
+## Package Information
+
+- **Package**: `@cere/cere-design-system`
+- **Version**: 0.0.10
+- **Repository**: https://github.com/cere-io/cere-design-system
+- **License**: MIT

package/.agent/rules/AGENTS.md

@@ -0,0 +1,145 @@
+# AGENTS.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Project Overview
+
+This is a React-based design system library built with Material UI and TypeScript. It's distributed as an npm package (@cere/cere-design-system) containing 40+ reusable UI components organized into categories: buttons, inputs, navigation, layout, and feedback components. The library also includes third-party integrations for ReactFlow (FlowEditor) and Monaco Editor (CodeEditor).
+
+## Architecture
+
+### Component Structure
+- All components are in `src/components/` organized by category:
+  - `buttons/` - Button, IconButton, LoadingButton, ButtonGroup
+  - `inputs/` - TextField, SearchField, Dropdown, Switch, Checkbox, Radio, ToggleButton
+  - `navigation/` - Sidebar, Tab, Menu, Pagination, Selector, Stepper
+  - `layout/` - Dialog, Drawer, Card, List, Avatar, Table, Grid, AppBar, Paper, etc.
+  - `feedback/` - Badge, Chip, Tooltip, Progress, Alert, EmptyState, Loading
+  - `third-party/` - FlowEditor (ReactFlow wrapper), CodeEditor (Monaco wrapper)
+
+### Component Pattern
+Each component follows this structure:
+- Main component file (e.g., `Button.tsx`) exports component and TypeScript types
+- Storybook story file (e.g., `Button.stories.tsx`) for documentation/testing
+- Jest test file in `__tests__/` subdirectory (e.g., `__tests__/Button.test.tsx`)
+- Components use styled MUI components, not custom CSS files
+
+### Theme System
+- Theme defined in `src/theme/index.ts` using Material UI's `createTheme()`
+- Primary color: #1976d2 (blue, not purple as README mentions)
+- Export both `theme` and `colors` objects from theme file
+- Components extend MUI components with custom styled variants (primary, secondary, tertiary)
+- Border radius: 12px for inputs/buttons, 16px for cards/chips
+- Typography: Inter font family, specific font weights/sizes for each variant
+
+### Build System
+- Uses `tsup` for bundling (see `tsup.config.ts`)
+- Outputs CommonJS (`dist/index.js`), ESM (`dist/index.mjs`), and TypeScript declarations (`dist/index.d.ts`)
+- All React, MUI, Monaco, and ReactFlow packages are marked as external dependencies (peer dependencies)
+- Entry point: `src/index.ts` - ALL exports must be added here
+
+## Development Commands
+
+### Build & Development
+```bash
+# Build the library (produces dist/ folder)
+npm run build
+
+# Build in watch mode
+npm run dev
+
+# Run Storybook for component development
+npm run storybook
+
+# Build Storybook for deployment
+npm run build-storybook
+```
+
+### Testing
+```bash
+# Run Jest unit tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
+
+# Run tests in CI mode
+npm run test:ci
+
+# Run Storybook interaction tests (includes a11y checks)
+npm run test:storybook
+```
+
+### Code Quality
+```bash
+# Run ESLint
+npm run lint
+
+# Fix ESLint issues automatically
+npm run lint:fix
+
+# TypeScript type checking
+npm run type-check
+
+# Type checking for CI
+npm run check-types:ci
+```
+
+## Testing Requirements
+
+### Test Structure
+- Unit tests: Use Jest + React Testing Library in `__tests__/` subdirectories
+- Interaction tests: Use Storybook's `play` function in `.stories.tsx` files
+- All components must wrap with `<ThemeProvider theme={theme}>` in tests
+- Standard test helper pattern:
+  ```tsx
+  const renderWithTheme = (component: React.ReactElement) => {
+    return render(<ThemeProvider theme={theme}>{component}</ThemeProvider>);
+  };
+  ```
+
+### Test Coverage
+- Target: 80%+ coverage for component logic
+- Test files should cover: rendering, user interactions, prop variants, callbacks, disabled/error states
+- Storybook Test Runner automatically runs accessibility (a11y) checks using axe-playwright
+
+## Adding New Components
+
+When adding new components:
+1. Create component file in appropriate category folder in `src/components/`
+2. Export component and TypeScript types (props interface)
+3. Add exports to `src/index.ts` (both component and type exports)
+4. Create Storybook story with examples of all variants/states
+5. Write Jest unit tests in `__tests__/` subdirectory
+6. Follow existing component patterns:
+   - Use MUI components as base, extend with `styled()`
+   - Support custom variants (primary, secondary, tertiary) where applicable
+   - Include proper TypeScript types and JSDoc comments
+   - Handle theme integration using `useTheme()` hook or `colors` import
+
+## Third-Party Components
+
+### FlowEditor (ReactFlow)
+- Wrapper around ReactFlow with theme integration
+- ReactFlow CSS imported in Storybook's preview.tsx
+- Custom props: height, showBackground, showControls, showMinimap
+- Re-exports commonly used ReactFlow types (Node, Edge, NodeTypes, etc.)
+
+### CodeEditor (Monaco)
+- Wrapper around Monaco Editor
+- Supports fullscreen mode, validation, type definitions injection
+- TypeScript configuration in `configureTypeScript()` function
+- Monaco loads from node_modules automatically (no loader configuration needed)
+- Supports multiple languages: typescript, javascript, json, yaml, python, etc.
+
+## Important Notes
+
+- This package uses peer dependencies - consumers must install React, MUI, ReactFlow, and Monaco themselves
+- Do NOT add new dependencies without considering if they should be peer dependencies
+- The package name is `@cere/cere-design-system`
+- When updating MUI components, ensure backward compatibility or update version appropriately
+- ESLint ignores: dist/, config files, and .stories files
+- Jest ignores: stories, test files, index.ts, and .d.ts files for coverage