Overlays: where a record opens
A record picked from a list opens in place, over the list, never as a jump to another page.
The rule
Section titled “The rule”- Size decides the layer. A medium or large record (a contact, a task, an invoice, a purchase
document, a webhook, a recurring invoice) opens in the side sheet,
Ui:Sheetmd (640 px, resizable). A small record (a label, a number series, a person, a bank account, the attempts of a webhook delivery, the history of a send, an iDoklad run) opens in a modalUi:Dialog. Places you work in stay pages: they are navigation, not records. These are a project and its board, an import and the iDoklad wizard, and a firm, a settings hub of tabs (details, invoicing, bank, e-mail) that a modal is not for. - The header of the sheet is one row, as a page header is: the title at the page-title size,
cut with an ellipsis (the full text in its
title), then the same actions as the record’s page header in the small size, a divider, a Full screen toggle (the width of the content panel, remembered per browser), Open as page (the record’s URL) and Close. On a phone the actions take a row of their own under the title. A record sizes its action buttons withrecord_action_size. In every page and sheet header the primary action comes first and the “⋯” menu last, after the secondary buttons:[Edit] [⋯] | [full screen] [open as page] [×]. Ui:MoreActions renders that order (itsprimaryblock), so a header’s actions are that one component, andtests/Ui/HeaderActionOrderTest.phpfails when anything follows it or a bare Ui:Menu stands in. - Edit happens in place. Edit loads the form into the same surface (sheet, dialog or page); Save and Cancel go back to the detail there. A document with lines (an invoice, a recurring invoice, a purchase document) widens its sheet to full screen while it is edited.
- The URL is the record’s. While a record is open its URL is in the address bar; Back closes it and gives the list its URL back. A reload, a new tab, a bookmark or a browser without JavaScript gets the record’s page at the same URL.
- On a phone the sheet fills the screen and Back closes it.
- Nesting. A dialog may open over a sheet (a confirmation, a small form); a sheet never opens over a dialog; two levels at most.
- Moving between records with the keyboard (j/k) is not part of the rule.
How a screen follows it
Section titled “How a screen follows it”- A list row says where its record opens:
opens: 'sheet'(the default),'dialog'or'page'on aUi:DataTablerow; aplainrow leaves Turbo, so it is a page. The row’s link getsdata-sheetordata-dialog, and the hosts inlayout/_dialogs.html.twigload it. A row whose target is a place to work in saysopens: 'page'. - A small record whose only view is its form (a label, a series, a person, a bank account) is a
dialog form (
layout/dialog.html.twigwhenin_dialog(), the page otherwise): the row opens it in the modal, Save closes it and the list loads again. - The host asks with the header
X-Foresi-Dialog:sheetfor the side sheet,1for a dialog.overlay()in Twig answerssheet,dialogornull(the page);in_dialog()is true for both. - The detail and its edit form extend
layout/record.html.twigonce and fill the blocks of the page (title,actions,content). Setrecord_overlaytodialogfor a small record andrecord_fieldsto true for a form. Setrecord_fullto true for a form with lines: the sheet fills the content panel while it shows and keeps the width it remembers for the next record; the Full screen toggle or the grip ends it. Asked by its own layer, the template is the overlay; otherwise it is the page. - Inside a record, a link in a
data-in-placearea (Edit, Cancel, the tabs) and the answer of a form load in the same host. A form that saves answers with a redirect, as on the page; the host loads its target in place and loads the list under it again once it closes. - A record whose title changes where it is read (a task) gives
record_title_edit, thetitleEditof its page header: the sheet’s header shows the same inline field, and the focus starts on the title. - The same record loaded again after a change (a property saved, a comment added) keeps where its body was scrolled and the focus on the field that changed. A dialog that finishes over a record in the sheet (log time, a new subtask, sharing) shows what comes next in the sheet instead of a page.
- A form inside an overlay that asks before it posts uses
confirm-submit, notdata-turbo-confirm: the host sends the form itself, and holds back a submit that is prevented.
Sources
Section titled “Sources”- Shopify Polaris, Modal: a last resort, not for actions on the page; no modal launched from another — https://shopify.dev/docs/api/app-home/web-components/overlays/modal
- Shopify Polaris, Page: one primary action and up to three secondary ones in the header — https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/page. Polaris puts the primary action at the right edge; Foresi deliberately leads with it and ends the row with “⋯”.
- Material Design, Top app bar: the overflow menu at the far end of the bar; actions move into it from that end, so the most used one stays visible longest — https://m2.material.io/components/app-bars-top
- Atlassian, Confluence page actions: additional page actions under the “More actions” (ellipsis) menu at the top right of the page — https://developer.atlassian.com/cloud/confluence/extending-page-actions
- GitHub Primer PageHeader: the title, then the trailing actions on the same row; on narrow viewports they become items of an overflow button — https://primer.style/product/components/page-header/guidelines/
- Atlassian Drawer: a secondary task while staying on the page; focus to the first item on open, back to the trigger on close, Escape dismisses — https://atlassian.design/components/drawer/usage
- Atlassian Modal dialog: not for complex interactions or large tables; dialogs never trigger other dialogs — https://atlassian.design/components/modal-dialog/usage
- GitHub Primer Dialog: a right side sheet as a dialog position; up to two nested dialogs, Escape closes the top one; full screen on narrow viewports — https://primer.style/product/components/dialog/guidelines/
- Material Components, Side sheet: a modal side sheet has a scrim and handles Back — https://github.com/material-components/material-components-android/blob/master/docs/components/SideSheet.md
- W3C APG, Dialog (Modal): focus moves in, stays in, Escape closes, focus returns to the opener — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
- W3C APG, Button: a toggle button carries
aria-pressed— https://www.w3.org/WAI/ARIA/apg/patterns/button/ - Turbo Frames: a frame can advance the history; the application renders the target on a reload — https://turbo.hotwired.dev/handbook/frames
- NN/g, Modal and nonmodal dialogs: avoid modal dialogs for complex decisions — https://www.nngroup.com/articles/modal-nonmodal-dialog/