add development.md to docs

docs/getting-started/development.md

@@ -0,0 +1,462 @@
+# Development Workflow
+
+This guide covers the development workflow for working with Adminator, including running the development server, making changes, and best practices.
+
+## Table of Contents
+
+- Quick Start
+- Development Server
+- Available npm Scripts
+- Making Changes
+- Hot Module Replacement
+- Code Quality & Linting
+- Debugging
+- Working with Components
+- Working with Styles
+- Best Practices
+- Common Issues
+- Next Steps
+
+## Quick Start
+
+After [installation](installation.md), start the development server:
+
+```bash
+npm start
+```
+
+Your application will be available at **http://localhost:4000**
+
+## Development Server
+
+### Standard Development Server
+
+The standard development server includes hot module replacement (HMR) for instant updates:
+
+```bash
+npm start
+```
+
+**Features:**
+- Hot module replacement (HMR)
+- Automatic browser refresh
+- Source maps for debugging
+- Fast rebuild times
+- Runs on port 4000
+
+### Development Server with Dashboard
+
+For enhanced development experience with visual feedback:
+
+```bash
+npm run dev
+```
+
+**Additional Features:**
+- Visual webpack dashboard
+- Real-time build statistics
+- Bundle size analysis
+- Build time metrics
+- Module dependency graph
+
+## Available npm Scripts
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Start development server with HMR |
+| `npm run dev` | Start development server with webpack dashboard |
+| `npm run clean` | Clean the `dist/` directory |
+
+### Production Build
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Production build (optimized, minified) |
+| `npm run release:minified` | Production build with minification |
+| `npm run release:unminified` | Production build without minification (for debugging) |
+| `npm run preview` | Preview production build locally |
+
+### Code Quality
+
+| Command | Description |
+|---------|-------------|
+| `npm run lint` | Run all linters (JavaScript + SCSS) |
+| `npm run lint:js` | Lint JavaScript files with ESLint |
+| `npm run lint:scss` | Lint SCSS files with Stylelint |
+
+## Making Changes
+
+### File Watching
+
+The development server automatically watches for changes in:
+
+- **HTML files** (`src/*.html`)
+- **JavaScript files** (`src/assets/scripts/**/*.js`)
+- **SCSS files** (`src/assets/styles/**/*.scss`)
+- **Static assets** (`src/assets/static/**/*`)
+
+Changes are automatically compiled and the browser refreshes.
+
+### Workflow
+
+1. **Start the development server**
+   ```bash
+   npm start
+   ```
+
+2. **Make your changes** in the `src/` directory
+
+3. **Save the file** - Changes are automatically detected
+
+4. **Browser refreshes** - See your changes instantly
+
+## Hot Module Replacement (HMR)
+
+HMR allows modules to be updated without a full page reload, preserving application state.
+
+### What Gets Hot Reloaded?
+
+- ✅ **JavaScript modules** - Component updates without page reload
+- ✅ **SCSS/CSS** - Style updates without page reload
+- ⚠️ **HTML files** - Requires full page reload
+- ⚠️ **Configuration files** - Requires server restart
+
+### HMR Benefits
+
+- Faster development cycle
+- Preserves application state
+- Instant visual feedback
+- Better debugging experience
+
+## Code Quality & Linting
+
+### JavaScript Linting (ESLint)
+
+Adminator uses ESLint 9.x with flat configuration:
+
+```bash
+# Lint all JavaScript files
+npm run lint:js
+
+# Auto-fix issues (if possible)
+npx eslint ./src --fix
+```
+
+**Configuration:** `eslint.config.mjs`
+
+**Rules:**
+- ES6+ modern JavaScript
+- No jQuery patterns
+- Consistent code style
+- Import/export validation
+
+### SCSS Linting (Stylelint)
+
+Maintain consistent SCSS code style:
+
+```bash
+# Lint all SCSS files
+npm run lint:scss
+
+# Auto-fix issues (if possible)
+npx stylelint "./src/**/*.scss" --fix
+```
+
+**Configuration:** `.stylelintrc.json`
+
+### Running All Linters
+
+```bash
+npm run lint
+```
+
+This runs both JavaScript and SCSS linters in sequence.
+
+## Debugging
+
+### Source Maps
+
+Development builds include source maps for easier debugging:
+
+1. Open browser DevTools (F12)
+2. Navigate to Sources tab
+3. Find your original source files under `webpack://`
+4. Set breakpoints and debug as normal
+
+### Console Logging
+
+The application includes minimal console output in production. For development debugging:
+
+```javascript
+// Development-only logging
+if (process.env.NODE_ENV !== 'production') {
+  console.log('Debug info:', data);
+}
+```
+
+### Browser DevTools
+
+**Recommended Extensions:**
+- React Developer Tools (if using React components)
+- Vue.js devtools (if using Vue components)
+- Redux DevTools (if using Redux)
+
+## Working with Components
+
+### Creating a New Component
+
+1. **Create component file** in `src/assets/scripts/components/`:
+
+```javascript
+// src/assets/scripts/components/MyComponent.js
+class MyComponent {
+  constructor(element) {
+    this.element = element;
+    this.init();
+  }
+
+  init() {
+    // Initialize component
+    this.setupEventListeners();
+  }
+
+  setupEventListeners() {
+    // Add event listeners
+  }
+
+  destroy() {
+    // Cleanup
+  }
+}
+
+export default MyComponent;
+```
+
+2. **Import and use** in `app.js`:
+
+```javascript
+import MyComponent from '@/components/MyComponent';
+
+// Initialize
+const myComponent = new MyComponent(document.querySelector('.my-component'));
+```
+
+3. **Add component styles** in `src/assets/styles/spec/components/`:
+
+```scss
+// src/assets/styles/spec/components/myComponent.scss
+.my-component {
+  // Component styles
+}
+```
+
+4. **Import styles** in `src/assets/styles/spec/components/index.scss`:
+
+```scss
+@import 'myComponent';
+```
+
+### Component Best Practices
+
+- Use ES6 classes for components
+- Keep components focused and single-purpose
+- Implement `destroy()` method for cleanup
+- Use webpack aliases (`@/components`, `@/utils`)
+- Follow existing naming conventions
+
+## Working with Styles
+
+### SCSS Architecture
+
+Adminator follows ITCSS (Inverted Triangle CSS) methodology:
+
+```
+styles/
+├── settings/    # Variables, config
+├── tools/       # Mixins, functions
+├── generic/     # Reset, normalize
+├── components/  # UI components
+├── utils/       # Utility classes
+└── vendor/      # Third-party styles
+```
+
+### Adding New Styles
+
+1. **Component styles** → `src/assets/styles/spec/components/`
+2. **Page-specific styles** → `src/assets/styles/spec/screens/`
+3. **Utility classes** → `src/assets/styles/spec/utils/`
+
+### Using CSS Variables
+
+Adminator uses CSS custom properties for theming:
+
+```scss
+.my-component {
+  background: var(--c-bkg-card);
+  color: var(--c-text-base);
+  border: 1px solid var(--c-border);
+}
+```
+
+**Available variables:** See `src/assets/styles/spec/utils/theme.css`
+
+### Dark Mode Support
+
+Ensure your components support dark mode:
+
+```scss
+.my-component {
+  background: var(--c-bkg-card); // Auto-adjusts for dark mode
+  
+  // Or use data attribute
+  [data-theme="dark"] & {
+    background: #1f2937;
+  }
+}
+```
+
+## Best Practices
+
+### Code Organization
+
+- ✅ Keep files small and focused
+- ✅ Use meaningful file and variable names
+- ✅ Group related functionality
+- ✅ Follow existing project structure
+- ✅ Use webpack aliases for imports
+
+### JavaScript
+
+- ✅ Use modern ES6+ features
+- ✅ Avoid jQuery patterns
+- ✅ Use vanilla JavaScript DOM APIs
+- ✅ Implement proper error handling
+- ✅ Add JSDoc comments for complex functions
+
+### SCSS
+
+- ✅ Use variables for colors and spacing
+- ✅ Follow BEM naming convention (optional)
+- ✅ Keep selectors shallow (max 3 levels)
+- ✅ Use mixins for repeated patterns
+- ✅ Support dark mode with CSS variables
+
+### Performance
+
+- ✅ Minimize DOM manipulations
+- ✅ Use event delegation
+- ✅ Debounce/throttle frequent events
+- ✅ Lazy load heavy components
+- ✅ Optimize images and assets
+
+### Accessibility
+
+- ✅ Use semantic HTML
+- ✅ Add ARIA labels where needed
+- ✅ Ensure keyboard navigation
+- ✅ Maintain color contrast ratios
+- ✅ Test with screen readers
+
+## Common Issues
+
+### Port Already in Use
+
+If port 4000 is already in use:
+
+```bash
+# Kill the process using port 4000 (Windows)
+netstat -ano | findstr :4000
+taskkill /PID <PID> /F
+
+# Or change the port in webpack/devServer.js
+```
+
+### Changes Not Reflecting
+
+1. **Hard refresh** the browser (Ctrl+F5)
+2. **Clear browser cache**
+3. **Restart development server**
+4. **Check for JavaScript errors** in console
+5. **Verify file is being watched** (check terminal output)
+
+### Build Errors
+
+```bash
+# Clean and rebuild
+npm run clean
+npm install
+npm start
+```
+
+### Linting Errors
+
+```bash
+# Auto-fix common issues
+npx eslint ./src --fix
+npx stylelint "./src/**/*.scss" --fix
+
+# Check remaining issues
+npm run lint
+```
+
+### Module Not Found
+
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+```
+
+## Development Tips
+
+### 1. Use the Webpack Dashboard
+
+```bash
+npm run dev
+```
+
+Provides visual feedback on build performance and bundle size.
+
+### 2. Keep the Console Clean
+
+Fix warnings and errors as they appear to maintain code quality.
+
+### 3. Test in Multiple Browsers
+
+- Chrome/Edge (Chromium)
+- Firefox
+- Safari (if on macOS)
+- Mobile browsers (responsive mode)
+
+### 4. Use Browser DevTools
+
+- **Elements tab** - Inspect and modify DOM/CSS
+- **Console tab** - Debug JavaScript
+- **Network tab** - Monitor requests
+- **Performance tab** - Profile performance
+- **Application tab** - Check localStorage/theme
+
+### 5. Commit Often
+
+Make small, focused commits with clear messages:
+
+```bash
+git add .
+git commit -m "feat: add new dashboard widget"
+git push
+```
+
+## Next Steps
+
+Now that you understand the development workflow:
+
+1. **[Customize Themes](../customization/theme-system.md)** - Set up dark mode and theming
+2. **[Build for Production](build-deployment.md)** - Deploy your application
+3. **[API Reference](../api/theme-api.md)** - JavaScript API documentation
+4. **[Project Structure](project-structure.md)** - Review the codebase structure
+
+---
+
+**Need Help?** Check the [main README](../../README.md) or [open an issue](https://github.com/puikinsh/Adminator-admin-dashboard/issues).