@khanacademy/wonder-blocks-dropdown 8.0.2 → 9.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Khan Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/components/dropdown-core.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StyleType } from "@khanacademy/wonder-blocks-core";
 import type { DropdownItem } from "../util/types";
-type Labels = {
+type LabelsValues = {
     /**
      * Label for describing the dismiss icon on the search filter.
      */
@@ -116,7 +116,7 @@ type ExportProps = Readonly<{
     /**
      * The object containing the custom labels used inside this component.
      */
-    labels?: Labels;
+    labels?: LabelsValues;
     /**
      * Used to determine if we can automatically select an item using the keyboard.
      */

package/dist/components/dropdown-opener.d.ts

@@ -28,7 +28,7 @@ type Props = Partial<Omit<AriaProps, "aria-disabled">> & {
      */
     testId?: string;
     /**
-     * Text for the opener that can be passed to the child as an argument.
+     * Content for the opener that can be passed to the child as an argument.
      */
     text: OptionLabel;
     /**
@@ -43,6 +43,10 @@ type Props = Partial<Omit<AriaProps, "aria-disabled">> & {
      * If the dropdown has an error.
      */
     error?: boolean;
+    /**
+     * The role of the opener.
+     */
+    role: "combobox" | "button";
 };
 type DefaultProps = {
     disabled: Props["disabled"];

package/dist/components/multi-select.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import { type AriaProps, type StyleType } from "@khanacademy/wonder-blocks-core";
 import OptionItem from "./option-item";
 import type { OpenerProps } from "../util/types";
-export type Labels = {
+export type LabelsValues = {
     /**
      * Label for describing the dismiss icon on the search filter.
      */
@@ -12,7 +12,7 @@ export type Labels = {
      */
     filter: string;
     /**
-     * Label for when the filter returns no results.
+     * Value for when the filter returns no results.
      */
     noResults: string;
     /**
@@ -24,15 +24,15 @@ export type Labels = {
      */
     selectNoneLabel: string;
     /**
-     * Label for the opening component when there are no items selected.
+     * Value for the opening component when there are no items selected.
      */
     noneSelected: string;
     /**
-     * Label for the opening component when there are some items selected.
+     * Value for the opening component when there are some items selected.
      */
     someSelected: (numOptions: number) => string;
     /**
-     * Label for the opening component when all the items have been selected.
+     * Value for the opening component when all the items have been selected.
      */
     allSelected: string;
 };
@@ -60,8 +60,8 @@ type DefaultProps = Readonly<{
      */
     shortcuts?: boolean;
     /**
-     * When false, the SelectOpener can show a Node as a label. When true, the
-     * SelectOpener will use a string as a label. If using custom OptionItems, a
+     * When false, the SelectOpener can show a Node as a value. When true, the
+     * SelectOpener will use a string as a value. If using custom OptionItems, a
      * plain text label can be provided with the `labelAsText` prop.
      * Defaults to true.
      */
@@ -94,9 +94,9 @@ type Props = AriaProps & DefaultProps & Readonly<{
      */
     isFilterable?: boolean;
     /**
-     * The object containing the custom labels used inside this component.
+     * The object containing the custom labels and placeholder values used inside this component.
      */
-    labels?: Labels;
+    labels?: LabelsValues;
     /**
      * Callback for when the selection changes. Parameter is an updated array of
      * the values that are now selected.
@@ -177,6 +177,9 @@ type Props = AriaProps & DefaultProps & Readonly<{
  * multiple options to be selected. Clients are responsible for keeping track
  * of the selected items.
  *
+ * Clients are also responsible for labeling the select using `LabeledField`, or
+ * an `aria-label` attribute or `aria-labelledby` on the select.
+ *
  * The multi select stays open until closed by the user. The onChange callback
  * happens every time there is a change in the selection of the items.
  *
@@ -185,7 +188,7 @@ type Props = AriaProps & DefaultProps & Readonly<{
  * ```jsx
  * import {OptionItem, MultiSelect} from "@khanacademy/wonder-blocks-dropdown";
  *
- * <MultiSelect onChange={setSelectedValues} selectedValues={selectedValues}>
+ * <MultiSelect aria-label="Fruits" onChange={setSelectedValues} selectedValues={selectedValues}>
  *  <OptionItem value="pear">Pear</OptionItem>
  *  <OptionItem value="mango">Mango</OptionItem>
  * </MultiSelect>

package/dist/components/select-opener.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import type { AriaProps } from "@khanacademy/wonder-blocks-core";
+import { type AriaProps } from "@khanacademy/wonder-blocks-core";
 import { OptionLabel } from "../util/types";
 type SelectOpenerProps = AriaProps & {
     /**
@@ -25,6 +25,10 @@ type SelectOpenerProps = AriaProps & {
      * of this component. A placeholder has more faded text colors and styles.
      */
     isPlaceholder: boolean;
+    /**
+     * A label to expose on the opener, in the absence of an associated label element or `aria-labelledby`.
+     */
+    ariaLabel?: string;
     /**
      * Callback for when the SelectOpener is pressed.
      */

package/dist/components/single-select.d.ts

@@ -2,9 +2,9 @@ import * as React from "react";
 import { type AriaProps, type StyleType } from "@khanacademy/wonder-blocks-core";
 import OptionItem from "./option-item";
 import type { OpenerProps } from "../util/types";
-export type SingleSelectLabels = {
+export type SingleSelectLabelsValues = {
     /**
-     * Label for describing the dismiss icon on the search filter.
+     * Label to create an accessible name for the dismiss icon on the search filter.
      */
     clearSearch: string;
     /**
@@ -12,11 +12,11 @@ export type SingleSelectLabels = {
      */
     filter: string;
     /**
-     * Label for when the filter returns no results.
+     * Value for when the filter returns no results.
      */
     noResults: string;
     /**
-     * Label for the opening component when there are some items selected.
+     * Value for the opening component when there are some items selected.
      */
     someResults: (numOptions: number) => string;
 };
@@ -54,12 +54,12 @@ type DefaultProps = Readonly<{
      */
     error?: boolean;
     /**
-     * The object containing the custom labels used inside this component.
+     * The object containing the custom labels and placeholder values used inside this component.
      */
-    labels?: SingleSelectLabels;
+    labels?: SingleSelectLabelsValues;
     /**
-     * When false, the SelectOpener can show a Node as a label. When true, the
-     * SelectOpener will use a string as a label. If using custom OptionItems, a
+     * When false, the SelectOpener can show a Node as a value. When true, the
+     * SelectOpener will use a string as a value. If using custom OptionItems, a
      * plain text label can be provided with the `labelAsText` prop.
      * Defaults to true.
      */
@@ -91,7 +91,8 @@ type Props = AriaProps & DefaultProps & Readonly<{
      */
     id?: string;
     /**
-     * Placeholder for the opening component when there are no items selected.
+     * Placeholder value for the opening component when there are no items selected.
+     * Note: a label is still necessary to describe the purpose of the select.
      */
     placeholder: string;
     /**
@@ -172,6 +173,9 @@ type Props = AriaProps & DefaultProps & Readonly<{
  * The single select allows the selection of one item. Clients are responsible
  * for keeping track of the selected item in the select.
  *
+ * Clients are also responsible for labeling the select using `LabeledField`, an
+ * `aria-label` attribute, or `aria-labelledby`.
+ *
  * The single select dropdown closes after the selection of an item. If the same
  * item is selected, there is no callback.
  *
@@ -188,7 +192,7 @@ type Props = AriaProps & DefaultProps & Readonly<{
  *
  * const [selectedValue, setSelectedValue] = React.useState("");
  *
- * <SingleSelect placeholder="Choose a fruit" onChange={setSelectedValue} selectedValue={selectedValue}>
+ * <SingleSelect aria-label="Your Favorite Fruits" placeholder="Choose a fruit" onChange={setSelectedValue} selectedValue={selectedValue}>
  *     <OptionItem label="Pear" value="pear" />
  *     <OptionItem label="Mango" value="mango" />
  * </SingleSelect>
@@ -203,6 +207,7 @@ type Props = AriaProps & DefaultProps & Readonly<{
  * const fruitArray = ["Apple", "Banana", "Orange", "Mango", "Pear"];
  *
  * <SingleSelect
+ *     aria-label="Your Favorite Fruits"
  *     placeholder="Choose a fruit"
  *     onChange={setSelectedValue}
  *     selectedValue={selectedValue}