@synopackageland/ui 0.17.12 → 0.17.14

package/docs/callout.md

@@ -11,6 +11,20 @@ has its own component, and none of them is a full-width banner.
 | A risk or a limit of a feature | `<Callout variant="inline">` | One short sentence; longer text in `#details` behind "Learn more", or a link. |
 | A failure the user has to know about now, outside the page | `Notification` / `MessageBox` | See their docs. |
 
+## Closing
+
+A Callout is dismissible by default: a 24px ✕ in the top-right corner,
+drawn in the tone, labelled "Close" (`closeLabel`) and reached with Tab.
+Closing hides that callout and emits `close`. It comes back by itself when
+what it says changes: its tone, title, `code` or rendered text (a new error
+message shows again), or `dismissKey` when the App names the condition
+itself. A dismissal lasts while the component is mounted; it is not stored.
+
+Set `:dismissible="false"` only for a state that must stay in view until it
+is resolved, such as a setup step the App cannot work without. Never hide the
+only way to an action behind a dismissible callout without another way to it
+on the page.
+
 ## The look
 
 A Callout and a Toast share one look: a raised surface in the page's neutral
@@ -76,7 +90,7 @@ Two earlier looks were rejected:
 - **Message**: one line on why it matters or what happens next: "Share links
   keep using the old address". Do not explain the steps; the action does them.
 - **Action**: one button (`Button size="sm"`, drawn as a capsule), or a `Link` when it leaves the
-  app. Two only when the second is "Later" and the Callout cannot be closed.
+  app. Two only when the second is "Later" and the Callout is not dismissible.
   The button label names what it does: "Apply nas.example.com", not "OK".
 - **Risk notes**: one sentence. Put the explanation in `#details`:
 
@@ -114,10 +128,10 @@ Two earlier looks were rejected:
 | `#actions` | One action, at the end of the message |
 | `#details` + `v-model:expanded` | Longer text behind a "Learn more" toggle (`moreLabel`, `lessLabel`) |
 | `code` | A machine error code, shown quieter after the message |
-| `closable`, `closeLabel`, `@close` | A close button for a message the user may dismiss |
+| `dismissible` (default `true`), `dismissKey`, `closeLabel`, `@close` | The close button; the callout returns when its text or `dismissKey` changes. `false` only for a state that must stay in view |
 | `fill` | Span the container instead of stopping at 720px |
 
-Theme hooks (`data-tone`, `data-variant`, `data-fill`, the `data-ui-callout-*`
+Theme hooks (`data-tone`, `data-variant`, `data-fill`, `data-dismissible`, the `data-ui-callout-*`
 parts) and tokens (`--ui-callout-max-width`, `--ui-callout-radius`,
 `--ui-callout-glow`, `--ui-callout-shadow`, which Toast shares) are listed in
 [theme hooks](theme-hooks.md).

package/docs/layout-rules.md

@@ -18,7 +18,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 - [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.
 - 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.
+- 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.
 - 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.
@@ -29,24 +29,46 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 - Labels sit above their controls (`Form direction="vertical"`), except in short DSM-style dialogs.
 - Size a field by its content: number fields are 128px; text fields use `fieldWidth`. Put two short fields side by side rather than stretching one across the page.
 - A checkbox's text sits on the same line as its box. Do not apply `display: grid` to `label` in App CSS; `Checkbox` renders its own label.
+- For 2–4 mutually exclusive settings, use `RadioGroup` (vertical by default, `orientation="horizontal"` when labels fit). A checkbox enables an independent option; a switch turns a feature on or off immediately. Keep the circular radio with a dot, square checkbox with a tick, and pill switch with a moving thumb.
+- Reserve `SegmentControl` for toolbar view switching: its selected item is a primary-filled capsule. `variant="sheet"` and `SectionTabs` are navigation tabs. Do not use either as a form value selector.
 - Choices side by side are 34px apart (`--ui-choice-inline-gap`, DSM's Task Scheduler) and share one top whether checked or not. For a set of checkboxes use `CheckboxGroup` (`orientation="horizontal"` for a row, `v-model` an array of values), as `RadioGroup` for one choice; Checkboxes written one after another get the same gap. Do not add margins between them.
 - A password field has a show/hide toggle; `Input type="password"` adds it.
 - Show a NAS path with `PathDisplay`, not a read-only input. It truncates from the start, shows the full path in a tooltip when it is cut, and offers copy. In a table cell use `display="name"`: the folder's name on one line, the full path always in its tooltip, copy still copies the full path.
 
+### Settings choice example
+
+```vue
+<FormItem label="Domain and LDAP people">
+  <RadioGroup
+    v-model="directoryReadMode"
+    :options="[
+      { value: 'lookup', label: 'When someone looks them up' },
+      { value: 'never', label: 'Not read' },
+    ]"
+  />
+</FormItem>
+```
+
+The setting is a form value, saved with the page's Apply action. It does not navigate between views.
+
 ## Settings pages
 
+- Use `<SectionTabs fill keep-mounted>` for settings with local unsaved drafts. `keep-mounted` mounts every supplied item panel immediately and hides inactive panels with `v-show`; their effects stay active. Without it, switching tabs unmounts the previous panel. `fill` alone only controls layout. Keep persistent business data and background work in the app when needed.
+- `SettingsPage` spaces direct sibling `SettingsSection`s by `--ui-space-6` (24px); place them directly in its default slot without a `Space` wrapper. `Fieldset` keeps its own DSM spacing.
 - A settings page has one label column. `FormItem` (horizontal), `SettingsRow` and `KeyValueRow` share `--ui-label-column` (`--ui-label-width`, at most 40% of a narrow row) and `--ui-label-gap`, so SDK panels and App rows line up; `FormActions inset` starts at the same edge. Labels and `KeyValueRow` values break between words, not inside one. Do not pass a different `labelWidth` per section.
 - Labels sit left in the column, as on DSM's own settings pages: the eye runs down one edge, and a long label wraps instead of pushing the value.
 - Colours are fixed by role: section title `--ui-text` semibold 14px, label and value `--ui-text`, help text `--ui-text-secondary` 12px.
 - A `SettingsRow` with a `description` aligns its label with the control's first line, not the middle of control and description.
 - A row that is only a button: give it a `SettingsRow` label when it acts on one thing, or put it in the section `#footer`. Inside a horizontal form, use `FormActions inset` so the button starts on the value edge.
-- A DSM-native settings page reads its structure from indentation and spacing (Control Panel > Network > General). Each section is a `Fieldset`: a blue title with a chevron (up while open) over a dashed divider across the whole width, collapsible. Sections one after another keep a 20px gap. A one-line explanation of the section is the Fieldset's `description`, directly under the title and across the whole width, not in the label column. Fields are one `Form` with one `labelWidth` (or the theme's column) and `FormItem`s; one `Form` may hold several Fieldsets.
+- A DSM-native settings page reads its structure from indentation and spacing (Control Panel > Security; measurements in [dsm-native-metrics.md](dsm-native-metrics.md#settings-page-control-panel--security-network)). Each section is a `Fieldset`: a 15px blue title over a dashed divider across the whole width, collapsible and expanded by default, with a chevron pointing up when expanded and down when collapsed (as Control Panel > Network). Use `:collapsible="false"` for a fixed section without a chevron (as Control Panel > Security). The title text and the fields start 8px in; the next section's title follows 8px after the body. A one-line explanation of the section is the Fieldset's `description`, directly under the title and across the whole width, not in the label column. Fields are one `Form` with one `labelWidth` (or the theme's column) and `FormItem`s; one `Form` may hold several Fieldsets.
+- A checkbox option is a `FormItem :label="false"` with a `Checkbox`: the box sits on the section's left edge and its help text (`description`) is a line of its own under the label text. Do not put a label beside a checkbox or a switch that already says what it does.
 - A read-only value is a `FormItem` with `text-only`: plain text in the control column, level with its label. A button that acts on it (Edit) goes in the item's `#after` slot and follows the field column.
 - Options that only matter while a checkbox or switch is on go in a `FormGroup` right after it, with `:disabled="!on"`. The parent is a `FormItem :label="false"`, so it starts at the section's left edge. The group indents one 28px step, disables and dims every control inside, and the labels inside give up the indent so the controls stay on the form's column, as DSM draws them. Nest a `FormGroup` for a second level. Do not indent with your own padding or disable each child by hand.
 - A section button such as Advanced Settings goes inside the `FormGroup` it belongs to, after its fields, as a plain `Button`: it starts on the group's indent and follows the group's disabled state. Do not centre it or put it in the label column.
 - A unit goes in the `Input`'s `unit` (or `#unit` slot): `<Input v-model="timeout" type="number" unit="s" />` puts "s" right after the field. Do not put units in the FormItem's `#after` slot, which starts after the whole field column.
 - Explanation is a short `description` under its field. A note is a `FormNote`: one remark reads "Note: …" on one line, two or more `items` become a list under the heading. Put it under the field it is about with `inset` (it starts on the field column), or at the end of the section without. Facts to read or copy (addresses, paths) go in an `InfoBox`. A warning or an error is a `Callout`. Do not write long full-width paragraphs or a separate "Note:" heading between fields.
-- A settings page has one Apply. On a page or window, put Reset then Apply in the footer (`Footbar`, `AppActionBar`), as Control Panel does; inside a form that ends the page, use `FormActions inset`. Do not put a Save between the fields of a section.
+- A settings page has one Apply. Put Reset then Apply in `SettingsPage`'s `#footer`, at the bottom-right, as Control Panel does. Keep the footer while the page has settings to apply, so nothing moves when a draft changes. Do not put a Save between the fields of a section.
+- A button that belongs to a field (Allowed websites, Trusted Proxies, Advanced Settings) is a grey `Button variant="secondary"` in the flow: in the `FormGroup` it depends on, after the field it acts on (`#after`), or under the section's description.
 
 ## Tables
 
@@ -63,7 +85,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 ## Fields
 
 - A field with buttons acting on it (a URL and its Install button) goes in `InputGroup`: one line, 8px gap, the field takes the room left.
-- Stack page sections with `Space direction="column"` and a pixel `spacing`; add `wrap` to a row of tags or buttons that may run out of room.
+- Outside `SettingsPage`, stack page sections with `Space direction="column"` and a pixel `spacing`; add `wrap` to a row of tags or buttons that may run out of room.
 
 ## Numbers and times
 
@@ -85,6 +107,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 ## Page
 
 - `PageHeader` sticks to the top while the content scrolls.
-- A list page whose grid pages its rows (downloads, tasks, logs) uses `AppLayout height="fill"` and `PageContent height="fill"`: the header, tabs and toolbar stay, the DataGrid (the last child) fills the height left and scrolls its rows, and its pager stays in view. Do not let the whole page scroll past a 50-row page to reach the pager.
+- A settings page with tabs is `SectionTabs fill` with one `SettingsPage` per panel, in a container with a height (a window, `AppLayout height="fill"`): 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.
+- `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.

package/package.json

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