feat(core): support global and contextual downIsGood configuration (#3297)

[FrancescoCastaldi]

Closes #3297

Description

This PR introduces global, page-level, and wrapper-context downIsGood (down_is_good) default configuration for <Delta>, <BigValue>, <Table>, and related comparison components.

In cost and finance dashboards, an increase is often negative (costs went up) and a decrease is positive (costs went down). Previously, authors had to add down_is_good={true} to each individual component.

Changes

1. Svelte Context & <DeltaDefaults> tag:
   • Created DeltaDefaultsContext (delta-defaults.context.svelte.ts)
   • Added <DeltaDefaults down_is_good={true}> / <DeltaDefaults downIsGood={true}> wrapper component
2. Page Frontmatter & Project Layout:
   • Added down_is_good and downIsGood to projectRootPageFrontmatterSchema and projectLayoutSchema
   • Updated pageSettingsSchema and CLI page settings resolution to pass layout & frontmatter defaults
3. Theme Defaults:
   • Added defaults and delta blocks to themeConfigSchema and themeOverridesSchema
4. Resolution Cascading in DeltaDisplay:
   • Priority hierarchy:
     1. Component prop override (comparison.down_is_good / downIsGood)
     2. Nearest <DeltaDefaults> context
     3. Page frontmatter (down_is_good / downIsGood)
     4. Project layout / theme defaults
     5. Fallback: false
5. Tests:
   • Added unit test suite delta-defaults.test.ts for schema validation and default inheritance
   • Added test cases in files.server.test.ts

[vercel]

Someone is attempting to deploy a commit to the Evidence Team on Vercel.

A member of the Team first needs to authorize it.

[FrancescoCastaldi]

Hi @archiewood @hughess! 👋 Whenever you have a moment, could you please take a look at this PR and approve the CI workflow? Thank you!

[hughess]

@FrancescoCastaldi do you have any examples where this configuration would be useful? We typically see down_is_good only used a small percentage of the time

[FrancescoCastaldi]

@hughess Sure — the main use case comes from financial and cost-oriented dashboards where the majority of metrics on a page (or section) benefit from inverted polarity.

Concrete examples:

1. Healthcare operational cost dashboards — I build BI dashboards for hospital networks where entire pages track cost KPIs: average wait time, cost per patient visit, overhead per department, readmission rates. On these pages, nearly every <Delta> and <BigValue> needs down_is_good={true}. Without this PR, each page ends up with 15-20 components all repeating the same prop.

2. SaaS churn & support dashboards — Pages tracking churn rate, average resolution time, ticket backlog, bounce rate. Again, an entire page where "down = good" across the board.

3. Manufacturing / supply chain — Defect rates, lead times, inventory shrinkage, downtime hours. Full sections where decreasing is the desired direction.

The pattern is: when a dashboard page or section is thematically about costs, errors, or durations, the default polarity inverts for the whole group — not for isolated metrics. Setting it once at page or wrapper level removes repetition and reduces the risk of forgetting it on one component (which creates a confusing inconsistency for the end user).

Even though down_is_good may only apply to a minority of all Evidence projects, within those projects it tends to apply to entire pages or sections at once, which is exactly the granularity this PR targets.

Happy to simplify the scope if needed — for instance, we could start with just the <DeltaDefaults> wrapper context and skip the frontmatter/theme integration for now. Let me know what you think.

[hughess]

That makes sense, thanks for the background. I think to start we should only apply the option at the page level - we can add the project configuration option later assuming the page one works well. If you're able to update to only have this at page level, I can get the process started to get this change in!

[FrancescoCastaldi]

@hughess Updated!

As requested, I've narrowed the scope to support down_is_good (downIsGood) exclusively at the page level via page frontmatter (down_is_good: true / downIsGood: true), removing the global layout and theme defaults for now.

The PR has also been cleanly restructured into 6 atomic commits:

1. feat(core): add down_is_good to page frontmatter schema
2. feat(core): add down_is_good to PageSettings interface
3. feat(cli): parse down_is_good page setting from frontmatter
4. feat(core): support page-level downIsGood default in DeltaDisplay
5. feat(core): forward downIsGood in BigValue and comparison tags
6. test(cli): add unit tests for page-level down_is_good frontmatter parsing

Ready for review whenever you get a chance!

[hughess]

/upstream

[github-actions]

Imported for internal review, this PR will be updated when it merges.

[hughess]

Thanks @FrancescoCastaldi, appreciate you narrowing the scope! I've brought this into our internal repo and made a few follow-up changes on top of your commit:

• Removed the false defaults on down_is_good in the component schemas (delta, big_value, measure, benchmark/target comparison). They meant the value was always set, so the page setting never kicked in.
• Dropped the downIsGood alias so it's just down_is_good, like the other frontmatter keys.
• Wired it into Studio and added render tests and docs.

It'll sync back here with your authorship when it merges. This PR will show as closed rather than merged, which is expected for the mirror.

[FrancescoCastaldi]

@hughess That's awesome, thanks a lot for catching those schema default edge cases and integrating it into Studio and the docs! Excited to see it land. Thanks again! 🙌

[FrancescoCastaldi]

@hughess Just pushed those exact follow-up tweaks to this PR branch as well (5a0648d8d): removed the hardcoded false defaults across component schemas and dropped the downIsGood alias so everything matches the clean down_is_good page-level behavior!