docs(FileUpload): add API decisions

[snitin315]

Pretty Markdown Doc

This PR addresses the decisions made for the FileUpload component API.

• API Specification: Detailed the structure, functionality, and visual representation of the FileUpload component API.
• Examples: Provided illustrative examples showcasing various use cases, including controlled and uncontrolled behaviors, single and multiple file selections.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 306c303

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 306c303:

Sandbox	Source
razorpay/blade: basic	Configuration

[github-actions]

✅ PR title follows Conventional Commits specification.

[chaitanyadeorukhkar]

What callback would the user get when an upload is cancelled midway?

[snitin315]

As per the current API, onRemove will be triggered when CloseIcon or TrashIcon is clicked. But users may want to use different logic so we should introduce a newonCancel prop. Otherwise they would need to rely on file.status which may not be ideal.

[chaitanyadeorukhkar]

onRemove theek hai na?

So upload can get cancelled 2 ways

1. User cancels it - we call onRemove because user can cancel it only by clicking the X button
2. Internet/Server Failure - what will we call here?

[snitin315]

@chaitanyadeorukhkar In case of server failure, the consumers will need to set file.status to error. We can cancel/remove via trashicon/closeicon button only. We don't have control over the submit/upload logic so consumers can control their server failures.

Screen.Recording.2024-02-23.at.4.24.42.PM.mov

[snitin315]

onRemove theek hai na?

So we trigger onRemove when either CloseIcon Or TrashIcon is clicked, right?

[snitin315]

try {
  // fetch api call
} catch (err) {
 // file.status = "error"
// file.errorText = error.message
}

After this the file is displayed in error state:

Now clicking the close icon triggers onCancel. Also trigger when clicking the close icon when uploading files:

@saurabhdaware

[saurabhdaware]

no I mean is it us who call API internally in our component? or do consumers call it?

[snitin315]

no I mean is it us who call API internally in our component? or do consumers call it?

@saurabhdaware Consumers have control of the submit logic, check examples I've added in this doc for more info

[saurabhdaware]

so clicking on close icon always calls onCancel right? should we call it onCloseButtonClick, onDismiss in that case similar to our other components?

Because to me, cancel implies that uploading got cancelled but in case where we show error and show close icon, we're not exactly cancelling the upload request no? upload request just failed the validation and the callback was called AFTER the consumer dismissed the error

[snitin315]

Yeah, onDismiss is more suitable.