@sumaris-net/ngx-components 18.11.0 → 18.12.0

package/src/app/shared/markdown/markdown.service.ts

@@ -0,0 +1,234 @@
+import { inject, Injectable } from '@angular/core';
+import { ActivatedRoute, Router, UrlTree } from '@angular/router';
+import { NavController } from '@ionic/angular';
+import { LocationStrategy } from '@angular/common';
+import { MarkedRenderer } from 'ngx-markdown';
+import { UrlUtils } from '../file/url.utils';
+import { Subject, Subscription } from 'rxjs';
+import { isNotNilOrBlank } from '../functions';
+import { MarkdownUtils } from './markdown.utils';
+import { PlatformService } from '../../core/services/platform.service';
+
+@Injectable({ providedIn: 'root' })
+export class MarkdownService {
+  private route = inject(ActivatedRoute);
+  private router = inject(Router);
+  private platform = inject(PlatformService);
+  private locationStrategy = inject(LocationStrategy);
+  private navController = inject(NavController);
+
+  private baseUrl: string;
+
+  private readonly _defaultRenderer = new MarkedRenderer();
+  private _markedRenderer: MarkedRenderer;
+
+  get renderer(): MarkedRenderer {
+    return this._markedRenderer;
+  }
+
+  set renderer(value: MarkedRenderer) {
+    this.setRenderer(value);
+  }
+
+  onClickMarkdownUrl = new Subject<string>();
+
+  constructor() {
+    this.setRenderer(new MarkedRenderer());
+  }
+
+  setBaseUrl(baseUrl: string) {
+    console.debug('[markdown-service] Base URL: ' + baseUrl);
+    this.baseUrl = baseUrl;
+  }
+
+  resetBaseUrl() {
+    this.setBaseUrl(null);
+  }
+
+  getUrlTree(url: string): UrlTree {
+    url = UrlUtils.normalizeUrl(url);
+    const urlPath = UrlUtils.stripFragmentAndQuery(url) || UrlUtils.stripFragmentAndQuery(this.router.url);
+    const parsedUrl = this.router.parseUrl(url);
+    const fragment = parsedUrl.fragment;
+    const queryParams = parsedUrl.queryParams;
+    return this.router.createUrlTree([urlPath], { relativeTo: this.route, fragment, queryParams });
+  }
+
+  navigate(url: string, replaceUrl = false) {
+    const urlTree = this.getUrlTree(url);
+    this.router.navigated = false;
+    this.navController.navigateForward(urlTree, { replaceUrl });
+  }
+
+  listenClickEvents(nativeElement: HTMLElement): Subscription {
+    console.debug('[markdown-service] Start listening click events...');
+    const subscription = new Subscription();
+    const listener = (event: Event) => this.click(event, nativeElement);
+    const links = nativeElement.querySelectorAll('a');
+    links.forEach((link) => {
+      // DEBUG
+      //console.debug('[markdown-service] Adding click listener to', link);
+      link.addEventListener('click', listener);
+      subscription.add(() => link.removeEventListener('click', listener));
+    });
+
+    // DEBUG
+    subscription.add(() => console.debug('[markdown-service] Stop listening click events'));
+
+    return subscription;
+  }
+
+  /**
+   * Transform a relative URL to its absolute representation according to current router state.
+   * @param url Relative URL path.
+   * @return Absolute URL based on the current route.
+   */
+  normalizeUrl(url: string): string {
+    if (UrlUtils.isExternalUrl(url)) {
+      return url;
+    }
+    if (this.baseUrl && UrlUtils.isRelativeUrl(url)) {
+      return MarkdownUtils.resolveRelativeUrl(this.baseUrl, url);
+    }
+
+    const urlTree = this.getUrlTree(url);
+    const serializedUrl = this.router.serializeUrl(urlTree);
+    return this.locationStrategy.prepareExternalUrl(serializedUrl);
+  }
+
+  scrollToAnchor(containerElement: HTMLElement, anchorId: string) {
+    if (!containerElement || !anchorId) {
+      console.warn("Missing 'containerElement' or 'fragment' argument.");
+      return;
+    }
+
+    console.debug('[markdown-anchor] Scrolling to anchor #' + anchorId);
+
+    // Find the target element with the specified fragment ID
+    let targetElement = containerElement.querySelector(`#${anchorId}`);
+
+    // If not found, retry fix a fixed anchor id. This can occur when ToC has been generated for the maven-markdown-plugin
+    if (!targetElement) {
+      targetElement = containerElement.querySelector(`#${MarkdownUtils.fixAnchor(anchorId)}`);
+    }
+
+    if (targetElement) {
+      // Scroll smoothly to the target element
+      targetElement.scrollIntoView({
+        behavior: 'smooth', // Smooth scrolling behavior
+        block: 'start', // Align the target element to the top of the container
+      });
+    } else {
+      console.warn(`No element found with the ID "${anchorId}" inside the container.`);
+    }
+  }
+
+  /* -- protected function -- */
+
+  protected setRenderer(renderer: MarkedRenderer) {
+    console.debug('[markdown-service] Set renderer', renderer);
+    renderer.link = (href, title, text) => this.link(href, title, text);
+    renderer.image = (href, title, text) => this.image(href, title, text);
+    renderer.heading = (text, level, raw) => this.heading(text, level, raw);
+    this._markedRenderer = renderer;
+  }
+
+  protected async click(event: Event, containerElement: HTMLElement): Promise<boolean> {
+    console.debug('[markdown-service] Processing click event...', event);
+
+    if (!(event.target instanceof HTMLAnchorElement) && !(event.target?.['tagName'] === 'A')) {
+      console.warn('[markdown-service] Invalid click event target. Should an anchor <a>', event.target);
+      return;
+    }
+
+    const element = event.target as HTMLAnchorElement;
+
+    let href = element.getAttribute('href');
+    const fragment = UrlUtils.getFragment(href);
+
+    // Fragment
+    if (href?.startsWith('#') && isNotNilOrBlank(fragment)) {
+      event.preventDefault();
+      this.scrollToAnchor(containerElement, fragment);
+      return true;
+    }
+
+    const routerLink = element.getAttribute('routerLink');
+    if (isNotNilOrBlank(routerLink)) {
+      event.preventDefault();
+      return this.navController.navigateForward(routerLink);
+    }
+
+    // Resolve relative URL, if baseUrl has been set
+    if (this.baseUrl && UrlUtils.isRelativeUrl(href)) {
+      if (MarkdownUtils.isMarkdownFile(href) && this.onClickMarkdownUrl.observed) {
+        event.preventDefault();
+        this.onClickMarkdownUrl.next(href);
+        return true;
+      }
+
+      // Resolve URL, then open using the platform
+      href = MarkdownUtils.resolveRelativeUrl(this.baseUrl, href);
+    }
+
+    // Resolve internal URL as an app route
+    if (UrlUtils.isInternalUrl(href)) {
+      const routePath = this.normalizeUrl(href.startsWith('/') ? href : `/${href}`);
+      const urlTree = this.getUrlTree(routePath);
+      event.preventDefault();
+      this.router.navigated = false;
+      // Opening route
+      return this.navController.navigateForward(urlTree);
+    }
+
+    // External URL: open using the platform
+    event.preventDefault();
+    await this.platform.open(href);
+    return true;
+  }
+
+  protected link(href: string | null, title: string | null, text: string): string {
+    // Resolve router links
+    if (UrlUtils.isInternalUrl(href) && !href.startsWith('#') && !this.baseUrl && !MarkdownUtils.isMarkdownFile(href)) {
+      const externalUrl = this.normalizeUrl(href);
+      return `<a href="${externalUrl}" routerLink="${href}" title="${title || ''}">${text}</a>`;
+    }
+    return `<a href="${href || ''}" title="${title || ''}">${text}</a>`;
+  }
+
+  protected image(href: string, title: string | null, text: string): string {
+    let url = href;
+    let fallbackUrl: string;
+    if (UrlUtils.isRelativeUrl(href) && this.baseUrl) {
+      // Resolve relative path
+      url = MarkdownUtils.resolveRelativeUrl(this.baseUrl, href);
+
+      // Compute a fallback URL
+      fallbackUrl = MarkdownUtils.resolveRelativeUrl(this.baseUrl, href, { absoluteByDefault: true });
+      fallbackUrl = fallbackUrl === url ? null : fallbackUrl;
+
+      // DEBUG
+      console.debug(`[markdown-service] Replacing image: ${href} -> ${url}`);
+
+      if (fallbackUrl) {
+        const fallbackHtml = `<img src="${fallbackUrl}" title="${title || ''}" alt="${text}" onerror="this.style.display='none';" />`;
+        return `<img src="${url}" title="${title || ''}" alt="${text}" onerror="this.style.display='none';" />` + fallbackHtml;
+      } else {
+        return this._defaultRenderer.image(url, title, text);
+      }
+    }
+    return this._defaultRenderer.image(url, title, text);
+  }
+
+  protected heading(text: string, level: number, raw: string): string {
+    // If NOT the h1 (document title)
+    const anchor = MarkdownUtils.textToAnchor(text);
+    if (isNotNilOrBlank(anchor)) {
+      const pageBreak = level < 2;
+      console.debug(`[markdown-service] Heading ${level} '${text}' with anchor ${anchor}`);
+      const link = `<a id="${anchor}" class="anchor ${pageBreak ? 'page-break' : ''}" aria-hidden="true" href="#${anchor}"></a>`;
+      return this._defaultRenderer.heading(link + text, level, raw);
+    }
+    return this._defaultRenderer.heading(text, level, raw);
+  }
+}

package/src/app/shared/markdown/markdown.utils.ts

@@ -0,0 +1,90 @@
+import { UriUtils } from '../file/uri.utils';
+import { UrlUtils } from '../file/url.utils';
+
+export class MarkdownUtils {
+  static readonly HTML_ENTITIES_MAP: { [entity: string]: string } = {
+    ''': "'", // Single quote
+    '"': '"', // Double quote
+    '&': '&', // Ampersand
+    '&lt;': '<', // Less-than
+    '&gt;': '>', // Greater-than
+    '&nbsp;': ' ', // Non-breaking space
+    // Add more entities here if needed
+  };
+
+  /**
+   * Converts the given text into a valid anchor-compatible format.
+   *
+   * @param {string} text - The input text to be transformed into an anchor.
+   * @return {string} The formatted string suitable for use as an anchor.
+   */
+  static textToAnchor(text: string): string {
+    if (!text) return '';
+    return (
+      text
+        .toLowerCase()
+        .trim()
+        // Replace entities
+        .replace(/&#?[a-z0-9]+;/g, (entity) => this.HTML_ENTITIES_MAP[entity] || '')
+        .replace(/['"&<>=\\()]+/g, '')
+        .replace(/\s/g, '-')
+        .replace(/^-|-$/g, '-')
+    );
+  }
+
+  /**
+   * Adjusts the given anchor ID by replacing underscores with hyphens and converting to lowercase.
+   *
+   * @param {string} anchorId - The anchor ID string to be fixed.
+   * @return {string} The modified anchor ID with underscores replaced by hyphens and converted to lowercase, or the original anchor ID if it is falsy.
+   */
+  static fixAnchor(anchorId: string): string {
+    if (!anchorId) return anchorId;
+    return anchorId.replace(/_/g, '-').toLowerCase();
+  }
+
+  static isMarkdownFile(url: string) {
+    if (!url) return false;
+    const cleanUrl = UrlUtils.stripFragmentAndQuery(url);
+    const filename = UriUtils.getFilename(cleanUrl);
+    return filename.endsWith('.md');
+  }
+
+  static resolveRelativeUrl(baseUrl: string, relativePath: string, opts?: { absoluteByDefault: boolean }) {
+    if (!baseUrl) throw new Error("Argument 'baseUrl' is missing");
+    if (!relativePath) throw new Error("Argument 'relativePath' is missing");
+    if (!UrlUtils.isRelativeUrl(relativePath)) throw new Error('Should be a relative path');
+
+    // Detect absolute URL
+    if (relativePath.startsWith('/') || (opts?.absoluteByDefault && !relativePath.startsWith('.'))) {
+      baseUrl = this.getRootUrl(baseUrl);
+      relativePath = relativePath.startsWith('/') ? relativePath.substring(1) : relativePath;
+    }
+
+    return UrlUtils.normalizeUrl(UrlUtils.concat(baseUrl, relativePath));
+  }
+
+  static isGitlabUrl(url: string) {
+    if (!url) return false;
+    return url.startsWith('https://gitlab.') || url.includes('/-/raw/') || url.includes('/-/blob/');
+  }
+
+  static fixGitlabUrlToRaw(url: string) {
+    if (!this.isGitlabUrl(url)) return url;
+    return url.replace('/-/blob/', '/-/raw/').replace('/-/tree/', '/-/raw/');
+  }
+
+  static getRootUrl(url: string) {
+    if (this.isGitlabUrl(url)) {
+      console.debug('[markdown] Gitlab URL detected: ' + url);
+      url = url.replace('/-/blob/', '/-/raw/');
+      if (url.includes('/-/raw/')) {
+        const index = url.indexOf('/-/raw/') + '/-/raw/'.length;
+        const rootPath = url.substring(0, index);
+        const branch = url.substring(index).split('/', 2)[0];
+        return rootPath + branch;
+      }
+    }
+    return UrlUtils.getRootUrl(url);
+  }
+}

package/src/app/shared/markdown/testing/markdown.test.html

@@ -0,0 +1,50 @@
+<ion-header>
+  <ion-toolbar color="primary">
+    <ion-buttons slot="start">
+      @if (content.canGoBack) {
+        <ion-button class="back-button" (click)="content.goBack($event)" routerDirection="back">
+          <ion-icon slot="icon-only" name="arrow-back"></ion-icon>
+        </ion-button>
+      } @else {
+        <ion-back-button></ion-back-button>
+      }
+    </ion-buttons>
+
+    <ion-title>Markdown test page</ion-title>
+
+    <ion-buttons slot="end">
+      <ion-button slot="end" (click)="content.print()">
+        <ion-icon slot="icon-only" name="print"></ion-icon>
+      </ion-button>
+
+      <ion-button (click)="openHelpModal($event)">Open in modal</ion-button>
+    </ion-buttons>
+  </ion-toolbar>
+</ion-header>
+
+<ion-content class="ion-padding">
+  <ion-input
+    #input
+    fill="outline"
+    [ngModel]="markdownUrl"
+    placeholder="Markdown URL"
+    label="URL: "
+    (keyup.enter)="onSubmit($event, input.value)"
+  >
+    <ion-button
+      slot="end"
+      [fill]="markdownUrl !== input.value ? 'solid' : 'clear'"
+      (click)="onSubmit($event, input.value)"
+    >
+      {{ 'COMMON.BTN_OK' | translate }}
+    </ion-button>
+  </ion-input>
+
+  <app-markdown-content
+    #content
+    [src]="markdownUrl"
+    enableNavigationHistory="true"
+    [debug]="debug"
+    (markdownUrlChange)="updateInputUrl($event)"
+  ></app-markdown-content>
+</ion-content>

package/src/app/shared/markdown/testing/markdown.test.ts

@@ -0,0 +1,49 @@
+import { ChangeDetectionStrategy, ChangeDetectorRef, Component, Inject } from '@angular/core';
+import { AppMarkdownModal } from '../markdown.modal';
+import { ModalController } from '@ionic/angular';
+import { Environment, ENVIRONMENT } from '../../../../environments/environment.class';
+
+@Component({
+  selector: 'app-markdown-test',
+  templateUrl: './markdown.test.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MarkdownTestPage {
+  protected markdownModalTitle = 'Markdown modal';
+  protected debug: boolean;
+
+  // URL from a starting markdown
+  //protected markdownUrl = 'http://localhost:3000/user-manual/index.md';
+  protected markdownUrl = 'https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-doc/-/raw/master/projects/pifil/man/quick_start_guide_fr.md';
+  //protected markdownUrl = 'https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-doc/-/raw/master/README.md';
+  //protected markdownUrl = 'https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-doc/-/raw/master/model/index.md';
+  //protected markdownUrl = 'https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-doc/-/raw/master/model/administration/index.md';
+  //protected markdownUrl ='https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-doc/-/raw/master/projects/activity-calendar/spe/collecte_de_donnees.md';
+  //protected markdownUrl ='https://gitlab.ifremer.fr/sih-public/sumaris/sumaris-app/-/raw/develop/doc/privacy_policy.md';
+
+  constructor(
+    private modalCtrl: ModalController,
+    private cd: ChangeDetectorRef,
+    @Inject(ENVIRONMENT) protected environment: Environment
+  ) {
+    this.debug = !environment.production;
+  }
+
+  onSubmit(event: Event, newUrl: string | number) {
+    this.markdownUrl = '' + newUrl;
+    this.cd.markForCheck();
+  }
+
+  updateInputUrl(url: string) {
+    this.markdownUrl = url;
+    this.cd.markForCheck();
+  }
+
+  openHelpModal(event: Event) {
+    return AppMarkdownModal.show(this.modalCtrl, {
+      title: this.markdownModalTitle,
+      src: this.markdownUrl,
+      canPrint: true,
+    });
+  }
+}

package/src/app/shared/markdown/testing/markdown.testing.module.ts

@@ -0,0 +1,22 @@
+import { RouterModule, Routes } from '@angular/router';
+import { SharedModule } from '../../shared.module';
+import { CommonModule } from '@angular/common';
+import { NgModule } from '@angular/core';
+import { MarkdownTestPage } from './markdown.test';
+import { FormsModule } from '@angular/forms';
+import { SharedMarkdownModule } from '../markdown.module';
+
+const routes: Routes = [
+  {
+    path: 'markdown',
+    pathMatch: 'full',
+    component: MarkdownTestPage,
+  },
+];
+
+@NgModule({
+  imports: [CommonModule, RouterModule.forChild(routes), SharedModule, FormsModule, SharedMarkdownModule],
+  declarations: [MarkdownTestPage],
+  exports: [RouterModule, MarkdownTestPage],
+})
+export class MarkdownTestingModule {}

package/src/app/shared/material/autocomplete/material.autocomplete.config.ts

@@ -0,0 +1,127 @@
+import { SuggestFn, SuggestService } from '../../services/entity-service.class';
+import { MatAutocompleteFieldUtils } from './material.autocomplete.utils';
+import { Observable } from 'rxjs';
+import { DisplayFn, EqualsFn } from '../../form/field.model';
+
+export declare interface MatAutocompleteFieldConfig<T = any, F = any> {
+  attributes?: string[];
+  suggestFn?: SuggestFn<T, F>;
+  filter?: Partial<F>;
+  items?: Observable<T[]> | T[];
+  columnSizes?: (number | 'auto' | undefined)[];
+  columnNames?: (string | undefined)[];
+  multiple?: boolean;
+  displayWith?: DisplayFn;
+  displayWithSeparator?: string; // Use to split searchText before searching
+  splitSearchText?: boolean; // Split searchText before searching? (will use the first value)
+  trimSearchText?: boolean; // Trim searchText before searching?
+  clearInvalidSearchTextOnBlur?: boolean; // Clear invalid text, on blur (false by default)
+  equals?: EqualsFn; // Used by <mat-chips-field>
+  showAllOnFocus?: boolean;
+  showPanelOnFocus?: boolean;
+  reloadItemsOnFocus?: boolean;
+  mobile?: boolean;
+  debounceTime?: number;
+  suggestLengthThreshold?: number;
+  highlightAccent?: boolean;
+  applyImplicitValue?: boolean;
+
+  /**
+   * Should select input content (desktop only)
+   */
+  selectInputContentOnFocus?: boolean;
+
+  /**
+   * Add a delay (ms) before trying to select input content (desktop only)
+   */
+  selectInputContentOnFocusDelay?: number;
+
+  /**
+   * If true, any invalid value entered in the input field will be cleared when the input loses focus.
+   * This helps in preventing invalid data to be displayed on the field
+   */
+  clearInvalidValueOnBlur?: boolean;
+
+  /**
+   * Determines whether the implicit value is preview in the input text field or not (desktop only).
+   *
+   * If not specified, the default behavior is to not preview implicit values (`false`).
+   *
+   * @type {boolean}
+   */
+  previewImplicitValue?: boolean;
+
+  /**
+   * Class to apply to the `div.mat-mdc-select-panel`
+   */
+  panelClass?: string;
+
+  /**
+   * Allow to fix panel width (e.g. '500px' or '100vw')
+   */
+  panelWidth?: string;
+
+  /**
+   * @deprecated use `panelClass` instead
+   */
+  class?: string;
+}
+
+export declare interface MatAutocompleteFieldAddOptions<T = any, F = any> extends Partial<MatAutocompleteFieldConfig<T, F>> {
+  service?: SuggestService<T, F>;
+}
+
+export class MatAutocompleteConfigHolder {
+  fields: {
+    [key: string]: MatAutocompleteFieldConfig;
+  } = {};
+
+  getUserAttributes: (fieldName: string, defaultAttributes?: string[]) => string[];
+
+  constructor(
+    private options?: {
+      getUserAttributes: (fieldName: string, defaultAttributes?: string[]) => string[];
+    }
+  ) {
+    // Store the function from options (e.g. get from user settings)
+    // or create a default function
+    this.getUserAttributes = options?.getUserAttributes || ((fieldName, defaultAttributes) => defaultAttributes || ['label', 'name']);
+  }
+
+  add<T = any, F = any>(fieldName: string, options?: MatAutocompleteFieldAddOptions<T, F>): MatAutocompleteFieldConfig<T, F> {
+    if (!fieldName) {
+      throw new Error('Unable to add config, with name: ' + (fieldName || 'undefined'));
+    }
+    options = options || <MatAutocompleteFieldAddOptions>{};
+    const suggestFn: SuggestFn<T, F> = options.suggestFn || (options.service && ((v, f) => options.service.suggest(v, f))) || undefined;
+    const attributes = this.getUserAttributes(fieldName, options.attributes) || ['label', 'name'];
+    // Keep original the function from options, when exists
+    const attributesOrFn = attributes.map((a, index) => (typeof a === 'function' && options.attributes[index]) || a);
+    const filter: Partial<F> = {
+      searchAttribute: attributes.length === 1 ? attributes[0] : undefined,
+      searchAttributes: attributes.length > 1 ? attributes : undefined,
+      ...options.filter,
+    };
+    const displayWith = options.displayWith || MatAutocompleteFieldUtils.createDisplayFn(attributes, options.multiple);
+    const equals = options.equals || MatAutocompleteFieldUtils.defaultEquals;
+
+    const config: MatAutocompleteFieldConfig = {
+      ...options,
+      attributes: attributesOrFn,
+      suggestFn,
+      filter,
+      displayWith,
+      equals,
+    };
+
+    this.fields[fieldName] = config;
+    return config;
+  }
+
+  get<T = any>(fieldName: string): MatAutocompleteFieldConfig<T> {
+    if (!fieldName) {
+      throw new Error('Unable to add config, with name: ' + (fieldName || 'undefined'));
+    }
+    return this.fields[fieldName] || (this.add(fieldName) as MatAutocompleteFieldConfig<T>);
+  }
+}