@synopackageland/ui 0.15.0 → 0.16.0

package/docs/button-policy.md

@@ -18,6 +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 |
 | 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/wizard.md

@@ -0,0 +1,99 @@
+# 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 setup wizard in a dialog](screenshots/wizard-dialog-light.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`. |
+| `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. |
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FolderPlus } from '@lucide/vue'
+import { WizardDialog, WizardStep } from '@synopackageland/ui'
+
+const open = ref(false)
+</script>
+
+<template>
+  <WizardDialog v-model:open="open" title="Create shared folder">
+    <WizardStep step-key="welcome" type="welcome" headline="Create a shared folder" description="Choose where it lives and who can open it" :icon="FolderPlus" next-step-key="name" />
+    <WizardStep step-key="name" headline="Name and location" label="Location" next-step-key="done" :pre-enter-next-step="validate">
+      <Form>…</Form>
+    </WizardStep>
+    <WizardStep step-key="done" type="done" headline="Folder created" :finished="refresh" />
+  </WizardDialog>
+</template>
+```
+
+## 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.
+- **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.
+- **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).
+- A step mounted later (`v-if`) takes its place in document order in the list.
+
+## Wizard
+
+| 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 600px. |
+| `title`, `description` | — | Shown above the steps in the rail. `WizardDialog` puts its `title` in the dialog header instead. |
+| `framed` | `false` | Border, corners and card shadow, for a wizard on a page. |
+| `cancellable` | `true` | Cancel in the footer. |
+| `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"`. |
+
+The `#footer` slot replaces the footer's buttons and receives `nextStep`,
+`previousStep`, `finish`, `cancel`, `canGoPrevious`, `isLastStep`, `busy` and
+`stepKey`. Events: `next-step`, `previous-step` (`{ from, to }`), `finished`,
+`cancel`. A step guard (`pre-enter-next-step`, `pre-enter-previous-step`)
+returning `false` keeps the step; the main action shows a spinner while it
+runs. The step list does not navigate, so a guard cannot be skipped.
+
+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 or let it take its content's height.
+
+## 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 the rail shows.
+- **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.15.0",
+  "version": "0.16.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,8 @@
     "docs/json-ui.md",
     "docs/layout-rules.md",
     "docs/size-and-split.md",
-    "docs/theme-hooks.md"
+    "docs/theme-hooks.md",
+    "docs/wizard.md"
   ],
   "bin": {
     "syno-pkg-land-ui": "./dist/cli.js"