feat(cards,modals): Chart, Table options, tooltips, Card width, DateInput/NumberInput, dispatch_action (#202)

[patrick-chinchill]

Summary

This PR ports the platform-neutral card and modal builder additions from chat@4.34–4.41. It covers only the builders, TypedDicts, fallback text and exports. Adapters render the new fields in #212 (Slack) and #220 (Teams).

• cards.py
  • Chart(title=, chart=) builder and chart alias.
  • New types: ChartSegment, ChartDataPoint, ChartSeries, PieChartDefinition, SeriesChartDefinition (x_label / y_label), ChartDefinition and ChartElement. ChartElement is added to CardChild.
  • chart_element_to_fallback_text() renders the title followed by an ASCII table.
    • Pie charts get Label / Value rows.
    • Series charts get one row per category and one column per series. Each point is looked up by category label, and a missing point is an empty cell.
  • The fallback text is wired into card_child_to_fallback_text and shared/card_utils.py::_child_to_fallback_text.
  • Table() gains caption, page_size, widths, vertical_align and grid_lines, plus grid_style, with the new TableVerticalAlignment and TableGridStyle types.
  • Button() / LinkButton() gain tooltip. Card() gains width (CardWidth).
• modals.py
  • New DateInput() / NumberInput() builders, their TypedDicts and the date_input / number_input aliases. Both types are added to VALID_MODAL_CHILD_TYPES and ModalChild.
  • dispatch_action on Select() / RadioSelect().
• chat_sdk/__init__.py: every new builder, alias and type is exported and listed in __all__.

Upstream commits mapped

Upstream	Release	Ported here
4717a384 (#696)	chat@4.34.0	Core slice: Chart* types, Chart(), chartElementToFallbackText, Table caption / pageSize
0153a39f (#757)	chat@4.36.0	DateInput / NumberInput elements and builders, valid modal children
4a0b5c0c (#895)	chat@4.40.0	CardWidth, Card.width, tooltip on Button / LinkButton (the callback-URL half belongs to #194)
84219537 (#906)	chat@4.41.0	Core slice: TableVerticalAlignment, TableGridStyle, widths / verticalAlign / gridLines / gridStyle
ad904325 (#952)	chat@4.41.0	Core slice: dispatchAction on Select / RadioSelect
929878b5 (#838)	chat@4.39.0	N/A (JSX only). LinkButton(id=...) already exists. Recorded in the jsx-runtime row of docs/UPSTREAM_SYNC.md

Tests ported

Every upstream test name listed in the issue now exists:

• tests/test_cards.py (11 tests)
  • Card: "creates a card with a width hint"
  • Button: "creates a button with a tooltip"
  • LinkButton: "creates a link button with a tooltip"
  • Table (4): "creates a table with caption and pageSize", "leaves caption and pageSize undefined when omitted", "carries the Teams-only rendering options", "leaves the rendering options undefined when omitted"
  • Chart (2): "creates a pie chart", "creates a line chart with series and categories"
  • Chart fallback text (2): "renders pie chart data as a labelled ASCII table", "renders series chart data with one column per series". These assert the exact output string, not just containment.
• tests/test_modals.py
  • "preserves dispatchAction=%s", parametrized over [Select, RadioSelect] × [True, False, None]
  • DateInput (2 tests)
  • NumberInput (3 tests), including "should keep a zero initial value", which also checks min=0, max=0 and decimal=False
  • "should keep valid child types": the existing Python filter test was renamed and extended with DateInput / NumberInput, matching upstream's updated test.
• Python-specific tests
  • Number formatting is parametrized over 13 cases: 45.0→45, 1.5, -0.0→0, 0.00001, 1e-7, 1e21→1e+21, 10**21, NaN, Infinity, and others.
  • A missing series point and a missing x_label render as empty cells.
  • card_to_fallback_text and the adapter-shared card_to_fallback_text both include the chart.
  • Root re-exports (tests/test_root_reexports.py).
• Skipped (JSX only, documented): "should convert a DateInput/NumberInput react element", the fromReactModalElement copy of "preserves dispatchAction=%s", and the jsx-runtime tooltip/width cases.

Fidelity (--report-target at chat@4.41.1, scripts/fidelity_target.json regenerated):

Delta vs committed report (HEAD): missing 282 -> 265 (-17)
  packages/chat/src/cards.test.ts: 31 -> 20 (-11)
  packages/chat/src/modals.test.ts: 34 -> 28 (-6)

Two notes on the modals numbers:

• They show -6 rather than -7 because the renamed test_valid_children_pass_through used to be fuzzy-matched to the unrelated JSX test "should pass through plain modal children", which now correctly reports as missing.
• The report still lists [DateInput] / [NumberInput] "should create with required fields" / "should include optional fields" as missing. Those names are shared with TextInput / ExternalSelect, and the matcher counts names without regard to which describe block they belong to. The DateInput and NumberInput tests are ported; the remaining misses are the TextInput / ExternalSelect gaps tracked in Extend verify_test_fidelity.py MAPPING to cover all packages/chat/src/*.test.ts #78.

Strict at the pin: 733/733 (unchanged).

Validation

• ruff check and ruff format: pass
• audit_test_quality: 0 hard failures
• --check-docs: pass
• --strict at chat@4.31.0: pass
• pytest: 5604 passed, 13 skipped (main baseline: 5561 passed)
• pyrefly: 0 errors

Divergences

None are added to the non-parity table. Notes:

• Number formatting in the chart fallback. Values go through _js_number_to_string, which implements ECMAScript Number::toString. The goal is to match upstream String(v) output ("Kit Kat | 45" for 45.0). I checked it against Node String() on 80,000 random doubles and found no mismatches. The only differences are that int values below 1e21 render exactly (JS rounds them above 2**53) and a None value renders as "". Other numeric types (Decimal from Postgres NUMERIC, Fraction, NumPy scalars) are converted to int / float first, so Decimal("45.00") renders "45". This is recorded in docs/UPSTREAM_SYNC.md under "Card and modal builders".
• Omitted keys. Builders omit keys whose argument is None, where upstream sets them to undefined. This is the repo's standard convention (hazard fix: launch must-fix items — security, perf, docs #7), not a new divergence.

Consumer impact

The change is additive. With the new options unset, the output of Card(), Table(), Button(), LinkButton(), Select() and RadioSelect() is byte-identical to before; tests assert this for Table, Card, the tooltips and dispatch_action.

• Charts become text for now. Card fallback text now includes charts. Slack, Teams, Google Chat, Discord, GitHub, Linear and Twilio post a chart as its title plus an ASCII table, as upstream adapters without native charts do. Messenger, WhatsApp and Telegram ignore it, as upstream does.
• Interim Slack gaps until [4.41/SL7] Slack cards & modals: data_table / data_visualization blocks, datepicker, number_input, selection change events #212.
  • modal_to_slack_view raises ValueError for date_input / number_input.
  • The SDK-free slack.blocks primitives (card_to_slack_blocks and card_to_slack_fallback_text) raise SlackBlockError for a chart child.
  • The Slack adapter posts charts as a plain mrkdwn section rather than a native data_visualization block.
  • dispatch_action, caption and page_size are ignored.
• No Teams rendering yet ([4.41/T5] Teams cards & dialogs: Adaptive Card 1.5 Table, tooltips, width, Input.Date/Number #220).
• Interim callback-URL gap until [4.41/CB] Callback tokens: consume once, bind to conversation, shorter TTL, preserve button fields #194 (PR fix(callback-url): single-use, conversation-bound callback tokens with 7-day TTL (#194) #256). A Button(callback_url=..., tooltip=...) loses tooltip when the URL is swapped for a token, because callback_url.py still copies a fixed key list. fix(callback-url): single-use, conversation-bound callback tokens with 7-day TTL (#194) #256 ports upstream's keep-every-field copy. No adapter renders tooltip before [4.41/T5] Teams cards & dialogs: Adaptive Card 1.5 Table, tooltips, width, Input.Date/Number #220.

Closes #202
Part of #184

Merge gate

Reviewer findings (2 independent reviewers, 4 findings), all fixed in 4f294d2:

• Fixed (docs): tooltip dropped from callback_url buttons. Real. The fix, the keep-every-field copy, is owned by [4.41/CB] Callback tokens: consume once, bind to conversation, shorter TTL, preserve button fields #194 (PR fix(callback-url): single-use, conversation-bound callback tokens with 7-day TTL (#194) #256, which rewrites the same hunk), so it is not duplicated here. The gap is now documented in the CHANGELOG bullet and in the docs/UPSTREAM_SYNC.md "Card and modal builders" section.
• Fixed (code + tests): _js_number_to_string rendered Decimal("45.00") as "45.00" and Fraction(1, 2) as "1/2". Non-int Integral values are now converted to int, and Decimal or other Real values to float, before formatting. Three new parametrized cases fail without the fix.
• Fixed (tests): truthiness mutations on DateInput / NumberInput optional / placeholder and on Table page_size survived. Added test_falsy_optional_and_placeholder_are_kept and test_keeps_empty_caption_and_zero_page_size. All five modal mutations and the caption / page_size / widths mutations are now caught.
• Fixed (docs): the claim that every adapter falls back to chart text was too broad. The docs and CHANGELOG now name the adapters that render a chart as text, and state that Messenger and WhatsApp drop chart children, as upstream does (cards.ts default: return []). They also note that slack.blocks card_to_slack_fallback_text raises for charts until [4.41/SL7] Slack cards & modals: data_table / data_visualization blocks, datepicker, number_input, selection change events #212.

gpt-6-astra: 1 round, on 4f294d2. The verdict was clean: "No actionable regressions found within the documented core-only scope."

Bots: CodeRabbit was rate-limited and posted no review comments. There were no Gemini comments.

CI on 4f294d2: all green (Lint & Type Check, test 3.12 and 3.13, CodeQL).

Local validation: all green: ruff, audit (0 hard failures), --check-docs, --strict 733/733 at chat@4.31.0, pytest 5604 passed, pyrefly 0 errors. Fidelity: Delta vs committed report (HEAD): missing 265 -> 265 (+0). These are Python-only tests, and the total stays at 265 against chat@4.41.1.

[coderabbitai]

Warning

Review limit reached

Next included review available in 58 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 3010b1aa-18dc-4b64-abd9-e6da27828e01

📥 Commits

Reviewing files that changed from the base of the PR and between 4817dc0 and 4f294d2.

📒 Files selected for processing (10)

• CHANGELOG.md
• docs/UPSTREAM_SYNC.md
• scripts/fidelity_target.json
• src/chat_sdk/__init__.py
• src/chat_sdk/cards.py
• src/chat_sdk/modals.py
• src/chat_sdk/shared/card_utils.py
• tests/test_cards.py
• tests/test_modals.py
• tests/test_root_reexports.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[patrick-chinchill]

Merge gate: CI green (Analyze (actions), Analyze (python), CodeQL, Lint & Type Check, test (3.12), test (3.13)); local Codex review (gpt-6-astra, xhigh, --base origin/main) on 4f294d2: "No actionable regressions found within the documented core-only scope. Targeted card, modal, and export tests passed, along with type checking, linting, and strict upstream test-fidelity verification."; 1 recorded astra round on the final HEAD (earlier review feedback addressed in 4f294d2); origin/main already an ancestor, so no re-merge was needed; CodeRabbit rate-limited (no review posted), no human reviews. Merging with --admin (Protect Main requires a code-owner approval).