demf-kpim-editor-control-panel 2.0.0

package/README.md

@@ -0,0 +1,352 @@
+# Digital Enabler KPIM Editor Control Panel
+
+The KPIM Editor Control Panel microfrontend manages all the steps of creating a KPI and manages the KPI itself when it is being updated or simply displayed. The KPIM Editor Control Panel works within the KPIM tool in which it is mounted, and is a the main dashboard inside the KPI Editor microfrontends.
+
+Built with **Vue 3**, **Vuetify 3**, and **Vite**. Designed for **Single-SPA** integration.
+
+> 📌 **See also:**
+> - [Root Config integration guide](https://github.com/digital-enabler/root-config-microfrontend-vite-template)
+> - [Microfrontend template documentation](https://github.com/digital-enabler/vuejs3-microfrontend-vite-template)
+
+---
+
+## 📦 Installation
+
+
+### Via CDN
+
+This project is available from the following CDN:
+
+```
+https://cdn.jsdelivr.net/npm/demf-kpim-editor-control-panel@latest/mf-app.js
+```
+
+Add it to your root-config import map:
+
+```json
+{
+  "imports": {
+    "demf-kpim-editor-control-panel": "https://cdn.jsdelivr.net/npm/demf-kpim-editor-control-panel@latest/mf-app.js"
+  }
+}
+```
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+Before you continue you need to have:
+
+- A Digital Enabler **root-config** application running
+- **Single-SPA** layout engine configured
+- A configuration file for the KPIM Editor Control Panel  (see below)
+
+### Integration Steps
+
+**1. Add to Import Map**
+
+In your root-config `importmap.json`:
+
+```json
+{
+  "imports": {
+    "demf-kpim-editor-control-panel": "https://cdn.jsdelivr.net/npm/demf-kpim-editor-control-panel@latest/mf-app.js"
+  }
+}
+```
+
+For local development:
+```json
+{
+  "imports": {
+    "demf-kpim-editor-control-panel": "http://localhost:9010/mf-app.js"
+  }
+}
+```
+
+**2. Register in Layout**
+
+In your root-config layout HTML:
+
+```html
+<application 
+  name="demf-kpim-editor-control-panel" 
+  props="realm, palette, kpim-editor-control-panel-config">
+</application>
+```
+
+**3. Create Configuration File**
+
+Create a `kpim-editor-control-panel-config.json` file with these settings:
+
+```json
+{
+  "name": "kpim-editor-control-panel",
+  "mf": "demf-kpim-editor-control-panel",
+  "api": "https://[generic_api_location]/api"
+}
+```
+
+This JSON file must be:
+- Stored in a location accessible to the root-config
+- Included in the root-config's remote configuration
+- Passed as the `kpim-editor-control-panel-config` prop to the microfrontend
+
+> 📖 For details on configuration management, see:
+> - [Microfrontend Template Guide](https://github.com/digital-enabler/vuejs3-microfrontend-vite-template)
+> - [Root Config Documentation](https://github.com/digital-enabler/root-config-microfrontend-vite-template)
+
+---
+
+## ⚙️ Configuration
+
+The KPIM Editor Control Panel  microfrontend receives a configuration object via the `kpim-editor-control-panel-config` prop:
+
+```json
+{
+  "name": "kpim-editor-control-panel",
+  "mf": "demf-kpim-editor-control-panel",
+  "api": "https://your-api-endpoint.com/api"
+}
+```
+
+### Configuration Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mf` | string | Yes | Microfrontend identifier (use "demf-kpim-editor-control-panel") |
+| `api` | string | Yes | Base URL for API calls |
+
+### Additional Props from Root-Config
+
+The microfrontend also receives these props automatically from the root-config:
+
+- **`realm`**: Current tenant/realm identifier
+- **`palette`**: Dynamic theme colors (primary, secondary, etc.)
+
+These props are used to:
+- Apply consistent theming across the platform
+- Configure tenant-specific behavior
+- Adapt the KPIM Editor Control Panel  appearance to the current application theme
+
+---
+
+## 🛠️ Development
+
+### Prerequisites
+
+Before you continue you need to have:
+
+- [NPM](https://www.npmjs.com/) installed
+- [Node.js](https://nodejs.org/) (v22+ or v24.8+) installed
+- [Vue.js](https://v3.vuejs.org/) and [Vite](https://vitejs.dev/) knowledge
+- A [GitHub](https://github.com/) account
+- Visual Studio Code or IntelliJ IDEA as your development IDE
+
+### Project Management
+
+#### Installation
+
+Open a **Terminal** window in the project folder and go inside the `app` folder, then launch:
+
+```bash
+npm install
+```
+
+> **NOTE:** When install finishes, do not worry about warnings on versions and vulnerability problems reported. **DO NOT** launch `npm audit fix` or `npm audit fix --force` commands.
+
+#### Development Server (with hot-reload)
+
+```bash
+npm run dev
+```
+
+This command:
+1. Generates Vuetify locales automatically (via `predev` script)
+2. Builds the microfrontend in watch mode
+3. Starts a preview server at `http://localhost:9010`
+
+The microfrontend will be available at: `http://localhost:9010/mf-app.js`
+
+#### Build for Production
+
+```bash
+npm run build
+```
+
+This command:
+1. Generates Vuetify locales automatically (via `prebuild` script)
+2. Creates an optimized production build in the `dist/` folder
+3. Outputs a SystemJS bundle ready for deployment
+
+#### Code Quality
+
+```bash
+npm run lint        # Lint and fix files with ESLint
+npm run format      # Format code with Prettier
+```
+
+> **NOTE:** Alternatively to the commands indicated above you can use the Vue UI browser interface.
+
+---
+
+## 🌐 Internationalization
+
+The KPIM Editor Control Panel  microfrontend supports multiple languages through **vue-i18n** with automatic **Vuetify locale integration**.
+
+### How It Works
+
+- Locale files are stored in `src/locales/*.json` (e.g., `en.json`, `it.json`)
+- The script `scripts/generate-vuetify-locales.mjs` automatically scans these files
+- Matching Vuetify translations are imported and merged
+- The active language is read from `localStorage.getItem('lang')` (defaults to `en`)
+
+### Supported Languages
+
+The KPIM Editor Control Panel  includes translations for the languages defined in `src/locales/`:
+- English (`en`)
+- Italian (`it`)
+- [Add other languages as needed]
+
+### Adding a New Language
+
+1. Create a new file: `src/locales/<code>.json` (e.g., `es.json`)
+2. Add your translations following the existing structure
+3. Run `npm run dev` or `npm run build`
+4. The generator will automatically include Vuetify translations for that language
+
+---
+
+## 🎨 Features
+
+- **Dynamic theming**: Automatically adapts to the palette passed from root-config
+- **Multi-language support**: Full internationalization with vue-i18n
+- **Responsive design**: Works seamlessly on mobile, tablet, and desktop
+- **Material Design**: Built with Vuetify 3 components and Material Design Icons
+- **Consistent branding**: Shows uniform KPIM Editor Control Panel  across all Digital Enabler services
+- **Platform information**: Displays version, copyright, and relevant links
+
+---
+
+## 📁 Project Structure
+
+```
+demf-kpim-editor-control-panel/
+├── app/
+│   ├── src/
+│   │   ├── App.vue                    # Main component
+│   │   ├── main.js                    # Entry point
+│   │   ├── components/                # KPIM Editor Control Panel  components
+│   │   ├── locales/
+│   │   │   ├── i18n.js               # i18n configuration
+│   │   │   ├── en.json               # English translations
+│   │   │   ├── it.json               # Italian translations
+│   │   │   └── vuetify-generated.js  # Auto-generated Vuetify locales
+│   │   ├── plugins/
+│   │   │   └── vuetify.js            # Vuetify configuration
+│   │   ├── router/
+│   │   └── store/
+│   ├── scripts/
+│   │   └── generate-vuetify-locales.mjs
+│   ├── public/
+│   ├── dist/                          # Build output
+│   ├── package.json
+│   ├── vite.config.js
+│   └── eslint.config.js
+├── docker/
+└── README.md
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### KPIM Editor Control Panel  not visible
+
+- Verify the import map includes `demf-kpim-editor-control-panel`
+- Check the layout HTML has the `<application>` tag with correct name
+- Ensure the bundle is accessible at the configured URL
+- Look for console errors in the browser developer tools
+
+### Configuration not working
+
+- Check that `kpim-editor-control-panel-config` prop is passed in the layout
+- Verify the configuration JSON structure matches the expected format
+- Ensure the root-config is loading the remote configuration correctly
+- Check console for warnings about missing configuration
+
+### Styling issues
+
+- Ensure the `palette` prop is being passed from root-config
+- Verify Material Design Icons fonts are loaded
+- Check that Vuetify theme configuration is correct
+- Clear browser cache and reload
+
+### API connection errors
+
+- Verify the `api` field in `kpim-editor-control-panel-config.json` is correct
+- Check network tab for failed API requests
+- Ensure CORS is properly configured on the backend
+- Verify the API endpoint is accessible from the browser
+
+### Development server not starting
+
+- Check that port 9001 is not already in use
+- Verify Node.js version is compatible (v22+ or v24.8+)
+- Try removing `node_modules` and running `npm install` again
+- Ensure all dependencies are correctly installed
+
+---
+
+## 📚 Tech Stack
+
+### Runtime Dependencies
+
+- **Vue 3** (^3.5.22) - Progressive JavaScript framework
+- **Vuetify 3** (^3.10.7) - Material Design component library
+- **Single-SPA Vue** (^3.0.1) - Single-SPA integration for Vue
+- **Vue Router** (^4.6.3) - Official router for Vue.js
+- **Vue i18n** (^9.14.5) - Internationalization plugin
+- **Vuex** (^4.1.0) - State management
+- **Axios** (^1.13.0) - HTTP client
+- **Material Design Icons** (^7.4.47) - Icon library
+
+### Development Dependencies
+
+- **Vite** (^7.1.12) - Next generation frontend tooling
+- **ESLint** (^9.38.0) - Code linting
+- **Prettier** (^3.6.2) - Code formatting
+- **Vite Plugin Vue DevTools** (^8.0.3) - Vue DevTools integration
+- **Concurrently** (^9.2.1) - Run multiple commands
+
+For complete dependencies, see [`package.json`](./app/package.json).
+
+---
+
+## 📖 Related Documentation
+
+- [Digital Enabler Root Config Template](https://github.com/digital-enabler/root-config-microfrontend-vite-template)
+- [Digital Enabler Microfrontend Template](https://github.com/digital-enabler/vuejs3-microfrontend-vite-template)
+- [Single-SPA Documentation](https://single-spa.js.org/)
+- [Vue 3 Documentation](https://vuejs.org/)
+- [Vuetify 3 Documentation](https://vuetifyjs.com/)
+- [Vite Documentation](https://vitejs.dev/)
+
+---
+
+## 📄 License
+
+This project is part of Digital Enabler Ecosystem.
+
+© 2025 Engineering Ingegneria Informatica S.p.A.
+
+---
+
+## 🆘 Support
+
+For support, questions, or issues:
+- Open an issue on [GitHub](https://github.com/digital-enabler/demf-kpim-editor-control-panel/issues)
+- Contact the Digital Enabler development team
+- Check the [Digital Enabler documentation](https://github.com/digital-enabler)