feat(FileUploader): add enhanced callbacks with feature flag (#20005)

* feat(FileUploader): add enhanced callbacks with feature flag

* fix: use crypto.getRandomValues

* test: adds test

* chore: snapshots

* refactor: fix import

---------

Co-authored-by: Taylor Jones <tay1orjones@users.noreply.github.com>
Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>
Co-authored-by: kennylam <909118+kennylam@users.noreply.github.com>

Author: 4 people

packages/feature-flags/feature-flags.yml

@@ -58,3 +58,9 @@ feature-flags:
     description: >
       Enable a reduced spacing between the toggle control and its label
     enabled: false
+  - name: enable-enhanced-file-uploader
+    description: >
+      Enable enhanced functionality for the FileUploader component, including
+      richer callback data and expanded trigger events for onChange and
+      onDelete.
+    enabled: false

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -3470,6 +3470,9 @@ Map {
       "enableDialogElement": {
         "type": "bool",
       },
+      "enableEnhancedFileUploader": {
+        "type": "bool",
+      },
       "enableExperimentalFocusWrapWithoutSentinels": {
         "type": "bool",
       },
@@ -3565,7 +3568,9 @@ Map {
         "args": [
           [
             "sm",
+            "small",
             "md",
+            "field",
             "lg",
           ],
         ],
@@ -10426,6 +10431,9 @@ Map {
       "enableDialogElement": {
         "type": "bool",
       },
+      "enableEnhancedFileUploader": {
+        "type": "bool",
+      },
       "enableExperimentalFocusWrapWithoutSentinels": {
         "type": "bool",
       },

packages/react/src/components/FeatureFlags/__tests__/FeatureFlags-test.js

@@ -633,5 +633,58 @@ describe('FeatureFlags', () => {
         enableV12DynamicFloatingStyles: true,
       });
     });
+    it('enable-enhanced-file-uploader - enableEnhancedFileUploader', () => {
+      const checkFlags = jest.fn();
+      const checkFlag = jest.fn();
+
+      function TestComponent() {
+        const featureFlags = useFeatureFlags();
+        const enableEnhancedFileUploader = useFeatureFlag(
+          'enable-enhanced-file-uploader'
+        );
+
+        checkFlags({
+          enableEnhancedFileUploader: featureFlags.enabled(
+            'enable-enhanced-file-uploader'
+          ),
+        });
+
+        checkFlag({
+          enableEnhancedFileUploader,
+        });
+
+        return null;
+      }
+
+      // Render the default
+      const { rerender } = render(
+        <FeatureFlags>
+          <TestComponent />
+        </FeatureFlags>
+      );
+
+      // Ensure the default value is as defined and as expected
+      expect(checkFlags).toHaveBeenLastCalledWith({
+        enableEnhancedFileUploader: false,
+      });
+      expect(checkFlag).toHaveBeenLastCalledWith({
+        enableEnhancedFileUploader: false,
+      });
+
+      // Enable the flag
+      rerender(
+        <FeatureFlags enableEnhancedFileUploader>
+          <TestComponent />
+        </FeatureFlags>
+      );
+
+      // Ensure that when enabled, this flag is true and does not error
+      expect(checkFlags).toHaveBeenLastCalledWith({
+        enableEnhancedFileUploader: true,
+      });
+      expect(checkFlag).toHaveBeenLastCalledWith({
+        enableEnhancedFileUploader: true,
+      });
+    });
   });
 });

packages/react/src/components/FeatureFlags/index.tsx

@@ -31,6 +31,7 @@ export interface FeatureFlagsProps {
   enableExperimentalFocusWrapWithoutSentinels?: boolean;
   enableDialogElement?: boolean;
   enableV12DynamicFloatingStyles?: boolean;
+  enableEnhancedFileUploader?: boolean;
 }
 /**
  * Our FeatureFlagContext is used alongside the FeatureFlags component to enable
@@ -53,6 +54,7 @@ function FeatureFlags({
   enableExperimentalFocusWrapWithoutSentinels = false,
   enableDialogElement = false,
   enableV12DynamicFloatingStyles = false,
+  enableEnhancedFileUploader = false,
 }: FeatureFlagsProps): JSX.Element {
   const parentScope = useContext(FeatureFlagContext);
   const [prevParentScope, setPrevParentScope] = useState(parentScope);
@@ -66,6 +68,7 @@ function FeatureFlags({
       enableExperimentalFocusWrapWithoutSentinels,
     'enable-dialog-element': enableDialogElement,
     'enable-v12-dynamic-floating-styles': enableV12DynamicFloatingStyles,
+    'enable-enhanced-file-uploader': enableEnhancedFileUploader,
     ...flags,
   };
   const [scope, updateScope] = useState(() => {
@@ -116,6 +119,7 @@ FeatureFlags.propTypes = {
   enableExperimentalFocusWrapWithoutSentinels: PropTypes.bool,
   enableDialogElement: PropTypes.bool,
   enableV12DynamicFloatingStyles: PropTypes.bool,
+  enableEnhancedFileUploader: PropTypes.bool,
 };
 
 /**

packages/react/src/components/FeatureFlags/overview.mdx

@@ -56,6 +56,7 @@ in the Carbon monorepo.
 | `enable-v12-structured-list-visible-icons`         | Enable icon components within StructuredList to always be visible                    | `false` |                 | ✅        | [enable-v12-structured-list-visible-icons](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade#enable-v12-structured-list-visible-icons) |
 | `enable-v12-dynamic-floating-styles`               | Enable dynamic setting of floating styles for components like Popover, Tooltip, etc. | `false` | ✅              |           | No - App level    |
 | `enable-v12-toggle-reduced-label-spacing`          | Enable a reduced spacing between the toggle control and its label                    | `false` |                 | ✅        | No - Style only   |
+| `enable-enhanced-file-uploader`                    | Enable enhanced FileUploader callbacks with richer data and expanded triggers.       | `false` | ✅              |           | No - Config only  |
 
 
 ## Turning on feature flags in Javascript/react

packages/react/src/components/FileUploader/FileUploader.featureflag.mdx

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/FileUploader/Feature Flag" name="Flag details" />
+
+# Enhanced FileUploader Callbacks
+
+The `enable-enhanced-file-uploader` flag enables enhanced functionality for the
+FileUploader component, including richer callback data and expanded trigger
+events for `onChange` and `onDelete`.
+
+When this flag is enabled, the `onChange` callback is consistently triggered for
+all file list modifications (additions, deletions, programmatic clears), and both
+`onChange` and `onDelete` events are augmented with detailed file information
+like `deletedFile`, `addedFiles`, and `currentFiles` on `event.target`.
+
+## Enable enhanced FileUploader callbacks
+
+```js
+<FeatureFlags enableEnhancedFileUploader={true}>
+  <FileUploader
+    multiple
+    filenameStatus="edit"
+    onChange={(evt) => console.log('onChange', evt.target.action, evt.target.currentFiles)}
+    onDelete={(evt) => console.log('onDelete', evt.target.deletedFile)}
+  />
+</FeatureFlags>

packages/react/src/components/FileUploader/FileUploader.featureflag.stories.js

@@ -0,0 +1,100 @@
+/**
+ * Copyright IBM Corp. 2016, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import { FileUploader } from '../FileUploader';
+import { WithFeatureFlags } from '../../../.storybook/templates/WithFeatureFlags';
+
+export default {
+  title: 'Components/FileUploader/Feature Flag',
+  component: FileUploader,
+  tags: ['!autodocs'],
+  decorators: [
+    (Story) => (
+      <WithFeatureFlags
+        flags={{
+          'enable-enhanced-file-uploader': true,
+        }}>
+        <Story />
+      </WithFeatureFlags>
+    ),
+  ],
+};
+
+export const EnhancedCallbacks = (args) => {
+  const handleChange = (event, data) => {
+    console.log('  Action:', event.target.action);
+
+    if (event.target.addedFiles) {
+      console.log(
+        '  Added Files:',
+        event.target.addedFiles.map((f) => ({ name: f.name, uuid: f.uuid }))
+      );
+    }
+
+    if (event.target.deletedFile) {
+      console.log('  Deleted File:', {
+        name: event.target.deletedFile.name,
+        uuid: event.target.deletedFile.uuid,
+      });
+    }
+
+    if (event.target.clearedFiles) {
+      console.log(
+        '  Cleared Files:',
+        event.target.clearedFiles.map((f) => ({ name: f.name, uuid: f.uuid }))
+      );
+    }
+
+    console.log(
+      '  Current Files:',
+      event.target.currentFiles?.map((f) => ({ name: f.name, uuid: f.uuid })) ||
+        []
+    );
+  };
+
+  const handleDelete = (event, data) => {
+    console.log('  Deleted File Object:', event.target.deletedFile);
+    console.log('  Deleted File Name:', event.target.deletedFile?.name);
+    console.log(
+      '  Remaining Files:',
+      event.target.remainingFiles?.map((f) => ({
+        name: f.name,
+        uuid: f.uuid,
+      })) || []
+    );
+  };
+
+  return (
+    <div>
+      <FileUploader
+        labelTitle="Enhanced FileUploader Demo"
+        labelDescription="Open browser console to see detailed callback data when adding/removing files"
+        buttonLabel="Add file(s)"
+        buttonKind="primary"
+        filenameStatus="edit"
+        multiple={true}
+        onChange={handleChange}
+        onDelete={handleDelete}
+        iconDescription="Remove uploaded file"
+        {...args}
+      />
+    </div>
+  );
+};
+
+EnhancedCallbacks.args = {
+  disabled: false,
+};
+
+EnhancedCallbacks.argTypes = {
+  disabled: {
+    control: {
+      type: 'boolean',
+    },
+  },
+};