Skip to content

feat: create announcements banner#617

Open
araujogui wants to merge 20 commits intomainfrom
feat/banners
Open

feat: create announcements banner#617
araujogui wants to merge 20 commits intomainfrom
feat/banners

Conversation

@araujogui
Copy link
Copy Markdown
Member

@araujogui araujogui commented Feb 20, 2026

Description

Create announcements banner component

Validation

image

Related Issues

Fixes #327

Check List

  • I have read the Contributing Guidelines and made commit messages that follow the guideline.
  • I have run node --run test and all tests passed.
  • I have check code formatting with node --run format & node --run lint.
  • I've covered new added functionality with unit tests if necessary.

@araujogui araujogui requested a review from a team as a code owner February 20, 2026 19:56
Copilot AI review requested due to automatic review settings February 20, 2026 19:56
@vercel
Copy link
Copy Markdown

vercel bot commented Feb 20, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
api-docs-tooling Ready Ready Preview Apr 2, 2026 3:16pm

Request Review

@codecov
Copy link
Copy Markdown

codecov bot commented Feb 20, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 12.50000% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.15%. Comparing base (e45645a) to head (89d0b00).

Files with missing lines Patch % Lines
src/generators/web/utils/generate.mjs 0.00% 7 Missing ⚠️
Additional details and impacted files 
@@            Coverage Diff             @@
##             main     #617      +/-   ##
==========================================
- Coverage   77.17%   77.15%   -0.03%     
==========================================
  Files         153      153              
  Lines       13771    13776       +5     
  Branches     1114     1114              
==========================================
+ Hits        10628    10629       +1     
- Misses       3139     3143       +4     
  Partials        4        4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Feb 20, 2026 •
edited
Loading

web Generator

File Base Head Diff
fs.html 1.43 MB 2.88 KB -1.43 MB (-99.80%)
crypto.html 1.09 MB 2.88 KB -1.08 MB (-99.74%)
buffer.html 905.71 KB 2.88 KB -902.84 KB (-99.68%)
stream.html 855.29 KB 2.88 KB -852.42 KB (-99.66%)
n-api.html 807.24 KB 2.88 KB -804.36 KB (-99.64%)
http2.html 768.58 KB 2.87 KB -765.71 KB (-99.63%)
test.html 753.88 KB 2.88 KB -751.00 KB (-99.62%)
http.html 738.70 KB 2.87 KB -735.83 KB (-99.61%)
util.html 691.88 KB 2.87 KB -689.01 KB (-99.59%)
process.html 676.14 KB 2.88 KB -673.26 KB (-99.57%)
webcrypto.html 521.99 KB 2.89 KB -519.10 KB (-99.45%)
deprecations.html 505.30 KB 2.90 KB -502.40 KB (-99.43%)
cli.html 492.50 KB 2.89 KB -489.61 KB (-99.41%)
errors.html 461.17 KB 2.88 KB -458.29 KB (-99.38%)
events.html 455.26 KB 2.88 KB -452.38 KB (-99.37%)
net.html 382.28 KB 2.87 KB -379.41 KB (-99.25%)
child_process.html 381.69 KB 2.90 KB -378.79 KB (-99.24%)
perf_hooks.html 381.48 KB 2.92 KB -378.56 KB (-99.23%)
tls.html 373.78 KB 2.88 KB -370.90 KB (-99.23%)
vm.html 370.79 KB 2.91 KB -367.88 KB (-99.22%)
worker_threads.html 365.46 KB 2.90 KB -362.56 KB (-99.21%)
quic.html 358.96 KB 2.87 KB -356.09 KB (-99.20%)
webstreams.html 355.72 KB 2.90 KB -352.83 KB (-99.19%)
url.html 347.67 KB 2.87 KB -344.80 KB (-99.18%)
assert.html 329.99 KB 2.88 KB -327.12 KB (-99.13%)
module.html 326.65 KB 2.91 KB -323.74 KB (-99.11%)
v8.html 321.08 KB 2.86 KB -318.22 KB (-99.11%)
stream_iter.html 309.02 KB 2.90 KB -306.12 KB (-99.06%)
diagnostics_channel.html 303.41 KB 2.91 KB -300.50 KB (-99.04%)
dns.html 295.80 KB 2.87 KB -292.94 KB (-99.03%)
zlib.html 290.23 KB 2.87 KB -287.36 KB (-99.01%)
sqlite.html 268.07 KB 2.88 KB -265.19 KB (-98.93%)
addons.html 262.55 KB 2.88 KB -259.67 KB (-98.90%)
readline.html 252.16 KB 2.88 KB -249.28 KB (-98.86%)
globals.html 230.36 KB 2.89 KB -227.47 KB (-98.74%)
cluster.html 196.29 KB 2.88 KB -193.41 KB (-98.53%)
dgram.html 194.36 KB 2.90 KB -191.45 KB (-98.51%)
async_context.html 187.56 KB 2.93 KB -184.64 KB (-98.44%)
repl.html 183.29 KB 2.87 KB -180.42 KB (-98.43%)
modules.html 178.72 KB 2.91 KB -175.81 KB (-98.37%)
report.html 175.91 KB 2.90 KB -173.01 KB (-98.35%)
inspector.html 171.37 KB 2.88 KB -168.49 KB (-98.32%)
async_hooks.html 159.70 KB 2.89 KB -156.81 KB (-98.19%)
esm.html 155.32 KB 2.91 KB -152.41 KB (-98.12%)
packages.html 154.64 KB 2.90 KB -151.74 KB (-98.13%)
https.html 150.34 KB 2.87 KB -147.46 KB (-98.09%)
console.html 146.76 KB 2.88 KB -143.88 KB (-98.04%)
os.html 142.72 KB 2.86 KB -139.85 KB (-97.99%)
path.html 139.25 KB 2.87 KB -136.38 KB (-97.94%)
timers.html 133.49 KB 2.88 KB -130.62 KB (-97.85%)
single-executable-applications.html 106.93 KB 2.95 KB -103.99 KB (-97.25%)
domain.html 105.09 KB 2.88 KB -102.22 KB (-97.26%)
tty.html 95.28 KB 2.87 KB -92.42 KB (-96.99%)
zlib_iter.html 88.05 KB 2.91 KB -85.15 KB (-96.70%)
tracing.html 84.15 KB 2.89 KB -81.26 KB (-96.57%)
wasi.html 69.36 KB 2.93 KB -66.43 KB (-95.78%)
querystring.html 63.84 KB 2.89 KB -60.95 KB (-95.47%)
punycode.html 63.18 KB 2.88 KB -60.30 KB (-95.44%)
embedding.html 59.42 KB 2.90 KB -56.52 KB (-95.12%)
intl.html 58.13 KB 2.92 KB -55.21 KB (-94.98%)
string_decoder.html 55.38 KB 2.90 KB -52.48 KB (-94.77%)
permissions.html 55.13 KB 2.89 KB -52.24 KB (-94.76%)
debugger.html 54.21 KB 2.88 KB -51.33 KB (-94.69%)
typescript.html 53.46 KB 2.90 KB -50.55 KB (-94.57%)
environment_variables.html 44.03 KB 2.92 KB -41.11 KB (-93.37%)
synopsis.html 42.66 KB 2.90 KB -39.76 KB (-93.21%)
documentation.html 38.03 KB 2.92 KB -35.11 KB (-92.33%)
index.html 36.23 KB 2.87 KB -33.36 KB (-92.07%)
styles.css 137.49 KB 139.42 KB +1.93 KB (+1.40%)

Copilot AI reviewed Feb 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR implements an announcement banner component that fetches configuration from a remote JSON endpoint to display global and version-specific banners on the API documentation pages. The banners support date-based activation/deactivation and can include links to relevant resources.

Changes:

  • Added AnnouncementBanner component that asynchronously fetches and displays banners from a remote config
  • Implemented isBannerActive utility function to filter banners based on date ranges
  • Added versionMajor and remoteConfig fields to static data passed from server to client

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
src/generators/web/index.mjs Adds remote config URL to web generator default configuration
src/generators/web/types.d.ts Adds remoteConfig type definition for the web generator
src/generators/web/utils/data.mjs Extracts version major and remote config URL from server config to client static data
src/generators/web/constants.mjs Registers AnnouncementBanner component in JSX imports map
src/generators/jsx-ast/utils/buildContent.mjs Adds AnnouncementBanner to document layout above navigation bar
src/generators/web/ui/utils/banner.mjs Implements date range checking logic for banner activation
src/generators/web/ui/utils/__tests__/banner.test.mjs Comprehensive tests for banner date range logic
src/generators/web/ui/components/AnnouncementBanner/types.d.ts Type definitions for banner entries and remote config structure
src/generators/web/ui/components/AnnouncementBanner/index.jsx Main component that fetches config and renders active banners

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/generators/web/ui/components/AnnouncementBanner/index.jsx Outdated
<div>
{banners.map(banner => (
<Banner key={banner.link} type={banner.type}>
{banner.link ? <a href={banner.link}>{banner.text}</a> : banner.text}
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

External URLs from the remote config are used directly in href attributes without validation. While React/Preact provides some protection against javascript: protocol URLs, there's still a potential security risk if the remote config source is compromised. Consider validating that banner.link uses an approved protocol (https://) or implementing an allowlist of acceptable domains to ensure only trusted URLs are rendered. This is especially important since the config is fetched from an external source.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member Author

@araujogui araujogui Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@avivkeller @ovflowd what do you think? is this necessary? We don't do this on nodejs website

avivkeller
avivkeller reviewed Feb 20, 2026
View reviewed changes
avivkeller
avivkeller approved these changes Feb 21, 2026
View reviewed changes
avivkeller
avivkeller reviewed Feb 21, 2026
View reviewed changes
@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 21, 2026

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 21, 2026

(this also means that this spec cannot ever change or needs to be forever retroactively compatible)

@avivkeller
Copy link
Copy Markdown
Member

avivkeller commented Feb 21, 2026

please be aware this must 100% be a client-side only component

It is

@araujogui
Copy link
Copy Markdown
Member Author

araujogui commented Feb 21, 2026 •
edited
Loading

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 21, 2026

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

Yeah... So we need to be very careful here 😓

@araujogui
Copy link
Copy Markdown
Member Author

araujogui commented Feb 25, 2026 •
edited
Loading

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

Yeah... So we need to be very careful here 😓

We already have a site.json on website repo, having another config file on nodejs/node looks like duplication?

@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 25, 2026

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

Yeah... So we need to be very careful here 😓

We already have a site.json on website repo, having another config file on nodejs/node looks like duplication?

We can use site.json, but note that it is not publicly available, the link would either need to be through raw.githubusercontent.com or we'd need to move the file to be publicly available.

@araujogui
Copy link
Copy Markdown
Member Author

araujogui commented Feb 25, 2026

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

Yeah... So we need to be very careful here 😓

We already have a site.json on website repo, having another config file on nodejs/node looks like duplication?

We can use site.json, but note that it is not publicly available, the link would either need to be through raw.githubusercontent.com or we'd need to move the file to be publicly available.

I think raw.githubusercontent.com is good enough

@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 26, 2026

@araujogui please be aware this must 100% be a client-side only component. Since the value of this comes from being able to fetch this at page load, as docs are built only once for each version.

uh, that also means we can't change the config url, so we should already create the config file on nodejs/node?

Yeah... So we need to be very careful here 😓

We already have a site.json on website repo, having another config file on nodejs/node looks like duplication?

We can use site.json, but note that it is not publicly available, the link would either need to be through raw.githubusercontent.com or we'd need to move the file to be publicly available.

I think raw.githubusercontent.com is good enough

IDK about that...

@MattIPv4
Copy link
Copy Markdown
Member

MattIPv4 commented Feb 26, 2026

I'd be fine with using raw.githubusercontent.com at build time (like we do via nodevu on the site), but I don't think we should be reliant on hitting it client-side every time someone loads a page on the site, that feels like abuse of GitHub's service. Can we have a JSON file accessible via the site, or an API endpiont?

@ovflowd
Copy link
Copy Markdown
Member

ovflowd commented Feb 26, 2026

I'd be fine with using raw.githubusercontent.com at build time (like we do via nodevu on the site), but I don't think we should be reliant on hitting it client-side every time someone loads a page on the site, that feels like abuse of GitHub's service. Can we have a JSON file accessible via the site, or an API endpiont?

We won't be loading this at build-time, cause it is supposed to be a client-side only, so it would hit indeed on every page load. I don't think raw.githubusercontent.com has cache headers so it would not be good.

@araujogui
Copy link
Copy Markdown
Member Author

araujogui commented Feb 26, 2026

I'd be fine with using raw.githubusercontent.com at build time (like we do via nodevu on the site), but I don't think we should be reliant on hitting it client-side every time someone loads a page on the site, that feels like abuse of GitHub's service. Can we have a JSON file accessible via the site, or an API endpiont?

We won't be loading this at build-time, cause it is supposed to be a client-side only, so it would hit indeed on every page load. I don't think raw.githubusercontent.com has cache headers so it would not be good.

Okay, maybe we could expose site.json in an endpoint of the website

ovflowd
ovflowd requested changes Mar 1, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@ovflowd ovflowd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's put a block on this for now as this needs to be done thoughtfully

@araujogui araujogui removed the blocked label Mar 12, 2026
@araujogui araujogui requested a review from ovflowd March 12, 2026 22:30
ovflowd
ovflowd reviewed Apr 1, 2026
View reviewed changes
ovflowd
ovflowd reviewed Apr 1, 2026
View reviewed changes
ovflowd
ovflowd reviewed Apr 1, 2026
View reviewed changes
ovflowd
ovflowd approved these changes Apr 1, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@ovflowd ovflowd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM, left final comments!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@avivkeller avivkeller avivkeller approved these changes

Copilot code review Copilot Copilot left review comments

@ovflowd ovflowd ovflowd approved these changes

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Implement real-time (on-load) updates to API docs live-environment

6 participants

@araujogui @ovflowd @avivkeller @MattIPv4 @canerakdas