rfc: added useClearButton proposal

rfcs/2023-use-clear-button.md

@@ -0,0 +1,165 @@
+<!-- Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. -->
+
+- Start Date: 2023-06-10
+- RFC PR: (leave this empty, to be filled in later)
+- Authors: Jakob Guddas
+
+# `useClearButton`
+
+## Summary
+
+Creating a new `useClearButton` hook.
+
+## Motivation
+
+The goal is to make it easier for people to build accessible input fields,
+
+I just see way too many WCAG breaking clear buttons.
+
+<!-- Why are we doing this? What use cases does it support? What is the expected
+outcome? -->
+
+## Detailed Design
+
+Just like `useToggleButton` this would also extend `useButton`.
+
+It would also be great to expose this as `clearButtonProps` from `useTextField`, `useCombobox`, etc.
+
+```diff
+  import type { AriaTextFieldProps } from "react-aria";
+  import { useTextField } from "react-aria";
+
+  function TextField(props: AriaTextFieldProps) {
+    let { label } = props;
+    let ref = React.useRef(null);
+    let {
+      labelProps,
+      inputProps,
+      descriptionProps,
++     clearButtonProps,
+      errorMessageProps,
+    } = useTextField(props, ref);
+
+    return (
+      <div style={{ display: "flex", flexDirection: "column", width: 200 }}>
+        <label {...labelProps}>{label}</label>
+        <input {...inputProps} ref={ref} />
++       <button {...clearButtonProps} />
+        {props.description && (
+          <div {...descriptionProps} style={{ fontSize: 12 }}>
+            {props.description}
+          </div>
+        )}
+        {props.errorMessage && (
+          <div {...errorMessageProps} style={{ color: "red", fontSize: 12 }}>
+            {props.errorMessage}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  <TextField label="Email" />;
+```
+
+### Supported features
+
+- Localized `aria-label`
+- Excluded from tab order `tabindex: -1`
+- Clicking the clear button moves focus to input
+- Reachable by screen reader
+- Escape key clears input as well as space/enter (when focused)
+
+<!--
+   This is the bulk of the RFC.
+
+   Explain the design with enough detail that someone familiar with React-Spectrum
+   can implement it by reading this document. Please get into specifics
+   of your approach, corner cases, and examples of how the change will be
+   used. Be sure to define any new terms in this section.
+-->
+
+## Documentation
+
+<!--
+    How will this RFC be documented? Does it need a formal announcement to explain
+		the motivation?
+-->
+
+## Drawbacks
+
+<!--
+    Why should we *not* do this? Consider why adding this into React-Spectrum
+    might not benefit the project or the community. Attempt to think
+    about any opposing viewpoints that reviewers might bring up.
+
+    Any change has potential downsides, including increased maintenance
+    burden, incompatibility with other tools, breaking existing user
+    experience, etc. Try to identify as many potential problems with
+    implementing this RFC as possible.
+-->
+
+## Backwards Compatibility Analysis
+
+<!--
+    How does this change affect existing React-Spectrum users? Will any behavior
+    change for them? If so, how are you going to minimize the disruption
+    to existing users?
+-->
+
+## Alternatives
+
+<!--
+    What other designs did you consider? Why did you decide against those?
+
+    This section should also include prior art, such as whether similar
+    projects have already implemented a similar feature.
+-->
+
+## Open Questions
+
+<!--
+    This section is optional, but is suggested for a first draft.
+
+    What parts of this proposal are you unclear about? What do you
+    need to know before you can finalize this RFC?
+
+    List the questions that you'd like reviewers to focus on. When
+    you've received the answers and updated the design to reflect them,
+    you can remove this section.
+-->
+
+## Help Needed
+
+<!--
+    This section is optional.
+
+    Are you able to implement this RFC on your own? If not, what kind
+    of help would you need from the team?
+-->
+
+## Frequently Asked Questions
+
+<!--
+    This section is optional but suggested.
+
+    Try to anticipate points of clarification that might be needed by
+    the people reviewing this RFC. Include those questions and answers
+    in this section.
+-->
+
+## Related Discussions
+
+<!--
+    This section is optional but suggested.
+
+    If there is an issue, pull request, or other URL that provides useful
+    context for this proposal, please include those links here.
+-->