@khanacademy/wonder-blocks-dropdown 5.4.6 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @khanacademy/wonder-blocks-dropdown
 
+## 5.5.0
+
+### Minor Changes
+
+-   5fb863d0: Add multiple selection support to `Combobox`
+-   ea506e85: Add Combobox component with single selection support
+-   2ad690b3: Add a11y features to announce combobox changes to screen readers
+-   b89e828c: Add autocomplete support to Combobox
+
+### Patch Changes
+
+-   326954dd: Update borderColor to be more a11y friendly
+-   Updated dependencies [5fb863d0]
+    -   @khanacademy/wonder-blocks-pill@2.5.0
+    -   @khanacademy/wonder-blocks-search-field@2.2.25
+    -   @khanacademy/wonder-blocks-modal@5.1.11
+
 ## 5.4.6
 
 ### Patch Changes

package/dist/components/combobox-live-region.d.ts

@@ -0,0 +1,52 @@
+/// <reference types="react" />
+import { ComboboxLabels, MaybeValueOrValues, OptionItemComponent } from "../util/types";
+type Props = {
+    /**
+     * The index of the focused item in the listbox.
+     */
+    focusedIndex: number;
+    /**
+     * The index of the focused item in the multi-select combobox.
+     */
+    focusedMultiSelectIndex: number;
+    /**
+     * The labels associated with the live region.
+     */
+    labels?: Pick<ComboboxLabels, "closedState" | "liveRegionCurrentItem" | "liveRegionListboxTotal" | "liveRegionMultipleSelectionTotal" | "noItems" | "selected" | "unselected">;
+    /**
+     * Whether the listbox is open/expanded.
+     */
+    opened?: boolean;
+    /**
+     * The list of items in the listbox.
+     */
+    options: Array<OptionItemComponent>;
+    /**
+     * The value of the selected item(s).
+     */
+    selected: MaybeValueOrValues;
+    /**
+     * The label(s) of the selected item(s).
+     */
+    selectedLabels: Array<string>;
+    /**
+     * Whether the use can select more than one option item. Defaults to
+     * `single`.
+     */
+    selectionType?: "single" | "multiple";
+    /**
+     * The testId used for the live region.
+     */
+    testId?: string;
+};
+/**
+ * A component that announces focus changes to Screen Readers.
+ *
+ * This is useful as there are lots of issues with `role="combobox"` + Safari
+ * when the browser is not capable of announcing correctly the status of the
+ * currently focused option item.
+ *
+ * @see https://bugs.webkit.org/show_bug.cgi?id=167671
+ */
+export declare function ComboboxLiveRegion({ focusedIndex, focusedMultiSelectIndex, labels, selectedLabels, opened, options, selected, selectionType, testId, }: Props): JSX.Element;
+export {};

package/dist/components/combobox-multiple-selection.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+type Props = {
+    /**
+     * Whether the combobox is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * The index of the focused item in the pills group.
+     */
+    focusedMultiSelectIndex: number;
+    /**
+     * The unique identifier for the selected items.
+     */
+    id: string;
+    /**
+     * The list of labels for the selected items.
+     */
+    labels: Array<string>;
+    /**
+     * Function to remove a selected item.
+     */
+    onRemove: (value: string) => void;
+    /**
+     * Accessible label for the remove button.
+     */
+    removeSelectedLabel: (value: string) => string;
+    /**
+     * The list of selected items, where each item represents the value of the
+     * selected option.
+     */
+    selected: Array<string>;
+    /**
+     * The testId prefix used for the pills.
+     */
+    testId?: string;
+};
+/**
+ * Renders the selected items as pills that are horizontally stacked before
+ * the input element.
+ */
+export declare const MultipleSelection: React.NamedExoticComponent<Props>;
+export {};

package/dist/components/combobox.d.ts

@@ -0,0 +1,101 @@
+/// <reference types="react" />
+import { StyleType } from "@khanacademy/wonder-blocks-core";
+import { ComboboxLabels, MaybeValueOrValues, OptionItemComponent } from "../util/types";
+type Props = {
+    /**
+     * The list of items to display in the listbox.
+     */
+    children: Array<OptionItemComponent>;
+    /**
+     * Whether the use can select more than one option item. Defaults to
+     * `single`.
+     *
+     * If `multiple` is selected, `aria-multiselectable={true}` is set
+     * internally in the listbox element.
+     */
+    selectionType: "single" | "multiple";
+    /**
+     * The value of the currently selected items.
+     */
+    value: MaybeValueOrValues;
+    /**
+     * Callback for when the selection changes. The value passed as an argument
+     * is an updated array of the selected value(s).
+     */
+    onChange?: (value: MaybeValueOrValues) => void;
+    /**
+     * Whether the combobox is disabled.
+     *
+     * A disabled combobox does not support interaction, but it supports focus
+     * for a11y reasons. It internally maps to`aria-disabled`. Defaults to
+     * false.
+     */
+    disabled?: boolean;
+    /**
+     * The unique identifier of the combobox element.
+     */
+    id?: string;
+    /**
+     * The object containing the custom labels used inside this component.
+     *
+     * This is useful for internationalization. Defaults to English.
+     */
+    labels?: ComboboxLabels;
+    /**
+     * Whether to display the light version of this component.
+     *
+     * For use when the component is used on a dark background. Defaults to
+     * false.
+     */
+    light?: boolean;
+    /**
+     * TODO(WB-1678): Add async support to the listbox.
+     *
+     * Whether to display the loading state to let the user know that the
+     * results are being loaded asynchronously. Defaults to false.
+     */
+    loading?: boolean;
+    /**
+     * Can be used to programmatically control the opening of the listbox.
+     */
+    opened?: boolean;
+    /**
+     * In controlled mode, use this prop in case the parent needs to be notified
+     * when the listbox opens/closes.
+     */
+    onToggle?: (opened: boolean) => void;
+    /**
+     * Text that provides context for the user when there are no items selected.
+     */
+    placeholder?: string;
+    /**
+     * Custom styles to add to the combobox element (input).
+     */
+    style?: StyleType;
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string;
+    /**
+     * Indicates whether inputting text could trigger display of one or more
+     * predictions of the user’s intended value.
+     *
+     * It’s internally mapped to aria-autocomplete set in the input field
+     * (combobox).
+     */
+    autoComplete?: "none" | "list" | undefined;
+};
+/**
+ * A `Combobox` is an input widget that has an associated `listbox`. This
+ * listbox enables users to choose one or more values for the input from a
+ * collection of option items.
+ *
+ * The `listbox` is hidden by default, so its default state is collapsed. The
+ * conditions that trigger expanding the `listbox` are:
+ *
+ * - It is displayed when the `ArrowDown`, `ArrowUp` keys are pressed, or the
+ *   Open button (🔽) is pressed.
+ * - It is displayed when the combobox receives focus.
+ */
+export default function Combobox({ autoComplete, children, disabled, id, labels, onChange, onToggle, opened, placeholder, selectionType, testId, value, }: Props): JSX.Element;
+export {};