@react-md/core 1.0.0-next.20 → 1.0.0-next.21

package/src/typography/HighlightText.tsx

@@ -0,0 +1,201 @@
+import {
+  Children,
+  type ComponentType,
+  type ReactElement,
+  type ReactNode,
+  useMemo,
+} from "react";
+import { remove as removeAccents } from "remove-accents";
+
+import { HighlightTextMark } from "./HighlightTextMark.js";
+
+// https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions#Using_special_characters
+const SPECIAL_CHARACTERS_REGEXP = /[.*+?^${}()|[\]\\]/g;
+
+/**
+ * @since 6.0.0
+ */
+export interface HighlightTextMatch {
+  /**
+   * The cleaned query that has diacritics, leading whitespace, and trailing
+   * whitespace removed.
+   */
+  query: string;
+
+  /**
+   * The raw query string that was provided.
+   */
+  rawQuery: string;
+
+  /**
+   * The full untouched text content for the HighlightText component.
+   */
+  rawText: string;
+
+  /**
+   * The current index in the {@link rawText} that is being matched against.
+   */
+  index: number;
+
+  /**
+   * The last index the query has been matched.
+   */
+  lastIndex: number;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface HighlightTextComponentProps {
+  /** {@inheritDoc HighlightTextMatch} */
+  match: HighlightTextMatch;
+
+  /**
+   * The matched content.
+   */
+  children: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export type HighlightTextComponent = ComponentType<HighlightTextComponentProps>;
+
+/**
+ * @since 6.0.0
+ */
+export interface HighlightTextProps {
+  /**
+   * This prop can be used to provide a custom highlight behavior. It will be
+   * provided the {@link HighlightTextComponentProps}
+   *
+   * @defaultValue `HighlightTextMark`
+   */
+  highlight?: HighlightTextComponent;
+
+  /**
+   * The query text to highlight in the children. When this is an empty string
+   * or whitespace only, nothing will be highlighted.
+   */
+  query: string;
+
+  /**
+   * The content to highlight based on the query text where highlighting only
+   * works for text children. The component will attempt to find all child text
+   * using the `React.Children` API, but might be inconsistent.
+   */
+  children: ReactNode;
+
+  /**
+   * Set to `true` if only the first match should be highlighted instead of all
+   * occurrences.
+   *
+   * @defaultValue `false`
+   */
+  firstMatchOnly?: boolean;
+}
+
+/**
+ * The `HighlightText` component can be used to highlight text matching the
+ * provided query ignoring case.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { HighlightText } from "@react-md/core/typography/HighlightText";
+ * import { Typography } from "@react-md/core/typography/Typography";
+ * import { type ReactElement } from "react";
+ *
+ * export default function SimpleExample(): ReactElement {
+ *   return (
+ *     <Typography>
+ *       <HighlightText query="lorem ipsum">
+ *         Lorem ipsum dolor sit amet, consectetur adipiscing elit. In eget metus
+ *         ut mi mattis dapibus. Praesent interdum sapien ut posuere convallis.
+ *         Donec et tristique ex. Aliquam erat volutpat. Donec sit amet dui
+ *         egestas, tempus quam id, hendrerit risus. Nullam tincidunt quam ut dui
+ *         aliquet ultricies. Lorem ipsum dolor sit amet, consectetur adipiscing
+ *         elit. Sed rhoncus, purus vitae tincidunt placerat, quam diam lobortis
+ *         magna, et aliquam ante diam id nunc. Cras blandit leo eu nisi
+ *         elementum, nec gravida ligula pharetra. Etiam molestie luctus orci,
+ *         vel hendrerit lacus eleifend ut. Nullam placerat dolor ac mi congue,
+ *         non auctor metus consectetur. Ut pretium mollis vulputate.
+ *       </HighlightText>
+ *     </Typography>
+ *   );
+ * }
+ *
+ * ```
+ * @see {@link https://next.react-md.dev/components/highlight-text | HighlightText Demos}
+ * @since 6.0.0
+ */
+export function HighlightText(
+  props: Readonly<HighlightTextProps>
+): ReactElement {
+  const {
+    query,
+    children,
+    highlight: Highlight = HighlightTextMark,
+    firstMatchOnly,
+  } = props;
+
+  return (
+    <>
+      {useMemo<ReactNode>(
+        () =>
+          Children.map(children, (child) => {
+            if (!query || !child || typeof child !== "string") {
+              return child;
+            }
+
+            const cleanQuery = removeAccents(query).trim();
+            if (!cleanQuery) {
+              return <>{child}</>;
+            }
+
+            const parts: ReactNode[] = [];
+            const text = removeAccents(child).trim();
+            const regex = new RegExp(
+              "(" + cleanQuery.replace(SPECIAL_CHARACTERS_REGEXP, "\\$&") + ")",
+              "gi"
+            );
+
+            let match: RegExpExecArray | null;
+            let lastIndex = 0;
+            while ((match = regex.exec(text)) !== null) {
+              const { index } = match;
+              if (index > lastIndex) {
+                parts.push(child.slice(lastIndex, index));
+              }
+
+              ({ lastIndex } = regex);
+              parts.push(
+                <Highlight
+                  key={index}
+                  match={{
+                    index,
+                    lastIndex,
+                    query: cleanQuery,
+                    rawQuery: query,
+                    rawText: child,
+                  }}
+                >
+                  {child.slice(index, lastIndex)}
+                </Highlight>
+              );
+
+              if (firstMatchOnly) {
+                break;
+              }
+            }
+
+            if (lastIndex < child.length) {
+              parts.push(child.slice(lastIndex));
+            }
+
+            return parts;
+          }),
+        [Highlight, children, firstMatchOnly, query]
+      )}
+    </>
+  );
+}

package/src/typography/HighlightTextMark.tsx

@@ -0,0 +1,25 @@
+import { type ReactElement } from "react";
+
+import { type HighlightTextComponentProps } from "./HighlightText.js";
+import { Mark, type MarkProps } from "./Mark.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface HighlightTextMarkProps
+  extends HighlightTextComponentProps,
+    Omit<MarkProps, "children"> {}
+
+/**
+ * This is the default implementation for the `HighlightText` component that
+ * just omits the `match` prop from {@link HighlightTextComponentProps} and
+ * passes the rest to the {@link Mark}.
+ *
+ * @since 6.0.0
+ */
+export function HighlightTextMark(
+  props: Readonly<HighlightTextMarkProps>
+): ReactElement {
+  const { match: _match, ...remaining } = props;
+  return <Mark {...remaining} />;
+}

package/src/typography/Mark.tsx

@@ -0,0 +1,41 @@
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
+import { mark } from "./markStyles.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface MarkProps extends HTMLAttributes<HTMLElement> {
+  children: ReactNode;
+}
+
+/**
+ * The `Mark` component can be used in place of the `mark` HTMLElement with
+ * some default styles.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { Mark } from "@react-md/core/typography/Mark";
+ *
+ * export function Example() {
+ *   return (
+ *     <>
+ *       Some text <Mark>that has highlights</Mark> and some other text.
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/mark | Mark Demos}
+ * @since 6.0.0
+ */
+export const Mark = forwardRef<HTMLElement, MarkProps>(
+  function Mark(props, ref) {
+    const { children, className, ...remaining } = props;
+    return (
+      <mark {...remaining} ref={ref} className={mark({ className })}>
+        {children}
+      </mark>
+    );
+  }
+);

package/src/typography/SrOnly.tsx

@@ -33,7 +33,7 @@ export interface SrOnlyProps extends HTMLAttributes<TypographyHTMLElement> {
  *
  * @example Simple Example
  * ```tsx
- * import { SrOnly } from "@react-md/core";
+ * import { SrOnly } from "@react-md/core/typography/SrOnly";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -49,6 +49,8 @@ export interface SrOnlyProps extends HTMLAttributes<TypographyHTMLElement> {
  *   );
  * }
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/sr-only | SrOnly Demos}
  */
 export const SrOnly = forwardRef<TypographyHTMLElement, SrOnlyProps>(
   function SrOnly(props, ref) {

package/src/typography/TextContainer.tsx

@@ -5,6 +5,13 @@ import {
   textContainer,
 } from "./textContainerStyles.js";
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-line-length"?: string | number;
+    "--rmd-text-container-padding"?: string | number;
+  }
+}
+
 /**
  * @since 6.0.0 Removed the `size` option since there is no longer a
  * different line-length for mobile and desktop.
@@ -21,7 +28,8 @@ export interface TextContainerProps
  *
  * @example Simple Example
  * ```tsx
- * import { TextContainer, Typography } from "@react-md/core";
+ * import { TextContainer } from "@react-md/core/typography/TextContainer";
+ * import { Typography } from "@react-md/core/typography/Typography";
  *
  * function Example() {
  *   return (
@@ -39,6 +47,7 @@ export interface TextContainerProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/text-container | TextContainer Demos}
  * @see {@link textContainer} If you only want to apply this class to an
  * element.
  * @since 6.0.0 Removed the `size` option since there is no longer a

package/src/typography/Typography.tsx

@@ -103,7 +103,7 @@ export interface TypographyProps
  *
  * @example All Example
  * ```tsx
- * import { Typography } from "@react-md/core":
+ * import { Typography } from "@react-md/core/typography/Typography":
  *
  * export function Example() {
  *   return (
@@ -136,6 +136,7 @@ export interface TypographyProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/typography | Typography Demos}
  * @since 6.0.0 Removed the children render function behavior . Use the
  * `typography` class name utility instead.
  */

package/src/typography/WritingDirectionProvider.tsx

@@ -64,7 +64,7 @@ const { Provider } = context;
  *
  * @example Manually Changing the Writing Direction
  * ```tsx
- * import { useDir } from "@react-md/core";
+ * import { useDir } from "@react-md/core/typography/WritingDirectionProvider";
  *
  * function Example() {
  *   const { dir, toggleDir } = useDir();
@@ -139,25 +139,24 @@ export const DEFAULT_WRITING_DIRECTION = (): Dir => {
  *
  * @example Root Setup
  * ```tsx
+ * import { WritingDirectionProvider } from "@react-md/core/typography/WritingDirectionProvider";
  * import { createRoot } from "react-dom/client";
- * import { WritingDirection } from "@react-md/core";
  * import App from "./App.js":
  *
  * const container = document.getElementById("root");
  * const root = createRoot(container);
  *
  * root.render(
- *   <WritingDirection>
+ *   <WritingDirectionProvider>
  *     <App />
- *   </WritingDirection>
+ *   </WritingDirectionProvider>
  * );
  * ```
  *
  * @example Supporting RTL Languages
  * ```tsx
  * import { createRoot } from "react-dom/client";
- * import { WritingDirection } from "@react-md/core";
- * import type { Dir } from "@react-md/core";
+ * import { type Dir, WritingDirectionProvider } from "@react-md/core/typography/WritingDirectionProvider";
  * import App from "./App.js":
  *
  * const container = document.getElementById("root");
@@ -190,12 +189,13 @@ export const DEFAULT_WRITING_DIRECTION = (): Dir => {
  * }
  *
  * root.render(
- *   <WritingDirection defaultDir={defaultDir}>
+ *   <WritingDirectionProvider defaultDir={defaultDir}>
  *     <App />
- *   </WritingDirection>
+ *   </WritingDirectionProvider>
  * );
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/writing-direction-provider | WritingDirectionProvider Demos}
  * @since 6.0.0 Renamed from `Dir`
  */
 export function WritingDirectionProvider(

package/src/typography/markStyles.ts

@@ -0,0 +1,20 @@
+import { cnb } from "cnbuilder";
+
+import { bem } from "../utils/bem.js";
+
+const styles = bem("rmd-mark");
+
+/**
+ * @since 6.0.0
+ */
+export interface MarkClassNameOptions {
+  className?: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function mark(options: MarkClassNameOptions = {}): string {
+  const { className } = options;
+  return cnb(styles(), className);
+}

package/src/typography/textContainerStyles.ts

@@ -2,13 +2,6 @@ import { cnb } from "cnbuilder";
 
 import { bem } from "../utils/bem.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-line-length"?: string | number;
-    "--rmd-text-container-padding"?: string | number;
-  }
-}
-
 const styles = bem("rmd-text-container");
 
 /**
@@ -24,7 +17,8 @@ export interface TextContainerClassNameOptions {
 /**
  * @example Simple Example
  * ```tsx
- * import { textContainer, Typography } from "@react-md/core";
+ * import { textContainer } from "@react-md/core/typography/textContainerStyles";
+ * import { Typography } from "@react-md/core/typography/Typography";
  *
  * function Example() {
  *   return (

package/src/typography/typographyStyles.ts

@@ -56,7 +56,7 @@ export type NullableTypographyClassNameOptions = Omit<
  *
  * @example Simple Example
  * ```ts
- * import { typography } from "@react-md/core";
+ * import { typography } from "@react-md/core/typography/typographyStyles";
  *
  * function Example() {
  *   return (
@@ -81,7 +81,7 @@ export type NullableTypographyClassNameOptions = Omit<
  *
  * @example Applying Additional Styles
  * ```ts
- * import { typography } from "@react-md/core";
+ * import { typography } from "@react-md/core/typography/typographyStyles";
  *
  * function Example() {
  *   return (

package/src/useAsyncFunction.ts

@@ -2,7 +2,9 @@
 
 import { useCallback, useState } from "react";
 
-import type { NonNullRef, UseStateSetter } from "./types.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type AsyncButton } from "./button/AsyncButton.js";
+import { type NonNullRef, type UseStateSetter } from "./types.js";
 import { useUnmounted } from "./useUnmounted.js";
 
 /**
@@ -64,77 +66,19 @@ export interface AsyncFunctionHookImplementation {
  * `react-query`, `@reduxjs/toolkit/query`, `@apollo/client`, etc for API calls
  * which have a built-in pending state for mutations.
  *
- * @example Simple Example (Async Button)
- * ```tsx
- * import type { ButtonProps } from "@react-md/core";
- * import { box, Button, CircularProgress, useAsyncFunction } from "@react-md/core";
- * import { cnb } from "cnbuilder";
- * import type { MouseEvent, ReactElement } from "react";
- *
- * import styles from "./AsyncButton.module.scss";
- *
- * export interface AsyncButtonProps extends ButtonProps {
- *   onClick(event: MouseEvent<HTMLButtonElement>): Promise<void>;
- * }
- *
- * export function AsyncButton(props: AsyncButtonProps): ReactElement {
- *   const { onClick, children, theme, className, disabled, ...remaining } = props;
- *   const { handleAsync, pending } = useAsyncFunction({ disabled });
- *
- *   return (
- *     <Button
- *       {...remaining}
- *       aria-disabled={pending || undefined}
- *       disabled={disabled}
- *       className={cnb(pending && styles.loading, className)}
- *       theme={pending ? "disabled" : theme}
- *       onClick={handleAsync(onClick)}
- *     >
- *       {children}
- *       {pending && (
- *         <span
- *           className={box({
- *             align: "center",
- *             disablePadding: true,
- *             className: styles.overlay,
- *           })}
- *         >
- *           <CircularProgress />
- *         </span>
- *       )}
- *     </Button>
- *   );
- * }
- *
- * // `AsyncButton.module.scss`
- * // hide everything in the button except for the overlay containing the circular
- * // progress
- * .loading > *:not(.overlay) {
- *   opacity: 0;
- * }
- *
- * .overlay {
- *   border-radius: inherit;
- *   box-shadow: inherit;
- *   inset: 0;
- *   position: absolute;
- *   z-index: 1;
- * }
- * ```
+ * @see {@link AsyncButton}
  *
  * @example Confirmation Dialog with Overlay
  * ```tsx
- * import {
- *   Button,
- *   DialogHeader,
- *   DialogContent,
- *   DialogFooter,
- *   Form,
- *   useAsyncFunction,
- * } from "@react-md/core";
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Dialog } from "@react-md/core/dialog/Dialog";
+ * import { DialogContent } from "@react-md/core/dialog/DialogContent";
+ * import { DialogFooter } from "@react-md/core/dialog/DialogFooter";
+ * import { DialogHeader } from "@react-md/core/dialog/DialogHeader";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { useAsyncFunction } from "@react-md/core/useAsyncFunction";
  * import CloseIcon from "@react-md/material-icons/CloseIcon";
- * import type { ReactElement } from "react";
- * import { useId } from "react";
+ * import { type ReactElement, useId } from "react";
  *
  * interface ExampleProps {
  *   hide(); void;

package/src/useDebouncedFunction.ts

@@ -11,7 +11,9 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
  *
  * @example Debounced Search API Requests
  * ```tsx
- * import { TextField, useDebouncedFunction, useUnmounted } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useDebouncedFunction } from "@react-md/core/useDebouncedFunction";
+ * import { useUnmounted } from "@react-md/core/useUnmounted";
  * import { useState } from "react";
  * import type { ReactElement } from "react";
  *

package/src/useDropzone.ts

@@ -108,8 +108,9 @@ export interface DropzoneImplementation {
  *
  * @example Dragging Example
  * ```tsx
- * import { useDropzone, useFileUpload } from "@react-md/core"
- * import type { CSSProperties, ReactElement } from "react";
+ * import { useFileUpload } from "@react-md/core/files/useFileUpload";
+ * import { useDropzone } from "@react-md/core/useDropzone";
+ * import { type CSSProperties, type ReactElement } from "react";
  *
  * const draggingStyle: CSSProperties = {
  *   backgroundColor: "orange",

package/src/useThrottledFunction.ts

@@ -10,7 +10,9 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
  *
  * @example Throttling Search API Requests
  * ```tsx
- * import { TextField, useThrottledFunction, useUnmounted } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useThrottledFunction } from "@react-md/core/useThrottledFunction";
+ * import { useUnmounted } from "@react-md/core/useUnmounted";
  * import { useState } from "react";
  * import type { ReactElement } from "react";
  *

package/src/useUnmounted.ts

@@ -7,7 +7,7 @@ import type { NonNullRef } from "./types.js";
 /**
  * @example Simple Example
  * ```tsx
- * import { useUnmounted } from "@react-md/core";
+ * import { useUnmounted } from "@react-md/core/useUnmounted";
  * import { useEffect, useState } from "react";
  *
  * function Example(): ReactElement {

package/src/utils/RenderRecursively.tsx

@@ -244,6 +244,7 @@ export interface RenderRecursivelyProps<
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/render-recursively | RenderRecursively Demos}
  * @since 6.0.0
  */
 export function RenderRecursively<Item, Data>(

package/src/utils/applyRef.ts

@@ -7,7 +7,7 @@ import type { MutableRefObject, Ref } from "react";
  * @example Simple Example
  * ```tsx
  * import { HTMLAttributes, forwardRef } from "react";
- * import { applyRef } from "@react-md/core";
+ * import { applyRef } from "@react-md/core/utils/applyRef";
  *
  * export type ExampleProps = HTMLAttributes<HTMLDivElement>;
  *

package/src/window-splitter/WindowSplitter.tsx

@@ -5,6 +5,17 @@ import { windowSplitter } from "./styles.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { type useWindowSplitter } from "./useWindowSplitter.js";
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-window-splitter-top"?: number | string;
+    "--rmd-window-splitter-right"?: number | string;
+    "--rmd-window-splitter-bottom"?: number | string;
+    "--rmd-window-splitter-left"?: number | string;
+    "--rmd-window-splitter-opacity"?: number | string;
+    "--rmd-window-splitter-position"?: number | string;
+  }
+}
+
 /**
  * @since 6.0.0
  * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/}
@@ -81,6 +92,7 @@ export type WindowSplitterProps = LabelRequiredForA11y<BaseWindowSplitterProps>;
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/window-splitter | WindowSplitter Demos}
  * @since 6.0.0
  */
 export const WindowSplitter = forwardRef<

package/src/window-splitter/useWindowSplitter.ts

@@ -13,17 +13,6 @@ import {
 } from "../draggable/useDraggable.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-window-splitter-top"?: number | string;
-    "--rmd-window-splitter-right"?: number | string;
-    "--rmd-window-splitter-bottom"?: number | string;
-    "--rmd-window-splitter-left"?: number | string;
-    "--rmd-window-splitter-opacity"?: number | string;
-    "--rmd-window-splitter-position"?: number | string;
-  }
-}
-
 /**
  * @since 6.0.0
  */