Refactor teal.reporter (part 2)

[donyunardi]

Continuation of #104

From comments: #104 (comment)

---

Done

teal.modules.general

• Rewrote example modules to align with the new design
  👉 Redesign of teal.reporter Cards teal.modules.general#862
• Ensured reproducibility of reports
  👉 Improve the Reproducibility Mechanisms and Code Display in Report Output teal.reporter#280
• Extended teal.code::eval_code and teal.code::get_code to support code labelling
  👉 introduce label to eval_code, within and get_code teal.code#248

teal

• Exposed reporter as an init parameter to allow global disabling
  👉 [Feature Request]: Globally disable reporter feature teal#871
• Added reporter$set_template() for setting custom templates when users add cards
  👉 [Feature Request]: User-defined templates for reports teal.reporter#271
• Introduced modify_teal_module_output() so devs can modify or disable report cards
  👉 [Feature Request]: Allow app dev to supply card function. teal.modules.general#736
  👉 Also allows disabling reporter on a per-module basis
  👉 optional reporter in the independent teal modules teal#678
• Added add_document_button_server() with a standalone "+" button (no more old buttons in modules)
  👉 https://github.com/insightsengineering/coredev-tasks/issues/545
  👉 Redesign of teal.reporter Cards teal#1499 (comment)
• Added Editor module
  • PR 👉 Edit Functionality for the Report Previewer module teal.reporter#312
  • User request 👉 Showcase functionality of editor for report previewer teal.reporter#306

teal.reporter

• Added report_document() and edit_report_document() for the new ReportDocument S3 class
• Extended Previewer and Reporter to support ReportDocument
• Deleted private Rendered class
• Refactored:
  • report_render_and_compress
  • report_render
  • Added load report button to previewer buttons

---

🔜 TODOs

teal

• [vignette] Create vignette for modify_teal_module_output() teal#1523 - Documentation (13 hours)
  • Add documentation and a vignette for modify_teal_module_output()
• Create wrapper for modify_teal_module_output and export them teal#1521 - Wrappers (13 hours)
  • Consider which wrappers to expose for modify_teal_module_output() (e.g. disable_teal_module_report_card)
• Viewing the structure of the report document for a module teal#1522 - Print
  • Consider extending print of modules to include report_card body
    👉 Redesign of teal.reporter Cards teal.modules.general#862 (comment)

teal.reporter

• Fix known issues:
  • [DONE] [Feature Request]: Dealing with duplicate card name teal.reporter#313
    Do not allow to create cards with the name that already is used (we aim not to allow user to input the same name, card name is the same with card title, UI needs to be updated to handle this assertion as well in the modal when we add the card) 5 hours
• [Documentation] Vignette for new feature teal.reporter#314
  Write a vignette covering new features (explain the new card object (ReportDocument), tutorial, and how they can be extended in teal, etc) - 8 hours
• Soft Deprecate old methods teal.reporter#315
  Soft Deprecate old methods (possibly just 1 parent method, ContentBlock method. we may need to create an initialization method on the parent class and put the deprecation warning there, make sure to test) - 3 hours
• Ensure R CMD Check is green teal.reporter#316
  Fix failing tests (R CMD check fails: unit test, examples, package metadata, a bit of everywhere) - 13 hours
• [DONE] Further refactoring:
  • Reuse opportunities between download_report_button_srv and reporter_previewer_srv teal.reporter#317
    Check for code reuse opportunities between download_report_button_srv and reporter_previewer_srv (8 hours)
    👉 Redesign of teal.reporter Cards teal.reporter#307 (comment)
• Editor improvements
  • [DONE] [Feature Request]: Rearrange the edit/delete button teal.reporter#318
    moving card edit/delete buttons somewhere else (UI to find a better place for the buttons) - 5 hours
  • [Feature Request]: Allow to edit card title teal.reporter#319
    allow to edit card title (make sure that the card name still unique, ) - 8 hours
    👉 Edit Functionality for the Report Previewer module teal.reporter#312 (comment)
  • allow to delete blocks - solution is being rewrite with a better approach, will need to circle back on this.
• Explore other alternative for the Add to Report button teal#1533
• Add support for html type of card content teal.reporter#203
• Create methods to support gtsummary outputs teal.reporter#323
• Can only add 1 card to current refactor teal.reporter#324
• [Feature Request]: c.teal_card should preserve metadata teal.reporter#339
• [Feature Request]: Implement c.teal_report method teal.reporter#340
• make a code_chunk preview collapsible and collapsed by default
• make sure that checking-out "include code chunks" in the reporter-download module excludes code chunks in downloaded document see this commit

Module Packages

• Rewrite report cards based on the new design in:
  • Documentation on module's return teal.modules.general#875 (3 hours, only when the teal.reporter is ready)
  • Rewrite reporter code in modules teal.modules.general#874 - 15 modules (23 hours)
  • Rewrite reporter code in modules teal.modules.clinical#1376 - 36 modules (54 hours)
  • Rewrite reporter code in modules teal.osprey#299 - 10 modules (15 hours)
  • Rewrite reporter code in modules teal.goshawk#342 - 6 modules (9 hours)
  • Rewrite reporter code in modules teal.modules.hermes#413 - 8 modules (12 hours)
  • remove filter_panel_api object from server functions from modules

---

Future Plans

• [Research] Automatic Show R Code button creation teal#1534
• [Question]: How to return report to teal? teal#1526

• Expose Show R Code as a button next to Add to Report button
  • This will require the module to return teal_data/qenv
  • This will require srv_teal_module to depend on whether module returned teal_data/qenv to show the button
  • This will allow to modify the teal_data/qenv returned by the module, so that Show R Code can be also customized or nullified

Bugs finding while testing:

• The report card updated in the background before saving teal.reporter#322
• Can't Download Report in refactor branch teal.reporter#327
• [Bug]: ReportDocument metadata not being merged on c() teal.reporter#329
• https://github.com/insightsengineering/coredev-tasks/issues/390
• Update README GIF in teal.reporter to reflect the new design

[m7pr]

TESTS

Tested with

• App with all modules for testing teal.modules.general#913
• App to test `teal_reportable` functionality teal.reporter#388

---

DONE

• Improve the Reproducibility Mechanisms and Code Display in Report Output teal.reporter#280
  • teal_card and teal_reporter introduced in the PR allow to support reproducible code in the final report generation
• https://github.com/insightsengineering/coredev-tasks/issues/545
  • Using add_card_button_srv with a standalone "+" button (no more old buttons in modules)
• [Feature Request]: Allow app dev to supply card function. teal.modules.general#736 + optional reporter in the independent teal modules teal#678
  • after functions allows disabling or changing reporter on a per-module basis
• Edit Functionality for the Report Previewer module teal.reporter#312
  • Editor functionality that allows to sort cards, edit cards (and extend them with text elements), delete cards
• Reuse opportunities between download_report_button_srv and reporter_previewer_srv teal.reporter#317
  • Refactored and cleaned up the code

---

WHAT WORKED BEFORE BUT NO LONGER WORKS

• [Feature Request]: Globally disable reporter feature teal#871
  • init parameter is exposed, and you can set to NULL to disable the reporter globally
    • but THE + sign is still shown and you can still add cards to reporter, but the reporter previewer is not shown
      • FIX: If reporter is globally disabled, do not show a + sign to add a card teal#1587
• [Feature Request]: User-defined templates for reports teal.reporter#271
  • Added reporter$set_template() for setting custom templates when users add cards
    • but when passing reporter to the app, the reporter is not used at all and empty reporter is used
      • FIX: If reporter was provided, reuse it in srv_teal teal#1586

---

CAN BE SKIPPED

• Soft Deprecate old methods teal.reporter#315
  • Old methods (like ContentBlock, TextBlock etc) were not exported, so they can just be deleted
  • No idea if we want to deprecate ReportCard ? NEEDS DISCUSS

---

BUGS

• [Bug]: Can't change Card's title in Reporter Editor teal.reporter#386
  • FIX Extend shinyjs to allow title edits in reporter previewer teal.reporter#392
• https://github.com/insightsengineering/coredev-tasks/issues/390
  • FIX refactor: adds custom plot sizes for figures in previewer & reporter teal.reporter#383
• [Bug]: Loading the report... gets added to previous card, when new card is opened teal.reporter#387
  • FIX 387 Only show loading placeholder for cards that are being initialized for the first time teal.reporter#390
• [Bug]: Downloaded report has incorrect header teal.reporter#357
  • FIX 357 proper header for downloaded report teal.reporter#389
• Unable to render report on Windows
  • FIX Use basename in .content_to_rmd for Windows paths teal.reporter#385

---

UNRESOLVED COMMENTS
8 unresolved comments in teal.reporter

• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)
• 📑 Refactor: Adds new teal_report, teal_card class and revamps reporter UI teal.reporter#331 (comment)

5 unresolved comments in teal

• 📑 Reporter Refactor: Adds support for new teal_report and teal_card class teal#1541 (comment)
• 📑 Reporter Refactor: Adds support for new teal_report and teal_card class teal#1541 (comment)
• 📑 Reporter Refactor: Adds support for new teal_report and teal_card class teal#1541 (comment)
• 📑 Reporter Refactor: Adds support for new teal_report and teal_card class teal#1541 (comment)
• 📑 Reporter Refactor: Adds support for new teal_report and teal_card class teal#1541 (comment)

---

TODOs in code
3 TODOs in the code in teal.reporter

• https://github.com/insightsengineering/teal.reporter/pull/331/files#diff-b2404771101f46531301f957fc7e3ebb5179e08f985bb9195b13503b527b43b6R264
• https://github.com/insightsengineering/teal.reporter/pull/331/files#diff-9b7aad168e17a96e238368559ca4892981af80affd0b3281ec30c6902c62756fR29
• https://github.com/insightsengineering/teal.reporter/pull/331/files#diff-e0ffaaa8737b3d5ec63787ec987e70f57bde8025da8de915e587222c99694e98R199

2 TODOs in the code in teal

• https://github.com/insightsengineering/teal/pull/1541/files#diff-51920e95310ebfbc1ae31709f3b95f89afffbf4f1a6e38e8b2b406e2fb6197eaR26
  https://github.com/insightsengineering/teal/pull/1541/files#diff-a5c0a1711563afbdaac3ed2683887be7ae554566b927661df204b5e234b53254R15

TODOS in tests

• 5 TODOS in tests in teal.reporter
• 1 TODOs in tests in teal
  • https://github.com/insightsengineering/teal/pull/1541/files#diff-1b0d923e7c5401b528d7249efe53c26e8dfd2cc634f85b79e6964276b8d95a5cR15

---

FIX R CMD CHECKS

• https://github.com/insightsengineering/teal.reporter/actions/runs/17375909612/job/49322072191?pr=331
• https://github.com/insightsengineering/teal/actions/runs/17290878213/job/49077725982?pr=1541

---

FUTURE PLANS
We decided to go with a first initial merge of functionalities to main, that then will be followed-up by another documentation PR that includes

• [Documentation] Vignette for new feature teal.reporter#314
• [Research] Automatic Show R Code button creation teal#1534
• Rewrite report cards based on the new design in:
  • Rewrite reporter code in modules teal.modules.general#874 - 15 modules (23 hours)
  • Rewrite reporter code in modules teal.modules.clinical#1376 - 36 modules (54 hours)
  • Rewrite reporter code in modules teal.osprey#299 - 10 modules (15 hours)
  • Rewrite reporter code in modules teal.goshawk#342 - 6 modules (9 hours)