@razorpay/blade 7.2.2 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @razorpay/blade
 
+## 8.0.0
+
+### Major Changes
+
+- 9917a5cd: feat(Dropdown): Controlled Dropdown and Button Trigger
+
+  - Adds API to seamlessly build controlled dropdown
+  - Add DropdownButton component to trigger dropdown using Button
+  - Removes `isDefaultSelected` from `ActionListItem` _(see migration guide below)_
+
+  > **Warning**
+  >
+  > **Breaking change** for consumers who -
+  >
+  > - Use `isDefaultSelected` on `ActionListItem` component
+  > - Use `onChange` on `SelectInput` (under some scenarios. Check migration guide below)
+  >
+  > Rest of the consumers can safely upgrade without any migration
+
+  ### Migration Guide
+
+  #### `isDefaultSelected` Migration
+
+  We have removed `isDefaultSelected` from `<ActionListItem />` component. [Check out API decision](https://github.com/razorpay/blade/blob/master/packages/blade/src/components/Dropdown/_decisions/controlled-dropdown.md) for reasoning
+
+  If you were using it as a workaround for controlled selection,
+
+  - We now have a first class controlled selection support with `value` and `onChange` prop on `SelectInput`.
+
+    Checkout CodeSandbox Example for new API - https://codesandbox.io/s/blade-controlled-select-vxg30b
+
+  If you were using `isDefaultSelected` for default selections, you can now use `defaultValue` on SelectInput
+
+  - Remove `isDefaultSelected` and use `defaultValue` on SelectInput. You can pass array of values to `defaultValue` in case of multiselect
+    ```diff
+    <Dropdown>
+      <SelectInput
+        label="Select City"
+    +   defaultValue="mumbai"
+      />
+      <DropdownOverlay>
+        <ActionListItem
+          title="Mumbai"
+          value="mumbai"
+    -     isDefaultSelected
+         />
+        <ActionListItem title="Bangalore" value="bangalore" />
+      </DropdownOverlay>
+    </Dropdown>
+    ```
+
+  #### `onChange` on SelectInput Migration
+
+  As a part of [bug fix](https://github.com/razorpay/blade/issues/1102), `onChange` will now **NOT** be called on initial render
+  like it previously did. This will only require migration if you were earlier relying on `onChange` to set initial value.
+
+  If you were relying on `onChange` to set initial value, you can now move those values to your `useState`'s initial value.
+
+  ```tsx
+  const Example = (): JSX.Element => {
+    const [cities, setCities] = React.useState();
+    return (
+      <>
+        <Dropdown>
+          <SelectInput label="Cities" onChange={({values}) => setCities(values) } />
+          <DropdownOverlay>
+            <ActionListItem title="Mumbai" value="mumbai" />
+            <ActionListItem title="Pune" value="pune" />
+          </DropdownOverlay>
+        </Dropdown>
+        <Text>{cities}</Text>
+        {/*
+          In earlier versions, value of `cities` would've been `['']`
+          (because onChange would've been called initially to set array with empty string value)
+
+          Now it will output undefined (anything you pass in your useState) as the onChange wouldn't be called on initial render
+        */}
+      <>
+    )
+  }
+  ```
+
 ## 7.2.2
 
 ### Patch Changes

package/build/components/index.d.ts

@@ -1437,6 +1437,10 @@ declare type ActionListItemProps = {
      * Link to open when item is clicked.
      */
     href?: string;
+    /**
+     * HTML target of the link
+     */
+    target?: string;
     /**
      * Item that goes on left-side of item.
      *
@@ -1451,12 +1455,14 @@ declare type ActionListItemProps = {
      * Valid elements - `<ActionListItemText />`, `<ActionListItemIcon />`
      */
     trailing?: React__default.ReactNode;
-    /**
-     * If item is selected on page load
-     */
-    isDefaultSelected?: boolean;
     isDisabled?: boolean;
     intent?: Extract<Feedback, 'negative'>;
+    /**
+     * Can be used in combination of `onClick` to highlight item as selected in Button Triggers.
+     *
+     * When trigger is SelectInput, Use `value` prop on SelectInput instead to make dropdown controlled.
+     */
+    isSelected?: boolean;
     /**
      * Internally passed from ActionList. No need to pass it explicitly
      *
@@ -2896,9 +2902,10 @@ declare const CheckboxGroup: ({ children, label, helpText, isDisabled, necessity
 
 declare type DropdownProps = {
     selectionType?: 'single' | 'multiple';
+    onDismiss?: () => void;
     children: React__default.ReactNode[];
 } & StyledPropsBlade;
-declare const Dropdown: ({ children, selectionType, ...styledProps }: DropdownProps) => JSX.Element;
+declare const Dropdown: ({ children, selectionType, onDismiss, ...styledProps }: DropdownProps) => JSX.Element;
 
 declare type DropdownOverlayProps = {
     children: React__default.ReactNode;
@@ -3792,7 +3799,7 @@ declare type TextInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | '
      */
     type?: Type;
 } & StyledPropsBlade;
-declare const TextInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "prefix" | "autoCapitalize" | "isDisabled" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "suffix" | "validationState" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & {
+declare const TextInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "prefix" | "autoCapitalize" | "isDisabled" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "suffix" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & {
     /**
      * Decides whether to render a clear icon button
      */
@@ -3878,7 +3885,7 @@ declare type PasswordInputExtraProps = {
     autoCompleteSuggestionType?: Extract<BaseInputProps['autoCompleteSuggestionType'], 'none' | 'password' | 'newPassword'>;
 };
 declare type PasswordInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'maxCharacters' | 'validationState' | 'errorText' | 'successText' | 'helpText' | 'isDisabled' | 'defaultValue' | 'placeholder' | 'isRequired' | 'value' | 'onChange' | 'onBlur' | 'onSubmit' | 'onFocus' | 'name' | 'autoFocus' | 'keyboardReturnKeyType' | 'autoCompleteSuggestionType' | 'testID'> & PasswordInputExtraProps & StyledPropsBlade;
-declare const PasswordInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "isDisabled" | "labelPosition" | "helpText" | "errorText" | "successText" | "validationState" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & PasswordInputExtraProps & Partial<Omit<MakeObjectResponsive<{
+declare const PasswordInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "isDisabled" | "labelPosition" | "validationState" | "helpText" | "errorText" | "successText" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & PasswordInputExtraProps & Partial<Omit<MakeObjectResponsive<{
     margin: SpacingValueType | ArrayOfMaxLength4<SpacingValueType>;
     marginX: SpacingValueType;
     marginY: SpacingValueType;
@@ -3912,7 +3919,7 @@ declare type TextAreaProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'n
      */
     onClearButtonClick?: () => void;
 } & StyledPropsBlade;
-declare const TextArea: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "numberOfLines" | "isDisabled" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "validationState" | "isRequired" | "maxCharacters"> & {
+declare const TextArea: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "value" | "onFocus" | "onBlur" | "onChange" | "onSubmit" | "autoFocus" | "defaultValue" | "numberOfLines" | "isDisabled" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "maxCharacters"> & {
     /**
      * Decides whether to render a clear icon button
      */
@@ -4005,6 +4012,16 @@ declare const OTPInput: ({ autoFocus, errorText, helpText, isDisabled, keyboardR
 
 declare type SelectInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'necessityIndicator' | 'validationState' | 'helpText' | 'errorText' | 'successText' | 'name' | 'isDisabled' | 'isRequired' | 'prefix' | 'suffix' | 'autoFocus' | 'onClick' | 'onFocus' | 'onBlur' | 'placeholder' | 'testID'> & {
     icon?: IconComponent$1;
+    /**
+     * Controlled value of the Select. Use it in combination of `onChange`.
+     *
+     * Check out [Controlled Dropdown Documentation](https://blade.razorpay.com/?path=/story/components-dropdown-with-select--controlled-dropdown&globals=measureEnabled:false) for example.
+     */
+    value?: string | string[];
+    /**
+     * Used to set the default value of SelectInput when it's uncontrolled. Use `value` instead for controlled SelectInput
+     */
+    defaultValue?: string | string[];
     onChange?: ({ name, values }: {
         name?: string;
         values: string[];
@@ -4037,8 +4054,18 @@ declare type SelectInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' |
  *
  * Checkout {@link https://blade.razorpay.com/?path=/docs/components-dropdown-with-select--with-single-select SelectInput Documentation}.
  */
-declare const SelectInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "onFocus" | "onBlur" | "onClick" | "autoFocus" | "prefix" | "isDisabled" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "suffix" | "validationState" | "isRequired"> & {
+declare const SelectInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "name" | "testID" | "placeholder" | "label" | "onFocus" | "onBlur" | "onClick" | "autoFocus" | "prefix" | "isDisabled" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "suffix"> & {
     icon?: IconComponent$1 | undefined;
+    /**
+     * Controlled value of the Select. Use it in combination of `onChange`.
+     *
+     * Check out [Controlled Dropdown Documentation](https://blade.razorpay.com/?path=/story/components-dropdown-with-select--controlled-dropdown&globals=measureEnabled:false) for example.
+     */
+    value?: string | string[] | undefined;
+    /**
+     * Used to set the default value of SelectInput when it's uncontrolled. Use `value` instead for controlled SelectInput
+     */
+    defaultValue?: string | string[] | undefined;
     onChange?: (({ name, values }: {
         name?: string | undefined;
         values: string[];

package/build/components/index.native.d.ts

@@ -1437,6 +1437,10 @@ declare type ActionListItemProps = {
      * Link to open when item is clicked.
      */
     href?: string;
+    /**
+     * HTML target of the link
+     */
+    target?: string;
     /**
      * Item that goes on left-side of item.
      *
@@ -1451,12 +1455,14 @@ declare type ActionListItemProps = {
      * Valid elements - `<ActionListItemText />`, `<ActionListItemIcon />`
      */
     trailing?: React__default.ReactNode;
-    /**
-     * If item is selected on page load
-     */
-    isDefaultSelected?: boolean;
     isDisabled?: boolean;
     intent?: Extract<Feedback, 'negative'>;
+    /**
+     * Can be used in combination of `onClick` to highlight item as selected in Button Triggers.
+     *
+     * When trigger is SelectInput, Use `value` prop on SelectInput instead to make dropdown controlled.
+     */
+    isSelected?: boolean;
     /**
      * Internally passed from ActionList. No need to pass it explicitly
      *
@@ -2898,9 +2904,10 @@ declare const CheckboxGroup: ({ children, label, helpText, isDisabled, necessity
 
 declare type DropdownProps = {
     selectionType?: 'single' | 'multiple';
+    onDismiss?: () => void;
     children: React__default.ReactNode[];
 } & StyledPropsBlade;
-declare const Dropdown: ({ children, selectionType, ...styledProps }: DropdownProps) => JSX.Element;
+declare const Dropdown: ({ children, selectionType, onDismiss, ...styledProps }: DropdownProps) => JSX.Element;
 
 declare type DropdownOverlayProps = {
     children: React__default.ReactNode;
@@ -3795,7 +3802,7 @@ declare type TextInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | '
      */
     type?: Type;
 } & StyledPropsBlade;
-declare const TextInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "defaultValue" | "prefix" | "autoCapitalize" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "suffix" | "validationState" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & {
+declare const TextInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "defaultValue" | "prefix" | "autoCapitalize" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "suffix" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & {
     /**
      * Decides whether to render a clear icon button
      */
@@ -3881,7 +3888,7 @@ declare type PasswordInputExtraProps = {
     autoCompleteSuggestionType?: Extract<BaseInputProps['autoCompleteSuggestionType'], 'none' | 'password' | 'newPassword'>;
 };
 declare type PasswordInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'maxCharacters' | 'validationState' | 'errorText' | 'successText' | 'helpText' | 'isDisabled' | 'defaultValue' | 'placeholder' | 'isRequired' | 'value' | 'onChange' | 'onBlur' | 'onSubmit' | 'onFocus' | 'name' | 'autoFocus' | 'keyboardReturnKeyType' | 'autoCompleteSuggestionType' | 'testID'> & PasswordInputExtraProps & StyledPropsBlade;
-declare const PasswordInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "defaultValue" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "helpText" | "errorText" | "successText" | "validationState" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & PasswordInputExtraProps & Partial<Omit<MakeObjectResponsive<{
+declare const PasswordInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "defaultValue" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "validationState" | "helpText" | "errorText" | "successText" | "isRequired" | "maxCharacters" | "keyboardReturnKeyType" | "autoCompleteSuggestionType"> & PasswordInputExtraProps & Partial<Omit<MakeObjectResponsive<{
     margin: SpacingValueType | ArrayOfMaxLength4<SpacingValueType>;
     marginX: SpacingValueType;
     marginY: SpacingValueType;
@@ -3915,7 +3922,7 @@ declare type TextAreaProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'n
      */
     onClearButtonClick?: () => void;
 } & StyledPropsBlade;
-declare const TextArea: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "numberOfLines" | "defaultValue" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "validationState" | "isRequired" | "maxCharacters"> & {
+declare const TextArea: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "value" | "onBlur" | "onFocus" | "numberOfLines" | "defaultValue" | "onChange" | "onSubmit" | "isDisabled" | "autoFocus" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "maxCharacters"> & {
     /**
      * Decides whether to render a clear icon button
      */
@@ -4008,6 +4015,16 @@ declare const OTPInput: ({ autoFocus, errorText, helpText, isDisabled, keyboardR
 
 declare type SelectInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' | 'necessityIndicator' | 'validationState' | 'helpText' | 'errorText' | 'successText' | 'name' | 'isDisabled' | 'isRequired' | 'prefix' | 'suffix' | 'autoFocus' | 'onClick' | 'onFocus' | 'onBlur' | 'placeholder' | 'testID'> & {
     icon?: IconComponent$1;
+    /**
+     * Controlled value of the Select. Use it in combination of `onChange`.
+     *
+     * Check out [Controlled Dropdown Documentation](https://blade.razorpay.com/?path=/story/components-dropdown-with-select--controlled-dropdown&globals=measureEnabled:false) for example.
+     */
+    value?: string | string[];
+    /**
+     * Used to set the default value of SelectInput when it's uncontrolled. Use `value` instead for controlled SelectInput
+     */
+    defaultValue?: string | string[];
     onChange?: ({ name, values }: {
         name?: string;
         values: string[];
@@ -4040,8 +4057,18 @@ declare type SelectInputProps = Pick<BaseInputProps, 'label' | 'labelPosition' |
  *
  * Checkout {@link https://blade.razorpay.com/?path=/docs/components-dropdown-with-select--with-single-select SelectInput Documentation}.
  */
-declare const SelectInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "onBlur" | "onFocus" | "onClick" | "prefix" | "isDisabled" | "autoFocus" | "labelPosition" | "helpText" | "errorText" | "successText" | "necessityIndicator" | "suffix" | "validationState" | "isRequired"> & {
+declare const SelectInput: React__default.ForwardRefExoticComponent<Pick<BaseInputProps, "testID" | "name" | "placeholder" | "label" | "onBlur" | "onFocus" | "onClick" | "prefix" | "isDisabled" | "autoFocus" | "labelPosition" | "validationState" | "helpText" | "errorText" | "necessityIndicator" | "successText" | "isRequired" | "suffix"> & {
     icon?: IconComponent$1 | undefined;
+    /**
+     * Controlled value of the Select. Use it in combination of `onChange`.
+     *
+     * Check out [Controlled Dropdown Documentation](https://blade.razorpay.com/?path=/story/components-dropdown-with-select--controlled-dropdown&globals=measureEnabled:false) for example.
+     */
+    value?: string | string[] | undefined;
+    /**
+     * Used to set the default value of SelectInput when it's uncontrolled. Use `value` instead for controlled SelectInput
+     */
+    defaultValue?: string | string[] | undefined;
     onChange?: (({ name, values }: {
         name?: string | undefined;
         values: string[];