Praxis Stepper Wizard Runtime
Use this skill for the canonical @praxisui/stepper runtime and the experimental wizard wrapper. Treat the stepper as a governed multi-step workflow surface, not as a local Material Stepper composition.
Source Audit
Before editing code or guidance, inspect the relevant source:
projects/praxis-stepper/AGENTS.mdprojects/praxis-stepper/README.mdprojects/praxis-stepper/docs/host-stepper-integration.mdprojects/praxis-stepper/docs/stepper-api-reference.mdprojects/praxis-stepper/src/public-api.tsprojects/praxis-stepper/src/lib/praxis-stepper.tsprojects/praxis-stepper/src/lib/praxis-stepper.spec.tsprojects/praxis-stepper/src/lib/praxis-stepper-config-editor*projects/praxis-stepper/src/lib/wizard/**projects/praxis-stepper/src/lib/ai/**
If public docs, registry, playgrounds, or examples mention stepper or wizard flows, also audit those derived artifacts before declaring the issue complete.
Canonical Boundary
@praxisui/stepper owns:
StepperMetadata,StepConfig, orientation, header, linear, navigation, density, classes, appearance, and iconsstepperId,componentInstanceId, and persistence throughASYNC_CONFIG_STORAGE- step selection,
selectedIndexChange,selectionChange, and Material animation events - dynamic-form step embedding through
steps[].form - rich step content through
stepBlocksBeforeFormandstepBlocksAfterForm - advanced host-owned widgets through
steps[].widgets serverValidate,validateStep, andnextWithValidationwidgetEventpropagation from nested widgets with step-aware path context- Settings Panel config editor, AI assistant integration, and
PRAXIS_STEPPER_AUTHORING_MANIFEST PraxisWizardFormComponentas the higher-level wizard adapter that mapsWizardFormConfigintoStepperMetadata
Hosts consume these contracts. Do not move linear validation, form step mapping, wizard normalization, or canonical resourcePath handling into app-local steppers when the lib owns the workflow semantics.
Runtime Rules
- Require a stable
stepperIdfor persisted or customizable flows. AddcomponentInstanceIdfor repeated instances on one route. - Keep
steps[].idstable. Authoring, widget paths, validation, and wizard mapping should resolve by id before label or index. - Pass dynamic-form
resourcePathas a canonical base resource path, such asdomain/resource; do not include/api,/filter,/{id}, schema endpoints, operation URLs, or query strings. - Use
linear=trueplus formFormGroupvalidity for normal blocking behavior. UseserverValidatefor remote validation instead of inventing a parallel validation DSL in stepper config. - Prefer
stepBlocksBeforeFormandstepBlocksAfterFormfor editorial content. Usesteps[].widgetsonly for advanced host-owned widgets after the canonical rich content path is unsuitable. getStepRichContentContext(stepIndex)propagates reactive form values across steps (merged at top-level, invalues, and per-step informskeyed bystep.idand step index, while keepingstep,stepIndex,stepper, and explicitstepperContextauthoritative), enabling workflow review steps to bind${...}expressions and[praxisQuickView]triggers (recordReference,keyValueList,propertySheet,recordSummary,relatedRecord) directly to entity references collected in earlier steps.- Pair with
praxis-rich-content-runtimeandpraxis-rich-content-integration-adapterswhen step rich content changes; new editorial content should preferRichContentDocumentover legacy wizard blocks. - Keep navigation config as workflow chrome. Do not encode business approval rules as button labels, local command strings, or keyword-routed step actions.
- Forward nested widget events through
widgetEventinstead of host-local event buses.
Forward operation/form mode and Reactive Determination metadata to each hosted form adapter. Step changes must cancel or isolate stale determination work so a result from a previous step cannot mutate the active form.
Wizard Rules
- Use
PraxisWizardFormComponentwhen the input is a higher-level wizard document rather than raw stepper config. - Treat
buildStepperConfig, wizard normalizers, migrations, validators, and form submission outputs as the canonical adapter path. - Preserve the current
zonesprecedence over legacyblockswhen both exist, avoiding duplicate rendered content. - Keep wizard output events such as submit/completed/custom action aligned with the wrapper contract. Do not force host code to reverse-engineer generated
StepperMetadata. - If the wizard cannot express a required flow, classify the gap before adding fields. Promote real contract gaps to the wizard/stepper owner, not a consuming app.
Authoring Rules
- Use
PraxisStepperConfigEditor, widget config editor, manifest capabilities, context packs, andPRAXIS_STEPPER_AUTHORING_MANIFESTfor governed authoring. - Keep Settings Panel apply/save/reset/reopen aligned with runtime config consumption.
- Keep i18n for authoring chrome and assistant labels in the package i18n path.
- When AI authors step changes, ensure operations target stable steps and preserve validation/persistence semantics.
- If a requested edit cannot be represented by the existing manifest or editor capability, classify it as
ja-suportado-so-ux,ja-suportado-mal-nomeado-ou-mal-materializado,suportado-parcialmente, orlacuna-real-de-contratobefore adding a contract.
Validation
Use the smallest reliable proof for the touched surface:
npm run build:praxis-stepperor the repo's equivalent focal build- focused specs for stepper runtime, config editor, wizard component, wizard adapter, normalizer, validator, and migrations
- dynamic-form integration validation when
steps[].form,resourcePath, submit, or form events change - Settings Panel round-trip validation when config editor behavior changes
- AI registry or authoring manifest validation when
ai/**, capabilities, manifest refs, or registry docs change - docs/playground validation when public examples or docs are updated
Report exactly what was validated and what remained unvalidated.
Companion Skills
Use
praxis-reactive-determinationsfor governed reactive definition/runtime and stale-result proof.Use
praxis-form-runtime-submitfor dynamic-form step integration, submit behavior, hooks, schema metadata, and resource path boundaries.Use
praxis-rich-content-runtimeandpraxis-rich-content-integration-adaptersfor step rich content, wizard legacy block convergence, andstepBlocksBeforeForm/stepBlocksAfterFormsemantics.Use
praxis-stepper-wizard-orchestrationfor linear navigation,serverValidate,validateStep,nextWithValidation, step form events, wizard adapter, submit/completed/customAction, preferences, and host workflow boundaries.Use
praxis-navigation-container-composition-eventsfor nested widgets, step-awareWidgetEventEnvelopepaths, dynamic page embedding, and composition links.Use
praxis-navigation-containers-ai-validationfor stepper AI manifests, registry projection, context packs, assistant turns, and cross-container validation.Use
praxis-navigation-agentic-registryfor stepper/wizard AI adapters, agentic turn flows, context packs, registry projection, and cross-container authoring consistency.Use
praxis-authoring-editorsfor Settings Panel editor round-trip.Use
praxis-core-composition-runtimefor nested widgets, widget events, composition links, and dynamic page materialization.Use
praxis-angular-i18n-governance,praxis-angular-public-api-governance,praxis-angular-docs-playgrounds, andpraxis-angular-validation-gateswhen the change touches their governed areas.