@synopackageland/ui 0.14.6 → 0.14.7

package/docs/button-policy.md

@@ -0,0 +1,62 @@
+# Button policy
+
+DSM 7 draws two button shapes. A **capsule** belongs to the bar that closes a
+window, dialog or form: OK / Cancel, Apply / Reset, a wizard's Next, a
+confirmation's Delete. Every other button is a **tool button** with the 3px
+control radius: toolbars, page headers, sections, rows, fields. The components
+pick the shape from where a button sits; an App chooses only the variant.
+
+![Each case in the light theme](screenshots/button-policy-light.png)
+
+Measured on DSM 7.4 (Control Panel, Package Center, File Station): every button
+is 28px high. A footer capsule is at least 80px wide, 120px for the blue or red
+one; a tool button sizes to its label with 13px each side. Colours and states
+are in [dsm-native-metrics.md](dsm-native-metrics.md).
+
+## Where each button goes
+
+| Place | Component | Shape | Variants |
+| --- | --- | --- | --- |
+| Dialog, sheet or wizard footer | `Dialog`, `Sheet`, `Wizard` `#footer` | capsule | Cancel `secondary`, then OK `primary` |
+| Confirmation of a destructive action | `Dialog` `#footer` | capsule | Cancel `secondary`, then Delete `danger` |
+| Form or window footer | `FormActions`, `AppActionBar`, `Footbar`, `Panel` `#fbar` | capsule | Reset `secondary`, then Apply `primary` |
+| Notification | `Notification` `confirm` / `cancel` | capsule | Cancel `secondary`, then the action `primary` |
+| Toolbar | `AppToolbar`, a row above a list | tool | `secondary`; `SplitButton` for Create and its variants |
+| Page header | `PageHeader` `#actions` | tool | one refresh `IconButton` per page |
+| Section or card | `SettingsSection` / `Card` body, `#actions`, `#footer` | tool | `secondary`; a Save / Cancel row there goes in `FormActions` |
+| Beside a field | `InputGroup` | tool | `secondary` (Open, Copy, Test) |
+| Row of a list or grid | `ListItem` `#actions`, an `actions` column | tool | `IconButton` with a `label` |
+| Navigation, help, external page | `Link` | text link | not a button |
+
+## Rules
+
+1. A capsule only ends something: it closes a dialog, applies a form or moves a
+   wizard. An action that stays on the page, such as Disable this connection,
+   Open or Check again, is a tool button even in a section footer.
+2. One main action per footer: one `primary`, or one `danger` for a
+   destructive confirmation. The others are `secondary`.
+3. The main action goes last, at the right edge: Cancel then OK, Reset then
+   Apply. A footer is right-aligned, except `FormActions` in a page form, which
+   starts at the field edge.
+4. Toolbar and row actions are grey, Delete too. Red appears in the dialog that
+   confirms the deletion, not on the button that opens it.
+5. Inside a page, use `primary` only for the one step that unblocks the page,
+   such as Sign in in a callout; at most one per section.
+6. Keep the default size. `sm` and `lg` exist for dense rows and touch layouts;
+   neighbouring buttons share one size.
+7. A disabled button keeps its shape and place. Say why next to it.
+8. An icon-only action is an `IconButton` with a `label`; it shows as its
+   tooltip and names the button for screen readers.
+9. Labels are verbs, without a closing period: Apply, Disable this connection.
+
+## What the components do
+
+- A Button takes its shape from the closest footer: inside `Dialog`, `Sheet`
+  and `Wizard` footers, `FormActions`, `AppActionBar`, `Footbar`, a `Panel`
+  `#fbar` or a `Notification` it is a capsule, everywhere else a tool button.
+  Set `kind="tool"` on one footer button to keep it a tool button (Help, say).
+- In development, a Button warns in the console when `kind="action"` is set
+  outside a footer, when a footer has two main actions, or when the main action
+  is not last. Production builds do not check.
+
+![Each case in the dark theme, in a DSM window](screenshots/button-policy-dark.png)

package/docs/layout-rules.md

@@ -15,8 +15,9 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 
 ## Actions
 
+- [Button policy](button-policy.md) says which button goes where: its shape, variant and order.
 - Buttons that belong together sit in one row with an 8px gap: `FormActions` in a form, the `#footer` slot in a section or card.
-- Footer rows draw capsule `action` buttons without a `kind`: `FormActions`, `Footbar`, `AppActionBar`, and the footers of `Dialog`, `Wizard`, `Sheet`, `SettingsSection`, `Card` and `Panel` (`#fbar`). `kind="tool"` opts one button out. Header actions and content stay `tool` buttons.
+- 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`.
 - On a settings form longer than the window, `FormActions sticky` keeps Apply in view at the bottom over a divider. 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.
 - A disabled primary button keeps readable text. Put the reason next to it, such as "Enter the password to confirm."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.14.6",
+  "version": "0.14.7",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -15,6 +15,7 @@
     "README.md",
     "docs/adaptive-layout.md",
     "docs/app-local-modal.md",
+    "docs/button-policy.md",
     "docs/color-system.md",
     "docs/component-defaults-0.5.7.md",
     "docs/json-ui.md",