@beeq/angular 1.8.0-beta.9 → 1.8.0

package/README.md

@@ -4,24 +4,18 @@ An Angular-specific wrapper on top of BEEQ web components that enables NG_VALUE_
 
 ## Package installation
 
-- install the package
-
-```
-npm install @beeq/angular
-```
-
-- update the package
+> [!TIP]
+>  Please always refer to the [official BEEQ documentation](https://www.beeq.design/3d466e231/p/359a26-for-developers/b/08eb89) for more information about the installation.
 
-```
-npm install @beeq/angular@latest
-```
-
-if the `@beeq/core` package is added to your `package.json` should update both
+- install the package
 
 ```
 npm install @beeq/{core,angular}
 ```
 
+> [!NOTE]
+> Make sure that you have installed the `@beeq/core` package.
+
 ## Setup
 
 ### Call `defineCustomElements`
@@ -43,7 +37,10 @@ applyPolyfills().then(() => {
 
 ### Add BEEQ styles and assets
 
-> ❗️The icons SVG are shipped in a separate folder. Projects will need to include `node_modules/@beeq/core/dist/beeq/svg` in their build and try to make it in a certain way that it respond to: `http://<domain>/svg`
+> [!TIP]
+>  BEEQ uses SVG icons and these assets are shipped in a separate folder. You can use the `setBasePath` method to set the path to the icons. Make sure that your project bundle the icons in a way that they are accessible from the browser.
+
+You can move the icons from the node_modules folder to your assets folder and set the path like this:
 
 ```json
 /** angular.json */
@@ -65,7 +62,7 @@ applyPolyfills().then(() => {
               {
                 "glob": "**/*",
                 "input": "node_modules/@beeq/core/dist/beeq/svg",
-                "output": "/svg/"
+                "output": "assets/svg/"
               }
             ],
             "styles": [
@@ -81,6 +78,25 @@ applyPolyfills().then(() => {
 }
 ```
 
+```js
+// main.ts
+import { setBasePath } from '@beeq/core';
+
+setBasePath('/assets/svg/');
+```
+
+But you can also use a different icons library or a CDN (*no need to move the icons to your assets folder via angular.json*):
+
+```js
+import { setBasePath } from '@beeq/core';
+
+// Using heroicons library
+setBasePath('https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline');
+```
+
+> [!CAUTION]
+> When using a different icons library, make sure you use the correct icon names provided by the library or the CDN.
+
 BEEQ styles can be also imported into your application's main style file:
 
 ```css
@@ -112,7 +128,8 @@ export class AppModule {}
 
 To enable two-way binding and the use of [ngModel] within BEEQ form components, you will need to add the Value Accessors in your module declarations, along with `@angular/forms`.
 
-> ❗️❗️ *Please notice that* **you might need to disable** `aot` *for enabling two-way data binding**. Details: https://github.com/ionic-team/stencil-ds-output-targets/issues/317*
+> [!CAUTION]
+> *Please notice that* **you might need to disable** `aot` *for enabling two-way data binding**. Details: https://github.com/ionic-team/stencil-ds-output-targets/issues/317*
 
 ```ts
 import { NgModule } from '@angular/core';

package/eslint.config.js

@@ -0,0 +1,45 @@
+const { fixupPluginRules } = require('@eslint/compat');
+const nxESLint = require('@nx/eslint-plugin');
+const angularESLint = require('@angular-eslint/eslint-plugin');
+const jsoncParser = require('jsonc-eslint-parser');
+
+/** @type { import("eslint").Linter.Config[] } */
+module.exports = [
+  {
+    files: ['*.ts'],
+    plugins: {
+      '@angular-eslint': fixupPluginRules(angularESLint),
+    },
+    rules: {
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'bq',
+          style: 'kebab-case',
+        },
+      ],
+      '@angular-eslint/component-class-suffix': 'off',
+      '@angular-eslint/directive-class-suffix': 'off',
+      '@angular-eslint/directive-selector': 'off',
+      '@angular-eslint/no-host-metadata-property': 'off',
+    },
+  },
+  {
+    files: ['**/package.json', '**/project.json'],
+    languageOptions: {
+      parser: jsoncParser,
+    },
+    plugins: {
+      '@nx': nxESLint,
+    },
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredDependencies: ['@beeq/core', '@stencil/core', 'tslib'],
+        },
+      ],
+    },
+  },
+];

package/jest.config.ts

@@ -0,0 +1,21 @@
+export default {
+  displayName: 'beeq-angular',
+  preset: '../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  globals: {
+    'ts-jest': {
+      tsconfig: '<rootDir>/tsconfig.spec.json',
+      stringifyContentPathRegex: '\\.(html|svg)$',
+    },
+  },
+  coverageDirectory: '../../coverage/packages/beeq-angular',
+  transform: {
+    '^.+\\.(ts|mjs|js|html)$': 'jest-preset-angular',
+  },
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/html-comment',
+  ],
+};

package/ng-package.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/beeq-angular",
+  "lib": {
+    "entryFile": "src/index.ts"
+  },
+  "allowedNonPeerDependencies": ["@beeq/core", "jsonc-parser"]
+}

package/package.json

@@ -1,40 +1,21 @@
 {
-    "name": "@beeq/angular",
-    "version": "1.8.0-beta.9",
-    "license": "Apache-2.0",
-    "description": "Angular specific wrapper for BEEQ Design System components",
-    "main": "dist/esm2015/index.js",
-    "module": "fesm2022/beeq-angular.mjs",
-    "types": "index.d.ts",
-    "dependencies": {
-        "@beeq/core": "^1.8.0-beta.9",
-        "tslib": "^2.6.3"
-    },
-    "peerDependencies": {
-        "@angular/common": ">=14.0.0",
-        "@angular/core": ">=14.0.0"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/Endava/BEEQ"
-    },
-    "typings": "index.d.ts",
-    "exports": {
-        "./package.json": {
-            "default": "./package.json"
-        },
-        ".": {
-            "types": "./index.d.ts",
-            "esm2022": "./esm2022/beeq-angular.mjs",
-            "esm": "./esm2022/beeq-angular.mjs",
-            "default": "./fesm2022/beeq-angular.mjs"
-        },
-        "./standalone": {
-            "types": "./standalone/index.d.ts",
-            "esm2022": "./esm2022/standalone/beeq-angular-standalone.mjs",
-            "esm": "./esm2022/standalone/beeq-angular-standalone.mjs",
-            "default": "./fesm2022/beeq-angular-standalone.mjs"
-        }
-    },
-    "sideEffects": false
-}
+  "name": "@beeq/angular",
+  "version": "1.8.0",
+  "license": "Apache-2.0",
+  "description": "Angular specific wrapper for BEEQ Design System components",
+  "main": "dist/esm2015/index.js",
+  "module": "dist/esm2015/index.js",
+  "types": "index.d.ts",
+  "dependencies": {
+    "@beeq/core": "^1.8.0",
+    "tslib": "^2.6.3"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=14.0.0",
+    "@angular/core": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Endava/BEEQ"
+  }
+}

package/project.json

@@ -0,0 +1,41 @@
+{
+  "name": "beeq-angular",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/beeq-angular/src",
+  "projectType": "library",
+  "tags": ["wrapper", "angular", "publishable"],
+  "prefix": "beeq",
+  "implicitDependencies": ["beeq"],
+  "targets": {
+    "prebuild": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["tsx packages/beeq-angular/scripts/fix-value-accessor-path.ts"]
+      },
+      "dependsOn": [{ "dependencies": true, "target": "build" }]
+    },
+    "build": {
+      "executor": "@nx/angular:package",
+      "outputs": ["{workspaceRoot}/dist/beeq-angular"],
+      "options": {
+        "project": "{projectRoot}/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "{projectRoot}/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "{projectRoot}/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production",
+      "dependsOn": [{ "target": "prebuild" }]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "lintFilePatterns": ["{projectRoot}/**/*.ts", "{projectRoot}/package.json", "{projectRoot}/project.json"]
+      }
+    }
+  }
+}

package/scripts/fix-value-accessor-path.ts

@@ -0,0 +1,94 @@
+import { resolve } from 'path';
+import { promises as fs } from 'fs';
+
+['module', 'standalone'].forEach((type) => {
+  fixValueAccessorPath(type);
+});
+
+/**
+ * Fix the value accessor path by moving the file to the correct path
+ *
+ * @param {string} type - The type of the Angular project (module or standalone)
+ */
+async function fixValueAccessorPath(type: string): Promise<void> {
+  const angularProjectPath = type === 'module' ? '.' : 'standalone';
+
+  // Define the folders and files paths
+  const basePath = resolve(__dirname, `../${angularProjectPath}/src/directives`).replace(/\\/g, '/');
+  const wrongFolderPath = `${basePath}/value-accessor.ts`;
+  const backupFolderPath = `${basePath}/value-accessor`;
+  const sourceFilePath = `${basePath}/value-accessor/value-accessor.ts`;
+  const destinationFilePath = wrongFolderPath;
+
+  // Check if the wrong file exists
+  if (await isDirectory(wrongFolderPath)) {
+    console.info(`Renaming wrong Value Accessor file for angular ${type} project...`);
+    await renameDirectory(wrongFolderPath, backupFolderPath);
+  } else {
+    console.info(`No changes required! Wrong folder does not exist for angular ${type} project`);
+    return;
+  }
+
+  // Move the file to the correct path
+  if (await isDirectory(backupFolderPath)) {
+    console.info(`Moving wrong Value Accessor file for angular ${type} project to the correct path...`);
+
+    try {
+      await moveFile(sourceFilePath, destinationFilePath);
+      await removeDirectory(backupFolderPath);
+      console.info(`File moved successfully for angular ${type} project to the correct path.`);
+    } catch (err) {
+      console.error(`Error moving the file for angular ${type} project`, err);
+      process.exit(1); // Exit the process with a failure code
+    }
+  } else {
+    console.warn(`No changes required! Source folder does not exist for angular ${type} project`);
+  }
+}
+
+/**
+ * Check if a path exists and is a directory
+ *
+ * @param {string} path - The path to check
+ * @returns {Promise<boolean>}
+ */
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(path);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rename a directory
+ *
+ * @param {string} oldPath - The current path of the directory
+ * @param {string} newPath - The new path of the directory
+ * @returns {Promise<void>}
+ */
+async function renameDirectory(oldPath: string, newPath: string): Promise<void> {
+  await fs.rename(oldPath, newPath);
+}
+
+/**
+ * Move a file
+ *
+ * @param {string} source - The source file path
+ * @param {string} destination - The destination file path
+ * @returns {Promise<void>}
+ */
+async function moveFile(source: string, destination: string): Promise<void> {
+  await fs.rename(source, destination);
+}
+
+/**
+ * Remove a directory
+ *
+ * @param {string} path - The path of the directory to remove
+ * @returns {Promise<void>}
+ */
+async function removeDirectory(path: string): Promise<void> {
+  await fs.rmdir(path);
+}

package/src/beeq.module.ts

@@ -0,0 +1,41 @@
+import { CommonModule, DOCUMENT } from '@angular/common';
+import { APP_INITIALIZER, ModuleWithProviders, NgModule, NgZone } from '@angular/core';
+import { defineCustomElements } from '@beeq/core/dist/loader';
+
+import { DIRECTIVES } from './directives';
+import { BooleanValueAccessor } from './directives/boolean-value-accessor';
+import { NumericValueAccessor } from './directives/number-value-accessor';
+import { RadioValueAccessor } from './directives/radio-value-accessor';
+import { SelectValueAccessor } from './directives/select-value-accessor';
+import { TextValueAccessor } from './directives/text-value-accessor';
+
+const DECLARATIONS = [
+  ...DIRECTIVES,
+  // ngModel Accessors
+  BooleanValueAccessor,
+  NumericValueAccessor,
+  RadioValueAccessor,
+  SelectValueAccessor,
+  TextValueAccessor,
+];
+
+@NgModule({
+  imports: [CommonModule],
+  declarations: DECLARATIONS,
+  exports: DECLARATIONS,
+})
+export class BeeQModule {
+  static forRoot(): ModuleWithProviders<BeeQModule> {
+    return {
+      ngModule: BeeQModule,
+      providers: [
+        {
+          provide: APP_INITIALIZER,
+          useFactory: () => defineCustomElements,
+          multi: true,
+          deps: [DOCUMENT, NgZone],
+        },
+      ],
+    };
+  }
+}

package/src/directives/angular-component-lib/utils.ts

@@ -0,0 +1,65 @@
+/* eslint-disable */
+/* tslint:disable */
+import { fromEvent } from 'rxjs';
+
+export const proxyInputs = (Cmp: any, inputs: string[]) => {
+  const Prototype = Cmp.prototype;
+  inputs.forEach((item) => {
+    Object.defineProperty(Prototype, item, {
+      get() {
+        return this.el[item];
+      },
+      set(val: any) {
+        this.z.runOutsideAngular(() => (this.el[item] = val));
+      },
+      /**
+       * In the event that proxyInputs is called
+       * multiple times re-defining these inputs
+       * will cause an error to be thrown. As a result
+       * we set configurable: true to indicate these
+       * properties can be changed.
+       */
+      configurable: true,
+    });
+  });
+};
+
+export const proxyMethods = (Cmp: any, methods: string[]) => {
+  const Prototype = Cmp.prototype;
+  methods.forEach((methodName) => {
+    Prototype[methodName] = function () {
+      const args = arguments;
+      return this.z.runOutsideAngular(() => this.el[methodName].apply(this.el, args));
+    };
+  });
+};
+
+export const proxyOutputs = (instance: any, el: any, events: string[]) => {
+  events.forEach((eventName) => (instance[eventName] = fromEvent(el, eventName)));
+};
+
+export const defineCustomElement = (tagName: string, customElement: any) => {
+  if (customElement !== undefined && typeof customElements !== 'undefined' && !customElements.get(tagName)) {
+    customElements.define(tagName, customElement);
+  }
+};
+
+// tslint:disable-next-line: only-arrow-functions
+export function ProxyCmp(opts: { defineCustomElementFn?: () => void; inputs?: any; methods?: any }) {
+  const decorator = function (cls: any) {
+    const { defineCustomElementFn, inputs, methods } = opts;
+
+    if (defineCustomElementFn !== undefined) {
+      defineCustomElementFn();
+    }
+
+    if (inputs) {
+      proxyInputs(cls, inputs);
+    }
+    if (methods) {
+      proxyMethods(cls, methods);
+    }
+    return cls;
+  };
+  return decorator;
+}

package/src/directives/boolean-value-accessor.ts

@@ -0,0 +1,27 @@
+import { Directive, ElementRef } from '@angular/core';
+import { NG_VALUE_ACCESSOR } from '@angular/forms';
+
+import { ValueAccessor } from './value-accessor';
+
+@Directive({
+  /* tslint:disable-next-line:directive-selector */
+  selector: 'bq-checkbox, bq-switch',
+  host: {
+    '(bqChange)': 'handleChangeEvent($event.target.checked)'
+  },
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: BooleanValueAccessor,
+      multi: true
+    }
+  ]
+})
+export class BooleanValueAccessor extends ValueAccessor {
+  constructor(el: ElementRef) {
+    super(el);
+  }
+  override writeValue(value: any) {
+    this.el.nativeElement.checked = this.lastValue = value == null ? false : value;
+  }
+}