SDK (B2B2C)Parameter form

Parameter form

The SDK ships an auto-generated React form that mirrors the parameter schema your Python project declares via the @cadbuildr_project decorator. Drop it in next to <CadbuildrViewer> and you have a configurator.

Declaring parameters on the Python side

from cadbuildr.foundation import (
    Color,
    Enum,
    Int,
    cadbuildr_project,
)
 
from cadbuildr_projects.lego import LegoFort
 
@cadbuildr_project(
    project_id="lego_fort",
    title="Fortress perimeter",
    description="Four-walled fort with running-bond bricks.",
    parameters=[
        Int("n_length_studs",
            default=16, min=8, max=48, step=2,
            label="Footprint length"),
        Int("n_width_studs",
            default=16, min=8, max=48, step=2,
            label="Footprint width"),
        Int("n_layers",
            default=4, min=1, max=12, step=1,
            label="Wall layers"),
        Color("brick_color",
              default="bright_red",
              choices=("bright_red", "bright_orange", "black"),
              label="Brick color"),
    ],
)
def lego_fort(n_length_studs, n_width_studs, n_layers, brick_color):
    return LegoFort(
        n_length_studs=n_length_studs,
        n_width_studs=n_width_studs,
        n_layers=n_layers,
        color=brick_color,
    )

Available descriptors:

  • Int(name, default, min, max, step, label, description)
  • Float(name, default, min, max, step, label, description)
  • Bool(name, default, label, description)
  • Enum(name, default, choices, label, description)
  • Color(name, default, choices?, label, description) — choices optional; if omitted the form renders a free color picker.

Names are the kwargs the wrapped function receives. Labels are what the form displays.

Emitting the schema

Run the project’s emit_schemas entry point (or your build pipeline) to write parameters/<project_id>.schema.json next to the package. The schema follows JSON Schema with a small CADbuildr extension carrying label, description, and step.

Auto-form in React

import {
  CadbuildrProvider,
  CadbuildrParameterForm,
  CadbuildrViewer,
  defaultValuesForSchema,
} from "@cadbuildr/sdk-react";
 
const schema = await fetch("/parameters/lego_fort.schema.json").then(r => r.json());
 
function App({ sessionToken }: Props) {
  const [values, setValues] = React.useState(
    () => defaultValuesForSchema(schema),
  );
  return (
    <CadbuildrProvider sessionToken={sessionToken} projectKey="lego">
      <aside>
        <CadbuildrParameterForm
          schema={schema}
          values={values}
          onChange={setValues}
        />
      </aside>
      <main>
        <CadbuildrViewer dag={template} parameters={values} />
      </main>
    </CadbuildrProvider>
  );
}

defaultValuesForSchema(schema) returns the { [paramName]: default } seed map.

Field rendering

The form renders one input per parameter, in declaration order:

DescriptorRendered as
IntNumber input + optional slider when min/max/step set
FloatNumber input + optional slider
BoolToggle switch
EnumNative <select>
Color (with choices)Native <select> over the LEGO palette names
Color (no choices)Native <input type="color">

The form is intentionally unstyled. Wrap it in your storefront’s component library if you need custom skinning, or compose the headless hooks (useCadbuildrProjectSchema) directly.

Discretization (slider step)

Sliders snap to the step you declare. This isn’t only a UX choice — the kernel-api L2 cache keys on parameter values, so a free-form slider at 5.0001 vs 5.0002 would miss the cache. Pick the smallest step where your geometry is visually distinct, and the cache hit rate over a parameter sweep stays high.

Viewer & providerFrozen-DAG mode