chore: Warn when columns exceed max value in Key-Value pairs component (#3645)

Co-authored-by: Johannes Weber <[email protected]>

Author: johannes-weber

src/key-value-pairs/__tests__/key-value-pairs.test.tsx

@@ -3,18 +3,29 @@
 import * as React from 'react';
 import { render } from '@testing-library/react';
 
+import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
+
 import Icon from '../../../lib/components/icon';
 import KeyValuePairs from '../../../lib/components/key-value-pairs';
 import Link from '../../../lib/components/link';
 import SpaceBetween from '../../../lib/components/space-between';
 import createWrapper, { IconWrapper } from '../../../lib/components/test-utils/dom';
 
+jest.mock('@cloudscape-design/component-toolkit/internal', () => ({
+  ...jest.requireActual('@cloudscape-design/component-toolkit/internal'),
+  warnOnce: jest.fn(),
+}));
+
 function renderKeyValuePairs(jsx: React.ReactElement) {
   const { container, ...rest } = render(jsx);
   return { wrapper: createWrapper(container).findKeyValuePairs()!, ...rest };
 }
 
 describe('KeyValuePairs', () => {
+  afterEach(() => {
+    (warnOnce as jest.Mock).mockReset();
+  });
+
   describe('item rendering', () => {
     test('renders correctly', () => {
       const { wrapper } = renderKeyValuePairs(
@@ -95,6 +106,25 @@ describe('KeyValuePairs', () => {
     });
   });
 
+  describe('warnOnce when columns property exceeds max', () => {
+    test.each([
+      { columns: 1, warnOnceMessage: false },
+      { columns: 2, warnOnceCalled: false },
+      {
+        columns: 3,
+        warnOnceCalled: false,
+      },
+      { columns: 4, warnOnceCalled: false },
+      {
+        columns: 5,
+        warnOnceCalled: true,
+      },
+    ])(`warnOnce called = $warnOnceCalled when columns is set to $columns`, ({ columns, warnOnceCalled }) => {
+      renderKeyValuePairs(<KeyValuePairs items={[]} columns={columns} />);
+      expect(warnOnce).toHaveBeenCalledTimes(warnOnceCalled ? 1 : 0);
+    });
+  });
+
   describe('column layout', () => {
     test('renders correctly', () => {
       const { wrapper } = renderKeyValuePairs(

src/key-value-pairs/internal.tsx

@@ -3,7 +3,7 @@
 import React from 'react';
 import clsx from 'clsx';
 
-import { useUniqueId } from '@cloudscape-design/component-toolkit/internal';
+import { useUniqueId, warnOnce } from '@cloudscape-design/component-toolkit/internal';
 
 import Box from '../box/internal';
 import ColumnLayout from '../column-layout/internal';
@@ -51,6 +51,15 @@ const InternalKeyValuePairs = React.forwardRef(
     }: KeyValuePairsProps & Required<Pick<KeyValuePairsProps, 'columns'>>,
     ref: React.Ref<HTMLDivElement>
   ) => {
+    const MAX_COLUMNS = 4;
+
+    if (columns > MAX_COLUMNS) {
+      warnOnce(
+        'Key-value pairs',
+        `\`columns\` (${columns}) must be <= ${MAX_COLUMNS}. Using ${MAX_COLUMNS} as default.`
+      );
+    }
+
     return (
       <LinkDefaultVariantContext.Provider value={{ defaultVariant: 'primary' }}>
         <div
@@ -66,7 +75,7 @@ const InternalKeyValuePairs = React.forwardRef(
         */}
           <ColumnLayout
             __tagOverride="dl"
-            columns={Math.min(columns, 4)}
+            columns={Math.min(columns, MAX_COLUMNS)}
             variant="text-grid"
             minColumnWidth={minColumnWidth}
           >