demf-rules-list 3.0.0

package/README.md

@@ -0,0 +1,371 @@
+# Digital Enabler Rules List
+
+The Rules List microfrontend shows a list of rules created and lets create a new one. The Rules List works within the Rule Manager (RM) tool in which it is mounted, and is an access point to the Rule Editor microfrontend.
+
+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-rules-list@latest/mf-app.js
+```
+
+Add it to your root-config import map:
+
+```json
+{
+  "imports": {
+    "demf-rules-list": "https://cdn.jsdelivr.net/npm/demf-rules-list@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 Rules List (see below)
+
+### Integration Steps
+
+**1. Add to Import Map**
+
+In your root-config `importmap.json`:
+
+```json
+{
+  "imports": {
+    "demf-rules-list": "https://cdn.jsdelivr.net/npm/demf-rules-list@latest/mf-app.js"
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "imports": {
+    "demf-rules-list": "http://localhost:9010/mf-app.js"
+  }
+}
+```
+
+**2. Register in Layout**
+
+In your root-config layout HTML:
+
+```html
+<application name="demf-rules-list" props="realm, palette, rules-list-config">
+</application>
+```
+
+**3. Create Configuration File**
+
+Create a `rules-list-config.json` file with these settings:
+
+```json
+{
+  "name": "rules-list",
+  "mf": "demf-rules-list",
+  "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 `rules-list-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 Rules List microfrontend receives a configuration object via the `rules-list-config` prop:
+
+```json
+{
+  "name": "rules-list",
+  "mf": "demf-rules-list",
+  "api": "https://your-api-endpoint.com/api"
+}
+```
+
+### Configuration Fields
+
+| Field | Type   | Required | Description                                  |
+| ----- | ------ | -------- | -------------------------------------------- |
+| `mf`  | string | Yes      | Microfrontend identifier (use "demf-rules-list") |
+| `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 Rules List appearance to the current application theme
+
+### Standard Error Event Mixin
+
+The template includes `src/mixins/events.js` with a standardized `setError(err, prevent, actionEv)` helper.
+
+This helper:
+
+- Safely handles network errors where `err.response` is missing
+- Dispatches normalized browser events (`error-<status>`)
+- Uses `preventDefault: Boolean(prevent)` for consistent behavior
+- Writes explicit technical details to browser console for debugging
+
+---
+
+## 🛠️ 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 Rules List 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 Rules List 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 Rules List across all Digital Enabler services
+- **Platform information**: Displays version, copyright, and relevant links
+
+---
+
+## 📁 Project Structure
+
+```
+demf-rules-list/
+├── app/
+│   ├── src/
+│   │   ├── App.vue                    # Main component
+│   │   ├── main.js                    # Entry point
+│   │   ├── components/                # Rules List components
+│   │   ├── mixins/
+│   │   │   └── events.js             # Shared setError helper
+│   │   ├── 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
+
+### Rules List not visible
+
+- Verify the import map includes `demf-rules-list`
+- 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 `rules-list-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 `rules-list-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-rules-list/issues)
+- Contact the Digital Enabler development team
+- Check the [Digital Enabler documentation](https://github.com/digital-enabler)