Commit e15bd06

Unreleased

Unpoly now builds a form's request params with the browser's own [form-data algorithm](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData), instead of walking the form's fields itself.

- [Form-associated custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#form-associated_custom_elements) are now submitted, without any configuration. (by @kmmbvnr)

- Values appended by a [`formdata`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event) event listener are now submitted. (by @kmmbvnr)

- A form-associated custom element is now also [watched](/up.watch), [validated](/validation), [switched](/switching-form-state) and [disabled](/disabling-forms), if it [exposes its state to a script](/custom-form-fields#contract).

- A new guide explains the [patterns for building a custom form field](/custom-form-fields).

- A `formdata` listener affects what Unpoly *sends*, not what it *watches*. See [`formdata` listeners](/custom-form-fields#formdata).

- A form-associated custom element that never calls `setFormValue()` submits no value, even when it is listed in `up.form.config.fieldSelectors`.

- ⚠️ A form containing an `<input type="file">` is now submitted as `multipart/form-data` even when no file is selected, because the browser's form-data algorithm produces an entry for every file input.

- ⚠️ An `<input type="image">` used as the submit button now contributes its `name.x` and `name.y` coordinates rather than its `[value]`, matching a native form submission.

- ⚠️ A `<button type="reset">` or `<input type="reset">` with a `[name]` is no longer treated as a form field, so it contributes no param to submissions, validations or watched values — matching a native form submission. It is still disabled by [`[up-disable]`](/up-submit#up-disable).

- When an overlay is closed by submitting a form with `[up-accept]` or `[up-dismiss]`, the [result value](/closing-overlays#result-values) now also contains the `[name]` and `[value]` of the submit button the user pressed. Formerly it contained only the form's fields.

- ⚠️ `up.Params.fromForm()` now requires a `<form>` element. It used to accept any container, which `up.Params.fromContainer()` does.

- ⚠️ Params now arrive in the order the browser produces them: the form's own fields in tree order, then values appended by a `formdata` listener, then controls that only Unpoly knows about (custom elements listed in `up.form.config.fieldSelectors`). In particular a submit button's `[name]` and `[value]` now appear at the button's position in the form, rather than after the form's `[up-params]`.

- `up.Params.fromForm()` now takes a `{ submitButton }` option, and assumes the form's first submit button when it is omitted. Pass `false` to submit no button at all. A button that the browser associates with a different form is ignored rather than crashing.

- `up.Params.fromForm()` ignores an `{ includeDisabled }` option. The browser's algorithm never includes a disabled control. The option still works with `up.Params.fromContainer()`, which is what form watching uses.

- ⚠️ Unpoly now throws an error when a field uses a `[form]` attribute to associate with a form in another [layer](/up.layer). The browser resolves such an attribute by document order and ignores layers, so it would submit one layer's field with another layer's form. If you render the same page into an overlay and it uses `[form]`, either give the form a unique `[id]` per layer, or move the field inside the form. Two forms sharing an `[id]` within a single layer are unaffected.

- ⚠️ A field inside a `<fieldset disabled>` is no longer submitted or validated, matching a native form submission. It is still reported by [watchers](/up.watch) and [`[up-switch]`](/switching-form-state).

- A custom control that exposes a `{ name }` but no readable `{ value }` no longer contributes an `undefined` param when watched.

- [Disabling a form](/disabling-forms) now also disables a form-associated custom element.

- The requirements for a [custom form field](/custom-form-fields#contract) are relaxed. A `value` getter is the only thing a custom control must provide.

- ⚠️ When Unpoly disables a custom control that exposes no `{ disabled }` property, it now sets the control's `[disabled]` attribute instead of assigning the property.

- ⚠️ A validation request no longer sends the params of the form's first submit button, and no longer honors that button's `[formaction]`, `[formmethod]`, `[up-params]` or `[up-headers]`. Nothing pressed the button, so only the `<form>` element decides where a validation goes.

- ⚠️ A `click` event dispatched by a script is no longer passed to [`up.on()`](/up.on) callbacks when the element carries a `[disabled]` attribute, even if the platform cannot disable that kind of element. Formerly only a `{ disabled }` property had this effect.

- ⚠️ When Unpoly [focuses](/focus) a form-associated custom element, it now assigns `.up-focus-visible` instead of `.up-focus-hidden`, even when the user interacted with a mouse or touch. `up.viewport.config.autoFocusVisible` shows a [focus ring](/focus-visibility) for every [field](/up.form.config#config.fieldSelectors), and such an element is now a field.

- `up.form.config.genericButtonSelectors` was renamed to `up.form.config.anyButtonSelectors` and now matches every kind of button, including submit and reset buttons. Unpoly uses it to disable a form's buttons while the form is submitting. The old name still works with [`unpoly-migrate.js`](/changes/upgrading).

import { teeToLogFile, LOG_FILE } from '../tooling/runner/terminal/tee.mjs'

const log = teeToLogFile()

const code = await runDev(process.argv.slice(2), process.env)

if (code === 1 || code === 2) console.error(`Full output: ${LOG_FILE}`)

await log.close()

#!/usr/bin/env node

import path from 'node:path'

import { updateGuides, guidesMissingToc, GUIDE_DIR } from '../tooling/toc.mjs'

const check = process.argv.includes('--check')

const relative = (file) => path.relative(process.cwd(), file)

const stale = updateGuides(undefined, { write: !check })

const missing = guidesMissingToc()

for (const file of stale) console.log(`${check ? 'stale' : 'updated'}: ${relative(file)}`)

for (const file of missing) console.log(`no TOC, but long enough to want one: ${relative(file)}`)

if (!stale.length && !missing.length) console.log(`All TOCs in ${relative(GUIDE_DIR)} are current.`)

if (check && (stale.length || missing.length)) {

console.error('Run `bin/update-contributing-tocs` to regenerate.')

process.exit(1)

Where code lives in this repository and why: the directory layout, the `window.up` global,

which module owns which topic, how a module is structured internally, and where to find the

specs for a given file.

- [Directory structure](#directory-structure)

- [Where to find a module's specs](#where-to-find-a-modules-specs)

- [Implementation plans](#implementation-plans)

- [Architecture](#architecture)

- [Not an ESM module](#not-an-esm-module)

- [Responsibilities](#responsibilities)

- [Main module pattern](#main-module-pattern)

- [Entry points and optional bundles](#entry-points-and-optional-bundles)

A change worth more than one commit is worth a written plan first: what was decided,

what was ruled out and why, and the sequence of commits it will take. Plans go in

`docs/plans/`, which is gitignored except for its `.gitkeep`.

A plan is a working note, not a deliverable. Keeping it out of the history means it

never reaches a reviewer, while still surviving the branch switches and rebases that a

long-lived branch goes through.

Name the file after the change it plans — the request, the feature or the pull request —

so that a directory listing reads as an index:

How Unpoly's own source is written: no types, no dependencies, no jQuery, and a real concern

for byte count. Some of these rules are enforced by ESLint (`bin/lint`), most are not.

We sometimes accept a suboptimal pattern because it saves bytes. Only bytes a minifier

can't recover, though — see [Leave it to the minifier](#leave-it-to-the-minifier).

We ship a minified build, and apps bundle Unpoly through their own minifier. Terser

already collapses branches into conditional expressions and rewrites control flow to

return early. Hand-writing those transformations saves nothing, and the version we have

to read and maintain for years is the unminified one.

- **Don't chain ternaries.** A single ternary for a genuinely binary choice is fine. A

chain of them standing in for `if` / `else if` / `else` is not: it reads as a puzzle,

and the minifier produces the same output from the readable form.

- **Early returns are for guards.** Return early to reject a missing argument, or an

element we don't handle, before the real work starts. Don't restructure a function

body into early returns just to avoid an `else`.

The same reasoning applies to any other trick whose only benefit is fewer characters.

Shorten code by removing work or reusing a helper, not by compressing its syntax.

How we write commits and what happens to them: the module prefix every subject carries, what

CI runs when you open a pull request, and what an agent must ask before committing.

Which browsers and language features Unpoly can rely on, and what we do instead of breaking a

public API: a polyfill in `unpoly-migrate.js` rather than a major version bump.