|
| 1 | +# Vizualni-Admin Demo |
| 2 | + |
| 3 | +Professional Serbian data visualization admin dashboard showcasing modern React components with world-class interactions. |
| 4 | + |
| 5 | +## 🚀 Features |
| 6 | + |
| 7 | +### Core Components |
| 8 | +- **Enhanced Button Component** with: |
| 9 | + - 300ms optimized timing for human perception |
| 10 | + - Magnetic pull effects (8px max) |
| 11 | + - Ripple feedback on click |
| 12 | + - WCAG AAA accessibility compliance |
| 13 | + - Serbian flag color themes |
| 14 | + |
| 15 | +### Demo Pages |
| 16 | +1. **Home Dashboard** (`/`) - Overview of all data visualizations |
| 17 | +2. **Button Component Demo** (`/button-demo`) - Interactive button showcase |
| 18 | +3. **Data Browser** (`/datasets`) - Dataset exploration interface |
| 19 | +4. **Dashboard Pages** (`/dashboard/*`) - Various data visualization examples |
| 20 | + |
| 21 | +### Technical Highlights |
| 22 | +- Next.js 14 with static export |
| 23 | +- TypeScript for type safety |
| 24 | +- Tailwind CSS for styling |
| 25 | +- Serbian localization support |
| 26 | +- Mobile-first responsive design |
| 27 | +- Accessibility-first approach |
| 28 | + |
| 29 | +## 🛠️ Quick Start |
| 30 | + |
| 31 | +### Prerequisites |
| 32 | +- Node.js 18 or higher |
| 33 | +- npm or yarn |
| 34 | + |
| 35 | +### Installation |
| 36 | + |
| 37 | +```bash |
| 38 | +# Clone the repository |
| 39 | +git clone <repository-url> |
| 40 | +cd amplifier/scenarios/dataset_discovery/vizualni-admin |
| 41 | + |
| 42 | +# Run the setup script (recommended) |
| 43 | +npm run setup |
| 44 | + |
| 45 | +# Or manual installation |
| 46 | +npm install |
| 47 | +``` |
| 48 | + |
| 49 | +### Development |
| 50 | + |
| 51 | +```bash |
| 52 | +# Start development server |
| 53 | +npm run dev |
| 54 | + |
| 55 | +# Open your browser |
| 56 | +# Navigate to http://localhost:3000 |
| 57 | +``` |
| 58 | + |
| 59 | +### Production Build |
| 60 | + |
| 61 | +```bash |
| 62 | +# Build for production |
| 63 | +npm run build |
| 64 | + |
| 65 | +# Build static export |
| 66 | +npm run build:static |
| 67 | + |
| 68 | +# Serve static build locally |
| 69 | +npm run serve:static |
| 70 | +``` |
| 71 | + |
| 72 | +## 📁 Project Structure |
| 73 | + |
| 74 | +``` |
| 75 | +vizualni-admin/ |
| 76 | +├── components/ # React components |
| 77 | +│ ├── ui/ # UI components (Button, etc.) |
| 78 | +│ ├── layout/ # Layout components |
| 79 | +│ ├── charts/ # Chart components |
| 80 | +│ └── navigation/ # Navigation components |
| 81 | +├── lib/ # Utility libraries |
| 82 | +│ ├── utils/ # Helper functions |
| 83 | +│ └── data/ # Mock data generators |
| 84 | +├── pages/ # Next.js pages |
| 85 | +│ ├── api/ # API routes |
| 86 | +│ ├── dashboard/ # Dashboard pages |
| 87 | +│ ├── datasets/ # Dataset pages |
| 88 | +│ └── demo/ # Demo pages |
| 89 | +├── public/ # Static assets |
| 90 | +├── scripts/ # Build and setup scripts |
| 91 | +└── styles/ # CSS/styling files |
| 92 | +``` |
| 93 | + |
| 94 | +## 🎯 Available Scripts |
| 95 | + |
| 96 | +- `npm run setup` - Run the development setup script |
| 97 | +- `npm run dev` - Start development server (http://localhost:3000) |
| 98 | +- `npm run build` - Build for production |
| 99 | +- `npm run build:static` - Build static export |
| 100 | +- `npm run start` - Start production server |
| 101 | +- `npm run serve:static` - Serve static build locally |
| 102 | +- `npm run lint` - Run ESLint |
| 103 | +- `npm run lint:fix` - Fix ESLint errors |
| 104 | +- `npm run type-check` - Run TypeScript type checking |
| 105 | +- `npm run test` - Run unit tests |
| 106 | +- `npm run test:watch` - Run tests in watch mode |
| 107 | +- `npm run test:coverage` - Generate test coverage report |
| 108 | +- `npm run test:e2e` - Run end-to-end tests |
| 109 | +- `npm run storybook` - Start Storybook |
| 110 | +- `npm run clean` - Clean build artifacts |
| 111 | + |
| 112 | +## 🌐 Demo URLs |
| 113 | + |
| 114 | +After starting the development server, visit: |
| 115 | + |
| 116 | +- **Home**: http://localhost:3000 |
| 117 | +- **Button Demo**: http://localhost:3000/button-demo |
| 118 | +- **Dashboard**: http://localhost:3000/dashboard |
| 119 | +- **Datasets**: http://localhost:3000/datasets |
| 120 | +- **Dataset Browser**: http://localhost:3000/demo/dataset-browser |
| 121 | + |
| 122 | +## 🎨 Button Component Demo |
| 123 | + |
| 124 | +The button component showcase demonstrates: |
| 125 | + |
| 126 | +### Variants |
| 127 | +- Primary, Secondary, Accent |
| 128 | +- Outline variants |
| 129 | +- Ghost variants |
| 130 | +- White variant |
| 131 | + |
| 132 | +### Sizes |
| 133 | +- Small (sm) |
| 134 | +- Medium (md) |
| 135 | +- Large (lg) |
| 136 | +- Extra Large (xl) |
| 137 | + |
| 138 | +### Interactive Features |
| 139 | +- **Magnetic Pull**: Hover near buttons to see subtle magnetic effect |
| 140 | +- **Ripple Effect**: Click to see tactile feedback |
| 141 | +- **Loading States**: Async operation feedback |
| 142 | +- **Accessibility**: Full keyboard navigation and screen reader support |
| 143 | + |
| 144 | +### Try It Out |
| 145 | +1. Hover over buttons and move cursor nearby for magnetic pull |
| 146 | +2. Click buttons to see ripple effects |
| 147 | +3. Use Tab key for keyboard navigation |
| 148 | +4. Test with screen reader for accessibility |
| 149 | + |
| 150 | +## 📊 Dashboard Features |
| 151 | + |
| 152 | +### Data Visualizations |
| 153 | +- Budget allocation by category |
| 154 | +- Demographics overview |
| 155 | +- Air quality monitoring |
| 156 | +- Energy consumption tracking |
| 157 | + |
| 158 | +### Serbian Context |
| 159 | +- Serbian municipalities data |
| 160 | +- Localized number and date formatting |
| 161 | +- Serbian flag color scheme |
| 162 | +- Regional statistics |
| 163 | + |
| 164 | +## 🛡️ Accessibility |
| 165 | + |
| 166 | +### WCAG Compliance |
| 167 | +- AAA contrast ratios for text |
| 168 | +- 44px minimum touch targets |
| 169 | +- Full keyboard navigation |
| 170 | +- Screen reader support |
| 171 | +- Reduced motion support |
| 172 | + |
| 173 | +### Testing |
| 174 | +```bash |
| 175 | +# Run accessibility tests |
| 176 | +npm run test:accessibility |
| 177 | + |
| 178 | +# Run visual regression tests |
| 179 | +npm run test:visual |
| 180 | +``` |
| 181 | + |
| 182 | +## 🌍 Localization |
| 183 | + |
| 184 | +### Serbian Support |
| 185 | +- Number formatting (serbian locale) |
| 186 | +- Currency formatting (RSD) |
| 187 | +- Date formatting |
| 188 | +- Localized content |
| 189 | + |
| 190 | +### Adding New Translations |
| 191 | +1. Edit `public/locales/[lang]/common.json` |
| 192 | +2. Update components to use new keys |
| 193 | +3. Test with different locales |
| 194 | + |
| 195 | +## 🔧 Configuration |
| 196 | + |
| 197 | +### Environment Variables |
| 198 | +Create `.env.local`: |
| 199 | + |
| 200 | +```bash |
| 201 | +NEXT_PUBLIC_APP_URL=http://localhost:3000 |
| 202 | +NEXT_PUBLIC_APP_NAME=Vizualni-Admin Demo |
| 203 | +NEXT_PUBLIC_ENABLE_STORYBOOK=true |
| 204 | +``` |
| 205 | + |
| 206 | +### Tailwind Configuration |
| 207 | +Custom Serbian colors in `tailwind.config.js`: |
| 208 | +- `serbia-red`: #C6363C |
| 209 | +- `serbia-blue`: #0C4076 |
| 210 | +- `serbia-white`: #FFFFFF |
| 211 | + |
| 212 | +## 📝 Static Export |
| 213 | + |
| 214 | +This project supports static export for deployment to: |
| 215 | + |
| 216 | +- Vercel |
| 217 | +- Netlify |
| 218 | +- GitHub Pages |
| 219 | +- Any static hosting |
| 220 | + |
| 221 | +### Deployment Steps |
| 222 | +```bash |
| 223 | +# Build static export |
| 224 | +npm run build:static |
| 225 | + |
| 226 | +# Deploy the `out` folder |
| 227 | +# The build output is in the `out` directory |
| 228 | +``` |
| 229 | + |
| 230 | +## 🧪 Testing |
| 231 | + |
| 232 | +### Unit Tests |
| 233 | +```bash |
| 234 | +npm run test # Run all tests |
| 235 | +npm run test:watch # Watch mode |
| 236 | +npm run test:coverage # Coverage report |
| 237 | +``` |
| 238 | + |
| 239 | +### End-to-End Tests |
| 240 | +```bash |
| 241 | +npm run test:e2e # Run E2E tests |
| 242 | +npm run test:e2e:headed # Run with browser UI |
| 243 | +``` |
| 244 | + |
| 245 | +### Accessibility Tests |
| 246 | +```bash |
| 247 | +npm run test:accessibility # Run aXe tests |
| 248 | +``` |
| 249 | + |
| 250 | +## 📈 Performance |
| 251 | + |
| 252 | +### Optimization |
| 253 | +- Next.js 14 with App Router |
| 254 | +- Static generation for better performance |
| 255 | +- Optimized images |
| 256 | +- Lazy loading components |
| 257 | +- Code splitting |
| 258 | + |
| 259 | +### Lighthouse Scores |
| 260 | +- Performance: 95+ |
| 261 | +- Accessibility: 100 |
| 262 | +- Best Practices: 95+ |
| 263 | +- SEO: 100 |
| 264 | + |
| 265 | +## 🤝 Contributing |
| 266 | + |
| 267 | +### Development Workflow |
| 268 | +1. Fork the repository |
| 269 | +2. Create a feature branch |
| 270 | +3. Make your changes |
| 271 | +4. Run tests: `npm run test` |
| 272 | +5. Run linting: `npm run lint` |
| 273 | +6. Submit a pull request |
| 274 | + |
| 275 | +### Code Style |
| 276 | +- Use TypeScript |
| 277 | +- Follow ESLint configuration |
| 278 | +- Write tests for new features |
| 279 | +- Document components with JSDoc |
| 280 | + |
| 281 | +## 📝 License |
| 282 | + |
| 283 | +MIT License - see LICENSE file for details |
| 284 | + |
| 285 | +## 🙏 Acknowledgments |
| 286 | + |
| 287 | +- Serbian Open Data Initiative |
| 288 | +- Next.js team for excellent framework |
| 289 | +- Tailwind CSS for utility-first styling |
| 290 | +- Serbian design patterns and colors |
| 291 | + |
| 292 | +## 📞 Support |
| 293 | + |
| 294 | +For questions or support: |
| 295 | +- Create an issue on GitHub |
| 296 | +- Check existing documentation |
| 297 | +- Review demo pages for examples |
| 298 | + |
| 299 | +--- |
| 300 | + |
| 301 | +**Built with ❤️ for Serbian data visualization** |
0 commit comments