diff --git a/docs/toc.md b/docs/toc.md index 057445995..f0e44a078 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -35,12 +35,27 @@ - [Tutorials](/tutorials/) - [Custom route with parameters](/tutorials/custom-route-with-parameters) - [Dialog actions](/tutorials/dialog-actions) - - [Custom route with parameters](tutorials/custom-route-with-parameters) - [How to create your first extension](/tutorials/how-to-create-your-first-extension) - [How to extend Content Metadata](/tutorials/content-metadata) - [How to extend File lists](/tutorials/file-lists) - [How to extend File Preview](/tutorials/file-preview) - [How to extend The Search Form](/tutorials/search-form) - [Upgrade guide](/upgrade-guide/) - - [Upgrade from v2.4.0 to v2.5.0](/upgrade-guide/upgrade24-45) + - [Upgrade from v2.4.0 to v2.5.0](/upgrade-guide/upgrade24-45) + - [Upgrade from v4.0.0 to v4.1.0](/upgrade-guide/upgrade40-41) + - [Upgrade from v4.1.0 to v4.2.0](/upgrade-guide/upgrade41-42) + - [Upgrade from v4.2.0 to v4.3.0](/upgrade-guide/upgrade42-43) + - [Upgrade from v4.3.0 to v4.4.1](/upgrade-guide/upgrade43-441) + - [Upgrade from v4.4.1 to v5.0.1](/upgrade-guide/upgrade441-501) + - [Upgrade from v5.0.1 to v5.1.1](/upgrade-guide/upgrade501-511) + - [Upgrade from v5.1.1 to v5.2.0](/upgrade-guide/upgrade511-520) + - [Upgrade from v5.2.0 to v5.3.0](/upgrade-guide/upgrade520-530) + - [Upgrade from v5.3.0 to v6.0.0](/upgrade-guide/upgrade530-600) + - [Upgrade from v6.0.0 to v7.0.1](/upgrade-guide/upgrade600-701) + - [Upgrade from v7.0.1 to v7.1.0](/upgrade-guide/upgrade701-710) + - [Upgrade from v7.1.0 to v7.2.0](/upgrade-guide/upgrade710-720) + - [Upgrade from v7.2.0 to v7.3.0](/upgrade-guide/upgrade720-730) + - [Upgrade from v7.3.0 to v7.4.1](/upgrade-guide/upgrade730-741) + - [Upgrade from v7.4.1 to v7.5.0](/upgrade-guide/upgrade741-750) + - [Upgrade from v7.5.0 to v8.0.0](/upgrade-guide/upgrade750-800) - [Get help](/help) diff --git a/docs/upgrade-guide/README.md b/docs/upgrade-guide/README.md index b06967f81..d178c1d2a 100644 --- a/docs/upgrade-guide/README.md +++ b/docs/upgrade-guide/README.md @@ -9,4 +9,20 @@ Below are links to the upgrade guides notes for released versions ## Contents -- [Upgrade from v2.4.o to v2.5.0](/upgrade-guide/upgrade24-45) +- [Upgrade from v7.5.0 to v8.0.0](upgrade750-800.md) +- [Upgrade from v7.4.1 to v7.5.0](upgrade741-750.md) +- [Upgrade from v7.3.0 to v7.4.1](upgrade730-741.md) +- [Upgrade from v7.2.0 to v7.3.0](upgrade720-730.md) +- [Upgrade from v7.1.0 to v7.2.0](upgrade710-720.md) +- [Upgrade from v7.0.1 to v7.1.0](upgrade701-710.md) +- [Upgrade from v6.0.0 to v7.0.1](upgrade600-701.md) +- [Upgrade from v5.3.0 to v6.0.0](upgrade530-600.md) +- [Upgrade from v5.2.0 to v5.3.0](upgrade520-530.md) +- [Upgrade from v5.1.1 to v5.2.0](upgrade511-520.md) +- [Upgrade from v5.0.1 to v5.1.1](upgrade501-511.md) +- [Upgrade from v4.4.1 to v5.0.1](upgrade441-501.md) +- [Upgrade from v4.3.0 to v4.4.1](upgrade43-441.md) +- [Upgrade from v4.2.0 to v4.3.0](upgrade42-43.md) +- [Upgrade from v4.1.0 to v4.2.0](upgrade41-42.md) +- [Upgrade from v4.0.0 to v4.1.0](upgrade40-41.md) +- [Upgrade from v2.4.0 to v2.5.0](upgrade24-45.md) diff --git a/docs/upgrade-guide/upgrade40-41.md b/docs/upgrade-guide/upgrade40-41.md new file mode 100644 index 000000000..52f708d22 --- /dev/null +++ b/docs/upgrade-guide/upgrade40-41.md @@ -0,0 +1,213 @@ +--- +Title: Upgrading from ACA v4.0 to v4.1 +--- + +# Upgrading from ACA v4.0 to v4.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.0.0 project to +v4.1.0. + +The headline of this release is the **ADF platform bump from 6.0.0 to 6.2.0** (and `@alfresco/js-api` 6.0.0 → 6.2.0). +Because that spans **two** ADF releases, most of the required work in this upgrade is **adapting to the breaking +changes ADF introduced in 6.1 and 6.2** — read those two ADF guides alongside this one: + +- [ADF — Upgrading from v6.0 to v6.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade60-61.md) +- [ADF — Upgrading from v6.1 to v6.2](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade61-62.md) + +Angular is a patch bump only (`14.1.2` → `14.1.3`), but the **Node requirement moved to 18**. On the ACA side the +most significant change is that three bundled extensions (**About**, **MS-Office/AOS**, **Folder Rules**) became +**secondary entry points of `@alfresco/aca-content`**, changing their import paths. Read the +[breaking changes](#breaking-changes) carefully. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps below +involve code and configuration changes — commit or back up your work first. + +**Node 18 is now required.** ACA's pinned Node version (`.nvmrc`) moved from **14** to **18**; move your build/CI +to Node 18 before upgrading. (This matches the ADF 6.1 Node bump.) + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 6.1 / 6.2](#aligning-with-adf-61--62) + - [ADF / js-api versions and caret ranges](#adf--js-api-versions-and-caret-ranges) + - [Angular Flex-Layout removed](#angular-flex-layout-removed) + - [Shared-link dialog is date-only](#shared-link-dialog-is-date-only) + - [Advanced search widgets](#advanced-search-widgets) + - [Theming — remove CSS variables that ADF now provides](#theming--remove-css-variables-that-adf-now-provides) + - [Fonts are now published packages](#fonts-are-now-published-packages) + - [Standalone components, `inject()` and view encapsulation](#standalone-components-inject-and-view-encapsulation) +- [Breaking changes](#breaking-changes) + - [Extensions moved to `aca-content` secondary entry points](#extensions-moved-to-aca-content-secondary-entry-points) + - [AcaAboutModule no longer uses forRoot](#acaaboutmodule-no-longer-uses-forroot) + - [aca-shared exports](#aca-shared-exports) + - [Removed plugins and components](#removed-plugins-and-components) + - [Changed automation ids](#changed-automation-ids) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-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-extensions": "6.2.0", + "@alfresco/js-api": "6.2.0", + "@angular/core": "14.1.3" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.2.0` as well. Two vendored assets became real +dependencies — `material-icons` (`^1.13.8`) and `@fontsource/open-sans` (`^5.0.3`) — and `@angular/flex-layout` +was **removed** (see below). Clean `node_modules` and the lockfile, then reinstall on Node 18. + +## Aligning with ADF 6.1 / 6.2 + +Most of this release is adapting ACA to the breaking changes ADF shipped across 6.1 and 6.2. Each item below links +back to the ADF guide that describes the underlying change. + +### ADF / js-api versions and caret ranges + +`@alfresco/adf-*` and `@alfresco/js-api` moved from exact pins to **caret ranges** in the ACA libraries' +`peerDependencies` (e.g. `>=6.0.0` / exact pin → `^6.1.0-0`), mirroring the ADF 6.1 change. If you maintain a fork +with its own `package.json` pins, switch to caret ranges so a compatible `6.x` build resolves. +(See ADF 6.1 → "`@alfresco/js-api` and ADF peers use a caret range".) + +### Angular Flex-Layout removed + +`@angular/flex-layout` was removed from ACA's `package.json` (root, `aca-shared`, `folder-rules`), following its +removal from the ADF libraries. Any spec/code importing `CoreModule` from `@angular/flex-layout` was repointed to +`@alfresco/adf-core`. If your fork used flex-layout only transitively via ADF/ACA, add it to your own +`package.json`, or migrate those templates off `fxLayout`/`fxFlex`. +(See ADF 6.1 → "Angular Flex-Layout removed".) + +### Shared-link dialog is date-only + +ADF 6.2 changed the share-link expiry control to a **date-only** picker and stopped reading the +`sharedLinkDateTimePickerType` app-config key. ACA removed that key from `app.config.json` accordingly +(`"sharedLinkDateTimePickerType": "datetime"` deleted from `app/src/app.config.json.tpl`). Remove it from any +custom `app.config.json`. +(See ADF 6.2 → "Share dialog: expiry is now date-only".) + +### Advanced search widgets + +ACA adopted the new ADF search widgets in `projects/aca-content/assets/app.extensions.json`: + +- The **logical filter** (`"selector": "logical-filter"`) was wired into the search configuration. +- The **Tags** and **Location** filters switched to the new `autocomplete-chips` widget (`field: "TAG"` with + `allowOnlyPredefinedValues: true`; `field: "SITE"` with `options: ["_REPOSITORY_"]`). +- Several **facets were converted to filters** using the new search-filter widget model, and unused i18n keys were + dropped. + +If you customised ACA's search configuration, reconcile it against the new `app.extensions.json` search block. +(See ADF 6.1/6.2 → new `logical-filter` / `autocomplete-chips` search widgets.) + +### Theming — remove CSS variables that ADF now provides + +ADF 6.2 exposes component styling through `--adf-*` CSS custom properties. ACA deleted its redundant local +`--theme-*` overrides that ADF now provides by default (in `adf-about.theme.scss`, `adf-pagination.theme.scss` +and `variables.scss`). If your fork re-declared any of those `--theme-*` variables, drop them and theme through +the ADF `--adf-*` properties instead. +(See ADF 6.2 → theme changes / new `--adf-*` custom properties.) + +### Fonts are now published packages + +The vendored **Material Icons** and **Open Sans** fonts were removed from `app/src/assets/fonts/` and replaced by +the published packages `material-icons` and `@fontsource/open-sans`, imported from `styles.scss`. `AppModule` now +injects `MatIconRegistry` and calls `setDefaultFontSetClass('material-icons-outlined')`. If your fork vendored +these fonts, switch to the packages. +(See ADF 6.1 → material-icons externalised to the published package.) + +### Standalone components, `inject()` and view encapsulation + +Aligning with ADF 6.2's `inject()` refactor and standalone direction, ACA: + +- flattened component/service constructors, removing now-unused injections (`Optimise injections and imports`); +- migrated a number of modules/components to **standalone**; +- enforced `ViewEncapsulation.None` across components via a new lint rule + (`@alfresco/eslint-angular/use-none-component-view-encapsulation`) so `--adf-*` design tokens cascade correctly. + +If you subclass ACA components or rely on their emulated encapsulation, re-check your styles. + +## Breaking changes + +### Extensions moved to `aca-content` secondary entry points + +The three bundled extensions are no longer separate packages — they are **secondary entry points of +`@alfresco/aca-content`**. Update the imports in your `extensions.module.ts` (and `package.json`): + +| Extension | Before (v4.0.0) | After (v4.1.0) | +| --------------- | ----------------------------------- | ------------------------------------ | +| Folder Rules | `@alfresco/aca-folder-rules` | `@alfresco/aca-content/folder-rules` | +| MS-Office (AOS) | `@alfresco/adf-office-services-ext` | `@alfresco/aca-content/ms-office` | +| About | `@alfresco/aca-about` | `@alfresco/aca-content/about` | + +### AcaAboutModule no longer uses forRoot + +`AcaAboutModule.forRoot(...)` was removed. Import the module directly and supply the former `forRoot` arguments +through the new injection tokens `DEV_MODE_TOKEN` and `PACKAGE_JSON` (exported from `@alfresco/aca-content/about`): + +```ts +// Before (v4.0.0) +import { AcaAboutModule } from '@alfresco/aca-about'; +// ... +imports: [ AcaAboutModule.forRoot(environment.production, packageJson) ] + +// After (v4.1.0) +import { AcaAboutModule, DEV_MODE_TOKEN, PACKAGE_JSON } from '@alfresco/aca-content/about'; +// ... +imports: [ AcaAboutModule ], +providers: [ + { provide: DEV_MODE_TOKEN, useValue: !environment.production }, + { provide: PACKAGE_JSON, useValue: packageJson } +] +``` + +### aca-shared exports + +`@alfresco/aca-shared` changed its public surface (standalone migration): + +- **Removed** module exports: `LockedByModule`, `GenericErrorModule`, `SharedInfoDrawerModule` + (`locked-by.module`, `generic-error.module`, `info-drawer/shared-info-drawer.module`). Import the now-standalone + components directly instead of the modules. +- **Added** exports: the new `OpenInAppComponent` / `OpenInAppModule` (`components/open-in-app`). + +`@alfresco/aca-shared/rules` and `@alfresco/aca-shared/store` are unchanged. + +### Removed plugins and components + +- The internal plugin assets `app.debug.json`, `app.metadata.json` and `app.search.json` were removed, along with + the `DocumentDisplayModeComponent` (and its toolbar entry). If you referenced these, remove the references. +- The unused `create-menu` component was deleted. + +### Changed automation ids + +Some non-unique `data-automation-id`s were disambiguated — update any e2e selectors that relied on the old values: + +- Toolbar menu item title `menu-item-title` split into `mat-button-menu-item-title` and + `mat-flat-button-menu-item-title`. +- The search button locator changed from `.app-search-button` to the scoped `aca-search-input .app-search-button`. + +## New components and features + +- **Open in App dialog** — a new `OpenInAppComponent` (`@alfresco/aca-shared`) prompts users to open content in the + mobile app; shown after login and for private files. +- **Multi-select** enabled for the Files and Trashcan views. +- **User initials** displayed for the current user. +- New **filter-state** styles and a facets-section UI refresh. + +## Behavioural changes + +| Area | Change | +| ------------ | --------------------------------------------------------------------------------------------------------------------------- | +| Navigation | Navigation behaviour was reworked to improve the user experience. | +| Search input | Several search-input bugs were fixed. | +| Performance | Template function calls were replaced with variable references (change-detection cost); the thumbnail column was optimised. | +| Libraries | Library-details styles are no longer lost after refreshing the page. | +| Security | An insecure-randomness issue was fixed. | diff --git a/docs/upgrade-guide/upgrade41-42.md b/docs/upgrade-guide/upgrade41-42.md new file mode 100644 index 000000000..800be1723 --- /dev/null +++ b/docs/upgrade-guide/upgrade41-42.md @@ -0,0 +1,183 @@ +--- +Title: Upgrading from ACA v4.1 to v4.2 +--- + +# Upgrading from ACA v4.1 to v4.2 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.1.0 project to +v4.2.0. + +The headline of this release is the **ADF 6.2.0 → 6.3.0** bump and, with it, the **`@alfresco/js-api` 6.2.0 → 7.0.0 +(major)** upgrade. The bulk of the work is **adapting to the ADF 6.3 / js-api v7 breaking changes** — read the ADF +guide alongside this one: + +- [ADF — Upgrading from v6.2 to v6.3](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade62-63.md) + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps below +involve code and configuration changes — commit or back up your work first. Node 18 is still required (unchanged +from 4.1.0). + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 6.3 / js-api v7](#aligning-with-adf-63--js-api-v7) + - [js-api v7 type migration](#js-api-v7-type-migration) + - [Compatibility mode removed](#compatibility-mode-removed) + - [Advanced search widgets](#advanced-search-widgets) + - [Content metadata editable binding](#content-metadata-editable-binding) + - [Breadcrumbs replaced by page headings](#breadcrumbs-replaced-by-page-headings) + - [i18n resources moved to ADF](#i18n-resources-moved-to-adf) +- [Breaking changes](#breaking-changes) + - [Viewer and preview moved to aca-content entry points](#viewer-and-preview-moved-to-aca-content-entry-points) + - [aca-shared exports](#aca-shared-exports) + - [Docker and environment-variable overhaul](#docker-and-environment-variable-overhaul) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-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-extensions": "6.3.0", + "@alfresco/js-api": "7.0.0", + "@angular/material-date-fns-adapter": "14.1.3" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.3.0` as well. A new dependency, +`@angular/material-date-fns-adapter`, is required by ADF's date-fns-based advanced date-range search widget. +Angular (`14.1.3`), TypeScript (`4.7.4`), rxjs (`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean +`node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 6.3 / js-api v7 + +Most of this release adapts ACA to the ADF 6.3 breaking changes — driven largely by the `@alfresco/js-api` v7 +major. See the [ADF 6.2 → 6.3 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade62-63.md) +for the underlying details. + +### js-api v7 type migration + +js-api v7 renamed its model types, and ACA migrated to them app-wide (across `aca-content` and `aca-shared`): + +| Before (js-api v6) | After (js-api v7) | +| ------------------------ | -------------------- | +| `MinimalNodeEntity` | `NodeEntry` | +| `MinimalNodeEntryEntity` | `Node` | +| `PathElementEntity` | `PathElement` | +| `SiteBody` | `SiteBodyCreate` | +| `FavoriteBody` | `FavoriteBodyCreate` | + +This changes some **public** ACA surfaces, so extension authors must adapt: + +- **NgRx action payloads** (`@alfresco/aca-shared/store`, `node.actions.ts`) — copy/move/delete/share/favorite + action types changed from `MinimalNodeEntity[]` / `MinimalNodeEntity` to `NodeEntry[]` / `NodeEntry`. +- **`ContentApiService`** (`@alfresco/aca-shared`) method signatures — e.g. `getNode()` / `restoreNode()` now + return `Observable`, `unlockNode()` returns `Promise`, `addFavorite()` / `removeFavorite()` + take `Array`, and `updateLibrary(siteId, siteBody: SiteBodyCreate)`. + +Update your own type references accordingly. (See ADF 6.3 → "JS-API v7 and type migrations".) + +### Compatibility mode removed + +`AlfrescoApiCompatibility` was removed in js-api v7; ACA dropped its use (test utilities now use `AlfrescoApi` / +`NodesApi` / `UploadApi` directly, and the Playwright/API wrappers were refactored onto the v7 model classes, e.g. +`Site.VisibilityEnum.PUBLIC`). If your code referenced `AlfrescoApiCompatibility`, migrate to `AlfrescoApi`. +(See ADF 6.3 → "Removed and hidden items".) + +### Advanced search widgets + +ACA adopted the ADF 6.3 advanced-search widgets in `projects/aca-content/assets/app.extensions.json` / +`app/src/app.config.json`: + +- **Created & Modified date filters merged** into one `date-range-advanced` widget (id `createdModifiedDateRange`, + `field: "cm:created,cm:modified"`); the date format token changed `DD-MMM-YY` → **`dd-MMM-yy`** (moment → + date-fns). +- The size / file-type facets were replaced by the new **`properties`** widget (`field: "content.size,cm:name"`). +- The **SITE** and **Categories** facets switched to the `autocomplete-chips` widget using the new + **`autocompleteOptions`** object model (`[{ "value": "_REPOSITORY_" }]`) instead of plain string `options`. +- New styles for the tabbed facet component (`.adf-search-filter-chip-tabbed`). + +If you customised the search configuration, reconcile it against the new `app.extensions.json`. (See ADF 6.3 → +"Advanced search" and "Search API changes".) + +### Content metadata editable binding + +The metadata tab now uses ADF 6.3's two-way `[(editable)]` binding on `adf-content-metadata-card`, and resets the +editable state to `false` when a node is locked (reacting to the `EditOffline` store action). If you extend the +metadata tab, adopt the two-way binding. + +### Breadcrumbs replaced by page headings + +Following ADF's breadcrumb rework (breadcrumbs moved to the `@alfresco/adf-core/breadcrumbs` secondary entry +point), ACA **replaced the `` on its list pages with an `

` heading** +(favorites, libraries, recent-files, shared-files, trashcan, details, etc.). Any code or test targeting the +`adf-breadcrumb` selector on those pages must be updated. + +### i18n resources moved to ADF + +The join-library message keys (`APP.MESSAGES.ERRORS.JOIN_REQUEST_FAILED` / `JOIN_CANCEL_FAILED` / +`INVALID_SENDER_EMAIL` / `INVALID_RECEIVER_EMAIL`, and `JOINED` / `JOIN_REQUESTED` / `JOIN_CANCELED`) were removed +from ACA's locale files — they are now provided by ADF 6.3. If you overrode these keys, re-source them from ADF. + +## Breaking changes + +### Viewer and preview moved to aca-content entry points + +The standalone `@alfresco/aca-viewer` and `@alfresco/aca-preview` packages were removed and became **secondary +entry points of `@alfresco/aca-content`**. The exported symbols are unchanged — only the import path: + +| Package | Before (v4.1.0) | After (v4.2.0) | +| ------- | ----------------------- | ------------------------------- | +| Viewer | `@alfresco/aca-viewer` | `@alfresco/aca-content/viewer` | +| Preview | `@alfresco/aca-preview` | `@alfresco/aca-content/preview` | + +### aca-shared exports + +The standalone-component migration reshaped `@alfresco/aca-shared`'s public surface: + +- **Toolbar components moved** from `.../components/tool-bar/...` to `.../components/toolbar/...` — deep imports + into the old `tool-bar` path break (the package-root exports still resolve, only the deep path changed). +- **Removed exports:** `OpenInAppModule` (the `OpenInAppComponent` is still exported — import the standalone + component), and `AlfrescoOfficeExtensionService` (plugin handling moved into the rules engine). +- `SharedModule` and `SharedToolbarModule` were moved under `aca-shared/src/lib/deprecated/` and marked + `@deprecated` backward-compat shims — import the standalone components/directives directly. + +### Docker and environment-variable overhaul + +The ACA Docker image was reworked (epic `ACA-4715`). If you run the published image or build your own, note: + +- **`envsubst` templating was removed.** `app/src/app.config.json.tpl` was renamed to `app.config.json` with ADF + runtime tokens (`{protocol}//{hostname}{:port}`) and hard-coded defaults; a new entrypoint + (`docker/docker-entrypoint.d/30-sed-on-appconfig.sh`) patches a **curated set of ~14 runtime env vars** via `sed`. +- **Env vars that are no longer applied at runtime** (plugin toggles, viewer / download-prompt, mobile-app-switch, + session-timeout, etc.) now use fixed defaults and are **silently ignored** if passed — set them in your own + `app.config.json` instead. +- The `--build-arg PROJECT_NAME` was removed (the image is wired to `dist/content-ce`), and the + `envsub` / `assemble-app-config` / `prebuild` / `prestart` / `validate-app-config` npm scripts were deleted. + +See the new `docs/getting-started/docker.md` for the current setup. + +## New components and features + +- **Standalone components** — a large migration converted the `aca-shared` component library to Angular standalone + (dropping most `CoreModule` usage); this is the source of the module-export removals above. +- **Improved plugin handling** — plugin enable/disable moved into the rules engine (`app.rules.ts`); the About + dialog's plugins section was fixed. + +## Behavioural changes + +| Area | Change | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| File lists | Row checkboxes are hidden by default in the Files and Trashcan lists (`[multiselect]="false"`; selection mode stays `multiple`). | +| Document list | The filter header is now retained when query params are present. | +| Security marks | The files document-list preset is now reactive (`filesDocumentListPreset$`), fixing incorrect initial loading of security-marks columns. | +| Styling | `!important` was removed from ACA style overrides (lint-enforced) — re-check custom styles that relied on the old cascade. | +| Security | Incomplete string-escaping in toolbar selectors was hardened (regex escaping). | diff --git a/docs/upgrade-guide/upgrade42-43.md b/docs/upgrade-guide/upgrade42-43.md new file mode 100644 index 000000000..5753cdae4 --- /dev/null +++ b/docs/upgrade-guide/upgrade42-43.md @@ -0,0 +1,133 @@ +--- +Title: Upgrading from ACA v4.2 to v4.3 +--- + +# Upgrading from ACA v4.2 to v4.3 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.2.0 project to +v4.3.0. + +This is a smaller release built on **ADF 6.3.0 → 6.4.0** (`@alfresco/js-api` 7.0.0 → 7.1.0, a minor bump). The main +ADF-driven change is completing the **moment → date-fns** move (ADF 6.4 dropped `moment`), and ACA **adopts several +new ADF 6.4 capabilities** (configurable document-list columns, custom metadata panels). Read the ADF guide +alongside this one: + +- [ADF — Upgrading from v6.3 to v6.4](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade63-64.md) + +Angular, Material, TypeScript, rxjs and the Node version are all **unchanged**. ACA's public library API +(`@alfresco/aca-shared` / `@alfresco/aca-content` entry points) is unchanged too — no exports were removed or +renamed — so most of this upgrade is dependency/config, not code. Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 is still +required (unchanged). + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 6.4](#aligning-with-adf-64) + - [moment removed (date-fns completion)](#moment-removed-date-fns-completion) + - [Configurable document-list columns](#configurable-document-list-columns) + - [Custom metadata side panels](#custom-metadata-side-panels) + - [Folder-rules category autocomplete](#folder-rules-category-autocomplete) +- [Breaking changes](#breaking-changes) + - [Nx 16 workspace migration](#nx-16-workspace-migration) + - [Peer dependency ranges loosened](#peer-dependency-ranges-loosened) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "6.4.0", + "@alfresco/adf-content-services": "6.4.0", + "@alfresco/adf-extensions": "6.4.0", + "@alfresco/js-api": "7.1.0" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.4.0` as well. Four **`moment`-related dependencies were +removed** — `moment`, `moment-es6`, `@angular/material-moment-adapter` and `@mat-datetimepicker/moment` — while +`@angular/material-date-fns-adapter`, `date-fns` and `@mat-datetimepicker/core` are retained. Angular (`14.1.3`), +TypeScript (`4.7.4`), rxjs (`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile, +then reinstall. + +## Aligning with ADF 6.4 + +See the [ADF 6.3 → 6.4 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade63-64.md) +for the underlying changes. + +### moment removed (date-fns completion) + +ADF 6.4 completed its moment → date-fns migration and dropped `moment` as a runtime/peer dependency. ACA followed +suit and removed the `moment` family from `package.json` (see [Library updates](#library-updates)). ACA's own +library/component source was already date-fns-based, so the only code change was in e2e tests, which now format +dates through ADF's `DateFnsUtils.formatDate()` (from `@alfresco/adf-core`) instead of raw `date-fns`. If your fork +still imports `moment` (or the moment Material adapters) transitively via ACA/ADF, add them to your own +`package.json` or migrate to date-fns. (See ADF 6.4 → "Date handling (moment → date-fns)".) + +### Configurable document-list columns + +Adopting ADF 6.4's `DataColumn.isHidden` support, ACA added an `[isHidden]="column.isHidden"` binding to the +`data-column` definitions across its seven document lists (`files`, `favorites`, `favorite-libraries`, +`libraries`, `recent-files`, `shared-files`, `trashcan`), so columns can be shown/hidden. If you customise these +lists, carry the `isHidden` binding through. + +### Custom metadata side panels + +ACA adopts ADF 6.4's `ContentMetadataComponent` `@Input() customPanels` to let extensions contribute extra metadata +panels. This adds a new extension point (see [New components and features](#new-components-and-features)); the +metadata tab now binds `[customPanels]` on `adf-content-metadata-card`. + +### Folder-rules category autocomplete + +The Folder Rules "Has Category" condition gained an autocomplete backed by ADF's `CategoryService.searchCategories()` +(`@alfresco/adf-content-services`). Internally this added an `'auto-complete'` `RuleConditionFieldType`. + +## Breaking changes + +ACA's published library API is unchanged in this release (the `public-api.ts` of every `@alfresco/aca-shared` and +`@alfresco/aca-content` entry point is identical between 4.2.0 and 4.3.0 — no exports removed, renamed or newly +deprecated). The consumer-affecting changes are at the dependency/build level: + +### Nx 16 workspace migration + +The workspace moved to **Nx 16** and the Nx package scope was renamed **`@nrwl/*` → `@nx/*`** (`nx` / `@nx/angular` +/ `@nx/workspace` / `@nx/eslint-plugin` `16.10.0`). `nx.json`, `project.json`, `.eslintrc.json` and `tsconfig.json` +were rewritten accordingly. If you maintain a fork with custom Nx targets or `@nrwl/*` imports, migrate them to +`@nx/*` and run the Nx 16 migrations. + +### Peer dependency ranges loosened + +The published ACA libraries (`projects/aca-content`, `projects/aca-shared`) changed their `peerDependencies` from +caret ranges to `>=` (e.g. `@alfresco/adf-core` `^6.3.0` → `>=6.4.0`, `@alfresco/js-api` `>=7.0.0` → `>=7.1.0`, and +the `@angular/*` / `@ngx-translate/core` / `rxjs` / `zone.js` peers likewise). This mainly affects how versions +resolve when you install those packages. + +## New components and features + +- **Name-column badges** — extensions can add icon badges (with tooltip, and an optional custom component) to the + document-list name column. New public `Badge` interface (`@alfresco/aca-shared`, `extends ContentActionRef` with + a `tooltip`), a new `features.badges` block in `app.extensions.json` (a `badge` needs `id`, `icon`, `tooltip`, + optional `component`), and a new `AppExtensionService.getBadges(node)` method. +- **Custom metadata side panels** — a new `features.customMetadataPanels` extension feature (array of + `contentActionRef`) renders registered extension components as extra metadata panels, surfaced via the new + `AppExtensionService.getCustomMetadataPanels(node)` method. +- **Configurable document-list columns** — see [Configurable document-list columns](#configurable-document-list-columns). +- **Breadcrumb navigation on the Details tab** — the Details page breadcrumb now navigates + (`onBreadcrumbNavigate(path)` dispatching `NavigateToFolder`). + +## Behavioural changes + +| Area | Change | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Info drawer | The info drawer / Details tab now opens **over a custom file preview** — `PageComponent.infoDrawerOpened$` no longer suppresses the drawer while a viewer outlet is active. | +| Library metadata | The library-metadata info-drawer was reworked into a single reactive form; update/cancel now reflect immediately in the UI, and renaming a library to a whitespace-only name is prevented. | +| Edit offline | Toggling "edit offline" now reselects the node so dependent UI refreshes. | +| Icons | Toolbar/info-drawer icons and button pressed/focus states were updated to match the current design (e.g. the info-drawer toggle icon `menu_open` → `view_sidebar`). | diff --git a/docs/upgrade-guide/upgrade43-441.md b/docs/upgrade-guide/upgrade43-441.md new file mode 100644 index 000000000..f34cdc71b --- /dev/null +++ b/docs/upgrade-guide/upgrade43-441.md @@ -0,0 +1,190 @@ +--- +Title: Upgrading from ACA v4.3 to v4.4.1 +--- + +# Upgrading from ACA v4.3 to v4.4.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.3.0 project to +v4.4.1 (covering the 4.4.0 and 4.4.1 releases). + +This is a large release: it moves **ADF 6.4.0 → 6.7.1** (spanning several ADF releases) and `@alfresco/js-api` +7.1.0 → 7.6.1, so most of the work is **adapting to the ADF breaking changes across 6.5.2, 6.6.0 and 6.7.x**. Read +those ADF guides alongside this one: + +- [ADF — Upgrading from v6.4 to v6.5.2](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade64-652.md) +- [ADF — Upgrading from v6.5.2 to v6.6.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade652-66.md) +- [ADF — Upgrading from v6.6.0 to v6.7.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade66-671.md) + +Angular, Material, TypeScript, rxjs and the Node version are all **unchanged**; the build tooling moves to +**Nx 17**. ACA's published library API (`@alfresco/aca-shared` / `@alfresco/aca-content` entry points) is +unchanged — no exports removed or renamed — so the consumer-facing work is mostly **`app.config.json` / +`app.extensions.json` configuration** plus adopting new ADF capabilities. Read the +[breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 is still +required (unchanged). The steps below involve configuration changes — commit or back up your work first. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 6.5 / 6.6 / 6.7](#aligning-with-adf-65--66--67) + - [Authentication — PKCE / code flow](#authentication--pkce--code-flow) + - [Search — Elasticsearch, date range and highlighting](#search--elasticsearch-date-range-and-highlighting) + - [Content metadata read-only model](#content-metadata-read-only-model) + - [Viewer close-button position](#viewer-close-button-position) + - [Document-list resizing, persistence and drag-drop columns](#document-list-resizing-persistence-and-drag-drop-columns) + - [Theming](#theming) + - [Disabling tags and categories](#disabling-tags-and-categories) +- [Breaking changes](#breaking-changes) + - [Configuration changes](#configuration-changes) + - [Nx 17 workspace migration](#nx-17-workspace-migration) + - [adf-testing dependency dropped](#adf-testing-dependency-dropped) + - [E2E selector changes](#e2e-selector-changes) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "6.7.1", + "@alfresco/adf-content-services": "6.7.1", + "@alfresco/adf-extensions": "6.7.1", + "@alfresco/js-api": "7.6.1" + } +} +``` + +`@alfresco/adf-cli` moves to `6.7.1`; **`@alfresco/adf-testing` was removed** as a dependency. (4.4.0 shipped ADF +`6.7.0` / js-api `7.6.0`; the 4.4.1 patch bumps them to `6.7.1` / `7.6.1`.) The build tooling +moved to **Nx 17** (`@nx/*` / `nx` `17.x`, from `16.10.0`). Angular (`14.1.3`), TypeScript (`4.7.4`), rxjs +(`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 6.5 / 6.6 / 6.7 + +Most of this release adapts ACA to the ADF breaking changes across three releases. Each item links back to the ADF +guide that describes the underlying change. + +### Authentication — PKCE / code flow + +ACA switched its default OAuth2 flow to **PKCE authorization-code flow**: in `app.config.json`, `implicitFlow: true` became `implicitFlow: false` + **`codeFlow: true`** (and a new +`APP_CONFIG_OAUTH2_CODE_FLOW` Docker env var). +If your `app.config.json` pins `oauth2.implicitFlow`, review it against the new default. (See ADF 6.6 → +"Authentication and SSO renames".) + +### Search — Elasticsearch, date range and highlighting + +- **Elasticsearch query migration** — the search configuration in `app.extensions.json` was updated for the + Elasticsearch backend (e.g. `-PNAME:'0/wiki'` → `-PATH:'//cm:wiki/*'`, and autocomplete options gained a + `query`). (See ADF 6.5.2 → "Search query migration (Elasticsearch)".) +- **Date-range widget** — every `"selector": "date-range-advanced"` reverted to **`"date-range"`** (now the tabbed + advanced widget), the date-format token changed `DD-MMM-YY` → **`dd-MMM-yy`**, and `displayedLabelsByField` maps + were added. (See ADF 6.6 → "Search date-range widget replaced".) +- **Search highlighting** — ACA now renders ADF search `highlight` snippets (config added under the results row). + +If you customised the search configuration, reconcile it against the new `app.extensions.json`. + +### Content metadata read-only model + +Following ADF's content-metadata rework, ACA's metadata tab adopted the **`readOnly`** model (the previous +`editable` input was inverted to `readOnly` with the opposite meaning) and re-wires the displayed aspect through +the store. If you extend the metadata tab, migrate `editable` usage to `readOnly`. (See ADF 6.6 → "Content +metadata property panels".) + +### Viewer close-button position + +The viewer close button's position is now configurable via `viewer.closeButtonPosition` in `app.config.json` +(default `right`), adopting ADF 6.6's `CloseButtonPosition`. (See ADF 6.6 → "Viewer close button".) + +### Document-list resizing, persistence and drag-drop columns + +ACA adopted the ADF document-list column capabilities added across 6.5.2–6.7.x: + +- **Resizable lists** — all document lists set `[isResizingEnabled]="true"` and `[blurOnResize]="false"`. +- **Per-column opt-out** — columns are resizable by default in newer ADF, so ACA marks the thumbnail/icon columns + `"resizable": false` (new `resizable` field in `extension.schema.json`). +- **Persistence & drag-drop** — column size / visibility / order are persisted (via ADF's + `setColumns*` inputs and `columns*Changed` outputs) and columns can be reordered by drag-drop + (`"draggable": true`). Stable `id="app.*"` values were added to every `data-column`. + +### Theming + +- **Internal Angular Material CSS classes** — ACA removed most `.mat-*` / `.cdk-*` selector overrides in favour of + ACA-owned `aca-*` / `adf-*` classes (preparation for ADF's Material MDC migration). If your fork overrides ACA + styles via Material internals, re-audit them. +- **Theme reference variables** — hardcoded/removed theme references were replaced with dynamic `--theme-*` tokens + (e.g. `--theme-secondary-text`, `--theme-card-background-color`, `--theme-sidenav-active-text-color`). (See ADF + 6.6 → "Theme reference variables".) + +### Disabling tags and categories + +ACA can now disable the tags and categories features via `app.config.json` (default `true`), using ADF's +`TagService.areTagsEnabled()` / `CategoryService.areCategoriesEnabled()`. + +> **Config-key rename in 4.4.1:** the ACA keys were introduced in 4.4.0 as `plugins.tags` / `plugins.categories`, +> then **renamed in 4.4.1 to `plugins.tagsEnabled` / `plugins.categoriesEnabled`** (ACS-6924) to avoid a naming +> conflict with ADF's own plugin keys. Use the new `*Enabled` names in a custom `app.config.json` (or via the +> `APP_CONFIG_PLUGIN_TAGS` / `APP_CONFIG_PLUGIN_CATEGORIES` env vars) — the ACA rule functions +> `areTagsEnabled` / `areCategoriesEnabled` read the renamed keys. + +## Breaking changes + +ACA's published library API is unchanged in this release — the `public-api.ts` of every `@alfresco/aca-shared` and +`@alfresco/aca-content` entry point is byte-identical between 4.3.0 and 4.4.0 (no exports removed, renamed or newly +deprecated). The breaking changes are at the configuration, build and dependency level. + +### Configuration changes + +Update your `app.config.json` / `app.extensions.json` (and any custom extensions): + +- `oauth2.implicitFlow: true` → `implicitFlow: false` + `codeFlow: true` (PKCE). +- The `date-range-advanced` search selector was removed — use `date-range`. +- Viewer extensions are now keyed under an **`extensions`** block (by `fileExtension`) instead of the old `content` + key in `app.extensions.json`. + +### Nx 17 workspace migration + +The workspace moved to **Nx 17** (`@nx/*` / `nx` `17.x`). `nx.json` and the cache configuration were rewritten. If +you maintain a fork with custom Nx targets, run the Nx 17 migrations. + +### adf-testing dependency dropped + +`@alfresco/adf-testing` was removed from ACA's dependencies. If your tests imported it via ACA, add it to your own +`devDependencies`. + +### E2E selector changes + +The viewer close-button e2e locator changed from `button[data-automation-id="adf-toolbar-back"]` to +`button.adf-viewer-close-button` (following ADF's `adf-toolbar-back` → `adf-toolbar-left-back` id change). Update +any e2e selectors targeting the old value. + +## New components and features + +- **Search highlighting** — matched terms in search results are highlighted (`aca-highlight`), configurable via + the results row `highlight` settings. +- **Configurable / persistent / draggable document-list columns** — see + [Document-list resizing, persistence and drag-drop columns](#document-list-resizing-persistence-and-drag-drop-columns); + the search-results list is now configurable with the same column model. +- **Dynamic Tags column** — the search-results tags column and its `getTags` call are now gated by + `tagsService.areTagsEnabled()` and driven by `app.config.json`. +- **Manage permissions from the viewer** — the *Manage permissions* action can now be triggered from inside a file + preview. +- **`AppExtensionService.updateSidebarActions()`** — a new (additive) public method that publishes + `features.sidebar.toolbar` content actions; new `areTagsEnabled` / `areCategoriesEnabled` rule functions are + exported from `@alfresco/aca-shared/rules`. + +## Behavioural changes + +| Area | Change | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Smart folders | *Edit aspects*, *Manage rules* and *Manage permissions* are now hidden for smart folders, and *Manage permissions* is hidden on multi-selection. | +| Records | *Edit Offline* and *Upload New Version* are hidden for declared records. | +| Storage | The local-storage prefix is set from the current username on login (via the unified `getUsername()` accessor), fixing an ADW prefix issue. | +| Libraries | After deleting a library from the Manage Members view, the user is redirected to the libraries page. | +| Search input | Clicking a search input that already contains text now lets you edit the term. | +| Viewer | *View details* is active in the expanded view. | diff --git a/docs/upgrade-guide/upgrade441-501.md b/docs/upgrade-guide/upgrade441-501.md new file mode 100644 index 000000000..7f83afe42 --- /dev/null +++ b/docs/upgrade-guide/upgrade441-501.md @@ -0,0 +1,173 @@ +--- +Title: Upgrading from ACA v4.4.1 to v5.0.1 +--- + +# Upgrading from ACA v4.4.1 to v5.0.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.4.1 project to +v5.0.1 (covering the 5.0.0 and 5.0.1 releases). + +**This is a major release.** The headline change is **Angular 14 → 15**, which brings the **Angular Material MDC +migration** — the single biggest source of visual breakage. It moves **ADF 6.7.1 → 7.0.0-alpha.2** and +**`@alfresco/js-api` 7.6.1 → 8.0.0-alpha.2**, and **TypeScript 4.7 → 4.9**. The ADF span crosses three ADF guides +(most relevant is the **7.0.0-alpha.2** section of the 6.9 → 7.0 guide, which is the Angular-15 + MDC step): + +- [ADF — Upgrading from v6.7.1 to v6.8.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade671-68.md) +- [ADF — Upgrading from v6.8 to v6.9](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade68-69.md) +- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0-alpha.2** section) + +Because of the MDC migration, budget time to re-audit any Material CSS overrides in your fork. Read the +[breaking changes](#breaking-changes) carefully. + +> **rxjs / Nx note:** although ADF's 7.0.0-alpha.2 itself moved to rxjs 7.8 and a newer Nx, ACA's root manifest at +> 5.0.1 still pins **rxjs 6.6.6** and **Nx 17.3.1** (and zone.js 0.11.8), so those ADF implications do **not** apply +> to your ACA app at this version. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your +application to **Angular 15 / TypeScript 4.9** in lockstep. Node 18 (`.nvmrc`) is unchanged. Budget time to build, +re-theme (Material MDC) and re-test after upgrading. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with Angular 15 / ADF 7.0-alpha](#aligning-with-angular-15--adf-70-alpha) + - [Angular Material MDC migration](#angular-material-mdc-migration) + - [ADF standalone components and MaterialModule](#adf-standalone-components-and-materialmodule) + - [ADF Notification Service](#adf-notification-service) + - [ADF document-list reload](#adf-document-list-reload) + - [js-api v8](#js-api-v8) +- [Breaking changes](#breaking-changes) + - [Library public API](#library-public-api) + - [Services and state rework](#services-and-state-rework) + - [Extension schema and configuration](#extension-schema-and-configuration) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@angular/core": "15.2.10", + "@angular/material": "15.2.9", + "typescript": "4.9.5", + "@alfresco/adf-core": "7.0.0-alpha.2", + "@alfresco/adf-content-services": "7.0.0-alpha.2", + "@alfresco/adf-extensions": "7.0.0-alpha.2", + "@alfresco/js-api": "8.0.0-alpha.2" + } +} +``` + +`@alfresco/adf-cli` moves to `7.0.0-alpha.2` too. `rxjs` (`6.6.6`), `nx` (`17.3.1`), `zone.js` (`0.11.8`) and Node +(`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with Angular 15 / ADF 7.0-alpha + +Most of this release is the Angular 15 platform move and adapting to ADF's 7.0.0-alpha.2 changes. See the ADF +[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) +(7.0.0-alpha.2 section) for the underlying detail. + +### Angular Material MDC migration + +Angular 15's Material components were rewritten onto MDC, changing their internal DOM and CSS class names +(`.mat-*` → `.mat-mdc-*`). ACA's NG15 migration (ACS-6693) was followed by a wave of MDC-driven restyling and +layout fixes (toolbar buttons, create/upload buttons, `mat-tabs`, dialog paddings, search input, bulk-action +dropdown, badges, folder-rules dialogs). **If your fork styles Material internals — directly or by overriding ACA +component styles — you must re-audit those styles.** This is the biggest source of visual breakage in this upgrade. + +### ADF standalone components and MaterialModule + +ADF 7.0-alpha.2 makes most components standalone and deprecates the shared `MaterialModule`. ACA: + +- updated document-list / column / context-menu / sidenav imports to the **standalone** ADF symbols (e.g. importing + `DynamicColumnComponent` / `DocumentListPresetRef` directly instead of `ExtensionsModule`); +- removed the deprecated shared **`MaterialModule`** from its imports. + +If your fork imports ADF via NgModules or `MaterialModule`, import the standalone components / specific +`@angular/material/*` modules directly. + +### ADF Notification Service + +ACA now calls ADF's `NotificationService` directly for snackbars instead of dispatching NgRx snackbar actions +(reworked across the content-management / node-template services, search input, toggle-edit-offline, +toggle-join-library, and the library/template/upload/router effects). If you dispatched those ACA snackbar actions, +call the ADF service instead. + +### ADF document-list reload + +ACA switched its list-refresh plumbing to ADF's **`DocumentListService.reload()` / `reload$`** (a 7.0.0-alpha.2 +addition), removing its own reload logic from `app-hook.service` and related effects/actions. + +### js-api v8 + +`@alfresco/js-api` moved to `8.0.0-alpha.2`. ACA wired the linked js-api path into `tsconfig.adf.json` and raised +the ACA libraries' peer ranges accordingly. Update any pins to allow js-api 8. + +## Breaking changes + +### Library public API + +The published ACA libraries changed their public surface: + +**`@alfresco/aca-shared`:** + +- **Renamed:** `aca-file-auto-download.service` → **`auto-download.service`** (`AcaFileAutoDownloadService` reworked + into `AutoDownloadService`). +- **Moved:** the `modal-configuration` model moved out of `@alfresco/aca-shared` to `@alfresco/aca-shared/store`. +- **Added:** `constants`, the `plugin-enabled.guard` (route guard), and the new `app-settings.service` / + `user-profile.service` (see [Services and state rework](#services-and-state-rework)). + +**`@alfresco/aca-shared/store`:** + +- **Removed `StoreModule`** (`store.module`) — effect registration was simplified; register effects via the app's + `app-store.module.ts` instead of importing the old module. +- **Removed** `dialog.effects` (dialog effects were removed) and the unused logout action. +- **Added** the relocated `modal-configuration` model. + +**`@alfresco/aca-content/viewer`:** now also exports `PreviewComponent`. + +### Services and state rework + +Several concerns moved out of the NgRx store into root-provided services (migrate direct store/config reads): + +- **`UserProfileService`** — holds the current user profile (`userProfile$`, `loadUserProfile()` via `PeopleApi` + + groups); replaces the profile slice of the app reducer. +- **`AppSettingsService`** — typed getters over `AppConfigService` (`appName`, `appVersion`, `appCopyright`, + `landingPage`, `aosHost`, `mimeTypes`, `appLogoUrl`, …). Roughly 800 lines were removed from `app.config.json` + and the corresponding store state; components now read settings from this service. +- **`AutoDownloadService`** — the renamed auto-download service now reads its size threshold from `AppSettingsService`. + +### Extension schema and configuration + +Update your `app.config.json` / `app.extensions.json` and any custom extensions: + +- **`aca:fields` → `app:fields`** — the custom search-form field property was renamed (in `DEFAULT_SEARCH`, + `DUBLIN_CORE`, `EFFECTIVITY`). Rename it in any custom search configuration. +- **`extension.schema.json` review** — the `userActions` and `mainAction` feature definitions (and a duplicate + top-level `badges`) were removed / relocated. Extensions relying on those schema keys must be updated. +- **Blank-page route removed** — the `blank` route was removed from `app.routes.ts` and `app.config.json`. +- **Plugin routing guard** — routes for optional plugins are now gated by a new `plugin-enabled.guard` (exported + from `@alfresco/aca-shared`). + +## New components and features + +- **Manage Holds / bulk Legal Hold** — a new *Manage Holds* dialog with Apply-New-Hold / Manage-Existing-Holds + tabs for bulk operations, backed by new `bulk-actions-dropdown` and `datatable-cell-badges` components and new + `bulk-actions` / badge-`tooltip` entries in `extension.schema.json` (aligns with ADF 7.0's Legal Hold area). +- **Security marks for Folder Rules** — rule actions can set security marks. +- **HxI connector availability** — a new store selector reports whether the HxI connector is available. + +## Behavioural changes + +| Area | Change | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Multi-select | Multi-selection is now **on by default** across the document lists (files, favorites, libraries, recent-files, shared-files, search-results, trashcan). | +| Search results | Delete and move actions are now available on the search-results page. | +| Folder rules | Rule-action node selection changed from multiple to **single**. | +| Checkboxes | Selection checkboxes use the Hyland-blue checked state. | +| Testing (fork note) | Protractor e2e was removed (migration to Playwright is complete); if your fork extends ACA's Protractor harness, move to Playwright. | diff --git a/docs/upgrade-guide/upgrade501-511.md b/docs/upgrade-guide/upgrade501-511.md new file mode 100644 index 000000000..3741d3f63 --- /dev/null +++ b/docs/upgrade-guide/upgrade501-511.md @@ -0,0 +1,110 @@ +--- +Title: Upgrading from ACA v5.0.1 to v5.1.1 +--- + +# Upgrading from ACA v5.0.1 to v5.1.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.0.1 project to +v5.1.1 (there was no 5.1.0 release). + +This is a small release on the ADF 7.0 alpha line: it moves **ADF 7.0.0-alpha.2 → 7.0.0-alpha.3** and +`@alfresco/js-api` 8.0.0-alpha.2 → 8.0.0-alpha.3. Angular (15.2), TypeScript (4.9), rxjs, Nx, zone.js and Node are +all **unchanged**. The work is adapting to the ADF alpha.3 **auth + js-api relocation** changes, plus adopting the +new **Knowledge Retrieval** feature. The relevant ADF guide is the **7.0.0-alpha.3** section of: + +- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0-alpha.3** section) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 +(`.nvmrc`) and the Angular 15 platform are unchanged from 5.0.1. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 7.0-alpha.3](#aligning-with-adf-70-alpha3) + - [AlfrescoApiService moved to adf-content-services](#alfrescoapiservice-moved-to-adf-content-services) + - [Functional route guards](#functional-route-guards) +- [Breaking changes](#breaking-changes) + - [aca-playwright-shared is now a published library](#aca-playwright-shared-is-now-a-published-library) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "7.0.0-alpha.3", + "@alfresco/adf-content-services": "7.0.0-alpha.3", + "@alfresco/adf-extensions": "7.0.0-alpha.3", + "@alfresco/js-api": "8.0.0-alpha.3" + } +} +``` + +`@alfresco/adf-cli` moves to `7.0.0-alpha.3` too. Angular (`15.2.10`), `@angular/material` (`15.2.9`), TypeScript +(`4.9.5`), rxjs (`6.6.6`), Nx (`17.3.1`), zone.js (`0.11.8`) and Node (`.nvmrc` `18`) are unchanged. Clean +`node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 7.0-alpha.3 + +See the **7.0.0-alpha.3** section of the ADF +[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) +("Auth and js-api relocation") for the underlying changes. + +### AlfrescoApiService moved to adf-content-services + +ADF alpha.3 moved `AlfrescoApiService` (and `AlfrescoApiServiceMock`) from `@alfresco/adf-core` to +`@alfresco/adf-content-services`. ACA updated all its imports accordingly: + +```ts +// Before +import { AlfrescoApiService } from '@alfresco/adf-core'; + +// After +import { AlfrescoApiService } from '@alfresco/adf-content-services'; +``` + +Update this import wherever your fork or extensions use it. (See ADF 7.0.0-alpha.3 → "`AlfrescoApiService` moved +from `@alfresco/adf-core` to `@alfresco/adf-content-services`".) + +### Functional route guards + +Following ADF's move to functional route guards (the `AuthGuardBase` class was deleted and the guards became +`CanActivateFn` values), ACA converted its own guards to the functional pattern +(`view-profile.guard`, `plugin-enabled.guard`, `shared.guard`, and the `extensions-data-loader.guard`). If your +fork subclasses ACA guards or references them as injectable classes, migrate to the functional form. (See ADF +7.0.0-alpha.3 → "Auth route guards are now functional `CanActivateFn` values".) + +## Breaking changes + +ACA's `@alfresco/aca-shared` and `@alfresco/aca-content` root public APIs are unchanged in this release (no exports +removed or renamed). The consumer-facing changes are the ADF import move above and the test-library packaging +change below. + +### aca-playwright-shared is now a published library + +`projects/aca-playwright-shared` became a **buildable, publishable Angular library** (it gained `ng-package.json` +and `package.json` and is exported for consumers). If you wrote Playwright e2e tests against ACA, you can now +import the shared Playwright helpers from the published `@alfresco/aca-playwright-shared` package instead of a +relative source path. + +## New components and features + +- **Knowledge Retrieval (AI)** — a new feature that returns an AI response for one or more selected files, adopting + ADF alpha.3's Knowledge Retrieval / `AgentService` / `SearchAiService`. It adds an `agents-button` and a + `search-ai-input-container` component, and can be **toggled in the Docker image** via a runtime env var. + +## Behavioural changes + +| Area | Change | +| ------------- | ------------------------------------------------------------------------ | +| Document list | The list refreshes after a file version is restored. | +| Selection | An error page is shown when an action is invoked with no nodes selected. | +| Extensions | Visibility rules now accept arrays (documented). | +| Search | The current location is passed as a query parameter. | diff --git a/docs/upgrade-guide/upgrade511-520.md b/docs/upgrade-guide/upgrade511-520.md new file mode 100644 index 000000000..20156bf86 --- /dev/null +++ b/docs/upgrade-guide/upgrade511-520.md @@ -0,0 +1,142 @@ +--- +Title: Upgrading from ACA v5.1 to v5.2 +--- + +# Upgrading from ACA v5.1 to v5.2 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.1.1 project to +v5.2.0. + +This release is another platform lift: **Angular 15 → 16**, **TypeScript 4.9 → 5.0**, **rxjs 6 → 7** and +**zone.js 0.11 → 0.13**, on **ADF 7.0.0-alpha.3 → 7.0.0-alpha.6** (`@alfresco/js-api` 8.0.0-alpha.3 → alpha.6). The +big new feature is **Saved Searches**. The relevant ADF changes are the **7.0.0-alpha.4** (Angular 15 → 16) and +**7.0.0-alpha.6** sections of: + +- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0-alpha.4** and **7.0.0-alpha.6** sections) + +Nx (17.3.1), `@ngx-translate/core` and Node (`.nvmrc` 18) are unchanged. Because of the Angular 16 / Material 16 +move, budget time to re-audit Material styles and re-test. Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your +application to **Angular 16 / TypeScript 5.0 / rxjs 7 / zone.js 0.13** in lockstep. Node 18 (`.nvmrc`) is unchanged. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with Angular 16 / ADF 7.0-alpha](#aligning-with-angular-16--adf-70-alpha) + - [Angular 16 migration](#angular-16-migration) + - [rxjs 7](#rxjs-7) + - [TypeScript 5 class-field initialization](#typescript-5-class-field-initialization) + - [Version manager inputs](#version-manager-inputs) +- [Breaking changes](#breaking-changes) + - [Platform lockstep](#platform-lockstep) + - [Context-menu action injection](#context-menu-action-injection) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@angular/core": "16.2.9", + "@angular/material": "16.2.9", + "typescript": "5.0.4", + "rxjs": "7.5.7", + "zone.js": "0.13.3", + "@ngrx/store": "16.3.0", + "@alfresco/adf-core": "7.0.0-alpha.6", + "@alfresco/adf-content-services": "7.0.0-alpha.6", + "@alfresco/adf-extensions": "7.0.0-alpha.6", + "@alfresco/js-api": "8.0.0-alpha.6" + } +} +``` + +`@alfresco/adf-cli`, the `@angular/*` toolchain, `@angular-eslint/*`, `ng-packagr` and `@ngrx/*` all move to their +Angular-16 lines. `nx` (`17.3.1`), `@ngx-translate/core` and Node (`.nvmrc` `18`) are unchanged. Clean +`node_modules` and the lockfile, then reinstall. + +## Aligning with Angular 16 / ADF 7.0-alpha + +See the **7.0.0-alpha.4** / **7.0.0-alpha.6** sections of the ADF +[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) +for the underlying changes. + +### Angular 16 migration + +The Angular 16 lift (ACS-6693 / the NG16 migration) rewrote a large amount of ACA to Angular 16 / Material 16 / +ngrx 16, with the dominant pattern being **constructor DI → `inject()`** across components, effects and services. +A batch of **Material-16 visual fixes** was folded in (checkbox focus colour, create-rule dialog, input fill, +sidenav/menu colours). If your fork styles Material internals or overrides ACA component styles, re-audit them. +(Some NG16 fixes in that squashed migration were provisional — re-test the areas you customise.) + +### rxjs 7 + +rxjs moved 6 → 7. The main source change was tightening empty subjects to **`Subject`**. Note ACA +**deliberately kept `toPromise()`** (still present in a handful of services) rather than migrating to +`firstValueFrom` / `lastValueFrom`; if you do the migration in your own code, be aware `toPromise` is deprecated in +rxjs 7. + +### TypeScript 5 class-field initialization + +TypeScript 5 / Angular 16 enforce stricter class-field semantics (`useDefineForClassFields`): a class-field +initializer that references a constructor-injected dependency now runs **before** the constructor assigns it. ACA +hit this in `FolderRuleSetsService` (`selectedRuleSet$` referenced an injected service in a field initializer and +threw on the Manage Rules page); the fix moved the observable construction into the constructor. **Audit your own +field initializers that use injected dependencies** and move them into the constructor (or use `inject()`). + +### Version manager inputs + +Adopting ADF alpha.4's `VersionManagerComponent` inputs, ACA's versions tab now binds `[allowViewVersions]`, +`[allowVersionDelete]` and `[showActions]`, driven by new `app.config.json` keys under **`adf-version-manager`** +(`allowViewVersions` / `allowVersionDelete` / `showActions`, default `true`) exposed through `AppSettingsService`. + +> The process-services-cloud changes in ADF alpha.4/alpha.6 (`counters$` → `counters`, `RUNNING_STATUS` → +> `DEPLOYED_STATUS`, `ContainerModel` getters, the process/task search tokens) do **not** apply to ACA — they are +> process-cloud only. + +## Breaking changes + +ACA's published library API is **additive only** this release — no exports were removed, renamed or deprecated +(the barrels gain `NavigationHistoryService` in `@alfresco/aca-shared` and `aca-search-utils` in +`@alfresco/aca-content`; the store gains a `CustomContextMenu` action). The breaking work is the platform move. + +### Platform lockstep + +You must move your application to **Angular 16, TypeScript 5.0, rxjs 7 and zone.js 0.13** together with ACA. Run +the Angular 16 update (`ng update @angular/core@16 @angular/cli@16 @angular/material@16`), address the TypeScript-5 +class-field caveat above, and re-audit Material 16 styles. A new +`@angular-eslint/template/prefer-self-closing-tags` lint rule was enabled (cosmetic template churn). + +### Context-menu action injection + +The context menu was split so custom actions can be injected. A new base directive **`[acaContextActions]`** (with +a `customActions` `@Input()`), a `CustomContextMenuComponent`, and a new injection token +**`CONTEXT_MENU_CUSTOM_ACTIONS`** were added, alongside a store `CustomContextMenu` action. There are now two +population modes: the default `acaContextActions` (loads from `app.extensions.json`) or injecting an array of +rule-formatted actions via `customActions` / the token. This is additive, but if you customised the context menu, +see `docs/features/context-menu-actions.md` for the new model. + +## New components and features + +- **Saved Searches** — save the current search, manage saved searches, and edit / save-as-new. Adds a + `save-search` dialog and an `[acaSaveSearch]` directive, a full-page **Manage Searches** list at the new + `saved-searches` route (`SavedSearchesSmartListComponent`, guarded by `AuthGuard`), and a sidenav entry + registered as the `app.search.navbar` extension component (under a new `app.navbar.secondary` group in + `app.extensions.json`). It is backed by ADF's `SavedSearchesService` / `SavedSearch` (ADF 7.0-alpha.4). +- **Context-menu custom-action injection** — see [Context-menu action injection](#context-menu-action-injection). +- **`NavigationHistoryService`** (`@alfresco/aca-shared`) — tracks router history so views can restore the last + selection (used by the Knowledge Retrieval "keep selection on back-navigation" behaviour). + +## Behavioural changes + +| Area | Change | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Knowledge Retrieval | Agent avatars are loaded from the backend (previously mocked); the query/question is removed from the input on the results page; selections and the question are kept when navigating back to the previous page. | +| Pagination | The items-per-page selector button is now visible. | +| Version manager | Whether versions can be viewed/deleted and whether actions show is now configurable via `app.config.json` (`adf-version-manager.*`). | diff --git a/docs/upgrade-guide/upgrade520-530.md b/docs/upgrade-guide/upgrade520-530.md new file mode 100644 index 000000000..17b71ccb4 --- /dev/null +++ b/docs/upgrade-guide/upgrade520-530.md @@ -0,0 +1,129 @@ +--- +Title: Upgrading from ACA v5.2 to v5.3 +--- + +# Upgrading from ACA v5.2 to v5.3 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.2.0 project to +v5.3.0. + +This is a small maintenance release on the ADF 7.0 alpha line: it moves **ADF 7.0.0-alpha.6 → 7.0.0-alpha.7** and +`@alfresco/js-api` 8.0.0-alpha.6 → 8.0.0-alpha.7, bumps **rxjs 7.5.7 → 7.8.1** and patches +`@angular-devkit/build-angular` (16.2.9 → 16.2.16). Angular (16.2.9), Material (16.2.9), TypeScript (5.0.4), +zone.js (0.13.3), Nx (17.3.1) and Node (`.nvmrc` 18) are all **unchanged**. Most of ADF's alpha.7 changes are +`process-services-cloud` only and do not affect ACA, so the work this cycle is mostly ACA's own fixes and a few new +capabilities. The corresponding ADF guide is the **7.0.0-alpha.7** section of: + +- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0-alpha.7** section) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 16 / +TypeScript 5 platform and Node 18 (`.nvmrc`) are unchanged from 5.2.0. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 7.0-alpha.7](#aligning-with-adf-70-alpha7) +- [Breaking changes](#breaking-changes) + - [Required component inputs](#required-component-inputs) + - [DeleteNodesAction gained an allowUndo argument](#deletenodesaction-gained-an-allowundo-argument) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "7.0.0-alpha.7", + "@alfresco/adf-content-services": "7.0.0-alpha.7", + "@alfresco/adf-extensions": "7.0.0-alpha.7", + "@alfresco/js-api": "8.0.0-alpha.7", + "rxjs": "7.8.1" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `7.0.0-alpha.7` too, and +`@angular-devkit/build-angular` moves `16.2.9 → 16.2.16` (a Vite security bump). Angular (`16.2.9`), +`@angular/material` (`16.2.9`), TypeScript (`5.0.4`), zone.js (`0.13.3`), `nx` (`17.3.1`) and Node (`.nvmrc` `18`) +are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 7.0-alpha.7 + +See the **7.0.0-alpha.7** section of the ADF +[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) +for the full detail. ADF alpha.7 is dominated by the **`process-services-cloud` standalone migration and removals** +(Start-Task-Cloud components, several process-cloud pipes/directives and NgModules, identity DI tokens) — **none of +which apply to ACA**, which does not depend on `@alfresco/adf-process-services-cloud`. The only cross-cutting +alpha.7 items are that ADF's `@alfresco/adf-core` peers were pinned to **exact Angular 16.2.9** (ACA already tracks +16.2.9, so no change) and that `@alfresco/adf-testing` was removed (ACA dropped that dependency back in 4.4.1). In +practice this ADF bump is drop-in for ACA. + +## Breaking changes + +ACA's published library API is effectively unchanged this release — every `@alfresco/aca-shared` and +`@alfresco/aca-content` `public-api.ts` barrel is byte-identical between 5.2.0 and 5.3.0 (no exports added, removed +or renamed). The two consumer-facing changes below are signature-level. + +> **Non-change (informational):** a migration of Saved Searches from the config file to the preferences API +> (ACS-9166) was merged and then **reverted** before 5.3.0, so Saved Searches storage is unchanged from 5.2.0. No +> action is needed — this is only noted in case you diff the intermediate commits. + +### Required component inputs + +Following Angular 16's required-inputs feature, several component `@Input()`s were marked +`@Input({ required: true })`. Two are on **exported `@alfresco/aca-shared` components**: + +- `ToolbarComponent` — `items` is now required. +- `InfoDrawerComponent` — its primary input is now required. + +(Others were applied to internal components: `rule-list` / `rule-list-item`, `datatable-cell-badges`, +`search-results-row`, and the sidenav `button-menu` / `expand-menu`.) If your fork or extension instantiates any of +these components in a template **without binding the now-required input, the Angular compiler will error** +(`NG8008`). Bind the input, or remove the usage. + +### DeleteNodesAction gained an allowUndo argument + +`DeleteNodesAction` (exported from `@alfresco/aca-shared/store`) and +`ContentManagementService.deleteNodes()` gained a second parameter, `allowUndo`, defaulting to `true`: + +```ts +// aca-shared/store +new DeleteNodesAction(payload /* , allowUndo = true */); + +// content-management.service +deleteNodes(items: NodeEntry[], allowUndo = true): void; +``` + +This is backward-compatible (the new argument is optional and preserves the previous behaviour). Pass +`allowUndo: false` to delete without offering the **Undo** snackbar action. + +## New components and features + +- **Folder information dialog** (MNT-24575) — a new dialog that displays folder details (retrieved via API, with a + retry on failure). It is not offered for items in the trashcan. +- **Suppressible delete-undo** (ACS-8604) — see + [DeleteNodesAction gained an allowUndo argument](#deletenodesaction-gained-an-allowundo-argument); callers can now + delete nodes without the Undo snackbar. +- **`takeUntilDestroyed` subscription cleanup** (ACS-8959) — ACA adopted Angular's `takeUntilDestroyed` operator + (with `DestroyRef`) across the folder-rules components and several `aca-content` components, replacing manual + `ngOnDestroy` / `takeUntil(Subject)` teardown. This is an internal refactor, but if your fork subclasses these + components or relied on their destroy `Subject`s, adopt the same pattern. + +## Behavioural changes + +| Area | Change | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Search input | The search input is now a reactive form control that disallows certain special characters (showing a validation error) and rewrites a leading `text:` to `TEXT:` on submit rather than erroring. | +| Search results | A loading spinner is now shown on the search-results page while filtering for files or folders. | +| Libraries | The context menu is no longer empty when multiple libraries are selected; the *Join library* option now shows the correct icon. | +| Breadcrumb | The file title in the breadcrumb now updates after the file is renamed. | +| Sidenav | The `expandedSidenav` flag is removed from local storage on logout. | +| Info drawer | Tag styling is applied to tags shown in the info drawer. | +| Saved searches | Long saved-search descriptions are truncated. | diff --git a/docs/upgrade-guide/upgrade530-600.md b/docs/upgrade-guide/upgrade530-600.md new file mode 100644 index 000000000..d4fc16e38 --- /dev/null +++ b/docs/upgrade-guide/upgrade530-600.md @@ -0,0 +1,142 @@ +--- +Title: Upgrading from ACA v5.3 to v6.0 +--- + +# Upgrading from ACA v5.3 to v6.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.3.0 project to +v6.0.0. + +**This is a major release.** The headline changes are **Angular 16 → 17**, **Node 18 → 20**, and ADF / +`@alfresco/js-api` reaching their **final `7.0.0` / `8.0.0`** releases (from `7.0.0-alpha.7` / `8.0.0-alpha.7`). It +also moves **TypeScript 5.0 → 5.3**, **zone.js 0.13 → 0.14**, and **NgRx 16 → 17**. The relevant ADF change is the +**7.0.0 (final)** section — the Angular 17 step — of: + +- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0 (final)** section) + +Because of the Angular 17 / Material 17 move and the Node 20 bump, budget time to rebuild your toolchain, re-audit +Material styles and re-test. Read the [breaking changes](#breaking-changes) carefully. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your +application to **Angular 17 / TypeScript 5.3 / zone.js 0.14 / NgRx 17** in lockstep, and update your build/CI +environment to **Node 20** (`.nvmrc` is now `20.18.1`). + +## Contents + +- [Library updates](#library-updates) +- [Aligning with Angular 17 / ADF 7.0](#aligning-with-angular-17--adf-70) + - [Angular 17 migration](#angular-17-migration) + - [Node 20](#node-20) + - [ADF 7.0 final — what applies to ACA](#adf-70-final--what-applies-to-aca) +- [Breaking changes](#breaking-changes) + - [Platform lockstep](#platform-lockstep) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "7.0.0", + "@alfresco/adf-content-services": "7.0.0", + "@alfresco/adf-extensions": "7.0.0", + "@alfresco/js-api": "8.0.0", + "@angular/core": "17.1.3", + "@angular/material": "17.1.2", + "@ngrx/store": "17.0.1", + "typescript": "5.3.3", + "zone.js": "0.14.8" + } +} +``` + +The whole `@angular/*` toolchain moves to `17.1.x`, `@ngrx/*` to `17.0.1`, `@angular-eslint/*` to `17.x`, +`@typescript-eslint/*` `5 → 6.21.0`, `@nx/*` `17.0.2 → 17.3.2`, `ng-packagr` `16 → 17.1.2`, +`@mat-datetimepicker/core` `12 → 13`, `tslib` `→ 2.8.1`, and `@alfresco/adf-cli` / +`@alfresco/eslint-plugin-eslint-angular` to `7.0.0`. `rxjs` stays `7.8.1`. **Node moves 18 → 20.18.1** (`.nvmrc`). +Unlike ADF (which migrated its test runner to Jest in 7.0.0), **ACA keeps Karma/Jasmine**. Clean `node_modules` and +the lockfile, then reinstall. + +## Aligning with Angular 17 / ADF 7.0 + +See the **7.0.0 (final)** section of the ADF +[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) +for the underlying platform detail. + +### Angular 17 migration + +ACA was lifted to Angular 17 / Material 17 / NgRx 17 (ACS-6849). Run the Angular 17 update +(`ng update @angular/core@17 @angular/cli@17 @angular/material@17`) against your fork. **ACA did not adopt Angular +17's new built-in control-flow syntax** (the `@if` / `@for` blocks); templates still use the classic `ngIf` / `ngFor` structural directives, so you do not +need to run that migration to stay aligned. Re-audit any Material style overrides against Angular 17. + +### Node 20 + +The build now requires **Node 20** (`.nvmrc` `20.18.1`, MNT-24892). Update your local toolchain, Docker base image +and CI runners to Node 20; Node 18 is no longer supported. + +### ADF 7.0 final — what applies to ACA + +Most of ADF 7.0.0's breaking removals are in areas ACA does not consume: + +- **`MomentDatePipe` / `MomentDateTimePipe` removed** — ACA does not use them (no change needed). +- The `FormModel` / `FullNamePipe` signature changes, the new form-validator injection tokens, the service-task + data-shape change and the Screens API are **process/forms-cloud** concerns and do not apply to ACA. + +What ACA does pick up from ADF 7.0.0: + +- **`DocumentListComponent` `displayDragAndDropHint` input** — ACA binds this to hide the drag-and-drop upload hint + when files cannot be uploaded to the current location (see [New components and features](#new-components-and-features)). +- **`SavedSearchesPreferencesApiService` / `SAVED_SEARCHES_SERVICE_PREFERENCES`** — ADF 7.0.0 made Saved Searches + persist through the Preferences API, which ACA now adopts (see below). + +## Breaking changes + +### Platform lockstep + +You must move your application to **Angular 17, TypeScript 5.3, zone.js 0.14 and NgRx 17** together with ACA, and +run it on **Node 20**. This is the dominant breaking change; there are no ACA source-API removals in this release. + +### Library public API + +The published ACA libraries are **additive only** — no exports were removed or renamed (only the copyright header +year changed across the barrels). `@alfresco/aca-content` gains two new exports: + +- **`ContentManagementService`** — the content-management service is now part of the public API (previously + internal), so extensions can call it directly. +- **`ExternalNodePermissionCommentsTabService`** — a new **abstract** service (`canAddComments(node): boolean`) + intended as a DI override point, letting a downstream app decide whether comments can be added for a node (e.g. + on retained / record documents). + +## New components and features + +- **Saved Searches persisted via the Preferences API** (ACS-9166) — Saved Searches now persist through the + Alfresco Preferences API (adopting ADF 7.0.0's `SavedSearchesPreferencesApiService`) instead of the config file. + (This migration was first attempted in the 5.3.0 cycle and reverted; it lands in 6.0.0.) +- **Comments extension point** — the new `ExternalNodePermissionCommentsTabService` lets an app control comment + availability; ACA uses it so comment creation is available on documents that have been retained / declared as + records (ACS-9083). +- **Drag-and-drop hint gating** (ACS-8782) — the drag-and-drop upload hint is hidden when files cannot be uploaded + to the current location (e.g. frozen files under a hold); this is what surfaced `ContentManagementService` as a + public export. +- **Accessibility** — the notification and user menus are now keyboard-accessible (ACS-9266), plus a wave of a11y + fixes across the sidebar, search page, breadcrumbs and Create Rule dialog (colour-contrast thresholds, supported + ARIA attributes, and discernible button text — ACS-9225 / 9228 / 9229 / 9235 / 9236). + +## Behavioural changes + +| Area | Change | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Node Details page | The *View Details* button was removed from the node Details page (ACS-9158). | +| Extensions | Extension visibility rules are used in **array** form in `app.extensions.json`; single-element arrays no longer log errors (ACS-9346 / ACS-9369). | +| Records mgmt | The permission error message shown when opening a records-management library was changed (ACS-9344). | +| Saved searches | The Saved Search navbar title is now translated (ACS-9119). | +| Login | The license displayed on the login page is updated from SSO (ACS-9213). | +| Search input | Search-input focus styles were fixed (ACA-4735). | +| Documentation | Product documentation links moved from `docs.alfresco.com` to `support.hyland.com` (ACS-9371); update any hardcoded doc links in a fork. | diff --git a/docs/upgrade-guide/upgrade600-701.md b/docs/upgrade-guide/upgrade600-701.md new file mode 100644 index 000000000..7b19944d3 --- /dev/null +++ b/docs/upgrade-guide/upgrade600-701.md @@ -0,0 +1,195 @@ +--- +Title: Upgrading from ACA v6.0 to v7.0.1 +--- + +# Upgrading from ACA v6.0 to v7.0.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v6.0.0 project to +v7.0.1 (covering the 7.0.0 and 7.0.1 releases). + +**This is the largest release in the series.** It moves **Angular 17 → 19** (via an internal 18 step), converts +ACA into a **standalone-bootstrapped application** (the root `AppModule` is gone), and takes ADF / +`@alfresco/js-api` to **8.0.0 / 9.0.0**. Alongside that it upgrades **`@ngx-translate/core` 14 → 16**, **pdf.js +3 → 5**, **NgRx 17 → 19**, **TypeScript 5.3 → 5.8**, **zone.js 0.14 → 0.15**, **Nx 17 → 21**, and **Node 20 → 22**. +It also adds a markdown/diagram rendering stack (`ngx-markdown`, `mermaid`, `katex`, `prismjs`) for Knowledge +Retrieval. The corresponding ADF guide is: + +- [ADF — Upgrading from v7.0 to v8.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md) + +Budget substantial time: you must migrate to Angular 19, adopt the standalone bootstrap, migrate your i18n setup, +re-audit your theme against ADF's theming clean-up, and move your PDF viewer worker asset. Read the +[breaking changes](#breaking-changes) carefully. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your +application to **Angular 19 / TypeScript 5.8 / zone.js 0.15 / NgRx 19** in lockstep, update your build/CI +environment to **Node 22** (`.nvmrc` is now `22.14.0`), and plan for the **standalone bootstrap** and **theming** +migrations below. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with Angular 19 / ADF 8.0](#aligning-with-angular-19--adf-80) + - [Angular 19 migration](#angular-19-migration) + - [Standalone application bootstrap](#standalone-application-bootstrap) + - [Internationalisation — ngx-translate 16](#internationalisation--ngx-translate-16) + - [Theming clean-up](#theming-clean-up) + - [PDF viewer — pdf.js 5](#pdf-viewer--pdfjs-5) + - [Node 22](#node-22) +- [Breaking changes](#breaking-changes) + - [Platform lockstep](#platform-lockstep) + - [Standalone bootstrap and extension registration](#standalone-bootstrap-and-extension-registration) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.0.1", + "@alfresco/adf-content-services": "8.0.1", + "@alfresco/adf-extensions": "8.0.1", + "@alfresco/js-api": "9.0.1", + "@angular/core": "19.2.6", + "@angular/material": "19.2.9", + "@ngrx/store": "19.2.1", + "@ngrx/operators": "19.2.1", + "@ngx-translate/core": "^16.0.4", + "pdfjs-dist": "^5.1.91", + "typescript": "5.8.2", + "zone.js": "0.15.0" + } +} +``` + +The whole `@angular/*` toolchain moves to `19.2.x`, `@ngrx/*` to `19.2.1` (with the new **`@ngrx/operators`** +package), `@angular-eslint/*` to `19.3.0`, `@typescript-eslint/*` `6 → 7/8`, `@nx/*` and `nx` `17 → 20/21`, +`ng-packagr` `17 → 19`, `@mat-datetimepicker/core` `13 → 15`, `prettier` `2 → 3.5`, and `@alfresco/adf-cli` / +`@alfresco/eslint-plugin-eslint-angular` to `8.0.1`. New runtime dependencies **`ngx-markdown` `19.1.1`, +`mermaid`, `katex` and `prismjs`** are added for Knowledge Retrieval. `rxjs` moves `7.8.1 → 7.8.2`. **Node moves +20 → 22.14.0** (`.nvmrc`). ACA still uses **Karma/Jasmine**. Clean `node_modules` and the lockfile, then reinstall. + +> The **7.0.1** patch bumps ADF `8.0.0 → 8.0.1` and `@alfresco/js-api` `9.0.0 → 9.0.1`, fixes an SSO login +> regression (see [Standalone application bootstrap](#standalone-application-bootstrap)), and pulls in a +> `form-data` security bump. There are no other functional changes between 7.0.0 and 7.0.1. + +## Aligning with Angular 19 / ADF 8.0 + +See the ADF [7.0 → 8.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md) +for the underlying platform detail — the sections below map ACA's work onto it. + +### Angular 19 migration + +ACA was lifted through **Angular 18** (#4448) and then **Angular 19** (#4520). Run the Angular update schematics +in the same order (`ng update @angular/core@18 @angular/cli@18 …` then `@19`), and re-audit Material style overrides +against Angular 19's Material. + +### Standalone application bootstrap + +ACA is now a **standalone-bootstrapped application** (AAE-36484 / AAE-36580): the root `AppModule` was removed and +`app/src/main.ts` calls `bootstrapApplication(AppComponent, AppConfig)`, where `AppConfig` is an +`ApplicationConfig` of providers. If your fork maintains its own root module or `main.ts`, migrate to the +standalone bootstrap and register providers (including ACA's, via `provideExtensions()` — see +[Standalone bootstrap and extension registration](#standalone-bootstrap-and-extension-registration)). + +> **Provider ordering (SSO):** with the standalone bootstrap, the order of providers in `AppConfig` matters. A +> login regression fixed in **7.0.1** (ACS-9934) was caused by `provideTranslations('app', 'assets')` being +> registered before the auth module; the fix moves `importProvidersFrom(AuthModule.forRoot({ useHash: true }))` +> **ahead of** `provideTranslations(...)`. If SSO login fails after your standalone migration, check that the auth +> providers are registered before the translation providers. + +### Internationalisation — ngx-translate 16 + +`@ngx-translate/core` moved `14 → 16`, whose provider API changed. Follow ADF's +[i18n section](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#internationalisation-i18n) +and register translations through the new provider functions in your standalone `ApplicationConfig` rather than the +old `TranslateModule.forRoot()` NgModule import. + +### Theming clean-up + +ADF 8.0 removed its prebuilt themes and colour/variable SCSS partials. In step with this, ACA **broke its +dependency on ADF Material selectors** (AAE-34494) and **added the missing palette colour variables** locally +(#4535). If your fork `@import`s ADF theme partials or styles ADF components through `.mat-*` selectors, re-audit +your SCSS against ADF's [theming clean-up](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#theming-clean-up). + +### PDF viewer — pdf.js 5 + +`pdfjs-dist` moved `3.x → 5.x`. If your fork bundles or overrides the PDF worker asset, update it to the pdf.js 5 +worker per ADF's [PDF viewer section](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#pdf-viewer-pdfjs-5). + +### Node 22 + +The build now requires **Node 22** (`.nvmrc` `22.14.0`). Update your local toolchain, Docker base image and CI +runners; Node 20 is no longer supported. + +## Breaking changes + +### Platform lockstep + +You must move your application to **Angular 19, TypeScript 5.8, zone.js 0.15 and NgRx 19** (adding the new +`@ngrx/operators` package) together with ACA, and run it on **Node 22**. This — together with the standalone +bootstrap below — is the dominant breaking change. + +### Standalone bootstrap and extension registration + +Because the root `AppModule` was removed, ACA's extensions are no longer registered by importing an NgModule. +`@alfresco/aca-content` now exports a **`provideExtensions()`** function (built on Angular 19's +`provideAppInitializer` / `inject`) that returns the providers to add to your standalone `ApplicationConfig`: + +```ts +import { provideExtensions } from '@alfresco/aca-content'; + +export const AppConfig: ApplicationConfig = { + providers: [ + // … + provideExtensions() + ] +}; +``` + +If your fork registered ACA via an NgModule import, switch to `provideExtensions()` in your bootstrap providers. + +### Library public API + +The published ACA libraries **removed** the following exports: + +- **`@alfresco/aca-shared`** — the deprecated **`shared.module`** and **`shared-toolbar.module`** NgModules were + removed. Import the standalone components/directives you need directly instead of these modules. +- **`@alfresco/aca-shared/store`** — the **`snackbar.actions`** and **`snackbar.effects`** were removed. Snackbar + handling now goes through ADF's `NotificationService` (this completes the migration started in earlier releases); + if you dispatched ACA snackbar actions, call the ADF service instead. + +Additive: + +- **`@alfresco/aca-content`** — new **`provideExtensions()`** export (see above). + +## New components and features + +- **Markdown rendering in Knowledge Retrieval** — AI responses now render **Markdown** (ACS-9427) via + `ngx-markdown`, including code highlighting (`prismjs`), diagrams (`mermaid`) and math (`katex`). Links embedded in + a response open in a **separate browser tab** (ACS-9535), and the repeated-question behaviour was fixed + (ACS-9546). +- **Folder Information enhancements** — the folder-information dialog now shows the **number of files** (ACS-9249) + and no longer displays an error while the API response is `IN_PROGRESS` (ACS-9466). +- **Favorite action notifications** (ACS-9398) — adding/removing favorites now shows snackbar notifications. +- **Folder-rule script name** (MNT-25175) — the folder-rule display now shows the script name. + +## Behavioural changes + +| Area | Change | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Viewer | The print button is now hidden / disabled for media files (ACS-9388). | +| Login | The login screen uses a white background and forces a light colour scheme (ACS-9670). | +| Permissions | The user is redirected away from the permissions page after the node is deleted (ACS-9554). | +| About page | Tasks and processes are displayed correctly when the About page is refreshed (ACS-9510). | +| Search | Property fields are now included in search header calls (MNT-24848). | +| Libraries | Library-permission warnings now use the notification service (with yellow warning styling) instead of the store (ACS-8746). | +| Folder rules | An invalid rule definition shows a correct error message (ACS-5503); the edit-rule dialog uses the correct title/button text (ACS-9386). | +| Legal hold | Legal-hold capabilities are verified correctly (MNT-24923). | +| Accessibility | Focus is restored after a dialog is closed (ACS-9702). | +| Metadata sidebar | Several metadata-sidebar issues were fixed (ACS-9789). | diff --git a/docs/upgrade-guide/upgrade701-710.md b/docs/upgrade-guide/upgrade701-710.md new file mode 100644 index 000000000..9a0ca7743 --- /dev/null +++ b/docs/upgrade-guide/upgrade701-710.md @@ -0,0 +1,119 @@ +--- +Title: Upgrading from ACA v7.0.1 to v7.1.0 +--- + +# Upgrading from ACA v7.0.1 to v7.1.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.0.1 project to +v7.1.0. + +This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.0.1 → 8.1.1** and `@alfresco/js-api` +9.0.1 → 9.1.1. Angular (19.2), Material, TypeScript (5.8), zone.js, NgRx (19.2) and Node (`.nvmrc` 22.14.0) are all +**unchanged** version-wise. The main consumer-facing work is a **provider-API migration** for extension +registration (finishing the standalone move started in 7.0.0) and an **NgRx API modernisation**. The corresponding +ADF guide is: + +- [ADF — Upgrading from v8.0 to v8.1.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade80-811.md) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 / +TypeScript 5.8 platform and Node 22 (`.nvmrc`) are unchanged from 7.0.1. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 8.1](#aligning-with-adf-81) +- [Breaking changes](#breaking-changes) + - [Extension registration moved to the provider API](#extension-registration-moved-to-the-provider-api) + - [NgRx API modernisation](#ngrx-api-modernisation) + - [Build dependencies](#build-dependencies) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.1.1", + "@alfresco/adf-content-services": "8.1.1", + "@alfresco/adf-extensions": "8.1.1", + "@alfresco/js-api": "9.1.1", + "date-fns": "^4.1.0" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.1.1` too. `date-fns` moves +`2.30.0 → 4.1.0` (a major bump — in ACA it is only used by the `@alfresco/aca-playwright-shared` test utilities), +`mermaid` `11.8 → 11.10`, and `nx` / `@nx/*` `21.2 → 21.3`. Angular (`19.2.6`), `@angular/material` (`19.2.9`), +TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node (`.nvmrc` `22.14.0`) are unchanged. Clean +`node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 8.1 + +See the ADF [8.0 → 8.1.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade80-811.md) +for the underlying library changes. ACA simply consumes ADF `8.1.1` / js-api `9.1.1`; there is no ADF-driven +source migration required in ACA beyond adopting the versions. + +## Breaking changes + +### Extension registration moved to the provider API + +ACA completed its move to Angular's provider API for extension registration (AAE-37293). The short-lived +`provideExtensions()` function that `@alfresco/aca-content` exported in 7.0.0 has been **removed**, along with the +`CoreExtensionsModule` (`core.extensions.module`) export. Extension registration now goes through: + +- **`provideContentAppExtensions()`** — a new function exported from **`@alfresco/aca-shared`**, and +- your own application-level extensions provider (in ACA, `provideApplicationExtensions()` from + `app/src/app/extensions.module.ts`). + +```ts +// Before (7.0.x) +import { provideExtensions } from '@alfresco/aca-content'; +// providers: [ …, provideExtensions() ] + +// After (7.1.0) +import { provideContentAppExtensions } from '@alfresco/aca-shared'; +// providers: [ …, provideContentAppExtensions(), provideApplicationExtensions() ] +``` + +Internally the content library now registers its components/guards through ADF's own +`provideExtensions` / `provideAppExtensions` (from `@alfresco/adf-extensions`). If your fork registered ACA +extensions via `provideExtensions()` from `@alfresco/aca-content` or imported `CoreExtensionsModule`, switch to +`provideContentAppExtensions()`. + +### NgRx API modernisation + +ACA's store was upgraded to the modern NgRx API (ACS-9911), including the effect and testing-module setup +(`app-testing.module` / `lib-testing-module` and the effects specs). If your fork extends ACA's effects or reuses +its testing modules, align them with the updated NgRx provider/testing API. + +### Build dependencies + +- **`@angular/cli` and `@schematics/angular` were removed** from `devDependencies` (AAE-37689) — the workspace + builds through Nx executors, not the Angular CLI. If your fork invokes `ng` directly, add the CLI back to your + own `devDependencies` or switch to the Nx equivalents. +- **`date-fns` moved `2 → 4`** (major). ACA only uses it in the Playwright test utilities, but if your fork uses + `date-fns` directly, review the v3/v4 breaking changes. + +## New components and features + +- **`provideContentAppExtensions()`** (`@alfresco/aca-shared`) — the new provider-API entry point for registering + ACA's content extensions (see [Extension registration moved to the provider API](#extension-registration-moved-to-the-provider-api)). +- **`noWhitespaceValidator`** (`@alfresco/aca-shared`) — a new reusable Angular form `ValidatorFn` that rejects + whitespace-only input. +- **Current ACS version selector** (ACS-9907) — a new store selector in `@alfresco/aca-shared/store` exposes the + current ACS repository version. + +## Behavioural changes + +| Area | Change | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| Search | The search popup no longer flickers on Enter, and the infinite loading animation on the search results was fixed (ACS-9374 / ACS-9590). | +| Search | Search requests are no longer altered when the query uses quote marks (MNT-25070). | diff --git a/docs/upgrade-guide/upgrade710-720.md b/docs/upgrade-guide/upgrade710-720.md new file mode 100644 index 000000000..da92c872b --- /dev/null +++ b/docs/upgrade-guide/upgrade710-720.md @@ -0,0 +1,122 @@ +--- +Title: Upgrading from ACA v7.1.0 to v7.2.0 +--- + +# Upgrading from ACA v7.1.0 to v7.2.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.1.0 project to +v7.2.0. + +This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.1.1 → 8.2.1** and `@alfresco/js-api` +9.1.1 → 9.2.1. Angular (19.2), Material, TypeScript (5.8), zone.js, NgRx (19.2) and Node (`.nvmrc` 22.14.0) are +**unchanged**. Despite being a minor bump, it carries a few consumer-facing items: an **OAuth config change**, +**ADF removed from the libraries' peer dependencies**, the continuation of the **ADF → ACA theming decoupling**, +new **All Libraries** and **custom user-profile-section** capabilities, and a large **accessibility** pass. The +corresponding ADF guide is: + +- [ADF — Upgrading from v8.1.1 to v8.2.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade811-821.md) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 / +TypeScript 5.8 platform and Node 22 (`.nvmrc`) are unchanged from 7.1.0. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 8.2](#aligning-with-adf-82) +- [Breaking changes](#breaking-changes) + - [OAuth configuration — secret field removed](#oauth-configuration--secret-field-removed) + - [ADF removed from library peer dependencies](#adf-removed-from-library-peer-dependencies) + - [Theme variables moved from ADF to ACA](#theme-variables-moved-from-adf-to-aca) + - [Deprecated API and module cleanup](#deprecated-api-and-module-cleanup) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.2.1", + "@alfresco/adf-content-services": "8.2.1", + "@alfresco/adf-extensions": "8.2.1", + "@alfresco/js-api": "9.2.1" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.2.1` too. Dev tooling advances +(`nx` / `@nx/*` `21.3 → 21.5`, `@playwright/test` `1.53 → 1.56`, `jasmine-core` `4.6 → 5.12`, `dotenv` `16 → 17`), +a `webpack-bundle-analyzer` devDependency and several `ci:*` npm scripts were added. Angular (`19.2.6`), +`@angular/material` (`19.2.9`), TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node +(`.nvmrc` `22.14.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 8.2 + +See the ADF [8.1.1 → 8.2.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade811-821.md) +for the underlying library changes. Beyond adopting ADF `8.2.1` / js-api `9.2.1`, the ADF-driven work in ACA is the +**theming decoupling** below — ACA now owns the theme variables it previously inherited from ADF. + +## Breaking changes + +### OAuth configuration — secret field removed + +The empty **`secret`** field was removed from the OAuth2 block of `app.config.json` across ADF / ACA / ADW +(ACS-10592). Remove `oauth2.secret` from any custom `app.config.json`. + +### ADF removed from library peer dependencies + +`@alfresco/adf-*` was **removed from the `peerDependencies`** of ACA's published libraries (`@alfresco/aca-shared`, +`@alfresco/aca-content`) — AAE-37857. Consuming projects are now responsible for declaring and aligning their own +ADF versions; ACA no longer pins them for you. + +### Theme variables moved from ADF to ACA + +Continuing the theming decoupling, ACA now defines locally the theme variables it previously inherited from ADF +(ACS-10448 added `projects/aca-content/src/lib/ui/overrides/adf-variables.scss`). If your fork relied on ADF theme +variables being provided transitively through ACA, re-audit your SCSS against the new ACA-owned variables. + +### Deprecated API and module cleanup + +ACA removed deprecated methods from its auth-related components (ACS-9768) and replaced other deprecated APIs and +modules (ACS-9859). If your fork subclasses those components or calls the removed methods, migrate to the current +equivalents. + +### Library public API + +The published API is otherwise **additive** — `@alfresco/aca-content` gains an **`isFeatureSupportedInCurrentAcs`** +pipe, and `@alfresco/aca-shared` gains a **`UserProfileSection`** type (with +`AppExtensionService.getUserProfileSections()`) and an **`isSSOEnabled`** rule (`@alfresco/aca-shared/rules`). No +exports were removed or renamed. + +## New components and features + +- **All Libraries page** (ACS-10165) — the libraries screens were refactored onto a shared `libraries-base` + component with a new reusable `library-list` component, and a new *all libraries* route was added. +- **Custom user-profile sections** (ACS-9980) — you can now contribute custom sections to the user-profile page + via a new `userProfileSections` extension in `app.extensions.json`, surfaced through the new `UserProfileSection` + type and `AppExtensionService.getUserProfileSections()`. +- **Feature gating by ACS version** — a new `isFeatureSupportedInCurrentAcs` pipe (with folder-information and + bulk-update evaluators, ACS-10036 / ACS-10038) resolves whether a feature is supported by the connected ACS + repository version. +- **Saved-searches backward compatibility** — ACA now also supports the legacy `config.json`-based saved-searches + approach alongside the Preferences API (ACS-10421), and ADW/ACA gracefully handle repositories below ACS 25.x + that do not support the preferences `PUT` method (ACS-10035). + +## Behavioural changes + +| Area | Change | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Search | The search results page now renders the Description / Title fields as **plain text** instead of interpreting embedded HTML (ACS-10116). | +| Search | The search input no longer clears when using a special search such as `text:value` (ACS-10076); filters clear correctly when the input is empty (MNT-25411). | +| Search | Filtering now behaves correctly in files and sites (ACS-10083), and switching between saved searches works correctly (MNT-25409). | +| Viewer | The version preview can now be changed from within the preview window (MNT-25285). | +| Libraries | Permission-checking logic in library navigation was fixed (ACS-10409). | +| Navigation | The *Go to personal files* button on the profile page now navigates correctly (ACS-10214); doubled menu-collapsing was removed (MNT-25423). | +| Accessibility | A large screen-reader / keyboard pass landed — context-menu keyboard navigation, rule-set header labels, profile-page field labels and error messages, and search clear / save-search dialog icons among others (ACS-10198 / 10238 / 10253 / 10285 / 10286 / 10290 / 10295 / 10297 / 10303). | diff --git a/docs/upgrade-guide/upgrade720-730.md b/docs/upgrade-guide/upgrade720-730.md new file mode 100644 index 000000000..8f1adce81 --- /dev/null +++ b/docs/upgrade-guide/upgrade720-730.md @@ -0,0 +1,110 @@ +--- +Title: Upgrading from ACA v7.2.0 to v7.3.0 +--- + +# Upgrading from ACA v7.2.0 to v7.3.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.2.0 project to +v7.3.0. + +This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.2.1 → 8.3.1** and `@alfresco/js-api` +9.2.1 → 9.3.1, and bumps **Node 22 → 24** (`.nvmrc` `24.13.0`). Angular stays on the 19.2 line (a patch bump from +`19.2.6` to `19.2.19`), and TypeScript, zone.js and NgRx are unchanged. The bulk of the release is a **large +accessibility pass**, plus the `adf-toolbar → mat-toolbar` migration, a generalised node **Information dialog**, and +search-query hardening. The corresponding ADF guide is: + +- [ADF — Upgrading from v8.2.1 to v8.3.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade821-831.md) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Update your +build/CI environment to **Node 24** (`.nvmrc` is now `24.13.0`); the Angular 19 / TypeScript 5.8 platform is +otherwise unchanged from 7.2.0. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 8.3](#aligning-with-adf-83) +- [Breaking changes](#breaking-changes) + - [Node 24](#node-24) + - [adf-toolbar replaced with mat-toolbar](#adf-toolbar-replaced-with-mat-toolbar) + - [Build — native Node env loader](#build--native-node-env-loader) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.3.1", + "@alfresco/adf-content-services": "8.3.1", + "@alfresco/adf-extensions": "8.3.1", + "@alfresco/js-api": "9.3.1", + "@angular/core": "19.2.19" + } +} +``` + +The whole `@angular/*` toolchain moves to the `19.2.19` patch, `@alfresco/adf-cli` / +`@alfresco/eslint-plugin-eslint-angular` to `8.3.1`, and dev tooling advances (`@nx/*` `21 → 22`, `jasmine-core` +`5 → 6`, `@types/node` `18 → 25`, `eslint-plugin-playwright` `1 → 2`, `mermaid` `11.10 → 11.12`). **Node moves +22 → 24.13.0** (`.nvmrc`). `@ngx-translate/core` stays `^16.0.4` (see the note below), and TypeScript (`5.8.2`), +`@ngrx/*` (`19.2.1`) and zone.js (`0.15.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +> **Non-change (informational):** an `@ngx-translate/core` upgrade was attempted and **reverted** before 7.3.0 +> (ACS-11213), so ngx-translate stays at `^16.0.4`. No action is needed — this is only noted in case you diff the +> intermediate commits. + +## Aligning with ADF 8.3 + +See the ADF [8.2.1 → 8.3.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade821-831.md) +for the underlying library changes. ACA consumes ADF `8.3.1` / js-api `9.3.1`; the only notable source adaptation +is a refactor of `getChild` usage (ACS-11051) to match the js-api. If your fork calls the same js-api node methods, +review them against js-api 9.3. + +## Breaking changes + +### Node 24 + +The build now requires **Node 24** (`.nvmrc` `24.13.0`). Update your local toolchain, Docker base image and CI +runners; Node 22 is no longer the target. + +### adf-toolbar replaced with mat-toolbar + +ACA replaced ADF's `` with Angular Material's `` (ACS-10934, e.g. in the Manage Rules +screens). If your fork styles the `.adf-toolbar` / `.adf-toolbar--inline` DOM or depends on the ADF toolbar +component's markup, re-audit those styles against the Material toolbar. + +### Build — native Node env loader + +The build switched to Node 24's **native `.env` loader**, and `dotenv-expand` was removed as a dependency +(#4970). If your fork's scripts relied on `dotenv-expand`, move to the native `--env-file` mechanism. + +### Library public API + +The published API is **additive** — `@alfresco/aca-shared` gains a **`noLeadingTrailingOperatorsValidator`** form +validator (used to reject search queries with leading/trailing operators). No exports were removed or renamed. + +## New components and features + +- **Node Information dialog** (MNT-25478) — the earlier folder-information dialog was generalised into a node + **Information dialog**, adding a new `location-link` component and a dialog for additional location references + (for nodes that appear in more than one location). +- **Search-query validation** — a new `noLeadingTrailingOperatorsValidator` (ACS-10514) rejects queries with + leading/trailing operators, and top-level filter management was added to the search filters (ACS-10083). + +## Behavioural changes + +| Area | Change | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Accessibility | A large screen-reader / keyboard / contrast pass landed — sidenav and snackbar now announce state, Esc no longer loses keyboard focus, headings and dropdown labels were corrected, folder-rules and bulk-actions controls were made SR-friendly, favourite add/remove is announced, and colour-contrast was improved in several places (ACS-10200 / 10201 / 10204 / 10217 / 10219 / 10226 / 10233 / 10283 / 10287 / 10293 / 10294 / 10307 / 10323 / 10885 / 10886 among others). | +| Search | Leading and trailing operators in a query are now handled correctly (ACS-10514); the *Save Changes* button no longer becomes disabled after modifying the search or filter (ACS-10730); the loader is no longer shown for a nullish query (MNT-25408). | +| Sorting | Sorting configured via the sorting key is now saved correctly in local storage (MNT-25276). | +| Knowledge Retrieval | The answer page now displays the response instead of a general error, with a workaround for the AI answer references id mapping (ACS-11033). | +| Security | Fixed an Angular i18n CSS vulnerability (PRODSEC-11289). | diff --git a/docs/upgrade-guide/upgrade730-741.md b/docs/upgrade-guide/upgrade730-741.md new file mode 100644 index 000000000..3d9b6fd3f --- /dev/null +++ b/docs/upgrade-guide/upgrade730-741.md @@ -0,0 +1,119 @@ +--- +Title: Upgrading from ACA v7.3.0 to v7.4.1 +--- + +# Upgrading from ACA v7.3.0 to v7.4.1 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.3.0 project to +v7.4.1 (there was no 7.4.0 release). + +This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.3.1 → 8.4.1** and `@alfresco/js-api` +9.3.1 → 9.4.1. Angular stays on the 19.2 line (patch `19.2.19` to `19.2.20`), and Node (`.nvmrc` 24.13.0), +TypeScript, zone.js and NgRx are unchanged. The notable items are the **`@ngx-translate/core` 16 → 17** major bump +(which was attempted and reverted in 7.3.0, and now lands), a **front-end rebrand**, a new **repository view**, and +a **search UX rework** that removed two recently-added form validators. The corresponding ADF guide is: + +- [ADF — Upgrading from v8.3.1 to v8.4.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade831-841.md) + +Read the [breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 / +TypeScript 5.8 platform and Node 24 (`.nvmrc`) are unchanged from 7.3.0. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 8.4](#aligning-with-adf-84) + - [ngx-translate 17](#ngx-translate-17) + - [js-api LazyApi decorator](#js-api-lazyapi-decorator) + - [Library peer dependencies](#library-peer-dependencies) +- [Breaking changes](#breaking-changes) + - [Removed search validators](#removed-search-validators) + - [prefer-inject lint rule](#prefer-inject-lint-rule) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.4.1", + "@alfresco/adf-content-services": "8.4.1", + "@alfresco/adf-extensions": "8.4.1", + "@alfresco/js-api": "9.4.1", + "@ngx-translate/core": "^17.0.0", + "@angular/core": "19.2.20" + } +} +``` + +The whole `@angular/*` toolchain moves to the `19.2.20` patch, `@alfresco/adf-cli` / +`@alfresco/eslint-plugin-eslint-angular` to `8.4.1`, `@angular-eslint/*` `19.3 → 19.8.1`, `@nx/*` / `nx` +`21/22 → 22.5.4`, and `prettier` `3.5 → 3.8`. `pdfjs-dist` is now pinned exactly (`5.1.91`). **`@ngx-translate/core` +moves `16 → 17`** (a major — see below). TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node +(`.nvmrc` `24.13.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 8.4 + +See the ADF [8.3.1 → 8.4.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade831-841.md) +for the underlying library changes. + +### ngx-translate 17 + +`@ngx-translate/core` moved `16 → 17`. This is the upgrade that was reverted in 7.3.0 and now lands together with +ADF 8.4. If your fork registers translation providers or a custom `TranslateLoader`, align them with the +ngx-translate 17 API. A related fix ensures the app no longer reverts components to English after switching the +language and reloading (ACS-10732). + +### js-api LazyApi decorator + +ACA adopted js-api's new **`LazyApi`** decorator (ACS-11205) and added the `declare` keyword to affected class +fields (with a matching `tsconfig` adjustment) to prevent field shadowing under `useDefineForClassFields`. If your +fork extends the same js-api-backed services, apply the same pattern. + +### Library peer dependencies + +The published libraries' `peerDependencies` for Angular and NgRx were updated to **v19.2** (#5151). Align your +consuming project's Angular / NgRx versions accordingly. + +## Breaking changes + +### Removed search validators + +As part of the search UX rework (ACS-10475), the two form validators added in the previous releases were +**removed** from `@alfresco/aca-shared` (their files were deleted): + +- `noWhitespaceValidator` +- `noLeadingTrailingOperatorsValidator` + +If your fork imported either validator from `@alfresco/aca-shared`, inline the check or provide your own +`ValidatorFn`; the search input now handles this internally. + +### prefer-inject lint rule + +The `@angular-eslint` **`prefer-inject`** rule was enabled by default (ACS-11417), in line with the Angular 20 +direction. This is a lint-level change that may produce warnings/errors in a fork that still uses constructor +injection; migrate to `inject()` or adjust your lint config. + +## New components and features + +- **Repository view** (MNT-25615) — a new `repository-view` component and route that surface the repository + (Company Home) root as a browsable location. +- **Search UX improvements** (ACS-10475) — a set of front-end search UX refinements (including the internalised + input validation that replaced the removed validators above). + +## Behavioural changes + +| Area | Change | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Branding | The application was rebranded — the Alfresco logo and favicon were updated (ACS-11271). | +| Localisation | Switching the language and reloading no longer reverts components back to English (ACS-10732). | +| Records | The *Edit Offline* option is hidden when a node is checked out (MNT-25584). | +| Node info | The Information button display was fixed (MNT-25478 follow-up). | +| Accessibility | The search page is now readable at 320px width (ACS-10258), and the Saved Search dialog manages focus correctly on open and return to trigger on close (ACS-10273). | +| Libraries | Library-properties handling was cleaned up (ACS-10621). | diff --git a/docs/upgrade-guide/upgrade741-750.md b/docs/upgrade-guide/upgrade741-750.md new file mode 100644 index 000000000..440f7c87e --- /dev/null +++ b/docs/upgrade-guide/upgrade741-750.md @@ -0,0 +1,107 @@ +--- +Title: Upgrading from ACA v7.4.1 to v7.5.0 +--- + +# Upgrading from ACA v7.4.1 to v7.5.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.4.1 project to +v7.5.0. + +This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.4.1 → 8.5.0** and `@alfresco/js-api` +9.4.1 → 9.5.0. Angular (19.2), Node (`.nvmrc` 24.13.0), TypeScript, zone.js and NgRx are all **unchanged**. The +headline is the **Material Design 3 (MD3) migration** — the biggest source of visual change in this release — plus +a new **Link document** capability and multivalued-property support in folder rules. The corresponding ADF guide +is: + +- [ADF — Upgrading from v8.4.1 to v8.5.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade841-850.md) + +Because of the MD3 migration, budget time to re-audit any custom theme or Material style overrides. Read the +[breaking changes](#breaking-changes). + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 / +TypeScript 5.8 platform and Node 24 (`.nvmrc`) are unchanged from 7.4.1. Budget time to re-theme (MD3) and re-test. + +## Contents + +- [Library updates](#library-updates) +- [Aligning with ADF 8.5](#aligning-with-adf-85) +- [Breaking changes](#breaking-changes) + - [Material Design 3 (MD3) migration](#material-design-3-md3-migration) + - [minimatch-browser dependency removed](#minimatch-browser-dependency-removed) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "8.5.0", + "@alfresco/adf-content-services": "8.5.0", + "@alfresco/adf-extensions": "8.5.0", + "@alfresco/js-api": "9.5.0" + } +} +``` + +`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.5.0` too, and `mermaid` moves +`11.12 → 11.15`. The **`minimatch-browser`** runtime dependency was removed. Angular (`19.2.20`), +`@angular/material` (`19.2`), TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node +(`.nvmrc` `24.13.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with ADF 8.5 + +See the ADF [8.4.1 → 8.5.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade841-850.md) +for the underlying library changes. Beyond adopting ADF `8.5.0` / js-api `9.5.0`, the ADF-aligned work in ACA is +the Material Design 3 theming migration below. + +## Breaking changes + +### Material Design 3 (MD3) migration + +ACA (and ADW / ACC) migrated their theming to **Angular Material 3 (MD3)** — ACS-10449. This reworked the theme +across roughly 70 files: `theme.scss`, `custom-theme.scss`, `variables.scss`, the ADF override partials +(`adf-style-fixes.theme.scss`, `adf-variables.scss`, `adf-pagination.theme.scss`, …), new `mixins.scss` / +`mat-selectors.scss`, and many component SCSS files. MD3 changes Material's design tokens, component styling and +CSS custom properties. + +**If your fork defines a custom theme or overrides Material component styles, you must re-audit them against MD3.** +This is the largest source of visual breakage in this upgrade. + +### minimatch-browser dependency removed + +The `minimatch-browser` runtime dependency was removed from `package.json`. If your fork imported it transitively +through ACA, add it to your own dependencies. + +### Library public API + +The published API is **additive** — `@alfresco/aca-content` now exports the **`NodeActionsService`** (ACS-9765), +which also gained *copy/move/link* support (see [New components and features](#new-components-and-features)). No +exports were removed or renamed. + +> **Non-change (informational):** a change to how sharable links handle redirects to the login page (ACS-11861) +> was merged and then **reverted** before 7.5.0, so that behaviour is unchanged. No action is needed — this is only +> noted in case you diff the intermediate commits. + +## New components and features + +- **Link document** (MNT-25522) — you can now create a **link** to a document in another location. This adds a new + node store action and extends the now-public `NodeActionsService`; linked nodes display `N/A` for size and number + of files in the Information dialog. +- **`NodeActionsService`** (`@alfresco/aca-content`) — the copy / move / link service is now part of the public API + (`copyNodes()`, `moveNodes()`, and the new link action), so extensions can drive those actions directly. +- **Folder rules — multivalued properties** (MNT-25149 / MNT-25558) — folder-rule property conditions and actions + now support multivalued properties. + +## Behavioural changes + +| Area | Change | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Accessibility | Focus is handled correctly after collapsing the sidenav menu (ACS-11350), and the info-drawer tabs show a proper focus indicator during keyboard navigation (ACS-11980). | +| Styling | General style updates accompanied the MD3 migration (ACS-11158). | +| Info dialog | Links display `N/A` for size and number of files (MNT-25522). | diff --git a/docs/upgrade-guide/upgrade750-800.md b/docs/upgrade-guide/upgrade750-800.md new file mode 100644 index 000000000..fee6df39e --- /dev/null +++ b/docs/upgrade-guide/upgrade750-800.md @@ -0,0 +1,124 @@ +--- +Title: Upgrading from ACA v7.5.0 to v8.0.0 +--- + +# Upgrading from ACA v7.5.0 to v8.0.0 + +This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.5.0 project to +v8.0.0. + +**This is a major release.** It moves ACA from **Angular 19 to 20**, takes ADF / `@alfresco/js-api` to their new +majors **9.0.0 / 10.0.0**, and upgrades **NgRx 19 → 20** and **TypeScript 5.8 → 5.9**. The most significant +functional change is the **removal of the embedded Knowledge Retrieval (AI) feature**, which is replaced by a link +to an **external Knowledge Discovery application**. The corresponding ADF guide is: + +- [ADF — Upgrading from v8.5.0 to v9.0.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade850-900.md) + +Budget time to migrate to Angular 20 and re-test. Read the [breaking changes](#breaking-changes) carefully. + +## Before you begin + +Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your +application to **Angular 20 / TypeScript 5.9 / NgRx 20** in lockstep. Node is a patch bump +(`.nvmrc` `24.13.0` to `24.13.1`). + +## Contents + +- [Library updates](#library-updates) +- [Aligning with Angular 20 / ADF 9.0](#aligning-with-angular-20--adf-90) + - [Angular 20 migration](#angular-20-migration) +- [Breaking changes](#breaking-changes) + - [Platform lockstep](#platform-lockstep) + - [Embedded Knowledge Retrieval removed](#embedded-knowledge-retrieval-removed) + - [Library public API](#library-public-api) +- [New components and features](#new-components-and-features) +- [Behavioural changes](#behavioural-changes) + +## Library updates + +Update the `package.json` file with the latest library versions: + +```json +{ + "dependencies": { + "@alfresco/adf-core": "9.0.0", + "@alfresco/adf-content-services": "9.0.0", + "@alfresco/adf-extensions": "9.0.0", + "@alfresco/js-api": "10.0.0", + "@angular/core": "20.3.25", + "@angular/material": "20.2.14", + "@ngrx/store": "~20.1.0", + "typescript": "5.9.3" + } +} +``` + +The whole `@angular/*` toolchain moves to `20.x`, `@ngrx/*` to `~20.1.0`, `@angular-eslint/*` `19.8 → 20.7`, +`@typescript-eslint/*` `→ 8.55.0`, `@nx/*` / `nx` `22 → 23`, `ng-packagr` `19 → 20`, `stylelint` `15 → 16`, +`@mat-datetimepicker/core` `15 → 16`, and `@alfresco/adf-cli` / `@alfresco/eslint-plugin-eslint-angular` to `9.0.0`. +The **`katex`, `mermaid`, `ngx-markdown` and `prismjs`** dependencies were **removed** (they backed the removed +Knowledge Retrieval markdown rendering), and an `overrides` entry pins `node-fetch` for `@module-federation/sdk`. +**Node is a patch bump** (`.nvmrc` `24.13.0 → 24.13.1`). Clean `node_modules` and the lockfile, then reinstall. + +## Aligning with Angular 20 / ADF 9.0 + +See the ADF [8.5.0 → 9.0.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade850-900.md) +for the underlying platform detail. + +### Angular 20 migration + +ACA was lifted to Angular 20 (ACS-11306). Run the Angular 20 update +(`ng update @angular/core@20 @angular/cli@20 @angular/material@20`) against your fork. Two notable points: + +- **Built-in control flow adopted** — unlike the Angular 19 step, ACA now uses Angular's built-in control-flow + syntax (`@if` / `@for`) in its templates. If your fork extends ACA templates, expect the new syntax. +- **`inject()` DI** — the `@angular-eslint` `prefer-inject` rule (enabled in 7.4.1) is now the norm; constructor + injection has largely been converted to `inject()`. + +## Breaking changes + +### Platform lockstep + +You must move your application to **Angular 20, TypeScript 5.9 and NgRx 20** together with ACA. This is the +dominant breaking change. + +### Embedded Knowledge Retrieval removed + +The embedded **Knowledge Retrieval (AI)** feature was **removed** from ACA (ACS-12037). All of its components were +deleted — `agents-button`, `search-ai-input`, `search-ai-input-container`, `search-ai-results` and the +`search-ai-marked-options` helper — along with the markdown rendering stack (`katex` / `mermaid` / `ngx-markdown` / +`prismjs`). + +In its place, ACA now offers a **link to an external Knowledge Discovery application**: a new +`knowledge-discovery-sidenav` component navigates to the URL from the new **`knowledgeDiscoveryUrl`** app setting, +which can be provided at runtime (e.g. via a Docker env var, #5295). If your fork depended on the in-app AI answer +components or dispatched the AI search actions, migrate to the external Knowledge Discovery integration. + +### Library public API + +- **`@alfresco/aca-shared/store`** — **removed** the `search-ai.actions` and the `ai-search-by-term-payload` model + (part of the Knowledge Retrieval removal above), and **added** `node-path.utils`. + +`node-path.utils` exports a `NodeContentSource` type (`'personal-files' | 'libraries' | 'repository'`) and a +`getNodeContentSource(path)` helper for determining which content source a node belongs to. + +## New components and features + +- **External Knowledge Discovery link** — the `knowledge-discovery-sidenav` component and the runtime-configurable + `knowledgeDiscoveryUrl` app setting replace the removed in-app AI feature (ACS-12037 / #5295). +- **`node-path.utils`** (`@alfresco/aca-shared/store`) — `NodeContentSource` / `getNodeContentSource()` for + classifying a node's source (personal files, libraries or repository). +- **Repository Access improvements** (MNT-25732) — enhancements to the repository-view feature introduced in 7.5.0. +- **Search refactoring and unification** (MNT-25681), plus a debounce timer for saved searches that limits API + calls on every keystroke (ACS-12041). + +## Behavioural changes + +| Area | Change | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Shared Files | Sorting now works for the Location, Size, Modified-by and Shared-by columns (ACS-12246). | +| Bulk upload | The context menu no longer disappears during a bulk upload (ACS-11973), and the preview no longer switches to the next file (ACS-12047). | +| Folder rules | Files can no longer be incorrectly marked as selected in the link-rules dialog (ACS-11975). | +| Viewer | The image-viewer toolbar is no longer transparent in crop mode (ACS-12014). | +| Search | The same term can be executed again when the search mode changes (#5297). | +| Styling | Container elevation now uses a proper shadow rather than `box-shadow: none` (ACS-11879, an MD3 follow-up). |