@cere/cere-design-system 0.0.11 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cere/cere-design-system",
-  "version": "0.0.11",
+  "version": "0.0.15",
   "description": "Cere Network Design System - UI component library built with Material UI and React",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,7 +14,7 @@
   },
   "files": [
     "dist",
-    ".agent"
+    ".specify/memory"
   ],
   "scripts": {
     "build": "tsup",

package/.agent/README.md

@@ -1,154 +0,0 @@
-# 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/guidelines.md

@@ -1,111 +0,0 @@
-### Cere Design System — Development Guidelines (Material UI, Vite, Storybook, Jest)
-
-These notes capture project-specific details for developing this Material UI–based design system. Components should be implemented first, then covered with comprehensive tests. They complement README/TESTING docs with nuances from this repo's configuration.
-
-#### Build and Configuration
-- Build tool: `tsup`
-  - Entry: `src/index.ts`
-  - Formats: CJS + ESM, with type declarations (`dts: true`)
-  - Externalized peer deps to keep bundle lean: `react`, `react-dom`, `@mui/*`, `@emotion/*`, `reactflow`, `@monaco-editor/react`
-  - Command: `npm run build`
-- Type checking: `npm run type-check` (and `npm run check-types:ci` in CI)
-- Linting: `npm run lint` or `npm run lint:fix`
-- Vite (for Storybook and local tooling): minimal plugin setup in `vite.config.ts`
-- Package entrypoints are defined in `package.json` `exports`, with `main/module/types` pointing to `dist/*`
-- Peer dependencies (must be present in consumer app and in local dev):
-  - `@emotion/react`, `@emotion/styled`, `@mui/material`, `@mui/icons-material`, `@mui/lab`, `react`, `react-dom`, plus `reactflow`, `@monaco-editor/react` for third-party components
-
-#### Storybook Setup (Vite)
-- Start: `npm run storybook`
-- Build: `npm run build-storybook`
-- Customizations in `.storybook/main.ts`:
-  - CSS modules `localsConvention: 'camelCase'` to align class name access patterns
-  - `optimizeDeps.include` for `@monaco-editor/react`, `reactflow`, `monaco-editor`
-  - `define: { 'process.env': {} }` to satisfy Monaco in Vite/Storybook
-- Accessibility: `.storybook/test-runner.ts` integrates `@axe-core/playwright` checks for every story root (`#storybook-root`). Run with `npm run test:storybook`.
-
-#### Jest and RTL Configuration
-- Jest setup in `jest.config.js`:
-  - Preset: `ts-jest`
-  - Environment: `jsdom`
-  - Roots: `<rootDir>/src`
-  - Test discovery: `**/__tests__/**/*.test.{ts,tsx}` and `**/*.test.{ts,tsx}` under `src/`
-  - Path alias: `^@/(.*)$ -> <rootDir>/src/$1`
-  - CSS modules auto-mocked via `identity-obj-proxy`
-  - Coverage excludes stories, test files, `src/index.ts`, and type decls
-  - Transform configured to ensure `jsx: 'react-jsx'`
-- Test setup file: `src/setupTests.ts`
-  - Imports `@testing-library/jest-dom`
-  - Mocks `window.matchMedia` (important for MUI internals and components using media queries)
-- Commands:
-  - All tests: `npm test`
-  - Watch: `npm run test:watch`
-  - Coverage: `npm run test:coverage`
-  - CI mode: `npm run test:ci`
-
-#### Verified test run (local sanity)
-A minimal Jest test was added temporarily at `src/__tests__/sanity.test.ts` and executed with:
-```
-npm test -- src/__tests__/sanity.test.ts
-```
-It passed (`1 passed`). The file was removed after verification to keep the repo clean. Use this pattern to quickly validate the test harness when needed.
-
-#### Writing Tests (Pragmatic Workflow)
-- Principle: Implement components first, then write comprehensive tests to ensure quality and prevent regressions.
-- Where to put tests:
-  - Preferred: colocate under the component area using `__tests__` with `*.test.tsx` naming. Example: `src/components/layout/__tests__/Avatar.test.tsx`
-  - Alternatively: place a direct `*.test.tsx` beside the component; Jest will still pick it up.
-- Wrap components with theme in tests:
-```
-import { ThemeProvider } from '@mui/material';
-import { theme } from '@/theme';
-import { render } from '@testing-library/react';
-
-const renderWithTheme = (ui: React.ReactElement) =>
-  render(<ThemeProvider theme={theme}>{ui}</ThemeProvider>);
-```
-- Use React Testing Library idioms:
-  - Prefer `getByRole`, `getByText`, `getByLabelText` and user-level interactions via `@testing-library/user-event`
-  - Use `@testing-library/jest-dom` matchers (already configured)
-- Snapshot testing: Avoid broad snapshots for MUI; assert semantics and key props/attributes instead
-- Accessibility: Validate roles, names, disabled state, focus management
-- Example patterns already in repo: see `src/components/**/__tests__/*.test.tsx` (e.g., `Avatar.test.tsx`)
-
-#### Adding Storybook Interaction Tests
-- Add `play` functions to stories using `@storybook/test` utilities (e.g., `within`, `userEvent`)
-- Run with: `npm run test:storybook`
-- These tests also run automatic axe accessibility checks via the configured test runner
-
-#### Component Authoring Conventions
-- Material UI theming
-  - Use the shared `theme` from `src/theme` and expose component tokens via theme when practical
-  - Respect MUI variants/sizes; provide sensible defaults and typed props
-- Public exports
-  - Ensure all new components are exported from `src/index.ts` and surfaced in the package
-- CSS and classNames
-  - MUI’s `sx` and `styled` utilities are preferred; if class-based styling is necessary, remember Storybook’s CSS module config uses camelCase
-- Third-party components
-  - If components integrate `reactflow` or `@monaco-editor/react`, keep their imports dynamic-friendly and avoid relying on Node globals; Storybook’s `process.env` shim is in place
-
-#### Common Pitfalls and Fixes
-- matchMedia not defined in JSDOM
-  - Already handled in `src/setupTests.ts`. If adding features that rely on different media APIs, extend this mock
-- Failing to wrap with ThemeProvider in tests
-  - Most MUI components require theme context; tests should wrap components with `ThemeProvider`
-- Missing peer dependencies in consumer app or local dev
-  - Install all listed peer deps to avoid runtime errors
-- Class name expectations
-  - RTL queries should target roles and text over MUI-generated class names; class selectors may be brittle across MUI versions
-
-#### Release Hygiene
-- Run `npm run type-check && npm run lint && npm test && npm run build` before publishing
-- Storybook should render locally (`npm run storybook`) for visual checks; optionally run `npm run test:storybook` for a11y/interaction coverage
-
-#### Quick Development Loop
-1) Implement component following existing patterns and conventions
-2) Create Storybook story with all variants and states
-3) Write comprehensive tests under the component's `__tests__` folder
-4) Run `npm test -- componentPathOrPattern` to verify coverage
-5) Add `play` interaction tests to Storybook stories if relevant
-6) Verify accessibility with `npm run test:storybook`
-