@synopackageland/ui 0.14.9 → 0.14.10

package/docs/button-policy.md

@@ -55,6 +55,9 @@ are in [dsm-native-metrics.md](dsm-native-metrics.md).
   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).
+- A Button in a `Callout`'s `#actions` and a toast's action are drawn as
+  capsules by the Callout and the Toast themselves ([callout](callout.md)).
+  They stay `kind="tool"` buttons, so they do not count as a footer's action.
 - 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.

package/docs/callout.md

@@ -0,0 +1,123 @@
+# Callout, Toast and inline notes
+
+A page says three kinds of things outside its content: a result that just
+happened, something the user has to act on, and a risk to keep in mind. Each
+has its own component, and none of them is a full-width banner.
+
+| The message | Use | Shape |
+| --- | --- | --- |
+| A passing result: "Settings applied", "The check passed", "Copied" | `useToast()` | A toast that fades after 4.5 s. Do not leave a Callout behind for it. |
+| Something the user has to act on: a missing setting, a failed connection, a sign-in that waits | `<Callout>` | One-line title, at most one line of text, one action. |
+| 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. |
+
+## The look
+
+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:
+
+- 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 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
+a card on purpose: a Callout floats above the settings rather than being one
+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.
+
+Contrast was measured on the surface, light and dark, in every tone: text at
+least 5.4:1, icons at least 3.3:1.
+
+`variant="inline"` keeps the icon and the tones and drops the surface: an
+icon and one line of secondary text, with a link or a small button after it.
+Use it for a note under a field or a section heading, where a panel would
+weigh more than the note.
+
+### Why this one
+
+Three directions were drawn as working prototypes, each in every tone, with
+and without an action, light and dark, and on a settings page:
+
+1. **Card with an icon chip** (in the manner of Stripe and Linear): a white
+   card with a hairline frame. The tone sits only in a rounded icon chip, and
+   the action is a text button. Calm, but close to the cards around it.
+2. **Status line** (in the manner of Apple's settings and Vercel): no
+   container. A filled round chip, the title and the message on one line, and
+   an "Action →" link. The lightest, but too quiet for something that blocks
+   the user.
+3. **Glow surface**: the look above. It was chosen because it keeps the 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
+  labels) does not end in a period; a period between two sentences stays.
+- **Title**: what is wrong or missing, in a few words: "DSM external access
+  address is not set".
+- **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.
+  The button label names what it does: "Apply nas.example.com", not "OK".
+- **Risk notes**: one sentence. Put the explanation in `#details`:
+
+  ```vue
+  <Callout tone="warning" variant="inline">
+    Without an access policy, anyone who knows the name reaches the service
+    <template #actions><Link :href="accessDocs" external>Set up access</Link></template>
+  </Callout>
+
+  <Callout tone="warning" title="No access policy">
+    Anyone who knows the name reaches the service
+    <template #details>Add an access policy that allows only your accounts…</template>
+  </Callout>
+  ```
+
+- A result the user caused, and that needs nothing more, is a toast:
+
+  ```ts
+  const toast = useToast()
+  toast.success('Settings applied', 'Added port 6690')
+  ```
+
+- Put a machine error code in `code`, not in the text.
+- Stack at most two Callouts in one section. More means the page should show
+  the state in its content (a `Badge`, a `KeyValueRow`) instead.
+
+## API
+
+| Prop / slot | Use |
+| --- | --- |
+| `tone` | `info` (default), `success`, `warning`, `danger` |
+| `variant` | `soft` (default) or `inline` |
+| `title` | One line, the thing to know |
+| default slot | The message |
+| `#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 |
+| `fill` | Span the container instead of stopping at 720px |
+
+Theme hooks (`data-tone`, `data-variant`, `data-fill`, 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/color-system.md

@@ -60,7 +60,7 @@ at 7:1 or more (`tests/css/palette.test.ts`).
 | `--ui-{tone}-soft` | `a3` of each tone (`gray-a3` for neutral) | badge fill |
 | `--ui-{tone}-text` | step 11 of each tone (`gray-11` for neutral) | badge text |
 | `--ui-danger-hover`, `--ui-danger-active` | `red-10`, `red-11` | red button hovered, pressed |
-| `--ui-warning-accent` | `orange-10` | a Callout's bar and icon |
+| `--ui-warning-accent` | `orange-10` | a warning Callout's or Toast's top light, glow and icon |
 
 Tones stay DSM's whatever the accent: an info badge is blue in every app.
 
@@ -75,8 +75,8 @@ The scales follow DSM where the two disagree:
   as light as a button fill.
 - **A pressed button is step 6.** DSM fills it at 70% of `#c6d4e0`, the colour
   of a field's frame.
-- **Orange step 10 is darker than DSM's hover orange,** so a Callout's bar and
-  icon keep 3:1 on its 5% tint.
+- **Orange step 10 is darker than DSM's hover orange,** so a warning Callout's
+  icon keeps 3:1 on its tint.
 
 ## Accent
 

package/docs/layout-rules.md

@@ -68,6 +68,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 - Show a headline number (space freed, files moved) with `Statistic`: `label`, `value`, optional `note`; `size="lg"` for the one number a page leads with. Put several in `Surface`s in a grid. Do not set font sizes for figures.
 - Colour a usage bar by meaning with `Progress tone` (`warning` when nearly full) rather than drawing your own bar.
 - Show a state as a `Badge` in a `KeyValueRow`, not as a sentence. A toned badge leads with a dot; keep `neutral` for plain values such as a version.
+- A passing result ("Settings applied") is a toast; a Callout is for something the user has to act on or a short risk note, with one title, one line and one action ([callout](callout.md)).
 - Put a machine error code in `Callout`'s `code` prop, not in the message text: `<Callout tone="warning" :code="status.code">{{ message }}</Callout>`.
 - Do not show internal identifiers, such as job ids or catalog keys. Show the name the user gave.
 - In Chinese and Japanese, a label and its value are separated by a full-width colon `：`.

package/docs/theme-hooks.md

@@ -89,6 +89,11 @@ here stay implementation details and can change in any release.
 | `data-ui-dialog`, `data-ui-sheet` | `Dialog` / `Sheet` panels | present |
 | `data-ui-list-item-title`, `-description`, `-meta`, `-actions` | `ListItem` parts | present |
 | `data-ui-statistic-label`, `-value`, `-note` | `Statistic` parts | present |
+| `data-tone` | `Callout` | `info`, `success`, `warning`, `danger` |
+| `data-variant` | `Callout` | `soft`, `inline` |
+| `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 |
 
 Select a `Button` variant with its tag so a `Surface`'s `data-variant` is not
 caught as well: `button[data-variant='primary']`.
@@ -110,6 +115,10 @@ 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-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)` |
 
 The colour, radius, spacing and web tokens are listed in the
 [README](../README.md#theme-override), [colour system](color-system.md) and

package/package.json

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