@abstraks-dev/ui-library 1.0.1

package/README.md

@@ -0,0 +1,708 @@
+# ui-library
+
+A comprehensive React UI component library with modern styling and robust testing.
+
+## Installation
+
+```bash
+npm install ui-library
+```
+
+## Usage
+
+```jsx
+import { Button, Card, TextInput } from 'ui-library';
+import 'ui-library/dist/styles/main.css';
+
+function App() {
+  return (
+    <div>
+      <Card>
+        <TextInput label="Name" placeholder="Enter your name" />
+        <Button variant="primary">Submit</Button>
+      </Card>
+    </div>
+  );
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+npm install
+npm test
+npm run storybook
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### SCSS Development
+
+The library uses SCSS for styling. Available SCSS commands:
+
+```bash
+# Build CSS from SCSS
+npm run build-css
+
+# Watch SCSS files for changes (development)
+npm run build-css:watch
+
+# Build compressed CSS for production
+npm run build-css:compressed
+```
+
+## Deployment
+
+This library is automatically deployed to npm using GitHub Actions.
+
+### Automatic Deployment
+
+- Push a version tag (e.g., `v1.0.0`) to trigger automatic deployment
+- The workflow will run tests, build the library, and publish to npm
+
+### Manual Deployment
+
+- Go to the Actions tab in GitHub
+- Select "Deploy to NPM" workflow
+- Click "Run workflow" and choose version bump type (patch/minor/major)
+
+### Setting Up NPM Token
+
+1. Generate an npm token at <https://www.npmjs.com/settings/tokens>
+2. Add it as `NPM_TOKEN` in repository secrets (Settings → Secrets and variables → Actions)
+
+### Version Tags
+
+```bash
+# Create and push a version tag
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+
+# UI Library Testing
+
+This document explains how to run and write tests for the UI Library components.
+
+## 🏃‍♂️ Running Tests
+
+### Basic Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode (automatically re-runs when files change)
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+### Test Files Structure
+
+```
+src/
+├── components/
+│   ├── __tests__/
+│   │   ├── Button.test.jsx
+│   │   ├── Heading.test.jsx
+│   │   ├── Label.test.jsx
+│   │   ├── Checkbox.test.jsx
+│   │   └── MenuHover.test.jsx
+│   └── [component files]
+├── icons/
+│   ├── __tests__/
+│   │   ├── ChevronDown.test.jsx
+│   │   └── ArrowRight.test.jsx
+│   └── [icon files]
+└── setupTests.js
+```
+
+## ✅ Current Test Coverage
+
+We have comprehensive unit tests for:
+
+### Components
+- **Button** - 9 tests covering props, events, states, and rendering
+- **Heading** - 8 tests covering different heading levels and props
+- **Label** - 12 tests covering label text, required states, and children
+- **Checkbox** - 15 tests covering state management, props, and interactions
+- **MenuHover** - 8 tests covering toggle behavior, CSS classes, and props
+
+### Icons
+- **ChevronDown** - 8 tests covering SVG properties, styling, and props
+- **ArrowRight** - 10 tests covering multi-path SVG structure and props
+
+**Total: 70 tests passing** ✅
+
+## 🧪 Testing Framework
+
+### Tech Stack
+- **Jest** - Test runner and assertion library
+- **React Testing Library** - Component testing utilities
+- **@testing-library/user-event** - User interaction simulation
+- **@testing-library/jest-dom** - Extended Jest matchers
+
+### Configuration
+- **Jest Config**: `jest.config.json`
+- **Babel Config**: `babel.config.json` 
+- **Setup File**: `src/setupTests.js`
+
+### Key Features
+- **CSS Import Mocking** - CSS files are automatically mocked
+- **Custom Test ID Attribute** - Uses `data-test-id` instead of `data-testid`
+- **SVG Testing** - Proper handling of SVG components
+- **User Interaction Testing** - Simulated clicks, form inputs, etc.
+
+## 📝 Writing New Tests
+
+### Basic Test Structure
+
+```jsx
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { YourComponent } from '../YourComponent';
+
+describe('YourComponent', () => {
+  test('renders correctly', () => {
+    render(<YourComponent />);
+    
+    expect(screen.getByRole('button')).toBeInTheDocument();
+  });
+
+  test('handles user interaction', async () => {
+    const user = userEvent.setup();
+    const handleClick = jest.fn();
+    
+    render(<YourComponent onClick={handleClick} />);
+    
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Testing Patterns
+
+#### 1. **Component Rendering**
+```jsx
+test('renders with default props', () => {
+  render(<Button>Click me</Button>);
+  
+  const button = screen.getByRole('button');
+  expect(button).toBeInTheDocument();
+  expect(button).toHaveTextContent('Click me');
+});
+```
+
+#### 2. **Props Testing**
+```jsx
+test('applies custom className', () => {
+  render(<Button additionalClassName="custom">Test</Button>);
+  
+  const button = screen.getByRole('button');
+  expect(button).toHaveClass('button', 'custom');
+});
+```
+
+#### 3. **User Interactions**
+```jsx
+test('handles click events', async () => {
+  const user = userEvent.setup();
+  const handleClick = jest.fn();
+  
+  render(<Button onClick={handleClick}>Click</Button>);
+  
+  await user.click(screen.getByRole('button'));
+  expect(handleClick).toHaveBeenCalledTimes(1);
+});
+```
+
+#### 4. **State Testing**
+```jsx
+test('toggles state when clicked', async () => {
+  const user = userEvent.setup();
+  render(<Checkbox labelText="Test" setName="test" />);
+  
+  const checkbox = screen.getByRole('checkbox');
+  
+  expect(checkbox).not.toBeChecked();
+  await user.click(checkbox);
+  expect(checkbox).toBeChecked();
+});
+```
+
+#### 5. **SVG/Icon Testing**
+```jsx
+test('renders SVG with correct attributes', () => {
+  render(<ChevronDown size={32} color="blue" />);
+  
+  const svg = document.querySelector('svg');
+  expect(svg).toHaveAttribute('width', '32');
+  expect(svg).toHaveAttribute('height', '32');
+  
+  const path = svg.querySelector('path');
+  expect(path).toHaveAttribute('stroke', 'blue');
+});
+```
+
+### Best Practices
+
+1. **Use semantic queries** - Prefer `getByRole()`, `getByLabelText()`, etc.
+2. **Test user behavior** - Focus on what users do, not implementation details
+3. **Use data-test-id sparingly** - Only when semantic queries aren't sufficient
+4. **Mock external dependencies** - Keep tests isolated and fast
+5. **Test error states** - Include edge cases and error conditions
+6. **Keep tests readable** - Use descriptive test names and clear assertions
+
+### Common Queries
+
+```jsx
+// Semantic queries (preferred)
+screen.getByRole('button')
+screen.getByLabelText('Email')
+screen.getByText('Submit')
+screen.getByPlaceholderText('Enter email')
+
+// Test ID queries (when semantic queries aren't enough)
+screen.getByTestId('custom-component')
+
+// Query variants
+getBy* // Throws error if not found
+queryBy* // Returns null if not found  
+findBy* // Async, waits for element to appear
+```
+
+## 🐛 Debugging Tests
+
+### Common Issues
+
+1. **Element not found** - Check if element is rendered and query is correct
+2. **CSS not loading** - CSS is automatically mocked, so style-based queries won't work
+3. **Async operations** - Use `findBy*` queries or `waitFor()` for async updates
+4. **SVG elements** - Use `document.querySelector()` instead of `getByRole()`
+
+### Debug Tools
+
+```jsx
+// Print rendered HTML
+screen.debug();
+
+// Print specific element
+screen.debug(screen.getByRole('button'));
+
+// Log available roles
+screen.logTestingPlaygroundURL();
+```
+
+## 📊 Coverage Goals
+
+- **Statements**: 80%+
+- **Branches**: 80%+  
+- **Functions**: 80%+
+- **Lines**: 80%+
+
+Current coverage is low because we only have tests for a few components. Add tests for remaining components to improve coverage.
+
+## 🚀 Next Steps
+
+1. **Add tests for remaining components** - Cover all components in the library
+2. **Integration tests** - Test component interactions and workflows  
+3. **Visual regression tests** - Consider adding Chromatic or similar tools
+4. **Performance tests** - Test rendering performance for complex components
+5. **Accessibility tests** - Add automated a11y testing
+
+---
+
+Happy testing! 🧪✨
+
+
+# Accessibility Utilities Usage Guide
+
+## Overview
+
+The `utils/accessibility.js` module provides safe, SSR-compatible utilities for common accessibility patterns throughout the UI library. These utilities help ensure consistent, robust accessibility implementations across components and stories.
+
+## Available Utilities
+
+### `announceToScreenReader(message, priority, timeout)`
+Safe screen reader announcements using ARIA live regions.
+- **Parameters**: 
+  - `message` (string): Message to announce
+  - `priority` ('polite'|'assertive'): Announcement priority (default: 'polite')
+  - `timeout` (number): Cleanup timeout in ms (default: 1000)
+- **Returns**: Cleanup function for manual cleanup
+- **SSR Safe**: Yes (returns no-op function)
+
+### `createLiveRegion(priority)`
+Creates a persistent live region for multiple announcements.
+- **Parameters**:
+  - `priority` ('polite'|'assertive'): Announcement priority (default: 'polite')
+- **Returns**: Object with `announce(message)` and `destroy()` methods
+- **SSR Safe**: Yes (returns no-op methods)
+
+### `safeFocus(element, options)`
+Safely focuses an element with fallback handling.
+- **Parameters**:
+  - `element` (HTMLElement|string): Element or selector to focus
+  - `options` (object): Focus options (optional)
+- **Returns**: Boolean indicating focus success
+- **Features**: Error handling, selector support, focus verification
+
+## Updated Components
+
+### ✅ Components Using Accessibility Utilities
+
+1. **Error.jsx**
+   - Uses built-in ARIA live regions (no manual utilities needed)
+   - Serves as example of proper component-level accessibility
+
+2. **Form.jsx**
+   - **Updated**: Uses `safeFocus` for error field focusing
+   - **Updated**: Uses `announceToScreenReader` for form validation announcements
+   - **Location**: Lines 1-4 (imports), Line 184 (focus call)
+
+3. **DragAndDrop.jsx**
+   - **Updated**: Uses `safeFocus` for keyboard navigation
+   - **Location**: Lines 12 (import), 123 (drag start), 174 & 184 (keyboard navigation)
+
+### ✅ Stories Using Accessibility Utilities
+
+1. **Avatar.stories.js**
+   - **Updated**: Replaced manual DOM manipulation with `announceToScreenReader`
+   - **Removed**: 13 lines of unsafe DOM manipulation code
+   - **Benefits**: SSR safety, consistent behavior, proper cleanup
+
+2. **AnimationGroup.stories.js**
+   - **Updated**: Replaced manual DOM manipulation with `announceToScreenReader`
+   - **Removed**: 15 lines of unsafe DOM manipulation code
+   - **Benefits**: Better positioning, consistent ARIA attributes
+
+3. **AnimationToggle.stories.js**
+   - **Updated**: Uses `safeFocus` for focus management
+   - **Updated**: Uses `announceToScreenReader` for state announcements
+   - **Benefits**: Safer focus operations, proper error handling
+
+4. **Card.stories.js**
+   - **Updated**: Replaced manual DOM manipulation with `announceToScreenReader`
+   - **Updated**: Uses `safeFocus` for ellipses menu focus management
+   - **Removed**: 14 lines of duplicate DOM manipulation code
+
+5. **DragAndDrop.stories.js**
+   - **Updated**: Uses `announceToScreenReader` instead of setState pattern
+   - **Benefits**: More reliable announcements, consistent with other stories
+
+## Components That Could Benefit Further
+
+### 🔄 Potential Future Updates
+
+1. **AnimationToggle.jsx** (Component level)
+   - Could use `safeFocus` for internal focus management
+   - Currently relies on native focus which works well
+
+2. **Crud.jsx**
+   - Has built-in screen reader announcements (lines 538-542)
+   - Could potentially use `createLiveRegion` for efficiency with many operations
+   - Current implementation is already quite good
+
+3. **Button.jsx**
+   - Has comprehensive ARIA support
+   - Focus management handled by browser - no updates needed
+
+4. **Select.jsx**, **TextInput.jsx**, **TextArea.jsx**, **Radio.jsx**, **Checkbox.jsx**
+   - These form elements have focus/blur handlers
+   - Current native focus handling is appropriate for form elements
+   - No updates recommended - browser handles focus well for form controls
+
+### ❓ Stories with Existing Accessibility Patterns
+
+1. **Crud.stories.js**
+   - Has comprehensive ARIA live regions built into component
+   - No manual DOM manipulation found - well implemented
+
+2. **Button.stories.js** 
+   - Uses component's built-in ARIA features
+   - No manual screen reader code found - good as is
+
+## Best Practices
+
+### ✅ When to Use These Utilities
+
+1. **Use `announceToScreenReader`** when:
+   - Making dynamic announcements in Storybook stories
+   - Announcing user actions or state changes
+   - Providing feedback for asynchronous operations
+
+2. **Use `createLiveRegion`** when:
+   - Making multiple announcements in succession
+   - Need more control over announcement timing
+   - Building components with frequent status updates
+
+3. **Use `safeFocus`** when:
+   - Focusing elements that might not exist
+   - Implementing custom focus management
+   - Focus operations that could fail (dynamic content, conditional elements)
+
+### ❌ When NOT to Use These Utilities
+
+1. **Don't use for**:
+   - Form elements with native focus handling
+   - Components with built-in ARIA live regions
+   - Simple static content that doesn't need announcements
+
+2. **Prefer component-level ARIA** for:
+   - Built-in component state announcements
+   - Semantic HTML with proper roles
+   - Standard form validation messages
+
+## Implementation Benefits
+
+### 🚀 Improvements Achieved
+
+1. **Safety**: SSR-compatible with browser environment checks
+2. **Consistency**: Standardized ARIA attributes and cleanup patterns
+3. **Maintainability**: Centralized accessibility logic
+4. **Reliability**: Proper error handling and fallbacks
+5. **Performance**: Efficient DOM cleanup and reuse patterns
+
+### 📈 Code Quality Improvements
+
+- **Removed**: 57+ lines of duplicate DOM manipulation code
+- **Added**: 3 robust, reusable utilities
+- **Improved**: Error handling for focus operations
+- **Enhanced**: Screen reader announcement reliability
+
+## Testing Recommendations
+
+### Screen Reader Testing
+- Test with NVDA, JAWS, VoiceOver to verify announcements
+- Verify announcements work in different browser environments
+- Test SSR scenarios to ensure no client-side errors
+
+### Focus Management Testing  
+- Test keyboard navigation flows
+- Verify focus indicators are visible
+- Test with dynamic content scenarios
+
+### Cross-browser Testing
+- Verify utilities work across different browsers
+- Test in high contrast mode
+- Verify reduced motion preferences are respected
+
+## Future Enhancements
+
+### Potential Additional Utilities
+
+1. **Focus Trap**: For modal dialogs and complex widgets
+2. **ARIA State Manager**: For complex state announcements
+3. **Keyboard Navigation Helper**: For arrow key navigation patterns
+4. **High Contrast Utilities**: For dynamic high contrast adaptations
+
+This comprehensive integration ensures the UI library follows accessibility best practices while maintaining clean, maintainable code.
+
+
+
+# Deployment Guide
+
+This guide explains how to deploy the UI library to npm using the automated GitHub Actions workflow.
+
+## Prerequisites
+
+1. **NPM Account**: Ensure you have an npm account and access to publish packages
+2. **Repository Access**: Admin access to the GitHub repository to configure secrets
+3. **Package Configuration**: Verify `package.json` is properly configured
+
+## Setup Process
+
+### 1. Configure NPM Token
+
+1. Go to [npm Access Tokens](https://www.npmjs.com/settings/tokens)
+2. Click "Generate New Token"
+3. Select "Automation" (for CI/CD use)
+4. Copy the generated token
+
+### 2. Add GitHub Secret
+
+1. Go to your repository on GitHub
+2. Navigate to Settings → Secrets and variables → Actions
+3. Click "New repository secret"
+4. Name: `NPM_TOKEN`
+5. Value: Paste your npm token
+6. Click "Add secret"
+
+### 3. Package Configuration
+
+Ensure your `package.json` has:
+
+```json
+{
+  "name": "your-package-name",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "npm run build-command"
+  }
+}
+```
+
+## Deployment Methods
+
+### Method 1: Tag-based Deployment (Recommended)
+
+This method automatically deploys when you push a version tag:
+
+```bash
+# Make sure your code is ready
+git add .
+git commit -m "Prepare for release v1.0.0"
+git push origin main
+
+# Create and push a version tag
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The workflow will:
+1. ✅ Run all tests
+2. ✅ Build the library
+3. ✅ Publish to npm
+4. ✅ Create a GitHub release
+
+### Method 2: Manual Deployment
+
+Use this for immediate deployment or when you want to control the version bump:
+
+1. Go to GitHub Actions tab in your repository
+2. Select "Deploy to NPM" workflow
+3. Click "Run workflow"
+4. Choose version bump type:
+   - **patch**: Bug fixes (1.0.0 → 1.0.1)
+   - **minor**: New features (1.0.0 → 1.1.0)
+   - **major**: Breaking changes (1.0.0 → 2.0.0)
+5. Click "Run workflow"
+
+## Workflow Steps
+
+The deployment workflow performs these steps:
+
+### 1. Testing Phase
+- ✅ Checkout code
+- ✅ Setup Node.js
+- ✅ Install dependencies
+- ✅ Run test suite
+- ✅ Generate coverage report
+
+### 2. Build and Deploy Phase
+- ✅ Build the library
+- ✅ Version management
+- ✅ Verify build artifacts
+- ✅ Publish to npm
+- ✅ Create GitHub release (for tags)
+
+## Monitoring Deployment
+
+### Check GitHub Actions
+1. Go to Actions tab in your repository
+2. Click on the running/completed workflow
+3. Review logs for each step
+4. Verify success or investigate failures
+
+### Verify NPM Publication
+1. Check [npmjs.com](https://www.npmjs.com/package/your-package-name)
+2. Verify the new version is available
+3. Test installation: `npm install your-package-name@latest`
+
+### Test Installation
+```bash
+# Create a test project
+mkdir test-installation && cd test-installation
+npm init -y
+
+# Install your package
+npm install your-package-name
+
+# Test import
+node -e "console.log(require('your-package-name'))"
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**❌ NPM_TOKEN not set**
+- Error: `npm ERR! need auth`
+- Solution: Verify the NPM_TOKEN secret is correctly configured
+
+**❌ Package name already exists**
+- Error: `npm ERR! 403 Forbidden`
+- Solution: Choose a unique package name or scope it (`@username/package-name`)
+
+**❌ Build failures**
+- Error: Various build errors
+- Solution: Run `npm run build` locally first to identify issues
+
+**❌ Test failures**
+- Error: Tests fail in CI
+- Solution: Ensure all tests pass locally with `npm test`
+
+### Debug Steps
+
+1. **Local verification**:
+   ```bash
+   npm ci
+   npm test
+   npm run build
+   ls -la dist/  # Verify build output
+   ```
+
+2. **Check workflow logs**:
+   - Go to Actions → Failed workflow → Click on failed step
+   - Review error messages and stack traces
+
+3. **Test npm authentication**:
+   ```bash
+   npm whoami  # Should show your npm username
+   ```
+
+## Best Practices
+
+### Version Management
+- Use semantic versioning (semver)
+- Document changes in CHANGELOG.md
+- Test thoroughly before releasing
+
+### Quality Gates
+- All tests must pass
+- Code coverage maintained
+- Build artifacts verified
+- Documentation updated
+
+### Release Notes
+- Use descriptive commit messages
+- Tag releases with clear version numbers
+- Maintain changelog for users
+
+## Security Considerations
+
+- 🔒 NPM tokens have write access - keep them secure
+- 🔒 Use "Automation" tokens for CI/CD (not "Publish" tokens)
+- 🔒 Regularly rotate tokens
+- 🔒 Monitor package downloads for suspicious activity
+
+## Support
+
+If you encounter issues:
+1. Check this guide first
+2. Review GitHub Actions logs
+3. Verify npm token permissions
+4. Test build process locally
+5. Check npm registry status