@synopackageland/ui 0.19.10 → 0.20.0

package/docs/layout-rules.md

@@ -19,7 +19,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 - Buttons that belong together sit in one row with an 8px gap: `FormActions` in a form, the `#footer` slot in a section or card.
 - Only the bar that closes a dialog or form draws capsule `action` buttons, without a `kind`: `FormActions`, `Footbar`, `AppActionBar`, a `Notification`'s actions, and the footers of `Dialog`, `Wizard`, `Sheet` and `Panel` (`#fbar`), with the main action last. `kind="tool"` opts one button out. A `SettingsSection` or `Card` footer, header actions and content stay `tool` buttons; put a section's Save / Cancel in `FormActions`.
 - A settings tab's Reset / Apply go in `SettingsPage`'s `#footer`: it stays at the bottom over a divider while only the sections scroll. Do not write your own sticky footer.
-- Each page has one refresh, in the page header. Panels expose `refresh()` for it instead of their own button.
+- Each page has one refresh, with the page's other buttons: in the bar above the page (the SDK `AppShell`'s `#actions`), or in `PageHeader` where a page draws one. Panels expose `refresh()` for it instead of their own button.
 - A disabled primary button keeps readable text. Put the reason next to it, such as "Enter the password to confirm."
 - Danger actions sit apart from the rest: the explanation comes first, then the button, or a confirm dialog.
 - Return the promise from a `Button` or `IconButton` click handler (`@click="save"` with an `async save`): the button shows a spinner, keeps its width and ignores further clicks until the promise settles. Use the `loading` prop only for work the button did not start.
@@ -108,8 +108,19 @@ The setting is a form value, saved with the page's Apply action. It does not nav
 
 ## Page
 
-- `PageHeader` sticks to the top while the content scrolls.
-- A settings page with tabs is `SectionTabs fill` with one `SettingsPage` per panel, in a container with a height (a window, `AppLayout height="fill"`; in a flex column it takes the height its siblings leave, with no override): the tab strip stays at the top, the footer at the bottom, and only the sections scroll. Without a height (a phone page), the page scrolls, the strip sticks to the top and the footer to the bottom, above the safe area. Under 520px of row width labels stack over their controls.
+- A page under a sidebar draws no title: the selected sidebar item names it. Keep a visually hidden `h1` with the page's name for screen readers, and put the page's buttons in a bar above the page (`AppToolbar` `#actions`). The SDK `AppShell` does both by itself; its `header: true` shows `PageHeader` instead. Pages have no subtitle.
+- Only the content scrolls. The navigation, the bar above the page, a page's tab strip and a settings footer stay in place, and no scrollbar runs past them. On a phone (640px and narrower) the page has one scrolling area, nothing scrolls sideways, and the footer stays in view.
+- Where a page draws `PageHeader`, it sticks to the top while the content scrolls.
+- A settings page with tabs is `SectionTabs fill` with one `SettingsPage` per panel, in a container with a height (a window, `AppLayout height="fill"` with `PageContent height="fill"`, or a page of the SDK `AppShell`, which fills by itself when it shows one): the tab strip stays at the top, the footer at the bottom edge, and only the sections scroll. A tab that is not a `SettingsPage` scrolls under the strip. The height passes through the App's own wrapper elements; do not add CSS to pass it on. A `SettingsPage` without tabs behaves the same, and its footer sits on the bottom edge with no space under it. Without a height, the page scrolls, the strip sticks to the top and the footer to the bottom, above the safe area. Under 520px of row width labels stack over their controls.
 - `DataGrid` and `DataTable` fill the height their flex-column container leaves by default (`fill`), as DSM's lists do: the header row stays, the rows scroll inside the table, and a DataGrid's footer ("3 items", the pager) sits at the container's bottom whatever the row count. A list page uses `AppLayout height="fill"` and `PageContent height="fill"` so the table, its last child, gets that height. Where the page itself scrolls (a phone), the footer sticks to the bottom of the viewport above the safe area. Give a short table inside a form, a settings section or a dialog `:fill="false"`: it is as tall as its rows. Do not let the whole page scroll past a 50-row page to reach the pager.
 - `PageHeader` keeps the title and its `meta` slot (an info button, a chip) on one line. Actions that would crowd the title move under it, at the right edge; a title longer than its line ends in "…" and shows in full on hover.
 - `EmptyState` fills the remaining height and centres its content. Do not add footnotes below it.
+
+## Moving an existing App
+
+An App written for the older layout (a title on every page, the whole page scrolling) moves to these rules as follows:
+
+- With the SDK `AppShell`, a page that should keep its visible title sets `header: true`. Drop page descriptions; they are not shown.
+- Remove a hidden `h1` you added beside `header: false` and buttons you moved into your own `AppToolbar`: the shell names the page and puts `#actions` in the bar above it.
+- Remove CSS that passed the height to a settings page through your wrappers (such as `.integration-app > [data-page] { flex: 1 1 0%; min-height: 0 }` and the same for its child) and CSS that removed the space under a settings footer (`padding-bottom: 0` on the page content).
+- Remove `fill: true` from SDK pages whose content is a `SettingsPage` or `SectionTabs fill`; keep it where the content scrolls itself, such as a split view or a table paged by height.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.19.10",
+  "version": "0.20.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",