@linagora/linid-im-front-corelib 0.0.5 → 0.0.7

package/CONTRIBUTING.md

@@ -1,269 +0,0 @@
-# **CONTRIBUTING 🤝**
-
-Thank you for contributing to **linid-im-front-corelib**, the core front-end library of the LinID Identity Manager platform.
-This document explains the conventions, workflows, and best practices to follow when contributing.
-
----
-
-# **📌 Git Conventions**
-
-## **🌿 Branch Naming**
-
-All branches must follow one of the following naming patterns:
-
-| Type            | Pattern                           | Example                           |
-| --------------- | --------------------------------- | --------------------------------- |
-| **Main**        | `main` or `dev`                   | `main`                            |
-| **Feature**     | `feature/<short-description>`     | `feature/plugin-zone-support`     |
-| **Bugfix**      | `bugfix/<short-description>`      | `bugfix/fix-null-validation`      |
-| **Improvement** | `improvement/<short-description>` | `improvement/refactor-core-types` |
-| **Release**     | `release/<version>`               | `release/1.2.0`                   |
-| **Hotfix**      | `hotfix/<short-description>`      | `hotfix/fix-critical-crash`       |
-
-### **Rules**
-
-- ✔ Allowed characters: lowercase letters, numbers, dashes (`-`), underscores (`_`), and dots (`.`)
-- ✔ Names must be concise and descriptive
-- ✔ Use English keywords and descriptions
-
----
-
-## **📝 Commit Message Format (Conventional Commits)**
-
-We follow the **Conventional Commits** specification:
-
-```
-<type>(<scope>): <short summary>
-```
-
-### **Accepted types**
-
-* **feat** – Introduces, updates, or removes a feature in the API or UI
-* **fix** – Resolves a bug in the API or UI originating from a previous feature
-* **refactor** – Rewrites or restructures code without changing API or UI behavior
-* **perf** – A specialized refactor focused on improving performance
-* **style** – Addresses code style issues (e.g., whitespace, formatting, missing semicolons) without affecting behavior
-* **test** – Adds missing tests or updates existing tests
-* **docs** – Documentation-only changes
-* **build** – Modifies build-related components (tooling, dependencies, versioning, CI/CD, etc.)
-* **ops** – Changes to operational or infrastructure components (deployment, backup, recovery, etc.)
-* **chore** – Miscellaneous maintenance tasks (e.g., updating `.gitignore`)
-
-### **Examples**
-
-```
-feat(core): add identity validation helpers
-fix(plugins): prevent crash on remote loading
-docs(contributing): add commit format rules
-```
-
----
-
-## **🔏 Commit Signing (GPG)**
-
-All commits **must be GPG-signed**:
-
-```bash
-git commit -S -m "feat(core): add new service"
-```
-
-Unsigned commits will be rejected.
-If you need help setting up GPG signing, refer to your Git hosting provider’s documentation.
-
----
-
-# **📚 Documentation Guidelines**
-
-## **📁 Documentation Directory**
-
-All functional or technical documentation must be placed inside:
-
-```
-/docs
-```
-
-Please keep this folder organized and up to date.
-
----
-
-## **📊 Diagrams with Mermaid**
-
-We use **Mermaid** for architecture diagrams, flowcharts, sequence diagrams, etc.
-
-* Source files must be `.md` or `.mmd`
-* They must be stored in the `docs` directory
-* Generated images must be committed together with source files
-
-### **Install Mermaid CLI**
-
-```bash
-npm install -g @mermaid-js/mermaid-cli
-```
-
-### **Generate a PNG**
-
-```bash
-mmdc -i docs/diagram.mmd -o docs/diagram.png
-```
-
-💡 Any modification to a Mermaid diagram **must include** regeneration of the corresponding PNG.
-
----
-
-# **🚀 Development**
-
-This project uses **pnpm** as the preferred package manager.
-Node.js **22.19+** is recommended.
-
-## **📦 Installation**
-
-### ⭐ Quick Start
-
-```sh
-corepack enable
-pnpm install
-```
-
-### Using pnpm (recommended)
-
-```sh
-pnpm install
-```
-
-### Using npm (legacy support and not recommended by the dev team)
-
-```sh
-npm install
-```
-
----
-
-## **🛠️ Build the Library**
-
-```sh
-pnpm build
-# or (not recommended by the dev team)
-npm run build
-```
-
----
-
-## **🔧 Development Mode**
-
-```sh
-pnpm dev
-# or (not recommended by the dev team)
-npm run dev
-```
-
----
-
-## **🧪 Run Tests**
-
-```sh
-pnpm test          # Runs the full test suite once
-pnpm test:watch    # Runs tests in watch mode
-pnpm test:coverage # Generates a coverage report
-
-# or (not recommended by the dev team)
-npm run test          # Runs the full test suite once
-npm run test:watch    # Runs tests in watch mode
-npm run test:coverage # Generates a coverage report
-```
-
----
-
-# **🧼 Code Quality**
-
-We use **ESLint**, **Prettier**, and **TypeScript** to enforce consistent code style and reliability.
-
-## **🔍 Lint**
-
-```sh
-pnpm lint
-pnpm lint:fix
-```
-
-## **🎨 Format**
-
-```sh
-pnpm format
-pnpm format:check
-```
-
-## **📘 Type Checking**
-
-```sh
-pnpm type-check
-```
-
-## **✔ Full Validation**
-
-```sh
-pnpm validate
-```
-
-## Copyright Headers
-
-All source files located in the `src` folder must contain a copyright header at the beginning of the file. This header is based on the content of the `COPYRIGHT` file at the project root.
-
-### Affected Files
-
-Copyright headers are mandatory for the following files:
-
-- TypeScript files (`.ts`)
-- JavaScript files (`.js`)
-- Vue files (`.vue`)
-
-### Automatic Verification
-
-An ESLint rule is configured via the `eslint-plugin-headers` plugin to check for the presence of these headers.
-
-### Automatic Header Addition
-
-If a file does not contain the required copyright header, you can add it automatically by running:
-
-```bash
-pnpm lint:fix
-```
-
-This command will analyze all files in the `src` folder and add missing headers according to the `COPYRIGHT` file.
-
-### Manual Verification
-
-To check compliance without modifying files, use:
-
-```bash
-pnpm lint
-```
-
-Any file without the appropriate header will be reported as a lint error.
-
----
-
-# **🧪 E2E & Integration Testing**
-
-Full E2E testing documentation is **Coming soon… ⏳**
-This library will later integrate with the LinID front-end test runner.
-
----
-
-# **🚀 Releases (Semantic Release)**
-
-Releases are fully automated using **Semantic Release**.
-
-When a merge is performed into `main`:
-
-* The version bump is automatically calculated from commit messages
-* `package.json` is updated
-* A changelog entry is generated
-* A Git tag is created
-
-⚠ No manual intervention is needed.
-
----
-
-# **📜 License**
-
-This project is licensed under the **GNU Affero General Public License v3**.
-See: [`LICENSE.md`](LICENSE.md)

package/COPYRIGHT

@@ -1,23 +0,0 @@
-Copyright (C) 2025 Linagora
-
-This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General
-Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
-any later version, provided you comply with the Additional Terms applicable for LinID Identity Manager software by
-LINAGORA pursuant to Section 7 of the GNU Affero General Public License, subsections (b), (c), and (e), pursuant to
-which these Appropriate Legal Notices must notably (i) retain the display of the "LinID™" trademark/logo at the top
-of the interface window, the display of the “You are using the Open Source and free version of LinID™, powered by
-Linagora © 2009–2013. Contribute to LinID R&D by subscribing to an Enterprise offer!” infobox and in the e-mails
-sent with the Program, notice appended to any type of outbound messages (e.g. e-mail and meeting requests) as well
-as in the LinID Identity Manager user interface, (ii) retain all hypertext links between LinID Identity Manager
-and https://linid.org/, as well as between LINAGORA and LINAGORA.com, and (iii) refrain from infringing LINAGORA
-intellectual property rights over its trademarks and commercial brands. Other Additional Terms apply, see
-<http://www.linagora.com/licenses/> for more details.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
-warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-details.
-
-You should have received a copy of the GNU Affero General Public License and its applicable Additional Terms for
-LinID Identity Manager along with this program. If not, see <http://www.gnu.org/licenses/> for the GNU Affero
-General Public License version 3 and <http://www.linagora.com/licenses/> for the Additional Terms applicable to the
-LinID Identity Manager software.

package/docs/components-plugin-zones.md

@@ -1,168 +0,0 @@
-# LinidZoneRenderer Component 🔌
-
-The **LinidZoneRenderer** component is a core feature of `linid-im-front-corelib`.  
-It allows the host application to **dynamically render remote Vue components (plugins)** inside predefined “zones” of the UI.
-
-This component works together with the **Linid Zone Store**, which manages plugin registration and provides reactive updates.
-
----
-
-## 🎯 Purpose
-
-LinidZoneRenderer provides:
-
-- **Dynamic rendering:** Components are loaded asynchronously only when needed.
-- **Reactive updates:** New plugins registered to a zone appear automatically.
-- **Extensibility:** New features can be added via plugins without modifying the host app.
-- **Standardization:** All plugins follow the `LinidZoneEntry` interface.
-
----
-
-## 🧱 How to Use the Component
-
-### Basic Usage
-
-```vue
-<template>
-  <LinidZoneRenderer zone="user-details" />
-</template>
-```
-
-* `zone` (string): Identifier of the zone where components should be rendered.
-* The component automatically fetches all registered plugins for this zone from the store and renders them asynchronously.
-
-### Props
-
-| Prop       | Type          | Description                                        |
-| ---------- | ------------- | -------------------------------------------------- |
-| `zone`     | string        | The name of the zone to render                     |
-
-### Default Slot - Fallback Component
-
-The `LinidZoneRenderer` component provides a **default slot** that is displayed when no components are registered in the specified zone **after loading is complete**.
-
-#### Purpose
-
-The default slot allows you to:
-- Display a custom message when a zone is empty
-- Render a placeholder component
-- Show alternative content for zones without plugins
-
-#### Behavior
-
-The slot is rendered **only when**:
-1. ✅ The loading process is complete
-2. ✅ No components are registered in the zone
-
-**Important:** The slot will **not** be displayed during the initial loading phase to avoid flickering.
-
----
-
-#### Usage
-
-##### Default Fallback (No Custom Slot)
-
-If you don't provide a custom slot, the component displays a default message:
-
-```vue
-<template>
-  <LinidZoneRenderer zone="sidebar" />
-</template>
-```
-
-**Rendered when zone is empty:**
-```html
-<div>No components to render in this zone.</div>
-```
-
----
-
-##### Custom Fallback Component
-
-You can provide your own fallback content using the default slot:
-
-```vue
-<template>
-  <LinidZoneRenderer zone="user-actions">
-    <template #default>
-      <div>
-        <p>No actions available for this user.</p>
-      </div>
-    </template>
-  </LinidZoneRenderer>
-</template>
-```
-
----
-
-## ⚡ Adding a Plugin with the Store
-
-Plugins must be registered in the **Linid Zone Store** before they can be rendered.
-
-```ts
-import { useLinidZoneStore } from '@linagora/linid-im-front-corelib';
-
-const linidZoneStore = useLinidZoneStore();
-
-linidZoneStore.register("user-details", {
-  plugin: "@/remote/UserCard",
-  props: { userId: 42 },
-});
-```
-
-* `plugin`: Path or identifier of the remote component to load.
-* `props`: Optional props passed to the plugin component.
-
-> Once registered, the `LinidZoneRenderer` component will automatically render this plugin in the specified zone.
-
----
-
-## 🧩 How It Works
-
-1. The component retrieves all entries for the given `zone` from the **Linid Zone Store**.
-2. Each entry is wrapped as an **async component** retrieved from its remote module using the `loadAsyncComponent(entry.plugin)` method.
-3. All plugins in the zone are rendered sequentially with:
-
-```vue
-<component :is="entry.component" v-bind="entry.props" />
-```
-
-* This allows multiple plugins to coexist in a single zone.
-* The component reacts automatically to changes in the store.
-
----
-
-## 🔧 Plugin Types
-
-Plugins must implement the `LinidZoneEntry` interface:
-
-```ts
-export interface LinidZoneEntry {
-  /** Path to the remote module */
-  plugin: string;
-
-  /** Props forwarded to the plugin component */
-  props?: Record<string, unknown>;
-}
-```
-
-* Props are automatically forwarded to the dynamically loaded component.
-* Components are wrapped in `loadAsyncComponent` for asynchronous loading.
-
----
-
-## ✅ Advantages
-
-* **Decoupled architecture:** Plugins are independent of the host.
-* **Lazy loading:** Only load components when needed.
-* **Reactive:** Supports runtime addition/removal of plugins.
-* **Standardized interface:** All plugins conform to `LinidZoneEntry`.
-* **Framework-friendly:** Works natively with Vue 3, Pinia, and Module Federation.
-
----
-
-## 📌 Notes
-
-* Multiple plugins can be registered for the same zone; they are rendered in registration order.
-* Failed imports are handled automatically; you can provide a `fallback` component.
-* Designed for scalable front-end applications using Module Federation.

package/docs/helpers.md

@@ -1,188 +0,0 @@
-# Helper Functions
-
-This document describes utility functions provided by `linid-im-front-corelib` to simplify common tasks.
-
----
-
-## `loadAsyncComponent`
-
-Loads a remote Vue component from a Module Federation remote using the enhanced runtime.
-
-This helper wraps Vue's `defineAsyncComponent` and Module Federation's `loadRemote` to provide a simple way to load federated components asynchronously.
-
-### Import
-
-```typescript
-import { loadAsyncComponent } from '@linagora/linid-im-front-corelib';
-```
-
-### Parameters
-
-| Parameter | Type     | Description                                                                                                          |
-| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
-| `plugin`  | `string` | The Module Federation remote identifier in the format `remoteName/modulePath`.<br/>Example: `'myRemote/MyComponent'` |
-
-### Returns
-
-Returns a Vue async component that can be used in templates or rendered programmatically.
-
-### Behavior
-
-1. **Lazy loading:** The component is only loaded when it's actually rendered
-2. **Error handling:** Throws an error if the remote module doesn't export a default component
-3. **Type safety:** Expects the remote module to follow the `RemoteComponentModule` structure
-
----
-
-## Usage Examples
-
-### Basic Usage
-
-```vue
-<template>
-  <component :is="remoteComponent" />
-</template>
-
-<script setup lang="ts">
-import { loadAsyncComponent } from '@linagora/linid-im-front-corelib';
-
-const remoteComponent = loadAsyncComponent('myRemote/HeaderWidget');
-</script>
-```
-
----
-
-### Dynamic Component Loading
-
-```vue
-<template>
-  <component
-    v-for="plugin in plugins"
-    :key="plugin"
-    :is="loadAsyncComponent(plugin)"
-  />
-</template>
-
-<script setup lang="ts">
-import { loadAsyncComponent } from '@linagora/linid-im-front-corelib';
-
-const plugins = ['remote1/ComponentA', 'remote2/ComponentB'];
-</script>
-```
-
----
-
-### In LinidZoneRenderer Context
-
-The `loadAsyncComponent` function is used internally by `LinidZoneRenderer`:
-
-```typescript
-// Internal usage in LinidZoneRenderer
-const components = entries.map((entry) => ({
-  ...entry,
-  component: loadAsyncComponent(entry.plugin),
-}));
-```
-
----
-
-## Error Handling
-
-### Module Not Found
-
-If the remote module cannot be loaded:
-
-```typescript
-const component = loadAsyncComponent('invalidRemote/Component');
-// Throws: Error loading remote module
-```
-
-### Missing Default Export
-
-If the module doesn't export a default component:
-
-```typescript
-// Remote module exports: export { MyComponent }
-const component = loadAsyncComponent('myRemote/MyComponent');
-// Throws: Failed to load component from myRemote/MyComponent
-```
-
-**Solution:** Ensure your remote module exports a default component:
-
-```vue
-<!-- ✅ Correct - remote module (.vue file) -->
-<template>
-  <div>My Component</div>
-</template>
-
-<script setup lang="ts">
-// Default export automatic with <script setup>
-// Nothing special to do!
-</script>
-```
-
-**Alternative with Options API:**
-
-```vue
-<!-- ✅ Correct - remote module (.vue file) -->
-<template>
-  <div>My Component</div>
-</template>
-
-<script lang="ts">
-import { defineComponent } from 'vue';
-
-export default defineComponent({
-  name: 'MyComponent',
-  // ...
-});
-</script>
-```
-
-**❌ Wrong - TypeScript/JavaScript file (not .vue):**
-
-```typescript
-// In a .ts file (not .vue)
-// ❌ Named export only - doesn't work with loadAsyncComponent
-export const MyComponent = defineComponent({
-  // ...
-});
-
-// ✅ Correct - default export
-export default defineComponent({
-  name: 'MyComponent',
-  // ...
-});
-```
-
----
-
-## TypeScript Support
-
-### Remote Module Structure
-
-The function expects remotes to follow this structure:
-
-```typescript
-/**
- * Module structure for a Vue component exposed via Module Federation.
- */
-interface RemoteComponentModule {
-  /**
-   * The default exported Vue component.
-   */
-  default: Component;
-}
-```
-
-### Type Inference
-
-The returned component is fully typed as a Vue `Component`:
-
-```typescript
-import type { Component } from 'vue';
-
-const myComponent: Component = loadAsyncComponent('remote/Component');
-```
-
----