Autocomplete fields

Copy of sumaris-app/.agents/rules/autocomplete.md (rule written for AI coding agents, when creating or modifying autocomplete fields in forms or tables). Do not edit here: run npm run site:sync-rules to update it.

Autocomplete fields are managed via MatAutocompleteFieldConfig and registered in components (Forms or Tables) using registerAutocompleteField().

Registration

In a Form (AppForm)

Registration is usually done in ngOnInit():

this.registerAutocompleteField('fieldName', {
  service: this.myService,
  filter: { ... },
  // other options
});

In a Table (AppTable)

Registration is usually done in registerAutocompleteFields() (or ngOnInit()):

this.registerAutocompleteField('columnName', {
  service: this.myService,
  filter: { ... },
  // other options
});

Configuration Options (MatAutocompleteFieldAddOptions)

Using a Service (Referential)

This is the most common case for referentials.

• service: The service to use for loading data (must implement loadAll or suggest);
• filter: Initial filter to apply (e.g., entityName, statusIds);

this.registerAutocompleteField('matrix', {
  service: this.referentialRefService,
  filter: <ReferentialRefFilter>{
    entityName: 'Matrix',
    statusIds: [StatusIds.ENABLE, StatusIds.TEMPORARY],
  },
});

Using a Static List

• items: An array of objects to display in the dropdown;

this.registerAutocompleteField('taxonGroup', {
  items: this.availableTaxonGroups,
});

Using a custom suggestion function (suggestFn)

Use suggestFn for complex logic or when the service doesn't follow the standard pattern.

• suggestFn: (value: string, filter?: any) => Observable<E[]> | Promise<E[]>;

this.registerAutocompleteField('taxonName', {
  suggestFn: (value: any, options?: any) => this.suggestTaxonNames(value, options),
});

UI Configuration (MatAutocompleteFieldConfig)

Display and Selection

• displayWith: Function to format the selected value in the input;
• attributes: List of properties to display in the result columns;
• columnNames: (Optional) I18n keys for column headers;
• columnSizes: (Optional) Width of each column (e.g., [1, 2, 'auto']);
• panelClass: (Optional) CSS class for the autocomplete panel (e.g., 'full-width');

this.registerAutocompleteField('recorderPerson', {
  service: this.personService,
  attributes: ['lastName', 'firstName', 'department.name'],
  displayWith: (person) => `${person.lastName} ${person.firstName}`,
});

Table specific options (MatAutocompleteFieldAddOptions)

• mobile: Set to this.mobile to use a specific UI on mobile devices;
• config: (Optional) Base configuration to extend;

Usage in Template

Once registered, the configuration is available through the autocompleteFields object in the component (provided by AppForm or AppTable).

In a Form (AppForm)

Use the mat-autocomplete-field component and bind the [config] property:

<mat-autocomplete-field
  formControlName="matrix"
  [config]="autocompleteFields.fieldName"
  [placeholder]="'TRIP.SAMPLE.EDIT.FIELD_NAME' | translate"
  required
>
  <ion-icon matPrefix name="contract"></ion-icon>
</mat-autocomplete-field>

In a Table (AppTable)

In a table, the [config] is usually passed to the mat-autocomplete-field within a mat-cell:

<ng-container matColumnDef="fieldName">
  <th mat-header-cell *matHeaderCellDef mat-sort-header translate>MY.TABLE.FIELD_NAME</th>
  <td mat-cell *matCellDef="let row">
    <mat-autocomplete-field
      [formControl]="row.validator.controls['fieldName']"
      [config]="autocompleteFields.fieldName"
      [readonly]="!row.editing"
    ></mat-autocomplete-field>
  </td>
</ng-container>

Common Patterns

Referential with entityName

When using ReferentialRefService, always specify the entityName in the filter.

this.registerAutocompleteField('location', {
  service: this.referentialRefService,
  filter: {
    entityName: 'Location', // Required when using ReferentialRefService 
    statusIds: [StatusIds.ENABLE, StatusIds.TEMPORARY],
  },
});

Extending existing configuration

Some common configurations are exported as constants (e.g., in referential.config.ts).

import { LocationLevelAutocompleteConfig } from '@app/referential/services/config/referential.config';

this.registerAutocompleteField('level', {
  ...LocationLevelAutocompleteConfig,
  service: this.referentialRefService,
});