The Static Onboarding Wizard is difficult to read

[balhar-jakub]

Describe the bug
The fields in the onboarding wizard for static onboarding has no borders, making it difficult to read and understand

Steps to Reproduce

1. Open the API Catalog
2. Click on Onboard New API
3. Click on Static Onboarding
4. This is the place where there are no borders

Expected behavior
Clear borders around the fields that can be filled by user

Screenshots

Details

• Version and build number: 3.5.0

API Catalog Web UI (in case of API Catalog issue):

• OS: MacOS
• Browser Chrome
• Version 149.0.7827.104

[balhar-jakub]

Problem Analysis — Static Onboarding Wizard Fields Lack Visible Borders (#4752)

Refined Problem Statement

When a system programmer opens the API Catalog and navigates to "Onboard New API → Static Onboarding," the input fields in the wizard have no visible borders or outlines. The fields — rendered as Material UI Input components with the standard (underline-only) variant — appear as bare text entry areas blending into the white background. The only visual cue that a field exists is a thin bottom underline and a label above it. This makes the form difficult to parse at a glance: users cannot quickly identify where one field ends and the next begins, and the interactive areas are not visually distinct from static descriptive text.

Real-world scenario: A system programmer configuring a new API service for static onboarding needs to fill in service ID, service name, base URL, route paths, catalog tile ID, tile title, and description. When scanning the form, the programmer's eyes land on descriptive text like "A unique identifier for the API (service ID):" and must then hunt for the corresponding input area below it — which looks indistinguishable from the description text because neither has a border box. This slows down data entry and increases the likelihood of skipping fields or entering data in the wrong field.

Current Architecture Touchpoints

The wizard UI is built with React and Material UI (v4.x, pre-MUI rebranding). The relevant components:

• WizardInputs.jsx — Renders all input fields for every wizard onboarding method (static, Spring, Micronaut, non-Java). Uses Material UI's Input component (standard variant, underline only) wrapped in a FormControl with className="wizardFormFields".
• wizard.css — Contains wizard-specific styling. Notably, there is NO CSS rule targeting .wizardFormFields or .MuiInput-root to add visible borders.
• wizard_static_categories.jsx — Defines the fields shown in the static onboarding path: URL (instanceBaseUrls), Routes (gatewayUrl, serviceRelativeUrl), Catalog info (catalogUiTileId), and Catalog UI Tiles (title, description).
• wizard_base_categories.jsx — Defines shared fields used across all onboarding methods: BASICS (serviceId, title), URL (description), AUTHENTICATION, and API INFO.

All affected fields share the same rendering path through WizardInputs.renderInputElement(), meaning the border problem is NOT specific to static onboarding — it affects ALL onboarding methods in the wizard.

Scope

In scope:

• Adding visible borders/outlines around all text input fields in the onboarding wizard across all onboarding methods (static, Spring, Micronaut, non-Java)
• Ensuring the border styling is visually consistent with the rest of the API Catalog UI design language
• Maintaining accessibility: borders should provide sufficient contrast and remain visible in all states (focus, hover, disabled, error)

Out of scope:

• Restructuring the wizard form layout (tab placement, field ordering, category organization)
• Changes to dropdown (Select) fields — these already have a distinct clickable appearance
• Changes to checkbox fields — these already have visible controls
• Changes to the YAML upload section
• Changes to the YAML preview/output pane
• Backend changes (this is purely a frontend CSS/component change)

Acceptance Criteria

1. All text input fields in the onboarding wizard (Input components) display a visible border/outline (minimum 1px solid, contrast ratio ≥ 3:1 against the background)
2. The border/outline distinguishes the input field from surrounding descriptive text and labels
3. Focus state provides an additional visual indicator (e.g., border color change or box-shadow glow) distinct from the default state
4. Disabled fields, if any, show a muted/appropriate border state
5. The border styling is visually consistent across all onboarding methods (static, Spring, Micronaut, non-Java)
6. No visual regressions: existing field labels, helper text, tooltips, validation messages, and the YAML preview pane remain unchanged in appearance
7. The change works across Chrome, Firefox, and Edge (the supported browsers for the API Catalog)

Design Questions for the Architect

1. Border approach: Should we switch from Material UI Input (standard variant) to OutlinedInput or TextField with variant="outlined", or add custom CSS borders to the existing Input component? Using the MUI outlined variant would be more idiomatic and maintainable, but may affect spacing and layout.

2. Select fields: Should dropdown (Select) fields also receive the same border treatment, or are they sufficiently distinct already?

3. Consistency: Does the rest of the API Catalog UI (Dashboard, Detail page, etc.) use outlined or standard inputs? The choice should be consistent with existing patterns.

4. Theme override vs. component-level: Should this be done as a global Material UI theme override (affecting all Input components in the API Catalog) or scoped only to the wizard (wizard.css or component-level styling)?

Constraints

• Must not break existing wizard functionality (field validation, YAML generation, pre-fill from uploaded YAML, catalog tile interference)
• Must not affect the YAML preview/output panel
• Material UI version is pinned (v4.x) — v5+ sx prop and updated theme APIs are not available
• The change should be minimal (CSS or component prop change, not a UI framework migration)

[balhar-jakub]

Solution Design — Static Onboarding Wizard Fields Lack Visible Borders (#4752)

Architecture Decision

Switch from Input (underline-only variant) to TextField with variant="outlined" in WizardInputs.jsx. This is the minimal, idiomatic change that aligns the wizard with the rest of the API Catalog UI while avoiding framework-level disruption.

Research Findings

1. Rest of API Catalog uses variant="outlined": Login.jsx uses TextField variant="outlined" and OutlinedInput. SearchCriteria.jsx uses TextField with InputProps={{ disableUnderline: true }}. The wizard is the ONLY component using bare Input (the underline-only variant).

2. No global MUI theme override exists: No createMuiTheme/createTheme found in the codebase. A theme-level change would be overkill — there's no theme to modify.

3. Select fields already have visible borders in MUI v4: The Select component (line 428) renders with a dropdown border by default in MUI v4 — no change needed there.

4. Material UI v4.12.4 is pinned: No v5+ APIs available. TextField variant="outlined" is fully supported in v4.

Proposed Change

Single file change: api-catalog-ui/frontend/src/components/Wizard/WizardComponents/WizardInputs.jsx

Replace lines 446-458 (the Input + FormControl + InputLabel + FormHelperText block) with a single TextField:

// BEFORE (lines 444-459 in renderInputElement):
const captionId = `my-helper${itemKey}`;
return (
    <Tooltip className="wizardTooltip" title={finalTooltip}>
        <FormControl className="wizardFormFields" disabled={disabled}>
            <InputLabel shrink>{question}</InputLabel>
            <Input
                id={itemKey}
                name={itemKey}
                value={value}
                onChange={(event) => this.handleInputChange(event, index)}
                aria-describedby={captionId}
            />
            <FormHelperText id={captionId}>{caption}</FormHelperText>
        </FormControl>
    </Tooltip>
);

// AFTER:
const captionId = `my-helper${itemKey}`;
return (
    <Tooltip className="wizardTooltip" title={finalTooltip}>
        <TextField
            id={itemKey}
            name={itemKey}
            value={value}
            onChange={(event) => this.handleInputChange(event, index)}
            aria-describedby={captionId}
            variant="outlined"
            fullWidth
            label={question}
            helperText={caption}
            disabled={disabled}
            InputLabelProps={{ shrink: true }}
            className="wizardFormFields"
        />
    </Tooltip>
);

Also add TextField to the Material UI imports (line 10-22):

import {
    Button,
    Checkbox,
    FormControl,
    FormControlLabel,
    FormHelperText,
    InputLabel,
    MenuItem,
    Select,
    Input,           // still needed — used as base component for Select in MUI v4
    TextField,       // NEW
    Tooltip,
} from '@material-ui/core';

Why This Approach

Decision	Rationale
TextField variant="outlined" (not CSS border)	Consistent with Login.jsx, Dashboard.jsx, SearchCriteria.jsx. Idiomatic MUI — leverages the framework's built-in outlined variant rather than fighting it with CSS overrides.
Component-level (not theme-level)	No global theme exists to modify. Component-level keeps the change surgical — only the wizard is affected.
Single TextField replaces 4 inner components	TextField in MUI v4 internally wraps FormControl + InputLabel + OutlinedInput + FormHelperText. Using one TextField is cleaner and less prone to version-specific DOM issues.
fullWidth prop	Matches the .wizardTooltip > span { width: 100% } layout already in wizard.css.
InputLabelProps={{ shrink: true }}	Preserves the existing behavior where labels are always shrunk above the input (the current code uses <InputLabel shrink>).
Select NOT changed	MUI v4 Select already renders with a visible border. Changing Select to variant="outlined" would be unnecessary scope creep.
Input import kept	Input is still used internally by MUI's Select component in v4. Removing the import could cause subtle issues.

Independent Areas (for PM decomposition)

This is a single-area change — one component, approximately 15 lines modified:

1. Area 1 — Implement outlined TextField in WizardInputs.jsx:
   • Import TextField from @material-ui/core
   • Replace the Input block with TextField variant="outlined" in renderInputElement()
   • Run npm test for WizardInputs tests to verify no regressions
   • Run npm start and visually verify borders appear on text inputs across all onboarding methods (static, Spring, Micronaut, non-Java)
   • Verify disabled fields render with muted border state (MUI outlined variant handles this natively)
   • Verify focus state shows additional visual indicator (MUI outlined variant provides blue border + box-shadow on focus by default)

Edge Cases and Risks

Risk	Mitigation
Enzyme shallow tests may assert on Input/FormControl component names	Tests that shallow-render and search by component name (wrapper.find('Input')) will need updating to wrapper.find('TextField'). Review WizardInputs.test.jsx for such assertions — from inspection, most tests use enzyme.shallow() to test logic (handleInputChange, etc.), not snapshot tests on component types. The first test uses screen.getByRole('textbox') which is component-agnostic.
YAML pre-fill (uploaded YAML populates fields)	The handleInputChange and value prop mechanism is unchanged — only the render component changes. Pre-fill via this.props.data.content[].value flows through the same data path.
Edge browser rendering	MUI v4 TextField variant="outlined" is cross-browser tested by the MUI team. The existing Login.jsx already uses this component and has been validated on Edge.
.wizardFormFields CSS compatibility	The existing CSS only has general .MuiFormControl-root { display: flex } — no style conflicts. TextField's internal FormControl receives the wizardFormFields className via MUI's className prop.
Tooltip wrapper — TextField is a block element	MUI TextField renders as a div with display: inline-flex. The existing .wizardTooltip > span { width: 100% } should still work. If layout shifts slightly, add display: block to .wizardFormFields.MuiFormControl-root in wizard.css.

Design Question Answers (from PM)

1. Border approach: Switch to TextField variant="outlined" — most idiomatic, maintainable, and consistent with existing patterns.

2. Select fields: No change needed. MUI v4 Select already renders with a visible dropdown border. The issue report only mentions text input fields being hard to read.

3. Consistency: The rest of the API Catalog (Login, Search) already uses TextField variant="outlined". The wizard is the outlier.

4. Theme override vs. component-level: Component-level. No global MUI theme exists, and even if one did, we'd want the change scoped to only the wizard's text inputs — not all inputs site-wide.

Acceptance Criteria Mapping

Criteria	How Addressed
Visible border on all Input fields	TextField variant="outlined" renders a 1px solid border (MUI default: rgba(0,0,0,0.23) — contrast ratio >3:1 on white background)
Border distinguishes from surrounding text	The outlined variant creates a clear visual box around the input area
Focus state indicator	MUI outlined variant changes border to primary blue + subtle box-shadow glow on focus
Disabled fields show muted state	MUI natively renders disabled TextField with greyed-out border and background
Consistent across all onboarding methods	All methods use the same WizardInputs.renderInputElement() — one change affects all
No regressions	Existing labels, helper text, tooltips, validation messages unchanged — only the input border is different
Cross-browser	MUI v4 outlined variant is tested on Chrome, Firefox, Edge

[balhar-jakub]

Decomposition — #4752 (Static Onboarding Wizard Fields Lack Visible Borders)

The architect's solution design identifies a single independent area — no multi-step decomposition needed.

Implementation plan (1 engineer task)

Area 1 — Replace Input with TextField variant="outlined" in WizardInputs.jsx

• File: api-catalog-ui/frontend/src/components/Wizard/WizardComponents/WizardInputs.jsx
• Scope: ~15 lines changed in renderInputElement()
• Import: Add TextField to existing @material-ui/core imports
• Change: Replace FormControl + InputLabel + Input + FormHelperText block with a single TextField variant="outlined" (same props: label, helperText, disabled, fullWidth, InputLabelProps={{ shrink: true }})
• Select fields: No change — MUI v4 Select already renders with visible border
• Input import: Kept (still used internally by MUI v4 Select)

Task flow

[Step 4a] Engineer → implement → [Step 5-6] Architect → validate + PR + review → [Step 7] QA → [Step 8] Security → [Step 9] PM notify

One engineer task, no parallel workstreams — sequential pipeline from here.

[balhar-jakub]

Decomposition — #4752 (Static Onboarding Wizard Fields Lack Visible Borders)

Single-area change — one engineer task created.

[Step 4a] Engineer — Replace Input with TextField variant="outlined" in WizardInputs.jsx renderInputElement().

• File: api-catalog-ui/frontend/src/components/Wizard/WizardComponents/WizardInputs.jsx
• Scope: ~15 lines changed
• Flow: Engineer → Architect (validate + PR + review) → QA → Security → PM notify

Pipeline task created. Ready for implementation.