Skip to content

feat: create announcements banner#617

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

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

Conversation

@araujogui
Copy link
Copy Markdown
Member

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

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

Project Deployment Actions Updated (UTC)
api-docs-tooling Ready Ready Preview Mar 31, 2026 11:24pm

Request Review

@codecov
Copy link
Copy Markdown

codecov bot commented Feb 20, 2026

Codecov Report

❌ Patch coverage is 11.11111% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.31%. Comparing base (27de0e7) to head (72e7dad).

Files with missing lines Patch % Lines
src/generators/jsx-ast/utils/buildContent.mjs 11.11% 8 Missing ⚠️
src/generators/web/utils/generate.mjs 0.00% 7 Missing ⚠️
src/generators/web/utils/processing.mjs 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #617      +/-   ##
==========================================
- Coverage   76.37%   76.31%   -0.06%     
==========================================
  Files         155      155              
  Lines       13766    13778      +12     
  Branches     1093     1093              
==========================================
+ Hits        10514    10515       +1     
- Misses       3247     3258      +11     
  Partials        5        5              

☔ 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

api-links Generator

apilinks.json
Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    'Agent.defaultMaxSockets': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L227',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L436',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L450',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L462',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L292',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L326',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L231',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L363',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L595',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L261',
    'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L552',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L491',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L588',
    'assert.assert': 'https://github.com/nodejs/node/blob/HEAD/lib/assert.js#L185',
    'asyncResource.asyncId': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L242',
...
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2289',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2422',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L120',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L122',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L614',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L624',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L636',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2384',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2106',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2527',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L652',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2536',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2462',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2491',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L620',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L659',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L246',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L360',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L296',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L307',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L269',

web Generator

File Base Head Diff
styles.css 137.49 KB 139.42 KB +1.93 KB (+1.40%)
addons.js 292.95 KB 293.03 KB +86.00 B (+0.03%)
assert.js 453.06 KB 453.14 KB +86.00 B (+0.02%)
async_context.js 216.46 KB 216.54 KB +86.00 B (+0.04%)
async_hooks.js 194.94 KB 195.02 KB +86.00 B (+0.04%)
buffer.js 1.08 MB 1.08 MB +86.00 B (+0.01%)
child_process.js 460.51 KB 460.60 KB +86.00 B (+0.02%)
cli.js 300.88 KB 300.97 KB +86.00 B (+0.03%)
cluster.js 194.23 KB 194.31 KB +86.00 B (+0.04%)
console.js 105.81 KB 105.89 KB +86.00 B (+0.08%)
crypto.js 1.19 MB 1.19 MB +86.00 B (+0.01%)
debugger.js 29.81 KB 29.89 KB +86.00 B (+0.28%)
deprecations.js 287.42 KB 287.50 KB +86.00 B (+0.03%)
dgram.js 169.55 KB 169.64 KB +86.00 B (+0.05%)
diagnostics_channel.js 231.90 KB 231.98 KB +86.00 B (+0.04%)
dns.js 262.44 KB 262.53 KB +86.00 B (+0.03%)
documentation.js 9.14 KB 9.23 KB +86.00 B (+0.92%)
domain.js 89.44 KB 89.52 KB +86.00 B (+0.09%)
embedding.js 36.84 KB 36.92 KB +86.00 B (+0.23%)
environment_variables.js 14.60 KB 14.68 KB +86.00 B (+0.58%)
errors.js 350.73 KB 350.82 KB +86.00 B (+0.02%)
esm.js 135.06 KB 135.14 KB +86.00 B (+0.06%)
events.js 541.63 KB 541.71 KB +86.00 B (+0.02%)
fs.js 1.21 MB 1.21 MB +86.00 B (+0.01%)
globals.js 127.12 KB 127.20 KB +86.00 B (+0.07%)
http.js 670.03 KB 670.11 KB +86.00 B (+0.01%)
http2.js 795.10 KB 795.18 KB +86.00 B (+0.01%)
https.js 159.22 KB 159.30 KB +86.00 B (+0.05%)
index.js 9.85 KB 9.94 KB +86.00 B (+0.85%)
inspector.js 118.33 KB 118.41 KB +86.00 B (+0.07%)
intl.js 36.06 KB 36.14 KB +86.00 B (+0.23%)
module.js 333.85 KB 333.93 KB +86.00 B (+0.03%)
modules.js 147.89 KB 147.98 KB +86.00 B (+0.06%)
n-api.js 710.42 KB 710.50 KB +86.00 B (+0.01%)
net.js 274.94 KB 275.02 KB +86.00 B (+0.03%)
os.js 104.52 KB 104.60 KB +86.00 B (+0.08%)
packages.js 122.31 KB 122.39 KB +86.00 B (+0.07%)
path.js 95.96 KB 96.04 KB +86.00 B (+0.09%)
perf_hooks.js 358.26 KB 358.34 KB +86.00 B (+0.02%)
permissions.js 28.44 KB 28.53 KB +86.00 B (+0.30%)
process.js 702.78 KB 702.86 KB +86.00 B (+0.01%)
punycode.js 27.48 KB 27.57 KB +86.00 B (+0.31%)
querystring.js 30.38 KB 30.46 KB +86.00 B (+0.28%)
quic.js 150.53 KB 150.61 KB +86.00 B (+0.06%)
readline.js 221.54 KB 221.63 KB +86.00 B (+0.04%)
repl.js 209.03 KB 209.12 KB +86.00 B (+0.04%)
report.js 188.15 KB 188.23 KB +86.00 B (+0.04%)
single-executable-applications.js 83.17 KB 83.25 KB +86.00 B (+0.10%)
sqlite.js 226.48 KB 226.56 KB +86.00 B (+0.04%)
stream.js 845.21 KB 845.30 KB +86.00 B (+0.01%)
stream_iter.js 398.51 KB 398.59 KB +86.00 B (+0.02%)
string_decoder.js 30.73 KB 30.81 KB +86.00 B (+0.27%)
synopsis.js 15.57 KB 15.66 KB +86.00 B (+0.54%)
test.js 849.95 KB 850.04 KB +86.00 B (+0.01%)
timers.js 96.44 KB 96.53 KB +86.00 B (+0.09%)
tls.js 308.12 KB 308.21 KB +86.00 B (+0.03%)
tracing.js 76.66 KB 76.74 KB +86.00 B (+0.11%)
tty.js 46.97 KB 47.05 KB +86.00 B (+0.18%)
typescript.js 24.22 KB 24.31 KB +86.00 B (+0.35%)
url.js 334.77 KB 334.85 KB +86.00 B (+0.03%)
util.js 739.54 KB 739.63 KB +86.00 B (+0.01%)
v8.js 329.43 KB 329.51 KB +86.00 B (+0.03%)
vm.js 435.39 KB 435.47 KB +86.00 B (+0.02%)
wasi.js 41.34 KB 41.42 KB +86.00 B (+0.20%)
webcrypto.js 379.78 KB 379.87 KB +86.00 B (+0.02%)
webstreams.js 283.66 KB 283.75 KB +86.00 B (+0.03%)
worker_threads.js 393.31 KB 393.39 KB +86.00 B (+0.02%)
zlib.js 307.54 KB 307.63 KB +86.00 B (+0.03%)
zlib_iter.js 57.21 KB 57.30 KB +86.00 B (+0.15%)

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.

<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

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

@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

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

@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

@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 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

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

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

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

createJSXElement(JSX_IMPORTS.Layout.name, {
sideBarProps,
metaBarProps,
announcementBannerProps: {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I'd argue these props should be injected in the web generator not jsx-ast.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Since the web generator is somewhat Node-specific but jsx-ast isn't and the whole announcement banner is something specific for us.

Copy link
Copy Markdown
Member

@avivkeller avivkeller Mar 28, 2026

Choose a reason for hiding this comment

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

Maybe we should leave it here, and in a follow-up, pass the entire (serialized) config to the JSX element, perhaps?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Right, I'm also not a fan that we are having so many props passed to the top level fn (not this) but like sideBarProps, metaBarProps and all of that being passed down to the build fns with the entries.

We should probably have a shared cache file (Map) that can be invoked by the jsx-ast and web generator. So the jsx-ast can set these sideBarProps/metaBarProps/stabilityOverviewEntries and what-not and allow the web generator consume it at build-time?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@araujogui can you add an inline todo so that this gets moved to somewhere else? I think @avivkeller will create an issue.

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 a few comments. I think this can work for the long-term.

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 a few tiny final comments, but looks good!

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

6 participants