@linagora/linid-im-front-corelib 0.0.1

package/docs/types-and-interfaces.md

@@ -0,0 +1,92 @@
+# TypeScript Types & Interfaces 🧩
+
+This document explains the **types and interfaces** used in `linid-im-front-corelib`.
+
+---
+
+## 🔌 LinidZoneEntry
+
+Represents a plugin entry that can be rendered inside a zone.
+
+```ts
+export interface LinidZoneEntry {
+  /** Path or identifier of the plugin module */
+  plugin: string;
+
+  /** Props forwarded to the plugin component */
+  props?: Record<string, unknown>;
+}
+```
+
+**Usage:**
+All plugins registered to the `Linid Zone Store` must implement this interface.
+
+---
+
+## 🧱 LinidZoneState
+
+Represents the state of the Pinia store that manages all plugin zones.
+
+```ts
+interface LinidZoneState {
+  /** Map of zone names to their registered plugin entries */
+  zones: Record<string, LinidZoneEntry[]>;
+}
+```
+
+* `zones` is a reactive object.
+* Each key corresponds to a zone, each value is an array of plugins for that zone.
+
+---
+
+## 📦 RemoteComponentModule
+
+Defines the structure of a Vue component module loaded via Module Federation.
+
+```ts
+export interface RemoteComponentModule {
+  /** The default exported Vue component */
+  default: Component;
+}
+```
+
+**Usage:**
+
+Used internally by [`loadAsyncComponent`](./helpers.md#loadasynccomponent) to ensure type safety when loading federated components.
+
+**Remote modules must export a default component:**
+
+```vue
+<!-- ✅ Correct - .vue file -->
+<template>
+  <div>My Component</div>
+</template>
+
+<script setup lang="ts">
+// Default export is automatic
+</script>
+```
+
+```typescript
+// ❌ Wrong - named export only
+export const MyComponent = defineComponent({ /* ... */ });
+
+// ✅ Correct - default export
+export default defineComponent({ /* ... */ });
+```
+
+---
+
+## 🧰 Summary
+
+| Type / Interface        | Purpose                                               |
+| ----------------------- | ----------------------------------------------------- |
+| `LinidZoneEntry`        | Defines the contract for a plugin component           |
+| `LinidZoneState`        | Defines the structure of the zone store               |
+| `RemoteComponentModule` | Defines the structure of a federated component module |
+
+These types enforce **consistency and type safety** across all front-end modules and plugins.
+
+---
+
+> Additional types and interfaces will be added as new features are implemented in the library.

package/eslint.config.js

@@ -0,0 +1,135 @@
+import js from '@eslint/js';
+import prettierSkipFormatting from '@vue/eslint-config-prettier/skip-formatting';
+import {
+  defineConfigWithVueTs,
+  vueTsConfigs,
+} from '@vue/eslint-config-typescript';
+import jsdoc from 'eslint-plugin-jsdoc';
+import vue from 'eslint-plugin-vue';
+import headers from 'eslint-plugin-headers';
+
+export default defineConfigWithVueTs(
+  {
+    ignores: [
+      'dist/',
+      'coverage/',
+      '**/vite.config.*.timestamp*',
+      '**/vitest.config.*.timestamp*',
+    ],
+  },
+  js.configs.recommended,
+  vueTsConfigs.recommended,
+  vue.configs['flat/recommended'],
+  jsdoc.configs['flat/recommended-typescript'],
+  prettierSkipFormatting,
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {
+        process: 'readonly',
+      },
+    },
+  },
+  {
+    files: ['**/*.{js,mjs,cjs,ts,vue}'],
+    rules: {
+      // Vue rules
+      'vue/multi-word-component-names': 'off',
+      'vue/require-default-prop': 'error',
+      'vue/require-prop-types': 'error',
+      'vue/component-api-style': ['error', ['script-setup']],
+      'vue/max-attributes-per-line': 'error',
+
+      // TypeScript rules
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/consistent-type-imports': 'error',
+
+      // JSDoc rules
+      'jsdoc/require-jsdoc': [
+        'error',
+        {
+          require: {
+            ArrowFunctionExpression: false,
+            ClassDeclaration: true,
+            ClassExpression: true,
+            FunctionExpression: true,
+            MethodDefinition: true,
+          },
+          contexts: [
+            'TSInterfaceDeclaration',
+            'TSTypeAliasDeclaration',
+            'TSEnumDeclaration',
+            'TSPropertySignature',
+            'TSModuleDeclaration VariableDeclaration',
+            'VariableDeclaration > VariableDeclarator > ArrowFunctionExpression',
+          ],
+        },
+      ],
+      'jsdoc/check-tag-names': 'error',
+      'jsdoc/check-types': 'error',
+      'jsdoc/check-param-names': 'error',
+      'jsdoc/require-description': 'warn',
+      'jsdoc/require-description-complete-sentence': 'error',
+
+      // General rules
+      'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
+      'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
+      curly: 'error',
+      'arrow-body-style': ['error', 'as-needed'],
+    },
+  },
+  {
+    files: ['src/**/*.vue'],
+    plugins: {
+      headers,
+    },
+    rules: {
+      'headers/header-format': [
+        'error',
+        {
+          source: 'file',
+          path: 'COPYRIGHT',
+          trailingNewlines: 2,
+          enableVueSupport: true,
+        },
+      ],
+    },
+  },
+  {
+    files: ['src/**/*.{ts,js}'],
+    plugins: {
+      headers,
+    },
+    rules: {
+      'headers/header-format': [
+        'error',
+        {
+          source: 'file',
+          path: 'COPYRIGHT',
+          blockPrefix: '\n',
+          trailingNewlines: 2,
+        },
+      ],
+    },
+  },
+  {
+    files: [
+      '**/*.test.ts',
+      '**/*.spec.ts',
+      '**/__tests__/**',
+      '**/*.config.*',
+      '**/*.config.*',
+    ],
+    rules: {
+      'jsdoc/require-jsdoc': 'off',
+      'headers/header-format': 'off',
+    },
+  }
+);

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@linagora/linid-im-front-corelib",
+  "version": "0.0.1",
+  "description": "Core library of the LinID Identity Manager project. Provides shared types, services, components, and utilities for front-end and plugin, enabling consistent integration across the LinID ecosystem.",
+  "type": "module",
+  "main": "dist/core-lib.umd.js",
+  "module": "dist/core-lib.es.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linagora/linid-im-front-corelib.git"
+  },
+  "contributors": [
+    {
+      "name": "Vincent Moittie",
+      "email": "moittie.vincent@gmail.com",
+      "url": "https://github.com/Zorin95670"
+    },
+    {
+      "name": "Jordy Cabannes",
+      "email": "jcabannes@linagora.com",
+      "url": "https://github.com/jcabannes"
+    },
+    {
+      "name": "Christophe Chevalier",
+      "email": "cchevalier@linagora.com",
+      "url": "https://github.com/christophechevalier"
+    }
+  ],
+  "license": "AGPL-3.0-only",
+  "bugs": {
+    "url": "https://github.com/linagora/linid-im-front-corelib/issues"
+  },
+  "homepage": "https://github.com/linagora/linid-im-front-corelib#readme",
+  "peerDependencies": {
+    "@module-federation/enhanced": "0.21.4",
+    "pinia": "3.0.4",
+    "vue": "3.5.24"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.1",
+    "@types/node": "20.19.9",
+    "@vitejs/plugin-vue": "6.0.1",
+    "@vue/eslint-config-prettier": "10.2.0",
+    "@vue/eslint-config-typescript": "14.6.0",
+    "eslint": "9.39.1",
+    "eslint-plugin-headers": "1.3.3",
+    "eslint-plugin-jsdoc": "61.2.1",
+    "eslint-plugin-vue": "10.5.1",
+    "prettier": "3.6.2",
+    "typescript": "5.9.3",
+    "vite": "7.2.2",
+    "vitest": "4.0.8",
+    "vue-tsc": "3.1.3"
+  },
+  "scripts": {
+    "build": "vite build && vue-tsc --declaration --emitDeclarationOnly",
+    "test": "vitest",
+    "dev": "vite",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.{js,ts,vue,json,css,scss,md}\"",
+    "format:check": "prettier --check \"src/**/*.{js,ts,vue,json,css,scss,md}\"",
+    "type-check": "vue-tsc --noEmit",
+    "validate": "pnpm type-check && pnpm lint && pnpm format:check"
+  }
+}

package/src/components/LinidZoneRenderer.vue

@@ -0,0 +1,77 @@
+<!--
+  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.
+-->
+
+<template>
+  <component
+    :is="entry.component"
+    v-for="(entry, index) in components"
+    :key="entry.plugin + index"
+    v-bind="entry.props"
+  />
+  <slot v-if="isLoadingComplete && components.length === 0">
+    <div>No components to render in this zone.</div>
+  </slot>
+</template>
+
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue';
+import { loadAsyncComponent } from '../services/federationService';
+import { useLinidZoneStore } from '../stores/linidZoneStore';
+import type { LinidZoneEntry } from '../types/linidZone';
+
+const props = defineProps<{
+  /**
+   *  The zone identifier where to render components.
+   */
+  zone: string;
+}>();
+const linidZoneStore = useLinidZoneStore();
+
+const components = ref<
+  ({
+    /**
+     * The component to render.
+     */
+    component: unknown;
+  } & LinidZoneEntry)[]
+>([]);
+
+const isLoadingComplete = ref(false);
+
+watchEffect(() => {
+  isLoadingComplete.value = false;
+
+  const entries = linidZoneStore.zones[props.zone] || [];
+  components.value = entries.map((entry) => ({
+    ...entry,
+    component: loadAsyncComponent(entry.plugin),
+  }));
+
+  Promise.resolve().then(() => {
+    isLoadingComplete.value = true;
+  });
+});
+</script>

package/src/index.ts

@@ -0,0 +1,51 @@
+/*
+ * 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.
+ */
+
+// Components
+export { default as LinidZoneRenderer } from './components/LinidZoneRenderer.vue';
+
+// Stores
+export { useLinidZoneStore } from './stores/linidZoneStore';
+
+// Types - Zones
+export type { LinidZoneEntry } from './types/linidZone';
+
+export type {
+  ModuleHostConfig,
+  RemoteComponentModule,
+  RemoteModule,
+} from './types/module';
+
+// Types - Module Lifecycle
+export type {
+  ModuleLifecycleHooks,
+  ModuleLifecycleResult,
+} from './types/moduleLifecycle';
+
+export { ModuleLifecyclePhase } from './types/moduleLifecycle';
+
+// Lifecycle Base Class
+export { BasicRemoteModule } from './lifecycle/skeleton';

package/src/lifecycle/skeleton.ts

@@ -0,0 +1,154 @@
+/*
+ * 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.
+ */
+
+import type { App } from 'vue';
+import type { ModuleHostConfig, RemoteModule } from '../types/module';
+import type { ModuleLifecycleResult } from '../types/moduleLifecycle';
+
+/**
+ * Basic implementation of a remote module lifecycle.
+ *
+ * This class provides default implementations for all lifecycle hooks,
+ * allowing business modules to extend it and override only the hooks they need.
+ *
+ * All lifecycle hooks are optional and return success by default.
+ */
+export class BasicRemoteModule implements RemoteModule {
+  /**
+   * Unique identifier for the module.
+   *
+   * Must match the ID in the host configuration.
+   */
+  public readonly id: string;
+
+  /**
+   * Human-readable name of the module.
+   */
+  public readonly name: string;
+
+  /**
+   * Version of the module (semantic versioning).
+   */
+  public readonly version: string;
+
+  /**
+   * Optional description of what the module does.
+   */
+  public readonly description?: string;
+
+  /**
+   * Creates a new remote module instance.
+   * @param id - Unique module identifier (kebab-case).
+   * @param name - Human-readable module name.
+   * @param version - Module version (semver).
+   * @param description - Optional module description.
+   */
+  constructor(id: string, name: string, version: string, description?: string) {
+    this.id = id;
+    this.name = name;
+    this.version = version;
+    this.description = description;
+  }
+
+  /**
+   * Setup phase - validate dependencies and prepare the module.
+   *
+   * This is called first, before any other lifecycle phase.
+   * Use it to check if all required dependencies are available.
+   *
+   * Default implementation returns success.
+   * Override this method to add custom setup logic.
+   * @param _app - The Vue application instance.
+   * @returns Promise resolving to the lifecycle result.
+   */
+  async onSetup(_app: App): Promise<ModuleLifecycleResult> {
+    return { success: true };
+  }
+
+  /**
+   * Configure phase - receive and validate host configuration.
+   *
+   * This is called after setup, before initialization.
+   * Use it to receive and validate the configuration from the host.
+   *
+   * Default implementation returns success.
+   * Override this method to add custom configuration logic.
+   * @param _app - The Vue application instance.
+   * @param _config - Module-specific configuration from host.
+   * @returns Promise resolving to the lifecycle result.
+   */
+  async onConfigure(
+    _app: App,
+    _config: ModuleHostConfig
+  ): Promise<ModuleLifecycleResult> {
+    return { success: true };
+  }
+
+  /**
+   * Initialize phase - register stores and initialize resources.
+   *
+   * This is called after configuration.
+   * Use it to register Pinia stores and initialize module resources.
+   *
+   * Default implementation returns success.
+   * Override this method to add custom initialization logic.
+   * @param _app - The Vue application instance.
+   * @returns Promise resolving to the lifecycle result.
+   */
+  async onInitialize(_app: App): Promise<ModuleLifecycleResult> {
+    return { success: true };
+  }
+
+  /**
+   * Ready phase - signal that the module is ready for use.
+   *
+   * This is called after all modules are initialized.
+   * Use it to perform final checks and emit ready state.
+   *
+   * Default implementation returns success.
+   * Override this method to add custom ready logic.
+   * @param _app - The Vue application instance.
+   * @returns Promise resolving to the lifecycle result.
+   */
+  async onReady(_app: App): Promise<ModuleLifecycleResult> {
+    return { success: true };
+  }
+
+  /**
+   * Post-initialization phase - cross-module integrations.
+   *
+   * This is called after all modules are ready.
+   * Use it for cross-module integrations and final setup.
+   *
+   * Default implementation returns success.
+   * Override this method to add custom post-init logic.
+   * @param _app - The Vue application instance.
+   * @returns Promise resolving to the lifecycle result.
+   */
+  async onPostInit(_app: App): Promise<ModuleLifecycleResult> {
+    return { success: true };
+  }
+}

package/src/services/federationService.ts

@@ -0,0 +1,44 @@
+/*
+ * 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.
+ */
+
+import { loadRemote } from '@module-federation/enhanced/runtime';
+import { defineAsyncComponent } from 'vue';
+import type { RemoteComponentModule } from '../types/module';
+
+/**
+ * Loads a remote component using the module federation enhanced runtime.
+ * @param plugin - The name of the remote plugin component to load.
+ * @returns A Vue async component.
+ */
+export const loadAsyncComponent = (plugin: string) =>
+  defineAsyncComponent(() =>
+    loadRemote<RemoteComponentModule>(plugin).then((module) => {
+      if (!module?.default) {
+        throw new Error(`Failed to load component from ${plugin}`);
+      }
+      return module.default;
+    })
+  );