Skip to content

PublishVersion

C-43 · Components · Versioning

All elements · PublishVersion on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for PublishVersion.

PublishVersion

C-43WCAG 2.2 AA · Passed

The body of the Publish version dialog: the version it will create (2.3 → 3.0), what happens to the previous published version, warnings, and a required comment. Opened from the document screen and from File → Publish version in the editor; both end in POST /api/v2/documents/{id}/publish.

Axis / element Values
__change · __from · __arrow · __to · __caption · __summary 2.3 → 3.0, read as “From version 2.3 to version 3.0”
__warnings .qf-banners: checked out by someone else (error, blocks), under legal hold (warning, publishing is allowed), open in the editor (info); each banner present on open is named in the dialog's aria-describedby after __change, so it is read when the dialog opens
__comment a required .qf-field with a multiline control; data-invalid + aria-invalid when empty on submit
[data-publish-submit] · aria-disabled the footer's Publish version; disabled with aria-describedby naming the blocking warning
Open the dialog
Body, inline (empty comment submitted)
Publish version

DraftFrom version 2.3 Publishedto version 3.0 Version 2.0 becomes superseded.

Enter a comment. It says what changed in this version.

Publish version

DraftFrom version 2.3 Publishedto version 3.0 Version 2.0 becomes superseded. Drafts 2.1 to 2.3 are kept for 90 days.

Say what changed. Everyone who opens the version history sees it.

Publish version

DraftFrom version 2.3 Publishedto version 3.0 Version 2.0 becomes superseded.

Open in the editor
Mark Rivera is editing. The editor publishes what is open there, including changes not yet in a checkpoint.
Say what changed. Everyone who opens the version history sees it.

Publish version

DraftFrom version 2.3 Publishedto version 3.0

Checked out by Mark Rivera
You can publish when Mark checks the document in, or after a records manager cancels the checkout.
Say what changed. Everyone who opens the version history sees it.

Guidance

When to use

  • Use it in the Publish version dialog, opened from the document screen or from File → Publish version in the editor.
  • Show the version it creates in __change (Draft 2.3 → Published 3.0) and what happens to the previous published version in __summary.
  • Require a comment (__comment); it is stored on the version and shown in the version history.
  • Put conditions in __warnings as Banners: checked out by someone else (error, Publish version is disabled), under legal hold (warning, publishing is allowed), open in the editor (info, the editor publishes).

When to consider something else

  • For a checkpoint, nothing is asked: the editor makes one when the session ends. Tell the user with a Toast if at all. See Toast.
  • For an approval workflow before publishing, use a Form in a task; this dialog publishes directly. See Form.
  • To confirm a destructive version action, such as deleting a draft, use a Confirmation. See Confirmation.

Usability

Do
  • Name the button Publish version, not Save or OK.
  • Compute the target number from the server's latest version (major + 1, minor 0) and show both numbers.
  • When the document is checked out by someone else, name the person and say how it gets unblocked.
  • After success, close the dialog, show the new version in the history and announce it ("Version 3.0 published").
Don’t
  • Don't disable Publish version for an empty comment; let it be pressed and explain the error at the field.
  • Don't treat a legal hold as an error: holds stop deletion, not new versions.
  • Don't wait for the publish answer to say the document is held: warn in __warnings before Publish version is pressed (Under legal hold: you can publish; no version of this document can be deleted or pruned while it is held), and don't repeat it in the success toast.
  • Don't publish from the document screen while the editor holds the document; hand the request to the editor (409 EDIT_SESSION_OPEN).

Accessibility

Keyboard

PublishVersion keyboard
Keys Action
Tab / Shift+Tab Moves through the comment, Cancel and Publish version; focus stays inside the modal dialog.
Enter or Space on Publish version Validates; an empty comment sets aria-invalid, changes the helper to the error and moves focus to the comment.
Escape Closes the dialog and returns focus to the control that opened it.

Roles and names

  • The dialog is a native <dialog> with aria-labelledby on its title and aria-describedby on __change followed by the id of each warning banner present when it opens (the legal-hold warning among them), so they are read with the dialog.
  • __arrow is aria-hidden; visually hidden "From version" and "to version" make __change read as a sentence.
  • The comment is a labelled <textarea> with required, aria-required and aria-describedby on its helper.
  • A blocked Publish version uses aria-disabled="true" (it stays focusable) and aria-describedby pointing at the blocking banner.

Focus

  • On open, focus goes to the comment field.
  • On error, focus goes to the comment; on a server conflict, to the new error banner (role alert).

Other requirements

  • Warnings present when the dialog opens are static banners (no live role); a conflict returned by the server after Publish version is added with role="alert" (4.1.3).
  • The dialog reflows at 320px: __change wraps under itself (1.4.10).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

PublishVersion test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (3 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- publish-version --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

PublishVersion package
Source css/classic/components/versions.css
Specimens also use Banner · Box · Button · Card · Chip · Control · Field · Icon · Overlay · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

PublishVersion latest updates
Date Version Breaking Description
2026-10-10 0.1 No Legal hold before publishing: the Publish version dialog's Under legal hold banner is named in the dialog's aria-describedby so it is read on open (You can publish. No version of this document can be deleted or pruned while it is held.); new .qf-hold-badge (a warning Chip with the gavel and On hold) for a pane header's .qf-object__meta and the new .qf-version-history__head title row, both skins (QF-10830)
2026-10-08 0.1 No PublishVersion (.qf-publish): the Publish version dialog body with the version change (2.3 → 3.0), checked-out / legal-hold / open-in-editor warnings and a required comment (QF-10840)

All release notes