@synopackageland/ui 0.19.11 → 0.20.1

package/docs/adaptive-layout.md

@@ -132,7 +132,11 @@ import {
   with no card, border or outer margin around it. The area is white, unless the
   page holds a card (`Card`, `Surface`): then it is the page grey
   (`--ui-bg`, the web canvas) and the cards lift off it with a 1px frame and
-  `--ui-shadow-card`, as on DSM's own card pages. `surface="card"` always stays
+  `--ui-shadow-card`, as on DSM's own card pages. A list page stays white: a
+  page with a `DataGrid` on it (not inside a card) keeps the white area when a
+  `Surface` opens beside the list, such as a detail pane for the selected row;
+  the pane keeps its 1px border and takes no shadow, so selecting a row never
+  repaints the page. `surface="card"` always stays
   white. `surface="flat"` always takes the grey canvas, for multi-card
   dashboards. All three behave the same in the web, DSM-window and mobile
   presentations.

package/docs/app-local-modal.md

@@ -1,6 +1,6 @@
 # App-local modal
 
-Status: implemented in 0.4.0; the default since 0.6.0. `AppRoot` uses
+`AppRoot` uses
 `modal-scope="app"` unless you pass `modal-scope="document"`, which only a
 full-page web or Portal app should do: document mode locks `document.body`.
 
@@ -148,9 +148,9 @@ root and inside the active panel, or use the library's supported popup component
 
 Reka 2.10.5 is an exact development dependency, bundled into the UI library's
 ESM dist. It is no longer a consumer runtime dependency. Vue remains an external
-peer, and the bundled code uses that same Vue instance. Existing consumers get
-the body-style fix on rebuilding with 0.4.0 without a package-manager patch or
-app code change. Independent modality is opt-in.
+peer, and the bundled code uses that same Vue instance. Consumers receive the
+body-style fix by rebuilding, without a package-manager patch or app code change.
+Independent modality is the default.
 
 `build/reka-patches.json` records the SHA-256 of every original upstream ESM
 module plus exact before/after hunks. `build/rekaPatch.ts` verifies the installed

package/docs/callout.md

@@ -14,12 +14,46 @@ has its own component, and none of them is a full-width banner.
 
 ## Closing
 
-A Callout is dismissible by default: a 24px ✕ in the top-right corner,
+A Callout is dismissible by default: a 24px ✕ at the end of the line,
 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.
+Closing hides that callout and emits `close`. A closed callout is not drawn
+and takes no room: no empty line, no gap, no margin.
+
+**It stays closed.** The dismissal is stored in `localStorage` under
+`syno-pkg-land-ui:callout:<app>:<id>`, so the callout stays closed after a
+reload and when the user comes back to the page. `<app>` is the DSM package
+(from `/webman/3rdparty/<package>/`) or the page's host and directory. `<id>`
+is the callout's `dismissKey`; without one it is a hash of the page path,
+the tone and the text. Give every callout a stable `dismissKey` that names
+what it is about:
+
+```vue
+<Callout tone="info" dismiss-key="recycle-bin-empty-in-dsm">
+  Or empty it in DSM: Control Panel › Shared Folder › Edit › Recycle Bin
+</Callout>
+```
+
+**It comes back when what it says changes.** The stored value is a hash of
+the tone, title, `code` and rendered text, so the same callout with a new
+message (a new error, "97% full" after "92% full") shows again, with or
+without a `dismissKey`.
+
+**A `danger` callout is hidden for this page load only.** An error that is
+still there after a reload is worth seeing again; closing it only clears the
+page for now. Every other tone is remembered.
+
+**The page's info button brings it back.** A closed callout that is still on
+the page is listed in the page's one info button (ⓘ) at the start of the
+toolbar, or on the title line, under "Hidden notices", each with "Show
+again", which shows it and forgets the dismissal. Where the toolbar or title
+line already has an info button (a page's notes), the list is added to it;
+otherwise the first toolbar (`AppToolbar`) or page header (`PageHeader`)
+shows one while a callout is closed, and none when nothing is. There is
+never a second icon, wherever the App puts the callout.
+
+Storage is read and written inside `try`/`catch`: without it (a private
+window, blocked site data) a callout shows as usual, and closing it lasts for
+the page load.
 
 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
@@ -31,12 +65,15 @@ on the page.
 A Callout and a Toast share one look: a raised surface in the page's neutral
 colour (`--ui-surface-raised`), with no frame and no tinted fill. A 1px ring
 at 6% of the text colour and a soft shadow lift it off the page. The tone
-appears in three small places only:
+appears in two small places only:
 
-- a 1.5px light along the top edge, in the tone, fading out halfway across;
 - a faint glow of the tone (9%; 14% in the workbench dark theme) in the
   corner behind the icon;
-- the 18px icon.
+- the icon (16px in a Callout, 18px in a Toast).
+
+A Toast also has a 1.5px light along its top edge, in the tone, fading out
+halfway across. A Callout drops it: it stays on the page, where DSM draws its
+notes with no decoration.
 
 The title reads in the text colour at 600, and the message under it in the
 secondary text colour. Corners are 12px (`--ui-callout-radius`), rounder than
@@ -45,10 +82,19 @@ of them. Buttons in `#actions` and a toast's action are capsules. A Callout
 fades in and rises 6px when it appears, and a toast slides in; with reduced
 motion both appear at once.
 
-A Callout grows to 720px (`--ui-callout-max-width`) and stops there, so a
-wide page does not stretch it into a strip. `fill` makes it span the
-container. Actions sit at the end of the message while the width allows; on
-a narrow panel they move under the text.
+A Callout spans its container (block, `width: 100%`), so it lines up with
+the table or form under it. `--ui-callout-max-width` (none by default) caps
+it where a theme wants that; `fill` is no longer needed. Actions sit at the
+end of the message while the width allows; on a narrow panel they move under
+the text.
+
+One line is a form row high, 32px: 7px above and below an 18px line. The
+icon, the text, a small action button (pulled into the line, so it does not
+make it taller) and the ✕ are centred on it. A taller callout, a title and a
+message or wrapped text, centres the icon and the ✕ on the whole block
+rather than on its first line: a Callout has a title and at most one line,
+so the block stays short, and centring keeps the icon and the ✕ level with an
+action button, which first-line alignment would not.
 
 Contrast was measured on the surface, light and dark, in every tone: text at
 least 5.4:1, icons at least 3.3:1.
@@ -82,14 +128,6 @@ and without an action, light and dark, and on a settings page:
    neutral, still shows the tone at a glance, and reads as modern without a
    coloured box.
 
-Two earlier looks were rejected:
-
-- **0.14.9 and before**: full width, a 3px bar on the leading edge, a tinted
-  strip, and buttons stacked under the text. It read as a dated admin-tool
-  warning box.
-- **A first redesign**: a tinted fill with a thin tinted frame. It was still
-  a coloured box.
-
 ## Writing one
 
 - **No closing period.** Callout text (title, message, details, action
@@ -137,10 +175,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`); in a hint, the tooltip of the whole line (`moreLabel` is not used) |
 | `code` | A machine error code, shown quieter after the message |
-| `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 |
+| `dismissible` (default `true`), `dismissKey`, `closeLabel`, `@close` | The close button. Closing is remembered (a `danger` callout for this page load only) until the text changes; `dismissKey` is the callout's stable id within the App. `false` only for a state that must stay in view |
+| `fill` | Deprecated: a Callout spans its container by default |
 
 Theme hooks (`data-tone`, `data-variant`, `data-fill`, `data-dismissible`, the `data-ui-callout-*`
-parts) and tokens (`--ui-callout-max-width`, `--ui-callout-radius`,
+parts, and `data-ui-callout-recall`, `-recall-trigger` and `-restore` for the info button's list) 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/{component-defaults-0.5.7.md → component-defaults.md}

@@ -1,4 +1,4 @@
-# Component defaults audit (0.5.7)
+# Component defaults audit
 
 `ConfigProvider locale` supplies en (default), zh-TW, zh-CN, ja, ko, de, fr,
 es or it. Nested Providers inherit unless they supply a locale. Built-in strings

package/docs/json-ui.md

@@ -9,7 +9,7 @@ normal Vue/TypeScript extensions.
 It also supports responsive `AppShell` and `ResponsiveView` alternatives:
 one JSON spec renders as a DSM window or a phone view, and as a wide Portal
 page when its `AppShell` sets `wideLayout: "web"`.
-`AppShell` `navigation: "top"` (0.13.1+) shows its `SidebarNav` as one bar above
+`AppShell` `navigation: "top"` shows its `SidebarNav` as one bar above
 the page instead of a left column; a phone keeps the drawer.
 See [adaptive-layout.md](adaptive-layout.md).
 
@@ -113,7 +113,7 @@ The package ships a `syno-pkg-land-ui` command and the same functions from the J
 entry. After `npm install @synopackageland/ui`, run
 `npx --no syno-pkg-land-ui <command>`. To run it without installing locally, use
 `npx -y -p @synopackageland/ui syno-pkg-land-ui <command>`; pin the package version
-for reproducible automation. Since 0.7.0 this is the only bin; the earlier name has no alias (see `CHANGELOG.md`).
+for reproducible automation. `syno-pkg-land-ui` is the package's command name.
 
 | Command | Purpose | Function |
 | --- | --- | --- |

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/docs/theme-hooks.md

@@ -1,6 +1,6 @@
 # Theme hooks: public `data-*` attributes and layout tokens
 
-Since 0.13.1 the attributes and tokens on this page are **public API**. An app
+The attributes and tokens on this page are **public API**. An app
 or a workspace theme may select on them in its own CSS and set the tokens on
 any ancestor. Class names, element nesting and every attribute not listed
 here stay implementation details and can change in any release.
@@ -141,6 +141,7 @@ here stay implementation details and can change in any release.
 | `data-fill` | `Callout` | present when it spans its container |
 | `data-tone` | each `Toast` (class `ui-toast`) | `info`, `success`, `warning`, `danger` |
 | `data-ui-callout-title`, `-body`, `-code`, `-more`, `-details`, `-actions` | `Callout` parts | present |
+| `data-ui-callout-recall`, `data-ui-callout-recall-trigger`, `data-ui-callout-restore` | the list of closed callouts in the page's info button, the info button a toolbar or page header adds for it, and a "Show again" button | present |
 
 Select a `Button` variant with its tag so a `Surface`'s `data-variant` is not
 caught as well: `button[data-variant='primary']`.
@@ -162,7 +163,7 @@ before the token existed. Set them on the app root or any ancestor.
 | `--ui-mobile-bar-bg` | the phone bar's background | `var(--ui-surface)` |
 | `--ui-mobile-bar-fg` | the phone bar's text, menu button and brand | `var(--ui-text-secondary)` (text), `var(--ui-text)` (button, brand) |
 | `--ui-mobile-bar-border` | the phone bar's bottom rule | `var(--ui-border-subtle)` |
-| `--ui-callout-max-width` | how wide a `Callout` grows before it stops (`fill` ignores it) | 720px |
+| `--ui-callout-max-width` | caps how wide a `Callout` grows; it spans its container by default | none |
 | `--ui-callout-radius` | a `Callout`'s and a `Toast`'s corners | 12px |
 | `--ui-callout-glow` | how strong the tone's glow is behind a `Callout`'s or `Toast`'s icon; a dark theme raises it (workbench: 14%) | 9% |
 | `--ui-callout-shadow` | the shadow under a `Callout` and a `Toast` (workbench dark: `0 10px 28px -12px rgba(0, 0, 0, 0.6)`) | `0 8px 24px -12px rgba(15, 23, 42, 0.18)` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.19.11",
+  "version": "0.20.1",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
     "docs/button-policy.md",
     "docs/callout.md",
     "docs/color-system.md",
-    "docs/component-defaults-0.5.7.md",
+    "docs/component-defaults.md",
     "docs/json-ui.md",
     "docs/layout-rules.md",
     "docs/size-and-split.md",