@react-md/core 1.0.0-next.0 → 1.0.0-next.10

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>;
 }

package/src/movement/useKeyboardMovementProvider.ts

@@ -198,6 +198,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     onFocus = noop,
     onKeyDown = noop,
     loopable = false,
+    disabled,
     searchable = false,
     horizontal = false,
     includeDisabled = false,
@@ -211,6 +212,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     jumpToLastKeys: propJumpToLastKeys,
     getFocusableElements = defaultGetFocusableElements,
     getDefaultFocusedIndex = returnNegative1,
+    isNegativeOneAllowed = false,
   } = options;
 
   const isRTL = useDir().dir === "rtl";
@@ -273,21 +275,27 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     }, []);
   }
 
+  let tabIndex: number | undefined;
+  if (tabIndexBehavior) {
+    tabIndex =
+      disabled || (tabIndexBehavior === "roving" && activeDescendantId)
+        ? -1
+        : 0;
+  }
+
   return {
     movementProps: {
       "aria-activedescendant":
         tabIndexBehavior === "virtual" ? activeDescendantId : undefined,
-      tabIndex:
-        tabIndexBehavior === "roving"
-          ? activeDescendantId
-            ? -1
-            : 0
-          : undefined,
+      tabIndex,
 
       // Note: This used to be on the `onFocus` event, but this causes issues in
       // Chromium browsers for drag and drop behavior
       onClick(event) {
         onClick(event);
+        if (disabled) {
+          return;
+        }
 
         // This makes it so you can click an element with a mouse and then
         // keyboard navigate from that element instead of the last keyboard focus
@@ -353,7 +361,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
         // This allows my custom `getDefaultFocusedIndex` implementations to
         // have a nice fallback without having to re-implement the "focus
         // first" behavior
-        if (defaultFocusIndex === -1) {
+        if (!isNegativeOneAllowed && defaultFocusIndex === -1) {
           if (tabIndexBehavior === "virtual") {
             // virtual keyboard navigation **must** always focus at least one element
             defaultFocusIndex = getVirtualFocusDefaultIndex({
@@ -392,6 +400,10 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
       },
       onKeyDown(event) {
         onKeyDown(event);
+        if (disabled) {
+          return;
+        }
+
         const { currentTarget } = event;
 
         const setFocusIndex = (
@@ -439,7 +451,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
         // TODO: Figure this part out. This is currently required for the tree
         // movement when the asterisk key is pressed. There might be other cases
         // as well.
-        if (currentFocusIndex.current === -1) {
+        if (!isNegativeOneAllowed && currentFocusIndex.current === -1) {
           currentFocusIndex.current = recalculateFocusIndex({
             focusables: getFocusableElements(currentTarget, programmatic),
             includeDisabled,
@@ -529,6 +541,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     },
     movementContext,
     currentFocusIndex,
+    activeDescendantId,
     setActiveDescendantId,
   };
 }

package/src/movement/utils.ts

@@ -1,6 +1,6 @@
-import type { KeyboardEvent } from "react";
+import { type KeyboardEvent } from "react";
 import { loop } from "../utils/loop.js";
-import type { FocusableIndexOptions, TabIndexBehavior } from "./types.js";
+import { type FocusableIndexOptions, type TabIndexBehavior } from "./types.js";
 
 /**
  * @remarks \@since 6.0.0
@@ -260,3 +260,13 @@ export function isSearchableEvent(event: KeyboardEvent): boolean {
     !metaKey
   );
 }
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export function isTypeEvent(event: KeyboardEvent): boolean {
+  return (
+    isSearchableEvent(event) || ["Backspace", "Delete", " "].includes(event.key)
+  );
+}

package/src/overlay/__tests__/Overlay.tsx

@@ -1,4 +1,4 @@
-import { describe, expect, it, jest } from "@jest/globals";
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 import { createRef, type ReactElement } from "react";
 import {
   fireEvent,
@@ -10,6 +10,7 @@ import {
 
 import { SsrProvider } from "../../SsrProvider.js";
 import { Button } from "../../button/Button.js";
+import { TRANSITION_CONFIG } from "../../transition/config.js";
 import { useToggle } from "../../useToggle.js";
 import { DISPLAY_NONE_CLASS } from "../../utils/isElementVisible.js";
 import { Overlay, type OverlayProps } from "../Overlay.js";
@@ -30,6 +31,10 @@ function Test({ defaultVisible = false }: TestProps): ReactElement {
 }
 
 describe("Overlay", () => {
+  beforeEach(() => {
+    TRANSITION_CONFIG.disabled = false;
+  });
+
   it("should apply the correct styling, HTMLAttributes, and allow a ref", () => {
     const ref = createRef<HTMLSpanElement>();
     const props = {
@@ -56,25 +61,22 @@ describe("Overlay", () => {
   });
 
   it("should support rendering inline if disablePortal prop is true", () => {
-    const { container, getByTestId } = render(
+    const { container } = render(
       <Overlay data-testid="overlay" visible disablePortal />
     );
 
-    const overlay = getByTestId("overlay");
+    const overlay = screen.getByTestId("overlay");
     expect(container.firstElementChild).toBe(overlay);
     expect(container).toMatchSnapshot();
   });
 
   it("should support rendering inline if it was visible by default and rendered through ssr", async () => {
-    const { container, getByRole, getByTestId } = render(
-      <Test defaultVisible />,
-      {
-        wrapper: ({ children }) => <SsrProvider ssr>{children}</SsrProvider>,
-      }
-    );
+    const { container } = render(<Test defaultVisible />, {
+      wrapper: ({ children }) => <SsrProvider ssr>{children}</SsrProvider>,
+    });
 
-    const button = getByRole("button", { name: "Toggle" });
-    const overlay = getByTestId("overlay");
+    const button = screen.getByRole("button", { name: "Toggle" });
+    const overlay = screen.getByTestId("overlay");
     expect(button.nextElementSibling).toBe(overlay);
     expect(container).toMatchSnapshot();
 
@@ -85,7 +87,9 @@ describe("Overlay", () => {
 
     fireEvent.click(button);
     await waitFor(() => {
-      expect(() => getByTestId("overlay")).not.toThrow();
+      expect(() => screen.getByTestId("overlay")).not.toThrow();
+    });
+    await waitFor(() => {
       expect(() => within(container).getByTestId("overlay")).toThrow();
     });
   });
@@ -98,7 +102,7 @@ describe("Overlay", () => {
     const onExiting = jest.fn();
     const onExited = jest.fn();
 
-    const props: Partial<OverlayProps> & { "data-testid": string } = {
+    const props: Partial<OverlayProps> = {
       "data-testid": "overlay",
       onEnter,
       onEntering,
@@ -109,11 +113,9 @@ describe("Overlay", () => {
       temporary: false,
     };
 
-    const { getByTestId, rerender } = render(
-      <Overlay {...props} visible={false} />
-    );
+    const { rerender } = render(<Overlay {...props} visible={false} />);
 
-    const overlay = getByTestId("overlay");
+    const overlay = screen.getByTestId("overlay");
     expect(overlay).toHaveClass(DISPLAY_NONE_CLASS);
     expect(overlay).toMatchSnapshot();
 
@@ -126,25 +128,25 @@ describe("Overlay", () => {
 
     rerender(<Overlay {...props} visible />);
     await waitFor(() => {
-      expect(onEnter).toHaveBeenCalledTimes(1);
-      expect(onEntering).toHaveBeenCalledTimes(1);
       expect(onEntered).toHaveBeenCalledTimes(1);
-      expect(onExit).not.toHaveBeenCalled();
-      expect(onExiting).not.toHaveBeenCalled();
-      expect(onExited).not.toHaveBeenCalled();
     });
+    expect(onEnter).toHaveBeenCalledTimes(1);
+    expect(onEntering).toHaveBeenCalledTimes(1);
+    expect(onExit).not.toHaveBeenCalled();
+    expect(onExiting).not.toHaveBeenCalled();
+    expect(onExited).not.toHaveBeenCalled();
     expect(overlay).not.toHaveClass(DISPLAY_NONE_CLASS);
     expect(overlay).toMatchSnapshot();
 
     rerender(<Overlay {...props} visible={false} />);
     await waitFor(() => {
-      expect(onEnter).toHaveBeenCalledTimes(1);
-      expect(onEntering).toHaveBeenCalledTimes(1);
-      expect(onEntered).toHaveBeenCalledTimes(1);
-      expect(onExit).toHaveBeenCalledTimes(1);
-      expect(onExiting).toHaveBeenCalledTimes(1);
       expect(onExited).toHaveBeenCalledTimes(1);
     });
+    expect(onEnter).toHaveBeenCalledTimes(1);
+    expect(onEntering).toHaveBeenCalledTimes(1);
+    expect(onEntered).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExiting).toHaveBeenCalledTimes(1);
     expect(overlay).toHaveClass(DISPLAY_NONE_CLASS);
     expect(overlay).toMatchSnapshot();
   });
@@ -168,20 +170,20 @@ describe("Overlay", () => {
       onExited,
     } as const;
 
-    const { getByTestId, rerender } = render(<Overlay {...props} />);
-    expect(() => getByTestId("overlay")).toThrow();
+    const { rerender } = render(<Overlay {...props} />);
+    expect(() => screen.getByTestId("overlay")).toThrow();
 
     rerender(<Overlay {...props} visible />);
     await waitFor(() => {
-      expect(onEnter).not.toHaveBeenCalled();
-      expect(onEntering).not.toHaveBeenCalled();
       expect(onEntered).toHaveBeenCalledTimes(1);
-      expect(onExit).not.toHaveBeenCalled();
-      expect(onExiting).not.toHaveBeenCalled();
-      expect(onExited).not.toHaveBeenCalled();
     });
+    expect(onEnter).not.toHaveBeenCalled();
+    expect(onEntering).not.toHaveBeenCalled();
+    expect(onExit).not.toHaveBeenCalled();
+    expect(onExiting).not.toHaveBeenCalled();
+    expect(onExited).not.toHaveBeenCalled();
 
-    const overlay = getByTestId("overlay");
+    const overlay = screen.getByTestId("overlay");
     expect(overlay).toMatchSnapshot();
   });
 

package/src/overlay/_overlay.scss

@@ -9,68 +9,65 @@ $z-index: utils.$temporary-element-z-index !default;
 $transition-duration: transition.$linear-duration !default;
 $transition-timing-function: transition.$linear-timing-function !default;
 
-$var-lookup: (
-  background-color: (
-    var: --rmd-overlay-background-color,
-    value: $background-color,
-  ),
-  z-index: (
-    var: --rmd-overlay-z-index,
-    value: $z-index,
-  ),
-);
+$variables: (background-color, z-index);
 
 @function get-var($name, $fallback: null) {
-  $found: utils.validate($var-lookup, $name, "overlay var");
-  $var: map.get($found, var);
-  $value: if($fallback, $fallback, map.get($found, value));
-
-  @if $value {
-    @return var(#{$var}, #{$value});
+  $var: utils.get-var-name($variables, $name, "overlay");
+  @if $fallback {
+    @return var(#{$var}, #{$fallback});
   }
 
   @return var(#{$var});
 }
 
 @mixin set-var($name, $value) {
-  $var: map.get(utils.validate($var-lookup, $name, "overlay var"), var);
-
-  #{$var}: #{$value};
+  @if $value {
+    #{utils.get-var-name($variables, $name, "overlay")}: #{$value};
+  }
 }
 
 @mixin use-var($property, $name: $property, $fallback: null) {
   #{$property}: get-var($name, $fallback);
 }
 
-@mixin styles {
+@mixin variables {
+  @if not $disable-everything {
+    @include set-var(background-color, $background-color);
+    @include set-var(z-index, $z-index);
+  }
+}
+
+@mixin styles($disable-layer: false) {
   @if not $disable-everything {
-    .rmd-overlay {
-      @include use-var(background-color);
-      @include use-var(z-index);
+    @include utils.optional-layer(overlay, $disable-layer) {
+      .rmd-overlay {
+        @include use-var(background-color);
+        @include use-var(z-index);
 
-      border-radius: inherit;
-      box-shadow: inherit;
-      inset: 0;
-      opacity: 0;
-      pointer-events: none;
-      position: fixed;
-      transition: opacity $transition-duration $transition-timing-function;
+        border-radius: inherit;
+        box-shadow: inherit;
+        inset: 0;
+        opacity: 0;
+        pointer-events: none;
+        position: fixed;
+        transition: opacity $transition-duration $transition-timing-function;
 
-      &--active {
-        opacity: 1;
-      }
+        &--active {
+          opacity: 1;
+        }
 
-      &--clickable {
-        cursor: pointer;
-      }
+        &--clickable {
+          cursor: pointer;
+        }
 
-      &--visible {
-        overflow: hidden;
-        pointer-events: auto;
-      }
+        &--visible {
+          overflow: hidden;
+          pointer-events: auto;
+        }
 
-      &--absolute {
-        position: absolute;
+        &--absolute {
+          position: absolute;
+        }
       }
     }
   }

package/src/portal/PortalContainerProvider.tsx

@@ -6,6 +6,7 @@ import {
   useState,
   type ReactElement,
   type ReactNode,
+  type RefObject,
 } from "react";
 
 /**
@@ -40,7 +41,7 @@ export interface PortalContainerProviderProps {
    * `<div id="rmd-portal-container"></div>` will be added as the last child to
    * the `document.body` and be used as the container element.
    */
-  container?: PortalContainer;
+  container?: PortalContainer | RefObject<PortalContainer>;
   children: ReactNode;
 }
 
@@ -61,6 +62,11 @@ export function PortalContainerProvider(
   const { container, children } = props;
   const [value, setValue] = useState<PortalContainer>(portalContainer);
   useEffect(() => {
+    if (container && "current" in container) {
+      setValue(container.current);
+      return;
+    }
+
     if (typeof container !== "undefined") {
       return;
     }
@@ -82,5 +88,7 @@ export function PortalContainerProvider(
     };
   }, [container]);
 
-  return <Provider value={container ?? value}>{children}</Provider>;
+  const containerValue =
+    (container && "current" in container) || !container ? value : container;
+  return <Provider value={containerValue}>{children}</Provider>;
 }

package/src/portal/__tests__/PortalContainerProvider.node.tsx

@@ -9,6 +9,7 @@ describe("PortalContainerProvider", () => {
   it("should not render portals server side", () => {
     expect(typeof document).toBe("undefined");
 
+    // eslint-disable-next-line testing-library/render-result-naming-convention
     const result = renderToString(
       <PortalContainerProvider>
         <Portal>

package/src/portal/__tests__/PortalContainerProvider.tsx

@@ -1,15 +1,16 @@
 import { describe, expect, it } from "@jest/globals";
-import { render } from "../../test-utils/index.js";
+import { render, screen } from "../../test-utils/index.js";
 
+import { useRef, type ReactElement } from "react";
+import { Portal } from "../Portal.js";
 import {
-  PortalContainerProvider,
   PORTAL_CONTAINER_ID,
+  PortalContainerProvider,
 } from "../PortalContainerProvider.js";
-import { Portal } from "../Portal.js";
 
 describe("PortalContainerProvider", () => {
   it("should portal all child portals to a div that was created as the last child in the document.body", () => {
-    const { container, getByTestId, unmount } = render(
+    const { container, unmount } = render(
       <PortalContainerProvider>
         <Portal>
           <div data-testid="div-1" />
@@ -21,8 +22,8 @@ describe("PortalContainerProvider", () => {
     );
 
     const portalRoot = document.getElementById(PORTAL_CONTAINER_ID);
-    const div1 = getByTestId("div-1");
-    const div2 = getByTestId("div-2");
+    const div1 = screen.getByTestId("div-1");
+    const div2 = screen.getByTestId("div-2");
 
     expect(document.body).toContainElement(portalRoot);
     expect(portalRoot).toContainElement(div1);
@@ -40,7 +41,7 @@ describe("PortalContainerProvider", () => {
   it("should allow for a custom container element", () => {
     const container = document.createElement("div");
     document.body.appendChild(container);
-    const { getByTestId } = render(
+    render(
       <PortalContainerProvider container={container}>
         <Portal>
           <div data-testid="div-1" />
@@ -51,11 +52,33 @@ describe("PortalContainerProvider", () => {
       </PortalContainerProvider>
     );
 
-    const div1 = getByTestId("div-1");
-    const div2 = getByTestId("div-2");
+    const div1 = screen.getByTestId("div-1");
+    const div2 = screen.getByTestId("div-2");
     expect(document.getElementById(PORTAL_CONTAINER_ID)).toBe(null);
     expect(container).toContainElement(div1);
     expect(container).toContainElement(div2);
     document.body.removeChild(container);
   });
+
+  it("should allow for a ref container", () => {
+    function Test(): ReactElement {
+      const portalContainer = useRef<HTMLDivElement>(null);
+      return (
+        <PortalContainerProvider container={portalContainer}>
+          <div data-testid="container" ref={portalContainer} />
+          <Portal>
+            <div data-testid="portal">
+              This will always be rendered in the portalContainer
+            </div>
+          </Portal>
+        </PortalContainerProvider>
+      );
+    }
+
+    render(<Test />);
+    const container = screen.getByTestId("container");
+    const portal = screen.getByTestId("portal");
+    expect(document.getElementById(PORTAL_CONTAINER_ID)).toBe(null);
+    expect(container).toContainElement(portal);
+  });
 });

package/src/positioning/__tests__/__snapshots__/useFixedPositioning.tsx.snap

@@ -85,35 +85,3 @@ exports[`useFixedPositioning should default to fixing itself with the BELOW_CENT
   </button>
 </div>
 `;
-
-exports[`useFixedPositioning should update the style correctly based on the initialX and initialY so that it can be used for context menus 1`] = `
-<div>
-  <button
-    type="button"
-  >
-    Toggle
-  </button>
-  <div
-    data-testid="element"
-    style="position: fixed; left: 16px; top: 0px;"
-  >
-    Some content.
-  </div>
-</div>
-`;
-
-exports[`useFixedPositioning should update the style correctly based on the initialX and initialY so that it can be used for context menus 2`] = `
-<div>
-  <button
-    type="button"
-  >
-    Toggle
-  </button>
-  <div
-    data-testid="element"
-    style="position: fixed; left: 30px; top: 40px;"
-  >
-    Some content.
-  </div>
-</div>
-`;