Add Wizard component, composable multi-step flows

[pedromenezes1]

Adds a Wizard to Kumo, a fullscreen, multi-step flow built as a single composable compound component.

what's included:

• compound API — Wizard.Fullscreen/Wizard.Grid/Wizard/Wizard.Sidebar/Wizard.Steps/Wizard.Step/Wizard.Page/Wizard.CloseButton, plus useWizard and useWizardGrid hooks
• non-linear step navigation via goToStep and a declarative when prop, so steps can branch rather than only go linear next/back
• controlled (step + onStepChange) and uncontrolled (defaultStep) modes
• fullscreen overlay with scroll lock, esc to dismiss, and a close button
• optional left-side title (via Wizard.Grid title) and composable right-side step indicator via Wizard.Sidebar
• optional decorative wireframe grid
• width on Wizard.Fullscreen — controls the card max-width ("narrow" / "wide")
• optional header on Wizard.Fullscreen — renders arbitrary top chrome; its height is measured and subtracted from the layout
• Wizard.CloseButton — close button for custom header placement; throws outside Wizard.Fullscreen
• useWizard().close() — programmatically closes the wizard by delegating to Wizard.Fullscreen's onClose
• previousStepNavigation — disables implicit go-back affordances (card click, sidebar click) while keeping explicit back()
• short-viewport handling — when vertical space is tight, the fixed top/bottom offsets lift so the LayerCard uses the space that's left instead of shrinking too hard
• i18n-ready — the aria-labels are overridable via labels props

usage:

import { Wizard, useWizard, useWizardGrid } from "@cloudflare/kumo";

function CreateWorker({ open, onClose }) {
  const { gridProps, onActiveStepElementChange } = useWizardGrid();

  return (
    <Wizard.Fullscreen open={open} onClose={onClose}>
      <Wizard.Grid title="Create a Worker" {...gridProps}>
        <Wizard onActiveStepElementChange={onActiveStepElementChange}>
          <Wizard.Sidebar />
          <Wizard.Steps>
            <Wizard.Step stepKey="method" label="Select a method">
              <Wizard.Page title="Ship something new" footer={<Footer />}>
                {/* ... */}
              </Wizard.Page>
            </Wizard.Step>
            {/* ...more steps */}
          </Wizard.Steps>
        </Wizard>
      </Wizard.Grid>
    </Wizard.Fullscreen>
  );
}

// the step footer reads navigation from useWizard()
function Footer() {
  const { back, next, isFirstStep } = useWizard();
  // ...
}

---

• Reviews
  • bonk has reviewed the change
  • automated review not possible because:
• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@559

commit: 231c033

[github-actions]

Docs Preview

View docs preview

Commit: d5914b5

[github-actions]

Visual Regression Report — 25 changed, 15 unchanged

25 screenshot(s) with visual changes:

Button / Variant: Secondary

161 px (0.16%) changed

Before	After	Diff

Button / Variant: Ghost

175 px (0.17%) changed

Before	After	Diff

Button / Variant: Destructive

278 px (0.27%) changed

Before	After	Diff

Button / Icon Only

110 px (0.11%) changed

Before	After	Diff

Button / Loading State

1 px (0%) changed

Before	After	Diff

Dialog / Dialog With Actions

200 px (0.2%) changed

Before	After	Diff

Dialog / Dialog Basic

259 px (0.26%) changed

Before	After	Diff

Dialog / Dialog Confirmation

707 px (0.7%) changed

Before	After	Diff

Dialog / Custom Max Width

515 px (0.51%) changed

Before	After	Diff

Dialog / Dialog With Select

225 px (0.22%) changed

Before	After	Diff

Dialog / Dialog With Combobox

225 px (0.22%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

130 px (0.13%) changed

Before	After	Diff

Dialog (Open)

0 px (0%) changed

Before	After	Diff

Select / Select Basic

300 px (0.3%) changed

Before	After	Diff

Select / Select Sizes

869 px (0.47%) changed

Before	After	Diff

Select / Select Without Label

105 px (0.1%) changed

Before	After	Diff

Select / Select With Description

1,213 px (1.02%) changed

Before	After	Diff

Select / Select With Error

1,730 px (1.46%) changed

Before	After	Diff

Select / Select Placeholder

418 px (0.41%) changed

Before	After	Diff

Select / Select Loading

0 px (0%) changed

Before	After	Diff

Select / Select Multiple

851 px (0.84%) changed

Before	After	Diff

Select / Select Complex

1,093 px (0.92%) changed

Before	After	Diff

Select / Select Disabled Items

176 px (0.17%) changed

Before	After	Diff

Select / Select Long List

1,572 px (1.33%) changed

Before	After	Diff

Select (Open)

3,038 px (0.01%) changed

Before	After	Diff

15 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Disabled State
• Button / Title
• Button / Link as Button
• Dialog / Dialog Alert
• Select / Select With Tooltip
• Select / Select Custom Rendering
• Select / Select Disabled Options
• Select / Select Grouped
• Select / Select Grouped With Disabled

---

Generated by Kumo Visual Regression

[pedromenezes1]

/bonk

[ask-bonk]

PR #559: Add Wizard component by pedromenezes1

Summary: Introduces a new Wizard compound component for building fullscreen, composable multi-step flows in Kumo.

What's added:

• 25 files (+5,242 / −125 lines)
• Compound API: Wizard.Fullscreen, Wizard.Grid, Wizard, Wizard.Steps, Wizard.Step, Wizard.Page, plus useWizard and useWizardGrid hooks
• Features: non-linear step navigation via goToStep and a declarative when prop, fullscreen overlay with scroll lock/ESC-to-dismiss, optional sidebar step indicator, decorative wireframe grid, short-viewport handling, and i18n-ready aria labels
• Includes docs page, demo components, and 1,663 lines of tests
• Changeset included

CI / Automation:

• 📦 pkg-pr-new preview available: npm i https://pkg.pr.new/@cloudflare/kumo@559
• 📖 Docs preview: available here
• 🖼️ Visual regression: 10 changed screenshots (Button, Dialog, Select variants), 29 unchanged — pixel diffs are minor (0–1.46%), likely from shared layout/style shifts rather than intentional visual changes

PR checklist: Author marked "Tests included/updated" as complete. Awaiting review.

github run

[pedromenezes1]

/bonk

[ask-bonk]

PR #559: Add Wizard component, composable multi-step flows by pedromenezes1

Overview: Introduces a new Wizard compound component for building fullscreen, composable multi-step flows in Kumo.

What's added:

• Compound API: Wizard.Fullscreen, Wizard.Grid, Wizard, Wizard.Steps, Wizard.Step, Wizard.Page, Wizard.Sidebar, Wizard.CloseButton, plus useWizard and useWizardGrid hooks
• Features: Non-linear step navigation via goToStep and a declarative when prop; controlled (step + onStepChange) and uncontrolled (defaultStep) modes; fullscreen overlay with scroll lock, ESC-to-dismiss, and close button; optional left-side title and right-side step indicator; decorative wireframe grid; short-viewport handling; i18n-ready aria labels
• Code: 25 new files, +6,329 / −125 lines across 30 files, including 2,176 lines of tests and a changeset
• Docs: New wizard docs page, demo components, and registry updates

CI / Automation:

• 📦 pkg-pr-new preview: npm i https://pkg.pr.new/@cloudflare/kumo@559
• 📖 Docs preview: available here
• 🖼️ Visual regression: 24 changed, 15 unchanged — minor pixel diffs (0–1.67%) on Button, Dialog, and Select variants, likely from shared layout/style shifts rather than intentional visual changes

Status: Author marked "Tests included/updated" as complete. Awaiting review.

github run

[stritt]

thanks for putting this together! we're cleaning up the pr backlog and this would need a significant rebase plus another api and design pass against current main. are you still planning to work on it? if not we'll close it for now on july 28, but you're always welcome to reopen it when ready.