diff --git a/docs/upgrade-guide/README.md b/docs/upgrade-guide/README.md index 24ab29cfa8..3073d7d3bd 100644 --- a/docs/upgrade-guide/README.md +++ b/docs/upgrade-guide/README.md @@ -6,6 +6,23 @@ Title: Upgrade guides Below are links to the upgrade guides notes for all released versions of ADF back to v2.6.0 +- [Upgrading from ADF v8.5 to v9.0](upgrade850-900.md) +- [Upgrading from ADF v8.4 to v8.5](upgrade841-850.md) +- [Upgrading from ADF v8.3.1 to v8.4.1](upgrade831-841.md) +- [Upgrading from ADF v8.2.1 to v8.3.1](upgrade821-831.md) +- [Upgrading from ADF v8.1.1 to v8.2.1](upgrade811-821.md) +- [Upgrading from ADF v8.0 to v8.1.1](upgrade80-811.md) +- [Upgrading from ADF v7.0 to v8.0](upgrade70-80.md) +- [Upgrading from ADF v6.9 to v7.0](upgrade69-70.md) +- [Upgrading from ADF v6.8 to v6.9](upgrade68-69.md) +- [Upgrading from ADF v6.7.1 to v6.8.0](upgrade671-68.md) +- [Upgrading from ADF v6.6.0 to v6.7.1](upgrade66-671.md) +- [Upgrading from ADF v6.5.2 to v6.6.0](upgrade652-66.md) +- [Upgrading from ADF v6.4 to v6.5.2](upgrade64-652.md) +- [Upgrading from ADF v6.3 to v6.4](upgrade63-64.md) +- [Upgrading from ADF v6.2 to v6.3](upgrade62-63.md) +- [Upgrading from ADF v6.1 to v6.2](upgrade61-62.md) +- [Upgrading from ADF v6.0 to v6.1](upgrade60-61.md) - [Upgrading from ADF v5.0 to v6.0](upgrade50-60.md) - [Upgrading from ADF v4.11 to v5.0](upgrade411-50.md) - [Upgrading from ADF v4.6 to v4.7](upgrade46-47.md) diff --git a/docs/upgrade-guide/upgrade-6.0.0-6.9.0.md b/docs/upgrade-guide/upgrade-6.0.0-6.9.0.md deleted file mode 100644 index fb16e6625e..0000000000 --- a/docs/upgrade-guide/upgrade-6.0.0-6.9.0.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -Title: Upgrading from ADF v5.0 to v6.0 ---- - -# Upgrading from ADF v6.0 to v6.9 - -This guide provides instructions on how to upgrade your v6.0.0 ADF projects to v6.9.0. - -## Before you begin - -Always perform upgrades on "clean" project state, backup your changes or make a project backup. - -```shell -# Recommended clean up -nx reset && rm -rf .angular .nx dist node_modules nxcache tmp -``` - -## .env file - -If you are using .env file, make sure to update it with the latest configuration: - -```yaml -APP_CONFIG_OAUTH2_HOST="" -APP_CONFIG_ENABLE_MOBILE_APP_SWITCH=false -APP_CONFIG_PLUGIN_AOS=true -APP_CONFIG_PLUGIN_CONTENT_SERVICE=true -APP_CONFIG_PLUGIN_FOLDER_RULES=true -APP_CONFIG_ENABLE_DOWNLOAD_PROMPT=false -APP_CONFIG_ENABLE_DOWNLOAD_PROMPT_REMINDERS=false -APP_CONFIG_DOWNLOAD_PROMPT_DELAY=30 -APP_CONFIG_DOWNLOAD_PROMPT_REMINDER_DELAY=30 -APP_CONFIG_ENABLE_FILE_AUTO_DOWNLOAD=false -APP_CONFIG_FILE_AUTO_DOWNLOAD_SIZE_THRESHOLD_IN_MB=10 -``` - -> [!IMPORTANT] -> The configuration values are for migration purposes only. -> Please refer to the documentation for more details on the configuration settings and values. - -## Library versions - -Update the `package.json` file with the latest library versions: - -- Angular: 14.1.3 -- Alfresco Component Libraries: 6.9.0 -- Alfresco JS-API: 7.6.1 - -```json -{ - "dependencies": { - "@alfresco/adf-core": "6.9.0", - "@alfresco/adf-content-services": "6.9.0", - "@alfresco/adf-process-services-cloud": "6.9.0", - "@alfresco/adf-insights": "6.9.0", - "@alfresco/js-api": "7.6.1" - } -} -``` - -> [!NOTE] -> You can also refer to the Alfresco Content Application [4.4.1 release](https://github.com/Alfresco/alfresco-content-app/blob/4.4.1/package.json) for the latest version of the libraries. - -### Remove old dependencies - -```json -{ - "dependencies": { - "@angular/material-moment-adapter": "14.1.3", - "@mat-datetimepicker/moment": "^9.0.68", - "moment": "^2.29.4", - "moment-es6": "1.0.0", - "@angular/flex-layout": "^14.0.0-beta.40" - } -} -``` - -### Add extra dependencies - -```json -{ - "dependencies": { - "@angular/material-date-fns-adapter": "14.1.3", - "date-fns": "^2.30.0" - } -} -``` - -Reinstall your dependencies and make initial build - -```sh -npm i --legacy-peer-deps -npm run build -``` - -### Update code - -If you are using the `@alfresco/js-api` library, make sure to update the code according to the latest version: - -| Before | After | -|------------------------|--------------------| -| MinimalNodeEntity | NodeEntry | -| SiteBody | SiteBodyCreate | -| MinimalNodeEntryEntity | Node | -| MinimalNode | Node | -| PathInfoEntity | PathInfo | -| SiteBody | SiteBodyCreate | -| FavoriteBody | FavoriteBodyCreate | -| PathElementEntity | PathElement | - -#### NullInjectorError: No provider for RedirectAuthService! - -If you are facing the `NullInjectorError: No provider for RedirectAuthService!` error, make sure to add the `AuthModule` to the `AppModule`: - -```typescript -import { AuthModule } from '@alfresco/adf-core'; - -@NgModule({ - imports: [ - // other imports - AuthModule.forRoot({ useHash: true }) - ] -}) -export class AppModule {} -``` - -For the development purposes, you may want to update the `app.config.json`: - -```json5 -{ - "oauth2": { - // other configurations - "skipIssuerCheck": true, - "strictDiscoveryDocumentValidation": false - } -} -``` - -### Document List component - -For document list components, remove the `display` property if used: - -```html -[display]="documentDisplayMode$ | async" -``` - -## Final steps - -After you have updated the code, make sure to test your application thoroughly to ensure that everything is working as expected. - -You can build and run your application using the following commands: - -```sh -npm run build -npm start content-ce -``` diff --git a/docs/upgrade-guide/upgrade-6.9.0-7.0.0.md b/docs/upgrade-guide/upgrade-6.9.0-7.0.0.md deleted file mode 100644 index 831ba2c307..0000000000 --- a/docs/upgrade-guide/upgrade-6.9.0-7.0.0.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -Title: Upgrading from ADF v6.9 to v7.0 ---- - -# Upgrading from ADF v6.9 to v7.0 - -This guide provides instructions on how to upgrade your v6.9.0 ADF projects to v7.0.0. - -## Before you begin - -Always perform upgrades on "clean" project state, backup your changes or make a project backup. - -```shell -# Recommended clean up -nx reset && rm -rf .angular .nx dist node_modules nxcache tmp -``` - -## Libraries updates - -Node version used is now 20.18.1. - -### Breaking changes with libraries: - -- Angular: 17.1.3 -- Angular Material: 17.1.2 -- Typescript: 5.3.3 -- RXJS: 7.8.1 -- NX: 20.0.0 - -Angular updates can be done with "Update Guide" from Angular documentation. - -### Added libraries: -- eslint-plugin-storybook -- jasmine-marbles -- @editorjs/paragraph -- editorjs-text-alignment-blocktune -- graphql-ws - -### Deleted libraries: -- protractor -- selenium-webdriver -- webdriver-manager -- shx -- monaco-editor -- ngx-monaco-editor-v2 -- @types/selenium-webdriver -- protractor-retry-angular-cli -- protractor-screenshoter-plugin -- protractor-smartrunner - -Reinstall your dependencies and make initial build: - -```shell -npm i -npm run build -``` - -Review your applications as some styles and classes of Angular Material components might have changed. - -## Demo-Shell and e2e -Demo shell and its e2e tests have been deleted. - - -## Material module -Material module is deprecated and will be removed in a future release. Please import components and modules independently. - - -## Standalone components -Most components have been changed to "standalone" and their modules have been deleted. Please import components directly. - -| Deleted modules | -|--------------------------------| -| AttachmentModule | -| AppsListModule | -| TaskListModule | -| ProcessListModule | -| ProcessUserInfoModule | -| TaskCommentsModule | -| ProcessCommentsModule | -| PeopleModule | -| DynamicTableModule | -| ContentWidgetModule | -| AnalyticsProcessModule | -| DiagramsModule | -| ButtonsMenuModule | -| SitesDropdownModule | -| DataColumnModule | -| ContentUserInfoModule | -| AppCardViewModule | -| AppCloudSharedModule | -| FileViewModule | -| AppProcessListModule | -| FolderDirectiveModule | -| ContentTypeModule | -| SortingPickerModule | -| ProcessServicesCloudPipeModule | -| StartTaskCloudModule | -| ProcessDirectiveModule | -| StartProcessCloudModule | -| TaskDirectiveModule | - - - -## Removed components, directives and pipes -| Deleted components, directives and pipes | -|------------------------------------------| -| IsIncludedPipe | -| TabLabelsPipe | -| BooleanPipe | -| FilterOutArrayObjectsByPropPipe | -| LocalizedRolePipe | -| MimeTypeIconPipe | -| FilterStringPipe | -| ProcessNameCloudPipe | -| FormStylePipe | -| CancelProcessDirective | -| MomentDateTimePipe | -| MomentDatePipe | - - -## A11y changes -Components have been reviewed and changed to fix most important issues with accessibility. Please test your application thoroughly to ensure that everything is working as expected, as some components have changed their structure, html roles or attributes. - -| Components changed | Description of changes | -|--------------------------------|----------------------------------------------------------------------| -| Tooltips | Tooltips have been changed from Angular Material to standard tooltip | -| Search Page and Search Filters | mat-chip-option replaced with mat-chip | -| Columns Selector | role attribute changes | -| DataTable | role attribute changes | -| Aspect List | structure of html changed | - - -## Guards -All guards have been converted to functional guards (using the new Angular functional route guard pattern). Please review any custom guards in your application and adapt them to the functional pattern as needed. - -Example of converting a class-based guard to a functional guard: - -```typescript -// Before (class-based) -@Injectable({ - providedIn: 'root' -}) -export class AuthGuard implements CanActivate { - constructor(private authService: AuthService, private router: Router) {} - - canActivate() { - if (this.authService.isLoggedIn()) { - return true; - } - this.router.navigate(['/login']); - return false; - } -} - -// After (functional) -export const authGuard = () => { - const authService = inject(AuthService); - const router = inject(Router); - - if (authService.isLoggedIn()) { - return true; - } - return router.parseUrl('/login'); -}; -``` - -## Model and interface changes - -Some models and interfaces have changed: - -| Before | After | Notes | -|-------------------------------|-----------------------|------------------------------| -| TaskDetailsModel | TaskRepresentation | Rename all instances | -| IdentityUserFilterInterface | Removed | Use type definitions instead | -| IdentityUserServiceInterface | Removed | Use type definitions instead | -| TaskCloudServiceInterface | Removed | Use type definitions instead | - - -## Final steps - -After you have updated the code, make sure to test your application thoroughly to ensure that everything is working as expected. Pay special attention to areas that use the renamed models or interfaces, and make sure all components are properly imported as standalone components. - -If you encounter any issues during the upgrade process, refer to the Angular update guide or the ADF community for assistance. diff --git a/docs/upgrade-guide/upgrade-7.0.0-8.0.0.md b/docs/upgrade-guide/upgrade-7.0.0-8.0.0.md deleted file mode 100644 index 8f7c4f9cc6..0000000000 --- a/docs/upgrade-guide/upgrade-7.0.0-8.0.0.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -Title: Upgrading from ADF v7.0 to v8.0 ---- - -# Upgrading from ADF v7.0 to v8.0 - -This guide provides instructions for upgrading your v7.0.0 ADF projects to v8.0.0. - -## Before you begin - -Always perform upgrades on a "clean" project state. Back up your changes or create a full project backup before proceeding. - -```shell -# Recommended clean up -nx reset && rm -rf .angular .nx dist node_modules nxcache tmp -``` - -## Libraries - -Update your dependencies to the versions introduced in the 8.0.0 release: - -```json -{ - "dependencies": { - "@alfresco/adf-core": "8.0.0", - "@alfresco/adf-content-services": "8.0.0", - "@alfresco/adf-process-services-cloud": "8.0.0", - "@alfresco/adf-insights": "8.0.0", - "@alfresco/adf-extensions": "8.0.0", - "@alfresco/adf-cli": "8.0.0", - "@alfresco/eslint-plugin-eslint-angular": "8.0.0", - "@alfresco/adf-testing": "8.0.0", - "@alfresco/js-api": "9.0.0" - } -} -``` - -Currently used Node version: 22.14.0. - -### Breaking changes - -Major version updates have been applied to the following core libraries: - -- Angular: 19.2.6 -- Angular Material: 19.2.9 -- Typescript: 5.8.2 - -> Details on Angular update can be found in *Update Guide* from Angular documentation. - -### Added libraries - -```json -{ - "dependencies": { - "node-fetch": "^3.3.2" - }, - "devDependencies": { - "resize-observer-polyfill": "^1.5.1", - "webdriver-manager": "12.1.9" - } -} -``` - -### Deleted libraries - -```json -{ - "devDependencies": { - "mini-css-extract-plugin": "X.X.X", - "css-loader": "X.X.X" - } -} -``` - -Reinstall your dependencies and perform an initial build: - -```shell -npm i -npm run build -``` - -Review your applications as some styles and classes of Angular Material components might have changed. - -## Deprecations - -The following table lists deprecated features and modules that will be removed in upcoming releases. Consider replacing them as soon as you update ADF to minimize future technical debt. - -| Name | Notes | -|-------------------------------|-----------------------------------------------------------------------------------------------| -| Custom Theme | Refer to [Custom Theme documentation](../../lib/core/custom-theme/README.md) | -| ShellModule | Refer to [Shell documentation](../../lib/core/shell/README.md) | -| FormBaseModule | Use standalone components instead. | -| CoreTestingModule | Use standalone components instead. | -| ProcessServicesCloudModule | Refer to [ProcessServicesCloudModule replacement](#processservicescloudmodule-replacement) | - -### ProcessServicesCloudModule replacement - -To replace this module, import the standalone components directly or use the following provider API to replicate its behavior: - -```typescript -providers: [ - provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'), - provideCloudPreferences(), - provideCloudFormRenderer(), - { provide: TASK_LIST_CLOUD_TOKEN, useClass: TaskListCloudService } -] -``` - -## New features and APIs - -You can start using the new features and APIs introduced in the 8.0.0 release. - -### XMLHttpRequest.withCredentials - -Support for disabling the `withCredentials` property in `app.config.json` for identity providers that disallow credentials has been introduced. You can configure it as shown below: - -```json -{ - "auth": { - "withCredentials": false - } -} -``` - -### provideShell - -The new provideShell API for providing the main application layout can replace the `withRoutes(routes: Routes | AppShellRoutesConfig)` method, as shown below. - -```typescript -import { provideShell } from '@alfresco/adf-core/shell'; - -provideShell( - { - routes: [], - appService: AppService, - authGuard: AuthGuard, - navBar: { - minWidth: 0, - maxWidth: 100 - } - } -) -``` - -### provideI18N - -The new `provideI18N` API for providing translation can replace `provideTranslations('app', 'assets')` method, as shown below. - -```typescript -import { provideI18N } from '@alfresco/adf-core'; - -provideI18N( - { - defaultLanguage: "en", // optional, defaults to "en" - assets: [['en', '/assets/i18n/en.json'], ['fr', '/assets/i18n/fr.json']] - } -) -``` - -## Final steps - -After updating your code, thoroughly test your application to ensure everything works as expected. - -If you encounter any issues during the upgrade process, refer to the Angular update guide or seek assistance from the ADF community. diff --git a/docs/upgrade-guide/upgrade60-61.md b/docs/upgrade-guide/upgrade60-61.md new file mode 100644 index 0000000000..e8ec46de72 --- /dev/null +++ b/docs/upgrade-guide/upgrade60-61.md @@ -0,0 +1,147 @@ +--- +Title: Upgrading from ADF v6.0 to v6.1 +--- + +# Upgrading from ADF v6.0 to v6.1 + +This guide provides instructions on how to upgrade your v6.0.0 ADF projects to v6.1.0. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. + +Do not skip this task if you want your application to be updated to the most recent version of ADF. +Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates. + +After the upgrade, check the other sections below to see if there are any changes affecting your project. + +## Contents + +- [Library updates](#library-updates) +- [Breaking changes](#breaking-changes) + - [Angular Flex-Layout removed](#angular-flex-layout-removed) + - [`@mat-datetimepicker` peer dependency major bump](#mat-datetimepicker-peer-dependency-major-bump) + - [`@alfresco/js-api` and ADF peers use a caret range](#alfrescojs-api-and-adf-peers-use-a-caret-range) +- [Third-party libraries](#third-party-libraries) +- [New components and features](#new-components-and-features) + - [Display Rich Text form widget (cloud)](#display-rich-text-form-widget-cloud) + - [Configurable header text color](#configurable-header-text-color) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "6.1.0", + "@alfresco/adf-content-services": "6.1.0", + "@alfresco/adf-process-services": "6.1.0", + "@alfresco/adf-process-services-cloud": "6.1.0", + "@alfresco/adf-insights": "6.1.0", + "@alfresco/adf-extensions": "6.1.0", + "@alfresco/js-api": ">=6.1.0" + } +} +``` + +Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`. + +Reinstall your dependencies + +```sh +npm install +``` + +**Note:** the ADF libraries now depend on `@alfresco/js-api` (and on each other) through a `^6.1.0` caret range, +where `6.0.0` used an exact pin. Make sure your application resolves a JS-API build of `6.1.0` or later. + +**Tooling note:** the repository's pinned Node version (`.nvmrc`) moved from **14** to **18**, so the libraries are +now built and tested on Node 18. Align your build/CI Node version accordingly. + +## Breaking changes + +The ADF project follows the [semver](https://semver.org/) conventions. `6.1.0` is a minor release, so there are +no removed or renamed public exports; the items below are dependency-level changes that can still affect your build. + +### Angular Flex-Layout removed + +`@angular/flex-layout` (`^14.0.0-beta.40`) has been **removed** as a dependency from every ADF library +(`@alfresco/adf-core`, `@alfresco/adf-content-services`, `@alfresco/adf-process-services`, +`@alfresco/adf-process-services-cloud` and `@alfresco/adf-insights`). All internal usage of `fxLayout`, +`fxFlex`, `fxHide` and `FlexLayoutModule` was removed from the component templates and modules. + +ADF no longer re-exports `FlexLayoutModule`, and it was never part of the public API barrels, so this does not +break any ADF import. However, if your own application relied on ADF transitively installing +`@angular/flex-layout` and you use flex-layout directives in your **own** templates, add the dependency to your +application directly: + +```sh +npm install @angular/flex-layout@^14.0.0-beta.40 +``` + +### `@mat-datetimepicker` peer dependency major bump + +`@alfresco/adf-core` bumped its `@mat-datetimepicker` peer dependencies by a major version: + +| Peer dependency | Before | After | +| ---------------------------- | --------- | --------- | +| `@mat-datetimepicker/core` | `^9.0.68` | `^10.1.1` | +| `@mat-datetimepicker/moment` | `^9.0.68` | `^10.1.1` | + +If your application pins these packages, update them to the `^10.1.1` range so your installed version matches +the one ADF is built against. + +### `@alfresco/js-api` and ADF peers use a caret range + +The peer dependencies inside the ADF libraries changed from exact pins (`6.0.0`) to caret ranges (`^6.1.0`). This +applies to `@alfresco/js-api` and to the inter-library ADF peers (for example `@alfresco/adf-core` and +`@alfresco/adf-extensions`). Ensure your lockfile resolves compatible `6.x` builds; a stale exact pin of +`@alfresco/js-api@6.0.0` should be updated to `>=6.1.0`. + +## Third-party libraries + +| Name | Version | Notes | +| ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ | +| `@angular/flex-layout` | removed | No longer a dependency of any ADF library (see [Angular Flex-Layout removed](#angular-flex-layout-removed)). | +| `@mat-datetimepicker/core` | `^10.1.1` | Major bump from `^9.0.68` (peer of `@alfresco/adf-core`). | +| `@mat-datetimepicker/moment` | `^10.1.1` | Major bump from `^9.0.68` (peer of `@alfresco/adf-core`). | + +## New components and features + +### Display Rich Text form widget (cloud) + +A new form widget, `DisplayRichTextWidgetComponent` (selector `display-rich-text`), is now declared and exported +by `FormCloudModule` in `@alfresco/adf-process-services-cloud`. Previously the widget class existed but was not +wired into the module, so it could not be used. It renders read-only rich-text content within a cloud form. + +### Configurable header text color + +`[HeaderLayoutComponent](../core/components/header.component.md)` (selector `adf-layout-header`) now reads a new +`headerTextColor` key from `app.config.json` and, when present, applies it to the +`--theme-header-text-color` CSS custom property (which defaults to the primary palette's contrast color). + +```json +{ + "headerTextColor": "#ffffff" +} +``` + +## Behavioural changes + +| Area | Change | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Tree component](../content-services/components/tree.component.md) | Pagination is now emitted only when the top-level entries change, and an expand/collapse regression was fixed. | +| Form save button (cloud) | On clicking the system **save** outcome the save button is now disabled, and it is re-enabled when a form field value changes. | +| Task / process lists (cloud) | Changing only column visibility no longer triggers a reload of the task or process list. | +| Task lists (cloud) | The loading spinner no longer disappears before the list has finished loading. | +| Task details (cloud) | The loading spinner alignment after opening task details was corrected. | +| [Tags creator](../content-services/components/tags-creator.component.md) | The "required field" message is no longer shown after discarding changes; the first tag position and an extra scrollbar (shown while the spinner is visible) were also corrected. | +| [Image viewer](../core/components/viewer.component.md) | Navigation between images was fixed, and image display in full-screen mode was corrected. | +| User roles fetch | `UserAccessService` now appends an `appkey` query parameter (read from the `application.key` app-config value) when fetching identity roles, if that value is configured. | +| Search facets | Facet, filter and widget chips had markup/icon adjustments in the facets section. | +| [Card view select item](../core/components/card-view.component.md) | The select input's position in the edit template was changed. | +| Start process / task outcomes | Outcome button positioning in the start-process form and the attach-file button style were corrected. | +| Group cloud | The identity group validation error message was replaced with a shorter version. | +| Theme | A task-filter color was changed to use the accent-contrast color. | diff --git a/docs/upgrade-guide/upgrade61-62.md b/docs/upgrade-guide/upgrade61-62.md new file mode 100644 index 0000000000..085a3cba02 --- /dev/null +++ b/docs/upgrade-guide/upgrade61-62.md @@ -0,0 +1,380 @@ +--- + +## Title: Upgrading from ADF v6.1 to v6.2 + +# Upgrading from ADF v6.1 to v6.2 + +This guide provides instructions on how to upgrade your v6.1.0 ADF projects to v6.2.0. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. + +Do not skip this task if you want your application to be updated to the most recent version of ADF. +Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates. + +After the upgrade, check the other sections below to see if there are any changes affecting your project. + +## Contents + +- [Library updates](#library-updates) +- [Breaking changes](#breaking-changes) + - [Dependency injection refactor (](#dependency-injection-refactor-inject)`inject()`[)](#dependency-injection-refactor-inject) + - [SharedLinksApiService.createSharedLinks](#sharedlinksapiservicecreatesharedlinks) + - [Share dialog: expiry is now date-only](#share-dialog-expiry-is-now-date-only) + - [Route-aware filter selection](#route-aware-filter-selection) +- [Removed items](#removed-items) +- [Renamed items](#renamed-items) + - [CSS class renames](#css-class-renames) + - [Encapsulation changes](#encapsulation-changes) + - [SCSS reference variables](#scss-reference-variables) +- [Third-party libraries](#third-party-libraries) +- [New components and features](#new-components-and-features) + - [Logical search filter](#logical-search-filter) + - [Advanced search: autocomplete chips](#advanced-search-autocomplete-chips) + - [Header customization](#header-customization) + - [Icon font set](#icon-font-set) + - [OAuth2 configuration handling](#oauth2-configuration-handling) +- [Behavioural changes](#behavioural-changes) +- [Theme changes](#theme-changes) + + + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "6.2.0", + "@alfresco/adf-content-services": "6.2.0", + "@alfresco/adf-process-services": "6.2.0", + "@alfresco/adf-process-services-cloud": "6.2.0", + "@alfresco/adf-insights": "6.2.0", + "@alfresco/adf-extensions": "6.2.0", + "@alfresco/js-api": ">=6.2.0" + } +} +``` + +Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`. + +Reinstall your dependencies + +```sh +npm install +``` + +**Note:** the ADF libraries now depend on `@alfresco/js-api` with a `>=6.2.0` range (previously a `^6.1.0` caret range). Make sure your application resolves a JS-API build of `6.2.0` or later. + +## Breaking changes + +### Dependency injection refactor (`inject()`) + +A large number of exported services, components and abstract base classes were refactored +to use Angular's `inject()` function instead of constructor-parameter injection. +As a result **their public constructor signatures changed** — most now take no arguments +(or a reduced set). + +This affects you only if you **subclass** one of these classes and call `super(...)`, +or if you **instantiate them directly** (for example, `new AuthenticationService(...)` in a unit test). + + +| Library | Affected classes | +| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@alfresco/adf-core` | `[BaseAuthenticationService](../../lib/core/src/lib/services/base-authentication.service.ts)`, `[AuthenticationService](../core/services/authentication.service.md)`, `[OIDCAuthenticationService](../../lib/core/src/lib/auth/oidc/oidc-authentication.service.ts)`, `[AuthGuardBase](../../lib/core/src/lib/auth/guard/auth-guard-base.ts)`, `AuthGuard`, `AuthGuardBpm`, `AuthGuardEcm`, `BaseCardView`, `[CardViewTextItemComponent](../../lib/core/src/lib/card-view/components/card-view-textitem/card-view-textitem.component.ts)`, `CardViewDateItemComponent`, `CardViewSelectItemComponent`, `CardViewArrayItemComponent`, `CardViewBoolItemComponent`, `CardViewKeyValuePairsItemComponent`, `CardViewMapItemComponent` | +| `@alfresco/adf-content-services` | `UploadBase`, `[UploadButtonComponent](../content-services/components/upload-button.component.md)`, `[UploadDragAreaComponent](../content-services/components/upload-drag-area.component.md)` | +| `@alfresco/adf-process-services` | `[FormComponent](../process-services/components/form.component.md)`, `[StartFormComponent](../core/components/start-form.component.md)` | +| `@alfresco/adf-process-services-cloud` | `BaseCloudService`, `FormCloudService`, `FormDefinitionSelectorCloudService`, `ProcessListCloudService`, `ProcessTaskListCloudService`, `ProcessCloudService`, `StartProcessCloudService`, `NotificationCloudService`, `UserPreferenceCloudService`, `StartTaskCloudService`, `TaskCloudService`, `TaskFilterCloudService`, `ServiceTaskListCloudService`, `TaskListCloudService` | + + +If you extend one of these classes, drop the old positional arguments from your `super(...)` call. + +Before: + +```ts +export class MyUpload extends UploadButtonComponent { + constructor(uploadService, contentService, nodesApiService, translationService, logService, ngZone) { + super(uploadService, contentService, nodesApiService, translationService, logService, ngZone); + } +} +``` + +After: + +```ts +export class MyUpload extends UploadButtonComponent { + constructor() { + super(); + } +} +``` + +If you were instantiating these classes manually in tests, note that `inject()` only works +inside an Angular injection context. Use `TestBed` and retrieve the instance from the injector +instead of calling `new`. + +**Note:** `BaseCloudService` now injects `[LogService](../core/services/log.service.md)` itself, +so `this.logService` is available to every cloud-service subclass. Subclasses that previously +declared their own `logService` no longer need to. + +### SharedLinksApiService.createSharedLinks + +A new middle parameter was added to `[createSharedLinks](../core/services/shared-links-api.service.md)` +so that expiry settings can be applied to the shared link itself. + +Before: + +```ts +createSharedLinks(nodeId: string, options: any = {}): Observable +``` + +After: + +```ts +createSharedLinks(nodeId: string, sharedLinkWithExpirySettings?: SharedLinkBodyCreate, options: any = {}): Observable +``` + +If you call this method with positional arguments, update the call: + +```ts +// Before +this.sharedLinksApiService.createSharedLinks(nodeId, options); + +// After +this.sharedLinksApiService.createSharedLinks(nodeId, undefined, options); +``` + + + +### Share dialog: expiry is now date-only + +The share-link expiry control in `[ShareDialogComponent](../../lib/content-services/src/lib/content-node-share/content-node-share.dialog.ts)` +changed from a date-**time** picker to a **date-only** picker, and the date library moved from +`moment` to `date-fns`. + +- The `sharedLinkDateTimePickerType` app-config key is **no longer read**. Setting it has no effect; the picker is date-only. +- Methods that previously accepted/returned `moment.Moment` now use the native `Date` type (for example `onTimeChanged(date: Date)`). Update any override accordingly. +- The template handler `onDatetimepickerClosed` was renamed to `onDatePickerClosed`, and the `#dateTimePickerInput` template reference to `#datePickerInput` — this affects you only if you override the dialog template. + + + +### Route-aware filter selection + +`[ProcessFiltersComponent](../process-services/components/process-filters.component.md)` and +`[TaskFiltersComponent](../process-services/components/task-filters.component.md)` (in `@alfresco/adf-process-services`) +now inject `Router` (plus `Location` / `ActivatedRoute` respectively) to highlight the active +filter based on the current route. If you instantiate these components in a test, provide routing +(for example, import `RouterTestingModule`). + +## Removed items + + +| Item | Package | Notes | +| ------------------------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `NotificationIconPipe` (`notificationIcon`) | `@alfresco/adf-core` | Internal, non-exported pipe. Icon resolution now happens in the notification factory. Only affects unsupported use of the deep `notifications/pipes/notification-icon.pipe` path. | +| `mockAuthConfigImplicitFlow`, `mockAuthConfigCodeFlow` | `@alfresco/adf-core` | Test mocks removed. Inline your own equivalents if your tests imported them. | +| `sharedLinkDateTimePickerType` (app-config key) | `app.config.json` | No longer read — the share-link expiry picker is date-only. | + + + + +## Renamed items + + + +### CSS class renames + +If you target these selectors from your own stylesheets, update them: + + +| Component | Before | After | +| -------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- | +| [About server settings](../core/components/about.component.md) | `.adf-github-link-container` | `.adf-about-server-settings` (+ `.adf-about-server-settings__card`) | +| [Edit task filter](../process-services-cloud/components/edit-task-filter-cloud.component.md) | `.adf-edit-task-filter-description` | `.adf-edit-task-filter-header__description` | +| [Edit process filter](../process-services-cloud/components/edit-process-filter-cloud.component.md) | `.adf-edit-process-filter-description` | `.adf-edit-process-filter-header__description` | + + + + +### Encapsulation changes + +`AboutServerSettingsComponent` and `PackageListComponent` **no longer use** `ViewEncapsulation.None`. +Global CSS overrides that previously "bled into" these components will no longer apply — theme them +through the new [CSS custom properties](#theme-changes) instead. + +### SCSS reference variables + +If you import ADF's `[_reference-variables.scss](../../lib/core/src/lib/styles/_reference-variables.scss)` +directly, note that several `$adf-ref-*` primitives were consolidated/renamed. The public `--adf-*` +CSS custom property names are unchanged — prefer overriding those instead. + + +| Before | After | +| ---------------------------------------------------------------- | ------------------------------- | +| `$adf-ref-edit-task-and-service-filter-header-title-color` | `$adf-ref-title-color` | +| `$adf-ref-edit-task-and-service-filter-header-description-color` | `$adf-ref-description-color` | +| `$adf-ref-edit-task-and-service-filter-header-height` | `$adf-ref-height-48` | +| `$adf-ref-card-border-radius` | `$adf-ref-card-border-radius-0` | + + + + +## Third-party libraries + + +| Name | Version | Notes | +| ---------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `material-icons` | `^1.13.8` | The bundled Material Icons font and its `material-icons.css` were removed from the build in favour of the published `[material-icons](https://www.npmjs.com/package/material-icons)` package. If your app relied on ADF bundling the font, provide it yourself. | +| `date-fns` | `^2.30.0` | New dependency (replaces `moment` in the share dialog). | + + + + +## New components and features + + +| Name | Package | Description | +| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------------------------------- | +| `[SearchLogicalFilterComponent](../content-services/components/search-logical-filter.component.md)` | `@alfresco/adf-content-services` | `logical-filter` search widget (AND / OR / AND-NOT). | +| `[SearchChipInputComponent](../content-services/components/search-chip-input.component.md)` | `@alfresco/adf-content-services` | Reusable chip text-entry field. | +| `[SearchFilterAutocompleteChipsComponent](../content-services/components/search-filter-autocomplete-chips.component.md)` | `@alfresco/adf-content-services` | `autocomplete-chips` search widget (Tags / Location). | +| `[SearchChipAutocompleteInputComponent](../content-services/components/search-chip-autocomplete-input.component.md)` | `@alfresco/adf-content-services` | Chip input with `mat-autocomplete`. | +| `[IsIncludedPipe](../content-services/pipes/is-included.pipe.md)` (`adfIsIncluded`) | `@alfresco/adf-content-services` | Returns whether a value is contained in an array. | + + + + +### Logical search filter + +A new search widget, `logical-filter`, lets users build AND / OR / AND-NOT queries from three +phrase inputs. Enable it by referencing the `logical-filter` widget type in your search configuration: + +```json +{ + "search": { + "categories": [ + { + "id": "logic", + "name": "Query", + "enabled": true, + "component": { + "selector": "logical-filter", + "settings": { "field": "cm:name,cm:title" } + } + } + ] + } +} +``` + + + +### Advanced search: autocomplete chips + +A new search widget, `autocomplete-chips`, provides chip-based multi-select with autocomplete for +filters such as Tags and Location. For `field: 'TAG'` it loads options through the tag service; +otherwise it uses the `options` from the widget settings. `[SearchWidgetSettings](../../lib/content-services/src/lib/search/models/search-widget-settings.interface.ts)` +gains a new optional property `allowOnlyPredefinedValues?: boolean`. + +```json +{ + "id": "tags", + "name": "Tags", + "enabled": true, + "component": { + "selector": "autocomplete-chips", + "settings": { "field": "TAG", "allowOnlyPredefinedValues": true } + } +} +``` + + + +### Header customization + +`[HeaderLayoutComponent](../core/components/header.component.md)` gained two new inputs: + + +| Input | Type | Default | Description | +| ------------ | --------- | -------- | ---------------------------------------- | +| `showLogo` | `boolean` | `true` | Whether the logo is displayed. | +| `toggleIcon` | `string` | `'menu'` | Icon used for the sidenav toggle button. | + + + + +### Icon font set + +`[IconComponent](../core/components/icon.component.md)` gained a new `fontSet` input, letting you +render an icon from a custom Material icon font set: + +```html + +``` + + + +### OAuth2 configuration handling + +`[AppConfigService](../core/services/app-config.service.md)` now exposes a normalized `oauth2` getter. + +Before: + +```ts +const oauth = this.appConfigService.get(AppConfigValues.OAUTHCONFIG, {}); +``` + +After: + +```ts +const oauth = this.appConfigService.oauth2; // returns an OauthConfigModel, defaulting to {} +``` + +- The `implicitFlow`, `silentLogin` and `codeFlow` flags now accept the string values `'true'` / `'false'` in `app.config.json` in addition to real booleans, and are coerced to booleans by the getter. The `oauth2.silentLogin` schema type was widened to `["boolean", "string"]`. +- `[OauthConfigModel](../../lib/core/src/lib/auth/models/oauth-config.model.ts)` gains an optional `redirectSilentIframeUri?: string` field. + + + +## Behavioural changes + + +| Area | Change | +| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Search facets | Facet chips with no results are rendered disabled and show a `remove` icon instead of the dropdown arrow. | +| Search facet/filter chips | The dropdown arrow flips between `keyboard_arrow_down` / `keyboard_arrow_up` with the menu state, the toggled-chip border uses the primary color, and the filter "cancel" action was relabeled from **Remove** to **Clear**. | +| [People (cloud)](../process-services-cloud/components/people-cloud.component.md) | No longer triggers an identity search for an empty value; at least one character is required. | +| Process / task filters | A filter is highlighted as active only when the current route matches the filter context and it is the current filter. | +| [Card view text item](../../lib/core/src/lib/card-view/components/card-view-textitem/card-view-textitem.component.ts) | On an invalid edit, `CardViewUpdateService.update` is now also emitted (with the edited value) after clearing previous errors. | +| [App config](../core/services/app-config.service.md) | When `app.config.json` fails schema validation, `AppConfigService` now logs `console.error('app.config.json contains validation errors')` and continues with the existing config. | +| Shared link expiry (security) | Setting an expiry now recreates the shared link with an `expiresAt` value so the backend enforces expiry on the link itself; turning the expiry off recreates a non-expiring link. | +| Accessibility | The filter-menu close control is now a real `button`, Shift+Tab is trapped inside filter menu cards, and the autocomplete input is associated with its listbox via `aria-controls`. | + + + + +## Theme changes + +Several components now expose their styles through `--adf-*` CSS custom properties, so you can theme +them without overriding internal selectors. Defaults preserve the previous appearance. Override a +property in your global stylesheet, for example: + +```scss +:root { + --adf-card-view-background: #fafafa; + --adf-card-view-border-radius: 8px; +} +``` + +The notable additions in this release: + + +| Component | CSS custom properties | +| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Card view](../core/components/card-view.component.md) | `--adf-card-view-background` (default `white`), `--adf-card-view-border` (`unset`), `--adf-card-view-border-color` (`unset`), `--adf-card-view-border-radius` (`0`) | +| [About panel](../core/components/about.component.md) | `--adf-about-panel-header-height` (`48px`), `--adf-about-panel-header-title-color` | +| About server settings | `--adf-about-server-settings-background`, `--adf-about-server-settings-color`, `--adf-about-server-settings-border-radius`, `--adf-about-server-settings-padding` | +| Package list table | `--adf-package-list-table-background`, plus `--adf-package-list-table-header-*` and `--adf-package-list-table-row-*` (borders, min-height, cell colors) | +| [Edit task / service filter](../process-services-cloud/components/edit-task-filter-cloud.component.md) | `--adf-edit-task-and-service-filter-header-title-color`, `--adf-edit-task-and-service-filter-header-description-color`, `--adf-edit-task-and-service-filter-header-height`, `--adf-edit-task-and-service-filter-content-text-label-color`, `--adf-edit-task-and-service-filter-content-select-label-color` | +| [Edit process filter](../process-services-cloud/components/edit-process-filter-cloud.component.md) | `--adf-edit-process-filter-header-height`, `--adf-edit-process-filter-header-title-color`, `--adf-edit-process-filter-header-description-color`, `--adf-edit-process-filter-content-text-label-color`, `--adf-edit-process-filter-content-select-label-color` | diff --git a/docs/upgrade-guide/upgrade62-63.md b/docs/upgrade-guide/upgrade62-63.md new file mode 100644 index 0000000000..4dbd0d616c --- /dev/null +++ b/docs/upgrade-guide/upgrade62-63.md @@ -0,0 +1,377 @@ +## Title: Upgrading from ADF v6.2 to v6.3 + +# Upgrading from ADF v6.2 to v6.3 + +This guide provides instructions on how to upgrade your v6.2.0 ADF projects to v6.3.0. + +--- + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. + +Do not skip this task if you want your application to be updated to the most recent version of ADF. +Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates. + +After the upgrade, check the other sections below to see if there are any changes affecting your project. + +## Contents + +- [Library updates](#library-updates) +- [Breaking changes](#breaking-changes) + - [JS-API v7 and type migrations](#js-api-v7-and-type-migrations) + - [Third-party libraries](#third-party-libraries) + - [HTTP client and auth](#http-client-and-auth) + - [Breadcrumbs moved to a secondary entry point](#breadcrumbs-moved-to-a-secondary-entry-point) + - [Search API changes](#search-api-changes) + - [Comments component](#comments-component) + - [Removed and hidden items](#removed-and-hidden-items) + - [CSRF default changed](#csrf-default-changed) + - [Role-based authorization](#role-based-authorization) + - [Other breaking changes](#other-breaking-changes) +- [Deprecated items](#deprecated-items) +- [New components and features](#new-components-and-features) + - [Advanced search](#advanced-search) + - [Core breadcrumbs](#core-breadcrumbs) + - [Data Table form widget](#data-table-form-widget) + - [Content metadata](#content-metadata) + - [Other additions](#other-additions) +- [Behavioural changes](#behavioural-changes) +- [Theme changes](#theme-changes) + + + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "6.3.0", + "@alfresco/adf-content-services": "6.3.0", + "@alfresco/adf-process-services": "6.3.0", + "@alfresco/adf-process-services-cloud": "6.3.0", + "@alfresco/adf-insights": "6.3.0", + "@alfresco/adf-extensions": "6.3.0", + "@alfresco/js-api": ">=7.0.0" + } +} +``` + +**Important:** ADF 6.3.0 requires `@alfresco/js-api` **v7 or later** (`>=7.0.0`). This is the biggest +single change to take into account — see [JS-API v7 and type migrations](#js-api-v7-and-type-migrations). + +The advanced date-range search and several date pickers now use `date-fns`. Make sure the new +peer dependency `@angular/material-date-fns-adapter` is installed. + +Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall: + +```sh +npm install +``` + + + +## Breaking changes + + + +### JS-API v7 and type migrations + +ADF now consumes the strongly-typed models from `@alfresco/js-api` v7 directly instead of its own +handwritten wrappers. Update your type references accordingly. + + +| Before (ADF wrapper / old type) | After (`@alfresco/js-api` type) | +| ------------------------------- | ------------------------------- | +| `MinimalNode` | `Node` | +| `MinimalNodeEntryEntity` | `Node` | +| `AssocChildBody` | `ChildAssociationBody` | +| `QueryBody` | `SearchRequest` | +| `SiteBody` | `SiteBodyCreate` | +| `FavoriteBody` | `FavoriteBodyCreate` | + + +The wrapper model file `document-library.model.ts` was **removed** from `@alfresco/adf-content-services`. +The following exports are no longer available from ADF — import the equivalents from `@alfresco/js-api`: +`NodePaging`, `NodePagingList`, `NodeMinimalEntry`, `NodeMinimal`, `Pagination`, `UserInfo`, +`ContentInfo`, `PathInfoEntity` (→ `PathInfo`), `PathElementEntity` (→ `PathElement`), `NodeProperties`. + +Public service signatures changed as a result — for example: + +```ts +// NodesApiService — before +getNode(nodeId: string, options?: any): Observable +// after +getNode(nodeId: string, options?: any): Observable +``` + +- `[ContentService](../core/services/content.service.md)`: `folderCreate` / `folderEdit` are now `Subject`. +- `[SearchService](../core/services/search.service.md)`: `searchByQueryBody(queryBody: SearchRequest)`. +- `BaseQueryBuilderService` (base of `[SearchQueryBuilderService](../content-services/services/search-query-builder.service.md)`): `updated` is now `Subject`; `update`, `execute`, `search`, `buildQuery` all use `SearchRequest`. +- `SearchConfigurationInterface.generateQueryBody(...)` now returns `SearchRequest`. Note `SearchRequest` is a **class** (`new SearchRequest({...})`), whereas `QueryBody` was a plain interface — object literals still assign structurally. +- `User` from `@alfresco/js-api` is now a **class** rather than a type alias. + + + +### Third-party libraries + +To support Angular 14+, several dependencies were upgraded (major bumps with their own breaking changes): + + +| Package | Before | After | +| ------------------------------------ | --------- | -------------------------------------------- | +| `@alfresco/js-api` | `>=6.2.0` | `>=7.0.0` | +| `chart.js` | `2.9.4` | `^4.3.0` | +| `ng2-charts` | `2.4.2` | `^4.1.1` | +| `ngx-monaco-editor` | `8.1.1` | replaced by `ngx-monaco-editor-v2` `^14.0.4` | +| `@angular/material-date-fns-adapter` | — | new dependency | + + +If you use the Insights charts, migrate to the `ng2-charts` v4 / `chart.js` v4 API (tree-shakeable +registration, new chart config). If you use the Monaco editor, switch the import from +`ngx-monaco-editor` to `ngx-monaco-editor-v2`. + +### HTTP client and auth + +- The Alfresco API HTTP client was replaced by an Angular `HttpClient`-based `AdfHttpClient` +(the old `alfresco-api.http-client` identifier is gone). Update any references to `AdfHttpClient`. +- HTTP-client and auth configuration moved out of `CoreModule` into `AuthModule`. Make sure your +application imports `AuthModule` so the API client and auth config are provided. +- Read the username/token from `[AuthenticationService](../core/services/authentication.service.md)` +rather than from `AlfrescoApi`'s `oauth2Auth`. +- **`NullInjectorError: No provider for RedirectAuthService!`** — because auth moved into `AuthModule`, importing +`CoreModule` alone no longer provides the OIDC `RedirectAuthService`. Import `AuthModule.forRoot()` in your root +module (use `AuthModule.forRoot({ useHash: true })` for hash-based routing) to resolve the error. + + + +### Breadcrumbs moved to a secondary entry point + +The new breadcrumb components ship from a dedicated secondary entry point rather than the root barrel: + +```ts +// Components +import { BreadcrumbComponent, BreadcrumbItemComponent } from '@alfresco/adf-core/breadcrumbs'; +``` + +```scss +// Theme +@use '@alfresco/adf-core/breadcrumbs' as breadcrumbs; +``` + +They are **not** exported from the root `@alfresco/adf-core`, and their theme is no longer part of the +core styles index — add the imports above where needed. + +### Search API changes + +- `SearchChipInputComponent` **was removed.** Remove any imports/usages (the logical filter no longer uses it). +- `disableUpdateOnSubmit` was removed from search widget settings — delete it from your `search.config`. +- `[SearchLogicalFilterComponent](../content-services/components/search-logical-filter.component.md)` changed its value model. The per-field condition type went from `string[]` to a single space-separated `string`, and a new `MATCH_EXACT = 'matchExact'` field was added: + ```ts + // LogicalSearchCondition — before: { matchAll: string[]; matchAny: string[]; exclude: string[] } + // after: { matchAll: string; matchAny: string; matchExact: string; exclude: string } + ``` +- `SearchChipAutocompleteInputComponent` and `SearchFilterAutocompleteChipsComponent` now use an +`AutocompleteOption` object model instead of plain strings. If you configured these with `string[]` +options, migrate to `AutocompleteOption[]` (`{ value: string; id?: string; fullPath?: string }`), +and note the new optional `SearchWidgetSettings.autocompleteOptions` field. + + + +### Comments component + +The comments components (`[adf-comments](../core/components/comments.component.md)` and +`adf-comment-list`) were cleaned up, with several consumer-facing consequences: + +- **The** `interfaces` **barrel was removed.** Import `CommentsService` / the comments token from their +specific files (or the top-level `public-api`) instead of `.../comments/interfaces`. +- **Comment text is no longer sanitised as HTML** — the message is rendered as plain text +(`white-space: pre-line`), not via `[innerHTML]`. Any HTML in a comment now shows as literal text. +- **Comment data must be** `CommentModel` **instances.** Display logic moved into new `CommentModel` +getters (`hasAvatarPicture`, `userDisplayName`, `userInitials`); plain object literals cast as +`CommentModel` will no longer render correctly. Build them with `new CommentModel({...})`. +- `CommentListComponent` removed the public members `selectedComment`, `currentLocale`, and the +methods `getUserShortName()` and `isPictureDefined()`; selection side-effects and the +`.adf-is-selected` styling were dropped (the component just emits `clickRow`). +- Several template element IDs (`adf-comment-{id}`, `comment-user-*`, `comment-message-*`, …) were +removed — update any CSS/E2E selectors that relied on them. + + + +### Removed and hidden items + + +| Item | Package | Notes | +| -------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SearchChipInputComponent` | `@alfresco/adf-content-services` | Removed (see [Search API changes](#search-api-changes)). | +| `document-library.model` exports | `@alfresco/adf-content-services` | Removed; use `@alfresco/js-api` types. | +| `AlfrescoApiCompatibility` usage | `@alfresco/adf-process-services` | `ExternalAlfrescoApiService` now extends `[AlfrescoApiService](../core/services/alfresco-api.service.md)` and uses `AlfrescoApi` (v7). Migrate any code typed against `AlfrescoApiCompatibility`. | +| Several `DocumentListComponent` / `DataTableComponent` methods | `@alfresco/adf-content-services`, `@alfresco/adf-core` | Made `private` (`updateCustomSourceData`, `setupDefaultColumns`, `preserveExistingSelection`, `isSingleSelectionMode`, `isMultipleSelectionMode`, `hasPreselectedNodes`, `hasPreselectedRows`, `hasCustomLayout`). `resetNewFolderPagination()` remains public. | +| `CallApiParams` (interface) | `@alfresco/adf-process-services-cloud` | Removed from the `BaseCloudService` public surface — it now uses `RequestOptions` from `@alfresco/js-api`. Only affects code that imported `CallApiParams` directly. | + + + + +### CSRF default changed + +The default for the `disableCSRF` app-config key changed to `true`. When the key is **absent** +from `app.config.json`, CSRF handling is now disabled by default. If your backend requires the ADF +CSRF token, set it explicitly: + +```json +{ + "disableCSRF": false +} +``` + + + +### Role-based authorization + +Roles are now resolved from the JWT access token instead of the remote `identity-adapter-service` +roles endpoint (a new `hxp_authorization` claim is supported alongside `realm_access`). As a result: + +- `UserAccessService.fetchUserAccess()` is now **synchronous** (returns `void`, was `Promise`). +- `UserAccessService.resetAccess()` was **removed**, and its constructor no longer injects `OAuth2Service`. +- `AuthGuardSsoRoleService.canActivate()` is now **synchronous** (returns `boolean`, was `Promise`). + + + +### Other breaking changes + +- **Bearer-excluded URL matching** is now anchored to the host + first path segment +(`^https?://[^/]+/`) instead of matching anywhere in the URL. Review any custom +`bearerExcludedUrls` patterns that relied on substring matching. +- **DataTable multiselect checkbox** wrapper changed from a `
` to a `