feat: Feature notifications by georgylobko · Pull Request #4186 · cloudscape-design/components

georgylobko · 2026-01-14T10:16:44Z

Description

Introduced a feature notifications API that allows dynamically injecting a feature notifications drawer on pages using the AppLayout component.

The new API includes 3 methods:

registerFeatureNotifications - registers a new drawer
showFeaturePromptIfPossible - manually shows a feature prompt next to the drawer's trigger button
clearFeatureNotifications - clears the feature notifications drawer

Also enhanced the existing feature prompt internal component by adding dismissal context to the onDismiss method (blur, close-button, outside-click, etc.).

Related links, issue #, if available: n/a

How has this been tested?

U tests / manually

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

Changes include appropriate documentation updates.
Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
Changes do not include unsupported browser features, see CONTRIBUTING.md.
Changes were manually tested for accessibility, see accessibility guidelines.

Security

If the code handles URLs: all URLs are validated through the checkSafeUrl function.

Testing

Changes are covered with new/existing unit tests?
Changes are covered with new/existing integration tests?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov · 2026-01-14T11:33:15Z

Codecov Report

❌ Patch coverage is 98.46154% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.43%. Comparing base (5163256) to head (c73929a).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...rc/internal/do-not-use/feature-prompt/internal.tsx	90.90%	2 Missing ⚠️
...efresh-toolbar/state/use-feature-notifications.tsx	98.92%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #4186    +/-   ##
========================================
  Coverage   97.42%   97.43%            
========================================
  Files         893      896     +3     
  Lines       26127    26298   +171     
  Branches     9438     9495    +57     
========================================
+ Hits        25455    25623   +168     
- Misses        666      669     +3     
  Partials        6        6

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pan-kot · 2026-02-20T14:13:52Z

src/app-layout/__tests__/runtime-feature-notifications.test.tsx

+      filterFeatures: feature => {
+        const halfYearAgo = new Date();
+        halfYearAgo.setDate(halfYearAgo.getDate() - 180);
+        return feature.releaseDate >= halfYearAgo;


nit: this implementation is unnecessary as using filterFeatures: () => true would give the same result.

If you also want to verify that the payload is correct, it is best to use:

const filterFeatures = jest.fn().returns(() => true);

, in which case you can explicitly check that the function was called the correct amount of times and with correct payload

the purpose of this test is to provide a usage example, so I would keep it as is

src/app-layout/__tests__/runtime-feature-notifications.test.tsx

pan-kot · 2026-02-20T14:17:05Z

src/app-layout/__tests__/runtime-feature-notifications.test.tsx

+  });
+
+  test('should not show feature prompt if all feature are seen', async () => {
+    mockRetrieveFeatureNotifications.mockResolvedValue({


I changed this to:

mockRetrieveFeatureNotifications.mockResolvedValue({ 'feature-1': 'mockDate2025.toString()', 'feature-2': 'mockDate2024.toString()', 'feature-old': 'mockDateOld.toString()', });

and the test still passed. Why do we need these values?

Yes, we need this test. However the dates are not important here, because we check only features ids - we check dates only when we persist values to filter out outdated values

pan-kot · 2026-02-20T14:20:45Z

src/app-layout/visual-refresh-toolbar/drawer/feature-notifications-drawer-content.tsx

+                    {formatDate(item.releaseDate)}
+                  </Box>
+                  {!!item.contentCategory && (
+                    <Box>


The RuntimeContentPart already wraps content with a div or span. Why do we need the surrounding Box elements for content category and content?

yes, we need them for right paddings

pan-kot · 2026-02-20T14:21:37Z

src/app-layout/visual-refresh-toolbar/drawer/feature-notifications-drawer-content.tsx

+          />
+
+          {!!featuresPageLink && (
+            <footer className={styles['runtime-feature-notifications-footer']}>


Should we use drawer's footer for that?

https://cloudscape.design/components/drawer/?tabId=playground&example=with-footer

No, I tried. The footer is sticky, which we don't need here

pan-kot · 2026-02-20T14:30:49Z

src/popover/body.tsx


    const isDialog = showDismissButton;
-    const shouldTrapFocus = showDismissButton && variant !== 'annotation';
+    const shouldTrapFocus = trapFocus || (showDismissButton && variant !== 'annotation');


Can we introduce a distinct variant for feature notifications instead?

pan-kot · 2026-02-20T14:34:30Z

src/internal/persistence/index.ts

  return Promise.resolve(false);
 };
+
+// eslint-disable-next-line require-await


nit: should we disable these two eslint rules for the entire file instead?

pan-kot · 2026-02-20T14:39:11Z

When register API is used from inside an iframe - the initial feature prompt is not shown. The "show a standalone prompt" still works - but focus is not handled correctly and click outside does not cause a dismiss.

I tested that by wrapping the new test page with the IframeWrapper util.

pan-kot · 2026-02-20T14:40:27Z

src/internal/do-not-use/feature-prompt/internal.tsx

+        fireNonCancelableEvent(onDismiss, { method: 'click-outside' });
+      }
+    };
+    window.addEventListener('click', clickListener, true);


This and the nodeBelongs can be a problem when the API is called from inside an iframe. I managed to confirm it by rendering the test page inside an iframe helper.

pan-kot · 2026-02-20T14:43:50Z

src/drawer/use-sticky-footer.ts

  const checkStickyState = throttle(
    useCallback(() => {
-      if (!drawerRef.current || !footerRef.current) {
+      if (!drawerRef?.current || !footerRef?.current) {


why is this change needed?

otherwise it throws an error

pan-kot · 2026-02-20T15:25:14Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+  }, [featureNotificationsData, seenFeatures]);
+
+  const defaultFeaturesFilter = (feature: Feature<unknown>) => {
+    return feature.releaseDate >= subtractDaysFromDate(new Date(), 90);


let's use a constant for 90 as well

pan-kot · 2026-02-20T15:26:57Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+  const featurePromptRef = useRef<FeaturePromptProps.Ref>(null);
+  const { ref: featurePromptMountRef, promise: featurePromptMountPromise } = useMountRefPromise();
+  const featurePromptMergedRef = useMergeRefs(featurePromptRef, featurePromptMountRef);
+  const allNotificationsSeen = useMemo(() => {


nit: this memo is not really needed - the cost of checking the data (which is already filtered) is negligible.

pan-kot · 2026-02-20T15:28:23Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+        resizeHandle: i18n('ariaLabels.resizeHandle', undefined),
+      },
+      resizable: true,
+      defaultSize: 320,


nit: let's create a constant for default drawer size, too

pan-kot · 2026-02-20T15:33:12Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+
+  function featureNotificationsMessageHandler(event: WidgetMessage) {
+    if (event.type === 'registerFeatureNotifications') {
+      warnOnce('feature notifications', 'Feature notifications drawer is overriding the tools panel');


This renders a warning when the feature notifications feature is used correctly - why?

We should only warn if the tools feature is actually used, and in that case the feature notifications must not be rendered.

Also, we should add a unit test for the warning.

not needed anymore as the drawer works along with tools

pan-kot · 2026-02-20T15:34:44Z

src/internal/utils/promises.ts

+ *
+ * @returns An object containing a ref callback and a promise that resolves with the mounted element
+ */
+export function useMountRefPromise<T extends HTMLElement>() {


pan-kot · 2026-02-20T15:38:45Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+    }
+
+    if (event.type === 'showFeaturePromptIfPossible') {
+      if (allNotificationsSeen) {


nit: we can simplify the check to:

if (event.type === 'showFeaturePromptIfPossible' && !allNotificationsSeen) { featurePromptRef.current?.show(); }

Alternatively, the event mapping can be made more explicit like:

switch (event.type) { case 'registerFeatureNotifications': return handleRegisterFeatureNotifications(...); case 'showFeaturePromptIfPossible': return showFeaturePromptIfApplicable(); case 'clearFeatureNotifications': return setFeatureNotificationsData(null); }

pan-kot · 2026-02-20T15:40:10Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+
+    // Features array is already sorted in reverse chronological order (most recent first)
+    // Find the first feature that hasn't been seen
+    for (const feature of featureNotificationsData.features) {


nit: this can be simplified to:

featureNotificationsData.features.find(feature => !seenFeatures[feature.id]) ?? null;

or even one line:

function getLatestUnseenFeature() { return featureNotificationsData?.features.find(feature => !seenFeatures[feature.id]) ?? null; }

pan-kot · 2026-02-20T15:45:26Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+
+  function renderLatestFeaturePrompt({ triggerRef }: RenderLatestFeaturePromptProps) {
+    const latestFeature = getLatestUnseenFeature();
+    if (!(triggerRef?.current && featureNotificationsData && latestFeature)) {


this can be simplified to:

if (!triggerRef.current || !latestFeature) { return null; }

pan-kot · 2026-02-20T15:47:48Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+        }}
+        onDismiss={event => {
+          if (event.detail?.method !== 'blur') {
+            triggerRef?.current!.focus();


This .focus() already accepts options object. Can we add support for suppressTooltip in there?

The suppress should be controlled not only when focus is set, but also when we show the feature popover. In that case, focus goes to the feature popover while the tooltip for its trigger is suppressed

pan-kot · 2026-02-20T15:52:24Z

src/app-layout/visual-refresh-toolbar/state/use-feature-notifications.tsx

+    }, {});
+    const filteredSeenFeaturesMap = filterOutdatedFeatures(seenFeatures);
+    const allFeaturesMap = { ...featuresMap, ...filteredSeenFeaturesMap };
+    const __persistFeatureNotifications:


nit: I would abstract the persistence related code into a dedicated function, so that the logic inside onOpenFeatureNotificationsDrawer is more clear:

const onOpenFeatureNotificationsDrawer = () => { if (!featureNotificationsData || allNotificationsSeen) { return; } const persistenceConfig = featureNotificationsData.persistenceConfig ?? DEFAULT_PERSISTENCE_CONFIG; persistFeatureNotificationsDismissState(persistenceConfig, featureNotificationsData).then((seenFeatures) => { setSeenFeatures(seenFeatures); setFeatureNotificationsData(data => (data ? { ...data, badge: false } : data)); }); };

pan-kot

Significant:

Feature notifications must not render if tools are present;
Dev warning should only be shown if feature notifications and tools are used together;
The API and feature prompt do not work correctly when used from an iframe;
The API is exported as a set of standalone methods w/o structural grouping.

Less significant:

Test coverage is not sufficient;
Code structure can be improved: remove tabTrap, awsuiSuppressTooltip;
Internal APIs for persistence are accessible via public API (with a ...{} hack);
Persisted structure includes date snapshots that are not used;
The dedicated test page requires an URL flag to be used;
I18n strings API properties are not descriptive enough.

Significant, but can be done as a followup:

No dedicated test utils for the UX features;
I18n messages cannot be overridden.

src/internal/plugins/widget/index.ts

…Props for registerFeatureNotifications

georgylobko changed the title ~~feat: Seature notifications~~ feat: Feature notifications Jan 14, 2026

georgylobko deployed to dev-pages-react16 January 14, 2026 11:32 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 14, 2026 11:32 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 14, 2026 12:08 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 14, 2026 12:08 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch from 4fa101b to efb51d9 Compare January 14, 2026 12:20

georgylobko deployed to dev-pages-react18 January 14, 2026 12:29 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 14, 2026 12:29 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 15, 2026 15:45 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 15, 2026 15:45 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch 2 times, most recently from 8343dd7 to aea04d1 Compare January 19, 2026 10:37

georgylobko deployed to dev-pages-react18 January 19, 2026 10:46 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 19, 2026 10:46 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 19, 2026 11:07 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 19, 2026 11:07 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch from 2e7cb8e to 1f4c85f Compare January 20, 2026 12:51

georgylobko deployed to dev-pages-react18 January 20, 2026 13:09 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 20, 2026 13:09 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch from 221927b to 4379ee3 Compare January 20, 2026 15:23

georgylobko deployed to dev-pages-react18 January 20, 2026 15:32 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 20, 2026 15:32 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react16 January 26, 2026 15:40 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 26, 2026 15:40 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch 2 times, most recently from 493d050 to fbd48d1 Compare January 27, 2026 09:31

georgylobko deployed to dev-pages-react16 January 27, 2026 09:41 — with GitHub Actions View deployment

georgylobko deployed to dev-pages-react18 January 27, 2026 09:41 — with GitHub Actions View deployment

georgylobko force-pushed the feat/feature-notitications branch from 9dc81fc to 6c9b625 Compare January 28, 2026 14:53

pan-kot reviewed Feb 20, 2026

View reviewed changes

src/app-layout/__tests__/runtime-feature-notifications.test.tsx Outdated Show resolved Hide resolved

pan-kot reviewed Feb 20, 2026

View reviewed changes

pan-kot previously requested changes Feb 20, 2026

View reviewed changes

pan-kot reviewed Feb 24, 2026

View reviewed changes

src/internal/plugins/widget/index.ts Outdated Show resolved Hide resolved

srungta08 previously approved these changes Feb 25, 2026

View reviewed changes

georgylobko added 4 commits February 25, 2026 20:36

feat: Feature notifications plugin API

03712a3

chore: small fix

63d4bd4

chore: Exclude feature notifications from a11y tests, use getExternal…

492d92d

…Props for registerFeatureNotifications

chore: Small refactoring

0f194cf

srungta08 previously approved these changes Feb 26, 2026

View reviewed changes

fix: eslint

c73929a

srungta08 approved these changes Feb 26, 2026

View reviewed changes

Conversation

georgylobko commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How has this been tested?

Correctness

Security

Testing

Uh oh!

codecov bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot commented Feb 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

georgylobko commented Jan 14, 2026 •

edited

Loading

codecov bot commented Jan 14, 2026 •

edited

Loading

pan-kot Feb 20, 2026 •

edited

Loading

pan-kot Feb 20, 2026 •

edited

Loading