apostrophe/CHANGELOG.md

The Apostrophe Content Management System.

# Changelog

## 4.28.1

### Patch Changes

- f8d1952: Bug fix: the "pretty URLs" feature of @apostrophecms/file is now compatible with locale prefixes.

## 4.28.0

### Adds

- Adds support for static URLs and static external frontend builds.
- Adds widget graph store, accessible in Admin UI.
- Support for the new `prettyUrls: true` option for @apostrophecms/file, which enables "pretty URLs" for PDFs and other items in the file library, in exchange for a small performance impact. Edit the slug field to adjust the pretty URL

### Fixes

- Fix a bug when rich text link open in new tab checkbox can't be cleared
- Ensures the `getOne` API can correctly retrieve documents that are not localized. Thanks to [Eduardo Correal](https://github.com/ecb34).
- Clicking a choice should dismiss the relationship suggestions dropdown. This regression was caused by part of the patch in release 4.27.1.
- lint on main
- Adds inner wrapper to area widget that creates a separate z-index context for the user, fixing widget/apostrophe UI conflicts
- Fixes a bug where Layout's mode erroneously switches state
- Fixes a bug where Layouts synthetic column styles were not reaching their children
- Fixes styles being sanitized as html (breaks quotes) and resolves duplicate styles on the page.
- Fix subtle bug in AposPermissionGrid that caused unrelated clicks to be "swallowed" due to a race condition at low network speeds
- Fixes two conditions where slow internet speed could cause input to lose focus before a selection can be registered.

### Changes

- Improve re-rendering UX while keeping the performance optimization
- raise the user's widget z-index context only when focused
- Hide add content buttons on rich text editing, like widget controls
- Refine in-context focus states for calmer UX
- Simplifies some in-context UI rendering checks
- Updated dependencies

### Security

- This previously undisclosed security vulnerability allowed users who had compromised a password to perform actions in the CMS without 2FA. For sites not using 2FA (e.g. our @apostrophecms/login-totp module), this changes nothing. But for those using our TOTP module or similar, upgrading to this release is urgent. Thanks to 0xkakashi for reporting the issue and recommending a fix.

## 4.27.1 (2026-03-03)

### Fixes

- Fixes two conditions where slow internet speed could cause relationship field inputs to lose focus before a selection can be registered.
- Fixes a subtle bug in AposPermissionGrid that caused unrelated clicks to be "swallowed" due to a race condition at low network speeds.

## 4.27.0 (2026-02-18)

### Adds

- Relax the image and attachment related Nunjucks helpers, they should never throw.
- Adds the `intlMapping` option to locale configuration to map custom locale codes to standard ones for `Intl` usage. This property is available in `apos.i18n.locales` for project-level code.
- In `@apostrophecms/i18n` add `direction` property to locale configuration to support RTL languages (e.g., `he`, `ar`), `slugDirection` option to control default direction of slug fields. Add `direction` property in the schema field definitions to override and validate text direction (supports `ltr` and `rtl`) of input fields. Note that the admin UI layout and labels overall are still LTR only for now, but these changes accommodate editing RTL locale content within that. For best results the feature should be combined with `adminLocales` and `defaultAdminLocale` module options, e.g. the admin UI itself should remain in English or another LTR language for now.
- Add new `showBreakpointsHelp` option (default `true`). If set to `false`, the "Show tablet/mobile" fields help text will be removed from the UI.
- Adds windowed view to widget editor
- Added support for translation interpolation for schema fields in the UI via `labelInterpolation` and `helpInterpolation` schema properties.
- Updates Global Styles Editor window title
- Updated dependencies [bbf3359]
  - sanitize-html@2.17.1

### Fixes

- Fix hardcoded help text in Layout Column fields. Rename the existing `breakpoints` option to `labelBreakpoints` for clarity. The old option is deprecated but still supported for BC reasons.
- Fix a bug where rich text images and permalinks are not properly rendered in public external front (e.g. Astro) views.
- Fixed a regression introduced in 4.26.0 that could cause some areas on the page not to be editable outside of the page or piece settings dialog.

## 4.27.0-alpha.2

### Changes

- Removes commit resolution markers that were left behind in the 4.27.0-alpha.1 release

## 4.26.1

### Fixes

- No changes relative to 4.26.0. Published to reset the `latest` tag in `npm`, which inadvertently pointed to an alpha release for a brief period of time.

## 4.27.0-alpha.1

### Adds

- In `@apostrophecms/i18n` add `direction` property to locale configuration to support RTL languages (e.g., `he`, `ar`), `slugDirection` option to control default direction of slug fields. Add `direction` property in the schema field definitions to override and validate text direction (supports `ltr` and `rtl`) of input fields. Note that the admin UI layout and labels overall are still LTR only for now, but these changes accommodate editing RTL locale content within that. For best results the feature should be combined with `adminLocales` and `defaultAdminLocale` module options, e.g. the admin UI itself should remain in English or another LTR language for now.

## 4.26.1-alpha.1

### Fixes

- Fix a bug where rich text images and permalinks are not properly rendered in public external front (e.g. Astro) views.

## 4.26.0

### Adds

- Add new Global Styles and Widget Styles features
- Explicitly specify `meta encoding="utf-8"` to ensure browser auto-detection does not inadvertently cause problems in a very small percentage of cases. Note that utf-8 is the only official encoding supported for html5.
- Adds field unit to box input UI if provided
- When editing a relationship it is now much easier to create and select new content for that purpose. A "New" button is directly exposed in the manager, a newly created document is automatically selected for the relationship, and several relevant bugs were fixed.
- Rich text table styles are now available in the public build and can be overridden by project level `modules/@apostrophecms/ui/ui/src/index.scss` file

### Changes

- Fix box field type to generate valid css properties
- set layout columns to min-width 0 to prevent automatic overflowing
- if no class provided for a rt style set it to null to ensure removal
- Updated dependencies

## 4.25.0

### Adds

- If you want production sourcemaps to be created but not actually uploaded for the public, you can combine `productionSourceMaps: true` with the new `productionSourceMapsDir` option to specify an alternate location where the `@apostrophecms/asset:build` task should place them. By using this option, you take responsibility for delivering the sourcemaps to their final home. Creating and/or erasing the folder between builds is also up to you. Most people will not need this option.
- Adds support for context utility admin bar items to display a label and omit an icon

### Fixes

- Fixes an issue where the frontend was caching stale choices for `select`, `radio` and `checkboxes` fields that were saved but no longer valid (i.e removed from the schema).
- When we reach the max in a widget area, the `Add Content` button is now disabled.
- Fix `getManagerOf` to log an error and return `undefined` instead of throwing for unsupported metaTypes

### Changes

- Bumped dependency on `express-cache-on-demand` to guarantee installation of recent fixes for edge cases that could share a response between two locales of a single-site project, report errors without a process restart, and correctly handle `res.send('')` with an empty string.
- Restores relative import paths inside Vite-generated entrypoints on \*nix builds so dev server HMR works again, while keeping the Windows-specific absolute path workaround.
- The `productionSourceMaps` option is now fully supported in both Vite and Webpack. Previously this feature did not work fully in Vite, and was not supported with Webpack. Enabling this feature completes the task of making sourcemaps fully available in the browser in production.
- Relationship input's autocomplete list now positioned with floating-ui

## 4.24.1 (2025-12-04)

### Fixes

- Fixes soft-redirect module to decode the URL path before matching historic URLs, ensuring proper matching of accents, Cyrillic, and other non-ASCII characters in old URLs. While this was not a new issue, the fix is of new importance now that a migration path to eliminate accent marks in existing slugs has been introduced in version 4.24.0.

### Adds

- Adds a new `isAdmin` method to the `permission` module.

## 4.24.0 (2025-11-25)

### Adds

- Adds `stripUrlAccents` option in `@apostrophecms/i18n` module to globally control whether accents are stripped from URLs. When set to `true`, all URLs (slugs) will have accents from Latin characters removed on document creation and updates. No existing documents are modified automatically; this only affects new or updated documents. A new task `node app @apostrophecms/i18n:strip-slug-accents` is provided to update existing document slugs in the database when needed.
- Add `@apostrophecms/migration:add-missing-schema-fields` task. This task does not run database migrations.
- Translation strings added for the layout- and layout-column-widgets.
- Adds `@apostrophecms/doc:get-apos-doc-id` and `@apostrophecms/doc:set-apos-doc-id` tasks.
- New `box` schema field type
- When switching locale from the doc editor, ask if the user wants to localize the current document in the target locale or want to start a blank document.
- Adds batch failure notifications.
- Introduced a new `longPolling: false` option for the `@apostrophecms/notification` module. This eliminates long-pending requests when logged in, but also slows down the delivery of notifications. The behavior can be tuned further via the `pollingInterval` option, which defaults to `5000` milliseconds.
- Add support for `def` in area fields - array of widget names to use as defaults when the area is created.

### Changes

- `@apostrophecms/migration:requirements` handler now runs the migration requirements like `insertIfMissing`, `implementParkAllInDefaultLocale`, `replicate` and `implementParkAllInOtherLocales`.
- Bump nodemailer to v7.x.
- Improves client error log when unable to render a widget.
- Rich text `styles` are once again available to insert menu items, such as our optional `@apostrophecms/ai-helper` module.

### Fixes

- Specify the content type when calling back to Astro with JSON to render an area. This is required starting in Astro 4.9.0 and up, otherwise the request is blocked by CSRF protection.
- Improved support for Node.js on "plain vanilla" Windows, e.g. without WSL. We suggest working with NVM for Windows and Git Bash.
- Fixes `AposBreadcrumbSwitch` tooltip prop that is supposed to be an object, not a string. Object returned from the shared method `getOperationTooltip`.
- Empty text nodes are output properly without a warning.
- Uses `modalData.locale` in `AposI18nLocalize` component. Fixes watcher on `relatedDocTypes` not being properly triggered (uses data and methods for more control instead).
- Layout area fix when no columns are present.

## 4.23.0 (2025-10-30)

### Adds

- Add locale picker in the page and piece manager modals.
- Support for the `render-areas` query parameter in the REST API when using Astro as an external frontend, provided the Astro project has the corresponding route. This allows section template library previews to work in Astro projects. For ease of migration, if Astro cannot satisfy the request, ApostropheCMS will also attempt to render the widget natively.
- Made `self.apos.externalFrontKey` available, simplifying API calls back to Astro.
- Layout widget for dynamic grid layouts.
- `widgetOperations` support for `placement: 'breadcrumb'` to add operations to the breadcrumb menu of widgets. Extend the widget operations configuration to support various features when in the breadcrumb menu.
- Area template (Nunjucks) support for `aposStyle`, `aposClassName`, `aposParentOptions` and `aposAttrs` contextual named variables (`with {}` syntax).
- New login option `caseInsensitive` to force login usernames and emails to be case insensitive. New task `login-case-insensitive` updating all login names / email to lowercase, used by a new migration when switching to `caseInsensitive`.
- Adds `disableIfProps` and `disableTooltip` to widget operations and breadcrumb operations.

### Changes

- Enable `/api/v1/@apostrophecms/login/logout` and `/api/v1/@apostrophecms/login/whoami` routes when `localLogin` is `false`.
- Refactored complex logic regarding data updates in `AposSchema`.
- Cleaned up `annotateAreaForExternalFront` logic and added context so developers understand the reason if it fails due to a widget type with no matching module in the project.
- Color fields now display their preset color swatches in the field UI rather than just the color picker popup
- Moves widget operations to backend with new `action` and `nativeAction` properties.
- Moves `mode` from breakpoint preview to it's own store (to be used by layout).

### Fixes

- The `render-areas` query parameter now works correctly with areas nested in array items.
- Fix min size calculation for image widgets configured with an aspect ratio.
- Added missing `await` in helper library function for the asset module, ensuring JS assets build reliably.
- Autodetection of bundles, and automatic activation of "improvements" shipped in those bundles, now works correctly when the bundle is delivered in ES module format rather than commonjs format.

## 4.22.0 (2025-10-01)

### Adds

- Custom operations registered with `addCreateWidgetOperation` can now specify an `ifTypesIntersect` property containing an array of widget type names. If the area in question allows at least one, the operation is offered.
- The login-requirements tests were updated to include tests for the `uponSubmit` filter
- Add `prependNodes` and `appendNodes` calls for `main`.
- Add options for pieces to change the title, message and icon of the empty state block.

### Fixes

- Fixes a bug in the login `uponSubmit` filter where a user could login without meeting the requirement.
- Fixes pieces filters when values from optional fields are falsy.
- Resolve inline image URLs correctly when in edit mode and not in the default locale.
- Using `CTRL+F` or `CMD+F` in the page manager now works.

### Changes

- Redirects to URLs containing accent marks and other non-ascii characters now behave as expected with Astro. Pre-encoding the URLs exactly the way `res.redirect` would before passing them to Astro prevents an error in Astro and allows the redirect to succeed.
- Removes the non-functional `uniqueUsername` route from the `user` module
- Modifies the `annotateAreaForExternalFront()` method of the `@apostrophecms/template` module to accept a per-module `annotateWidgetForExternalFront()` method. This allows widgets to send project-level options alongside the per-area options to external frontends.
- Updated dependencies to address deprecation warnings.

## 4.21.1 (2025-09-26)

### Adds

- The `exit` option to the main `apostrophe()` function now supports the new string value `exit: 'throw'`. If this value is specified and the apostrophe startup procedure fails with an error, the actual error is re-thrown for the benefit of the caller.
- For backwards compatibility, the existing `exit: false` option to the main `apostrophe()` function is still supported, but now logs the error that took place before returning `undefined` as before. This is more useful than the previous behavior, but `exit: 'throw'` is the more logical choice if you need to avoid a process exit.
- The default behavior is still to log the error and exit the process, which isthe only sensible move in most single-site projects.

## 4.21.0 (2025-09-03)

### Adds

- Modules can now call `apos.area.addCreateWidgetOperation` to register a custom operation that invokes a modal and inserts the widget returned by that modal. These operations are offered as choices in all "add widget" menus, both regular and expanded.
- `AposDocEditor` now accepts a `values` prop, which can be used to pass an object of initial values for some or all fields. Use of this prop is optional. It is not supported when editing existing documents.
- `apos.doc.edit` now accepts an optional `values` object as the final parameter, containing initial values for some or all fields. This is supported only when editing existing documents.
- When specifying a modal name to be executed, developers may now register "transformers" to be invoked first, using pipe syntax. For example, the modal name `aposSectionTemplateLibraryWidgetToDoc|AposDocEditor` will invoke the transformer `aposSectionTemplateLibraryWidgetToDoc` with the original props, and pass the returned result to `AposDocEditor`. Note that transformers are awaited. Transformers are registered in frontend admin UI code by passing a name and a function to `apos.ui.addTransformer`.
- Adds quick image upload UI to `@apostrophecms/image-widget`.
- Makes autocropping work when uploading or selecting images from the new quick image upload UI.

### Fixes

- The `?render-areas=1` API feature now correctly disregards areas in separate documents loaded via relationship fields. Formerly their presence resulted in an error, not a rendering.
- Make conditional fields work in Image Editor.
- Importing a custom icon from an npm module using a `~` path per the admin UI now works per the documentation, as long as the Vue component used for the icon is structured like those found in `@apostrophecms/vue-material-design-icons`.
- The `button: true` flag works again for piece module utility operations. Previously the button appeared but did not trigger the desired operation.
- Fix the fact that area options `minSize` and `aspectRatio` weren't passed to the image cropper when coming directly from the area and the widget controls (without passing through the widget editor).
- Fixes the widget data being cloned to be saved before the `postprocess` method being called, which leads to a loss of data in `AposWidgetEditor` (like the autocrop data).
- In editors like `AposWidgetEditor` relationships are now post processed after they are updated in `AposInputRelationship` only for the relationship that has been updated.
  It allows live preview to work well with it, it also avoids complexity and fixes updated data not being properly synced between the editor and the `AposSchema`.
- Deeply nested widgets can now be edited properly via the editor dialog box. This longstanding issue did not affect on-page editing.

### Changes

- Rolled back a change in 4.16.0 that strictly enforced `required` and `min` for relationship fields. Because the related document can be archived or deleted at any time, it is misleading to offer such enforcement. Also, it greatly complicates adding these constraints to existing schemas, resulting in surprising and unwanted behaviors. Therefore it is better for these constraints to be soft constraints on the front end. `max` is still a hard constraint.
- The `@apostrophecms/login/whoami` route now accepts both `POST` (recommended) and `GET` requests. Previously, it only supported `GET`. This maintains backwards compatibility while aligning with the documentation’s recommendation to use `POST`.

## 4.20.0 (2025-08-06)

### Adds

- Adds any alt text found in an attribute to the media library attachment during import of rich text inline images by API
- Adds `prependNodes` and `appendNodes` methods to every module. These methods allow you to inject HTML to every page using a `node` declaration.

### Changes

- A `clone-widget.js` file has been factored out, providing a universal way to return a clone of an existing widget which is distinct from the original.
- Adds any alt text found in an attribute to the media library attachment during import of rich text inline images by API
- Adds `prependNodes` and `appendNodes` methods to every module. These methods allow you to inject HTML to every page using a `node` declaration.
- Changes handling of `order` and `groups` in the `admin-bar` module to respect, rather that reverse, the order of items
- Interacting with the text inside a rich text widget will hide the widget controls to prevent awkward text selection.

### Fixes

- Let the `@apostrophecms/page:unpark` task unpark all parked pages with the given slug, not just the first one.
- Exclude unknown page types from the page manager.
- Remove multiple calls to render-widget when switch to edit mode.
- Resolved an issue affecting `withRelationships` with two or more steps. This issue could cause a document to appear to be related to the same document more than once.
- You can now use checkboxes as filter `inputType`.
- Fixed a regression that prevented multiple variations of `p` with different classes from being recognized again when reopening the rich text editor, even if they are all on the style menu. This was caused by knock-on effects of upstream changes in tiptap and prosemirror and our previous efforts to mitigate these. Those upstream changes were correct, but they did have certain side effects in ApostropheCMS. By more fully specifying the desired behavior, we have now fully corrected the issue at the ApostropheCMS level.
- Correctly update alt attribute of images in rich text widgets.

### Security

- Clear an npm audit warning by replacing `connect-multiparty` with `multer`. Thanks to [Radhakrishnan Mohan](https://github.com/RadhaKrishnan) for this contribution.
- To be clear, this was never an actual security vulnerability. The CVE in question is disputed, and for good reasons. However, since `connect-multiparty` is no longer maintained, it makes sense to move to `multer`.

## 4.19.0 (2025-07-09)

### Adds

- Implemented GET /api/v1/@apostrophecms/login/whoami route such that it returns the details of the currently logged in user; added the route to the login module.
  Thanks to [sombitganguly](https://github.com/sombitganguly) for this contribution.
- Adds keyboard shortcuts for manipulating widgets in areas. Includes Cut, Copy, Paste, Delete, and Duplicate.
- Automatic translation now supports a disclaimer and an help text for the checkbox. You can now set the disclaimer by setting `automaticTranslationDisclaimer` `i18n` key and the help text by setting `automaticTranslationCheckboxHelp` `i18n` key.
- Adds dynamic choices working with piece manager filters.
- Allow `import.imageTags` (array of image tag IDs) to be passed to the rich text widget when importing (see <https://docs.apostrophecms.org/reference/api/rich-text.html#importing-inline-images>).
- Adds a new way to make `GET` requests with a large query string. It can become a `POST` request containing the key `__aposGetWithQuery` in its body.
  A middleware checks for this key and converts the request back to a `GET` request with the right `req.query` property.
- Adds a new batch operation to tag images.

### Changes

### Fixes

- Add missing Pages manager shortcuts list helper.
- Improve the `isEmpty` method of the rich text widget to take into account the HTML blocks (`<figure>` and `<table>`) that are not empty but do not contain any plain text.
- Fixed admin bar item ordering to correctly respect the precedence hierarchy: groups (when leader is positioned) > explicit order array > groups (when leader has positioning options) > individual `last`/`after` options.
- (Backward compatibility break) Conditional field that depends on already hidden field is also hidden, again.

## 4.18.0 (2025-06-11)

### Adds

- Adds MongoDB-style support (comparison operators) for conditional fields and all systems that use conditions. Conditional fields now have access to the `following` values from the parent schema fields.
- Add `followingIgnore` option to the `string` field schema. A boolean `true` results in all `following` values being ignored (not attempted to be used as a value for the field). When array of strings, the UI will ignore every item that matches a `following` field name.
- Adds link configuration to the `@apostrophecms/image-widget` UI and a new option `linkWithType` to control what document types can be linked to. Opt-out of the widget inline styles (reset) by setting `inlineStyles: false` in the widget configuration or contextual options (area).
- Use the link configuration of the Rich Text widget for image links too. It respects the existing `linkWithType` Rich Text option and uses the same schema (`linkFields`) used for text links. The fields from that schema can opt-in for specific tiptap extension now via a field property `extensions` (array) with possible array values `Link` and/or `Image`. You still need to specify the `htmlAttribute` property (the name of the attribute to be added to the link tag) in the schema when adding more fields. If the `extensions` property is not set, the field will be applied for both tiptap extensions.
- Adds body style support for breakpoint preview mode. Created new `[data-apos-refreshable-body]` div inside the container during breapoint preview.
  Switch body attributes to this new div to keep supporting body styles in breakpoint preview mode.

### Changes

- Set the `Cache-Control` header to `no-store` for error pages in order to prevent the risk of serving stale error pages to users.
- Updates rich-text default configuration.

### Fixes

- The Download links in the media library now immediately download the file as expected, rather than navigating to the image in the current tab. `AposButton` now supports the `:download="true"` prop as expected.
- Using an API key with the editor, contributor or guest role now have a `req` object with the corresponding rights. The old behavior gave non-admin API keys less access than expected.

## 4.17.1 (2025-05-16)

### Fixes

- Pinned to tiptap 2.11.0 and specific prosemirror releases compatible with it, to work around a bug that broke the behavior of lists in the editor when re-opening an existing list. We are working with upstream projects to resolve this so we can continue to track updates in tiptap and prosemirror.

## 4.17.0 (2025-05-14)

### Adds

- Support for `fetchRelationships: false` in `applyPatch` and related methods. This is intended for the use of the `@apostrophecms/import-export` module, so the functionality is not exposed in a way that can be accessed simply by making a web request.

### Fixes

- Errors thrown on the server side by subfields of widgets are now reported in a useful form at the document level. Previously a different error occurred in the error handling logic itself, confusing the issue.

## 4.16.0 (2025-05-14)

### Adds

- Uses new `widgetOperations` to add the `adjustImage` operation to the image widget.
- Adds a server validation before adding a widget to an area. Introduces a new POST route `@apostrophecms/area/validate-widget`.
- The new `widgetOperations` cascade config property can be used to display custom operations for widgets. An `if` condition can be used to test properties of the widget before displaying an operation.

### Changes

- Enable widget live preview by default.

### Fixes

- Fixes `range` field type default value not being set properly.
- Fixes autocomplete and search sorting and as a consequence, fixes potential duplicates during pagination.
- Fixes all eslint warnings.
- When pasting a widget from the clipboard, the correct widget type is always offered on the "Add Content" menu.
- Widget live preview is now attempting to auto-position the Widget Editor modal only if no explicit widget configuration (`options.origin`) is provided.
- `required` is now implemented on the server side as well for `relationship` fields. It behaves like `min: 1`. It was always implemented on the front end. However, note that a relationship can still become empty if the related document is archived or deleted.
- Image widgets, and others with a placeholder when empty, now restore their placeholder view when canceling the widget editor in live preview mode.
- Fixes `z-index` of widget controls, going above the controls add button.

### Changes

- Updates the default fields for the `getMangageApiProjection()` to include a more sensible base configuration and adds a `true` option to return the minimal default values.

## 4.15.2 (2025-04-28)

### Security

- Fixes a potential XSS attack vector, [CVE-2025-26791](https://github.com/advisories/GHSA-vhxf-7vqr-mrjg). While the risk was low, it was possible for one user with login and editing privileges to carry out an XSS attack on another by uploading a specially crafted SVG file. Normally this would not work because ApostropheCMS typically renders uploaded SVGs via an `img` tag, however if the second user downloaded the SVG file from the media library the exploit could work.

## 4.15.1 (2025-04-22)

### Fixes

- Fixes a RT bug where including `table` in `toolbar` but omitting an `insert` array crashed the rich text editor.

## 4.15.0 (2025-04-16)

### Adds

- To display a live preview on the page as changes are made to widgets, set the `preview: true` option on any widget module. To turn it on for all widgets, you can set it on the `@apostrophecms/widget-type` module, the base class of all widget modules. This works especially well when `range` fields are used to achieve visual effects.
- Adds separate control bar for editing tables in rich text
- Adds ability to drag-resize rich text table columns

### Changes

- Improve the Page Manager experience when dragging and dropping pages - the updates happen in background and the UI is not blocked anymore.
- Allow scrolling while dragging a page in the Page Manager.
- Change user's email field type to `email`.
- Improve media manager experience after uploading images. No additional server requests are made, no broken UI on error.
- Change reset password form button label to `Reset Password`.
- Removed overly verbose logging of schema errors in the schema module itself. These are already logged appropriately if they become the actual result of an API call. With this change it becomes possible to catch and discard or mitigate these in some situations without excessive log output.
- Bumps eslint-config-apostrophe, fix errors and a bunch of warnings.
- Gets back checkboxes in the media manager.

### Fixes

- Adds missing notifications and error handling in media manager and save notification for auto-published pieces.
- Update `uploadfs` to `1.24.3`.
- Fixes an edge case where reordering a page in the Page Manager might affect another locale.
- Fixes chrome bug when pages manager checkboxes need a double click when coming from the rich text editor (because some text is selected).
- Fixes the rich text insert menu image menu not being properly closed.
- Fixes the rich text toolbar not closing sometimes when unfocusing the editor.
- Fixes missing wording on images batch operations.
- Fixes rich text toolbar width being limited to parent width.
- Fixes rich text insert menu focused item text color easily overridable.
- Fixes long overlapping text in the header of the Report modal.
- Fixes clipped text in the pager and in the relationship filters of piece manager.
- Fixes an error when pressing Enter in a relationship input without a focused suggestion.
- Fixes locale switcher not allowing to switch the page of an article when its parent page is draft only.

## 4.14.2 (2025-04-02)

### Fixes

- Hotfix: the `choices` query parameter of the REST API no longer results in a 500 error if an invalid filter name is part of the list. Such filters are now properly ignored in `choices`. This issue could also have resulted in invocation of query methods that are not builders, however since all such methods are read-only operations, no arguments could be passed and no information was returned, there are no security implications.

## 4.14.1 (2025-03-31)

### Fixes

- Hotfix: fixes a bug in which the same on-demand cache was used across multiple sites in the presence of `@apostrophecms/multisite`. In rare cases, this bug could cause the home page of site "A" to be displayed on a request for site "B," but only if requests were simultaneous. This bug did not impact single-site projects.

## 4.14.0 (2025-03-19)

### Adds

- Add a label for the `@apostrophecms/attachment` module (error reporting reasons).
- Add `translate` boolean option for report modal header configuration to force translation of the relevant items value (table cells).
- Adds feature to generate a table from an imported CSV file inside the rich-text-widget.
- Add data-test attributes to the login page.
- Adds AI-generated missing translations
- Adds the missing "Tags" filter to the chooser/manager view of files.
- Adds batch operations to the media manager.
- Passes `moduleName` to the event `content-changed` for batch operations, to know if data should be refreshed or not.

### Changes

- Bumps the `perPage` option for piece-types from 10 to 50
- Reworks rich text popovers to use `AposContextMenu`, for toolbar components as well as insert menu items.

### Fixes

- The `lang` attribute of the `<html>` tag now respects localization.
- Fixes the focus styling on AposTable headers.
- Proper errors when widgets are badly configured in expanded mode.
- More reliable Media Manager infinite scroll pagination.
- Fixes margin collapse in nested areas by switching to `padding` instead of `margin`
- Fixes Edit in Media Manager when the image is not in the currently loaded images. This may happen when the the Media Manager is in a relationship mode.
- Removes `publish` batch operation for `autopublished` pieces.
- Fixes `restore` batch operation having the action `update`.
- Fixes `localize` batch operation having no `action` and no `docIds`.

### Removes

- Table controls from the default rich text control bar

## 4.13.0 (2025-02-19)

### Adds

- Supports progress notification type, can be used when no job are involved. Manage progress state into the new `processes` entity.
- Moves global notification logic into Pinia store as well as job polling that updates processes.

### Fixes

- Field inputs inside an array modal can now be focused/tabbed via keyboard
- Fixes admin bar overlapping widget area add menu.
- Fixed the checkered background for gauging color transparency.
- Fixes `group.operations` (batch configuration) merging between modules in the same way that `group.fields` are merged.
- The i18n manager detects the current locale correctly in some edge cases, like when the locale is changed per document (Editor Modal) and the localization manager is opened from a relationship manager via a document context menu.

### Adds

- Add support for batch localization of pieces and pages.
- Adds type for each file uploaded by big-upload. Moves big-upload-client to `apos/ui` folder and makes it esm.
- When present, projections for reverse relationships now automatically include the special id and field storage properties for the relationship in question, allowing the related documents to be successfully returned.
- Introduce `AposModalReport` component for displaying table reports. It's accessible via `apos.report(content, options)` method and it's now used in the `@apostrophecms/i18n` module for detailed reporting after a batch localization operation.

### Changes

- The array editor's `isModified` method is now a computed property for consistency.
- The `modal` configuration property for batch operations without a group is now accepted and works as expected in the same way as for grouped operations.
- Explicitly enable document versions for `@apostrophecms/file-tag`, `@apostrophecms/file`, `@apostrophecms/image-tag` and `@apostrophecms/image` piece types.

### Adds

- If `error.cause` is prevent, log the property.

## 4.12.0 (2025-01-27)

### Fixes

- Fixes ability to change color hue by clicking the color hue bar rather than dragging the indicator.
- Prevents the rich text control bar from closing while using certain UI within the color picker.
- Saving a document via the dialog box properly refreshes the main content area when on a "show page" (when the context document is a piece rather than a page)
- Fixes the `AposButtonSplit` markup to follow the HTML5 specification, optimizes the component performance, visuals and testability.
- Fixes a case where releationship button overlaps a context menu.

### Adds

- Ability to disable the color spectrum UI of a color picker
- Accessibility improvement for the rich text editor Typography toolbar item.
- Adds `moduleLabels` prop to `AposDocContextMenu` to pass it to opened modals from custom operations (used by templates to define labels to display on the export modal).

### Changes

- Range style updates.
- The `pickerOptions` sub property of a color field's configuration has been merged with it's parent `options` object.
- Reworks `inline` and `micro` UI of some fields (color, range, select). Improve global inline style.
- Makes the range input being a number all the time instead of a string that we convert manually.
- Command line tasks can run before the first frontend asset build without error messages.

## 4.11.2 (2024-12-29)

### Fixes

- Fixes a bug where images in Media manager are not selectable (click on an image does nothing) in both default and relationship mode.
- Eliminated superfluous error messages. The convert method now waits for all recursive invocations to complete before attempting to determine if fields are visible.

### Adds

- Possibility to set a field not ready when performing async operations, when a field isn't ready, the validation and emit won't occur.

## 4.11.1 (2024-12-18)

### Fixes

- Corrected a unit test that relies on the sitemap module, as it now makes explicit that the project level `baseUrl` must be set for a successful experience, and the module level `baseUrl` was set earlier. No other changes.

## 4.11.0 (2024-12-18)

### Adds

- When validating an `area` field, warn the developer if `widgets` is not nested in `options`.
- Adds support for supplying CSS variable names to a color field's `presetColors` array as selectable values.
- Adds support for dynamic focus trap in Context menus (prop `dynamicFocus`). When set to `true`, the focusable elements are recalculated on each cycle step.
- Adds option to disable `tabindex` on `AposToggle` component. A new prop `disableFocus` can be set to `false` to disable the focus on the toggle button. It's enabled by default.
- Adds support for event on `addContextOperation`, an option `type` can now be passed and can be `modal` (default) or `event`, in this case it does not try to open a modal but emit a bus event using the action as name.

### Fixes

- Focus properly Widget Editor modals when opened. Keep the previous active focus on the modal when closing the widget editor.
- a11y improvements for context menus.
- Fixes broken widget preview URL when the image is overridden (module improve) and external build module is registered.
- Inject dynamic custom bundle CSS when using external build module with no CSS entry point.
- Range field now correctly takes 0 into account.
- Apos style does not go through `postcss-viewport-to-container-toggle` plugin anymore to avoid UI bugs.

## 4.10.0 (2024-11-20)

### Fixes

- Extra bundle detection when using external build module works properly now.
- Widget players are now properly invoked when they arrive later in the page load process.
- Fix permission grid tooltip display.
- Fixes a bug that crashes external frontend applications.
- Fixes a false positive warning for module not in use for project level submodules (e.g. `widges/module.js`) and dot-folders (e.g. `.DS_Store`).
- Bumped `express-bearer-token` dependency to address a low-severity `npm audit` warning regarding noncompliant cookie names and values. Apostrophe
  did not actually use any noncompliant cookie names or values, so there was no vulnerability in Apostrophe.
- Rich text "Styles" toolbar now has visually focused state.
- The `renderPermalinks` and `renderImages` methods of the `@apostrophecms/rich-text` module now correctly resolve the final URLs of page links and inline images in rich text widgets, even when the user has editing privileges. Formerly this was mistakenly prevented by logic intended to preserve the editing experience. The editing experience never actually relied on the
  rendered output.
- Search bar will perform the search even if the bar is empty allowing to reset a search.
- Fixes Color picker being hidden in an inline array schema field, also fixes rgba inputs going off the modal.

### Adds

- It's possible now to target the HMR build when registering via `template.append` and `template.prepend`. Use `when: 'hmr:public'` or `when: 'hmr:apos'` that will be evaluated against the current asset `options.hmr` configuration.
- Adds asset module option `options.modulePreloadPolyfill` (default `true`) to allow disabling the polyfill preload for e.g. external front-ends.
- Adds `bundleMarkup` to the data sent to the external front-end, containing all markup for injecting Apostrophe UI in the front-end.
- Warns users when two page types have the same field name, but a different field type. This may cause errors or other problems when an editor switches page types.
- The piece and page `GET` REST APIs now support `?render-areas=inline`. When this parameter is used, an HTML rendering of each widget is added to that specific widget in each area's `items` array as a new `_rendered` property. The existing `?render-areas=1` parameter is still supported to render the entire area as a single `_rendered` property. Note that this older option also causes `items` to be omitted from the response.

### Changes

- Removes postcss plugin and webpack loader used for breakpoint preview mode. Uses instead the new `postcss-viewport-to-container-toggle` plugin in the webpack config.
- Implement `vue-color` directly in Apostrophe rather than as a dependency
- Switch color handling library from `tinycolor2` to `@ctrl/tinycolor`
- Removes error messages in server console for hidden fields. These messages should not have been printed out in the server console in the first place.
- Removes invalid error messages on select fields appearing while opening an existing valid document.

## 4.9.0 (2024-10-31)

### Adds

- Relationship inputs have aria accessibility tags and autocomplete suggestions can be controlled by keyboard.
- Elements inside modals can have a `data-apos-focus-priority` attribute that prioritizes them inside the focusable elements list.
- Modals will continute trying to find focusable elements until an element marked `data-apos-focus-priority` appears or the max retry threshold is reached.
- Takes care of an edge case where Media Manager would duplicate search results.
- Add support for ESM projects.
- Modules can now have a `before: "module-name"` property in their configuration to initialize them before another module, bypassing the normal
  order implied by `defaults.js` and `app.js`.
- `select` and `checkboxes` fields that implement dynamic choices can now take into account the value of other fields on the fly, by specifying
  a `following` property with an array of other field names. Array and object subfields can access properties of the parent document
  by adding a `<` prefix (or more than one) to field names in `following` to look upwards a level. Your custom method on the server side will
  now receive a `following` object as an additional argument. One limitation: for now, a field with dynamic choices cannot depend on another field
  with dynamic choices in this way.
- Adds AI-generated missing translations
- Adds the mobile preview dropdown for non visibles breakpoints. Uses the new `shortcut` property to display breakpoints out of the dropdown.
- Adds possibility to have two icons in a button.
- Breakpoint preview only targets `[data-apos-refreshable]`.
- Adds a `isActive` state to context menu items. Also adds possibility to add icons to context menu items.
- Add a postcss plugin to handle `vh` and `vw` values on breakpoint preview mode.
- Adds inject component `when` condition with possible values `hmr`, `prod`, and `dev`. Modules should explicitely register their components with the same `when` value and the condition should be met to inject the component.
- Adds inject `bundler` registration condition. It's in use only when registering a component and will be evaluated on runtime. The value should match the current build module (`webpack` or the external build module alias).
- Adds new development task `@apostrophecms/asset:reset` to reset the asset build cache and all build artifacts.
- Revamps the `@apostrophecms/asset` module to enable bundling via build modules.
- Adds `apos.asset.devServerUrl()` nunjucks helper to get the (bundle) dev server URL when available.
- The asset module has a new option, `options.hmr` that accepts `public` (default), `apos` or `false` to enable HMR for the public bundle or the admin UI bundle or disable it respectively. This configuration works only with external build modules that support HMR.
- The asset module has a new option, `options.hmrPort` that accepts an integer (default `null`) to specify the HMR WS port. If not specified, the default express port is used. This configuration works only with external build modules that support HMR WS.
- The asset module has a new option, `options.productionSourceMaps` that accepts a boolean (default `false`) to enable source maps in production. This configuration works only with external build modules that support source maps.

### Changes

- Silence deprecation warnings from Sass 1.80+ regarding the use of `@import`. The Sass team [has stated there will be a two-year transition period](https://sass-lang.com/documentation/breaking-changes/import/#transition-period) before the feature is actually removed. The use of `@import` is common practice in the Apostrophe codebase and in many project codebases. We will arrange for an orderly migration to the new `@use` directive before Sass 3.x appears.
- Move saving indicator after breakpoint preview.
- Internal methods `mergeConfiguration`, `autodetectBundles`, `lintModules`, `nestedModuleSubdirs` and `testDir` are now async.
- `express.getSessionOptions` is now async.

### Fixes

- Modifies the `AposAreaMenu.vue` component to set the `disabled` attribute to `true` if the max number of widgets have been added in an area with `expanded: true`.
- `pnpm: true` option in `app.js` is no longer breaking the application.
- Remove unused `vue-template-compiler` dependency.
- Prevent un-publishing the `@apostrophecms/global` doc and more generally all singletons.
- When opening a context menu while another is already opened, prevent from focusing the button of the first one instead of the newly opened menu.
- Updates `isEqual` method of `area` field type to avoid comparing an area having temporary properties with one having none.
- In a relationship field, when asking for sub relationships using `withRelationships` an dot notion.
  If this is done in combination with a projection, this projection is updated to add the id storage fields of the needed relationships for the whole `withRelationships` path.
- The admin UI no longer fails to function when the HTML page is rendered with a direct `sendPage` call and there is no current "in context" page or piece.

## 4.7.2 and 4.8.1 (2024-10-09)

### Fixes

- Correct a race condition that can cause a crash at startup when custom `uploadfs` options are present in some specific cloud environments e.g. when using Azure Blob Storage.

## 4.8.0 (2024-10-03)

### Adds

- Adds a mobile preview feature to the admin UI. The feature can be enabled using the `@apostrophecms/asset` module's new `breakpointPreviewMode` option. Once enabled, the asset build process will duplicate existing media queries as container queries. There are some limitations in the equivalence between media queries and container queries. You can refer to the [CSS @container at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@container) documentation for more information. You can also enable `breakpointPreviewMode.debug` to be notified in the console when the build encounters an unsupported media query.
- Apostrophe now automatically adds the appropriate default values for new properties in the schema, even for existing documents in the database. This is done automatically during the migration phase of startup.
- Adds focus states for media library's Uploader tile.
- Adds focus states file attachment's input UI.
- Simplified importing rich text widgets via the REST API. If you you have HTML that contains `img` tags pointing to existing images, you can now import them all quickly. When supplying the rich text widget object, include an `import` property with an `html` subproperty, rather than the usual `content` property. You can optionally provide a `baseUrl` subproperty as well. Any images present in `html` will be imported automatically and the correct `figure` tags will be added to the new rich text widget, along with any other markup acceptable to the widget's configuration.

### Changes

- The various implementations of `newInstance` found in Apostrophe, e.g. for widgets, array items, relationship fields and documents themselves, have been consolidated in one implementation. The same code is now reused both on the front and the back end, ensuring the same result without the need to introduce additional back end API calls.

### Fixes

- Apostrophe's migration logic is no longer executed twice on every startup and three times in the migration task. It is executed exactly once, always at the same point in