@cere/cere-design-system 0.0.8 → 0.0.11

package/.agent/rules/guidelines.md

@@ -0,0 +1,111 @@
+### 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`
+

package/README.md

@@ -5,7 +5,7 @@ Cere Network Design System built with Material UI and React.
 ## Installation
 
 ```bash
-npm install @cere-network/cere-design-system
+npm install @cere/cere-design-system
 ```
 
 ## Usage
@@ -205,6 +205,36 @@ npm run lint
 
 - [Full Components Reference](./COMPONENTS.md) - Complete API documentation
 - [Integration Guide](./INTEGRATION.md) - Step-by-step integration instructions
+- **[AI Agent Context](./.agent/README.md)** - Component reference optimized for AI agents (Claude, GPT-4, Cursor, etc.)
+
+## AI-Assisted Development
+
+This design system includes comprehensive AI agent context to accelerate development with AI coding assistants.
+
+### For AI Agents (Cursor, Claude, GPT-4, etc.)
+
+The package includes a complete component reference optimized for AI agents at `.agent/rules/COMPONENTS.md`.
+
+**Quick Start:**
+```bash
+# After installing the package
+cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
+```
+
+Paste the output into your AI conversation to give the agent complete knowledge of:
+- All 70+ available components
+- Props and TypeScript types
+- Usage examples and patterns
+- Theme configuration
+- Best practices
+
+**Setup Methods:**
+
+1. **Direct reference** - Copy the file content into your AI conversation
+2. **Project rules** - Add to `.cursorrules` or `.agent/rules/`
+3. **Auto-inject** - Use a postinstall script to copy to your project
+
+See [.agent/README.md](./.agent/README.md) for detailed setup instructions and examples.
 
 ## Integration with Existing Projects
 
@@ -224,8 +254,8 @@ To use this package in `dynamic-indexer-client` or other projects:
 
 3. Use in your app:
    ```tsx
-   import { theme } from '@cere-network/cere-design-system';
-   import { Button, Dialog, Sidebar } from '@cere-network/cere-design-system';
+   import { theme } from '@cere/cere-design-system';
+   import { Button, Dialog, Sidebar } from '@cere/cere-design-system';
    ```
 
 See [INTEGRATION.md](./INTEGRATION.md) for detailed migration guide.

package/dist/index.css

@@ -0,0 +1,79 @@
+/* src/assets/fonts/human-sans-font.css */
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 200;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-ExtraLight-VL7DEKQ4.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 300;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-Light-YV7AFKRB.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-Regular-QMFEP3F6.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-Medium-UULJ3PIR.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-Bold-4EAJ3L3T.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 900;
+  font-style: normal;
+  font-display: swap;
+  src: url("./HumanSans-Black-C4YJONK7.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 200;
+  font-style: oblique;
+  font-display: swap;
+  src: url("./HumanSans-ExtraLightOblique-VK2JTUXF.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 300;
+  font-style: oblique;
+  font-display: swap;
+  src: url("./HumanSans-LightOblique-VIXV7QA6.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 400;
+  font-style: oblique;
+  font-display: swap;
+  src: url("./HumanSans-RegularOblique-YPKQJAAM.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 500;
+  font-style: oblique;
+  font-display: swap;
+  src: url("./HumanSans-MediumOblique-M7FHDZRS.otf") format("opentype");
+}
+@font-face {
+  font-family: "HumanSans";
+  font-weight: 700;
+  font-style: oblique;
+  font-display: swap;
+  src: url("./HumanSans-BoldOblique-4D325T4F.otf") format("opentype");
+}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/assets/fonts/human-sans-font.css"],"sourcesContent":["@font-face {\n  font-family: 'HumanSans';\n  font-weight: 200;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-ExtraLight.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 300;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-Light.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 400;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-Regular.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 500;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-Medium.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 700;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-Bold.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 900;\n  font-style: normal;\n  font-display: swap;\n  src: url('./HumanSans-Black.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 200;\n  font-style: oblique;\n  font-display: swap;\n  src: url('./HumanSans-ExtraLightOblique.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 300;\n  font-style: oblique;\n  font-display: swap;\n  src: url('./HumanSans-LightOblique.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 400;\n  font-style: oblique;\n  font-display: swap;\n  src: url('./HumanSans-RegularOblique.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 500;\n  font-style: oblique;\n  font-display: swap;\n  src: url('./HumanSans-MediumOblique.otf') format('opentype');\n}\n\n@font-face {\n  font-family: 'HumanSans';\n  font-weight: 700;\n  font-style: oblique;\n  font-display: swap;\n  src: url('./HumanSans-BoldOblique.otf') format('opentype');\n}\n\n"],"mappings":";AAAA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,2CAAkC,OAAO;AAChD;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,sCAA6B,OAAO;AAC3C;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,wCAA+B,OAAO;AAC7C;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,uCAA8B,OAAO;AAC5C;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,qCAA4B,OAAO;AAC1C;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,sCAA6B,OAAO;AAC3C;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,kDAAyC,OAAO;AACvD;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,6CAAoC,OAAO;AAClD;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,+CAAsC,OAAO;AACpD;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,8CAAqC,OAAO;AACnD;AAEA;AACE,eAAa;AACb,eAAa;AACb,cAAY;AACZ,gBAAc;AACd,OAAK,4CAAmC,OAAO;AACjD;","names":[]}