diff --git a/.cursor/INDEX.md b/.cursor/INDEX.md new file mode 100644 index 000000000..2745c8b9c --- /dev/null +++ b/.cursor/INDEX.md @@ -0,0 +1,254 @@ +# Documentation Index + +## 📚 Complete Documentation Structure + +This repository now has comprehensive Cursor AI documentation organized in the `.cursor/` directory. + +### 🎯 Entry Point +- **`.cursorrules`** (root) - Main entry point for Cursor AI, points to all detailed docs + +### 📖 Core Documentation Files + +#### Getting Started (2 files) +1. **`overview.md`** - Project overview, tech stack, repository structure +2. **`setup.md`** - Installation, prerequisites, environment setup + +#### Development Guides (3 files) +3. **`development-workflow.md`** - Daily development, building, debugging +4. **`component-patterns.md`** - Creating components, file structure, design patterns +5. **`state-management.md`** - MobX store patterns, reactive state management + +#### Testing Guides (2 files) +6. **`unit-testing.md`** - Jest unit testing with React Testing Library +7. **`e2e-testing.md`** - Playwright E2E testing, multi-user sessions + +#### Technical References (2 files) +8. **`build-and-webpack.md`** - Webpack config, build system, loaders +9. **`code-standards.md`** - TypeScript, React, styling, git conventions + +#### Quick References (2 files) +10. **`commands-reference.md`** - All commands in one place +11. **`troubleshooting.md`** - Common issues and solutions + +#### Meta (2 files) +12. **`README.md`** - Documentation structure and how to use it +13. **`INDEX.md`** - This file - complete overview + +--- + +## 📊 Documentation Statistics + +- **Total Files**: 13 markdown files +- **Total Lines**: ~5,500+ lines of documentation +- **Coverage**: Complete coverage of development workflow, testing, and patterns + +### By Category: +- Getting Started: 2 files +- Development: 3 files +- Testing: 2 files +- Technical: 2 files +- Reference: 2 files +- Meta: 2 files + +--- + +## 🚀 Quick Start for New Team Members + +### Day 1: Setup +1. Read `.cursorrules` (2 min) +2. Read `.cursor/overview.md` (5 min) +3. Follow `.cursor/setup.md` (15 min) +4. Keep `.cursor/commands-reference.md` handy + +### Day 2-5: Learning +5. Study `.cursor/component-patterns.md` when creating components +6. Reference `.cursor/state-management.md` when working with store +7. Read `.cursor/development-workflow.md` for daily tasks + +### Ongoing: Reference +8. Use `.cursor/commands-reference.md` for quick lookups +9. Check `.cursor/troubleshooting.md` when stuck +10. Follow `.cursor/code-standards.md` for consistency + +--- + +## 📋 What Each File Contains + +### `.cursorrules` +- Project overview +- Quick reference for Cursor AI +- Pointers to detailed documentation +- Common pitfalls and best practices + +### Overview & Setup +- **overview.md**: Architecture, packages, tech stack, structure +- **setup.md**: Prerequisites, installation, environment, verification + +### Development +- **development-workflow.md**: Build commands, development flow, debugging +- **component-patterns.md**: File structure, component code, exports, examples +- **state-management.md**: MobX patterns, store singleton, observers + +### Testing +- **unit-testing.md**: Jest setup, React Testing Library, mocking, patterns +- **e2e-testing.md**: Playwright config, test utilities, multi-user testing + +### Technical +- **build-and-webpack.md**: Webpack config, loaders, plugins, optimization +- **code-standards.md**: TypeScript, React, styling, git commit conventions + +### Reference +- **commands-reference.md**: Every command you need, organized by task +- **troubleshooting.md**: Common issues with step-by-step solutions + +### Meta +- **README.md**: How to use the documentation, contribution guidelines +- **INDEX.md**: This file - complete overview + +--- + +## �� Documentation Features + +### ✅ What's Included +- [x] Complete project setup instructions +- [x] Component creation patterns with examples +- [x] State management with MobX +- [x] Unit testing patterns and examples +- [x] E2E testing with Playwright +- [x] Build system and webpack configuration +- [x] Code standards and conventions +- [x] Quick command reference +- [x] Comprehensive troubleshooting guide +- [x] Best practices and common pitfalls + +### 🎨 Documentation Style +- Clear headings and structure +- Code examples with syntax highlighting +- ✅/❌ do's and don'ts +- Step-by-step instructions +- Common issues and solutions +- Cross-references between docs + +--- + +## 🔍 How to Find Information + +### By Topic: +- **Setup & Installation** → `setup.md` +- **Daily Development** → `development-workflow.md`, `commands-reference.md` +- **Creating Components** → `component-patterns.md` +- **Working with Store** → `state-management.md` +- **Writing Tests** → `unit-testing.md`, `e2e-testing.md` +- **Build Issues** → `build-and-webpack.md`, `troubleshooting.md` +- **Code Style** → `code-standards.md` +- **Stuck/Debugging** → `troubleshooting.md` + +### By Task: +- **"I need to create a new component"** → `component-patterns.md` +- **"Build is failing"** → `troubleshooting.md` → `build-and-webpack.md` +- **"How do I run tests?"** → `commands-reference.md` → `unit-testing.md` +- **"What's the store pattern?"** → `state-management.md` +- **"How do I start developing?"** → `setup.md` → `development-workflow.md` + +--- + +## 💡 Tips for Using This Documentation + +### For Cursor AI: +1. **Start with `.cursorrules`** - Understand project basics +2. **Reference specific docs** - Point users to detailed files +3. **Follow patterns** - Use examples as templates +4. **Check standards** - Ensure suggestions match conventions + +### For Developers: +1. **Bookmark in browser** - Keep docs open in tabs +2. **Search across files** - Use IDE search (Cmd/Ctrl+Shift+F) +3. **Keep updated** - Add new patterns as they emerge +4. **Share knowledge** - Update docs when you solve issues + +### For Team Leads: +1. **Onboarding** - Share with new team members +2. **Code reviews** - Reference standards from docs +3. **Updates** - Keep docs in sync with code changes +4. **Improvements** - Add new sections as needed + +--- + +## 🔄 Keeping Documentation Updated + +### When Code Changes: +- Update relevant `.cursor/*.md` files +- Add new patterns to `component-patterns.md` +- Document new issues in `troubleshooting.md` +- Update commands in `commands-reference.md` + +### When Dependencies Update: +- Update versions in `overview.md` +- Verify setup instructions in `setup.md` +- Test and update `build-and-webpack.md` + +### When Processes Change: +- Update `development-workflow.md` +- Revise testing docs if frameworks change +- Update `.cursorrules` if structure changes + +--- + +## 📈 Documentation Coverage + +### Fully Documented ✅ +- Project setup and installation +- Development workflow and commands +- Component creation patterns +- State management with MobX +- Unit testing with Jest +- E2E testing with Playwright +- Build system and webpack +- Code standards and conventions +- Common troubleshooting + +### Future Additions 📝 +- CI/CD pipeline details +- Release and deployment process +- Performance optimization guide +- API integration patterns +- Migration guides for major updates +- Architecture decision records (ADRs) + +--- + +## 🤝 Contributing to Documentation + +Found something missing or incorrect? + +1. Edit the relevant `.cursor/*.md` file +2. Follow existing format and style +3. Add examples and code snippets +4. Update cross-references if needed +5. Test commands and examples +6. Commit with descriptive message + +--- + +## 📞 Support + +### Resources: +- **GitHub**: https://github.com/webex/widgets +- **NPM**: https://www.npmjs.com/package/@webex/cc-widgets +- **Issues**: https://github.com/webex/widgets/issues +- **Contributing**: `packages/contact-center/CONTRIBUTING.md` + +### When Stuck: +1. Check `.cursor/troubleshooting.md` +2. Search documentation with IDE +3. Review test files for examples +4. Ask team lead +5. Create GitHub issue + +--- + +**Documentation Created**: November 2025 +**Current Version**: 1.28.0-ccwidgets.122 +**Maintained By**: Webex Contact Center Widgets Team + +**Status**: ✅ Complete and ready to use! diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 000000000..47515f832 --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,161 @@ +# Cursor AI Documentation + +This directory contains comprehensive documentation for the Webex Contact Center Widgets repository, specifically organized to help Cursor AI (and developers) understand and work with the codebase effectively. + +## 📂 Documentation Files + +| File | Purpose | When to Use | +| ---------------------------- | ---------------------------------------------- | ------------------------------------------------- | +| **overview.md** | Project overview, architecture, tech stack | First time setup, understanding project structure | +| **setup.md** | Installation, prerequisites, environment setup | Setting up dev environment for first time | +| **development-workflow.md** | Daily development commands, build process | Daily development, making changes | +| **component-patterns.md** | Component structure, design patterns | Creating new components, following conventions | +| **state-management.md** | MobX store patterns, reactive state | Working with store, state updates | +| **unit-testing.md** | Jest & React Testing Library patterns | Writing unit tests | +| **e2e-testing.md** | Playwright E2E testing | Writing end-to-end tests | +| **build-and-webpack.md** | Webpack config, build system | Build issues, understanding bundling | +| **code-standards.md** | TypeScript, React, style conventions | Code review, maintaining consistency | +| **commands-reference.md** | Quick command cheatsheet | Quick lookup for commands | +| **troubleshooting.md** | Common issues and solutions | Debugging problems | +| **WIDGET-EXPOSURE-GUIDE.md** | Widget exposure & testing workflow | Exposing widgets, testing in sample app | + +## 🎯 How to Use This Documentation + +### For Cursor AI + +The `.cursorrules` file in the repository root points to these documentation files. When assisting with code: + +1. **Reference appropriate docs** - Direct users to specific `.cursor/*.md` files +2. **Follow patterns** - Use examples from documentation as templates +3. **Check standards** - Ensure suggestions match `code-standards.md` +4. **Understand context** - Read relevant docs before suggesting solutions + +### For Developers + +1. **Start with** `overview.md` - Understand the project +2. **Follow** `setup.md` - Get environment running +3. **Reference** topic-specific files as needed +4. **Use** `commands-reference.md` for quick lookups + +## 📋 Documentation Coverage + +### Complete Coverage ✅ + +- [x] Project overview and structure +- [x] Initial setup and installation +- [x] Component creation patterns +- [x] State management with MobX +- [x] Unit testing with Jest +- [x] E2E testing with Playwright +- [x] Build system and Webpack +- [x] Development workflow +- [x] Code standards + +### To Be Added 📝 + +- [ ] Troubleshooting guide (common issues) +- [ ] Commands quick reference +- [ ] API integration patterns +- [ ] Performance optimization +- [ ] CI/CD pipeline +- [ ] Release process +- [ ] Migration guides + +## 🔄 Keeping Documentation Updated + +### When to Update: + +- New features added +- Build process changes +- Dependencies updated +- New patterns established +- Common issues discovered + +### How to Update: + +1. Edit relevant `.cursor/*.md` file +2. Keep examples accurate and tested +3. Update `.cursorrules` if structure changes +4. Maintain consistency across files + +## 🤝 Contributing to Documentation + +When adding or updating documentation: + +### Structure: + +- Use clear headings (H1-H4) +- Include code examples +- Add ✅/❌ do's and don'ts +- Provide context and explanations + +### Style: + +- Be concise but complete +- Use code blocks with syntax highlighting +- Include command examples with comments +- Link to related sections + +### Format: + +````markdown +## Section Title + +Brief introduction explaining what this covers. + +### Subsection + +Explanation with examples: + +```typescript +// Example code with comments +const example = 'like this'; +``` +```` + +**Key points:** + +- Point 1 +- Point 2 + +``` + +## 📖 External Resources + +- [Webex Widgets GitHub](https://github.com/webex/widgets) +- [Contributing Guide](../packages/contact-center/CONTRIBUTING.md) +- [NPM Package](https://www.npmjs.com/package/@webex/cc-widgets) +- [Momentum Design](https://momentum-design.github.io/momentum-design/) +- [MobX Documentation](https://mobx.js.org/) +- [Playwright Docs](https://playwright.dev/) + +## 💡 Tips for Using These Docs + +### Quick Navigation +Use your IDE's file search to quickly jump between documentation files: +- Cmd/Ctrl + P → type `.cursor/filename` + +### Search Within Docs +Use your IDE's search to find specific topics across all docs: +- Cmd/Ctrl + Shift + F → search `.cursor/` directory + +### Keep Docs Open +Keep frequently referenced docs open in tabs: +- `component-patterns.md` - when creating components +- `development-workflow.md` - for daily commands +- `commands-reference.md` - for quick lookups + +## 🆘 Getting Help + +If documentation is unclear or incomplete: +1. Check related sections in other docs +2. Look at actual code examples in `packages/contact-center/` +3. Review tests for usage patterns +4. Ask team lead or create GitHub issue + +--- + +**Maintained by**: Webex Contact Center Widgets Team +**Last Updated**: November 2025 + +``` diff --git a/.cursor/WIDGET-EXPOSURE-GUIDE.md b/.cursor/WIDGET-EXPOSURE-GUIDE.md new file mode 100644 index 000000000..503b6ef03 --- /dev/null +++ b/.cursor/WIDGET-EXPOSURE-GUIDE.md @@ -0,0 +1,433 @@ +# Widget Exposure & Testing Guide + +## Overview + +This guide explains the **CRITICAL** process of exposing widgets through the `@webex/cc-widgets` package and testing them in the sample app. + +## 🚨 Why This Matters + +1. **Consumers** install ONLY `@webex/cc-widgets` - not individual widget packages +2. **cc-widgets** is the single entry point that re-exports all widgets +3. **Sample app** is the mandatory testing ground before publishing +4. **Both React AND Web Components** must be exposed + +## The Widget Flow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Step 1: Create Widget in Individual Package │ +│ @webex/cc-my-widget/src/my-widget.tsx │ +└─────────────────────────┬───────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 2: Export from Widget Package │ +│ @webex/cc-my-widget/src/index.ts │ +│ export { MyWidget } │ +└─────────────────────────┬───────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 3A: Re-Export in cc-widgets (React) │ +│ @webex/cc-widgets/src/index.ts │ +│ import { MyWidget } from '@webex/cc-my-widget' │ +│ export { MyWidget } │ +└─────────────────────────┬───────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Step 3B: Wrap as Web Component │ +│ @webex/cc-widgets/src/wc.ts │ +│ const WebMyWidget = r2wc(MyWidget, { props: {...} }) │ +└─────────────────────────┬───────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 4: Build cc-widgets Package │ +│ yarn workspace @webex/cc-widgets run build:src │ +└─────────────────────────┬───────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 5: Test in Sample React App │ +│ widgets-samples/cc/samples-cc-react-app/src/App.tsx │ +│ import { MyWidget } from '@webex/cc-widgets' │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Step-by-Step: Exposing a Widget + +### 1. Create Your Widget Package + +```bash +cd packages/contact-center +mkdir my-widget +cd my-widget +``` + +Create basic structure: + +``` +my-widget/ +├── src/ +│ ├── my-widget.tsx +│ ├── my-widget.types.ts +│ ├── my-widget.utils.ts +│ ├── my-widget.style.scss +│ └── index.ts +├── package.json +├── webpack.config.js +└── tsconfig.json +``` + +### 2. Implement Widget + +```typescript +// my-widget/src/my-widget.tsx +import React from 'react'; +import { withMetrics } from '@webex/cc-ui-logging'; +import { MyWidgetProps } from './my-widget.types'; +import './my-widget.style.scss'; + +const MyWidgetComponent: React.FC = (props) => { + const { title, onAction, logger } = props; + + return ( +
+

{title}

+ +
+ ); +}; + +export const MyWidget = withMetrics(MyWidgetComponent); +``` + +```typescript +// my-widget/src/my-widget.types.ts +import {ILogger} from '@webex/cc-store'; + +export interface MyWidgetProps { + title: string; + onAction?: () => void; + logger?: ILogger; +} +``` + +```typescript +// my-widget/src/index.ts +export {MyWidget} from './my-widget'; +export type {MyWidgetProps} from './my-widget.types'; +``` + +### 3. Build Widget Package + +```bash +yarn workspace @webex/cc-my-widget run build:src +``` + +### 4. Expose Through cc-widgets (CRITICAL!) + +#### 4A: Add React Component Export + +```typescript +// packages/contact-center/cc-widgets/src/index.ts +import {StationLogin} from '@webex/cc-station-login'; +import {UserState} from '@webex/cc-user-state'; +import {IncomingTask, TaskList, CallControl, CallControlCAD, OutdialCall} from '@webex/cc-task'; +import {MyWidget} from '@webex/cc-my-widget'; // ← ADD THIS +import store from '@webex/cc-store'; +import '@momentum-ui/core/css/momentum-ui.min.css'; + +export { + StationLogin, + UserState, + IncomingTask, + CallControl, + CallControlCAD, + TaskList, + OutdialCall, + MyWidget, // ← ADD THIS + store, +}; +``` + +#### 4B: Add Web Component + +```typescript +// packages/contact-center/cc-widgets/src/wc.ts +import r2wc from '@r2wc/react-to-web-component'; +import {MyWidget} from '@webex/cc-my-widget'; // ← ADD THIS + +// Wrap React component +const WebMyWidget = r2wc(MyWidget, { + props: { + title: 'string', + onAction: 'function', + }, +}); + +// Add to components array +const components = [ + {name: 'widget-cc-user-state', component: WebUserState}, + {name: 'widget-cc-station-login', component: WebStationLogin}, + {name: 'widget-cc-incoming-task', component: WebIncomingTask}, + {name: 'widget-cc-task-list', component: WebTaskList}, + {name: 'widget-cc-call-control', component: WebCallControl}, + {name: 'widget-cc-outdial-call', component: WebOutdialCall}, + {name: 'widget-cc-call-control-cad', component: WebCallControlCAD}, + {name: 'widget-cc-my-widget', component: WebMyWidget}, // ← ADD THIS +]; + +// Auto-register all web components +components.forEach(({name, component}) => { + if (!customElements.get(name)) { + customElements.define(name, component); + } +}); + +export {store}; +``` + +**Prop Type Mapping**: + +- `'string'` - String values +- `'number'` - Number values +- `'boolean'` - Boolean values +- `'json'` - Objects and arrays (serialized as JSON) +- `'function'` - Callback functions + +### 5. Build cc-widgets Package + +```bash +yarn workspace @webex/cc-widgets run build:src +``` + +This step is **CRITICAL** - consumers get widgets from the built `cc-widgets` package! + +## Step-by-Step: Testing in Sample App + +### 1. Import Widget in Sample App + +```typescript +// widgets-samples/cc/samples-cc-react-app/src/App.tsx +import { + StationLogin, + UserState, + IncomingTask, + TaskList, + CallControl, + CallControlCAD, + store, + OutdialCall, + MyWidget, // ← ADD THIS (import from cc-widgets!) +} from '@webex/cc-widgets'; +``` + +### 2. Add Widget Toggle + +```typescript +// Add to defaultWidgets object +const defaultWidgets = { + stationLogin: true, + userState: true, + incomingTask: true, + taskList: true, + callControl: true, + callControlCAD: true, + outdialCall: true, + myWidget: true, // ← ADD THIS +}; +``` + +### 3. Add Widget Toggle Checkbox + +```typescript +// In the App component render, add checkbox in sidebar +
+ {/* ... existing checkboxes ... */} + + handleWidgetToggle('myWidget', e.target.checked)} + > + My Widget + +
+``` + +### 4. Render Widget + +```typescript +// In the main content area + + + {/* ... other widgets ... */} + + {selectedWidgets.myWidget && ( +
+ My Widget + { + console.log('Widget action triggered'); + }} + /> +
+ )} + + +``` + +### 5. Run and Test + +```bash +# Start sample app +yarn samples:serve-react + +# Open http://localhost:3000 +``` + +**Testing Checklist**: + +- ✅ Widget appears when checkbox is enabled +- ✅ Widget disappears when checkbox is disabled +- ✅ All widget functionality works +- ✅ No console errors +- ✅ Props are passed correctly +- ✅ Store integration works (if applicable) +- ✅ Events/callbacks work +- ✅ Styling is correct +- ✅ Works in light and dark themes + +## Web Component Testing (Optional) + +```html + + + + +``` + +```bash +yarn samples:serve-wc +``` + +## Common Mistakes to Avoid + +### ❌ Don't Do This: + +1. **Importing directly from widget package in sample app** + + ```typescript + // ❌ WRONG + import {MyWidget} from '@webex/cc-my-widget'; + + // ✅ CORRECT + import {MyWidget} from '@webex/cc-widgets'; + ``` + +2. **Forgetting to build cc-widgets after changes** + + ```bash + # ❌ WRONG - only building widget package + yarn workspace @webex/cc-my-widget run build:src + + # ✅ CORRECT - also build cc-widgets + yarn workspace @webex/cc-my-widget run build:src + yarn workspace @webex/cc-widgets run build:src + ``` + +3. **Not adding to both index.ts AND wc.ts** + + ```typescript + // ❌ WRONG - only added to index.ts + // Missing from wc.ts + + // ✅ CORRECT - added to BOTH files + // index.ts: export { MyWidget } + // wc.ts: const WebMyWidget = r2wc(MyWidget, {...}) + ``` + +4. **Not testing in sample app** + + ```bash + # ❌ WRONG - pushing without testing + git push + + # ✅ CORRECT - always test first + yarn samples:serve-react + # Verify widget works + git push + ``` + +## Build Order Reminder + +When making changes to widgets: + +```bash +# 1. Build store (if changed) +yarn workspace @webex/cc-store run build:src + +# 2. Build ui-logging (if changed) +yarn workspace @webex/cc-ui-logging run build:src + +# 3. Build components (if changed) +yarn workspace @webex/cc-components run build:src + +# 4. Build your widget package +yarn workspace @webex/cc-my-widget run build:src + +# 5. Build cc-widgets (CRITICAL!) +yarn workspace @webex/cc-widgets run build:src + +# 6. Test in sample app +yarn samples:serve-react +``` + +## Publishing Flow + +When widget is ready: + +1. ✅ Widget built in its package +2. ✅ Exposed in cc-widgets (index.ts + wc.ts) +3. ✅ cc-widgets rebuilt +4. ✅ Tested in sample app (React) +5. ✅ Tested as web component (optional) +6. ✅ Unit tests added/passing +7. ✅ E2E tests added (if applicable) +8. ✅ Documentation updated +9. ✅ PR created and reviewed +10. ✅ Merged to main +11. ✅ Semantic release publishes to npm + +## Quick Reference + +### Adding New Widget Checklist + +- [ ] Create widget package structure +- [ ] Implement widget component +- [ ] Export from widget package (`src/index.ts`) +- [ ] Build widget package +- [ ] Add to `cc-widgets/src/index.ts` (React export) +- [ ] Add to `cc-widgets/src/wc.ts` (Web Component) +- [ ] Build cc-widgets package +- [ ] Import in sample app from `@webex/cc-widgets` +- [ ] Add toggle to `defaultWidgets` +- [ ] Add checkbox UI +- [ ] Add render logic +- [ ] Test in `yarn samples:serve-react` +- [ ] Verify all functionality +- [ ] Add unit tests +- [ ] Add E2E tests (if needed) +- [ ] Create PR + +## Help & Support + +- **Build issues**: See `.cursor/troubleshooting.md` +- **Component patterns**: See `.cursor/component-patterns.md` +- **Development workflow**: See `.cursor/development-workflow.md` +- **Testing**: See `.cursor/unit-testing.md` and `.cursor/e2e-testing.md` + +--- + +**Remember**: If consumers can't import it from `@webex/cc-widgets`, it doesn't exist! Always expose and test! diff --git a/.cursor/build-and-webpack.md b/.cursor/build-and-webpack.md new file mode 100644 index 000000000..5f5a8ae76 --- /dev/null +++ b/.cursor/build-and-webpack.md @@ -0,0 +1,633 @@ +# Build System & Webpack Configuration + +## Build System Overview + +The repository uses **Webpack 5** with **TypeScript** and **Babel** for building packages. + +- **Bundler**: Webpack 5.94.0+ +- **TypeScript**: ts-loader for compilation +- **Babel**: babel-loader for transpilation +- **Styles**: sass-loader + css-loader + style-loader +- **Output**: UMD bundles for browser and Node.js + +## Build Targets + +Each package generates: + +1. **React Components Bundle** (`dist/index.js`) + + - Entry: `src/index.ts` + - Exports all React components + - Type definitions: `dist/types/index.d.ts` + +2. **Web Components Bundle** (`dist/wc.js`) + + - Entry: `src/wc.ts` + - Web Components wrapped with r2wc + - Type definitions: `dist/types/wc.d.ts` + +3. **Type Declarations** (`dist/types/`) + - Generated TypeScript declaration files + - Mirrors source structure + +## Webpack Configuration + +### Base Configuration (`webpack.config.js`) + +```javascript +const webpack = require('webpack'); +const path = require('path'); + +module.exports = { + mode: process.env.NODE_ENV || 'development', + + entry: { + index: './src/index.ts', + wc: './src/wc.ts', + }, + + output: { + path: path.resolve(__dirname, 'dist'), + filename: '[name].js', + library: { + type: 'umd', + name: 'WebexCCWidgets', + }, + globalObject: 'this', + }, + + resolve: { + extensions: ['.ts', '.tsx', '.js', '.jsx', '.scss'], + fallback: { + fs: false, + process: require.resolve('process/browser'), + crypto: require.resolve('crypto-browserify'), + stream: require.resolve('stream-browserify'), + // ... more polyfills + }, + }, + + externals: { + react: 'react', + 'react-dom': 'react-dom', + '@webex/cc-store': '@webex/cc-store', + '@momentum-ui/react-collaboration': '@momentum-ui/react-collaboration', + }, + + module: { + rules: [ + // TypeScript + { + test: /\.(ts|tsx)$/, + exclude: /node_modules/, + use: 'ts-loader', + }, + // JavaScript (Babel) + { + test: /\.(js|jsx)$/, + exclude: /node_modules/, + use: 'babel-loader', + }, + // SCSS + { + test: /\.scss$/, + use: ['style-loader', 'css-loader', 'sass-loader'], + exclude: /node_modules/, + }, + // CSS + { + test: /\.css$/, + use: ['style-loader', 'css-loader'], + }, + // Assets (fonts, images) + { + test: /\.(woff|woff2|eot|ttf|otf|png|jpg|svg)$/, + type: 'asset/resource', + }, + ], + }, + + plugins: [ + new webpack.ProvidePlugin({ + process: 'process/browser', + }), + ], + + stats: { + warningsFilter: [/sass-loader/], // Suppress Sass deprecation warnings + }, +}; +``` + +### Key Configuration Sections + +#### Entry Points + +```javascript +entry: { + index: './src/index.ts', // React components + wc: './src/wc.ts', // Web components +} +``` + +#### Output Configuration + +```javascript +output: { + path: path.resolve(__dirname, 'dist'), + filename: '[name].js', + library: { + type: 'umd', // Universal Module Definition + name: 'WebexCCWidgets', + }, + globalObject: 'this', +} +``` + +**Output Files**: + +- `dist/index.js` - React components bundle +- `dist/wc.js` - Web components bundle + +#### Resolve Configuration + +```javascript +resolve: { + extensions: ['.ts', '.tsx', '.js', '.jsx', '.scss'], + fallback: { + // Browser polyfills for Node.js modules + crypto: require.resolve('crypto-browserify'), + stream: require.resolve('stream-browserify'), + process: require.resolve('process/browser'), + os: require.resolve('os-browserify/browser'), + vm: require.resolve('vm-browserify'), + util: require.resolve('util/'), + url: require.resolve('url/'), + querystring: require.resolve('querystring-es3'), + }, +} +``` + +#### Externals (Peer Dependencies) + +```javascript +externals: { + 'react': 'react', + 'react-dom': 'react-dom', + '@webex/cc-store': '@webex/cc-store', + '@momentum-ui/react-collaboration': '@momentum-ui/react-collaboration', +} +``` + +These are NOT bundled - consumers must provide them. + +## Loaders + +### TypeScript Loader + +```javascript +{ + test: /\.(ts|tsx)$/, + exclude: /node_modules/, + use: 'ts-loader', +} +``` + +Compiles TypeScript to JavaScript using `tsconfig.json`. + +### Babel Loader + +```javascript +{ + test: /\.(js|jsx)$/, + exclude: /node_modules/, + use: 'babel-loader', +} +``` + +Transpiles modern JavaScript/JSX using `babel.config.js`. + +### SCSS Loader Chain + +```javascript +{ + test: /\.scss$/, + use: [ + 'style-loader', // 3. Injects styles into DOM + 'css-loader', // 2. Turns CSS into CommonJS + 'sass-loader', // 1. Compiles Sass to CSS + ], +} +``` + +**Flow**: SCSS → CSS → JavaScript → DOM `