@valantify/steps

Configurator step logic for multi-step product configuration flows.

What it does

This package manages the logic for product configurators where users make selections across multiple steps (e.g., color → design → accessories). It handles:

• Conditional visibility: Steps appear/hide based on prior selections
• Cascading selections: Changing one step auto-updates dependent steps
• Variation matching: Maps feature combinations to actual product variations

Core concepts

Variation

A valid feature combination from your product catalog metadata (product.json + variant.json):

{
  folder: "./jetgate/gray-mesh-electric/",
  features: { color: "gray", design: "mesh", meshAccessory: "electric" }
}

Step

A configuration stage with selectable options:

{
  type: "color",           // "color" | "image" | "text"
  title: "Choose color",
  options: [
    { color: "#A51717", features: { color: "red" } },
    { color: "#818181", features: { color: "gray" } }
  ]
}

VisibleStep

A computed step showing what's currently available:

{
  step: { /* original step */ },
  stepIndex: 0,
  availableOptions: [ /* options valid given prior selections */ ],
  selectedOption: { /* currently selected option or null */ }
}

API

Finding variations

// Get features for the currently displayed variation
getCurrentFeatures(variations, "./jetgate/gray-linear/")
// → { color: "gray", design: "linear" }

// Find exact variation match
findVariation(variations, { color: "gray", design: "linear" })
// → Variation | null

// Find closest match (useful when exact match doesn't exist)
findClosestVariation(variations, { color: "gray" })
// → Variation with most matching features

Computing step visibility

// Get visible steps and their available options
const visibleSteps = getVisibleSteps(steps, currentFeatures, variations);
// → VisibleStep[]
// Only includes steps with 2+ available options
// Auto-selects first available if current selection is invalid

Handling user selections

// Resolve full state after user picks an option
const result = resolveSelection(
  steps,
  variations,
  currentFeatures,
  changedStepIndex,      // which step changed
  newOptionFeatures       // features from the new option
);
// → { features, variation, visibleSteps }
// Cascades through subsequent steps, auto-fixing invalid selections

Example flow

const variations = [
  { folder: "./shoe/red-linear/", features: { color: "red", design: "linear" } },
  { folder: "./shoe/red-mesh-electric/", features: { color: "red", design: "mesh", meshAccessory: "electric" } },
  // ... more variations
];

const steps = [
  {
    type: "color",
    title: "Choose color",
    options: [
      { color: "#A51717", features: { color: "red" } },
      { color: "#818181", features: { color: "gray" } }
    ]
  },
  {
    type: "image",
    title: "Choose design",
    options: [
      { image: "./mesh.webp", features: { design: "mesh" } },
      { image: "./linear.webp", features: { design: "linear" } }
    ]
  },
  {
    type: "image",
    title: "Mesh accessory",  // Only visible if design=mesh
    options: [
      { image: "./electric.webp", features: { meshAccessory: "electric" } },
      { image: "./wire.webp", features: { meshAccessory: "wire" } }
    ]
  }
];

// Initial state
let visibleSteps = getVisibleSteps(steps, {}, variations);
// Shows: Color step (red, gray)

// User picks red
const result = resolveSelection(steps, variations, {}, 0, { color: "red" });
// Shows: Color step (red selected), Design step (mesh, linear)

// User picks mesh design
const result2 = resolveSelection(steps, variations, result.features, 1, { design: "mesh" });
// Shows: Color, Design, Mesh accessory (electric, wire now visible)

Key behaviors

• Auto-selection: If current selection becomes invalid, automatically picks first available option
• Auto-hiding: Steps with 0-1 options are hidden (no choice to make)
• Feature locking: Each step locks features for subsequent steps in order
• Cascade updates: Changing a step revalidates all subsequent steps

Development

yarn typecheck    # Type check
yarn test         # Run tests
yarn test:watch   # Watch mode

Integration

Used by configurator UIs to:

1. Render only visible steps
2. Show available options per step
3. Handle option clicks and update state
4. Display the matching variation's images

See test file for detailed examples.