✅ 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.

✅ PR preview is ready!

Summary

This PR adds a new delta_description parameter to st.metric(), allowing users to display a short descriptive text (e.g., "month over month", "vs. last quarter") next to the delta value. The implementation spans the full stack:

• Proto: New string delta_description = 12 field in Metric.proto.
• Python backend (lib/streamlit/elements/metric.py): New delta_description: str | None = None keyword argument, passed through to the proto.
• Frontend (Metric.tsx, styled-components.ts): New StyledDeltaContainer and StyledDeltaDescription components to render the description. Adds accessibility support via aria-describedby linking the delta to its description.
• Tests: 3 Python unit tests, 7 TypeScript unit tests, and E2E coverage integrated into existing test cases.

Also includes a minor refactor of the delta_arrow mapping logic to use a dictionary lookup (_DELTA_ARROW_TO_PROTO) consistent with the existing _DELTA_COLOR_TO_PROTO pattern.

Code Quality

Python backend (lib/streamlit/elements/metric.py):

• Clean, well-structured implementation. The delta_description parameter is keyword-only (after the *), which is correct.
• The _DELTA_ARROW_TO_PROTO dictionary refactor is a nice improvement that follows the same pattern as _DELTA_COLOR_TO_PROTO.
• The docstring for delta_description is clear and follows the existing parameter documentation style.
• The parameter defaults to None and only sets the proto field when non-None, which is the correct protobuf pattern (empty string is the default for proto3 string fields).

Frontend (Metric.tsx):

• Good use of useId() for generating unique ARIA IDs -- this is the React-recommended approach.
• The aria-describedby pattern correctly links the delta badge to the description for screen readers, and is only set when deltaDescription exists.
• The conditional rendering logic (deltaExists || deltaDescription) correctly handles the case where delta_description is provided without a delta value.
• The title attribute on StyledDeltaDescription provides a native browser tooltip for truncated text, which is a thoughtful UX touch.

Styled components (styled-components.ts):

• StyledDeltaContainer uses flexbox row layout with proper overflow handling.
• StyledDeltaDescription uses flexShrink: 1 + minWidth: 0 which correctly allows truncation while the delta badge (flexShrink: 0) stays fixed-width.
• Text truncation with textOverflow: "ellipsis" is handled at both the container and the nested markdown levels.
• Gap uses 0.5em (relative unit), which follows the guideline of avoiding pixel sizes.

Minor observations:

• The paddingBottom: theme.spacing.threeXS on StyledDeltaContainer (line 134) introduces bottom padding for the delta row. Previously this padding was absent since the delta badge was a standalone element. This is a subtle visual change but should be fine since it appears intentional for the new layout.

Test Coverage

Python unit tests (lib/tests/streamlit/elements/metric_test.py):

• 3 new tests covering: default None behavior, with delta, and without delta. All have docstrings.
• The tests correctly verify the proto field values.
• Good coverage of the key scenarios (with delta, without delta, default).

Frontend unit tests (Metric.test.tsx):

• 7 new tests in a well-organized describe("Delta description") block.
• Tests cover: rendering with delta, rendering without delta, not rendering when absent, correct styling, title attribute, aria-describedby link, and ensuring no problematic ARIA patterns.
• Good use of RTL queries (getByTestId, queryByTestId) following the correct patterns for presence/absence assertions.
• The aria-describedby test properly verifies the ID linkage between the delta and description elements.

E2E tests (e2e_playwright/st_metric_test.py):

• Delta description is tested across multiple existing test functions (not as separate tests, which is efficient per E2E best practices):
  • test_second_metric_in_first_row verifies "since open" text.
  • test_third_metric_in_first_row verifies visibility with long description.
  • test_border verifies delta_description with material icon.
  • test_code_in_help_shows_up_properly verifies "year over year" text.
  • test_custom_delta_color_render verifies "month over month" with yellow delta.
• Good approach of adding delta_description to existing E2E test scenarios rather than creating separate test scripts.
• Snapshot tests will capture the visual appearance across themes and browsers.

Coverage gap (minor): No typing test file exists for st.metric in lib/tests/streamlit/typing/. However, the PR description doesn't mention adding one, and this appears to be a pre-existing gap not introduced by this PR.

Backwards Compatibility

• Fully backwards compatible. The delta_description parameter defaults to None, and when None, the proto field is not set (defaults to empty string in proto3), so existing code is unaffected.
• The proto field uses field number 12 (next available), which is correct.
• The _DELTA_ARROW_TO_PROTO refactor is a pure internal refactor with identical behavior.
• The new StyledDeltaContainer wrapper around the delta area doesn't change the rendering when deltaDescription is absent because the container condition (deltaExists || deltaDescription) and the inner condition deltaExists preserve the original behavior.
• The addition of flexShrink: 0 to StyledMetricDeltaText and the wrapper StyledDeltaContainer with paddingBottom may cause minor visual differences for existing metrics (the delta badge is now wrapped in a flex container with some bottom padding). This is captured in the snapshot updates.

Security & Risk

• No security concerns. The delta_description is rendered through StreamlitMarkdown with allowHTML={false}, preventing XSS.
• The title attribute uses the raw deltaDescription string, but title attributes are inherently safe (HTML-escaped by React).
• No risk of injection since all user-provided strings go through the protobuf serialization layer.

Accessibility

• Well implemented. The aria-describedby pattern correctly associates the delta value with its description for screen readers.
• useId() generates stable, unique IDs that work correctly with React's server-side rendering and concurrent features.
• The title attribute provides a native tooltip for sighted users on hover, which helps when the description is truncated.
• The test at line 745 (does not use container aria-label fallback for markdown deltas) correctly ensures no over-engineering of ARIA patterns that could confuse screen readers.
• One minor observation: when only deltaDescription is provided without delta, the description renders alone. In this case, the description has no aria-describedby target since there's no delta element. This is acceptable since the description itself is readable by screen readers via its text content.

Recommendations

No blocking issues found. The following are minor, non-blocking suggestions:

1. Consider input validation for delta_description: The backend currently accepts any string (including empty strings). An empty string "" would render the StyledDeltaDescription container with no visible text. Consider treating "" the same as None in the backend (i.e., if delta_description is not None and delta_description != ""), or document that empty strings are a no-op.

2. Consider adding a typing test: While this is a pre-existing gap, adding a lib/tests/streamlit/typing/metric_types.py file with assert_type checks for the new delta_description parameter would improve type safety coverage.

3. Minor CSS note: The StyledDeltaDescription nested CSS selectors ("& > div" > "& > p") duplicate the truncation pattern found in StyledTruncateText. If this pattern is reused further in the future, it might be worth extracting into a shared mixin. This is very low priority.

Verdict

APPROVED: Well-implemented feature with thorough test coverage, good accessibility support, and full backwards compatibility. The code follows existing patterns and conventions throughout the stack.

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

@cursor review

Consolidated Code Review: delta_description support for st.metric

Summary

This PR adds a new delta_description parameter to st.metric() that displays descriptive text next to the delta value (e.g., "month over month", "vs. last quarter"). The implementation spans the full stack:

• Protobuf: New delta_description field (field number 12) added to Metric.proto.
• Python backend: New optional delta_description parameter with docstring, truthy-check validation, and proto serialization. Also refactors delta_arrow mapping to a dictionary lookup (_DELTA_ARROW_TO_PROTO), consistent with the existing _DELTA_COLOR_TO_PROTO pattern.
• Frontend: New StyledDeltaContainer and StyledDeltaDescription styled components. The description renders next to the delta badge with ellipsis overflow, title attribute for hover, and aria-describedby ARIA linkage.
• Refactoring: Moves text truncation from a StyledTruncateText wrapper into a reusable truncate prop on StreamlitMarkdown, simplifying metric JSX and benefiting future consumers.

Reviewer Consensus

Both reviewers (gpt-5.3-codex-high and opus-4.6-thinking) approved the PR unanimously. There were no disagreements on any aspect of the review. Below is a synthesis of their findings.

Code Quality

Agreement: High quality, follows existing patterns.

Both reviewers found the code well-structured and consistent with codebase conventions:

• The _DELTA_ARROW_TO_PROTO dictionary refactoring is a clean improvement.
• The truncate prop on StreamlitMarkdown is a good abstraction that eliminates wrapper components and improves reusability.
• Styling uses proper flexbox layout with overflow: hidden, gap, flexShrink: 1, and minWidth: 0 for robust truncation behavior.
• Concerns (rendering vs. styling) are well-separated across files.

Minor observation (opus-4.6-thinking): The truthy check if delta_description: on line 418 of metric.py silently discards empty strings. This is intentional and tested (confirmed by metric_test.py line 608), but using if delta_description is not None: would be more explicit and consistent with how format is handled on line 415. This is a stylistic point, not a blocker.

Test Coverage

Agreement: Comprehensive and well-structured.

Both reviewers highlighted the thorough multi-layer testing:

• Python unit tests: 3 new parameterized test cases covering None, empty string, with-delta, and without-delta scenarios.
• Frontend unit tests: 7 new tests covering rendering states, styling/title behavior, and accessibility wiring, with good positive + negative assertion patterns.
• StreamlitMarkdown tests: 2 new tests validating the truncate prop in both true/false states.
• E2E tests: delta_description tested across multiple existing test functions with varying lengths, material icons, and layout contexts. Snapshots cover light/dark themes and all three browsers.

Backwards Compatibility

Agreement: Fully backwards compatible, no breaking changes.

• delta_description defaults to None; existing calls are unaffected.
• Protobuf field 12 is additive; older frontends ignore it, newer frontends handle its absence via proto3 defaults.
• The truncate prop defaults to undefined/false; existing StreamlitMarkdown usages are unaffected.
• StyledTruncateText removal is purely internal.
• _DELTA_ARROW_TO_PROTO refactoring is a behavioral no-op.

Security & Risk

Agreement: No security concerns; low regression risk.

• delta_description is rendered through StreamlitMarkdown with allowHTML={false}, preventing XSS.
• title attribute and aria-describedby IDs (via React useId()) are safely handled.
• No dangerouslySetInnerHTML, eval, or other dangerous patterns.
• The truncate refactoring changes DOM structure slightly (removes a wrapper div), but updated E2E snapshots across all browsers confirm visual equivalence. A follow-up commit (925105e10) addressed an extra height regression from lineHeight: "normal".

Accessibility

Agreement: Good accessibility implementation.

• aria-describedby links the delta element to its description for screen readers.
• title attribute provides native tooltips for truncated text.
• useId() generates unique ARIA IDs, avoiding collisions.
• When deltaDescription is provided without a delta value, the description renders as regular accessible text content (no broken ARIA reference).

Recommendations

1. Consider is not None check (minor, non-blocking): Using if delta_description is not None: instead of if delta_description: on line 418 of metric.py would be more explicit and consistent with the format parameter handling. Both reviewers noted this is not a blocker.

2. Add typing test as follow-up (both reviewers agreed): Consider adding a typing-focused test for st.metric(..., delta_description=...) in lib/tests/streamlit/typing/ to improve type safety coverage.

3. Note snapshot churn in PR description (gpt-5.3-codex-high): If not already done, note that the broad snapshot updates are expected from truncation/line-height adjustments to ease reviewer verification.

Verdict

APPROVED

Both reviewers approved unanimously. The feature is coherently implemented across backend, frontend, and protobuf with thorough test coverage, good accessibility practices, full backwards compatibility, and clean code that follows existing patterns. No blocking issues were identified.

Consolidated review by opus-4.6-thinking.