@synopackageland/ui 0.16.4 → 0.17.1

package/docs/app-local-modal.md

@@ -50,6 +50,20 @@ Dialog and Sheet forward cancellable `escapeKeyDown`, `pointerDownOutside`,
 <Dialog title="Settings" @escape-key-down="event => event.preventDefault()" />
 ```
 
+### A window-like dialog
+
+DSM leaves the window behind a modal window readable: no dark mask, a soft
+shadow round the modal, and a press outside it does nothing. A Dialog opens
+that way with three props, which `WizardDialog` sets:
+
+| Prop | Default | |
+| --- | --- | --- |
+| `scrim` | `dim` | The mask over the app: `dim` (`--ui-overlay`, blurred), `light` (`--ui-overlay-light`, a faint tint) or `none`. Each blocks presses, wheel and touch on the app behind. |
+| `close-on-outside` | `true` | `false`: a press outside neither closes the dialog nor reaches the app. Escape and the close button still close it. |
+| `header-divider` | `true` | `false` drops the line under the header, for content whose own header continues it (a Wizard's step title). |
+
+The mask and the outside press stay local to the app in app mode, as above.
+
 ## Floating dialogs in a DSM window
 
 `<AppRoot dialog-bounds="viewport">` (app mode only; default `app`) lets Dialog

package/docs/button-policy.md

@@ -18,7 +18,7 @@ are in [dsm-native-metrics.md](dsm-native-metrics.md).
 | Place | Component | Shape | Variants |
 | --- | --- | --- | --- |
 | Dialog, sheet or wizard footer | `Dialog`, `Sheet`, `Wizard` `#footer` | capsule | Cancel `secondary`, then OK `primary` |
-| Wizard footer | `Wizard` | capsule | Back `secondary` at the start; the step's `#actions`, Cancel `secondary`, then Next / Apply / Finish `primary` at the end |
+| Wizard footer | `Wizard` | capsule | The step's `#actions` at the start (a quiet `ghost` `kind="tool"` text action); Cancel `secondary` (a page wizard only), Back `secondary`, then Next / Apply / Finish `primary` at the end |
 | 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` |

package/docs/color-system.md

@@ -133,7 +133,7 @@ The same roles, with the light page's sage carried into the greys:
 | `--ui-*-soft` | the tone at 18% | |
 
 The tones' solid fills, radii, spacing and type are the light values. The
-masks and shades (`--ui-overlay`, `--ui-drawer-backdrop`,
+masks and shades (`--ui-overlay`, `--ui-overlay-light`, `--ui-drawer-backdrop`,
 `--ui-scroll-edge-shade`), shadows, tooltip, scroll bar and switch thumb have
 dark values too; a component draws no colour of its own outside these tokens.
 

package/docs/wizard.md

@@ -1,20 +1,22 @@
 # Wizard
 
-A wizard walks the user through a setup in a few steps. It is a window-sized
-layout, not a row of dots: the steps sit in a **rail** beside the step (or in a
-**stepper band** above it when the wizard is narrower than 600px), the step
-scrolls between a fixed band and a fixed footer, and the footer has **Back on
-the left and one main action on the right**.
+A wizard walks the user through a setup in a few steps. It follows DSM's
+wizard window: a **fixed header** (the wizard's name small, the current step's
+title large, a compact progress bar beside it, one line under it), the step
+scrolling in the middle, and a **fixed footer** with Back and the one main
+action together at the end, in the same place on every step.
 
 ![A setup wizard in a dialog](screenshots/wizard-dialog-light.png)
 
+![The same wizard in the dark theme](screenshots/wizard-dialog-dark.png)
+
 ## Pieces
 
 | Component | Use |
 | --- | --- |
-| `WizardDialog` | The wizard in an app-local dialog: DSM's `xl` width (860px) and 600px high, both capped to the window. Cancel closes it; so does Finish unless `close-on-finish="false"`. Other attributes and listeners go to the `Wizard`. |
+| `WizardDialog` | The wizard in an app-local dialog sized like DSM's wizard windows: 75% of the app's width (560–860px) and its height less 48px (600px at most), so the app shows around it; `width`, `height` or `size` set your own. Its `title` is the wizard's name, beside the close button; see [Modal](#modal). Other attributes and listeners go to the `Wizard`. |
 | `Wizard` | The layout and the step flow, for a dialog of your own (`<Dialog flush>`) or a page (`framed`). |
-| `WizardStep` | One step: hero, headline, one line, content, and the step's own footer actions. |
+| `WizardStep` | One step: its title (shown in the header), hero, one line, content, and the step's own footer actions. |
 
 ```vue
 <script setup lang="ts">
@@ -38,20 +40,29 @@ const open = ref(false)
 
 ## Steps
 
-- **Hero.** `icon` puts an icon tile beside the headline. The `#hero` slot puts a
-  picture or a diagram on a stage above it; prefer one there to a paragraph.
-  A `type="done"` step shows a success mark that pops in once, centred.
-- **Text.** `headline` is the step's title; `label` is a shorter name for the
-  step list. `description` is one short line under the headline, without a
-  closing period. Keep the content to the controls the step needs.
+- **Title.** `headline` is the step's title. It shows large in the wizard
+  header, not in the step, so do not repeat it in the content. `label` is a
+  shorter name for the step list (read by screen readers, and in the rail).
+- **Hero.** The step opens with its hero: `icon` puts an icon tile beside the
+  step's line; the `#hero` slot puts a picture or a diagram on a stage; prefer
+  one there to a paragraph. A compact `ConnectionTopology` on the stage is a
+  centred row of three boxes of one width, without a frame of its own. A
+  short step with a hero takes a little of its free room above it (32px at
+  most) and leaves the rest below. A `type="done"` step shows a success mark that pops
+  in once, centred.
+- **Text.** `description` is one short line at the top of the step, under the
+  hero, without a closing period. Keep the content to the controls the step
+  needs; it may be wide (a row of cards) or a form.
 - **Types.** `welcome` offers only Start; `done` drops Back and Cancel, fills
   the progress and turns the main action into Finish. The last step without
   `next-step-key` turns it into Apply.
 - **Main action.** `next-label`, `next-disabled` and `:show-next="false"` (a step
   that moves on by itself or through its own choices, such as a row of cards)
   change it for one step. `:show-back="false"` hides Back.
-- **More actions.** The step's `#actions` slot goes in the footer before Cancel
-  and the main action: secondary buttons only, there is one main action.
+- **More actions.** The step's `#actions` slot goes at the start of the footer,
+  away from Back and the main action. Use it only when the step needs it, and
+  as a quiet text action: `<Button variant="ghost" kind="tool">`. There is one
+  main action.
 - **State.** Inactive steps stay mounted so their fields keep what the user
   typed; `lazy` mounts a step's content only while it shows (a step that loads
   data when it opens).
@@ -62,13 +73,14 @@ const open = ref(false)
 | Prop | Default | |
 | --- | --- | --- |
 | `active-step-key` (`v-model`) | the first step | The shown step. The wizard also moves by itself; bind it back to follow. |
-| `stepper` | `auto` | `rail`, `header` (the band), `none`; `auto` is the rail from `rail-min-width`. |
-| `rail-min-width` | `600` | The wizard width from which `auto` shows the rail. |
-| `title`, `description` | — | Shown above the steps in the rail. `WizardDialog` puts its `title` in the dialog header instead. |
+| `stepper` | `auto` | The progress: `auto` and `bar`, a segment per step beside the step title; `rail`, the steps listed beside the step from `rail-min-width` (the bar below it); `none`, only the "Step n of total" line. `header` (0.16's band) is the bar. |
+| `rail-min-width` | `600` | The wizard width from which `rail` shows the rail. |
+| `title` | — | The wizard's name, small above the step title. `WizardDialog` puts its `title` in the dialog header instead. |
+| `description` | — | Deprecated: not shown since 0.17. Put the line in the first step's `description`. |
 | `framed` | `false` | Border, corners and card shadow, for a wizard on a page. |
 | `fit` | `false` | On a page: takes the height left below it in its scroll container (or the window), so the steps, band and footer stay in view and only the step scrolls. |
 | `fit-min-height` | `320` | The least height `fit` takes; a shorter window scrolls the page instead. |
-| `cancellable` | `true` | Cancel in the footer. |
+| `cancellable` | `true` | Cancel in the footer, before Back. `WizardDialog` sets it to `false`: its header's close button cancels. |
 | `footer` | `true` | `false` hides the footer; an object renames `start`, `previous`, `next`, `apply`, `finish`, `cancel`. |
 | `progress-text` | "Step n of total" | The progress line. |
 | `show-steps` | — | Deprecated: `false` is `stepper="none"`. |
@@ -84,21 +96,49 @@ A wizard fills the height its container gives it (`WizardDialog` and
 `<Dialog flush height="…">` give it one); on a page, set a height on its
 container, set `fit`, or let it take its content's height. A wizard held to a
 height under 560px (`fit` in a short window, or a dialog) draws a smaller
-headline, hero and spacing.
+title, hero and spacing; one under 600px wide keeps less margin.
+
+## Footer
+
+The footer is the same on every step: the step's `#actions` at the start;
+Cancel (a page wizard only), Back and the main action at the end. The main
+action is always last, at the right edge, so it never moves; on the first step
+there is no Back and nothing shifts. A welcome step offers Start alone; a done
+step offers Finish (and its own `#actions`). There is no Close in the footer:
+a `WizardDialog` closes from its header.
+
+## Modal
+
+`WizardDialog` opens like a DSM modal window, in the app (app-local, see
+[app-local-modal.md](app-local-modal.md)):
+
+- a soft glow all round the panel (`--ui-shadow-modal`) and rounder corners,
+- a light scrim over the app (`--ui-overlay-light`) instead of the dark mask:
+  the app stays readable, but takes no presses,
+- a press outside does nothing: it neither closes the wizard nor reaches the
+  app; Escape and the close button close it, and either emits `cancel`,
+- the focus it moves (on opening, to the first field; on a step change, to the
+  step title) shows a ring only after a key, never after a click.
+
+These are `Dialog` props (`scrim="light"`, `:close-on-outside="false"`,
+`:header-divider="false"`), so a dialog of your own around a `Wizard` can
+open the same way.
 
 ## Behaviour
 
 - **Focus.** When the step changes while the focus is in the wizard, the focus
-  moves to the new step's headline, so a screen reader reads where the user
-  is. A step that changes while the focus is elsewhere (the app follows the
-  backend) leaves the focus alone.
-- **Assistive technology.** The step list is an ordered list named "Steps" with
-  `aria-current="step"`, and each finished step is read as completed. A step is
-  a section labelled by its headline; hidden steps are `aria-hidden`.
-- **Motion.** A step slides in 16px from the side it comes from; the progress
-  bar and the markers ease to their new state; the done mark pops with a ring
-  and a short burst. Reduced motion turns all of it off.
-- **Size.** In a phone-width window the dialog is a bottom sheet with the
-  band; in a DSM window from 600px wide (`rail-min-width`) the rail shows.
+  moves to the step title in the header, which is described by the progress
+  ("Step 2 of 4"), so a screen reader reads where the user is. A step that
+  changes while the focus is elsewhere (the app follows the backend) leaves
+  the focus alone. In a `WizardDialog` the Tab key stays in the dialog.
+- **Assistive technology.** The dialog is a `dialog` labelled by the wizard's
+  name. The progress is an ordered list named "Steps" with
+  `aria-current="step"`, and each finished step is read as completed. The
+  shown step is a section labelled by the header's title; hidden steps are
+  `aria-hidden`.
+- **Motion.** A step fades in from 10px on the side it comes from and its
+  title fades in; the progress segments ease to their new state; the done mark
+  pops with a ring and a short burst. Reduced motion turns all of it off.
+- **Size.** In a phone-width window the dialog is a bottom sheet.
 - **Theme.** Colours are the theme's roles, so the wizard follows the accent
   and the dark theme.

package/package.json

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