Compositions

Upload wizard

A 2-step wizard (Settings → Mapping) for ingesting tabular files (CSV, XLSX, JSON) into structured records. Use this pattern any time the app accepts a user-provided file that needs column mapping before storage. Always pair with origin-aware navigation so users return to their starting context after upload.

Overview

The upload wizard is a specialization of the Wizard system. Step 1 collects the file plus ingestion options (auto-match, hierarchical, visibility). Step 2 is column mapping — detected source headers on the left, target fields on the right. Users return to their starting context on completion via the origin-aware breadcrumb.

Use cases

  • Catalog upload. Product records from CSV/XLSX.
  • Price list import. Price updates bulk-imported from a spreadsheet.
  • Member roster. CSV of employee emails + roles to seed a workspace.
  • Configuration migration. JSON export from one workspace imported into another.

Anatomy

PartClassRole
File picker.bn-drop + .bn-file-stripTwo states: empty drop zone before pick, collapsed file strip after.
Option rows.bn-opt / .bn-radioTitle + one-liner help. Checkboxes for independent options, radios for one-of-N.
Folder picker.bn-treeTree-view inside a wizard panel for "where do these records go?".
Sortable priority list.bn-priorityDrag-to-reorder list for tie-break ordering.
Column mapping.bn-mapStep 2. Source headers left, target fields right, dropdown per row.
Section title.bn-section-titleLightweight in-card title that breaks Settings into logical groups.

Best practices

  • Origin-aware. The crumb in the wizard header reflects where the user launched the upload from — not a generic "Files" label. Cancel + post-submit landing return to the same view.
  • Drop zone, file strip. Show a drop zone before pick; collapse to a one-line file strip after. Don't keep the drop zone visible after selection.
  • Required fields first in mapping. Step 2 lists required target fields at the top with red asterisks. Optional fields below.
  • Validation before commit. Show row-level errors before the user clicks Import. Don't let them submit and then surface errors.

Composition

Upload wizard composes the Wizard system chrome with these specialized parts. The header uses the WizardCrumbs variant and the origin crumb is set per launch context. See Breadcrumbs for how origin-aware navigation is implemented.