impact-ui 3.7.25 → 4.0.0-alpha.10

package/MIGRATION_GUIDE.md

@@ -0,0 +1,328 @@
+# Migrating to impact-ui v4.0
+
+## Private npm packages `@impactsmartsuite/*` (v5.0+)
+
+The UI library and MCP server are published to [npm](https://www.npmjs.com/) under the **impactsmartsuite** organization as **private** scoped packages:
+
+- `@impactsmartsuite/impact-ui`
+- `@impactsmartsuite/impact-ui-mcp-server`
+
+Your npm user (or CI token) must have permission to install and publish these packages on that org. Authenticate against the default registry (`https://registry.npmjs.org/`):
+
+```bash
+npm login
+```
+
+For automation, use a granular access token with **read/publish** as appropriate and configure `~/.npmrc` or environment-based auth (for example `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`). Do not commit tokens.
+
+**Install:**
+
+```bash
+npm install @impactsmartsuite/impact-ui
+```
+
+**Imports** (same subpath style as before, with the scoped package name):
+
+```tsx
+import { Button, Badge } from '@impactsmartsuite/impact-ui';
+import { Button } from '@impactsmartsuite/impact-ui/Button';
+```
+
+---
+
+## Quick Start: Tree Shaking Migration (2 minutes)
+
+Version 4.0 introduces **tree shaking support** for significantly smaller bundle sizes. Follow these steps to migrate:
+
+### Step 1: Update the Package
+
+```bash
+npm install @impactsmartsuite/impact-ui@latest
+```
+
+### Step 2: Run Automatic Migration
+
+```bash
+npx impact-ui-migrate ./src
+```
+
+This will automatically transform all your barrel imports to direct imports:
+
+**Before:**
+```tsx
+import { Button, Input, Card, Alert } from '@impactsmartsuite/impact-ui';
+```
+
+**After:**
+```tsx
+import { Button } from '@impactsmartsuite/impact-ui/Button';
+import { Input } from '@impactsmartsuite/impact-ui/Input';
+import { Card } from '@impactsmartsuite/impact-ui/Card';
+import { Alert } from '@impactsmartsuite/impact-ui/Alert';
+```
+
+### Step 3: Verify Changes
+
+```bash
+git diff          # Review the changes
+npm test          # Run your tests
+npm run build     # Verify the build works
+```
+
+### Step 4: (Recommended) Add ESLint Rule
+
+Prevent future barrel imports by adding the ESLint rule:
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['impact-ui'],
+  rules: {
+    'impact-ui/no-barrel-import': 'error'
+  }
+};
+
+// Or use the recommended config
+module.exports = {
+  extends: ['plugin:impact-ui/recommended']
+};
+```
+
+Then run auto-fix for any violations:
+
+```bash
+npx eslint --fix ./src
+```
+
+---
+
+## Migration CLI Options
+
+```bash
+# Basic usage
+npx impact-ui-migrate ./src
+
+# Preview changes without applying (dry run)
+npx impact-ui-migrate ./src --dry
+
+# Migrate only TypeScript files
+npx impact-ui-migrate ./src --extensions tsx,ts
+
+# Migrate a specific file
+npx impact-ui-migrate ./src/components/MyComponent.tsx
+
+# Show detailed output
+npx impact-ui-migrate ./src --verbose
+
+# Show help
+npx impact-ui-migrate --help
+```
+
+---
+
+## ESLint Plugin Configuration
+
+### Basic Setup
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['impact-ui'],
+  rules: {
+    'impact-ui/no-barrel-import': 'error'
+  }
+};
+```
+
+### Using Recommended Config
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: ['plugin:impact-ui/recommended']
+};
+```
+
+### Available Configs
+
+| Config | Description |
+|--------|-------------|
+| `plugin:impact-ui/recommended` | Enforces direct imports as errors |
+| `plugin:impact-ui/warning` | Shows warnings (for gradual migration) |
+| `plugin:impact-ui/strict` | Strict mode with no exceptions |
+
+### ESLint Flat Config (eslint.config.js)
+
+```javascript
+// eslint.config.js
+import impactUI from 'impact-ui/eslint-plugin';
+
+export default [
+  impactUI.configs['flat/recommended'],
+  // ... your other configs
+];
+```
+
+### Rule Options
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  rules: {
+    'impact-ui/no-barrel-import': ['error', {
+      // Ignore specific imports (keep them as barrel imports)
+      ignoreImports: ['someUtilFunction'],
+      
+      // Add custom component mappings
+      additionalComponents: {
+        'CustomComponent': 'impact-ui/CustomComponent'
+      }
+    }]
+  }
+};
+```
+
+---
+
+## Bundle Size Impact
+
+| Import Style | Bundle Size | Tree Shaking |
+|--------------|-------------|--------------|
+| Barrel import (`from 'impact-ui'`) | ~450KB | No |
+| Direct import (`from 'impact-ui/Button'`) | ~15-50KB* | Yes |
+
+*Actual size depends on components used
+
+---
+
+## TypeScript Support
+
+impact-ui now ships with TypeScript definitions. No changes required for JS users.
+
+### For TypeScript Users:
+
+```typescript
+import { Button, ButtonProps } from 'impact-ui/Button';
+
+const MyButton: React.FC = () => {
+  const handleClick: ButtonProps['onClick'] = (e) => {
+    // Fully typed event
+  };
+  
+  return <Button onClick={handleClick}>Click</Button>;
+};
+```
+
+### TypeScript Configuration
+
+Ensure your `tsconfig.json` has the correct module resolution:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"  // or "node16" / "nodenext"
+  }
+}
+```
+
+---
+
+## Breaking Changes
+
+### Removed
+- PropTypes (replaced with TypeScript interfaces)
+
+### Changed
+- Build output now uses Vite (bundle size reduced ~20%)
+- CSS import path remains the same: `import 'impact-ui/styles'`
+- Package now exports ESM by default with CJS fallback
+- Module type is now "module" (ESM)
+- **Recommended**: Use direct imports for tree shaking
+
+---
+
+## Accessibility Improvements
+
+All components now meet WCAG 2.1 Level AA standards. Components include:
+- Proper ARIA attributes
+- Keyboard navigation support
+- Focus management
+- Screen reader compatibility
+
+---
+
+## Available Components
+
+All components support direct imports:
+
+```tsx
+import { Accordion } from 'impact-ui/Accordion';
+import { Alert } from 'impact-ui/Alert';
+import { Avatar } from 'impact-ui/Avatar';
+import { Badge } from 'impact-ui/Badge';
+import { Button } from 'impact-ui/Button';
+import { Card } from 'impact-ui/Card';
+import { Checkbox } from 'impact-ui/Checkbox';
+import { Chips } from 'impact-ui/Chips';
+import { Input } from 'impact-ui/Input';
+import { Switch } from 'impact-ui/Switch';
+import { Tag } from 'impact-ui/Tag';
+import { Tooltip } from 'impact-ui/Tooltip';
+
+// Utils and types
+import { /* utils */ } from 'impact-ui/utils';
+import type { /* types */ } from 'impact-ui/types';
+
+// Styles (import once in your app entry)
+import 'impact-ui/styles';
+```
+
+---
+
+## Troubleshooting
+
+### Unknown export warning during migration
+
+If you see warnings about unknown exports:
+1. Check the export exists in your version of impact-ui
+2. Verify the spelling is correct
+3. The unknown exports will remain as barrel imports
+
+### ESLint rule not working
+
+1. Ensure the plugin is installed: `npm install @impactsmartsuite/impact-ui`
+2. Restart your IDE/editor
+3. Check ESLint is configured correctly
+
+### TypeScript errors after migration
+
+Ensure your `tsconfig.json` has:
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### Build errors
+
+If you encounter build errors after migration:
+1. Clear your build cache: `rm -rf node_modules/.cache`
+2. Reinstall dependencies: `npm install`
+3. Try rebuilding: `npm run build`
+
+---
+
+## Compatibility
+
+- React 17.0.0 - 19.x
+- Node.js 16+
+- TypeScript 5.0+ (for TypeScript users)
+- ESLint 8.x or 9.x (for ESLint plugin)
+
+---
+
+## Support
+
+For issues or questions, please file an issue on the project repository.

package/README.md

@@ -1,34 +1,173 @@
-# impact-ui
+# @impactsmartsuite/impact-ui
 
-> Impact Analytics UI library
+Impact Analytics UI Component Library - A modern, accessible React component library built with TypeScript and Vite (private npm package).
 
-[![NPM](https://img.shields.io/npm/v/impact-ui.svg)](https://www.npmjs.com/package/impact-ui) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+## Features
 
-## Install
+- 🎨 **48+ Production-Ready Components** - Comprehensive UI component library
+- 🔒 **TypeScript First** - Full type safety with TypeScript definitions
+- ♿ **Accessibility** - WCAG 2.1 Level AA compliant
+- ⚡ **Fast** - Built with Vite for optimal performance
+- 🎭 **Storybook** - Interactive component documentation
+- 🧪 **Well Tested** - Unit tests with accessibility checks
+- 📦 **Tree Shakeable** - Import only what you need
+
+## Installation
 
 ```bash
-npm install impact-ui --save
+npm install @impactsmartsuite/impact-ui
 ```
 
 ## Usage
 
-```jsx
-import React from 'react'
-import { MyComponent } from 'impact-ui'
+### Basic Example
+
+```typescript
+import { Button } from '@impactsmartsuite/impact-ui';
+import '@impactsmartsuite/impact-ui/styles';
 
-const Example = () => {
-  return <MyComponent />
+function App() {
+  return (
+    <Button variant="primary" size="large">
+      Click Me
+    </Button>
+  );
 }
 ```
 
-## Documentation & Demo
+### TypeScript Support
+
+```typescript
+import { Button, type ButtonProps } from '@impactsmartsuite/impact-ui';
+
+const props: ButtonProps = {
+  variant: 'primary',
+  size: 'large',
+  onClick: (e) => console.log('Clicked!'),
+};
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 16+
+- npm or yarn
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run Storybook
+npm run storybook
+
+# Run tests
+npm run test
+
+# Run tests with UI
+npm run test:ui
+```
+
+### Scripts
+
+- `npm run dev` - Start Vite dev server
+- `npm run build` - Build library for production
+- `npm run build:lib` - Build library (alias)
+- `npm run preview` - Preview production build
+- `npm run storybook` - Start Storybook dev server
+- `npm run build:storybook` - Build Storybook static site
+- `npm run test` - Run tests with Vitest
+- `npm run test:ui` - Run tests with UI
+- `npm run test:storybook` - Run Storybook play tests (Vitest + Playwright)
+- `npm run playwright:install` - Install Chromium only (required for `test:storybook`)
+- `npm run lint` - Lint TypeScript files
+- `npm run lint:fix` - Fix linting errors
+- `npm run lint:a11y` - Check accessibility compliance
+- `npm run format` - Format code with Prettier
+- `npm run format:check` - Check code formatting
+- `npm run type-check` - Type check without emitting files
+
+### Storybook tests and Playwright
+
+To run Storybook play tests (`npm run test:storybook`), install Chromium first:
+
+```bash
+npm run playwright:install
+```
+
+If you see **"unable to get local issuer certificate"** (common on corporate networks with a custom CA):
+
+1. **Recommended:** Point Node at your CA bundle:  
+   `NODE_EXTRA_CA_CERTS=/path/to/your/ca-bundle.pem npm run playwright:install`
+2. **Last resort (insecure):** Disable TLS verification only for the install:  
+   `NODE_TLS_REJECT_UNAUTHORIZED=0 npm run playwright:install`
+
+## Project Structure
+
+```
+frontend/
+├── .storybook/          # Storybook configuration
+├── src/
+│   ├── components/      # UI components
+│   ├── styles/          # Global styles
+│   ├── test/            # Test utilities
+│   └── types/           # TypeScript type definitions
+├── dist/                # Build output
+├── tsconfig.json        # TypeScript configuration
+├── vite.config.ts       # Vite configuration
+└── vitest.config.ts     # Vitest configuration
+```
+
+## Contributing
 
-Explore our [Documentation and interactive Demo page](https://impact-ui-v3.iaproducts.ai/?path=/docs/getting-started--docs) to gain a comprehensive understanding of the various components available in our framework. This resource serves as a valuable guide for developers and users alike, detailing the features, functionalities, and best practices for utilizing the components effectively.
+1. Create a feature branch
+2. Make your changes
+3. Run tests: `npm run test`
+4. Run linting: `npm run lint`
+5. Format code: `npm run format`
+6. Type check: `npm run type-check`
+7. Submit a pull request
+
+### Code Quality
+
+All code must pass:
+- TypeScript compilation without errors
+- ESLint checks (including accessibility)
+- Prettier formatting
+- Unit tests with accessibility checks
+
+## Accessibility
+
+This library follows WCAG 2.1 Level AA standards. All components include:
+- Proper semantic HTML
+- ARIA attributes where needed
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+
+Run accessibility checks:
+```bash
+npm run lint:a11y
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
 
 ## License
 
-MIT © [](https://github.com/)
+MIT
+
+## Version
 
-## Keywords
+Current version: 4.0.0-alpha.1
 
-design-system react react-component impact-ui
+See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for upgrading from v3.x.

package/bin/migrate-image-paths.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function parseArgs(argv) {
+  const options = {
+    targetPath: './src',
+    reportPath: './IMAGE_MIGRATION_REPORT.md',
+    extensions: 'tsx,ts,jsx,js,mjs,cjs',
+    dry: false,
+    verbose: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--dry') options.dry = true;
+    else if (arg === '--verbose' || arg === '-v') options.verbose = true;
+    else if (arg === '--target' && argv[i + 1]) options.targetPath = argv[++i];
+    else if (arg.startsWith('--target=')) options.targetPath = arg.split('=')[1];
+    else if (arg === '--report' && argv[i + 1]) options.reportPath = argv[++i];
+    else if (arg.startsWith('--report=')) options.reportPath = arg.split('=')[1];
+    else if (arg === '--extensions' && argv[i + 1]) options.extensions = argv[++i];
+    else if (arg.startsWith('--extensions=')) options.extensions = arg.split('=')[1];
+    else if (!arg.startsWith('-')) options.targetPath = arg;
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`
+Usage:
+  node ./bin/migrate-image-paths.cjs [target] [options]
+
+Options:
+  --report <path>        Migration report path (default: ./IMAGE_MIGRATION_REPORT.md)
+  --extensions <list>    Comma-separated file extensions (default: tsx,ts,jsx,js,mjs,cjs)
+  --dry                  Dry-run mode (no file writes)
+  --verbose              Verbose jscodeshift output
+  --help, -h             Show help
+`);
+}
+
+function parseReport(reportContent) {
+  const mappings = [];
+  const regex = /`(src\/assets\/[^`]+)`\s*->\s*`(src\/assets\/webp\/[^`]+)`/g;
+  let match = regex.exec(reportContent);
+  while (match) {
+    const from = match[1].replace(/^src\//, '');
+    const to = match[2].replace(/^src\//, '');
+    mappings.push({ oldPath: from, newPath: to });
+    match = regex.exec(reportContent);
+  }
+  return mappings;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const projectRoot = path.resolve(__dirname, '..');
+  const reportPath = path.resolve(projectRoot, options.reportPath);
+  const targetPath = path.resolve(projectRoot, options.targetPath);
+  const transformPath = path.resolve(projectRoot, 'codemods/image-paths-transform.js');
+
+  if (!fs.existsSync(reportPath)) {
+    console.error(`Report not found: ${reportPath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(targetPath)) {
+    console.error(`Target path not found: ${targetPath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(transformPath)) {
+    console.error(`Transform not found: ${transformPath}`);
+    process.exit(1);
+  }
+
+  const reportContent = fs.readFileSync(reportPath, 'utf8');
+  const mappings = parseReport(reportContent);
+  if (mappings.length === 0) {
+    console.error('No mappings found in IMAGE_MIGRATION_REPORT.md');
+    process.exit(1);
+  }
+
+  const tempMapFile = path.join(os.tmpdir(), `image-path-map-${Date.now()}.json`);
+  fs.writeFileSync(tempMapFile, JSON.stringify(mappings), 'utf8');
+
+  const args = [
+    'jscodeshift',
+    '-t',
+    transformPath,
+    targetPath,
+    `--extensions=${options.extensions}`,
+    '--parser=tsx',
+    '--ignore-pattern=**/node_modules/**',
+    '--ignore-pattern=**/*.test.*',
+    '--ignore-pattern=**/*.spec.*',
+    '--ignore-pattern=**/*.stories.*',
+    `--mapFile=${tempMapFile}`,
+  ];
+
+  if (options.dry) args.push('--dry');
+  if (options.verbose) args.push('--verbose=2');
+
+  console.log(`Applying ${mappings.length} image-path mappings...`);
+  const result = spawnSync('npx', args, { stdio: 'inherit', shell: true });
+
+  try {
+    fs.unlinkSync(tempMapFile);
+  } catch {
+    // ignore
+  }
+
+  process.exit(result.status || 0);
+}
+
+main();
+