[LG-5457] feat(suggestions): restrict ConfigurationParameter types to enhance API clarity (#3093)

* refactor(suggestions): clean up ConfigurationParameter types for better state management

* chore(suggestions): changeset

* test(suggestions): add type specs

Author: stephl3

.changeset/cute-zebras-tickle.md

@@ -0,0 +1,5 @@
+---
+'@lg-chat/suggestions': patch
+---
+
+[LG-5457](https://jira.mongodb.org/browse/LG-5457): restrict `ConfigurationParameter` types to enhance API clarity

chat/suggestions/src/StatusBanner/StatusBanner.tsx

@@ -2,7 +2,11 @@ import React from 'react';
 
 import Banner, { Variant as BannerVariant } from '@leafygreen-ui/banner';
 
-import { ConfigurationParameter, State } from '../shared.types';
+import {
+  ErrorConfigurationParameter,
+  State,
+  SuccessConfigurationParameter,
+} from '../shared.types';
 
 import {
   bannerWrapperStyles,
@@ -16,11 +20,13 @@ export const StatusBanner = ({
   failedParameters,
 }: {
   state: State;
-  appliedParameters?: Array<ConfigurationParameter>;
-  failedParameters?: Array<ConfigurationParameter>;
+  appliedParameters?: Array<SuccessConfigurationParameter>;
+  failedParameters?: Array<ErrorConfigurationParameter>;
 }) => {
   const clusterConfigurationBannerContent = (
-    parameters?: Array<ConfigurationParameter>,
+    parameters?: Array<
+      SuccessConfigurationParameter | ErrorConfigurationParameter
+    >,
   ) => {
     return (
       <ul className={listStyles}>

chat/suggestions/src/SuggestedActions/SuggestedActions.spec.tsx

@@ -586,4 +586,57 @@ describe('chat/suggestions', () => {
       });
     });
   });
+
+  /* eslint-disable jest/no-disabled-tests */
+  describe.skip('types behave as expected', () => {
+    test('SuggestedActions throws error when no required props are provided', () => {
+      // @ts-expect-error - missing required props
+      <SuggestedActions />;
+    });
+
+    test('SuggestedActions throws error when missing configurationParameters', () => {
+      // @ts-expect-error - missing configurationParameters
+      <SuggestedActions state={State.Unset} onClickApply={() => {}} />;
+    });
+
+    test('SuggestedActions throws error when missing onClickApply', () => {
+      // @ts-expect-error - missing onClickApply
+      <SuggestedActions
+        state={State.Unset}
+        configurationParameters={[{ key: 'test', value: 'test' }]}
+      />;
+    });
+
+    test('SuggestedActions throws error when missing state', () => {
+      // @ts-expect-error - missing state
+      <SuggestedActions
+        configurationParameters={[{ key: 'test', value: 'test' }]}
+        onClickApply={() => {}}
+      />;
+    });
+
+    test('SuggestedActions accepts configurationParameters with allowed state values', () => {
+      <SuggestedActions
+        state={State.Success}
+        configurationParameters={[
+          { key: 'unset', value: 'value' },
+          { key: 'explicit-unset', value: 'value', state: 'unset' },
+          { key: 'success', value: 'value', state: 'success' },
+          { key: 'error', value: 'value', state: 'error' },
+        ]}
+        onClickApply={() => {}}
+      />;
+    });
+
+    test('SuggestedActions does not accept configurationParameters with state "apply"', () => {
+      <SuggestedActions
+        state={State.Success}
+        configurationParameters={[
+          // @ts-expect-error - "apply" is not a valid state for configurationParameters
+          { key: 'apply', value: 'value', state: State.Apply },
+        ]}
+        onClickApply={() => {}}
+      />;
+    });
+  });
 });

chat/suggestions/src/SuggestedActions/SuggestedActions.types.ts

@@ -9,7 +9,7 @@ export interface SuggestedActionsProps
     DarkModeProps {
   /**
    * Configuration parameters with their individual state values.
-   * Each parameter includes a key, value, and state (unset/apply/success/error).
+   * Each parameter includes a key, value, and state (unset/success/error).
    */
   configurationParameters: ConfigurationParameters;
 

chat/suggestions/src/shared.types.ts

@@ -9,15 +9,30 @@ export const State = {
 } as const;
 export type State = (typeof State)[keyof typeof State];
 
-/**
- * A single configuration parameter with its key, value, and current state
- */
-export interface ConfigurationParameter {
+interface BaseConfigurationParameter {
   key: string;
   value: string;
-  state?: State; // Defaults to 'unset' if not specified
 }
 
+interface UnsetConfigurationParameter extends BaseConfigurationParameter {
+  state?: 'unset';
+}
+
+export interface SuccessConfigurationParameter
+  extends BaseConfigurationParameter {
+  state: 'success';
+}
+
+export interface ErrorConfigurationParameter
+  extends BaseConfigurationParameter {
+  state: 'error';
+}
+
+export type ConfigurationParameter =
+  | SuccessConfigurationParameter
+  | ErrorConfigurationParameter
+  | UnsetConfigurationParameter;
+
 /**
  * Array of configuration parameters, each with their own state.
  */