box-ui-elements 24.0.0-beta.4 → 24.0.0-beta.5

package/src/elements/content-explorer/MetadataSidePanel.tsx

@@ -1,7 +1,7 @@
 import React, { useState } from 'react';
 import { useIntl } from 'react-intl';
 
-import { IconButton, SidePanel, Text } from '@box/blueprint-web';
+import { IconButton, SidePanel, Text, useNotification } from '@box/blueprint-web';
 import { XMark } from '@box/blueprint-web-assets/icons/Fill/index';
 import { FileDefault } from '@box/blueprint-web-assets/icons/Line/index';
 import {
@@ -10,12 +10,13 @@ import {
     JSONPatchOperations,
     MetadataInstance,
     MetadataInstanceForm,
+    type MetadataTemplateField,
 } from '@box/metadata-editor';
 
 import type { Selection } from 'react-aria-components';
-import type { Collection } from '../../common/types/core';
+import type { BoxItem, Collection } from '../../common/types/core';
 import type { MetadataTemplate } from '../../common/types/metadata';
-import { getTemplateInstance, useSelectedItemText } from './utils';
+import { useTemplateInstance, useSelectedItemText } from './utils';
 
 import messages from '../common/messages';
 
@@ -23,17 +24,29 @@ import './MetadataSidePanel.scss';
 
 export interface MetadataSidePanelProps {
     currentCollection: Collection;
-    onClose: () => void;
     metadataTemplate: MetadataTemplate;
+    onClose: () => void;
+    onUpdate: (
+        items: BoxItem[],
+        operations: JSONPatchOperations,
+        templateOldFields: MetadataTemplateField[],
+        templateNewFields: MetadataTemplateField[],
+        successCallback: () => void,
+        errorCallback: ErrorCallback,
+    ) => Promise<void>;
+    refreshCollection: () => void;
     selectedItemIds: Selection;
 }
 
 const MetadataSidePanel = ({
     currentCollection,
+    metadataTemplate,
     onClose,
+    onUpdate,
+    refreshCollection,
     selectedItemIds,
-    metadataTemplate,
 }: MetadataSidePanelProps) => {
+    const { addNotification } = useNotification();
     const { formatMessage } = useIntl();
     const [isEditing, setIsEditing] = useState<boolean>(false);
     const [isUnsavedChangesModalOpen, setIsUnsavedChangesModalOpen] = useState<boolean>(false);
@@ -43,7 +56,7 @@ const MetadataSidePanel = ({
         selectedItemIds === 'all'
             ? currentCollection.items
             : currentCollection.items.filter(item => selectedItemIds.has(item.id));
-    const templateInstance = getTemplateInstance(metadataTemplate, selectedItems);
+    const templateInstance = useTemplateInstance(metadataTemplate, selectedItems, isEditing);
 
     const handleMetadataInstanceEdit = () => {
         setIsEditing(true);
@@ -53,19 +66,47 @@ const MetadataSidePanel = ({
         setIsEditing(false);
     };
 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const handleMetadataInstanceFormChange = (values: FormValues) => {
-        // TODO: Implement on form change
-    };
-
     const handleMetadataInstanceFormDiscardUnsavedChanges = () => {
         setIsUnsavedChangesModalOpen(false);
         setIsEditing(false);
     };
 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const handleUpdateMetadataSuccess = () => {
+        addNotification({
+            closeButtonAriaLabel: formatMessage(messages.close),
+            sensitivity: 'foreground',
+            styledText: formatMessage(messages.metadataUpdateSuccessNotification, {
+                numSelected: selectedItems.length,
+            }),
+            typeIconAriaLabel: formatMessage(messages.success),
+            variant: 'success',
+        });
+        setIsEditing(false);
+        refreshCollection();
+    };
+
+    const handleUpdateMetadataError = () => {
+        addNotification({
+            closeButtonAriaLabel: formatMessage(messages.close),
+            sensitivity: 'foreground',
+            styledText: formatMessage(messages.metadataUpdateErrorNotification),
+            typeIconAriaLabel: formatMessage(messages.error),
+            variant: 'error',
+        });
+    };
+
     const handleMetadataInstanceFormSubmit = async (values: FormValues, operations: JSONPatchOperations) => {
-        // TODO: Implement onSave callback
+        const { fields: templateNewFields } = values.metadata;
+        const { fields: templateOldFields } = templateInstance;
+
+        await onUpdate(
+            selectedItems,
+            operations,
+            templateOldFields,
+            templateNewFields,
+            handleUpdateMetadataSuccess,
+            handleUpdateMetadataError,
+        );
     };
 
     return (
@@ -99,7 +140,7 @@ const MetadataSidePanel = ({
                                 isUnsavedChangesModalOpen={isUnsavedChangesModalOpen}
                                 selectedTemplateInstance={templateInstance}
                                 onCancel={handleMetadataInstanceFormCancel}
-                                onChange={handleMetadataInstanceFormChange}
+                                onChange={null}
                                 onDelete={null}
                                 onDiscardUnsavedChanges={handleMetadataInstanceFormDiscardUnsavedChanges}
                                 onSubmit={handleMetadataInstanceFormSubmit}

package/src/elements/content-explorer/MetadataViewContainer.tsx

@@ -1,7 +1,9 @@
 import * as React from 'react';
 import type { EnumType, FloatType, MetadataFormFieldValue, RangeType } from '@box/metadata-filter';
 import { MetadataView, type MetadataViewProps } from '@box/metadata-view';
+import { type Key } from '@react-types/shared';
 
+import { SortDescriptor } from 'react-aria-components';
 import type { Collection } from '../../common/types/core';
 import type { MetadataTemplate } from '../../common/types/metadata';
 
@@ -25,6 +27,21 @@ type ActionBarProps = Omit<
     onFilterSubmit?: (filterValues: ExternalFilterValues) => void;
 };
 
+/**
+ * Helper function to trim metadataFieldNamePrefix from column names
+ * For example: 'metadata.enterprise_1515946.mdViewTemplate1.industry' -> 'industry'
+ */
+function trimMetadataFieldPrefix(column: string): string {
+    // Check if the column starts with 'metadata.' and contains at least 2 dots
+    if (column.startsWith('metadata.') && column.split('.').length >= 3) {
+        // Split by dots and take everything after the first 3 parts
+        // metadata.enterprise_1515946.mdViewTemplate1.industry -> industry
+        const parts = column.split('.');
+        return parts.slice(3).join('.');
+    }
+    return column;
+}
+
 function transformInitialFilterValuesToInternal(
     publicValues?: ExternalFilterValues,
 ): Record<string, { value: MetadataFormFieldValue }> | undefined {
@@ -55,6 +72,8 @@ export interface MetadataViewContainerProps extends Omit<MetadataViewProps, 'ite
     actionBarProps?: ActionBarProps;
     currentCollection: Collection;
     metadataTemplate: MetadataTemplate;
+    /* Internally controlled onSortChange prop for the MetadataView component. */
+    onSortChange?: (sortBy: Key, sortDirection: string) => void;
 }
 
 const MetadataViewContainer = ({
@@ -62,6 +81,7 @@ const MetadataViewContainer = ({
     columns,
     currentCollection,
     metadataTemplate,
+    onSortChange: onSortChangeInternal,
     ...rest
 }: MetadataViewContainerProps) => {
     const { items = [] } = currentCollection;
@@ -111,7 +131,47 @@ const MetadataViewContainer = ({
         };
     }, [actionBarProps, initialFilterValues, onFilterSubmit, filterGroups]);
 
-    return <MetadataView actionBarProps={transformedActionBarProps} columns={columns} items={items} {...rest} />;
+    // Extract the original tableProps.onSortChange from rest
+    const { tableProps, ...otherRest } = rest;
+    const onSortChangeExternal = tableProps?.onSortChange;
+
+    // Create a wrapper function that calls both. The wrapper function should follow the signature of onSortChange from RAC
+    const handleSortChange = React.useCallback(
+        ({ column, direction }: SortDescriptor) => {
+            // Call the internal onSortChange first
+            // API accepts asc/desc "https://developer.box.com/reference/post-metadata-queries-execute-read/"
+            if (onSortChangeInternal) {
+                const trimmedColumn = trimMetadataFieldPrefix(String(column));
+                onSortChangeInternal(trimmedColumn, direction === 'ascending' ? 'ASC' : 'DESC');
+            }
+
+            // Then call the original customer-provided onSortChange if it exists
+            // Accepts "ascending" / "descending" (https://react-spectrum.adobe.com/react-aria/Table.html)
+            if (onSortChangeExternal) {
+                onSortChangeExternal({
+                    column,
+                    direction,
+                });
+            }
+        },
+        [onSortChangeInternal, onSortChangeExternal],
+    );
+
+    // Create new tableProps with our wrapper function
+    const newTableProps = {
+        ...tableProps,
+        onSortChange: handleSortChange,
+    };
+
+    return (
+        <MetadataView
+            actionBarProps={transformedActionBarProps}
+            columns={columns}
+            items={items}
+            tableProps={newTableProps}
+            {...otherRest}
+        />
+    );
 };
 
 export default MetadataViewContainer;

package/src/elements/content-explorer/__tests__/ContentExplorer.test.tsx

@@ -454,7 +454,7 @@ describe('elements/content-explorer/ContentExplorer', () => {
                     textValue: 'Name',
                     id: 'name',
                     type: 'string' as const,
-                    allowSorting: true,
+                    allowsSorting: true,
                     minWidth: 150,
                     maxWidth: 150,
                 },
@@ -462,7 +462,7 @@ describe('elements/content-explorer/ContentExplorer', () => {
                     textValue: field.displayName,
                     id: `${metadataFieldNamePrefix}.${field.key}`,
                     type: field.type as MetadataFieldType,
-                    allowSorting: true,
+                    allowsSorting: true,
                     minWidth: 150,
                     maxWidth: 150,
                 })),
@@ -506,6 +506,40 @@ describe('elements/content-explorer/ContentExplorer', () => {
                 expect(screen.getByRole('button', { name: 'Metadata' })).toBeInTheDocument();
             });
 
+            test('should call both internal and user onSortChange callbacks when sorting by a metadata field', async () => {
+                const mockOnSortChangeInternal = jest.fn();
+                const mockOnSortChangeExternal = jest.fn();
+
+                renderComponent({
+                    ...metadataViewV2ElementProps,
+                    metadataViewProps: {
+                        ...metadataViewV2ElementProps.metadataViewProps,
+                        onSortChange: mockOnSortChangeInternal, // Internal callback - receives trimmed column name
+                        tableProps: {
+                            ...metadataViewV2ElementProps.metadataViewProps.tableProps,
+                            onSortChange: mockOnSortChangeExternal, // User callback - receives full column ID
+                        },
+                    },
+                });
+
+                const industryHeader = await screen.findByRole('columnheader', { name: 'Industry' });
+                expect(industryHeader).toBeInTheDocument();
+
+                const firstRow = await screen.findByRole('row', { name: /Child 2/i });
+                expect(firstRow).toBeInTheDocument();
+
+                await userEvent.click(industryHeader);
+
+                // Internal callback gets trimmed version for API calls
+                expect(mockOnSortChangeInternal).toHaveBeenCalledWith('industry', 'ASC');
+
+                // User callback gets full column ID with direction
+                expect(mockOnSortChangeExternal).toHaveBeenCalledWith({
+                    column: 'metadata.enterprise_0.templateName.industry',
+                    direction: 'ascending',
+                });
+            });
+
             test('should call onClick when bulk item action is clicked', async () => {
                 let mockOnClickArg;
                 const mockOnClick = jest.fn(arg => {

package/src/elements/content-explorer/__tests__/MetadataQueryAPIHelper.test.ts

@@ -8,7 +8,7 @@ import {
     JSON_PATCH_OP_REPLACE,
     JSON_PATCH_OP_TEST,
 } from '../../../common/constants';
-import { FIELD_METADATA, FIELD_NAME, FIELD_EXTENSION } from '../../../constants';
+import { FIELD_METADATA, FIELD_NAME, FIELD_EXTENSION, FIELD_PERMISSIONS } from '../../../constants';
 
 describe('features/metadata-based-view/MetadataQueryAPIHelper', () => {
     let metadataQueryAPIHelper;
@@ -426,27 +426,30 @@ describe('features/metadata-based-view/MetadataQueryAPIHelper', () => {
                 expect(isArray(updatedMetadataQuery.fields)).toBe(true);
                 expect(includes(updatedMetadataQuery.fields, FIELD_NAME)).toBe(true);
                 expect(includes(updatedMetadataQuery.fields, FIELD_EXTENSION)).toBe(true);
+                expect(includes(updatedMetadataQuery.fields, FIELD_PERMISSIONS)).toBe(true);
 
                 if (index === 2) {
-                    // Verify "name" and "extension" are added to pre-existing fields
+                    // Verify "name", "extension" and "permission" are added to pre-existing fields
                     expect(updatedMetadataQuery.fields).toEqual([
                         ...mdQueryWithoutNameField.fields,
                         FIELD_NAME,
                         FIELD_EXTENSION,
+                        FIELD_PERMISSIONS,
                     ]);
                 }
 
                 if (index === 4) {
-                    // Verify "extension" is added when "name" exists but "extension" doesn't
+                    // Verify "extension" and "permission" are added when "name" exists but "extension" and "permission" don't
                     expect(updatedMetadataQuery.fields).toEqual([
                         ...mdQueryWithoutExtensionField.fields,
                         FIELD_EXTENSION,
+                        FIELD_PERMISSIONS,
                     ]);
                 }
 
                 if (index === 5) {
-                    // No change, original query has all necessary fields
-                    expect(updatedMetadataQuery.fields).toEqual(mdQueryWithBothFields.fields);
+                    // Verify "permission" is added
+                    expect(updatedMetadataQuery.fields).toEqual([...mdQueryWithBothFields.fields, FIELD_PERMISSIONS]);
                 }
             },
         );

package/src/elements/content-explorer/__tests__/MetadataSidePanel.test.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import userEvent from '@testing-library/user-event';
-import { render, screen } from '../../../test-utils/testing-library';
+import { Notification } from '@box/blueprint-web';
+import { render, screen, waitFor } from '../../../test-utils/testing-library';
 import MetadataSidePanel, { type MetadataSidePanelProps } from '../MetadataSidePanel';
 
 // Mock scrollTo method
@@ -65,13 +66,20 @@ const mockOnClose = jest.fn();
 describe('elements/content-explorer/MetadataSidePanel', () => {
     const defaultProps: MetadataSidePanelProps = {
         currentCollection: mockCollection,
-        onClose: mockOnClose,
         metadataTemplate: mockMetadataTemplate,
+        onClose: mockOnClose,
+        onUpdate: jest.fn(),
+        refreshCollection: jest.fn(),
         selectedItemIds: new Set(['1']),
     };
 
     const renderComponent = (props: Partial<MetadataSidePanelProps> = {}) =>
-        render(<MetadataSidePanel {...defaultProps} {...props} />);
+        render(
+            <Notification.Provider>
+                <Notification.Viewport />
+                <MetadataSidePanel {...defaultProps} {...props} />
+            </Notification.Provider>,
+        );
 
     test('renders the metadata title', () => {
         renderComponent();
@@ -124,4 +132,138 @@ describe('elements/content-explorer/MetadataSidePanel', () => {
         const submitButton = screen.getByRole('button', { name: 'Save' });
         expect(submitButton).toBeInTheDocument();
     });
+
+    test('switches back to view mode when cancel button is clicked', async () => {
+        renderComponent();
+        const editTemplateButton = screen.getByLabelText('Edit Mock Template');
+        await userEvent.click(editTemplateButton);
+
+        const cancelButton = screen.getByRole('button', { name: 'Cancel' });
+        await userEvent.click(cancelButton);
+
+        // Should be back in view mode
+        expect(screen.getByLabelText('Edit Mock Template')).toBeInTheDocument();
+    });
+
+    test('calls onUpdate when form is submitted for single item', async () => {
+        const mockUpdateMetadata = jest.fn().mockResolvedValue(undefined);
+        renderComponent({ onUpdate: mockUpdateMetadata });
+
+        const editTemplateButton = screen.getByLabelText('Edit Mock Template');
+        await userEvent.click(editTemplateButton);
+
+        const submitButton = screen.getByRole('button', { name: 'Save' });
+        await userEvent.click(submitButton);
+
+        expect(mockUpdateMetadata).toHaveBeenCalledWith(
+            [mockCollection.items[0]],
+            expect.any(Array),
+            expect.any(Array),
+            expect.any(Array),
+            expect.any(Function),
+            expect.any(Function),
+        );
+    });
+
+    test('calls onUpdate when multiple items are selected', async () => {
+        const mockUpdateMetadata = jest.fn().mockResolvedValue(undefined);
+
+        renderComponent({
+            selectedItemIds: new Set(['1', '2']),
+            onUpdate: mockUpdateMetadata,
+        });
+
+        const editTemplateButton = screen.getByLabelText('Edit Mock Template');
+        await userEvent.click(editTemplateButton);
+
+        const submitButton = screen.getByRole('button', { name: 'Save' });
+        await userEvent.click(submitButton);
+
+        await waitFor(() => {
+            expect(mockUpdateMetadata).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    test('displays success notification when metadata update succeeds', async () => {
+        const mockUpdateMetadata = jest.fn().mockImplementation((_, __, ___, ____, successCallback) => {
+            successCallback();
+            return Promise.resolve();
+        });
+        const mockRefreshCollection = jest.fn();
+
+        renderComponent({
+            onUpdate: mockUpdateMetadata,
+            refreshCollection: mockRefreshCollection,
+        });
+
+        const editTemplateButton = screen.getByLabelText('Edit Mock Template');
+        await userEvent.click(editTemplateButton);
+
+        const submitButton = screen.getByRole('button', { name: 'Save' });
+        await userEvent.click(submitButton);
+
+        expect(screen.getByText('1 document updated')).toBeInTheDocument();
+        expect(mockRefreshCollection).toHaveBeenCalledTimes(1);
+        expect(screen.getByLabelText('Edit Mock Template')).toBeInTheDocument(); // Back to view mode
+    });
+
+    test('displays error notification when metadata update fails', async () => {
+        const mockUpdateMetadata = jest.fn().mockImplementation((_, __, ___, ____, _____, errorCallback) => {
+            errorCallback();
+            return Promise.resolve();
+        });
+
+        renderComponent({ onUpdate: mockUpdateMetadata });
+
+        const editTemplateButton = screen.getByLabelText('Edit Mock Template');
+        await userEvent.click(editTemplateButton);
+
+        const submitButton = screen.getByRole('button', { name: 'Save' });
+        await userEvent.click(submitButton);
+
+        await waitFor(() => {
+            expect(screen.getByText('Unable to save changes. Please try again.')).toBeInTheDocument();
+        });
+    });
+
+    test('handles "all" selection correctly', () => {
+        renderComponent({ selectedItemIds: 'all' });
+        const subtitle = screen.getByText('2 files selected');
+        expect(subtitle).toBeInTheDocument();
+    });
+
+    test('displays "Multiple Values" for items with different field values', () => {
+        const collectionWithDifferentValues = {
+            ...mockCollection,
+            items: [
+                {
+                    ...mockCollection.items[0],
+                    metadata: {
+                        enterprise_123: {
+                            mockTemplate: {
+                                alias: 'value-1',
+                            },
+                        },
+                    },
+                },
+                {
+                    ...mockCollection.items[1],
+                    metadata: {
+                        enterprise_123: {
+                            mockTemplate: {
+                                alias: 'value-2',
+                            },
+                        },
+                    },
+                },
+            ],
+        };
+
+        renderComponent({
+            currentCollection: collectionWithDifferentValues,
+            selectedItemIds: new Set(['1', '2']),
+        });
+
+        expect(screen.getByText('Multiple Values')).toBeInTheDocument();
+    });
 });

package/src/elements/content-explorer/stories/tests/MetadataView-visual.stories.tsx

@@ -3,7 +3,9 @@ import { http, HttpResponse } from 'msw';
 import { Download, SignMeOthers } from '@box/blueprint-web-assets/icons/Fill/index';
 import { Sign } from '@box/blueprint-web-assets/icons/Line';
 import { expect, fn, userEvent, waitFor, within, screen } from 'storybook/test';
+
 import noop from 'lodash/noop';
+import orderBy from 'lodash/orderBy';
 
 import ContentExplorer from '../../ContentExplorer';
 import { DEFAULT_HOSTNAME_API } from '../../../../constants';
@@ -138,17 +140,16 @@ export const metadataViewV2: Story = {
     args: metadataViewV2ElementProps,
 };
 
-// @TODO Assert that rows are actually sorted in a different order, once handleSortChange is implemented
 export const metadataViewV2SortsFromHeader: Story = {
     args: metadataViewV2ElementProps,
     play: async ({ canvas }) => {
-        await waitFor(() => {
-            expect(canvas.getByRole('row', { name: /Industry/i })).toBeInTheDocument();
-        });
+        const industryHeader = await canvas.findByRole('columnheader', { name: 'Industry' });
+        expect(industryHeader).toBeInTheDocument();
+
+        const firstRow = await canvas.findByRole('row', { name: /Child 2/i });
+        expect(firstRow).toBeInTheDocument();
 
-        const firstRow = canvas.getByRole('row', { name: /Industry/i });
-        const industryHeader = within(firstRow).getByRole('columnheader', { name: 'Industry' });
-        userEvent.click(industryHeader);
+        await userEvent.click(industryHeader);
     },
 };
 
@@ -237,6 +238,37 @@ export const metadataViewV2WithBulkItemActionMenuShowsItemActionMenu: Story = {
     },
 };
 
+export const sidePanelOpenWithMultipleItemsSelected: Story = {
+    args: {
+        ...metadataViewV2ElementProps,
+        metadataViewProps: {
+            columns,
+            tableProps: {
+                isSelectAllEnabled: true,
+            },
+        },
+    },
+
+    play: async ({ canvas }) => {
+        await waitFor(() => {
+            expect(canvas.getByRole('row', { name: /Child 2/i })).toBeInTheDocument();
+        });
+
+        // Select the first row by clicking its checkbox
+        const firstItem = canvas.getByRole('row', { name: /Child 2/i });
+        const checkbox = within(firstItem).getByRole('checkbox');
+        await userEvent.click(checkbox);
+
+        // Select the second row by clicking its checkbox
+        const secondItem = canvas.getAllByRole('row', { name: /Child 1/i })[0];
+        const secondCheckbox = within(secondItem).getByRole('checkbox');
+        await userEvent.click(secondCheckbox);
+
+        const metadataButton = canvas.getByRole('button', { name: 'Metadata' });
+        await userEvent.click(metadataButton);
+    },
+};
+
 const meta: Meta<typeof ContentExplorer> = {
     title: 'Elements/ContentExplorer/tests/MetadataView/visual',
     component: ContentExplorer,
@@ -248,7 +280,21 @@ const meta: Meta<typeof ContentExplorer> = {
     parameters: {
         msw: {
             handlers: [
-                http.post(`${DEFAULT_HOSTNAME_API}/2.0/metadata_queries/execute_read`, () => {
+                // Note that the Metadata API backend normally handles the sorting. The mocks below simulate the sorting for specific cases, but may not 100% accurately reflect the backend behavior.
+                http.post(`${DEFAULT_HOSTNAME_API}/2.0/metadata_queries/execute_read`, async ({ request }) => {
+                    const body = await request.clone().json();
+                    const orderByDirection = body.order_by[0].direction;
+                    const orderByFieldKey = body.order_by[0].field_key;
+
+                    // Hardcoded case for sorting by industry
+                    if (orderByFieldKey === `industry` && orderByDirection === 'ASC') {
+                        const sortedMetadata = orderBy(
+                            mockMetadata.entries,
+                            'metadata.enterprise_0.templateName.industry',
+                            'asc',
+                        );
+                        return HttpResponse.json({ ...mockMetadata, entries: sortedMetadata });
+                    }
                     return HttpResponse.json(mockMetadata);
                 }),
                 http.get(`${DEFAULT_HOSTNAME_API}/2.0/metadata_templates/enterprise/templateName/schema`, () => {