Changelog ========= Changes to this project will be documented in this file. If you're upgrading from an older Unpoly version, you should load [`unpoly-migrate.js`](https://unpoly.com/changes/upgrading) to polyfill deprecated APIs. Changes handled by `unpoly-migrate.js` are not considered breaking changes. You may browse a formatted and hyperlinked version of this file at . 3.14.2 ------ You can now use `:has()` selectors with Unpoly-specific suffixes like `:maybe`, [`:before`](/targeting-fragments#appending-or-prepending) and [`:after`](/targeting-fragments#appending-or-prepending). For example, this target selector is now valid: ```css .container:has(.child):maybe ``` 3.14.1 ------ - Source maps for minified are now included in the npm package. 3.14.0 ------ This release delivers many requested features while filing off some long-standing sharp edges throughout the framework. Breaking changes are marked with a ⚠️ emoji and polyfilled by [`unpoly-migrate.js`](https://unpoly.com/changes/upgrading). > [note] > Our sponsor [makandra](https://makandra.de/en) funded this release ❤️\ > You can hire makandra for [Unpoly support](https://unpoly.com/support). ### Global scripting policies This version introduces settings to globally control whether Unpoly will execute JavaScript on your page. #### Script elements The boolean `up.fragment.config.runScripts` has been replaced with a more flexible setting `up.script.config.scriptElementPolicy`. This lets you control whether to run scripts in new fragments: ```html

``` ⚠️ By default Unpoly will now run any ` ``` ### Relaxed JSON Unpoly now supports [relaxed JSON](/relaxed-json) in all attributes and options where it also accepts JSON. Relaxed JSON is a JSON dialect that that aims to be easier to write by humans. It supports syntactic sugar that you enjoy with JavaScript [object literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer): - Unquoted property names - Single-quoted strings - Trailing commas For example, you can now write `[up-data]` like this: ```html Bob ``` When Unpoly outputs HTML (e.g. for the `X-Up-Context` header) it always produces regular JSON. ### Progress bar Improvements have been made to the [global progress bar](/progress-bar), which appears when requests are tooking long to load: - The progress bar will no longer restart its animation when a request is immediately followed by another request. For example, when a user changes an `[up-autosubmit]` form that is already waiting for a request, a second request is sent after the first request has loaded. The progress bar will now show one uninterrupted animation until all requests have loaded. - Old versions have used a "bad response time" setting to define the delay until the [progress bar](/progress-bar) is shown. This setting has been renamed to "late delay" everywhere: | Old name | New name | |----------|----------| | ❌ `[up-bad-response-time]` | ✅ `[up-late-delay]` | | ❌ `{ badResponseTime }` | ✅ `{ lateDelay }` | | ❌ `up.network.config.badResponseTime` | ✅ `up.network.config.lateDelay` | | ❌ `up.Request.prototype.badResponseTime` | ✅ `up.Request.prototype.lateDelay` | - Foreground requests can now opt out of the progress bar (and `up:network:late` events) by setting `[up-late-delay="false"]` or `{ lateDelay: false }`. ### Disabling form fields Unpoly 3.0 has added the `[up-disable]` attribute to [disable forms while working](/disabling-forms). This release adds the following features: - When fields are [disabled](/disabling-forms) during a render pass, and a field loses its focus, that field is now re-focused when the field is re-renabled afterwards. - You can now [disable form fields when the user activates a hyperlink](/disabling-forms#from-link). - Disabling now also disable non-submit buttons, like an `button[type=button]` or `input[type=button]`. - New configuration `up.form.config.genericButtonSelectors`. - The `{ disable }` option now also accepts an `Element` (or an array of elements) to disable. - Fix a bug where rendering with `up.render({ disable })` would crash unless an `{ origin }` was also passed. ### Tokens are separated by comma When a string contains multiple tokens, Unpoly used to separate those tokens with a space character. While this is still possible, the new canonical way is to separate tokens with a comma: | Old form (still valid) | New form | |------------|-----------| | ✅ `[up-layer="parent root"]` | ✅ `[up-parent="parent, root"]` | | ✅ `[up-show-for="value1 value2"]` | ✅ `[up-show-for="value1, value2"]` | | ✅ `[up-alias="/foo /bar"]` | ✅ `[up-alias="/foo, /bar"]` | | ✅`up.on('event1 event2', fn)` | ✅ `up.on('event1, event2', fn)` | In some cases tokens used to be separated by an `or` operator. This is no longer supported. Use a comma instead: | Old form (now invalid) | New form | |------------|-----------| | ❌ `[up-scroll="target or main"]` | ✅ `[up-scroll="target, main"]` | | ❌ `[up-focus="target or main"]` | ✅ `[up-scroll="target, main"]` | ### Feedback classes Unpoly assigns the `.up-active` class to clicked links and submit buttons, and `.up-loading` to targeted fragments that are loading new content. These [feedback classes](/feedback-classes) have been reworked to make it easier to select working elements from CSS and JavaScript: - `.up-active` and `.up-loading` are now always enabled by default (even when not [navigating](/navigation)). They can still disabled explicitly with an `[up-feedback=false]` attribute or a `{ feedback: false }` option. - When submitting a form, the `

` element now also receives the `.up-active` class (in addition to the submit button). - When submitting a form from a focused field, the default submit button now also receives the `.up-active` class (in addition to the field and the ``). - Added a configuration `up.status.config.activeClasses`. This allows to set custom CSS classes for working links and forms. - Added a configuration `up.status.config.loadingClasses`. This allows to set custom CSS classes for targeted fragments that are loading new content. ### Better selector parsing Unpoly 3.10 is smarter when parsing values with structured grammar, and no longer relies on magic strings to split complex expressions. For example, Unpoly can now process more complex target selectors. Selectors like `.foo:has(.bar, .baz)` or `.foo[attr="one, two"]` used to cause quirky behavior, but are now parsed correctly. ### Native `:has()` selector For almost 10 years Unpoly has polyfilled the [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) pseudo-selector for all browsers. Since then the selector has been standardized and has received [great browser support](https://caniuse.com/css-has). Starting with this release, Unpoly will no longer include a polyfill and use the browser's native `:has()` support. Unpoly will no longer boot on old browsers that don't support `:has()` natively. ### Watching fields for changes Unpoly has several methods to detect and process changes in form fields, most notably `[up-watch]`, `[up-autosubmit]` and `[up-validate]`. This release includes the following changes: - The `[up-watch]` callback can now use an `options` argument. It contains an object of all [watch options](/watch-options) parsed from that field, e.g. `{ disable, preview, placeholder }`. - The watch options `{ event, delay }` will no longer be passed to callbacks of `up.watch()` and `[up-watch]`, as these options have already been processed by Unpoly. - ❌ `up.watch()` and `[up-watch]` will no longer process an `[up-watch-disable]` attribute. Instead the attribute is only parsed and passed to the callback as a `{ disable }` option. It is up to the callback to forward the option it to any rendering function that supports `{ disable }`. - Fix a bug where `up.autosubmit()` options did not override options parsed from `[up-watch-...]` prefixed attributes. It is convention in Unpoly that JavaScript options [always take precedence](/attributes-and-options#options) over HTML attributes. ### Target derivation [Target derivation](/target-derivation#derivation-patterns) is the process of finding a discriminating CSS selector for an element. This release includes the following changes: - `up.fragment.toTarget()` now supports a `{ strong: true }` option. This produces a more unique selector by only considering the element's `[id]` and `[up-id]` attributes. Weaker [derivation patterns](/target-derivation#derivation-patterns), like the element's class, are not considered in strong mode. The element's tag name is only considered for singleton elements like `` or ``. - `up.fragment.toTarget()` can now skip [target verifcation](/target-derivation#verification) by passing a `{ verify: false }` option. - When a [validated](/validation#validating-after-changing-a-field) field wants to update its form group, that form group is no longer targeted by its `[class]`, which would often be ambigous. Instead the form group is only targeted by its `[id]` or `[up-id]` attribute. If the form group doesn't have an `[id]` or `[up-id]` attribute, it is targeted with a `.has()` selector referencing the changed field, e.g. `fieldset:has(#changed-field)`. ### [Fragment API](/up.fragment) - You can now [update element's inner HTML](/targeting-fragments#content) using the `.element:content` pseudo-selector. This swaps all children of `.element`, while preserving the element itself. This feature was previously documented, but didn't work yet. - New configuration `up.fragment.config.renderOptions`. This is an object of default render options to always apply, even when not [navigating](/navigation). - When calling `up.fragment.get()` with multiple search layers (e.g. `{ layer: "current, parent"}`), Unpoly will now search those layers in the given order. - Calling `up.fragment.get()` with an `Element`, that element is returned without further lookups. - New `[up-use-data]` attribute allows to [override data](/data#override) for the targeted fragment. The corresponding render options is `{ data }`. - The render option `{ useHungry }` has been renamed to `{ hungry }`, but `{ useHungry }` is still accepted as an alias. The corresponding HTML attribute remains `[up-use-hungry]` as to not conflict with a link's or form's own `[up-hungry]` modifier. - The render option `{ useKeep }` has been renamed to `{ keep }`, but `{ useKeep }` is still accepted as an alias. The corresponding HTML attribute remains `[up-use-keep]` as to not conflict with a link's or form's own `[up-keep]` modifier. ### [Layers](/up.layer) - Opening a new overlay with only a `{ mode }` option has been deprecated. Always pass a `{ layer: 'new' }` option in addition to `{ mode }`. - The layer option `{ dismissAriaLabel }` has been renamed to `{ dismissARIALabel }` - When opening a new layer with `[up-use-data]` or `{ data }`, that data is now applied to the topmost swappable element (instead of to the overlay container). For example, `up.layer.open({ target: '#target', url: '/path', data: { ... }})` will apply the data object to the `#target` element. - When [opening an overlay](/opening-overlays), the property `Request#layer` is now set to `'new'` (instead of to the parent layer). Also the `#fragments` property is now set to `[]` (instead of to the parent layer's main element) ### Working with node lists Many Unpoly functions have traditionally expected content with a single DOM element at its root. Unpoly 3.10 makes it easier to render lists of mixed `Text` and `Element` nodes: - `[up-content]` now also accepts multiple elements, or a mix of `Text` and `Element` siblings. - `{ content }` now accepts any `List`, e.g. the `NodeList` returned by `querySelectorAll()`. - New experimental function `up.element.createNodesFromHTML()`. This parses a [list](/List) of [nodes](https://developer.mozilla.org/en-US/docs/Web/API/Node) from a string of HTML. Unlike `up.element.createFromHTML()`, this new function does not require a single root element in the HTML. It can parse `Text` nodes, or a mixed list of `Text` and `Element` siblings. ### Bootstrap plugin - Clicked links and submit buttons now receive the `.active` class. ### `up.feedback` is now `up.status` The `up.feedback` package has been renamed to `up.status`. This package exposed no public JavaScript functions, but does have some configuration settings you need to rename: | Old name | New name | |------------|-----------| | ❌ `up.feedback.config.currentClasses` | ✅ `up.status.config.currentClasses` | | ❌ `up.feedback.config.navSelectors` | ✅ `up.status.config.navSelectors` | | ❌ `up.feedback.config.noNavSelectors` | ✅ `up.status.config.noNavSelectors` | ### Other changes - You can now [embed CSP nonces](/script-security#callback-nonces) into the attribute callbacks `[up-on-keep]`, `[up-on-hungry]` and `[up-on-opened]`. - New property `up.Request#ended` indicates whether this request is no longer waiting for the network for any reason. It is `true` when the server has responded or when the request [failed](/failed-responses) or was [aborted](/aborting-requests). - The attribute `[up-flashes]` is now stable (discussion #679) - Clicking a link with a page-local `#hash` in the `[href]` will now honor [fixed layout obstructions](/up-fixed-top) if the browser location is already on that `#hash`. - Fix a bug where a link with `[up-confirm]` would show the confirmation dialog before [preloading](/preloading). - Fix a crash with `up.submit({ submitButton: false })`. - Fix a bug where rendering with `{ focus: 'keep' }` would sometimes re-focus elements that never lost focus. - Fix a bug where opening an overlay would stop infinite scrolling (discussion #694). - Fix a bug where Unpoly would create duplicate cache entries when the server redirects to a fully qualified URL (with protocol and hostname). - Fix a bug where when a link with `[up-preload]` renders expired content from the cache, unhovering the link would abort the revalidation request. 3.9.5 ----- This is another maintenance release that addresses some bugs while we're working on the next major feature update. ### Changes - Fix a bug where targeted fragments would show the default [focus outline](/focus-visibility) on Safari. Regression introduced in 3.9.4. - Fix a bug where an overlay would show double scrollbars if `` was chosen as the overflow element. Regression introduced in 3.8.0. - Prevent Unpoly from following or preloading links with the `tel:` scheme when Unpoly is configured to [handle all links](/handling-everything) (by @begerdom). 3.9.4 ----- - Fix `.up-focus-hidden` style from causing flickering outlines when there is a `transition` on `outline-color` (by @foobear). 3.9.3 ----- This is a maintenance release that addresses some bugs while we're working on the next major feature update. ### Changes - Fix an error being thrown when a caching request is tracking an existing request to the same URL, and that existing request responds with an [error status](/failed-responses) (issue #676). - Fix a bug where a modal overlay could not be closed when a child popup would be open below the screen fold. - Focus is no longer trapped in popup overlays. Focus remains trapped in all other overlay modes, but this can be disabled by setting `up.layer.config.overlay.trapFocus = false`. - The dismiss button in overlays now has a hand cursor (by @apollo13). - Fix a bug where links with relative URLs were sometimes [revalidated](/caching#revalidation) against the wrong base URL (issue #669). 3.9.2 ----- - Fix a bug where `up:fragment:loaded` listeners could not open a new layer by setting `event.renderOptions.layer = "new"`. 3.9.1 ----- - Fix a bug where any `form[up-target]` would receive a `[role=button]` attribute (issue #668). 3.9.0 ----- This release brings many fixes and quality-of-life improvements that were requested by the community. The vast majority of these changes are backward compatible. One breaking change can be found with [making links followable](#making-links-followable). Existing usage is polyfilled by [`unpoly-migrate.js`](/changes/upgrading). ### Emitting events on buttons - You can now use `[up-emit]` to emit an event when any element is clicked. In particular this works with a `