studio-adding-robot-form-ui-fields

# Adding Robot Form UI Field Components Add new robot-form controls as explicit `robot_payload_ui(...)` item kinds so plugin authors can opt in without Studio-specific React code in plugins. Read these first: - `application/docs/robot-plugins.md` - `application/docs/explanation/robot-plugin-architecture.md` - `physicalai/packages/physicalai-studio-plugin/src/physicalai_studio_plugin/ui_schema.py` - `application/ui/src/features/robots/robot-form/robot-schema/schema-form.tsx` ## Workflow 1. **Define the UX contract and ownership model.** - Pick an explicit `kind` name (for example `calibration`) and required item shape (`name`, optional `label`, optional `description`, etc.). - Keep ownership semantics aligned with existing controls: item-owned fields must not also be rendered as `field` or owned by another item. - Prefer explicit opt-in (`kind`) over heuristic detection in the UI. - Done when: you can describe exactly which payload field(s) the item owns and how plugins enable it. 2. **Add SDK typing + validation for the new item kind.** - Edit `physicalai/packages/physicalai-studio-plugin/src/physicalai_studio_plugin/ui_schema.py`: - add a new `TypedDict` for the item kind, - include it in `RobotUiItem` union, - validate required fields and field type constraints, - enforce ownership conflict checks. - Keep validation errors precise and actionable for plugin authors. - Done when: invalid metadata fails `validate_robot_payload_ui(...)` with a clear error and valid metadata passes. 3. **Render the field in SchemaForm using kind-based dispatch.** - Add a component under `application/ui/src/features/robots/robot-form/robot-schema/components/`. - Integrate it in `application/ui/src/features/robots/robot-form/robot-schema/schema-form.tsx` in `SchemaFormItem` next to existing `connection` / `ip_address` handling. - Reuse shared visibility rules; do not create ad-hoc visibility behavior for a single kind. - Honor `robot_field_ui({"advanced_configuration": True})` and required/optional behavior consistently. - Done when: rendering is triggered only by explicit `kind` items and matches default form behavior for advanced/required fields. 4. **Implement robust field UX and payload updates.** - Parse and validate user input in the component before mutating payload. - Show clear inline errors for invalid input. - Keep labels/descriptions visually consistent with existing form controls. - For structured payloads (like calibration maps), include a compact preview so users can verify imported values. - Done when: happy path updates payload correctly, invalid path is recoverable, and the control is readable in dense forms. 5. **Adopt the new kind in built-in catalog payloads.** - Update backend payload UI metadata in the relevant catalog file(s), e.g. `application/backend/src/robots/catalog/so101.py`. - Replace generic `field` usage with the new item kind where appropriate. - Keep business semantics in field descriptions (for example: when a provided calibration bypasses guided calibration). - Done when: `/api/robots/catalog/{type}/schema` emits the expected `x-physicalai-ui` item and Studio renders the new control. 6. **Add tests at all affected layers.** - UI component tests (new file): - `application/ui/src/features/robots/robot-form/robot-schema/components/<new-field>.test.tsx` - cover parse success, parse failure, required/optional markers, preview/sorting, and clear/reset behavior. - Schema form integration tests: - `application/ui/src/features/robots/robot-form/robot-schema/schema-form.test.tsx` - assert kind-driven rendering, advanced visibility, and payload wiring. - Feature-level tests where used (example bimanual forms): - `application/ui/src/features/robots/robot-form/catalog/*.test.tsx` - Plugin SDK contract tests: - `physicalai/packages/physicalai-studio-plugin/tests/test_contracts.py` - cover valid item metadata, type errors, missing fields, and ownership conflicts. - Done when: all changed test suites pass locally. 7. **Update docs and communicate to plugin authors.** - Update public docs: - `application/docs/robot-plugins.md` (supported item kinds + usage snippet) - `application/docs/explanation/robot-plugin-architecture.md` (architecture list of supported kinds) - Add a handoff note for plugin maintainers when behavior changes materially: - `application/docs/handoff-<feature>.md` (expected JSON format, migration guidance, limitations) - Include copy-paste plugin snippet showing new `robot_payload_ui` usage. - Call out rollout notes explicitly for affected plugin owners (for example SO101, BimanualSO101, LeKiwi): - what to change, - what stays backward compatible, - what validation/runtime behavior changes. - Done when: plugin authors can adopt the feature without reading UI source code. ## Verify From `application/ui/`: ```bash npm run type-check npm run test:unit -- src/features/robots/robot-form/robot-schema/components/<new-field>.test.tsx npm run test:unit -- src/features/robots/robot-form/robot-schema/schema-form.test.tsx ``` From the runtime repo root (or environment where plugin tests run): ```bash uv run python -m pytest packages/physicalai-studio-plugin/tests/test_contracts.py ``` When skill files changed: ```bash python3 .github/scripts/skills/agent_skills.py sync python3 .github/scripts/skills/agent_skills.py validate ``` ## References - `application/ui/src/features/robots/robot-form/robot-schema/schema-form.tsx` - `application/ui/src/features/robots/robot-form/robot-schema/components/connection-field.tsx` - `application/ui/src/features/robots/robot-form/robot-schema/components/ip-address-field.tsx` - `application/ui/src/features/robots/robot-form/robot-schema/components/calibration-field.tsx` - `physicalai/packages/physicalai-studio-plugin/src/physicalai_studio_plugin/ui_schema.py` - `physicalai/packages/physicalai-studio-plugin/tests/test_contracts.py`