feat: add reset to defaults to collection preferences

pages/collection-preferences/reset-to-defaults.page.tsx

@@ -0,0 +1,56 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as React from 'react';
+
+import Box from '~components/box';
+import CollectionPreferences, { CollectionPreferencesProps } from '~components/collection-preferences';
+
+import ScreenshotArea from '../utils/screenshot-area';
+import { contentDensityPreference, pageSizePreference, wrapLinesPreference } from './shared-configs';
+
+const defaultPreferences: CollectionPreferencesProps.Preferences = {
+  pageSize: 10,
+  wrapLines: false,
+  contentDensity: 'comfortable',
+};
+
+const resetToDefaults: CollectionPreferencesProps.ResetToDefaults = {
+  label: 'Reset to defaults',
+  preferences: defaultPreferences,
+};
+
+export default function CollectionPreferencesResetToDefaults() {
+  const [preferences, setPreferences] = React.useState<CollectionPreferencesProps.Preferences>({
+    pageSize: 50,
+    wrapLines: true,
+    contentDensity: 'compact',
+  });
+  const [lastReset, setLastReset] = React.useState<CollectionPreferencesProps.Preferences | null>(null);
+
+  return (
+    <>
+      <h1>CollectionPreferences with reset to defaults</h1>
+      <ScreenshotArea disableAnimations={true}>
+        <Box margin={{ bottom: 's' }}>
+          Current preferences: <span id="current-preferences">{JSON.stringify(preferences)}</span>
+        </Box>
+        <Box margin={{ bottom: 's' }}>
+          Last reset detail: <span id="last-reset">{lastReset ? JSON.stringify(lastReset) : 'none'}</span>
+        </Box>
+        <CollectionPreferences
+          className="cp-reset"
+          title="Preferences"
+          confirmLabel="Confirm"
+          cancelLabel="Cancel"
+          preferences={preferences}
+          pageSizePreference={pageSizePreference}
+          wrapLinesPreference={wrapLinesPreference}
+          contentDensityPreference={contentDensityPreference}
+          resetToDefaults={resetToDefaults}
+          onReset={({ detail }) => setLastReset(detail)}
+          onConfirm={({ detail }) => setPreferences(detail)}
+        />
+      </ScreenshotArea>
+    </>
+  );
+}

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -9419,6 +9419,93 @@ The values for all configured preferences are present even if the user didn't ch
       "detailType": "CollectionPreferencesProps.Preferences<CustomPreferenceType>",
       "name": "onConfirm",
     },
+    {
+      "cancelable": false,
+      "description": "Called when the user restores the default preferences using the reset button in the modal footer.
+
+The event \`detail\` contains the default preferences the modal's working state was restored to
+(the same object supplied in \`resetToDefaults.preferences\`).",
+      "detailInlineType": {
+        "name": "CollectionPreferencesProps.Preferences<CustomPreferenceType>",
+        "properties": [
+          {
+            "inlineType": {
+              "name": ""compact" | "comfortable"",
+              "type": "union",
+              "values": [
+                "compact",
+                "comfortable",
+              ],
+            },
+            "name": "contentDensity",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "contentDisplay",
+            "optional": true,
+            "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem>",
+          },
+          {
+            "inlineType": {
+              "name": "NonNullable<CustomPreferenceType>",
+              "type": "union",
+              "values": [
+                "CustomPreferenceType",
+                "{}",
+              ],
+            },
+            "name": "custom",
+            "optional": true,
+            "type": "NonNullable<CustomPreferenceType>",
+          },
+          {
+            "name": "pageSize",
+            "optional": true,
+            "type": "number",
+          },
+          {
+            "inlineType": {
+              "name": "StickyColumns",
+              "properties": [
+                {
+                  "name": "first",
+                  "optional": true,
+                  "type": "number",
+                },
+                {
+                  "name": "last",
+                  "optional": true,
+                  "type": "number",
+                },
+              ],
+              "type": "object",
+            },
+            "name": "stickyColumns",
+            "optional": true,
+            "type": "StickyColumns",
+          },
+          {
+            "name": "stripedRows",
+            "optional": true,
+            "type": "boolean",
+          },
+          {
+            "name": "visibleContent",
+            "optional": true,
+            "type": "ReadonlyArray<string>",
+          },
+          {
+            "name": "wrapLines",
+            "optional": true,
+            "type": "boolean",
+          },
+        ],
+        "type": "object",
+      },
+      "detailType": "CollectionPreferencesProps.Preferences<CustomPreferenceType>",
+      "name": "onReset",
+    },
   ],
   "functions": [],
   "name": "CollectionPreferences",
@@ -9925,6 +10012,116 @@ of the most recent getModalRoot call as an argument.",
       "optional": true,
       "type": "((container: HTMLElement | null) => void)",
     },
+    {
+      "description": "Configures the built-in "reset to defaults" affordance.
+
+When set, the component displays a reset button in the modal footer that restores the modal's
+working state to the provided default preferences in a single action. The user still needs to
+confirm the change using the confirm button for it to take effect.
+
+It contains the following:
+- \`label\` (string) - Specifies the text displayed on the reset button.
+- \`preferences\` (CollectionPreferencesProps.Preferences) - Specifies the default preference values the modal
+  is restored to when the user activates the reset button.",
+      "i18nTag": true,
+      "inlineType": {
+        "name": "CollectionPreferencesProps.ResetToDefaults<CustomPreferenceType>",
+        "properties": [
+          {
+            "name": "label",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "inlineType": {
+              "name": "CollectionPreferencesProps.Preferences<CustomPreferenceType>",
+              "properties": [
+                {
+                  "inlineType": {
+                    "name": ""compact" | "comfortable"",
+                    "type": "union",
+                    "values": [
+                      "compact",
+                      "comfortable",
+                    ],
+                  },
+                  "name": "contentDensity",
+                  "optional": true,
+                  "type": "string",
+                },
+                {
+                  "name": "contentDisplay",
+                  "optional": true,
+                  "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem>",
+                },
+                {
+                  "inlineType": {
+                    "name": "NonNullable<CustomPreferenceType>",
+                    "type": "union",
+                    "values": [
+                      "CustomPreferenceType",
+                      "{}",
+                    ],
+                  },
+                  "name": "custom",
+                  "optional": true,
+                  "type": "NonNullable<CustomPreferenceType>",
+                },
+                {
+                  "name": "pageSize",
+                  "optional": true,
+                  "type": "number",
+                },
+                {
+                  "inlineType": {
+                    "name": "StickyColumns",
+                    "properties": [
+                      {
+                        "name": "first",
+                        "optional": true,
+                        "type": "number",
+                      },
+                      {
+                        "name": "last",
+                        "optional": true,
+                        "type": "number",
+                      },
+                    ],
+                    "type": "object",
+                  },
+                  "name": "stickyColumns",
+                  "optional": true,
+                  "type": "StickyColumns",
+                },
+                {
+                  "name": "stripedRows",
+                  "optional": true,
+                  "type": "boolean",
+                },
+                {
+                  "name": "visibleContent",
+                  "optional": true,
+                  "type": "ReadonlyArray<string>",
+                },
+                {
+                  "name": "wrapLines",
+                  "optional": true,
+                  "type": "boolean",
+                },
+              ],
+              "type": "object",
+            },
+            "name": "preferences",
+            "optional": false,
+            "type": "CollectionPreferencesProps.Preferences<CustomPreferenceType>",
+          },
+        ],
+        "type": "object",
+      },
+      "name": "resetToDefaults",
+      "optional": true,
+      "type": "CollectionPreferencesProps.ResetToDefaults<CustomPreferenceType>",
+    },
     {
       "description": "Configures the sticky columns preference that can be set for both left and right columns.
 
@@ -38467,6 +38664,14 @@ To find a specific item use the \`findBreadcrumbLink(n)\` function as chaining \
             "name": "PageSizePreferenceWrapper",
           },
         },
+        {
+          "name": "findResetButton",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "ButtonWrapper",
+          },
+        },
         {
           "name": "findStickyColumnsPreference",
           "parameters": [
@@ -49646,6 +49851,14 @@ To find a specific item use the \`findBreadcrumbLink(n)\` function as chaining \
             "name": "PageSizePreferenceWrapper",
           },
         },
+        {
+          "name": "findResetButton",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "ButtonWrapper",
+          },
+        },
         {
           "name": "findStickyColumnsPreference",
           "parameters": [

src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap

@@ -170,6 +170,7 @@ exports[`test-utils selectors 1`] = `
     "awsui_page-size-form-field_tc96w",
     "awsui_page-size-radio-group_tc96w",
     "awsui_page-size_tc96w",
+    "awsui_reset-button_tc96w",
     "awsui_root_tc96w",
     "awsui_sticky-columns-first_tc96w",
     "awsui_sticky-columns-form-field_tc96w",

src/collection-preferences/__tests__/collection-preferences.test.tsx

@@ -3,7 +3,7 @@
 import React from 'react';
 import { render } from '@testing-library/react';
 
-import CollectionPreferences from '../../../lib/components/collection-preferences';
+import CollectionPreferences, { CollectionPreferencesProps } from '../../../lib/components/collection-preferences';
 import TestI18nProvider from '../../../lib/components/i18n/testing';
 import createWrapper from '../../../lib/components/test-utils/dom';
 import { CollectionPreferencesWrapper } from '../../../lib/components/test-utils/dom';
@@ -307,3 +307,74 @@ describe('i18n', () => {
     expect(modal.findContentDisplayPreference()!.find('[aria-label*="Custom drag handle"')).toBeTruthy();
   });
 });
+
+describe('Collection preferences - Reset to defaults', () => {
+  const resetToDefaults: CollectionPreferencesProps.ResetToDefaults = {
+    label: 'Reset to defaults',
+    preferences: { pageSize: 10, wrapLines: false },
+  };
+
+  test('does not render the reset button when resetToDefaults is not provided', () => {
+    const wrapper = renderCollectionPreferences({});
+    wrapper.findTriggerButton().click();
+    expect(wrapper.findModal()!.findResetButton()).toBeNull();
+  });
+
+  test('renders the reset button with the provided label when resetToDefaults is set', () => {
+    const wrapper = renderCollectionPreferences({ resetToDefaults });
+    wrapper.findTriggerButton().click();
+    const resetButton = wrapper.findModal()!.findResetButton();
+    expect(resetButton).not.toBeNull();
+    expect(resetButton!.findTextRegion()!.getElement()).toHaveTextContent('Reset to defaults');
+  });
+
+  test('calls onReset with the default preferences when clicking the reset button', () => {
+    const onResetSpy = jest.fn();
+    const wrapper = renderCollectionPreferences({
+      resetToDefaults,
+      onReset: onResetSpy,
+      preferences: { pageSize: 50, wrapLines: true },
+    });
+    wrapper.findTriggerButton().click();
+    wrapper.findModal()!.findResetButton()!.click();
+    expect(onResetSpy).toHaveBeenCalledTimes(1);
+    expect(onResetSpy).toHaveBeenCalledWith(expect.objectContaining({ detail: { pageSize: 10, wrapLines: false } }));
+  });
+
+  test('does not throw when onReset is not provided', () => {
+    const wrapper = renderCollectionPreferences({ resetToDefaults });
+    wrapper.findTriggerButton().click();
+    expect(() => wrapper.findModal()!.findResetButton()!.click()).not.toThrow();
+  });
+
+  test('restores the working state so that confirm applies the default preferences', () => {
+    const onConfirmSpy = jest.fn();
+    const wrapper = renderCollectionPreferences({
+      resetToDefaults,
+      onConfirm: onConfirmSpy,
+      preferences: { pageSize: 50, wrapLines: true },
+    });
+    wrapper.findTriggerButton().click();
+    wrapper.findModal()!.findResetButton()!.click();
+    wrapper.findModal()!.findConfirmButton()!.click();
+    expect(onConfirmSpy).toHaveBeenCalledWith(expect.objectContaining({ detail: { pageSize: 10, wrapLines: false } }));
+  });
+
+  test('does not close the modal when clicking the reset button', () => {
+    const wrapper = renderCollectionPreferences({ resetToDefaults });
+    wrapper.findTriggerButton().click();
+    wrapper.findModal()!.findResetButton()!.click();
+    expect(wrapper.findModal()).not.toBeNull();
+  });
+
+  test('supports using resetToDefaults label from i18n provider', () => {
+    const { container } = render(
+      <TestI18nProvider messages={{ 'collection-preferences': { 'resetToDefaults.label': 'Custom reset' } }}>
+        <CollectionPreferences resetToDefaults={{ preferences: {} }} />
+      </TestI18nProvider>
+    );
+    const wrapper = createWrapper(container).findCollectionPreferences()!;
+    wrapper.findTriggerButton().click();
+    expect(wrapper.findModal()!.findResetButton()!.findTextRegion()!.getElement()).toHaveTextContent('Custom reset');
+  });
+});