🎉 (gdocs) add key-indicator component

[sophiamersmann]

Adds a new GDoc component, key-indicator, that showcases a given indicator by rendering an interactive Grapher chart, a title and motivational text, and some metadata.

Note that the key-indicator component is used as a building block of a higher-order component, key-indicator-collection (added in #3108), but can also be used as a stand-alone component.

Examples

Working example: Gdoc / Admin / Staging
Example with error states: Gdoc / Admin

{.key-indicator}
    datapageUrl: https://ourworldindata.org/grapher/life-expectancy
    title: My title
    source: Optional source overwrite

    [.+blurb]
        Required Intro text.

        Allowing for multiple paragraphs.
    []
{}

Spec

• datapageUrl (required)
  • Non-datapage grapher links are not supported
• title (required)
• blurb (required): multi-paragraph motivational text
• source (optional): optional source overwrite
  • the indicator's source is inferred from metadata, but the responsible metadata fields are not guaranteed to be given or be well curated
  • ideally, we'd fix the metadata and wouldn't need the overwrite
  • but for now, Joe has decided that an Archie overwrite is the practical thing to do

Metadata defaults: the indicator title and source are inferred from metadata; both show the exact same string that is shown on a datapage (see screenshots below)

• Indicator title: equals the title of a datapage
• Indicator source (next to the title): equals the short attribution shown next to the title on a datapage

Datapage

Key indicator block

Technical details

• The key indicator component (i) renders a chart and (ii) displays indicator metadata
  • To make (i) work, the key indicator chart is added to the linkedCharts attachment
  • To make (ii) work, a new attachment is added, linkedIndicators that stores a subset of metadata for a given indicator
• How linked charts and linked indicators interact:
  • If a linked chart renders as a datapage, we grab the relevant indicator ID and store it with the linked chart (note that we're doing this for all linked charts)
  • For each linked chart that has an indicator ID (and is referenced in a key indicator block), we add an entry in linkedIndicators that stores a subset of metadata properties
• To figure out whether a grapher page renders as datapage, I extracted code that lived in the GrapherBaker and refactored it into a separate function (getVariableOfDatapageIfApplicable(grapher)) that can be used elsewhere

Summary by CodeRabbit

• New Features
  • Added support for "Linked Indicators" across the site, allowing for richer, data-driven narratives.
  • Introduced a new component for displaying key indicators dynamically, enhancing data presentation and user engagement.
• Enhancements
  • Improved data page rendering logic for clarity and efficiency, ensuring a smoother user experience.
  • Updated styling for charts and key indicators, optimizing visual presentation across various screen sizes.
• Refactor
  • Consolidated and reorganized imports across multiple files for better maintainability.
  • Refined handling and prefetching of linked indicators and documents, improving site performance.
• Documentation
  • Expanded type definitions to include new entities related to "Linked Indicators," facilitating development and integration.

[sophiamersmann]

Current dependencies on/for this PR:

• master
  • PR 🎉 (gdocs) add key-indicator component #3103 👈
    • PR 🎉 (gdocs) add key-indicator-collection component #3108

This stack of pull requests is managed by Graphite.

[coderabbitai]

Walkthrough

This update involves a significant overhaul aimed at integrating LinkedIndicator entities and key indicator blocks to enhance data presentation and accessibility. The changes entail reorganizing imports, refining data handling, and introducing new functionalities to manage and display linked indicators and key indicators within documents and charts, with the goal of making data insights more interactive and user-friendly.

Changes

Files	Summary
adminSiteClient/gdocsDeploy.ts, db/model/Variable.ts, packages/@ourworldindata/utils/src/Util.ts, packages/@ourworldindata/utils/src/index.ts, packages/@ourworldindata/utils/src/metadataHelpers.ts	Reorganized imports and added/updated utility functions for linked indicators handling.
baker/GrapherBaker.tsx, baker/SiteBaker.tsx	Refactored data handling and added support for linked indicators.
db/model/Gdoc/... (multiple files), packages/@ourworldindata/types/src/gdocTypes/... (multiple files)	Introduced LinkedIndicator entity, added new types for key indicators, and enhanced Gdoc functionality with these entities.
site/... (multiple files)	Enhanced web components to support linked indicators, added new styling for key indicators, and improved data page content presentation.

Related issues

• Tasks: Key indicator block / Chartbook #3092: The introduction of LinkedIndicator entities and key indicator blocks directly contributes to implementing new GDoc components for displaying interactive charts with metadata. This PR appears to lay the groundwork necessary for steps 1 and 2 of the key indicator block objective.

🐇✨
In the land of code and data, where insights gleam,
A rabbit hopped, weaving a developer's dream.
With linked indicators and charts so bright,
It crafted a world of knowledge, pure delight.
🌟📊

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

---

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository from git and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.