✅ PR preview is ready!

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

Summary

This PR adds support for empty query parameter values (?foo=) in widget URL binding, enabling clearable widgets (multiselect, pills, etc.) to represent their cleared state in the URL. The key changes include:

• Adding an explicit clearable flag to both backend (WidgetMetadata) and frontend (QueryParamBinding) binding structures
• Introducing is_empty_url_value() helper function to detect empty URL parameters
• Updating _seed_widget_from_url() to handle empty values based on the clearable flag
• Requiring clearable to be explicitly set when using bind='query-params'

Code Quality

The code is well-structured with clear function names and follows the Streamlit codebase conventions.

Frontend (WidgetStateManager.ts):

• Clean implementation of empty value handling in convertToUrlValue() (lines 1214-1269)
• The isEmptyValueValid() method is appropriately simplified to just return binding.clearable (lines 1277-1280)
• Good edge case handling in isDefaultValue() for cleared scalar widgets with empty array defaults (lines 1427-1435)

Backend (query_params.py, session_state.py, widgets.py):

• The is_empty_url_value() function correctly handles all edge cases including ["", ""] (lines 67-83 in query_params.py)
• Clean integration in _seed_widget_from_url() with early return for non-clearable widgets with empty values (lines 1019-1023 in session_state.py)
• Good validation in register_widget() requiring clearable when bind='query-params' (lines 143-148 in widgets.py)

Minor Observations:

• The parameter order change in registerQueryParamBinding puts clearable before the optional urlFormat and options, which is the correct pattern for required parameters.

Test Coverage

The test coverage is comprehensive and follows best practices:

Python Tests:

• test_parse_empty_string_values - Parameterized tests for all value types with empty string inputs
• test_is_empty_url_value - Comprehensive edge case coverage including mixed values like ["a", ""]
• test_seed_widget_with_empty_url_and_clearable_true/false - Both positive and negative assertions
• test_seed_widget_with_empty_list_and_clearable_true/false - List variant testing
• Tests include negative assertions (e.g., verifying URL is cleared when clearable=False)

TypeScript Tests:

• it("preserves empty value in URL when clearable=true") - Multiple widget types tested
• it("clears URL param when clearable=false") - Negative case covered
• it("clears URL when empty array equals default") - Hide-at-default behavior
• it("preserves empty array in URL when empty differs from default") - Differentiation from default
• Tests use both positive and negative assertions appropriately

E2E Tests:

• The PR notes E2E tests will be added when widget implementations use this feature, which is reasonable for infrastructure changes.

Backwards Compatibility

The changes maintain backwards compatibility:

1. clearable defaults to False in WidgetMetadata (common.py line 167), preserving existing behavior for widgets that don't support clearing
2. Explicit requirement for bind='query-params' - While clearable must now be explicitly set when using URL binding, this is an internal API that widget implementations control
3. Empty string reservation - The PR notes that empty string "" is reserved to mean "cleared/empty" rather than a literal option value. This is a reasonable trade-off documented in the PR description

Note: Existing widget code using registerQueryParamBinding will need to add the clearable parameter, but this is intentional to force explicit handling.

Security & Risk

No security concerns identified:

• No user input is executed or evaluated unsafely
• URL parameter parsing has proper validation and error handling
• Invalid values are cleared rather than causing errors

Low regression risk:

• The default behavior (clearable=False) preserves existing widget behavior
• Comprehensive test coverage reduces regression risk
• Changes are additive to the existing query param binding infrastructure

Accessibility

Not applicable - this PR focuses on URL state synchronization infrastructure and does not introduce any UI changes or frontend components that would affect accessibility.

Recommendations

1. Minor documentation suggestion: Consider adding a note to the widget development documentation explaining that "" (empty string) is reserved for representing the "cleared" state and cannot be used as a literal option value.

2. Type annotation improvement (optional): The clearable: bool | None parameter in register_widget() could use an overload or more specific type to indicate it's required when bind='query-params', though the runtime validation is sufficient.

3. Future consideration: When implementing this in specific widgets, ensure E2E tests cover the URL synchronization behavior comprehensively.

Verdict

APPROVED: This is a well-implemented infrastructure change with comprehensive test coverage. The design decision to require explicit clearable configuration is good API design that forces widget developers to consciously handle empty states. The code follows Streamlit conventions and includes appropriate documentation through docstrings.

This is an automated AI review using opus-4.5-thinking. Please verify the feedback and use your judgment.