@react-md/core 1.0.0-next.8 → 1.0.0-next.9

package/src/form/useEditableCombobox.ts

@@ -0,0 +1,139 @@
+"use client";
+import { useRef } from "react";
+import { isTypeEvent } from "../movement/utils.js";
+import {
+  useCombobox,
+  type BaseComboboxOptions,
+  type ComboboxImplementation,
+} from "./useCombobox.js";
+import { isChangeableHTMLElement, triggerManualChangeEvent } from "./utils.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface EditableComboboxOptions<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+> extends BaseComboboxOptions<ComboboxEl, PopupEl> {}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface EditableComboboxImplementation<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+> extends ComboboxImplementation<ComboboxEl, PopupEl> {}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export function useEditableCombobox<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: EditableComboboxOptions<ComboboxEl, PopupEl> = {}
+): EditableComboboxImplementation<ComboboxEl, PopupEl> {
+  const focusFirst = useRef(false);
+  const { getMenuProps, ...combobox } = useCombobox({
+    ...options,
+    loopable: true,
+    searchable: false,
+    isNegativeOneAllowed: true,
+    getEnterDefaultFocusedIndex(options) {
+      const { focusLast, focusables, currentFocusIndex } = options;
+      if (focusFirst.current) {
+        focusFirst.current = false;
+        return 0;
+      }
+
+      if (focusLast) {
+        return focusables.length - 1;
+      }
+
+      return currentFocusIndex;
+    },
+    extendKeyDown(movementData) {
+      const {
+        event,
+        show,
+        hide,
+        visible,
+        currentFocusIndex,
+        setActiveDescendantId,
+      } = movementData;
+
+      const resetFocus = (): void => {
+        currentFocusIndex.current = -1;
+        setActiveDescendantId("");
+      };
+
+      switch (event.key) {
+        case "Escape":
+          if (!visible && isChangeableHTMLElement(event.currentTarget)) {
+            event.preventDefault();
+            event.stopPropagation();
+            triggerManualChangeEvent(event.currentTarget, "");
+          }
+          break;
+        case "Home":
+        case "End":
+          // do not attempt to jump to the start or end of the listbox so
+          // natural text editing occurs
+          event.stopPropagation();
+          if (visible) {
+            resetFocus();
+          }
+          break;
+        case "ArrowLeft":
+        case "ArrowRight":
+          if (visible) {
+            resetFocus();
+          }
+          break;
+        case "ArrowUp":
+          // Note: The non-altKey version is handled in the `useCombobox` hook
+          //
+          // if the popup is available and the altKey was pressed, return focus
+          // to the combobox without closing. If the focus was already on the
+          // combobox, hide the popup
+          if (visible && event.altKey) {
+            event.preventDefault();
+            event.stopPropagation();
+
+            if (currentFocusIndex.current !== -1) {
+              resetFocus();
+            } else {
+              hide();
+            }
+          }
+          break;
+        case "ArrowDown":
+          // if the popup is available, display the popup keep the focus on the
+          // combobox if the altKey was pressed. Otherwise, move focus into the
+          // listbox
+          if (!visible) {
+            event.preventDefault();
+            event.stopPropagation();
+            focusFirst.current = !event.altKey;
+            show();
+          }
+          break;
+        default:
+          if (isTypeEvent(event)) {
+            show();
+            resetFocus();
+          }
+      }
+    },
+  });
+
+  return {
+    ...combobox,
+    getMenuProps(props) {
+      return {
+        preventOverlap: true,
+        ...getMenuProps(props),
+      };
+    },
+  };
+}

package/src/form/useFormReset.ts

@@ -0,0 +1,48 @@
+"use client";
+import { useEffect, type RefObject } from "react";
+import {
+  triggerManualChangeEvent,
+  type ChangeableHTMLElement,
+} from "./utils.js";
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export interface FormResetOptions {
+  form?: string;
+  elementRef: RefObject<ChangeableHTMLElement>;
+  defaultValue: string;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export function useFormReset(options: FormResetOptions): void {
+  const { form, elementRef, defaultValue } = options;
+
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) {
+      return;
+    }
+
+    const formElement =
+      (form && document.getElementById(form)) ||
+      element.closest<HTMLFormElement>("form") ||
+      null;
+    if (!formElement) {
+      return;
+    }
+
+    const handleReset = (): void => {
+      triggerManualChangeEvent(element, defaultValue);
+    };
+
+    formElement.addEventListener("reset", handleReset);
+    return () => {
+      formElement.removeEventListener("reset", handleReset);
+    };
+  }, [defaultValue, elementRef, form]);
+}

package/src/form/useListboxProvider.ts

@@ -17,12 +17,14 @@ export interface ListboxContext {
    */
   currentValue: string | number | null;
 
+  selectedIconAfter: boolean;
   disableSelectedIcon: boolean;
 }
 
 const context = createContext<ListboxContext>({
   inputRef: { current: null },
   currentValue: null,
+  selectedIconAfter: false,
   disableSelectedIcon: false,
 });
 

package/src/form/useSelectCombobox.ts

@@ -0,0 +1,70 @@
+"use client";
+import {
+  useCombobox,
+  type BaseComboboxOptions,
+  type ComboboxImplementation,
+} from "./useCombobox.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface SelectComboboxOptions<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+> extends BaseComboboxOptions<ComboboxEl, PopupEl> {
+  value: string;
+  values: readonly string[];
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface SelectComboboxImplementation<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+> extends ComboboxImplementation<ComboboxEl, PopupEl> {}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export function useSelectCombobox<
+  ComboboxEl extends HTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: SelectComboboxOptions<ComboboxEl, PopupEl>
+): SelectComboboxImplementation<ComboboxEl, PopupEl> {
+  const { value, values, ...comboboxOptions } = options;
+
+  return useCombobox({
+    ...comboboxOptions,
+    searchable: true,
+    extendKeyDown(movementData) {
+      const { event, show, focusLast, visible } = movementData;
+      if (visible) {
+        return;
+      }
+
+      switch (event.key) {
+        case " ":
+        case "Home":
+        case "End":
+          event.preventDefault();
+          event.stopPropagation();
+          focusLast.current = event.key === "End";
+          show();
+          break;
+      }
+    },
+    getEnterDefaultFocusedIndex(options) {
+      const { focusLast } = options;
+      if (focusLast && !value) {
+        return values.length - 1;
+      }
+
+      return Math.max(
+        0,
+        values.findIndex((option) => option === value)
+      );
+    },
+  });
+}

package/src/form/utils.ts

@@ -54,10 +54,23 @@ export function tryToSubmitRelatedForm<E extends HTMLElement>(
  * @internal
  * @remarks \@since 6.0.0
  */
-export type ChangeableHTMLElement =
-  | HTMLInputElement
-  | HTMLTextAreaElement
-  | HTMLSelectElement;
+export type EditableHTMLElement = HTMLInputElement | HTMLTextAreaElement;
+
+/**
+ * @internal
+ * @remarks \@since 6.0.0
+ */
+export type ChangeableHTMLElement = EditableHTMLElement | HTMLSelectElement;
+
+/**
+ * @internal
+ * @remarks \@since 6.0.0
+ */
+export function isChangeableHTMLElement(
+  element: Element | null
+): element is ChangeableHTMLElement {
+  return !!element && "value" in element;
+}
 
 /**
  * This is used to trigger a change event for a form element.

package/src/index.ts

@@ -1,6 +1,7 @@
 export { nanoid } from "nanoid";
 export * from "./CoreProviders.js";
 export * from "./NoSsr.js";
+export * from "./RootHtml.js";
 export * from "./SsrProvider.js";
 export * from "./app-bar/AppBar.js";
 export * from "./app-bar/AppBarTitle.js";
@@ -69,6 +70,7 @@ export * from "./form/Option.js";
 export * from "./form/Password.js";
 export * from "./form/Radio.js";
 export * from "./form/Select.js";
+export * from "./form/SelectedOption.js";
 export * from "./form/Slider.js";
 export * from "./form/SliderContainer.js";
 export * from "./form/SliderMark.js";
@@ -95,12 +97,18 @@ export * from "./form/switchStyles.js";
 export * from "./form/textFieldStyles.js";
 export * from "./form/types.js";
 export * from "./form/useCheckboxGroup.js";
+export * from "./form/useCombobox.js";
+export * from "./form/useEditableCombobox.js";
 export * from "./form/useFileUpload.js";
+export * from "./form/useFormReset.js";
+export * from "./form/useListboxProvider.js";
 export * from "./form/useNumberField.js";
 export * from "./form/useRadioGroup.js";
 export * from "./form/useRangeSlider.js";
+export * from "./form/useSelectCombobox.js";
 export * from "./form/useSlider.js";
 export * from "./form/useTextField.js";
+export * from "./form/utils.js";
 export * from "./form/validation.js";
 export * from "./hoverMode/useHoverMode.js";
 export * from "./hoverMode/useHoverModeProvider.js";
@@ -188,6 +196,11 @@ export * from "./responsive-item/styles.js";
 export * from "./scroll/ScrollLock.js";
 export * from "./scroll/getScrollbarWidth.js";
 export * from "./scroll/useScrollLock.js";
+export * from "./searching/caseInsensitive.js";
+export * from "./searching/fuzzy.js";
+export * from "./searching/toSearchQuery.js";
+export * from "./searching/types.js";
+export * from "./searching/utils.js";
 export * from "./segmented-button/SegmentedButton.js";
 export * from "./segmented-button/SegmentedButtonContainer.js";
 export * from "./segmented-button/segmentedButtonContainerStyles.js";
@@ -253,6 +266,7 @@ export * from "./theme/utils.js";
 export * from "./tooltip/Tooltip.js";
 export * from "./tooltip/TooltipHoverModeProvider.js";
 export * from "./tooltip/constants.js";
+export * from "./tooltip/tooltipStyles.js";
 export * from "./tooltip/useTooltip.js";
 export * from "./transition/CSSTransition.js";
 export * from "./transition/Collapse.js";
@@ -314,7 +328,6 @@ export * from "./utils/RenderRecursively.js";
 export * from "./utils/alphaNumericSort.js";
 export * from "./utils/applyRef.js";
 export * from "./utils/bem.js";
-export * from "./utils/filters.js";
 export * from "./utils/getClientPosition.js";
 export * from "./utils/getMiddleOfRange.js";
 export * from "./utils/getPercentage.js";

package/src/menu/Menu.tsx

@@ -26,6 +26,7 @@ import {
 } from "../transition/useScaleTransition.js";
 import { type LabelRequiredForA11y, type PropsWithRef } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
+import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
 import {
   MenuConfigurationProvider,
   useMenuConfiguration,
@@ -449,7 +450,7 @@ export const Menu = forwardRef<HTMLDivElement, LabelRequiredForA11y<MenuProps>>(
       },
     });
 
-    const { ref, style, callbacks } = useFixedPositioning({
+    const { ref, style, callbacks, updateStyle } = useFixedPositioning({
       ...transitionOptions,
       onEnter,
       style: isSheet ? propStyle : menuStyle,
@@ -539,6 +540,13 @@ export const Menu = forwardRef<HTMLDivElement, LabelRequiredForA11y<MenuProps>>(
         window.removeEventListener("click", callback);
       };
     }, [disableHoverMode, role, visible]);
+    useIsomorphicLayoutEffect(() => {
+      if (!visible) {
+        return;
+      }
+
+      updateStyle();
+    }, [updateStyle, children, visible]);
 
     return (
       <MenuConfigurationProvider

package/src/menu/__tests__/__snapshots__/useContextMenu.tsx.snap

@@ -0,0 +1,54 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`useContextMenu should work as expected 1`] = `
+<div
+  aria-label="Context Menu"
+  class="rmd-menu rmd-menu--elevated"
+  id="menu-:r0:"
+  role="menu"
+  style="left: 300px; top: 600px; position: fixed; transform-origin: 0 0;"
+  tabindex="-1"
+>
+  <ul
+    class="rmd-list"
+    role="none"
+  >
+    <li
+      class="rmd-list-item rmd-list-item--normal rmd-interaction-surface rmd-menu-item"
+      id="menuitem-:r1:"
+      role="menuitem"
+      tabindex="-1"
+    >
+      <span
+        class="rmd-list-item__text"
+      >
+        Cut
+      </span>
+    </li>
+    <li
+      class="rmd-list-item rmd-list-item--normal rmd-interaction-surface rmd-menu-item"
+      id="menuitem-:r2:"
+      role="menuitem"
+      tabindex="-1"
+    >
+      <span
+        class="rmd-list-item__text"
+      >
+        Copy
+      </span>
+    </li>
+    <li
+      class="rmd-list-item rmd-list-item--normal rmd-interaction-surface rmd-menu-item"
+      id="menuitem-:r3:"
+      role="menuitem"
+      tabindex="-1"
+    >
+      <span
+        class="rmd-list-item__text"
+      >
+        Paste
+      </span>
+    </li>
+  </ul>
+</div>
+`;

package/src/menu/__tests__/useContextMenu.tsx

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "@jest/globals";
+import { type ReactElement } from "react";
+import { fireEvent, rmdRender, screen } from "../../test-utils/index.js";
+import { Menu } from "../Menu.js";
+import { MenuItem } from "../MenuItem.js";
+import { useContextMenu } from "../useContextMenu.js";
+
+function Test(): ReactElement {
+  const { menuProps, onContextMenu } = useContextMenu();
+  return (
+    <>
+      <label>
+        Example
+        <textarea onContextMenu={onContextMenu} />
+      </label>
+      <Menu {...menuProps}>
+        <MenuItem>Cut</MenuItem>
+        <MenuItem>Copy</MenuItem>
+        <MenuItem>Paste</MenuItem>
+      </Menu>
+    </>
+  );
+}
+
+describe("useContextMenu", () => {
+  // I should add some real tests later...
+  it("should work as expected", async () => {
+    rmdRender(<Test />);
+    const textarea = screen.getByRole("textbox", { name: "Example" });
+
+    fireEvent.contextMenu(textarea, {
+      clientX: 300,
+      clientY: 600,
+    });
+
+    const menu = await screen.findByRole("menu", { name: "Context Menu" });
+    // mostly verifying that the useFixedPositioning allows for the initialX and
+    // initialY set by clientX and clientY
+    expect(menu).toMatchSnapshot();
+  });
+});

package/src/menu/useContextMenu.ts

@@ -71,15 +71,15 @@ const noop = (): void => {
  *   const { menuProps, onContextMenu } = useContextMenu();
  *
  *   return (
- *     <div onContextMenu={onContextMenu}>
- *       <textarea />
+ *     <>
+ *       <textarea onContextMenu={onContextMenu} />
  *       <Menu {...menuProps}>
  *         <MenuItem>Cut</MenuItem>
  *         <MenuItem>Copy</MenuItem>
  *         <MenuItem>Paste</MenuItem>
  *         <MenuItem>Undo</MenuItem>
  *       </Menu>
- *     </div>
+ *     </>
  *   );
  * }
  * ```

package/src/movement/types.ts

@@ -30,6 +30,27 @@ import type {
  */
 export type TabIndexBehavior = "roving" | "virtual";
 
+/**
+ * This should be used for specific widgets that should not include all
+ * focusable elements and instead only specific elements.
+ *
+ * @example
+ * ```ts
+ * const getExpansionPanelsOnly: GetFocusableElements = (container) =>
+ *   [...container.querySelectorAll(".rmd-expansion-panel__button")];
+ *
+ * const getTreeItemsOnly: GetFocusableElements = (container) =>
+ *   [...container.querySelectorAll("[role='treeitem']")];
+ * ```
+ *
+ * @defaultValue `getFocusableElements`
+ * @see the default `getFocusableElements` function.
+ */
+export type GetFocusableElements = (
+  container: HTMLElement,
+  programmatic: boolean
+) => readonly HTMLElement[];
+
 /**
  * @remarks \@since 5.0.0
  */
@@ -154,7 +175,15 @@ export type GetDefaultFocusedIndex = (options: FocusableIndexOptions) => number;
  * @remarks \@since 6.0.0
  * @internal
  */
-export interface FocusChangeEvent {
+export type ExtendKeyDown<E extends HTMLElement> = (
+  movementData: KeyboardMovementExtensionData<E>
+) => void;
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export interface KeyboardMovementFocusChangeEvent {
   index: number;
   element: HTMLElement;
 }
@@ -163,8 +192,8 @@ export interface FocusChangeEvent {
  * @remarks \@since 6.0.0
  * @internal
  */
-export type KeyboardMovementFocusChangeEvent = (
-  event: FocusChangeEvent
+export type KeyboardMovementFocusChangeEventHandler = (
+  event: KeyboardMovementFocusChangeEvent
 ) => void;
 
 /**
@@ -193,15 +222,18 @@ export interface KeyboardMovementProviderOptions<E extends HTMLElement>
   onFocus?(event: FocusEvent<E>): void;
   onKeyDown?(event: KeyboardEvent<E>): void;
 
+  /** @defaultValue `false` */
+  disabled?: boolean;
+
   /**
    * This is used to implement custom keyboard movement for the `keydown` event.
    */
-  extendKeyDown?(movementData: KeyboardMovementExtensionData<E>): void;
+  extendKeyDown?: ExtendKeyDown<E>;
 
   /**
    * Triggered whenever the focus changes.
    */
-  onFocusChange?: KeyboardMovementFocusChangeEvent;
+  onFocusChange?: KeyboardMovementFocusChangeEventHandler;
 
   /**
    * From what I've understood so far, programmatically focusable elements
@@ -212,32 +244,24 @@ export interface KeyboardMovementProviderOptions<E extends HTMLElement>
    */
   programmatic?: boolean;
 
-  /**
-   * This should be used for specific widgets that should not include all
-   * focusable elements and instead only specific elements.
-   *
-   * @example
-   * ```ts
-   * const getExpansionPanelsOnly = (container: HTMLElement): readonly HTMLElement[] =>
-   *   container.querySelectorAll(".rmd-expansion-panel__button");
-   *
-   * const getTreeItemsOnly = (container: HTMLElement): readonly HTMLElement[] =>
-   *   container.querySelectorAll("[role='treeitem']");
-   * ```
-   *
-   * @defaultValue `getFocusableElements`
-   * @see the default `getFocusableElements` function.
-   */
-  getFocusableElements?(
-    container: HTMLElement,
-    programmatic: boolean
-  ): readonly HTMLElement[];
+  /** @see {@link GetFocusableElements} */
+  getFocusableElements?: GetFocusableElements;
 
   /**
    * This can be used to set the initial focus index whenever the container
    * element is first focused or the focus index is `-1` on other focus events.
    */
   getDefaultFocusedIndex?: GetDefaultFocusedIndex;
+
+  /**
+   * This was added to support editable combobox behavior. As the user types or
+   * uses native input keyboard behavior, the focus index should be reset to
+   * `-1` so that the next "ArrowDown" event focuses the first option again
+   * instead of the last selected one.
+   *
+   * @defaultValue `false`
+   */
+  isNegativeOneAllowed?: boolean;
 }
 
 /**
@@ -274,5 +298,6 @@ export interface KeyboardMovementProviderImplementation<E extends HTMLElement> {
   movementProps: Readonly<KeyboardMovementProps<E>>;
   movementContext: Readonly<KeyboardMovementContext>;
   currentFocusIndex: NonNullMutableRef<number>;
+  activeDescendantId: string;
   setActiveDescendantId: UseStateSetter<string>;
 }